rungate 0.8.2 → 0.8.4

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 (74) 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/BunTestPathGuard.hook.ts +106 -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/TopLevelCdGuard.hook.ts +38 -6
  13. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  14. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  15. package/lib/ai-review-jury.ts +725 -0
  16. package/lib/ai-review-rounds.ts +791 -4
  17. package/lib/ai-review-unmeasured.ts +361 -0
  18. package/lib/bash-write-guard.ts +1235 -102
  19. package/lib/bun-test-paths.ts +253 -0
  20. package/lib/cli-commands.ts +252 -11
  21. package/lib/closing-reference-audit.ts +163 -0
  22. package/lib/conformity.ts +17 -1
  23. package/lib/create-sc.ts +45 -12
  24. package/lib/derived-spec.ts +206 -0
  25. package/lib/file-claims.ts +335 -0
  26. package/lib/finding-arbiter.ts +502 -28
  27. package/lib/finding-jury.ts +61 -5
  28. package/lib/finding-pr-routing.ts +333 -0
  29. package/lib/frontmatter.ts +16 -0
  30. package/lib/gate-check-audit.ts +646 -0
  31. package/lib/generators/agents-md.ts +29 -0
  32. package/lib/github.ts +112 -7
  33. package/lib/hook-tree-currency.ts +494 -0
  34. package/lib/issue-closure-audit.ts +161 -14
  35. package/lib/issue-create-override.ts +53 -3
  36. package/lib/issue-filing-gate.ts +1073 -76
  37. package/lib/local-review-rounds.ts +523 -0
  38. package/lib/organize.ts +21 -1
  39. package/lib/project-state-shape.ts +56 -5
  40. package/lib/release-preflight.ts +90 -1
  41. package/lib/repo-path.ts +94 -0
  42. package/lib/report-provenance.ts +218 -3
  43. package/lib/risk-tier.ts +302 -0
  44. package/lib/rounds-to-pass.ts +274 -0
  45. package/lib/rule-row-drift.ts +199 -0
  46. package/lib/sc-claim-forms.ts +33 -5
  47. package/lib/sc-guard.ts +11 -1
  48. package/lib/sc-id-cross-tree.ts +17 -2
  49. package/lib/sc-ids.ts +71 -6
  50. package/lib/sc-reservations.ts +158 -14
  51. package/lib/scaffold/ai-review-findings.ts +1369 -27
  52. package/lib/scaffold/ai-review-step.ts +4095 -119
  53. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  54. package/lib/scaffold/owned-files.ts +14 -0
  55. package/lib/scaffold/steps.ts +100 -9
  56. package/lib/scratch-roots.ts +93 -3
  57. package/lib/spec-updater.ts +22 -2
  58. package/lib/spec-write-ast.ts +728 -0
  59. package/lib/spec-write-sweep.ts +470 -0
  60. package/lib/test-suite-lock.ts +127 -13
  61. package/lib/ts-ast.ts +26 -0
  62. package/lib/validators/spec-validators.ts +36 -7
  63. package/lib/write-spec.ts +138 -0
  64. package/package.json +2 -1
  65. package/scripts/ai-review-findings.ts +41 -1
  66. package/scripts/arbitrate-finding.ts +330 -12
  67. package/scripts/audit-specs.ts +225 -24
  68. package/scripts/convert-spec.ts +7 -2
  69. package/scripts/create-sc.ts +14 -2
  70. package/scripts/create-spec.ts +5 -2
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/record-ai-review-unmeasured.ts +370 -0
  73. package/scripts/split-spec.ts +17 -4
  74. package/scripts/sync-sc-status.ts +14 -2
