rungate 0.8.1 → 0.8.3

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 (75) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/BashWriteGuard.hook.ts +19 -0
  9. package/hooks/DocHygiene.hook.ts +2 -1
  10. package/hooks/GateResultProtection.hook.ts +28 -7
  11. package/hooks/HookCurrency.hook.ts +48 -1
  12. package/hooks/VerifyPhaseLock.hook.ts +68 -11
  13. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  14. package/lib/ai-review-jury.ts +725 -0
  15. package/lib/ai-review-rounds.ts +1249 -0
  16. package/lib/ai-review-unmeasured.ts +361 -0
  17. package/lib/bash-file-read.ts +17 -3
  18. package/lib/bash-write-guard.ts +2165 -51
  19. package/lib/cli-commands.ts +252 -11
  20. package/lib/closing-reference-audit.ts +163 -0
  21. package/lib/conformity.ts +12 -0
  22. package/lib/create-sc.ts +45 -12
  23. package/lib/derived-spec.ts +206 -0
  24. package/lib/distribution-standing.ts +75 -4
  25. package/lib/failure-intake.ts +12 -4
  26. package/lib/file-claims.ts +335 -0
  27. package/lib/file-extensions.ts +81 -0
  28. package/lib/finding-arbiter.ts +1489 -0
  29. package/lib/finding-jury.ts +584 -0
  30. package/lib/finding-pr-routing.ts +333 -0
  31. package/lib/frontmatter.ts +16 -0
  32. package/lib/gate-check-audit.ts +259 -0
  33. package/lib/generators/agents-md.ts +29 -0
  34. package/lib/github.ts +160 -0
  35. package/lib/hook-tree-currency.ts +494 -0
  36. package/lib/interpreters.ts +64 -0
  37. package/lib/issue-closure-audit.ts +161 -14
  38. package/lib/issue-create-override.ts +122 -11
  39. package/lib/issue-filing-gate.ts +1602 -0
  40. package/lib/local-review-rounds.ts +523 -0
  41. package/lib/organize.ts +10 -0
  42. package/lib/project-state-shape.ts +56 -5
  43. package/lib/publish-window.ts +287 -0
  44. package/lib/repo-path.ts +94 -0
  45. package/lib/report-provenance.ts +65 -3
  46. package/lib/risk-tier.ts +302 -0
  47. package/lib/rounds-to-pass.ts +274 -0
  48. package/lib/rule-row-drift.ts +199 -0
  49. package/lib/sc-claim-forms.ts +33 -5
  50. package/lib/sc-guard.ts +11 -1
  51. package/lib/sc-id-cross-tree.ts +17 -2
  52. package/lib/sc-ids.ts +71 -6
  53. package/lib/sc-reservations.ts +158 -14
  54. package/lib/scaffold/ai-review-findings.ts +1157 -18
  55. package/lib/scaffold/ai-review-step.ts +4672 -85
  56. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  57. package/lib/scaffold/managed-workflow.ts +163 -4
  58. package/lib/scaffold/owned-files.ts +14 -0
  59. package/lib/scaffold/steps.ts +462 -108
  60. package/lib/scanner.ts +10 -3
  61. package/lib/scratch-roots.ts +93 -3
  62. package/lib/spec-updater.ts +16 -0
  63. package/lib/ticked-sc-symbols.ts +361 -0
  64. package/lib/validators/spec-validators.ts +28 -2
  65. package/lib/workflow-actions.ts +18 -0
  66. package/package.json +3 -1
  67. package/scripts/ai-review-findings.ts +41 -1
  68. package/scripts/arbitrate-finding.ts +542 -0
  69. package/scripts/audit-specs.ts +225 -23
  70. package/scripts/create-sc.ts +11 -0
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/generate-code-map.ts +6 -3
  73. package/scripts/record-ai-review-unmeasured.ts +370 -0
  74. package/scripts/split-spec.ts +12 -0
  75. package/scripts/sync-sc-status.ts +93 -8
@@ -47,8 +47,50 @@
47
47
  * Using `stripQuoted` for both would let an attacker quote the path; using
48
48
  * `dequote` for both reinstates all four false positives. Each test below
49
49
  * names which one it uses and why.
50
+ *
51
+ * ## The names are global; the artifacts are not (#1175)
52
+ *
53
+ * `PROTECTED_FILES` is a list of NAMES, and until #1175 a name matched in any
54
+ * tree. A fixture at `/tmp/rg-abc/workflow-state.json` was refused as readily
55
+ * as a live run's state, which is a true positive against the rule and a false
56
+ * positive against intent — agents on this repo build such fixtures
57
+ * constantly, including fixtures for this module.
58
+ *
59
+ * The scoping is by SCRATCH TREE rather than by project root, and that is a
60
+ * measurement and not a preference. #1175's acceptance asked for "the path
61
+ * relative to the project root". Swept over 5,531 real commands, the gate
62
+ * artifacts named in them resolve like this:
63
+ *
64
+ * 2,620 under the run store (`$RUNGATE_WORK_DIR`, i.e. `~/.rungate`)
65
+ * 521 under a former run store (`~/.pai-work`) or `~/.claude`
66
+ * 1,724 no resolvable path at all — a bare basename, or built by `join`
67
+ * 83 under an OS temp root
68
+ * 65 relative
69
+ * 16 under a repository tree
70
+ *
71
+ * A live `workflow-state.json` is almost never inside the project root: it is
72
+ * in the run store, one level up and sideways. "Protect what is under the
73
+ * root" would therefore have stopped protecting 3,141 of 3,240 absolute
74
+ * references — reopening `pai-config#473` C1, the forge-a-gate-result attack
75
+ * this guard was built for. The root-relative reading is recorded here as
76
+ * MEASURED WRONG rather than merely not chosen.
77
+ *
78
+ * So the question asked is the fail-closed one: can this path be shown to be
79
+ * in a scratch tree? Only then is it a fixture. Every other answer —
80
+ * elsewhere, relative, or not a path at all — keeps the old refusal. An
81
+ * allowlist is normally the wrong shape here and `pai-config#474`'s
82
+ * read-only-prefix list is why: a PREFIX says nothing about what a command
83
+ * writes. A scratch root says something about the DESTINATION, is consulted
84
+ * only after the destination has been extracted, and is not a judgement call
85
+ * — each entry is a value `mktemp -d` returns on a supported platform.
86
+ * Narrowing it over-blocks; it cannot open a hole.
50
87
  */
51
88
 
89
+ import { realpathSync, statSync } from 'fs';
90
+ import { tmpdir } from 'os';
91
+ import { basename, dirname, join, resolve } from 'path';
92
+ import { isInterpreterWord, isShellWord } from './interpreters';
93
+
52
94
  /** Gate artifacts. A write to any of these must come from the gate runner. */
53
95
  export const PROTECTED_FILES = ['workflow-state.json', '.gate-salt', '/witnesses/'];
54
96
 