@@ -457,6 +457,194 @@ function resolveThroughLinks(normalised: string): string | null {
457
457
  */
458
458
  const LINK_CREATION = /\bln\s|\bsymlinkSync\b|\bos\.symlink\b|\bsymlink\s*\(/;
459
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
+
460
648
  /**
461
649
  * #1240: both tests read a view that KEEPS the text an interpreter is going
462
650
  * to run. `stripHeredocs` deletes a heredoc body, so an `ln` inside
@@ -468,7 +656,8 @@ function exemptionIsVoid(cmd: string): boolean {
468
656
  const programs = interpreterPrograms(cmd).map(p => p.program);
469
657
  const view = [stripHeredocs(cmd), ...programs].join('\n');
470
658
  if (LINK_CREATION.test(view)) return true;
471
- return segments(view).some(seg => commandWord(seg) === 'ln');
659
+ const all = [...segments(view), ...nestedCommands(view).flatMap(inner => segments(inner))];
660
+ return all.some(seg => commandWord(seg) === 'ln' || flagMakesLink(seg));
472
661
  }
473
662
 
474
663
  /**
@@ -892,23 +1081,324 @@ export function commandWord(segment: string): string {
892
1081
  * then dequoted, because `> "x/.gate-salt"` writes the same file as `>
893
1082
  * x/.gate-salt`.
894
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
+
895
1164
  /**
896
1165
  * Read one word starting at `i`, honouring quotes. Returns the word's
897
1166
  * CONTENTS — quote characters removed, contents kept — and the index after
898
1167
  * it, so `dir/"workflow-state.json"` reads as one word and not as two halves
899
1168
  * either side of a span that was deleted.
900
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
+
901
1345
  function readWord(s: string, i: number): [string, number] {
902
1346
  let w = '';
903
1347
  while (i < s.length) {
904
1348
  const c = s[i];
905
1349
  if (c === ' ' || c === '\t' || c === '\n') break;
906
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.
907
1389
  if (c === "'" || c === '"') {
908
- const close = s.indexOf(c, i + 1);
909
- const end = close === -1 ? s.length : close;
910
- w += s.slice(i + 1, end);
911
- 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;
912
1402
  continue;
913
1403
  }
914
1404
  // #1205: a command substitution is part of the word it sits in, however
@@ -922,43 +1412,42 @@ function readWord(s: string, i: number): [string, number] {
922
1412
  // expand anything, and keeping the `$`/backtick is what lets #1175's
923
1413
  // `isScratchPath` go on reading an unexpanded path as unprovable.
924
1414
  if (c === '`') {
925
- const close = s.indexOf('`', i + 1);
926
- // Unterminated: consume to the end. A substitution this module cannot
927
- // see the end of is not one it can read a word boundary out of, so it
928
- // takes the rest — the fail-closed direction.
929
- const end = close === -1 ? s.length : close + 1;
930
- w += s.slice(i, end);
931
- i = end;
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;
932
1441
  continue;
933
1442
  }
934
1443
  if (c === '$' && s[i + 1] === '(') {
935
- let depth = 0;
936
- let j = i;
937
- for (; j < s.length; j++) {
938
- // A parenthesis inside a STRING LITERAL is data, not grammar.
939
- // Counting it dropped the depth to zero early, ended the word in the
940
- // middle of the substitution, and left a `"` whose partner had
941
- // already been consumed — so the quote branch above then took
942
- // `close === -1` and swallowed the rest of the line INCLUDING the
943
- // `>` operator. No operator, no target, allow:
944
- //
945
- // echo $(echo "x)") > <protected> ran, and wrote
946
- //
947
- // This is #1205's own sentence a second time — the bug is what the
948
- // scanner cannot see, not the substitution — so it is fixed the same
949
- // way rather than by special-casing the literal that exposed it.
950
- const q = s[j];
951
- if (q === "'" || q === '"') {
952
- const close = s.indexOf(q, j + 1);
953
- j = close === -1 ? s.length : close; // the loop's j++ steps past it
954
- continue;
955
- }
956
- if (s[j] === '(') depth++;
957
- else if (s[j] === ')' && --depth === 0) {
958
- j++;
959
- break;
960
- }
961
- }
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);
962
1451
  w += s.slice(i, j); // unterminated falls out here with j === s.length
963
1452
  i = j;
964
1453
  continue;
@@ -1253,6 +1742,68 @@ function shellBody(segment: string): string {
1253
1742
  * and `.claude/rules/checks-must-be-able-to-fail.md` would call it a
1254
1743
  * detector narrower than what it detects. It is the widest setting the
1255
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.
1256
1807
  */
1257
1808
  const WRITE_INTENT =
1258
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]\+?['"]/;
@@ -1346,67 +1897,624 @@ function absoluteNamesOutsideScratch(text: string, exempt: boolean): string[] {
1346
1897
  }
1347
1898
 
1348
1899
  /**
1349
- * Does every absolute path literal in an interpreter body sit in a scratch
1350
- * tree? A STOPGAP, and labelled one — see #1269.
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).
1351
2128
  *
1352
- * Arm 3 refuses because an interpreter's program is opaque: what it writes
1353
- * cannot be read off the command line. The scratch exemption contradicted
1354
- * that premise by deciding the destination from one path word, and a
1355
- * destination can be computed. Executed against the module as merged:
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:
1356
2139
  *
1357
2140
  * bun -e 'writeFileSync("/tmp/x/workflow-state.json"
1358
- * .replace("/tmp/x", "<run store>"), "{}")' EXEMPT
1359
- *
1360
- * The word carrying the name is the `/tmp` literal that is thrown away. Two
1361
- * other computed spellings — a `..` chain and an `os.path.join` with `..`
1362
- * components — happened to normalise back into the store and were already
1363
- * refused, which is luck rather than coverage.
1364
- *
1365
- * This asks a question about the WHOLE body instead of one word: if the
1366
- * program also names an absolute path that is NOT scratch, the exemption
1367
- * does not apply. The escaping spelling above names the run store in its
1368
- * second argument, so it is refused.
1369
- *
1370
- * ## What this does NOT cover, stated so nobody reads it as the repair
1371
- *
1372
- * It still reads literals, so a spelling that leaves no non-scratch
1373
- * literal behind would still pass. Three candidates were tried rather than
1374
- * assumed, and all three were ALREADY refused on `origin/main` — a `$HOME`
1375
- * concatenation, an env-var concatenation and a command substitution — in
1376
- * each case because the carrying word is an absolute non-scratch suffix
1377
- * like `/.rungate/run/workflow-state.json`. Only the `.replace` of a
1378
- * scratch literal ever escaped, and that is what this closes.
1379
- *
1380
- * The durable repair is to resolve the write TARGET and ask whether the
1381
- * resolved path is under a scratch root, at which point a computed
1382
- * destination stops being a special case — the same primitive #1269's
1383
- * first fix introduced for protected trees. Filed; this is the stopgap.
1384
- *
1385
- * Neither reading closes an assembled NAME: `'workflow' + '-state.json'`
1386
- * leaves no word carrying the artifact, so arm 3 never receives a
1387
- * candidate at all. That is a limit of the candidate search rather than of
1388
- * the exemption, it is pre-existing, and it has its own row in the tests.
1389
- *
1390
- * ## Why not drop the exemption from arm 3 altogether
1391
- *
1392
- * It was built and swept. It costs **12** corpus commands against this
1393
- * one's **4**, and it reverses two of #1175's ten witnesses — the
1394
- * `python3 -I -c` and `bun -e` rows, which assert that an interpreter
1395
- * writing under a scratch root is a fixture. It also still reads literals,
1396
- * so it buys a stricter version of the same weakness rather than the
1397
- * property. Paying 12 and two witnesses for a different patch is the wrong
1398
- * trade; paying 6 for today's escape is not.
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.
1399
2455
  */
1400
- function bodyIsAllScratch(bare: string): boolean {
1401
- // `/^\/[^/]/` and not `startsWith('/')`: the looser test counted a bare
1402
- // `/` and the `//` of a comment as absolute paths that are not scratch,
1403
- // which ended the exemption for two real fixture commands on the strength
1404
- // of a comment marker. Measured, not reasoned: the loose version newly
1405
- // refuses 6 corpus commands and this one refuses 4, and the two it drops
1406
- // had no non-scratch path in them at all — only punctuation that looked
1407
- // like one.
1408
- const words = bare.split(/[\s'"`,;(){}[\]]+/).filter(w => /^\/[^/]/.test(w));
1409
- return words.length > 0 && words.every(isScratchPath);
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);
1410
2518
  }
1411
2519
 
1412
2520
  const ALL_PROTECTED = [...PROTECTED_FILES, ...PROTECTED_HOOKS];
@@ -1450,7 +2558,13 @@ export function decideBashWrite(cmd: string, depth = 0, exemptIn?: boolean): Bas
1450
2558
  if (inner.blocked) return inner;
1451
2559
  continue;
1452
2560
  }
1453
- const pf = absoluteNamesOutsideScratch(program, exempt).find(p => writesNear(program, p));
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
+ );
1454
2568
  if (pf) {
1455
2569
  return {
1456
2570
  blocked: true,
@@ -1525,11 +2639,30 @@ export function decideBashWrite(cmd: string, depth = 0, exemptIn?: boolean): Bas
1525
2639
  }
1526
2640
 
1527
2641
  if (isInterpreter || isMutatingFind) {
1528
- // #1269: the exemption asks about the whole body, not one word. See
1529
- // `bodyIsAllScratch` for what it closes, what it does not, and the
1530
- // 6-against-12 measurement behind choosing it over dropping the
1531
- // exemption from this arm entirely.
1532
- const candidates = namesOutsideScratch(bare, ALL_PROTECTED, exempt && bodyIsAllScratch(bare));
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);
1533
2666
  const pf = isMutatingFind
1534
2667
  ? (candidates[0] ?? null)
1535
2668
  : (candidates.find(p => writesNear(bare, p)) ?? null);