@@ -62,6 +104,595 @@ export interface BashWriteDecision {
62
104
 
63
105
  const ALLOW: BashWriteDecision = { blocked: false };
64
106
 
107
+ /**
108
+ * The trees an OS temporary directory can be in.
109
+ *
110
+ * `/tmp` and `/private/tmp` are both listed because on macOS they are the
111
+ * same directory under two names and a command may spell either; `resolve()`
112
+ * normalises `..` but does not follow links, and the link cannot be followed
113
+ * here because the path being judged usually does not exist yet — it is about
114
+ * to be created. `/var/folders` is where macOS puts a per-user `$TMPDIR`, and
115
+ * `tmpdir()` covers whatever the platform or the environment says, which is
116
+ * what `mkdtemp`, `mkstemp` and `mktemp -d` all build on.
117
+ *
118
+ * Each root is also recorded in its REALPATH form. On macOS `/var` is a
119
+ * symlink to `/private/var`, so `tmpdir()` hands back `/var/folders/…/T`
120
+ * while the resolution below hands back `/private/var/folders/…/T`, and a
121
+ * list holding only the first form answers `false` for every path spelled
122
+ * the way `mkdtemp` hands it to a program.
123
+ *
124
+ * The corpus does NOT show this, and saying so is the point: real commands
125
+ * spell `/tmp` literally, so all 37 fixture commands clear either way. It
126
+ * was found by `isScratchPath, asserted directly` calling `tmpdir()`, which
127
+ * is what a program does and what a person does not. A sweep over what
128
+ * people typed cannot see a defect in what their programs compute.
129
+ *
130
+ * Read at call time rather than frozen at import, because `TMPDIR` is what a
131
+ * test harness moves when it wants its own scratch space, and a guard that
132
+ * cached the old value would refuse the new one.
133
+ *
134
+ * ## `TMPDIR` is the writer's variable, so it is not trusted
135
+ *
136
+ * The first version of this took `process.env.TMPDIR` as given. Measured:
137
+ *
138
+ * TMPDIR unset isScratchPath(…/.rungate/x/…) = false
139
+ * TMPDIR=$HOME/.rungate = true
140
+ *
141
+ * The agent whose write is being judged sets the variable that decides
142
+ * whether the write is exempt, and pointing it at the run store switches the
143
+ * guard off for the one directory it exists to protect. `tmpdir()` is the
144
+ * same hole wearing a function call — on POSIX it READS `TMPDIR`.
145
+ *
146
+ * So `FIXED` is the whole of the trust, and the environment can only ever
147
+ * SELECT within it: a `TMPDIR` that does not already resolve inside a fixed
148
+ * root is dropped. A platform whose temp directory is somewhere else
149
+ * over-blocks, which is the direction this module is allowed to be wrong in.
150
+ */
151
+ const FIXED_SCRATCH_ROOTS = ['/tmp', '/private/tmp', '/var/folders'];
152
+
153
+ /**
154
+ * Trees that hold LIVE artifacts, wherever on the disk they are.
155
+ *
156
+ * This is SUBTRACTED from the exemption in `isScratchPath`, not merely used
157
+ * to vet the root list. The difference matters: vetting roots is a proxy for
158
+ * the property, and it only holds for roots somebody thought of. Subtracting
159
+ * the trees themselves IS the property — "a live artifact is never exempt" —
160
+ * and it keeps holding when a root is added later by someone who has not
161
+ * read this comment.
162
+ *
163
+ * The two mechanisms are also not interchangeable, and conflating them was
164
+ * measured. Dropping a ROOT because it contains a protected tree removes
165
+ * `/tmp` wholesale the moment `RUNGATE_WORK_DIR` points inside it — which a
166
+ * real corpus command does — and refuses every fixture on the machine.
167
+ * Subtracting the TREE removes only that subtree and leaves the rest of
168
+ * `/tmp` exempt. So the root list is vetted only against trees that are not
169
+ * themselves scratch, and the subtraction below applies unconditionally.
170
+ *
171
+ * ## The hook directories are here because a checkout CAN be the live hook
172
+ *
173
+ * A review argued that `PROTECTED_HOOKS` should lose the scratch exemption
174
+ * entirely, on the grounds that a `.hook.ts` under `/tmp` is as likely to be
175
+ * a real checkout as a fixture — worktrees under `/tmp` are routine here.
176
+ * The counter-argument offered was that a hook source in a checkout is not
177
+ * the live hook, so compromising one does nothing until it is deployed.
178
+ *
179
+ * That counter-argument is FALSE on this machine, and `lib/hook-target-tree.ts`
180
+ * is where it was measured: every registration in `~/.claude/settings.json`
181
+ * is spelled `${PAI_HOOKS_DIR}/…` or `${RUNGATE_HOOKS_DIR}/…`, and
182
+ * `RUNGATE_HOOKS_DIR` resolved to *a checkout that is not this one*, with
183
+ * fourteen hooks executing from it. #999's shell-injection fix never reached
184
+ * the bytes that run. A checkout is the live hook exactly when a variable
185
+ * says it is.
186
+ *
187
+ * So the answer is neither "refuse the exemption for hooks" nor "trust the
188
+ * checkout": resolve where the registrations actually point and subtract
189
+ * THAT, wherever it is — including when it is under `/tmp`. A hook in a
190
+ * worktree nothing registers stays a fixture, which is the case #1175 exists
191
+ * for; a hook in the tree that is actually wired stays protected, which is
192
+ * the case the review was worried about.
193
+ *
194
+ * `process.cwd()` is deliberately NOT here, and the reason is measured. A
195
+ * checkout under `/tmp` is ordinary on this machine — the worktree this was
196
+ * written in is `/private/tmp/rg-1175-wt` — so treating the working
197
+ * directory as protected drops `/private/tmp` from the roots, and because
198
+ * `/tmp` realpaths to it the walk then refuses every `/tmp` path as well.
199
+ * 12 of 145 tests red, measured.
200
+ *
201
+ * ## BOTH spellings, which #1175 got wrong
202
+ *
203
+ * `resolve()` normalises `.` and `..`; it does not follow a symlink. So a
204
+ * tree named `/tmp/e2e` stayed in this list as `/tmp/e2e` while a path
205
+ * through the same inode reads `/private/tmp/e2e/…`, and `inAnyTree`
206
+ * matches neither spelling against the other. Executed against the module
207
+ * as merged, with `RUNGATE_WORK_DIR=/tmp/e2e`:
208
+ *
209
+ * /tmp/e2e/s/workflow-state.json blocked
210
+ * /private/tmp/e2e/s/workflow-state.json ALLOWED ← the run store
211
+ *
212
+ * The same for `RUNGATE_HOOKS_DIR`, and `/tmp` is a symlink to
213
+ * `/private/tmp` on every macOS install, so the second spelling is not
214
+ * exotic — it is what `realpath` prints.
215
+ *
216
+ * `scratchRoots()` below already recorded both spellings for the fixed
217
+ * roots, so the asymmetry was inside one file: the roots a write may land
218
+ * in were realpathed and the trees it may not were not. A `catch` here
219
+ * means the tree is not on disk, which is ordinary for a variable pointing
220
+ * at a directory the command is about to create, and the resolved spelling
221
+ * stands on its own.
222
+ */
223
+ function protectedTrees(): string[] {
224
+ const home = process.env.HOME || '';
225
+ const spellings: string[] = [];
226
+ for (const p of [
227
+ // The run store — where 2,620 of 3,240 absolute artifact references live.
228
+ process.env.RUNGATE_WORK_DIR || '',
229
+ home ? join(home, '.rungate') : '',
230
+ home ? join(home, '.claude') : '',
231
+ // The trees a hook registration resolves to. Read from the environment
232
+ // because that is what the registrations are spelled with.
233
+ process.env.PAI_HOOKS_DIR || '',
234
+ process.env.RUNGATE_HOOKS_DIR || '',
235
+ home ? join(home, '.pai', 'hooks') : '',
236
+ ].filter(Boolean)) {
237
+ const normalised = resolve(p);
238
+ spellings.push(normalised);
239
+ try {
240
+ const real = realpathSync(normalised);
241
+ if (real !== normalised) spellings.push(real);
242
+ } catch {
243
+ // Not on disk. The resolved spelling above still stands.
244
+ }
245
+ }
246
+ return spellings;
247
+ }
248
+
249
+ /** Is `p` inside, or equal to, any of `trees`? */
250
+ function inAnyTree(p: string, trees: string[]): boolean {
251
+ return trees.some(t => p === t || p.startsWith(t + '/'));
252
+ }
253
+
254
+ function scratchRoots(): string[] {
255
+ const out: string[] = [];
256
+ const contains = (root: string, p: string) => p === root || p.startsWith(root + '/');
257
+
258
+ const fixed: string[] = [];
259
+ for (const r of FIXED_SCRATCH_ROOTS) {
260
+ const n = resolve(r);
261
+ fixed.push(n);
262
+ try {
263
+ fixed.push(realpathSync(n));
264
+ } catch {
265
+ // A root that is not on this disk is still a name a command can spell.
266
+ }
267
+ }
268
+
269
+ // A protected tree that is ITSELF inside a fixed scratch root is not a
270
+ // reason to drop that root. `RUNGATE_WORK_DIR=/tmp/e2e-gate-test` is a real
271
+ // corpus command — a harness deliberately putting the run store in scratch
272
+ // for a test — and without this clause it drops `/tmp` and refuses every
273
+ // fixture on the machine, which is the same self-defeat `process.cwd()`
274
+ // caused. Measured: `isScratchPath('/tmp/p/x')` goes false under that one
275
+ // environment variable.
276
+ const guarded = protectedTrees().filter(t => !fixed.some(f => contains(f, t)));
277
+ const add = (p: string) => {
278
+ if (p === '/' || out.includes(p)) return;
279
+ // The invariant, enforced rather than documented: an exemption root that
280
+ // contains a protected tree is not an exemption root.
281
+ if (guarded.some(t => contains(p, t))) return;
282
+ out.push(p);
283
+ };
284
+
285
+ for (const f of fixed) add(f);
286
+
287
+ // The environment SELECTS within the fixed set; it cannot extend it.
288
+ for (const r of [tmpdir(), process.env.TMPDIR ?? '']) {
289
+ if (!r || !r.startsWith('/')) continue;
290
+ const n = resolve(r);
291
+ let real = n;
292
+ try {
293
+ real = realpathSync(n);
294
+ } catch {
295
+ /* not on this disk; judge the spelling */
296
+ }
297
+ if (!fixed.some(f => contains(f, n) || contains(f, real))) continue;
298
+ add(n);
299
+ add(real);
300
+ }
301
+ return out;
302
+ }
303
+
304
+ /**
305
+ * Is this path demonstrably inside a scratch tree?
306
+ *
307
+ * Only an ABSOLUTE path can be placed in a tree, so everything else — a bare
308
+ * basename, a relative path, a `join(dir, "workflow-state.json")` whose `dir`
309
+ * lives in a variable — answers `false` and stays refused. That is the whole
310
+ * fail-closed property: this function's job is to say YES, and silence means
311
+ * the old behaviour.
312
+ *
313
+ * `resolve()` first, per #1129: a destination spelled `/tmp/../Users/me/
314
+ * .rungate/x/workflow-state.json` is not in `/tmp`, and comparing the
315
+ * unnormalised string would say it is.
316
+ *
317
+ * The deepest EXISTING ancestor is then realpath'd, which is the half
318
+ * `resolve()` cannot do. Without it, `ln -s ~/.rungate/slug /tmp/esc` followed
319
+ * by a write to `/tmp/esc/workflow-state.json` is a two-command bypass of the
320
+ * thing this guard protects. The stat happens only after a protected NAME has
321
+ * already matched, so the common command pays nothing for it.
322
+ *
323
+ * It does NOT close the case where the link is made by the SAME command —
324
+ * see `exemptionIsVoid`, which is where that is handled, because the answer
325
+ * is a property of the command and not of the path.
326
+ *
327
+ * An UNEXPANDED expansion is refused. `/tmp/$X/workflow-state.json` is not a
328
+ * path, it is a path the shell will build, and `$X` may be `../../Users/me/
329
+ * .rungate/slug`. Five of the six spellings a review raised were already
330
+ * refused by `resolve()` and the `startsWith('/')` precondition — `${X}`, the
331
+ * backtick form, `/tmp/../…`, `$HOME/…` and `~/…` — and this is the sixth.
332
+ * Measured cost of refusing it: 0 of the 37 commands this branch clears, with
333
+ * 209 corpus-wide carrying a `$` in an artifact path, none of them in the
334
+ * population at stake.
335
+ *
336
+ * Both exits below return `false`. They are all but unreachable — the
337
+ * deepest artifact path in the corpus is 6 components against a cap of 64,
338
+ * and the walk only runs out of parents if `realpathSync('/')` throws — but
339
+ * an unreachable fail-OPEN in a fail-closed module is a line that reads as
340
+ * permission, and the next person to make the walk reachable inherits it.
341
+ */
342
+
343
+ /**
344
+ * Glob and brace metacharacters, tested against the DIRECTORY part only.
345
+ *
346
+ * `echo '{}' > /tmp/sym*​/workflow-state.json`, with `/tmp/syma` a symlink
347
+ * into the run store: `/tmp/sym*` does not exist, the walk climbs past it to
348
+ * `/tmp`, and the path is exempted — then the shell expands the glob and the
349
+ * write goes through the link. Same escape as the symlink case with no `ln`
350
+ * in the command for `exemptionIsVoid` to see.
351
+ *
352
+ * Only the directory part is tested, and that is measured rather than
353
+ * cautious. A glob in the BASENAME is already safe, because the directory
354
+ * above it is the thing `resolveThroughLinks` resolves — built and executed:
355
+ * with `SRC/syma` linked out of scratch, `SRC/syma/*.json` answers false and
356
+ * `SRC/sym*​/x` answered true. So the basename case needs no refusal, and
357
+ * refusing it anyway costs a real command: `rm -f /tmp/713-battery/
358
+ * pai-wrongfix/*.hook.ts` is 1 of the 37 this branch clears, and a blanket
359
+ * metacharacter class takes it back. Restricting the test to the directory
360
+ * part closes the escape at a measured cost of 0.
361
+ *
362
+ * The exact class a review proposed, `[$`*?[]{}~]` tested against the whole
363
+ * path, was swept over the same 5,573-command corpus: it takes back 1 of the
364
+ * 37, that `rm -f`. It does not ship on caution either way — it ships on the
365
+ * reading, and the reading is 1 against 0.
366
+ */
367
+ const UNRESOLVED_DIR = /[*?[\]{}]/;
368
+ export function isScratchPath(path: string): boolean {
369
+ if (!path || !path.startsWith('/')) return false;
370
+ if (/[$`]/.test(path)) return false;
371
+ // A glob in a DIRECTORY component is unresolvable and escapes; one in the
372
+ // basename does not. See `UNRESOLVED_DIR` for the measurement.
373
+ if (UNRESOLVED_DIR.test(dirname(path))) return false;
374
+
375
+ const normalised = resolve(path);
376
+ const real = resolveThroughLinks(normalised);
377
+ if (real === null) return false;
378
+
379
+ // The subtraction, applied to BOTH the spelling and the resolved path. A
380
+ // live artifact is never exempt, whichever of the two names it.
381
+ const live = protectedTrees();
382
+ if (inAnyTree(normalised, live) || inAnyTree(real, live)) return false;
383
+
384
+ const roots = scratchRoots();
385
+ return inAnyTree(normalised, roots) && inAnyTree(real, roots);
386
+ }
387
+
388
+ /**
389
+ * The path with its deepest EXISTING ancestor resolved through symlinks, and
390
+ * the not-yet-created tail re-attached. `null` when nothing in the chain can
391
+ * be resolved — which is the fail-closed answer, not a missing one.
392
+ */
393
+ function resolveThroughLinks(normalised: string): string | null {
394
+ let dir = normalised;
395
+ let suffix = '';
396
+ for (let i = 0; i < 64; i++) {
397
+ try {
398
+ const real = realpathSync(dir);
399
+ return suffix ? resolve(real, suffix) : real;
400
+ } catch {
401
+ const parent = dirname(dir);
402
+ if (parent === dir) return null;
403
+ suffix = suffix ? join(basename(dir), suffix) : basename(dir);
404
+ dir = parent;
405
+ }
406
+ }
407
+ return null;
408
+ }
409
+
410
+ /**
411
+ * Does this command do something that makes a resolved path untrustworthy?
412
+ *
413
+ * `isScratchPath` resolves the destination's existing ancestors at DECISION
414
+ * time. A command that creates a symbolic link before it writes invalidates
415
+ * that resolution between the decision and the execution, and the whole
416
+ * thing fits in one command:
417
+ *
418
+ * ln -s ~/.rungate/victim /tmp/esc && echo '{}' > /tmp/esc/workflow-state.json
419
+ *
420
+ * At decision time `/tmp/esc` does not exist, the walk reaches `/tmp`, and
421
+ * the write is exempted. Then the shell creates the link and the write lands
422
+ * in the run store. Both halves were executed: the module allowed the
423
+ * command, and a real shell put the bytes through the link. This is a
424
+ * bypass, not a race — no second actor is required.
425
+ *
426
+ * `mkdir -p` is the overwhelmingly common thing a fixture does to a path that
427
+ * does not exist yet, and a directory cannot point out of its tree. Only a
428
+ * LINK can, so only link creation voids the exemption. Measured: 0 of the 37
429
+ * commands this branch clears create one, and 9 commands in the whole 5,550
430
+ * corpus match at all.
431
+ *
432
+ * ## The verb is resolved, not pattern-matched
433
+ *
434
+ * The first version tested `/(?:^|[\s;&|(])ln\s/` against the raw command,
435
+ * which requires whitespace or a separator immediately before `ln`. Measured:
436
+ * `ln -s`, `sudo ln` and `find -exec ln` voided, but **`/bin/ln -s … /tmp/x`
437
+ * and `\ln -s … /tmp/x` did not** — two spellings the shell resolves
438
+ * identically to the one that did, walking past the control the whole
439
+ * exemption rests on.
440
+ *
441
+ * `commandWord` already strips a leading path and a leading `\` or `(`, and
442
+ * already skips `sudo`, `env`, `xargs` and the other wrappers, because
443
+ * #1120 and #1184 taught it to. Running it per segment is one tokeniser
444
+ * instead of two and gets all of that for free, so the segment's resolved
445
+ * VERB is the primary test.
446
+ *
447
+ * `LINK_CREATION` stays as a second, broader net for the positions a command
448
+ * word cannot reach: `find . -exec ln …` resolves to `find`, and
449
+ * `symlinkSync` lives inside an interpreter body this module does not parse.
450
+ * It is read off the raw command for that reason — the link and the write
451
+ * are in different segments by construction.
452
+ *
453
+ * `mkdir -p` is the overwhelmingly common thing a fixture does to a path that
454
+ * does not exist yet, and a directory cannot point out of its tree. Only a
455
+ * LINK can, so only link creation voids the exemption. Measured: 0 of the 37
456
+ * commands this branch clears create one.
457
+ */
458
+ const LINK_CREATION = /\bln\s|\bsymlinkSync\b|\bos\.symlink\b|\bsymlink\s*\(/;
459
+
460
+ /**
461
+ * `ln` is not the only verb that makes a link (#1411, raised as a CRITICAL
462
+ * by the review on #1354).
463
+ *
464
+ * GNU and BSD `cp` create links on request and spell none of
465
+ * `LINK_CREATION`'s four alternatives, so every one of these was ALLOWED —
466
+ * the bypass in the docblock above, reachable by a different verb:
467
+ *
468
+ * cp -s ~/.rungate/victim /tmp/esc && echo '{}' > /tmp/esc/workflow-state.json
469
+ *
470
+ * Measured before the fix, all allowed: `cp -s`, `cp --symbolic-link`,
471
+ * `cp -l`, `cp --link`, `cp -rs`, `cp -as`, `cp -sv`, `/bin/cp -s`,
472
+ * `sudo cp -s`, `install -l s`. `-l` belongs with `-s`: a hard link to a
473
+ * file inside the run store aims a later write at the victim's inode just
474
+ * as a symlink aims it at the victim's path.
475
+ *
476
+ * ## The FAMILY, not the spelling
477
+ *
478
+ * A test for the literal `cp -s` is the cheapest wrong fix — seven of the
479
+ * ten rows above walk around it. So the reading is token-level: a short
480
+ * cluster is any `-…` containing a lower-case `s` or `l`, which is what
481
+ * makes `-rs`, `-as` and `-sv` fall out of one rule rather than three; a
482
+ * long option is matched by PREFIX, because GNU accepts any unambiguous
483
+ * abbreviation and `--sym` is as real as `--symbolic-link`.
484
+ *
485
+ * Case matters: `cp -L` dereferences links in the SOURCE and creates none,
486
+ * so only the lower-case letters count. `cp -r`, `cp -p`, `cp -a` and
487
+ * `mkdir -p` are CONTROL rows and must stay exempt.
488
+ *
489
+ * The scan is position-independent rather than keyed to the resolved verb,
490
+ * so `find . -exec cp -s …` is covered — the same position `LINK_CREATION`
491
+ * exists to reach for `ln`, where `commandWord` resolves to `find`.
492
+ *
493
+ * ## And the `ln` boundary, since it was asked
494
+ *
495
+ * `\bln\s` needs a following character, so it misses an `ln` that ends a
496
+ * segment. Measured over five spellings: the regex misses four, and the
497
+ * segment-verb net catches three of those four (`ln`, `echo x && ln`,
498
+ * `sudo ln`). The one neither catches is `find . -exec ln` with no
499
+ * terminator, which `find(1)` refuses — "the expression must be terminated
500
+ * by a semicolon" — so it is a syntax error, not a bypass. Count: ONE
501
+ * spelling missed by both nets, ZERO executable. No change made.
502
+ *
503
+ * ## The FOUR transforms a shell applies before `cp` sees a flag
504
+ *
505
+ * Every bypass found in this family so far has been the same question asked
506
+ * about a different transform, and each was rediscovered separately because
507
+ * nothing wrote the list down. There are three, and a reading of a token is
508
+ * only correct if it survives all of them:
509
+ *
510
+ * | transform | what the shell does | where this module does it |
511
+ * |---|---|---|
512
+ * | quote removal | `'-s'`, `"-s"`, `-'s'`, `c""p` all arrive bare | `readWord`, via `scanSegment` (#1429) |
513
+ * | escape removal | `-\s`, `-r\s`, `-\-symbolic-link`, `--sy\mbolic-link` arrive as `-s`, `-rs`, `--symbolic-link` | `isLinkFlag`, before EITHER branch |
514
+ * | substitution grouping | `` `…` `` and `$(…)` hand their text to ANOTHER shell, and `$(…)` nests | `nestedCommands` |
515
+ * | ANSI-C quoting | `$'-s'` is the word `-s`, and `$'-\163'` is too | `readWord`, via `decodeAnsiC` |
516
+ *
517
+ * Measured against `/bin/bash` rather than assumed: `printf '[%s]' -\s -\l
518
+ * -r\s -\-symbolic-link --sy\mbolic-link $'-s' $'-\163' $'cp'` prints
519
+ * `[-s][-l][-rs][--symbolic-link][--symbolic-link][-s][-s][cp]`. Every one
520
+ * of those was ALLOWED before its transform was read, as were
521
+ * `` `cp -s …` ``, ``eval `cp -s …` ``, a `$(…)` containing a second
522
+ * `$(…)`, and a `$(…)` wrapping a parenthesised subshell.
523
+ *
524
+ * The fourth arrived the way the second and third did — a review round
525
+ * after the table said three — which is the argument for the table rather
526
+ * than against it. If a fifth turns up, add the row. The point is that the
527
+ * next reader checks all of them at once instead of finding them one review
528
+ * at a time.
529
+ *
530
+ * ANSI-C is the one that hides a VERB as well as a flag: `$'cp' -s` leaves
531
+ * `verbToken` nothing to match, so it is read in `readWord` — the module's
532
+ * one quote reader — rather than in `isLinkFlag`, which a hidden verb never
533
+ * reaches. Unlike the other substitution syntaxes it is settled at parse
534
+ * time, so decoding it makes a word more readable rather than guessing at
535
+ * one, and an unexpanded `$(…)` goes on reading as unprovable.
536
+ */
537
+ const LINK_VERBS = new Set(['cp', 'install']);
538
+
539
+ /** A token's verb name: `/bin/cp` and `\cp` are both `cp`. */
540
+ function verbToken(token: string): string {
541
+ const bare = token.replace(/^[\\(]+/, '');
542
+ return bare.slice(bare.lastIndexOf('/') + 1);
543
+ }
544
+
545
+ function isLinkFlag(raw: string): boolean {
546
+ // ESCAPE REMOVAL, the second of the three transforms in the table above,
547
+ // and it governs BOTH branches below rather than only the short one.
548
+ // `cp -\s` reaches `cp` as `-s` and `cp --sy\mbolic-link` reaches it as
549
+ // `--symbolic-link`; against the raw token the letter run reads `''` and
550
+ // the long name fails its prefix test, so all five escaped spellings were
551
+ // measured ALLOWED.
552
+ //
553
+ // A backslash inside a QUOTED word is literal to the shell, and `readWord`
554
+ // has already removed the quotes by the time the token arrives, so this
555
+ // cannot tell `-\s` from `'-\s'` and treats both as `-s`. That is the
556
+ // fail-closed direction and it costs a token that `cp` itself rejects as
557
+ // an invalid option. The control that keeps it honest is an ordinary
558
+ // quoted filename containing a backslash, which carries no leading `-`
559
+ // and so never reaches either branch.
560
+ const token = raw.replace(/\\(.)/g, '$1');
561
+ if (token.startsWith('--')) {
562
+ const name = token.slice(2).split('=')[0];
563
+ if (!name) return false;
564
+ return 'symbolic-link'.startsWith(name) || 'link'.startsWith(name);
565
+ }
566
+ if (!token.startsWith('-') || token.length < 2) return false;
567
+ // A flag whose letters this module cannot read — `-$F`, `-${X}`, `-`+a
568
+ // substitution — is one it cannot rule OUT, and the verb is already known
569
+ // to make links on request. Same fail-closed shape as an unplaceable
570
+ // literal in `placeLiteral`: declining to clear is cheap and visible,
571
+ // clearing something unread is neither.
572
+ if (/[$`]/.test(token)) return true;
573
+ // The LEADING LETTER RUN, not the whole token. `cp -st/tmp/esc` bundles
574
+ // `-s` with `-t`'s attached argument and `cp -sS.bak` bundles it with
575
+ // `-S`'s, and an anchored `^-[A-Za-z]+$` rejected both on the `/` and the
576
+ // `.` without ever reading the `s`. Both were measured ALLOWED. The
577
+ // controls are the same bundles without the link letter — `-t/tmp/p` and
578
+ // `-S.bak` — which must stay exempt, and do.
579
+ //
580
+ // Lower case only: `-L` follows links in the SOURCE and creates none.
581
+ const letters = /^-([A-Za-z]*)/.exec(token)?.[1] ?? '';
582
+ return /[sl]/.test(letters);
583
+ }
584
+
585
+ /**
586
+ * The tokens come from `scanSegment`, the module's ONE quote-aware pass.
587
+ *
588
+ * The first spelling of this used `stripQuoted`, which deletes a quoted
589
+ * span's content rather than removing the quotes, and the #1429 review was
590
+ * right that it defeated the whole check: `cp '-s'`, `cp "-s"`, `"cp" -s`,
591
+ * `c""p -s` and `cp --'s'ymbolic-link` were all measured ALLOWED, each one
592
+ * a command the shell runs identically to the one that was refused.
593
+ *
594
+ * The second spelling was a tokeniser of my own, and that was the wrong
595
+ * repair even though it worked. `commandWord` already resolves `"cp"`
596
+ * correctly, through `scanSegment`, because #1184 and #1196 taught it to
597
+ * after `stripQuoted` deleted `"chmod"` outright. A second tokeniser beside
598
+ * it is two deciders answering one question — the fourth shape in
599
+ * `.claude/rules/checks-must-be-able-to-fail.md` — and a mutation of either
600
+ * leaves the other holding every case up. One tokeniser.
601
+ */
602
+ function flagMakesLink(segment: string): boolean {
603
+ const words = scanSegment(segment).words;
604
+ if (!words.some(w => LINK_VERBS.has(verbToken(w)))) return false;
605
+ return words.some(isLinkFlag);
606
+ }
607
+
608
+ /**
609
+ * Text a segment will hand to ANOTHER shell: the contents of its quoted
610
+ * words and of its command substitutions (#1429).
611
+ *
612
+ * `ln` is caught inside `bash -c '…'`, `$( … )` and `eval '…'` today, but
613
+ * only because `LINK_CREATION` is a regex read off the raw text and a regex
614
+ * does not care about nesting. A reading built on segments and tokens does,
615
+ * and all four spellings of `cp -s` were measured ALLOWED while their `ln`
616
+ * twins were refused — so this is not a new hole, it is the old net's reach
617
+ * that the new one had to be given too.
618
+ *
619
+ * `interpreterPrograms` was the obvious place and is the wrong one: it
620
+ * reaches a heredoc body and returns NOTHING for `bash -c 'cp -s …'`,
621
+ * `sh -c "…"`, `$( … )` or `eval '…'` — measured, all four empty, against
622
+ * a heredoc control that returns the body. Widening it would change what
623
+ * every other arm reads. This is local to the void check.
624
+ */
625
+ function nestedCommands(view: string): string[] {
626
+ const out: string[] = [];
627
+ for (const m of view.matchAll(/'([^']*)'|"([^"]*)"/g)) out.push(m[1] ?? m[2] ?? '');
628
+ // Backticks are the OTHER substitution syntax and were missing entirely:
629
+ // `` `cp -s …` `` and ``eval `cp -s …` `` were measured ALLOWED while
630
+ // their `ln` twins were refused, for the same reason the `$(…)` rows were
631
+ // — `LINK_CREATION` is a raw-text regex that does not care about nesting
632
+ // and this reading is built on segments. They do not nest in bash, so a
633
+ // flat match is the whole grammar here.
634
+ for (const m of view.matchAll(/`([^`]*)`/g)) out.push(m[1]);
635
+ // `$(…)` DOES nest, so it gets the module's one substitution walk rather
636
+ // than a second spelling of it. Every `$(` position is examined — the
637
+ // index is not advanced past a substitution that was just read — so an
638
+ // inner body is collected as well as the outer one it sits in.
639
+ for (let i = 0; i < view.length; i++) {
640
+ if (view[i] !== '$' || view[i + 1] !== '(') continue;
641
+ const end = endOfSubstitution(view, i);
642
+ const body = view.slice(i + 2, end);
643
+ out.push(body.endsWith(')') ? body.slice(0, -1) : body); // unterminated keeps all of it
644
+ }
645
+ return out.filter(s => /\s/.test(s));
646
+ }
647
+
648
+ /**
649
+ * #1240: both tests read a view that KEEPS the text an interpreter is going
650
+ * to run. `stripHeredocs` deletes a heredoc body, so an `ln` inside
651
+ * `bash <<'EOF'` was invisible to the first test; `segments(cmd)` over the
652
+ * raw command does not make a body's lines into segments, so it was
653
+ * invisible to the second as well. One view, built once, fed to both.
654
+ */
655
+ function exemptionIsVoid(cmd: string): boolean {
656
+ const programs = interpreterPrograms(cmd).map(p => p.program);
657
+ const view = [stripHeredocs(cmd), ...programs].join('\n');
658
+ if (LINK_CREATION.test(view)) return true;
659
+ const all = [...segments(view), ...nestedCommands(view).flatMap(inner => segments(inner))];
660
+ return all.some(seg => commandWord(seg) === 'ln' || flagMakesLink(seg));
661
+ }
662
+
663
+ /**
664
+ * Path-like words in `text` that contain `needle`.
665
+ *
666
+ * A word here ends at whitespace or at a character that cannot be inside a
667
+ * shell or source-literal path — a quote, a comma, a bracket, a semicolon.
668
+ * That is deliberately crude and deliberately in the refusing direction: when
669
+ * a path is assembled rather than written out, the word this returns is the
670
+ * fragment that WAS written, which is relative, which `isScratchPath` refuses
671
+ * to exempt.
672
+ *
673
+ * Case-folded for the same reason `names()` is (#1184): the default macOS
674
+ * filesystem resolves `WORKFLOW-STATE.JSON` and `workflow-state.json` to one
675
+ * inode, so a case-sensitive search here would find no path word for the
676
+ * uppercase spelling, and a name with no path words is not exempted — it
677
+ * would refuse rather than leak. Folding keeps the two readings agreeing
678
+ * instead of agreeing by accident.
679
+ */
680
+ function pathWordsContaining(text: string, needle: string): string[] {
681
+ const out: string[] = [];
682
+ const hay = text.toLowerCase();
683
+ const pin = needle.toLowerCase();
684
+ let i = 0;
685
+ while ((i = hay.indexOf(pin, i)) !== -1) {
686
+ let s = i;
687
+ while (s > 0 && !/[\s'"`,;(){}[\]]/.test(hay[s - 1])) s--;
688
+ let e = i + pin.length;
689
+ while (e < hay.length && !/[\s'"`,;(){}[\]]/.test(hay[e])) e++;
690
+ out.push(text.slice(s, e)); // the ORIGINAL case: this is a path to resolve
691
+ i = e;
692
+ }
693
+ return out;
694
+ }
695
+
65
696
  /**
66
697
  * Split a command at top-level `;`, `&&`, `||`, `|` and newline, leaving
67
698
  * separators inside quotes alone.
@@ -87,7 +718,27 @@ export function segments(cmd: string): string[] {
87
718
  const c = cmd[i];
88
719
  if (quote) {
89
720
  cur += c;
90
- if (c === quote && cmd[i - 1] !== '\\') quote = null;
721
+ // #1203: inside SINGLE quotes nothing is escaped, not even a backslash,
722
+ // so the first `'` always closes. Treating `\'` as an escape there kept
723
+ // the span open past its real end, and everything after it — the
724
+ // separator AND the write verb — was swallowed into one segment where
725
+ // `commandWord` could never reach the verb. Inside DOUBLE quotes `\"`
726
+ // IS an escape, which is why the two cases are told apart rather than
727
+ // handled by one rule.
728
+ //
729
+ // #1249: inside DOUBLE quotes, consume the escape PAIR rather than
730
+ // looking one character back. `\\` is an escaped BACKSLASH — a
731
+ // complete pair — and the `"` after it closes the span. A lookbehind
732
+ // cannot tell that `"` from the escaped one in `\"`, so `"x\\"` was
733
+ // read as still open and the rest of the command, separator and write
734
+ // verb together, became one segment whose command word is `echo`. The
735
+ // outside-quote branch below already consumes the pair, for this same
736
+ // reason; this is that rule applied inside the span.
737
+ if (quote === '"' && c === '\\' && i + 1 < cmd.length) {
738
+ cur += cmd[++i];
739
+ continue;
740
+ }
741
+ if (c === quote) quote = null;
91
742
  continue;
92
743
  }
93
744
  if (c === '"' || c === "'") {
@@ -95,6 +746,31 @@ export function segments(cmd: string): string[] {
95
746
  cur += c;
96
747
  continue;
97
748
  }
749
+ // #1203: a backslash-newline is a LINE CONTINUATION. The shell joins the
750
+ // two lines into one command before it looks for anything else, so
751
+ // splitting on that newline put the verb in one segment and its target in
752
+ // the next, and `cp x \<nl> /r/workflow-state.json` reached the `cp` arm
753
+ // with a single operand. Same class as #1176 and #1184 — a check reading a
754
+ // transformed view whose transformation relocated the token — except this
755
+ // one relocates it across a SEGMENT boundary rather than into a quote.
756
+ //
757
+ // Joining with NOTHING, not with a space, because that is what the shell
758
+ // does: `ch\<nl>mod 777 x.hook.ts` runs chmod, so `commandWord` has to
759
+ // resolve `chmod` too. Inserting a space would read the verb as `ch`.
760
+ //
761
+ // Only outside a quote. Inside single quotes the backslash is literal and
762
+ // the newline is data, which is the negative control this must not break.
763
+ if (c === '\\') {
764
+ if (cmd[i + 1] === '\n') {
765
+ i++;
766
+ continue;
767
+ }
768
+ // An ESCAPED backslash. Consume the pair, so `\\` at end of line leaves
769
+ // no dangling `\` to swallow the newline that genuinely separates.
770
+ cur += c;
771
+ if (i + 1 < cmd.length) cur += cmd[++i];
772
+ continue;
773
+ }
98
774
  if (c === ';' || c === '\n' || c === '|' || c === '&') {
99
775
  if (cmd[i + 1] === c) i++; // `&&`, `||` are one separator, not two
100
776
  out.push(cur);
@@ -171,24 +847,156 @@ export function stripHeredocs(s: string): string {
171
847
  }
172
848
 
173
849
  /**
174
- * The delimiter word of a `<<WORD` on this line, if any.
850
+ * Which character positions on this line are OUTSIDE every quoted span.
851
+ *
852
+ * A `$(` opens a COMMAND SUBSTITUTION, and the shell parses its contents as a
853
+ * fresh command with fresh quoting — so text inside `"$( … )"` is unquoted
854
+ * even though it sits between double quotes. That one rule is the whole
855
+ * difference between the two cases in #1196's H6, and it is why this is a
856
+ * small stack rather than a boolean. Single quotes do not substitute, so a
857
+ * `$(` inside them is literal and opens nothing.
175
858
  *
176
- * #1176: deliberately NOT quote-aware, and that is load-bearing. Restricting
177
- * this to a top-level `<<` — the obvious hardening — was tried and REDDENS
178
- * the recorded `pai-config#474` false positive, whose heredoc is legitimately
179
- * nested inside `"$(cat <<'EOF' … )"`. A heredoc inside a command
180
- * substitution inside double quotes is a real heredoc; telling it apart from
181
- * `echo "<<EOF"` needs command-substitution nesting, which is a shell parser.
182
- * So `echo "<<EOF"` followed by a later bare `EOF` line still over-strips.
183
- * That direction over-blocks nothing — it deletes text the checks would
184
- * otherwise read — and is recorded rather than half-fixed.
859
+ * Deliberately per-line, matching its only caller: a quote opened on an
860
+ * earlier line reads as unquoted here. That is the behaviour this function
861
+ * replaced — which was not quote-aware at all — so no case gets worse, and
862
+ * the direction it is wrong in deletes text rather than admitting it.
863
+ */
864
+ function unquotedPositions(line: string): boolean[] {
865
+ const open = new Array<boolean>(line.length).fill(false);
866
+ const stack: string[] = ['']; // quote state per substitution depth
867
+ let i = 0;
868
+ while (i < line.length) {
869
+ const q = stack[stack.length - 1];
870
+ const c = line[i];
871
+ if (q === "'") {
872
+ if (c === "'") stack[stack.length - 1] = '';
873
+ i++;
874
+ } else if (q === '"') {
875
+ if (c === '\\') i += 2;
876
+ else if (c === '$' && line[i + 1] === '(') (stack.push(''), (i += 2));
877
+ else if (c === '"') (stack[stack.length - 1] = ''), i++;
878
+ else i++;
879
+ } else if (c === '\\') {
880
+ i += 2;
881
+ } else if (c === '$' && line[i + 1] === '(') {
882
+ open[i] = open[i + 1] = true;
883
+ stack.push('');
884
+ i += 2;
885
+ } else if (c === ')' && stack.length > 1) {
886
+ stack.pop();
887
+ i++;
888
+ } else if (c === '"' || c === "'") {
889
+ stack[stack.length - 1] = c;
890
+ i++;
891
+ } else {
892
+ open[i] = true;
893
+ i++;
894
+ }
895
+ }
896
+ return open;
897
+ }
898
+
899
+ /**
900
+ * The delimiter word of a `<<WORD` on this line, if any — at a position the
901
+ * shell would read as an operator rather than as text.
902
+ *
903
+ * #1176 left this NOT quote-aware on purpose, because the obvious hardening
904
+ * ("must be top-level") REDDENS the recorded `pai-config#474` false positive,
905
+ * whose heredoc is legitimately nested inside `"$(cat <<'EOF' … )"`. That
906
+ * reasoning was right about the fix it tried and wrong about the conclusion:
907
+ * the distinction is not depth, it is whether a command substitution has
908
+ * reset the quoting. #1196 pays for the small stack that tells them apart.
909
+ *
910
+ * What it buys: `bun -e 'x = "<<EOF"'` opened a heredoc, so every following
911
+ * line up to a bare `EOF` was deleted as a document — a quoted STRING chose
912
+ * what the guard could see. H5 was this same body-drop reached through the
913
+ * wrong character position (`<<<`); this is the wrong quoting position.
185
914
  */
186
915
  function heredocDelimiter(line: string): string | null {
187
916
  // #1184: `(?<!<)` and `(?!<)` exclude a `<<<` HERESTRING, which has no
188
917
  // terminator at all. Matching one invented a delimiter from the quoted text
189
918
  // after it and then ran straight into the unterminated case above.
190
- const m = /(?<!<)<<(?!<)-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/.exec(line);
191
- return m ? m[2] : null;
919
+ const re = /(?<!<)<<(?!<)-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
920
+ const open = unquotedPositions(line);
921
+ for (let m = re.exec(line); m; m = re.exec(line)) {
922
+ if (open[m.index]) return m[2];
923
+ }
924
+ return null;
925
+ }
926
+
927
+ /**
928
+ * Does the heredoc opened on this line hand its body to an interpreter?
929
+ *
930
+ * Two ways it can. The segment carrying the operator IS an interpreter
931
+ * (`bash <<'EOF'`), or the operator's segment is piped into one
932
+ * (`cat <<'EOF' | bash`). Everything else — `cat > doc.md <<'EOF'`,
933
+ * `gh issue comment --body-file - <<'EOF'` — is a DOCUMENT, and stripping
934
+ * those bodies is what stopped 1,860 real commands from being refused for
935
+ * quoting the words this guard looks for. That distinction is the whole
936
+ * reason this is a predicate rather than "stop stripping heredocs".
937
+ */
938
+ function heredocInterpreter(line: string): string | null {
939
+ const segs = segments(line);
940
+ const ownerIdx = segs.findIndex(s => heredocDelimiter(s) !== null);
941
+ if (ownerIdx === -1) return null;
942
+ const owner = commandWord(segs[ownerIdx]);
943
+ if (isInterpreterWord(owner)) return owner;
944
+ const opAt = line.search(/(?<!<)<<(?!<)/);
945
+ if (opAt === -1 || !line.slice(opAt).includes('|')) return null;
946
+ return segs.slice(ownerIdx + 1).map(commandWord).find(isInterpreterWord) ?? null;
947
+ }
948
+
949
+ /**
950
+ * The program text this command hands to an interpreter on stdin (#1240).
951
+ *
952
+ * A heredoc body fed to an interpreter, and a herestring operand of one.
953
+ * Deliberately NOT the `-c`/`-e` form: arm 3a already reads that, and
954
+ * returning it here would decide it twice.
955
+ *
956
+ * An UNTERMINATED heredoc is not returned. `stripHeredocs` already emits
957
+ * those lines unchanged — the #1184 fail-closed direction — so every arm
958
+ * can already see them, and returning them again would double-count a body
959
+ * that is not hidden in the first place.
960
+ */
961
+ export function interpreterPrograms(cmd: string): Array<{ shell: boolean; program: string }> {
962
+ const out: Array<{ shell: boolean; program: string }> = [];
963
+ const lines = cmd.split('\n');
964
+ let i = 0;
965
+ while (i < lines.length) {
966
+ const line = lines[i];
967
+ i++;
968
+ if (/^\s*#/.test(line)) continue; // a comment cannot open either form
969
+
970
+ // A HERESTRING has no body and no terminator, which is why
971
+ // `heredocDelimiter` excludes it (#1184). It is still a program, and it
972
+ // is invisible for the other half of the mechanism: the `>` inside it
973
+ // sits in a quoted span that the VERB view removes.
974
+ const hs = /(?<!<)<<<(?!<)([\s\S]*)$/.exec(line);
975
+ if (hs) {
976
+ const owner = segments(line).find(s => /(?<!<)<<<(?!<)/.test(s));
977
+ const word = owner ? commandWord(owner) : '';
978
+ if (isInterpreterWord(word)) {
979
+ out.push({ shell: isShellWord(word), program: dequote(hs[1]).trim() });
980
+ }
981
+ }
982
+
983
+ const delim = heredocDelimiter(line);
984
+ if (!delim) continue;
985
+ const body: string[] = [];
986
+ let j = i;
987
+ while (j < lines.length && lines[j].trim() !== delim) {
988
+ body.push(lines[j]);
989
+ j++;
990
+ }
991
+ if (j < lines.length) {
992
+ const word = heredocInterpreter(line);
993
+ if (word) out.push({ shell: isShellWord(word), program: body.join('\n') });
994
+ i = j + 1;
995
+ } else {
996
+ i = j; // unterminated: already visible, see the docblock
997
+ }
998
+ }
999
+ return out.filter(p => p.program !== '');
192
1000
  }
193
1001
 
194
1002
  /** Remove quote characters, keep the contents. Use when looking for a TARGET. */
@@ -199,6 +1007,13 @@ export function dequote(s: string): string {
199
1007
  /** Wrappers that delegate to the real command word rather than being one. */
200
1008
  const WRAPPERS = /^(?:sudo|env|nohup|time|command|xargs)$/;
201
1009
 
1010
+ /**
1011
+ * A variable assignment prefix, by the POSIX shape: an identifier, an
1012
+ * optional array subscript, then `=`. Read on the raw token — see
1013
+ * `commandWord`, where recognising it only after the path strip was a bypass.
1014
+ */
1015
+ const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*\])?=/;
1016
+
202
1017
  /**
203
1018
  * The command word of a segment — the first token that is not a wrapper, an
204
1019
  * assignment or an option. Read off `stripQuoted`, because a quoted token is
@@ -215,7 +1030,39 @@ export function commandWord(segment: string): string {
215
1030
  // The grep-PATTERN false positive this function was protecting against is
216
1031
  // unaffected: `grep -nE "chmod" f` still resolves to `grep`, because the
217
1032
  // real verb comes FIRST and a pattern is never in first position.
218
- for (const raw of dequote(stripHeredocs(segment)).trim().split(/\s+/)) {
1033
+ //
1034
+ // #1196: the TOKENS come from `scanSegment`, the same quote-aware pass the
1035
+ // redirect scan uses. The #1184 spelling was `dequote(...).split(/\s+/)`,
1036
+ // which removes the quote characters and THEN splits on whitespace — so a
1037
+ // quoted value's internal spaces become token boundaries. `A="1 grep" cp
1038
+ // <protected> /tmp/x` split to `A=1`, `grep`, `cp`, …: the `=` skip
1039
+ // consumed only `A=1` and the verb resolved to `grep`, which is on the
1040
+ // read-only side, so the `cp` was allowed. A quoted span must stay inside
1041
+ // its word; `readWord` already does that, and now there is one tokeniser
1042
+ // rather than two spellings of the idea.
1043
+ for (const raw of scanSegment(segment).words) {
1044
+ // A token carrying WHITESPACE is not a verb. It is what the quote-aware
1045
+ // tokeniser above is for — `A="1 grep"` is one word — and the same
1046
+ // property makes `--body "## Goal … chflags uchg …"` one word too. The
1047
+ // first spelling of this fix returned that whole document as the command
1048
+ // word, and `decideBashWrite` tests `IN_PLACE` against `${word} ${code}`:
1049
+ // a `gh issue create` whose body described chflags on a hook was refused,
1050
+ // which is the recorded `pai-config#474` family. The shell cannot run a
1051
+ // verb named `chmod 777` either, so nothing executable is lost.
1052
+ if (/\s/.test(raw)) continue;
1053
+ // An assignment prefix is recognised on the RAW token, before the path
1054
+ // strip. #1196: the strip runs `^.*\/` and takes the `=` away with the
1055
+ // directory part, so `FOO=/x/grep` arrived at the `includes('=')` test
1056
+ // spelled `grep` and was returned as the command word — a fake verb in
1057
+ // front of the real one. `FOO=/x/grep chmod 777 <hook>` was ALLOW on
1058
+ // main and ALLOW behind the first #1196 fix; `chmod 777 <hook>` BLOCKs.
1059
+ // Four arms were reachable this way. Same defect this issue names, a
1060
+ // different assignment shape: the prefix hides the verb either way.
1061
+ //
1062
+ // Matched by the POSIX shape rather than by `includes('=')` so a real
1063
+ // path is not mistaken for one — `/opt/a=b/bin/tool` does not start
1064
+ // with an identifier, and the test below still catches the rest.
1065
+ if (ASSIGNMENT.test(raw)) continue;
219
1066
  const tok = raw
220
1067
  .replace(/^[({\\]+/, '') // `(cmd …`, `{ cmd …`, `\cmd` — alias bypass
221
1068
  .replace(/^.*\//, ''); // `/usr/bin/python3` -> `python3`
@@ -234,23 +1081,375 @@ export function commandWord(segment: string): string {
234
1081
  * then dequoted, because `> "x/.gate-salt"` writes the same file as `>
235
1082
  * x/.gate-salt`.
236
1083
  */
1084
+
1085
+ /**
1086
+ * The index just past a quoted span whose OPENING quote is at `i`.
1087
+ *
1088
+ * #1239: both scanners below used to find the partner with `indexOf`, and
1089
+ * `indexOf` cannot tell `"` from `\"`. Inside a double-quoted span the
1090
+ * escaped quote was read as the closing one, every subsequent quote was
1091
+ * paired off by one, and the scanner ran off the end of the line — taking
1092
+ * the `>` operator with it. No operator, no target, ALLOW. Seven spellings
1093
+ * that bash runs and that overwrite the file reached a real write that way,
1094
+ * across both call sites; `test/bash-write-guard.test.ts` holds the table.
1095
+ *
1096
+ * The asymmetry is bash's and is the whole of the fix: a single-quoted span
1097
+ * takes NO escapes, so `'a\'` is a complete span whose contents are `a\`,
1098
+ * while in a double-quoted span `\` escapes whatever follows it.
1099
+ *
1100
+ * Unterminated spans run to `s.length` — the pre-existing, fail-closed
1101
+ * direction. Those spellings are syntax errors that bash refuses to run, so
1102
+ * nothing executable depends on the choice.
1103
+ *
1104
+ * ## #1471: `end` alone could not say which of those two happened
1105
+ *
1106
+ * This used to return a bare number, and for a span that closes at the very
1107
+ * LAST character of the string that number is `s.length` — the same value
1108
+ * an unterminated span returns. The one caller that strips the quotes
1109
+ * resolved the ambiguity with `end === s.length ? s.length : end - 1`, which
1110
+ * cannot be right: it takes the unterminated branch for a correctly closed
1111
+ * final word and keeps the closing quote inside the word.
1112
+ *
1113
+ * Measured on `5d0bf00e` before this fix, and **one trailing space is the
1114
+ * entire difference** — `segments()` trims it, so the spaced form is simply
1115
+ * the same command without a final-word quote:
1116
+ *
1117
+ * cp /tmp/evil.hook.ts /repo/hooks/ → targets 2, BLOCKED
1118
+ * cp /tmp/evil.hook.ts "/repo/hooks/" → targets 1, ALLOWED
1119
+ *
1120
+ * The consequence is sharper than a cosmetic trailing quote. `/repo/hooks/"`
1121
+ * does not end with `/`, so `isDirDestination` reads a DIRECTORY as a plain
1122
+ * file, the `dest/basename(src)` expansion never happens, and the target
1123
+ * that would have named `.hook.ts` is never produced. That is #1184's H4
1124
+ * arriving through a new door.
1125
+ *
1126
+ * It is #1239's defect one level down: there, `indexOf` could not tell `"`
1127
+ * from `\"`; here, `s.length` could not tell *closed at the end* from
1128
+ * *never closed*. One value carrying two meanings — and
1129
+ * `.claude/rules/checks-must-be-able-to-fail.md` names the shape: *a status
1130
+ * code is almost never specific to one mechanism*.
1131
+ *
1132
+ * So the span reports BOTH boundaries and no caller recomputes either.
1133
+ * `contentEnd` is where the span's contents stop; `end` is where the next
1134
+ * word starts. For a terminated span they differ by the closing quote, and
1135
+ * for an unterminated one they are equal. The three callers read the field
1136
+ * they need and none of them owns a ternary — which is the point, because
1137
+ * a `terminated` flag computed at each call site would be three deciders
1138
+ * over one question, and that is how this family keeps coming back.
1139
+ *
1140
+ * One function, three callers, so a mutation of it moves all of them.
1141
+ */
1142
+ interface QuotedSpan {
1143
+ /** The index just past the closing quote, or `s.length` if there is none. */
1144
+ end: number;
1145
+ /** Where the span's CONTENTS stop — `end - 1` when terminated, else `end`. */
1146
+ contentEnd: number;
1147
+ }
1148
+
1149
+ function endOfQuoted(s: string, i: number): QuotedSpan {
1150
+ const q = s[i];
1151
+ for (let j = i + 1; j < s.length; j++) {
1152
+ // Every span except the single-quoted one takes escapes — that is the
1153
+ // asymmetry stated above, and spelling it as "not `'`" rather than as a
1154
+ // list is what let the BACKTICK span join without a second scanner.
1155
+ if (q !== "'" && s[j] === '\\') {
1156
+ j++; // the escaped character, whatever it is, is not a delimiter
1157
+ continue;
1158
+ }
1159
+ if (s[j] === q) return { end: j + 1, contentEnd: j };
1160
+ }
1161
+ return { end: s.length, contentEnd: s.length };
1162
+ }
1163
+
237
1164
  /**
238
1165
  * Read one word starting at `i`, honouring quotes. Returns the word's
239
1166
  * CONTENTS — quote characters removed, contents kept — and the index after
240
1167
  * it, so `dir/"workflow-state.json"` reads as one word and not as two halves
241
1168
  * either side of a span that was deleted.
242
1169
  */
1170
+ /**
1171
+ * The index just past the `)` that closes the `$(` at `i`, or the end of
1172
+ * the string if it never closes.
1173
+ *
1174
+ * A parenthesis inside a STRING LITERAL is data, not grammar. Counting it
1175
+ * dropped the depth to zero early, ended the word in the middle of the
1176
+ * substitution, and left a `"` whose partner had already been consumed — so
1177
+ * `readWord`'s quote branch then took `close === -1` and swallowed the rest
1178
+ * of the line INCLUDING the `>` operator. No operator, no target, allow:
1179
+ *
1180
+ * echo $(echo "x)") > <protected> ran, and wrote
1181
+ *
1182
+ * That is #1205's own sentence a second time — the bug is what the scanner
1183
+ * cannot see, not the substitution — so it was fixed the same way rather
1184
+ * than by special-casing the literal that exposed it.
1185
+ *
1186
+ * Extracted from `readWord` so `nestedCommands` can reuse the walk. The
1187
+ * alternative was a second flat `/\$\(([^()]*)\)/`, which is two deciders
1188
+ * answering one question about substitution structure — the fourth shape in
1189
+ * `.claude/rules/checks-must-be-able-to-fail.md` — and the flat one is the
1190
+ * weaker: it cannot match a substitution containing parentheses at all, so
1191
+ * `$(cp -s $(echo V) /tmp/esc)` matched only the INNER one and the outer
1192
+ * body was never read. One reader.
1193
+ *
1194
+ * ## The escape handling is #1239's and it is load-bearing here (#1361)
1195
+ *
1196
+ * This function was extracted on `main` from a copy of the walk that
1197
+ * predated #1239, so it opened spans on `\"` and found their ends with
1198
+ * `indexOf`. Merging the two branches by taking the extraction unchanged
1199
+ * would have reinstated the bypass it had already fixed on the other side:
1200
+ * `echo \" > <protected>` opens a span that never closes, the scanner
1201
+ * swallows the `>`, no operator means no target, and the write is allowed.
1202
+ * One reader is still right — the reader just has to be the fixed one.
1203
+ *
1204
+ * So: a backslash OUTSIDE a span escapes the next character, and the end of
1205
+ * a span is `endOfQuoted`, which honours `\"` inside double quotes and
1206
+ * correctly does not inside single ones, because bash processes no escapes
1207
+ * there.
1208
+ */
1209
+ function endOfSubstitution(s: string, i: number): number {
1210
+ let depth = 0;
1211
+ let j = i;
1212
+ for (; j < s.length; j++) {
1213
+ const q = s[j];
1214
+ // #1239: outside a quoted span a backslash escapes the next character,
1215
+ // so `\"` does not OPEN a span and `\)` does not close the substitution.
1216
+ if (q === '\\') {
1217
+ j++; // the loop's j++ steps past the escaped character
1218
+ continue;
1219
+ }
1220
+ if (q === "'" || q === '"') {
1221
+ // `endOfQuoted` returns the index AFTER the closing quote; the loop's
1222
+ // j++ would then step over the character following it, so back up one.
1223
+ j = endOfQuoted(s, j).end - 1;
1224
+ continue;
1225
+ }
1226
+ if (s[j] === '(') depth++;
1227
+ else if (s[j] === ')' && --depth === 0) {
1228
+ j++;
1229
+ break;
1230
+ }
1231
+ }
1232
+ return j;
1233
+ }
1234
+
1235
+ /**
1236
+ * ANSI-C quoting: the value of a `$'…'` word.
1237
+ *
1238
+ * Unlike `$(…)` and `` `…` ``, this is settled at parse time — no command
1239
+ * runs and nothing is looked up — so decoding it makes a word MORE readable
1240
+ * rather than guessing at one. `$'-\163'` is the string `-s` on every run.
1241
+ *
1242
+ * An escape this does not recognise keeps its backslash, which is what bash
1243
+ * does with one.
1244
+ *
1245
+ * ## Octal and `\x` are BYTES, so the decode assembles bytes
1246
+ *
1247
+ * Measured: `printf '%s' $'\303\251' | od -An -tx1` gives `c3 a9`, and so
1248
+ * do `$'\xc3\xa9'` and a literal `é` — all three are the UTF-8 encoding of
1249
+ * one character. A per-escape `String.fromCharCode` gives U+00C3 followed
1250
+ * by U+00A9, a different string of four bytes, so above 0x7F that spelling
1251
+ * hands the module a token the shell never produced. Same defect as the
1252
+ * transforms this function exists to close, pointing the other way.
1253
+ *
1254
+ * It is a live one, not a cosmetic differential. With a symlink named
1255
+ * `café` under a scratch root pointing into the run store, the write
1256
+ * through it is REFUSED when spelled literally and when spelled
1257
+ * `$'café'`, and was ALLOWED when spelled `$'caf\303\251'` or
1258
+ * `$'caf\xc3\xa9'` — the module looked for a directory nobody had made,
1259
+ * found nothing to resolve, and exempted it as ordinary scratch. That is
1260
+ * #1175's escape with a name the decoder disagreed about.
1261
+ *
1262
+ * So escapes are decoded into BYTES and the byte string is decoded as
1263
+ * UTF-8 once, at the end. Refusing to decode above 0x80 was the first
1264
+ * repair and it does NOT close this: an undecoded `caf\303\251` is just
1265
+ * another directory that does not exist, which is exempt. The conservative
1266
+ * answer and the wrong answer are the same answer here.
1267
+ *
1268
+ * `\u` and `\U` stay code points, because that is what bash defines them
1269
+ * as — it emits their UTF-8 encoding, which is what they mean once the
1270
+ * command text has itself been decoded from UTF-8.
1271
+ *
1272
+ * What remains: a byte sequence that is not valid UTF-8, such as a lone
1273
+ * `$'\303'`, becomes U+FFFD here and names a file this module cannot
1274
+ * spell. Closing that needs byte-level paths throughout, which is a
1275
+ * different change; the residue is one unmatched character in a position
1276
+ * that is then unprovable rather than wrongly exempt.
1277
+ */
1278
+ const ANSI_C_SHORT: Record<string, string> = {
1279
+ a: '\x07',
1280
+ b: '\b',
1281
+ e: '\x1b',
1282
+ E: '\x1b',
1283
+ f: '\f',
1284
+ n: '\n',
1285
+ r: '\r',
1286
+ t: '\t',
1287
+ v: '\v',
1288
+ '\\': '\\',
1289
+ "'": "'",
1290
+ '"': '"',
1291
+ '?': '?',
1292
+ };
1293
+
1294
+ function decodeAnsiC(body: string): string {
1295
+ const bytes: number[] = [];
1296
+ // Plain text accumulates and is encoded in runs rather than per character,
1297
+ // so a surrogate PAIR is encoded as the one code point it spells instead
1298
+ // of as two lone halves.
1299
+ let pending = '';
1300
+ const flush = () => {
1301
+ if (!pending) return;
1302
+ for (const b of new TextEncoder().encode(pending)) bytes.push(b);
1303
+ pending = '';
1304
+ };
1305
+ for (let k = 0; k < body.length; k++) {
1306
+ if (body[k] !== '\\' || k + 1 >= body.length) {
1307
+ pending += body[k];
1308
+ continue;
1309
+ }
1310
+ const n = body[k + 1];
1311
+ const short = ANSI_C_SHORT[n];
1312
+ if (short !== undefined) {
1313
+ pending += short;
1314
+ k++;
1315
+ continue;
1316
+ }
1317
+ if (n >= '0' && n <= '7') {
1318
+ const oct = /^[0-7]{1,3}/.exec(body.slice(k + 1))?.[0] ?? '';
1319
+ flush();
1320
+ bytes.push(parseInt(oct, 8) & 0xff); // a BYTE
1321
+ k += oct.length;
1322
+ continue;
1323
+ }
1324
+ if (n === 'x' || n === 'u' || n === 'U') {
1325
+ const width = n === 'x' ? 2 : n === 'u' ? 4 : 8;
1326
+ const hex = new RegExp(`^[0-9a-fA-F]{1,${width}}`).exec(body.slice(k + 2))?.[0] ?? '';
1327
+ if (hex) {
1328
+ const value = parseInt(hex, 16);
1329
+ if (n === 'x') {
1330
+ flush();
1331
+ bytes.push(value & 0xff); // a BYTE
1332
+ } else {
1333
+ pending += String.fromCodePoint(value); // a CODE POINT
1334
+ }
1335
+ k += 1 + hex.length;
1336
+ continue;
1337
+ }
1338
+ }
1339
+ pending += body[k]; // an escape bash does not recognise keeps its backslash
1340
+ }
1341
+ flush();
1342
+ return new TextDecoder('utf-8').decode(new Uint8Array(bytes));
1343
+ }
1344
+
243
1345
  function readWord(s: string, i: number): [string, number] {
244
1346
  let w = '';
245
1347
  while (i < s.length) {
246
1348
  const c = s[i];
247
1349
  if (c === ' ' || c === '\t' || c === '\n') break;
248
1350
  if (c === '>' || c === '<') break; // an operator ends a word
1351
+ // #1239: a backslash escapes the next character, so `\"` is a literal
1352
+ // quote and does not open a span. Without this, `echo \" > <protected>`
1353
+ // opened a span that never closed and the scanner swallowed the `>` —
1354
+ // the shortest bypass in the family, needing no `$( )` at all. The text
1355
+ // is kept verbatim because this module expands nothing; what matters is
1356
+ // that the escaped character cannot act as a delimiter.
1357
+ if (c === '\\' && i + 1 < s.length) {
1358
+ w += c + s[i + 1];
1359
+ i += 2;
1360
+ continue;
1361
+ }
1362
+ // ANSI-C quoting, the FOURTH transform. `$'-s'` is the word `-s`, and
1363
+ // reading the `$` as an ordinary character left the token `$-s`, which
1364
+ // fails `isLinkFlag`'s `startsWith('-')` precondition before any flag
1365
+ // letter is looked at. Handled here rather than in `isLinkFlag` because
1366
+ // it is a QUOTING rule and this is the module's quote reader — and
1367
+ // because doing it here also fixes `$'cp'`, where the thing hidden is
1368
+ // the VERB and `isLinkFlag` is never consulted at all.
1369
+ //
1370
+ // A `\'` inside the body is an escaped quote, so the closing quote is
1371
+ // found by walking rather than by `indexOf`.
1372
+ //
1373
+ // ORDER AGAINST THE CLAUSE ABOVE DOES NOT MATTER and the merge that put
1374
+ // them together should say so: one tests `\` and the other `$`, so no
1375
+ // input reaches both. What does matter is that BOTH precede the quote
1376
+ // clause below, or an escaped or ANSI-C quote opens a span and the
1377
+ // scanner swallows the redirect — which is #1239's bypass arriving by a
1378
+ // second route (#1361 merge).
1379
+ if (c === '$' && s[i + 1] === "'") {
1380
+ let k = i + 2;
1381
+ for (; k < s.length && s[k] !== "'"; k++) if (s[k] === '\\') k++;
1382
+ w += decodeAnsiC(s.slice(i + 2, Math.min(k, s.length)));
1383
+ i = k + 1; // unterminated leaves i past the end, which ends the word
1384
+ continue;
1385
+ }
1386
+ // #1239: `echo "x\"" > <protected>` needs no substitution at all — the
1387
+ // shortest bypass in the family, and the issue that filed the `$( )`
1388
+ // spellings did not name it. `endOfQuoted` honours the backslash.
249
1389
  if (c === "'" || c === '"') {
250
- const close = s.indexOf(c, i + 1);
251
- const end = close === -1 ? s.length : close;
252
- w += s.slice(i + 1, end);
253
- i = end + 1;
1390
+ const span = endOfQuoted(s, i);
1391
+ // The span's CONTENTS, outer quotes removed. The escape is kept rather
1392
+ // than resolved: this module expands nothing, and keeping the text
1393
+ // verbatim is what lets `isScratchPath` go on reading an unexpanded
1394
+ // path as unprovable (#1175). What had to be right here is the word
1395
+ // BOUNDARY, so the operator after it is still seen.
1396
+ //
1397
+ // #1471: this read `end === s.length ? s.length : end - 1`, which is
1398
+ // the ambiguity `endOfQuoted` now resolves for it. `contentEnd` is the
1399
+ // answer, not a ternary this site re-derives.
1400
+ w += s.slice(i + 1, span.contentEnd);
1401
+ i = span.end;
1402
+ continue;
1403
+ }
1404
+ // #1205: a command substitution is part of the word it sits in, however
1405
+ // much whitespace is inside it. Ending the word at the first space split
1406
+ // `> /tmp/`id -un`/workflow-state.json` into the target `/tmp/`id` — which
1407
+ // names no protected artifact, so arm 1 never fired at all and a write to
1408
+ // a live run-store path was allowed. The space-free spelling was caught,
1409
+ // which is why this survived: the bug is the SPACE, not the substitution.
1410
+ //
1411
+ // The text is kept verbatim rather than expanded. This module does not
1412
+ // expand anything, and keeping the `$`/backtick is what lets #1175's
1413
+ // `isScratchPath` go on reading an unexpanded path as unprovable.
1414
+ if (c === '`') {
1415
+ // #1361's AI review found this one, and it is right: this was the last
1416
+ // `indexOf` partner-finder in the module. `indexOf` cannot tell `` ` ``
1417
+ // from ``\` ``, so an escaped backtick inside the substitution was read
1418
+ // as the closer, the word ended in the wrong place, and the `>` that
1419
+ // followed was never seen. No operator, no target, ALLOW — the exact
1420
+ // shape #1239 fixed for `"`, `'` and `$(...)`, surviving in the one
1421
+ // branch those fixes did not touch.
1422
+ //
1423
+ // Verified both halves before fixing, because a guard missing a command
1424
+ // bash refuses to run is not a bypass. All three spellings return no
1425
+ // targets at all AND are performed by bash:
1426
+ //
1427
+ // echo `echo a\`b` > <run-store>/workflow-state.json
1428
+ // echo `echo \`` > <run-store>/workflow-state.json
1429
+ // echo `echo \`\`x` > <run-store>/workflow-state.json
1430
+ //
1431
+ // `endOfQuoted` already walks escapes; a backtick span escapes exactly
1432
+ // as a double-quoted one does, so this is a third caller of the one
1433
+ // scanner rather than a fourth hand-rolled one. It returns `s.length`
1434
+ // for an unterminated span, which is the same fail-closed direction
1435
+ // this branch already took.
1436
+ // Keeps the backticks, so it reads `end` and never `contentEnd` — the
1437
+ // whole span verbatim is the point here (#1175).
1438
+ const span = endOfQuoted(s, i);
1439
+ w += s.slice(i, span.end);
1440
+ i = span.end;
1441
+ continue;
1442
+ }
1443
+ if (c === '$' && s[i + 1] === '(') {
1444
+ // #1361 merge: main extracted this walk into `endOfSubstitution` so
1445
+ // `nestedCommands` could reuse it — one reader, which is the right
1446
+ // call and is kept. #1239's backslash handling, which this branch had
1447
+ // added to the inline copy, is ported INTO that function rather than
1448
+ // left behind here. Taking main's line unchanged would have silently
1449
+ // reinstated the bypass.
1450
+ const j = endOfSubstitution(s, i);
1451
+ w += s.slice(i, j); // unterminated falls out here with j === s.length
1452
+ i = j;
254
1453
  continue;
255
1454
  }
256
1455
  w += c;
@@ -283,7 +1482,18 @@ function isWriteOperand(op: string): boolean {
283
1482
  * was seen by neither pass. Scanning finds the operator at a position and
284
1483
  * then reads the operand as a word, which is the same rule the shell uses.
285
1484
  */
286
- export function writeTargets(segment: string): string[] {
1485
+ /**
1486
+ * One left-to-right pass over a segment, returning its WORDS and its
1487
+ * redirect TARGETS.
1488
+ *
1489
+ * #1196 made this the single tokeniser. `commandWord` previously did its own
1490
+ * `dequote(...).split(/\s+/)`, which is not tokenisation: it let a quoted
1491
+ * multi-word assignment VALUE break into separate tokens, so
1492
+ * `A="1 grep" cp …` dropped only `A=1` on the `includes('=')` skip and
1493
+ * resolved the verb to `grep`. Here a quoted span stays INSIDE its word, so
1494
+ * the same input yields the single token `A=1 grep`, which is skipped whole.
1495
+ */
1496
+ function scanSegment(segment: string): { words: string[]; targets: string[] } {
287
1497
  const targets: string[] = [];
288
1498
  const words: string[] = [];
289
1499
  const s = stripHeredocs(segment);
@@ -316,8 +1526,26 @@ export function writeTargets(segment: string): string[] {
316
1526
  }
317
1527
  const [w, next] = readWord(s, i);
318
1528
  i = next === i ? i + 1 : next;
1529
+ // #1196 R3: an IO NUMBER is not a word. POSIX: an unquoted digit string
1530
+ // immediately preceding `<` or `>` names a file descriptor, so the `2`
1531
+ // in `2>/dev/null` belongs to the redirect. Emitting it as a word put it
1532
+ // in LAST position among a `cp`'s arguments, which is where this module
1533
+ // looks for the destination — so `cp /tmp/x.json /r/<protected>
1534
+ // 2>/dev/null` read its destination as `2` and the real one was demoted
1535
+ // to a source. Measured on the corpus: four genuine writes to a gate
1536
+ // artifact or a hook, allowed by #1188, and found only because a
1537
+ // classifier written for a different question made the same mistake.
1538
+ if (w && /^\d+$/.test(w) && (s[i] === '>' || s[i] === '<')) continue;
319
1539
  if (w) words.push(w);
320
1540
  }
1541
+ return { words, targets };
1542
+ }
1543
+
1544
+ /**
1545
+ * Paths a segment writes through shell redirection or a copying verb.
1546
+ */
1547
+ export function writeTargets(segment: string, whole: string = segment): string[] {
1548
+ const { words, targets } = scanSegment(segment);
321
1549
 
322
1550
  // `tee` takes MANY files. Reading only the first operand let
323
1551
  // `tee /tmp/a <protected>` through (#1176).
@@ -336,11 +1564,9 @@ export function writeTargets(segment: string): string[] {
336
1564
  if (args.length >= 2) {
337
1565
  const dest = args[args.length - 1];
338
1566
  targets.push(dest);
339
- // #1184: when the destination is a DIRECTORY the real sink is
340
- // `dest/basename(src)`, for every source. `cp /tmp/forged/
341
- // workflow-state.json /Users/jhorn/.rungate/x/` names no protected
342
- // artifact in its last argument and writes one.
343
- if (isDirDestination(dest)) {
1567
+ // When the destination is a DIRECTORY the real sink is
1568
+ // `dest/basename(src)`, for every source (#1184).
1569
+ if (isDirDestination(dest, args, whole)) {
344
1570
  for (const src of args.slice(0, -1)) {
345
1571
  targets.push(`${dest.replace(/\/+$/, '')}/${src.replace(/^.*\//, '')}`);
346
1572
  }
@@ -351,23 +1577,56 @@ export function writeTargets(segment: string): string[] {
351
1577
  }
352
1578
 
353
1579
  /**
354
- * Does this destination name a directory? A trailing slash settles it without
355
- * touching the disk; otherwise one `stat`, which is allowed to fail — a path
356
- * that cannot be examined is treated as a plain file, because the plain-file
357
- * reading is what the last-argument test already covers.
1580
+ * Does this destination name a DIRECTORY? Four oracles, three of them
1581
+ * syntactic, in the order they settle the question cheaply.
1582
+ *
1583
+ * #1184 asked only the fourth, `statSync`, and that is #1196's R2: a
1584
+ * PreToolUse hook decides before ANY of the command has run, so in
1585
+ * `mkdir -p d && cp <protected> d` the directory never exists at decision
1586
+ * time. Measured both ways on the same command — directory absent ALLOW,
1587
+ * directory present BLOCK. A guard whose answer depends on a directory the
1588
+ * same command is about to create is not a guard.
1589
+ *
1590
+ * The reviewer's simpler repair was to delete the test and push
1591
+ * `dest/basename(src)` unconditionally. Measured on 5,543 corpus commands
1592
+ * naming a protected artifact, that refuses 19 real commands and catches no
1593
+ * real write that the oracles below miss — every one of the 19 is a
1594
+ * protected file copied OUT to a plain destination, and 11 of those are the
1595
+ * `cp hooks/X.hook.ts /tmp/x.bak` backup that
1596
+ * `.claude/rules/checks-must-be-able-to-fail.md` requires before a mutation
1597
+ * battery. A guard that refuses the repository's own mandated practice gets
1598
+ * switched off. So the test stays and gains the readings it was missing.
358
1599
  */
359
- // Declared beside its only reader, matching `lib/gate-result-protection.ts`.
360
- import { statSync } from 'fs';
361
-
362
- function isDirDestination(dest: string): boolean {
363
- if (dest.endsWith('/')) return true;
1600
+ // #1175 moved `statSync` to the import block at the top, which `isScratchPath`
1601
+ // also reads from. Two `from 'fs'` statements in one module is legal and is
1602
+ // still one import of one module; one of them is what a reader greps for.
1603
+ function isDirDestination(dest: string, args: string[], whole: string): boolean {
1604
+ if (dest.endsWith('/')) return true; // `cp x d/` — the shell requires a dir
1605
+ if (args.length > 2) return true; // `cp a b c d` — d MUST be a directory
1606
+ if (createdAsDirectory(dest, whole)) return true; // `mkdir -p d && cp x d`
364
1607
  try {
365
1608
  return statSync(dest).isDirectory();
366
1609
  } catch {
367
- return false;
1610
+ return false; // unreadable reads as a plain file; that is the last-arg case
1611
+ }
1612
+ }
1613
+
1614
+ /** Does some earlier segment of this same command `mkdir` the destination? */
1615
+ function createdAsDirectory(dest: string, whole: string): boolean {
1616
+ const want = dest.replace(/\/+$/, '');
1617
+ for (const seg of segments(whole)) {
1618
+ if (commandWord(seg) !== 'mkdir') continue;
1619
+ for (const a of scanSegment(seg).words.slice(1)) {
1620
+ if (!a.startsWith('-') && a.replace(/\/+$/, '') === want) return true;
1621
+ }
368
1622
  }
1623
+ return false;
369
1624
  }
370
1625
 
1626
+ // `statSync` used to be declared here, beside its only reader. #1175 gave it
1627
+ // a second reader in `isScratchPath` at the top of the module, so the import
1628
+ // moved to the import block rather than being written twice.
1629
+
371
1630
  /**
372
1631
  * Non-option arguments of a segment, dequoted. This is what an in-place verb
373
1632
  * actually operates on — as opposed to its script, which is an argument too
@@ -417,10 +1676,35 @@ const IN_PLACE = [
417
1676
  /\brm\b/,
418
1677
  /\bln\b/,
419
1678
  /\bgit\s+(?:checkout|restore)\b/,
1679
+ // #1146: extended attributes are file metadata, and `com.apple.provenance`
1680
+ // is what was blocking writes to the hooks on this machine — so removing it
1681
+ // is a mutation of hook integrity by any reading.
1682
+ //
1683
+ // The mutating forms are read off `xattr --help`, not guessed:
1684
+ //
1685
+ // xattr [-lrsvx] file … list READ
1686
+ // xattr -p [-lrsvx] attr file … print READ
1687
+ // xattr -w [-rsx] attr value file set MUTATES
1688
+ // xattr -d [-rsv] attr file … delete MUTATES
1689
+ // xattr -c [-rsv] file … clear ALL MUTATES
1690
+ //
1691
+ // So the letters are `c`, `d`, `w` — and they may sit ANYWHERE in a flag
1692
+ // cluster, which is why this does not read a single letter. The first
1693
+ // revision of this PR shipped `-[dws]`, wrong in both directions against
1694
+ // that table: it missed `-c`, which deletes every attribute on the file,
1695
+ // and it refused `-s`, which only says "act on the symbolic link itself".
1696
+ // Seven of fifteen spellings were decided wrongly.
1697
+ //
1698
+ // A bare invocation carries no leading dash, so the READ that this arm
1699
+ // must not refuse — two real corpus commands run `xattr <hook>` to inspect
1700
+ // the attribute list — is excluded by construction rather than by a list.
1701
+ /\bxattr\b[^\n]*\s-[A-Za-z]*[cdw][A-Za-z]*\b/,
420
1702
  ];
421
1703
 
422
- /** Interpreters whose argument is a program this module cannot read. */
423
- const INTERPRETERS = /^(?:python[23]?|perl|ruby|node|bun|deno|osascript|sh|bash|zsh|dash|ksh|php)$/;
1704
+ // #1240: the list moved to `lib/interpreters.ts`, which `lib/bash-file-read.ts`
1705
+ // now reads too. Two modules were answering "is this an interpreter" with two
1706
+ // different lists, and the narrower one was why a `python3` heredoc read as a
1707
+ // document.
424
1708
 
425
1709
  /**
426
1710
  * Interpreters whose `-c` argument is SHELL — which this module can read.
@@ -429,8 +1713,9 @@ const INTERPRETERS = /^(?:python[23]?|perl|ruby|node|bun|deno|osascript|sh|bash|
429
1713
  * Python idioms, so `bash -c 'echo x > <protected>'` matched nothing and was
430
1714
  * allowed. Arm 1 could not see it either, because the body is quoted. The
431
1715
  * body is shell, the module parses shell, so it recurses instead of guessing.
1716
+ *
1717
+ * #1240: also in `lib/interpreters.ts` as `isShellWord`.
432
1718
  */
433
- const SHELLS = /^(?:sh|bash|zsh|dash|ksh)$/;
434
1719
 
435
1720
  /** The `-c` body of a shell invocation, dequoted. */
436
1721
  function shellBody(segment: string): string {
@@ -457,6 +1742,68 @@ function shellBody(segment: string): string {
457
1742
  * and `.claude/rules/checks-must-be-able-to-fail.md` would call it a
458
1743
  * detector narrower than what it detects. It is the widest setting the
459
1744
  * measured false-positive rate allows.
1745
+ *
1746
+ * ## #1214: an imported project function is outside what this arm can decide
1747
+ *
1748
+ * The concession above says an interpreter can evade this arm by calling
1749
+ * through a variable or putting the program in a file. #1214 filed a case
1750
+ * needing neither — a plain call to a project function the enumeration has
1751
+ * never heard of:
1752
+ *
1753
+ * bun -e "
1754
+ * import {initWorkflow, writeACs} from '<harness>/gates/orchestrator.ts';
1755
+ * const sf = '<run store>/workflow-state.json';
1756
+ * initWorkflow(sf, {…});
1757
+ * writeACs(sf, JSON.parse(process.argv[1]));"
1758
+ *
1759
+ * `initWorkflow` and `writeACs` both write `sf`, `sf` is a live run-store
1760
+ * artifact, and nothing in the list above matches. ALLOW.
1761
+ *
1762
+ * The issue's framing 1 — derive the suspicious-call set from the body's OWN
1763
+ * `import` statement, so the module enumerates nothing and stays
1764
+ * project-agnostic — was implemented and swept over 130,247 real commands
1765
+ * from this machine's 31,793 transcripts:
1766
+ *
1767
+ * newly BLOCKED 616 newly ALLOWED 0
1768
+ * 600 call a writing orchestrator symbol (writeWorkflowState 301,
1769
+ * initWorkflow+writeACs 285, the rest in ones and twos)
1770
+ * 10 call a reading one (readWorkflow, loadWorkflow, …)
1771
+ * 6 probe this module or take a hook census
1772
+ * 0 of the 616 are scratch fixtures; every one names the live run store.
1773
+ *
1774
+ * 97% precision by that reading, and it is still **not shippable** — for a
1775
+ * reason no count could show. The 600 are not evasions. They are this
1776
+ * harness's own prescribed mechanism:
1777
+ *
1778
+ * - `workflows/ship.js` EMITS the filed command, at the GOAL phase, under
1779
+ * an instruction reading "Run this EXACTLY as written". The payload
1780
+ * spelling `JSON.parse(process.argv[1])` is generated by
1781
+ * `acPayloadReadExpression()` in `lib/evidence-command-transport.ts`, so
1782
+ * the fingerprint belongs to the harness and to nothing else.
1783
+ * - `gates/SCHEMA-GUIDE.md` prescribes `writeWorkflowState` via `bun -e`
1784
+ * in place of the Write tool or `cat >`.
1785
+ * - `lib/gate-result-protection.ts` and `lib/gate-enforcement.ts` PRINT
1786
+ * that command to the agent as the sanctioned repair.
1787
+ *
1788
+ * So the predicate would refuse the GOAL phase of every run, and the guard
1789
+ * would be refusing the exact command its sibling modules hand out as the
1790
+ * remedy. The filed case and the sanctioned repair are the same operation,
1791
+ * differing only in which orchestrator symbol is called — and separating
1792
+ * them means enumerating one consumer's API, which is what #1214 forbids and
1793
+ * is wrong in every other tree besides.
1794
+ *
1795
+ * **The result is therefore framing 2, and it belongs here rather than in an
1796
+ * open issue: a program that imports project code is outside what a
1797
+ * command-line guard can decide.** Nothing read off the command line
1798
+ * distinguishes a sanctioned write from an unsanctioned one when both are
1799
+ * the same call to the same function on the same path. That is a question
1800
+ * about the command's PROVENANCE, not its text, so closing it needs the
1801
+ * harness to mark the commands it issued — a different mechanism from
1802
+ * parsing, and not one this module can reach.
1803
+ *
1804
+ * `test/bash-write-guard.test.ts` pins the conclusion rather than leaving it
1805
+ * as prose: the sanctioned commands must stay ALLOWED, so the next person to
1806
+ * reach for the obvious fix gets a red suite naming what it costs.
460
1807
  */
461
1808
  const WRITE_INTENT =
462
1809
  /\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]\+?['"]/;
@@ -498,6 +1845,678 @@ function names(text: string, list: string[]): string | null {
498
1845
  return null;
499
1846
  }
500
1847
 
1848
+ /**
1849
+ * Protected artifacts this text names somewhere OTHER than a scratch tree
1850
+ * (#1175).
1851
+ *
1852
+ * A name is exempted only when EVERY path word carrying it is scratch. One
1853
+ * mention of the live artifact alongside ten fixtures still refuses, which is
1854
+ * the direction a guard should err in and also the common real shape: a
1855
+ * command that copies a fixture over a run's state names both.
1856
+ */
1857
+ function namesOutsideScratch(text: string, list: string[], exempt: boolean): string[] {
1858
+ const out: string[] = [];
1859
+ for (const p of list) {
1860
+ const words = pathWordsContaining(text, p);
1861
+ if (words.length === 0) continue;
1862
+ if (exempt && words.every(isScratchPath)) continue;
1863
+ out.push(p);
1864
+ }
1865
+ return out;
1866
+ }
1867
+
1868
+ /**
1869
+ * Protected names in a program body, counting only ABSOLUTE spellings
1870
+ * outside a scratch tree (#1240).
1871
+ *
1872
+ * The stricter reading exists because of what it costs otherwise, measured
1873
+ * rather than reasoned: scanning an interpreter body for a protected NAME
1874
+ * newly refused **23** real commands, and every one of them was an agent
1875
+ * building hook FIXTURES in a `/tmp` tree with an assembled path —
1876
+ * `open(os.path.join(dst, n), "w")`, where the only word carrying
1877
+ * `.hook.ts` is the relative suffix itself. A relative fragment cannot be
1878
+ * shown to be scratch, so the fail-closed reading in `isScratchPath`
1879
+ * correctly refuses to exempt it, and the result is that the fixture work
1880
+ * #1175 exists to unblock gets refused by the arm added beside it.
1881
+ *
1882
+ * So this arm asks for an absolute path. The spelling it is there to catch
1883
+ * — `open("<run store>/workflow-state.json", "w")` inside a heredoc — is
1884
+ * absolute, and the 23 are not. The arm it mirrors (arm 3, the `-c` form)
1885
+ * keeps its looser reading: that behaviour is pre-existing and measured,
1886
+ * and tightening it is not this change's business.
1887
+ */
1888
+ function absoluteNamesOutsideScratch(text: string, exempt: boolean): string[] {
1889
+ const out: string[] = [];
1890
+ for (const p of ALL_PROTECTED) {
1891
+ const words = pathWordsContaining(text, p).filter(w => w.startsWith('/'));
1892
+ if (words.length === 0) continue;
1893
+ if (exempt && words.every(isScratchPath)) continue;
1894
+ out.push(p);
1895
+ }
1896
+ return out;
1897
+ }
1898
+
1899
+ /**
1900
+ * The `-c`/`-e` program of an interpreter segment, with only its OUTER
1901
+ * quoting removed (#1277).
1902
+ *
1903
+ * `shellBody` next door `dequote`s, which is right for a shell body about to
1904
+ * be re-parsed as shell and wrong for every other language: it deletes the
1905
+ * only thing that marks where one string literal ends and the next
1906
+ * expression begins. `bodyTargets` is the whole point of this function, and
1907
+ * it cannot answer its question on a view with no quotes in it.
1908
+ *
1909
+ * An unmatched outer quote leaves the text as it stands. `bodyTargets` then
1910
+ * reports the body `unreadable` rather than guessing, which is the
1911
+ * fail-closed direction.
1912
+ */
1913
+ export function programBody(segment: string): string {
1914
+ const m = /\s-[a-z]*[ce]\s+([\s\S]+)$/.exec(segment);
1915
+ if (!m) return '';
1916
+ const raw = m[1].trim();
1917
+ const q = raw[0];
1918
+ if ((q === "'" || q === '"') && raw.length > 1 && raw[raw.length - 1] === q) {
1919
+ return raw.slice(1, -1);
1920
+ }
1921
+ return raw;
1922
+ }
1923
+
1924
+ /**
1925
+ * A literal that STANDS ALONE as an argument is one nothing transforms, so
1926
+ * the path it spells is the path the program hands to the filesystem.
1927
+ *
1928
+ * Both sets are closed-world and that is the point. They enumerate what may
1929
+ * legally DELIMIT an argument, not what may operate on one — so a language
1930
+ * whose concatenation operator nobody here thought of reads as "not
1931
+ * delimited", which refuses. The other spelling, a denylist of operators
1932
+ * (`+`, `%`, `.replace`, an f-string, …), is a detector narrower than what
1933
+ * it detects — `.claude/rules/checks-must-be-able-to-fail.md` — and it is
1934
+ * what #1276's stopgap was a second attempt at.
1935
+ *
1936
+ * ## `=` and `:` ARE openers, and the rebinding question moved (#1371)
1937
+
1938
+ * A round of #1371 dropped them, on the finding that `p = "/tmp/x"` records
1939
+ * a target nothing then follows through its reassignment:
1940
+ *
1941
+ * p = '/tmp/fix/workflow-state.json'
1942
+ * p = p.replace('/tmp/fix', os.environ['RUNGATE_WORK_DIR'])
1943
+ * open(p, 'w').write('{}')
1944
+ *
1945
+ * Dropping them worked and was the wrong place to answer it. `inWritePosition`
1946
+ * answers the same question generally — a binding at statement level is an
1947
+ * argument of no call, so it is not a write position — and it also catches the
1948
+ * dict KEY, the ternary branch, and the inner call's default that the `:` drop
1949
+ * reached only by accident or not at all. Measured: with `inWritePosition` in
1950
+ * place, restoring `=` and `:` moves nothing — 0 newly blocked and 0 newly
1951
+ * allowed over 132,196 real commands, and the same exemption population.
1952
+ *
1953
+ * So they are restored, because two deciders answering one question are
1954
+ * behaviourally one, no behavioural test can tell them apart, and the next
1955
+ * reader deletes whichever looks redundant — the fourth shape in
1956
+ * `.claude/rules/checks-must-be-able-to-fail.md`. The measurement above is
1957
+ * exactly the evidence that they WERE two deciders.
1958
+ *
1959
+ * What this set still answers alone is ADJACENCY: `x + "/tmp/…"` has an
1960
+ * operator against the literal, and no question about write position can see
1961
+ * that.
1962
+ *
1963
+ * A closing bracket is neither an opener nor a closer. It ENDS the group the
1964
+ * literal sits in and leaves the outer expression still running, so the walk
1965
+ * steps past it and keeps asking — which is how `Path("/tmp/x")
1966
+ * .relative_to(…)` is told from `shutil.copy(src, "/tmp/x")`. The first
1967
+ * version of this stopped at the `)` and reported the pathlib spelling as a
1968
+ * target; its own CONTROL row caught it, and that row is in the tests.
1969
+ */
1970
+ const ARG_OPENS = new Set(['(', ',', '[', '{', '=', ':', ';']);
1971
+ const ARG_CLOSES = new Set([')', ',', ']', '}', ';', ':']);
1972
+ const GROUP_CLOSES = new Set([')', ']', '}']);
1973
+
1974
+ export interface BodyTargets {
1975
+ /** Carrying literals that stand alone — the paths the program can write. */
1976
+ targets: string[];
1977
+ /** Carrying literals an expression consumes. The destination is NOT these. */
1978
+ fragments: string[];
1979
+ /**
1980
+ * Literals resolving inside a protected tree, whatever they spell and
1981
+ * whether or not anything transforms them (#1371).
1982
+ *
1983
+ * `targets` and `fragments` are both filtered by `ALL_PROTECTED`, so
1984
+ * `targets.every(isScratchPath)` quantifies over a set the caller chose the
1985
+ * membership of. This one is not filtered by a name list at all, which is
1986
+ * the point: the property it reports does not depend on `ALL_PROTECTED`
1987
+ * being complete, and completeness is what failed.
1988
+ */
1989
+ protectedLiterals: string[];
1990
+ /**
1991
+ * Path-shaped literals the reader could NOT place — an expansion it cannot
1992
+ * perform, a backtick, or a relative path whose meaning depends on a
1993
+ * working directory. Kept on their own list rather than folded into
1994
+ * `protectedLiterals`, so that afterwards the reason a body was refused is
1995
+ * still readable: "it names a live tree" and "I could not tell" are
1996
+ * different facts and only one of them is a finding about the command.
1997
+ */
1998
+ unplaceable: string[];
1999
+ /** The body does not read as a sequence of complete literals. */
2000
+ unreadable: boolean;
2001
+ }
2002
+
2003
+ /**
2004
+ * Where a literal sits, as THREE readings and not two (#1371, second round).
2005
+ *
2006
+ * The first version of this returned a boolean behind
2007
+ * `if (!value.startsWith('/')) return false`, and the review was right that
2008
+ * the word *absolute* in the remedy I was given is where the hole came
2009
+ * from. `~/.rungate/run`, `$HOME/.rungate/run` and `${HOME}/.claude` all
2010
+ * took that early exit, and the caller read `false` as **not a protected
2011
+ * target** rather than as **I could not place this** — a silent skip, one
2012
+ * layer inside the remedy for silent skips.
2013
+ *
2014
+ * The asymmetry that settles it: a false `unplaceable` costs a refused
2015
+ * exemption, which somebody notices and fixes. A false `elsewhere` costs a
2016
+ * bypass, which nobody notices.
2017
+ *
2018
+ * Expansion handles the spellings we thought of; `unplaceable` handles the
2019
+ * ones we did not, and it is the half that matters. Both are kept because
2020
+ * expansion is what stops the fail-closed half from refusing every ordinary
2021
+ * `~/`-spelled read.
2022
+ */
2023
+ type Placement = 'protected' | 'unplaceable' | 'elsewhere';
2024
+
2025
+ /** A leading `~`, `$HOME` or `${HOME}`, which the runtime or shell expands. */
2026
+ const HOME_PREFIX = /^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/;
2027
+
2028
+ /**
2029
+ * Path-shaped and NOT placeable: an expansion we cannot perform, a backtick,
2030
+ * or a relative path whose meaning depends on a working directory this
2031
+ * module cannot see. `isScratchPath` already gives a relative path exactly
2032
+ * this reading — "only an ABSOLUTE path can be placed in a tree" — so this
2033
+ * is that rule applied on the other side of the same question.
2034
+ */
2035
+ const UNPLACEABLE = /[$`~]/;
2036
+
2037
+ function expandHome(value: string): string {
2038
+ const home = process.env.HOME || '';
2039
+ if (!home) return value;
2040
+ return value.replace(HOME_PREFIX, home);
2041
+ }
2042
+
2043
+ /**
2044
+ * One site per reading, so a mutation battery can remove the live-tree
2045
+ * reading without removing the fail-closed one and report which rows each
2046
+ * is actually holding up. Inlining either verdict at a second site would
2047
+ * let a refusal bypass the mutation and the rows would go green having
2048
+ * witnessed nothing — `.claude/rules/checks-must-be-able-to-fail.md`.
2049
+ */
2050
+ const IN_LIVE_TREE: Placement = 'protected';
2051
+ const CANNOT_PLACE: Placement = 'unplaceable';
2052
+
2053
+ /**
2054
+ * ## The case comparison is the VOLUME's to make, and it makes it (#1371)
2055
+ *
2056
+ * The review asked for both sides of the live-tree comparison to be
2057
+ * case-folded, as `names()` already is, because `/Users/JHORN/…` and
2058
+ * `/Users/jhorn/…` are one file and two strings on this volume. It was
2059
+ * built, and then the mutation battery refused to witness it: removing the
2060
+ * fold left the SHOUTED row refused anyway, because `resolveThroughLinks`
2061
+ * climbs to the deepest EXISTING ancestor and `realpathSync` returns the
2062
+ * canonical case — `/USERS` comes back `/Users`. So the fold decided
2063
+ * nothing that the resolution had not already decided.
2064
+ *
2065
+ * It is not shipped, and the reason is not thrift. Two deciders answering
2066
+ * one question are behaviourally one, no test can tell them apart, and the
2067
+ * next reader deletes whichever looks redundant. And on a case-SENSITIVE
2068
+ * volume the fold is the wrong answer rather than a spare one: there
2069
+ * `/Users/JHORN/x` really is a different file, which the fold would report
2070
+ * as live. `names()` folds for a different situation — it matches a
2071
+ * basename inside a command string where nothing resolves anything.
2072
+ *
2073
+ * CI proved both halves of that, and corrected the heading this note used
2074
+ * to carry. It said the differential "does not exist here", measured on
2075
+ * macOS — and the SHOUTED row went red on the Linux runner, where
2076
+ * `/HOME/RUNNER/.rungate/run` is a path that does not exist and is not the
2077
+ * artifact. The guard was right on both volumes; the claim was macOS's,
2078
+ * read as universal. The row now probes the volume and asserts the verdict
2079
+ * tracks it in BOTH directions, so a blind `.toLowerCase()` fold reddens it
2080
+ * on Linux and dropping the resolution reddens it on macOS.
2081
+ *
2082
+ * #1211 / #1358 is the same QUESTION about `WorkflowStateGuard` and may
2083
+ * well have a different answer, because that matcher has no resolution step
2084
+ * to fall back on. Worth reading this note before fixing it there.
2085
+ */
2086
+ function placeLiteral(value: string, live: string[]): Placement {
2087
+ const expanded = expandHome(value);
2088
+ // UNPLACEABLE is asked FIRST, and the order is the fix for a hole the
2089
+ // other way round left open (#1411 review): `"$RG"` carries no slash, so
2090
+ // a slash test in front of this one answered `elsewhere` — "I placed it,
2091
+ // and it is not protected" — for a value nothing had placed. Witnessed:
2092
+ // `shutil.copy("/tmp/fix/workflow-state.json", os.path.expandvars("$RG"))`
2093
+ // was ALLOWED before this swap and is refused after it. The slash-bearing
2094
+ // spelling of the same command was already refused, which is what made
2095
+ // the gap invisible.
2096
+ if (UNPLACEABLE.test(expanded)) return CANNOT_PLACE;
2097
+ // Not path-shaped at all: a mode string, a JSON blob, a module name. The
2098
+ // exemption would never apply again if these ended it.
2099
+ if (!expanded.includes('/')) return 'elsewhere';
2100
+ // A RELATIVE path-shaped literal stays `elsewhere`, and that is measured
2101
+ // rather than comfortable. Treating one as unplaceable costs 7 real
2102
+ // commands and halves the exemption population (13 segments to 6),
2103
+ // because `'hornjason/pai-config'` and `'./lib/x.ts'` are slash-bearing
2104
+ // and are not paths — and it does not even close the class it was
2105
+ // widened for, since `'.'` and `'x'` carry no slash at all. The honest
2106
+ // closure for a relative destination is `inWritePosition`, which asks
2107
+ // only about literals the write actually consumes.
2108
+ if (!expanded.startsWith('/')) return 'elsewhere';
2109
+ const normalised = resolve(expanded);
2110
+ if (inAnyTree(normalised, live)) return IN_LIVE_TREE;
2111
+ const real = resolveThroughLinks(normalised);
2112
+ // Nothing in the chain resolved, so this is a path we could not place —
2113
+ // not a path we placed outside the live trees. The distinction is the
2114
+ // whole of #1371's third round, and `isScratchPath` already notes that an
2115
+ // unreachable fail-OPEN in a fail-closed module reads as permission.
2116
+ if (real === null) return CANNOT_PLACE;
2117
+ // Both spellings, for the reason `protectedTrees` gives at length:
2118
+ // `resolve` normalises `..` and does not follow a link, so a pre-existing
2119
+ // symlink out of scratch is invisible to the first reading.
2120
+ if (inAnyTree(real, live)) return IN_LIVE_TREE;
2121
+ return 'elsewhere';
2122
+ }
2123
+
2124
+ /**
2125
+ * Which path literals in an interpreter body can be shown to be the write
2126
+ * TARGET, and which are merely fragments of an expression that computes one
2127
+ * (#1277).
2128
+ *
2129
+ * ## The mistake this replaces
2130
+ *
2131
+ * Every escape in this family is the same one wearing a different costume:
2132
+ * the exemption read a path LITERAL off the command line and treated it as
2133
+ * the destination. #1276 shipped a labelled stopgap — "is every absolute
2134
+ * literal in the body scratch" — which closed the one spelling that had been
2135
+ * measured and left the class open, because a computed destination need not
2136
+ * leave a non-scratch literal behind. Four spellings that it exempts and
2137
+ * this refuses are asserted in `test/bash-write-guard.test.ts`; the one that
2138
+ * matters least is also the one that reads worst:
2139
+ *
2140
+ * bun -e 'writeFileSync("/tmp/x/workflow-state.json"
2141
+ * .replace("/tmp/x", process.env.RUNGATE_WORK_DIR), "{}")'
2142
+ *
2143
+ * Every absolute literal in it is scratch. The write lands in the run store.
2144
+ *
2145
+ * ## What is asked instead
2146
+ *
2147
+ * A literal is a target only when nothing between it and the filesystem
2148
+ * transforms it — then, and only then, `isScratchPath` resolving it answers
2149
+ * the real question. A carrying literal that does NOT stand alone is not
2150
+ * evidence against the write, it is the ABSENCE of evidence for it, so it
2151
+ * ends the exemption rather than being ignored. That is the same fail-closed
2152
+ * reading `isScratchPath` already applies to a relative path.
2153
+ *
2154
+ * The three things this still does not do are stated rather than hidden.
2155
+ * It cannot see an assembled NAME (`'workflow' + '-state.json'`) — no
2156
+ * literal carries the artifact, so arm 3 never receives a candidate, which
2157
+ * is a limit of the candidate search and has its own asserted row. It does
2158
+ * not read a program in a FILE. And `eval` defeats it, as it defeats any
2159
+ * reading of a program that does not run it.
2160
+ */
2161
+ export function bodyTargets(body: string): BodyTargets {
2162
+ const targets: string[] = [];
2163
+ const fragments: string[] = [];
2164
+ const protectedLiterals: string[] = [];
2165
+ const unplaceable: string[] = [];
2166
+ /** Every literal span read so far, so the backward walk can step over one. */
2167
+ const spans: [number, number][] = [];
2168
+ // Read once per body rather than once per literal: each call realpaths up
2169
+ // to six trees, and a body has as many literals as it likes.
2170
+ const live = protectedTrees();
2171
+ let i = 0;
2172
+ while (i < body.length) {
2173
+ const q = body[i];
2174
+ if (q !== "'" && q !== '"') {
2175
+ i++;
2176
+ continue;
2177
+ }
2178
+ let j = i + 1;
2179
+ let value = '';
2180
+ let closed = false;
2181
+ while (j < body.length) {
2182
+ const c = body[j];
2183
+ // Only a DOUBLE-quoted literal escapes. Inside single quotes a
2184
+ // backslash is literal in both shell and Python, and treating it as an
2185
+ // escape keeps the span open past its real end — #1203's defect, one
2186
+ // layer down.
2187
+ if (q === '"' && c === '\\' && j + 1 < body.length) {
2188
+ value += body[j + 1];
2189
+ j += 2;
2190
+ continue;
2191
+ }
2192
+ if (c === q) {
2193
+ closed = true;
2194
+ break;
2195
+ }
2196
+ value += c;
2197
+ j++;
2198
+ }
2199
+ // An unterminated literal means every boundary after it is a guess.
2200
+ if (!closed) return { targets: [], fragments: [], protectedLiterals: [], unplaceable: [], unreadable: true };
2201
+ spans.push([i, j]);
2202
+ const where = placeLiteral(value, live);
2203
+ if (where === 'protected') protectedLiterals.push(value);
2204
+ if (where === 'unplaceable') unplaceable.push(value);
2205
+ if (ALL_PROTECTED.some(p => value.toLowerCase().includes(p.toLowerCase()))) {
2206
+ const pos = standsAlone(body, i, j) ? inWritePosition(body, i, spans) : UNPROVEN;
2207
+ if (pos === 'destination') targets.push(value);
2208
+ // `argument` is deliberately in neither list — see `inWritePosition`.
2209
+ else if (pos === 'unproven') fragments.push(value);
2210
+ }
2211
+ i = j + 1;
2212
+ }
2213
+ return { targets, fragments, protectedLiterals, unplaceable, unreadable: false };
2214
+ }
2215
+
2216
+ /**
2217
+ * Whitespace, including a newline. See `standsAlone` for why the newline is
2218
+ * in here rather than carrying a rule of its own.
2219
+ */
2220
+ const WHITESPACE = new Set([' ', '\t', '\n', '\r']);
2221
+
2222
+ /**
2223
+ * The callees a literal may be a direct argument of and still be the write
2224
+ * TARGET (#1371, second round).
2225
+ *
2226
+ * This is a WHITELIST OF POSITIONS, which is why it is allowed to exist at
2227
+ * all. The thing refused twice on this PR is a denylist of TRANSFORMS —
2228
+ * `.replace(`, `+`, `%`, an f-string — because a transform nobody listed
2229
+ * reads as "no transform" and the exemption holds; `Path("/tmp/x")
2230
+ * .relative_to(…)` is the standing proof and it is a CONTROL row. A
2231
+ * whitelist fails the other way: a callee nobody listed is not a recognised
2232
+ * write position, so the literal is a fragment and the exemption ends.
2233
+ *
2234
+ * The names are not a new list. They are the names already in
2235
+ * `WRITE_INTENT`, which is what makes a command a candidate for arm 3 in
2236
+ * the first place — so a verb missing here is a verb that never brought a
2237
+ * command to this question.
2238
+ *
2239
+ * `remove`, `rename`, `replace`, `unlink` and `write` are qualified rather
2240
+ * than matched bare: `str.replace` and `stdout.write` are not writes to a
2241
+ * file, and a bare match would read a transform as a write position, which
2242
+ * is the denylist's failure wearing a whitelist's clothes.
2243
+ */
2244
+ const WRITE_CALLEES = new Set([
2245
+ 'writeFileSync',
2246
+ 'appendFileSync',
2247
+ 'createWriteStream',
2248
+ 'copyFileSync',
2249
+ 'renameSync',
2250
+ 'unlinkSync',
2251
+ 'rmSync',
2252
+ 'truncateSync',
2253
+ 'write_text',
2254
+ 'open',
2255
+ 'dump',
2256
+ 'copy',
2257
+ 'copyfile',
2258
+ 'copytree',
2259
+ 'move',
2260
+ 'rmtree',
2261
+ ]);
2262
+ const QUALIFIED_WRITE_CALLEES = new Set([
2263
+ 'os.remove',
2264
+ 'os.rename',
2265
+ 'os.replace',
2266
+ 'os.unlink',
2267
+ 'os.rmdir',
2268
+ 'shutil.copy',
2269
+ 'shutil.copyfile',
2270
+ 'shutil.copytree',
2271
+ 'shutil.move',
2272
+ 'shutil.rmtree',
2273
+ 'json.dump',
2274
+ ]);
2275
+
2276
+ /**
2277
+ * WHICH argument of a recognised write call is the destination (#1411).
2278
+ *
2279
+ * Recognising the callee is not enough, because most of these take a SOURCE
2280
+ * as well: `shutil.copy("/tmp/fix/workflow-state.json", dest)` put a scratch
2281
+ * literal in `targets` while the destination was a name nothing tracks, and
2282
+ * `targets.every(isScratchPath)` then exempted a copy whose destination was
2283
+ * unknown. Witnessed allowed before this map and refused after it.
2284
+ *
2285
+ * `-1` means NO argument of that callee is ever a destination path:
2286
+ * `json.dump(obj, fp)` writes to a file object, and `p.write_text(data)`
2287
+ * writes to its RECEIVER. A literal argument of either is data, and reading
2288
+ * it as a target is the same defect pointed the other way.
2289
+ *
2290
+ * The default is 0 rather than "unknown", because every remaining name in
2291
+ * `WRITE_CALLEES` takes its path first and a name that reaches here has
2292
+ * already passed the whitelist.
2293
+ */
2294
+ const DEST_INDEX = new Map<string, number>([
2295
+ ['copy', 1],
2296
+ ['copyfile', 1],
2297
+ ['copytree', 1],
2298
+ ['copyFileSync', 1],
2299
+ ['move', 1],
2300
+ ['rename', 1],
2301
+ ['renameSync', 1],
2302
+ ['replace', 1],
2303
+ ['dump', -1],
2304
+ ['write_text', -1],
2305
+ ]);
2306
+
2307
+ function destIndexOf(name: string): number {
2308
+ const last = name.slice(name.lastIndexOf('.') + 1);
2309
+ const at = DEST_INDEX.get(last);
2310
+ return at === undefined ? 0 : at;
2311
+ }
2312
+
2313
+ function isWriteCallee(name: string): boolean {
2314
+ if (!name) return false;
2315
+ if (QUALIFIED_WRITE_CALLEES.has(name)) return true;
2316
+ const last = name.slice(name.lastIndexOf('.') + 1);
2317
+ return WRITE_CALLEES.has(last);
2318
+ }
2319
+
2320
+ /**
2321
+ * Is the literal beginning at `start` a DIRECT argument of a recognised
2322
+ * write call?
2323
+ *
2324
+ * The walk goes backwards to the opener of the group the literal sits in,
2325
+ * stepping over balanced groups and over literal spans already read — a
2326
+ * `(` inside a string is not a bracket. Three endings, and only the first
2327
+ * is a yes:
2328
+ *
2329
+ * a `(` at depth 0 the literal is an argument of that call; read the
2330
+ * callee in front of it and ask the whitelist
2331
+ * a `[` or `{` at 0 the literal is an element of a list or an entry
2332
+ * in a dict, not an argument of anything
2333
+ * the start of the body the literal is at statement level: a binding, a
2334
+ * bare expression, a dict key with no enclosing call
2335
+ *
2336
+ * This is what makes the exemption a claim about the WRITE rather than
2337
+ * about a path that appears somewhere near one, and it is what the two
2338
+ * earlier rounds were each reaching for with a cheaper instrument.
2339
+ *
2340
+ * ## Three answers, because two of them conflated placed with unreadable
2341
+ *
2342
+ * `argument` is a literal that IS a direct argument of a recognised write
2343
+ * call and is NOT at the destination index — `shutil.copy`'s source, or
2344
+ * `json.dump`'s object. A boolean had to call that `unproven`, which is a
2345
+ * fragment, which ends the exemption: with the index map added and two
2346
+ * answers available, `shutil.copy('/tmp/a/x', '/tmp/b/x')` went from
2347
+ * allowed to refused, and that command is the exact shape #1175 exists to
2348
+ * unblock. It is three CONTROL rows across three describes and all three
2349
+ * went red together, which is what a control is for.
2350
+ *
2351
+ * So: `destination` counts as a target, `unproven` ends the exemption, and
2352
+ * `argument` does neither — the literal is placed, and placed somewhere
2353
+ * that is not the write. A command whose ONLY literal is an `argument`
2354
+ * still reaches `targets.length === 0` and is refused.
2355
+ */
2356
+ type Position = 'destination' | 'argument' | 'unproven';
2357
+ const IS_DESTINATION: Position = 'destination';
2358
+ const UNPROVEN: Position = 'unproven';
2359
+
2360
+ function inWritePosition(body: string, start: number, spans: [number, number][]): Position {
2361
+ let i = start - 1;
2362
+ let depth = 0;
2363
+ /** Depth-0 commas between the opener and the literal: its argument index. */
2364
+ let index = 0;
2365
+ while (i >= 0) {
2366
+ const span = spans.find(([s, e]) => i >= s && i <= e);
2367
+ if (span) {
2368
+ i = span[0] - 1;
2369
+ continue;
2370
+ }
2371
+ const c = body[i];
2372
+ if (c === ')' || c === ']' || c === '}') {
2373
+ depth++;
2374
+ } else if (c === '(') {
2375
+ if (depth === 0) {
2376
+ const callee = calleeBefore(body, i);
2377
+ if (!isWriteCallee(callee)) return UNPROVEN;
2378
+ return index === destIndexOf(callee) ? IS_DESTINATION : 'argument';
2379
+ }
2380
+ depth--;
2381
+ } else if (c === '[' || c === '{') {
2382
+ if (depth === 0) return UNPROVEN;
2383
+ depth--;
2384
+ } else if (c === ',') {
2385
+ if (depth === 0) index++;
2386
+ } else if (c === '?') {
2387
+ // A ternary BRANCH is not a destination, it is one of two candidates,
2388
+ // and the guard has no way to say which runs. `:` is an `ARG_OPEN`, so
2389
+ // the false branch read as a complete argument and the walk continued
2390
+ // past `?` to the write call's own paren — witnessed:
2391
+ // `writeFileSync(x ? d : "/tmp/fix/workflow-state.json", "{}")` was
2392
+ // ALLOWED, while the same command with the literal in the TRUE branch
2393
+ // was already refused, because `?` is not an `ARG_OPEN` and the
2394
+ // literal fell out as a fragment. That asymmetry is the whole finding:
2395
+ // one spelling of one expression was fail-closed by accident and the
2396
+ // other was not.
2397
+ if (depth === 0) return UNPROVEN;
2398
+ }
2399
+ i--;
2400
+ }
2401
+ return UNPROVEN;
2402
+ }
2403
+
2404
+ /** The dotted name immediately in front of an opening parenthesis. */
2405
+ function calleeBefore(body: string, openIndex: number): string {
2406
+ let i = openIndex - 1;
2407
+ while (i >= 0 && WHITESPACE.has(body[i])) i--;
2408
+ let end = i + 1;
2409
+ while (i >= 0 && /[A-Za-z0-9_$.]/.test(body[i])) i--;
2410
+ return body.slice(i + 1, end);
2411
+ }
2412
+
2413
+ /**
2414
+ * Is the literal spanning `[start, end]` a complete argument on both sides,
2415
+ * and is every expression ENCLOSING it also complete?
2416
+ *
2417
+ * ## A newline is whitespace, not a delimiter (#1371)
2418
+ *
2419
+ * It used to be one: a newline at the literal's own depth ENDED the
2420
+ * expression, on the reading that a newline ends a statement. The AI review
2421
+ * on #1371 found what that costs, and it is the whole of #1277 — the
2422
+ * headline escape, with one newline inserted:
2423
+ *
2424
+ * writeFileSync("/tmp/x/workflow-state.json"
2425
+ * .replace("/tmp/x", process.env.RUNGATE_WORK_DIR), "{}")
2426
+ *
2427
+ * The literal is followed by a newline, so it read as a complete argument;
2428
+ * the `.replace` on the next line was never looked at. Both JavaScript and
2429
+ * Python continue an expression across a newline, so "a newline ends a
2430
+ * statement" is true only of a statement nothing encloses — which this walk
2431
+ * cannot tell apart from a line break inside one. A detector a reformat
2432
+ * defeats is the second shape in
2433
+ * `.claude/rules/checks-must-be-able-to-fail.md`, and it defeated the exact
2434
+ * witness the PR was written for.
2435
+ *
2436
+ * So the walk looks THROUGH whitespace in both directions to the real
2437
+ * delimiter, which is the same question it was always asking. It keeps the
2438
+ * ordinary multi-line fixture, because looking back through a newline from
2439
+ * a literal that starts a line lands on the `(` or `,` that really opened
2440
+ * it.
2441
+ *
2442
+ * ## The LEADING half has no witness, and that is said rather than implied
2443
+ *
2444
+ * The trailing half is the escape above, executed. The leading half —
2445
+ * `x +\n "…"`, where a literal opening a line read as unconsumed — is
2446
+ * symmetry, and no harmful instance of it exists that I could write: for it
2447
+ * to matter the literal must be scratch AND carry a protected artifact AND
2448
+ * be the right operand of a concatenation, and a scratch absolute path is
2449
+ * not a suffix of anything. It is kept because the two halves ask one
2450
+ * question and an asymmetric rule invites the next reader to restore the
2451
+ * half that looks arbitrary. Measured cost over 131,942 real commands:
2452
+ * 0 newly blocked, 0 newly allowed, and the exemption population does not
2453
+ * move. `bodyTargets` reporting it as a fragment is asserted in the tests;
2454
+ * no verdict claim is made for it, because none was earned.
2455
+ */
2456
+ function standsAlone(body: string, start: number, end: number): boolean {
2457
+ let a = start - 1;
2458
+ while (a >= 0 && WHITESPACE.has(body[a])) a--;
2459
+ if (a >= 0 && !ARG_OPENS.has(body[a])) return false;
2460
+
2461
+ let b = end + 1;
2462
+ for (;;) {
2463
+ while (b < body.length && WHITESPACE.has(body[b])) b++;
2464
+ if (b >= body.length) return true;
2465
+ const c = body[b];
2466
+ if (GROUP_CLOSES.has(c)) {
2467
+ b++;
2468
+ continue;
2469
+ }
2470
+ return ARG_CLOSES.has(c);
2471
+ }
2472
+ }
2473
+
2474
+ /**
2475
+ * Can every write this body could make to a protected artifact be shown to
2476
+ * land in a scratch tree?
2477
+ *
2478
+ * Five ways to answer no, and all five are the absence of evidence rather
2479
+ * than evidence of harm: the body cannot be read, a carrying literal is
2480
+ * consumed by an expression, the body names a live tree, the body names a
2481
+ * path the reader cannot PLACE, or no literal carries the artifact at all.
2482
+ * The exemption's job is to say YES.
2483
+ *
2484
+ * With five refusals stacked, the failure that costs us is no longer a
2485
+ * bypass — it is an exemption that silently never applies again, and every
2486
+ * refusal row stays green through exactly that. So the CONTROL rows are the
2487
+ * load-bearing half of the suite, and the corpus reading that matters most
2488
+ * is `exempt > 0`, not `newly blocked == 0`.
2489
+ *
2490
+ * ## Why the live-tree reading is a separate question (#1371)
2491
+ *
2492
+ * The last line is `every` over `targets`, and `targets` only ever receives
2493
+ * literals that matched `ALL_PROTECTED`. So the quantifier ranges over a set
2494
+ * the command's author chooses the membership of, and the two readings come
2495
+ * apart on a body that writes a protected artifact into scratch AND touches
2496
+ * a live tree under a name no list has:
2497
+ *
2498
+ * shutil.copy('/tmp/fix/workflow-state.json', '$HOME/.rungate/run')
2499
+ *
2500
+ * Every member of `targets` is scratch, so `every` says yes; the copy lands
2501
+ * in the run store. `main` refused this, this module allowed it until
2502
+ * #1371, and 50,189 real commands could not see it — an honest caller does
2503
+ * not write it, which is exactly who it is worth something to.
2504
+ *
2505
+ * `protectedLiterals` is the reading that does not go through a name list,
2506
+ * so it cannot be walked around by choosing a basename. The alternative on
2507
+ * the table was a second whole-body gate ANDed with this one, and it was
2508
+ * refused: two deciders answering one question are behaviourally one, no
2509
+ * test can tell them apart, and the next reader deletes the live half —
2510
+ * `.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape.
2511
+ */
2512
+ function bodyTargetsAreScratch(body: string): boolean {
2513
+ const { targets, fragments, protectedLiterals, unplaceable, unreadable } = bodyTargets(body);
2514
+ if (unreadable || fragments.length > 0) return false;
2515
+ if (protectedLiterals.length > 0 || unplaceable.length > 0) return false;
2516
+ if (targets.length === 0) return false;
2517
+ return targets.every(isScratchPath);
2518
+ }
2519
+
501
2520
  const ALL_PROTECTED = [...PROTECTED_FILES, ...PROTECTED_HOOKS];
502
2521
 
503
2522
  /**
@@ -508,12 +2527,53 @@ const ALL_PROTECTED = [...PROTECTED_FILES, ...PROTECTED_HOOKS];
508
2527
  * reason the checks above are structural: a guard tuned so wide that people
509
2528
  * work around it protects nothing, and four real refusals of read-only work
510
2529
  * is already a pattern.
2530
+ *
2531
+ * `exempt` is computed once from the WHOLE command and handed down, rather
2532
+ * than recomputed per segment or per recursion. The command that voids the
2533
+ * exemption puts the `ln` in one segment and the write in another, so a
2534
+ * per-segment answer would never see both.
511
2535
  */
512
- export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
2536
+ export function decideBashWrite(cmd: string, depth = 0, exemptIn?: boolean): BashWriteDecision {
513
2537
  if (!cmd) return ALLOW;
514
2538
  // A shell body can contain a shell body. Bounded so a crafted nest costs a
515
2539
  // fixed amount of work rather than the session.
516
2540
  if (depth > 3) return ALLOW;
2541
+ const exempt = exemptIn ?? !exemptionIsVoid(cmd);
2542
+
2543
+ // #1240: a program handed to an interpreter on stdin. `stripHeredocs`
2544
+ // deletes the body before every arm below, and arm 3a only reads a body
2545
+ // back when the segment also carries `-c`/`-e` — which `bash <<'EOF'` does
2546
+ // not. The result was that the guard decided on the single word `bash`
2547
+ // while the program underneath wrote whatever it liked. Each program is
2548
+ // re-entered as a command in its own right, and recomputes its own
2549
+ // exemption: an `ln` in the body is the body's business.
2550
+ // A SHELL body is read as shell; anything else gets the treatment arm 3
2551
+ // gives a `-c` body it cannot parse — a declared write verb near the name
2552
+ // of a protected artifact. Reading a Python body as shell finds nothing,
2553
+ // which is how `python3 <<'PY'` stayed allowed after the shell spellings
2554
+ // were closed.
2555
+ for (const { shell, program } of interpreterPrograms(cmd)) {
2556
+ if (shell) {
2557
+ const inner = decideBashWrite(program, depth + 1, exempt && !exemptionIsVoid(program));
2558
+ if (inner.blocked) return inner;
2559
+ continue;
2560
+ }
2561
+ // #1277: the same target question as arm 3 below. A stdin program is
2562
+ // the arm 3 body reached by another route, and it had NO body gate at
2563
+ // all — so the `.replace` spelling #1276 closed for `-e` was still open
2564
+ // here, in a heredoc, for as long as the stopgap existed.
2565
+ const pf = absoluteNamesOutsideScratch(program, exempt && bodyTargetsAreScratch(program)).find(p =>
2566
+ writesNear(program, p),
2567
+ );
2568
+ if (pf) {
2569
+ return {
2570
+ blocked: true,
2571
+ reason:
2572
+ `Bash command runs an interpreter or a mutating \`find\` naming "${pf}". ` +
2573
+ `What it writes cannot be read off the command line, so it is refused.`,
2574
+ };
2575
+ }
2576
+ }
517
2577
 
518
2578
  for (const seg of segments(cmd)) {
519
2579
  const bare = dequote(seg); // TARGET view: contents kept
@@ -522,7 +2582,12 @@ export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
522
2582
 
523
2583
  // 1. Shell redirection and copying verbs. Never exempted by anything:
524
2584
  // this is the arm the old allowlist sat above, which is #1120.
525
- for (const target of writeTargets(seg)) {
2585
+ // The whole command is passed so the directory test can see a `mkdir`
2586
+ // in an EARLIER segment (#1196 R2). Everything else is per-segment.
2587
+ for (const target of writeTargets(seg, cmd)) {
2588
+ // #1175: the target IS a path, so the tree question is asked directly
2589
+ // here rather than through `namesOutsideScratch`.
2590
+ if (exempt && isScratchPath(target)) continue;
526
2591
  const pf = names(target, PROTECTED_FILES);
527
2592
  if (pf) {
528
2593
  return {
@@ -546,7 +2611,7 @@ export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
546
2611
  // text contains it, and `grep "rm -rf …"` must stay a grep.
547
2612
  const verbView = `${word} ${code}`;
548
2613
  if (IN_PLACE.some(p => p.test(verbView))) {
549
- const pf = names(argumentsOf(seg).join(' '), ALL_PROTECTED);
2614
+ const pf = namesOutsideScratch(argumentsOf(seg).join(' '), ALL_PROTECTED, exempt)[0];
550
2615
  if (pf) {
551
2616
  return {
552
2617
  blocked: true,
@@ -560,23 +2625,47 @@ export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
560
2625
  // this asks for a declared write verb rather than refusing every
561
2626
  // interpreter that names a protected artifact, and for what that
562
2627
  // concession costs.
563
- const isInterpreter = INTERPRETERS.test(word) && /\s-[a-z]*[ce]\b/.test(code);
2628
+ const isInterpreter = isInterpreterWord(word) && /\s-[a-z]*[ce]\b/.test(code);
564
2629
  const isMutatingFind = word === 'find' && FIND_MUTATING.test(code);
565
2630
 
566
2631
  // 3a. A shell `-c` body is shell. Read it as shell rather than scanning
567
2632
  // it for Node and Python idioms it will never contain (#1176).
568
- if (isInterpreter && SHELLS.test(word)) {
2633
+ if (isInterpreter && isShellWord(word)) {
569
2634
  const body = shellBody(seg);
570
2635
  if (body) {
571
- const inner = decideBashWrite(body, depth + 1);
2636
+ const inner = decideBashWrite(body, depth + 1, exempt);
572
2637
  if (inner.blocked) return inner;
573
2638
  }
574
2639
  }
575
2640
 
576
2641
  if (isInterpreter || isMutatingFind) {
2642
+ // #1214 asked for a third reading here — an imported project symbol
2643
+ // called with a protected path — and it was built, measured and
2644
+ // REJECTED. See `WRITE_INTENT` for the numbers and for the one fact
2645
+ // that decided it.
2646
+ //
2647
+ // #1361 merge: this branch read the exemption with `bodyIsAllScratch`
2648
+ // (#1269). `main` has since replaced that with the TARGET question
2649
+ // below (#1277), which its own comment says closes the class #1269's
2650
+ // predicate only sampled. Main's is kept and `bodyIsAllScratch` is
2651
+ // deleted rather than left defined-and-uncalled — a superseded
2652
+ // predicate still in the file is the next reader's second decider.
2653
+ // #1277: the exemption asks whether the body's write TARGET can be
2654
+ // shown to be scratch — see `bodyTargets`. It replaces #1276's
2655
+ // all-absolute-literals stopgap, which this closes the class of.
2656
+ //
2657
+ // Two cases keep the plain `exempt`, because their destinations are
2658
+ // SHELL WORDS and not source literals, so `namesOutsideScratch`
2659
+ // already asks the target question of them directly: a mutating
2660
+ // `find`, whose operands are on the command line, and a shell `-c`
2661
+ // body, which arm 3a re-enters as shell. Handing either to a reader of
2662
+ // string literals would refuse them for having none.
2663
+ const bodyExempt =
2664
+ isMutatingFind || isShellWord(word) ? exempt : exempt && bodyTargetsAreScratch(programBody(seg));
2665
+ const candidates = namesOutsideScratch(bare, ALL_PROTECTED, bodyExempt);
577
2666
  const pf = isMutatingFind
578
- ? names(bare, ALL_PROTECTED)
579
- : (ALL_PROTECTED.find(p => bare.includes(p) && writesNear(bare, p)) ?? null);
2667
+ ? (candidates[0] ?? null)
2668
+ : (candidates.find(p => writesNear(bare, p)) ?? null);
580
2669
  if (pf) {
581
2670
  return {
582
2671
  blocked: true,
@@ -587,12 +2676,37 @@ export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
587
2676
  }
588
2677
  }
589
2678
 
590
- // 4. Permission changes on a hook file. The COMMAND WORD must be the
591
- // verb — not merely a `chmod` somewhere in the string, which is what
592
- // refused four read-only commands. The target is read off `bare`, so
593
- // quoting the path does not hide it.
594
- if ((word === 'chmod' || word === 'chflags') && names(bare, PROTECTED_HOOKS)) {
595
- return { blocked: true, reason: 'Permission change on hook file blocked. Hook integrity is protected.' };
2679
+ // 4. Permission changes on a protected artifact. The COMMAND WORD must be
2680
+ // the verb — not merely a `chmod` somewhere in the string, which is
2681
+ // what refused four read-only commands. The target is read off `bare`,
2682
+ // so quoting the path does not hide it.
2683
+ //
2684
+ // #1146: the TARGET list widened from PROTECTED_HOOKS to every
2685
+ // protected artifact; the VERB test is untouched, and that asymmetry is
2686
+ // the point. There was no reason for a `chmod` on `.gate-salt` to be
2687
+ // allowed while a `chmod` on a `.hook.ts` was refused — mode bits are
2688
+ // how a file stops being writable, so a permission change on the gate
2689
+ // salt is a step toward writing it. Measured on the 5,059 allowed
2690
+ // commands naming a protected artifact, the widening newly blocks
2691
+ // exactly one, and that one is real:
2692
+ // `chmod 600 …/worktrees/agent-abbce…/hooks/lib/.gate-salt`
2693
+ //
2694
+ // #1175 composes with that widening rather than replacing it: the
2695
+ // target list stays `ALL_PROTECTED` and the lookup moves to
2696
+ // `namesOutsideScratch`, so a `chmod` on a FIXTURE in a scratch tree
2697
+ // is not a permission change on a protected artifact. The widened
2698
+ // list and the tree scoping are independent and both are kept — a
2699
+ // textual merge that took either side alone would have silently
2700
+ // dropped one of them.
2701
+ const permTarget =
2702
+ word === 'chmod' || word === 'chflags'
2703
+ ? (namesOutsideScratch(bare, ALL_PROTECTED, exempt)[0] ?? null)
2704
+ : null;
2705
+ if (permTarget) {
2706
+ return {
2707
+ blocked: true,
2708
+ reason: `Permission change on protected artifact "${permTarget}" blocked. Integrity is protected.`,
2709
+ };
596
2710
  }
597
2711
 
598
2712
  // 5. The gate salt in the Keychain. Exempted by nothing — unlike `chmod`,