rungate 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. package/scripts/sync-sc-status.ts +77 -16
@@ -0,0 +1,146 @@
1
+ /**
2
+ * One reading of the process table, for every caller that needs one (#690, #707).
3
+ *
4
+ * Two subsystems ask about running processes and they used to ask differently:
5
+ * `lib/test-suite-lock.ts` ran `ps -axo command` and pattern-matched the text,
6
+ * and `~/.pai/hooks/OrphanProcessCleanup.hook.ts` ran `pgrep -f "bun test"` and
7
+ * then `pkill -f "bun test"`. Neither could answer the only question that
8
+ * matters when processes belong to other people — **whose process is this** —
9
+ * because neither read a pid, a parent, or an age.
10
+ *
11
+ * ## A pattern is not a reading, and `pkill` is not a decision
12
+ *
13
+ * `pkill -f <pattern>` has no observation step at all: it matches and signals
14
+ * in one syscall sequence, against whatever the table holds at signal time,
15
+ * including processes that started after whoever ran it decided to run it.
16
+ * There is no pid to record, no list to report, and no way to exclude the
17
+ * shell that launched the thing being killed — `-f` matches the full command
18
+ * line, so the measuring wrapper dies with the measured suite and the exit
19
+ * code is never written. That is #690: two full suites died mid-run on
20
+ * 2026-10-19 leaving logs that end at 323 lines with no summary, which is
21
+ * byte-indistinguishable from a hang.
22
+ *
23
+ * So this module reads ROWS — pid, ppid, elapsed seconds, command — and every
24
+ * decision downstream is taken about a row and signalled to a pid. Nothing in
25
+ * this repository may signal by pattern; `test/orphan-reaper.test.ts` holds
26
+ * that population at zero over `lib`, `hooks`, `scripts`, `workflows`,
27
+ * `gates` and `bin`, with no exemption list.
28
+ *
29
+ * ## An unreadable table is UNMEASURED, and it has a control string
30
+ *
31
+ * `ps` exiting non-zero, printing nothing, or printing something this parser
32
+ * cannot read must NOT come back as "no processes are running" — `0`, `[]`
33
+ * and silence are indistinguishable from success
34
+ * (`.claude/rules/config-access.md`). The control is the cheapest one
35
+ * available and it cannot be absent from a real reading: **the reading must
36
+ * contain the pid of the process taking it.** A table that cannot see its own
37
+ * reader is an instrument failure, and `readProcessTable` throws rather than
38
+ * returning a short list that every caller would read as an idle machine.
39
+ */
40
+
41
+ import { execFileSync } from "child_process";
42
+
43
+ /** One row of the process table. */
44
+ export interface ProcessRow {
45
+ pid: number;
46
+ ppid: number;
47
+ /** Wall-clock seconds since the process started, from `ps` `etime`. */
48
+ elapsedSeconds: number;
49
+ /** The full command line, `argv` joined by spaces, as `ps` reports it. */
50
+ command: string;
51
+ }
52
+
53
+ /**
54
+ * The process table could not be read, or the reading failed its own control.
55
+ *
56
+ * A distinct type so a caller can report UNMEASURED by name instead of
57
+ * folding the failure into an empty list.
58
+ */
59
+ export class ProcessTableUnreadable extends Error {
60
+ constructor(reason: string) {
61
+ super(`the process table is UNMEASURED: ${reason}`);
62
+ this.name = "ProcessTableUnreadable";
63
+ }
64
+ }
65
+
66
+ /** The `ps` invocation, in one place so there is one thing to mutate. */
67
+ export const PS_ARGS = ["-axo", "pid=,ppid=,etime=,command="];
68
+
69
+ /**
70
+ * `etime` in seconds, from BSD `ps`'s four shapes: `SS`, `MM:SS`, `HH:MM:SS`
71
+ * and `DD-HH:MM:SS`.
72
+ *
73
+ * Returns `null` rather than 0 on anything it cannot read. Zero is a real age
74
+ * — a process that started this second — so returning it for a parse failure
75
+ * would make an unreadable row look like the youngest possible process, which
76
+ * is the one state an age floor treats as "definitely leave this alone". That
77
+ * is the safe direction for the floor and the wrong direction for honesty, so
78
+ * the caller is made to decide.
79
+ */
80
+ export function parseEtime(raw: string): number | null {
81
+ const text = raw.trim();
82
+ if (!/^(\d+-)?(\d+:)?(\d+:)?\d+$/.test(text)) return null;
83
+ const [days, clock] = text.includes("-")
84
+ ? [Number(text.slice(0, text.indexOf("-"))), text.slice(text.indexOf("-") + 1)]
85
+ : [0, text];
86
+ const parts = clock.split(":").map(Number);
87
+ if (parts.some((n) => !Number.isFinite(n))) return null;
88
+ let seconds = 0;
89
+ for (const part of parts) seconds = seconds * 60 + part;
90
+ return days * 86_400 + seconds;
91
+ }
92
+
93
+ /**
94
+ * Parse `ps -axo pid=,ppid=,etime=,command=` output into rows.
95
+ *
96
+ * Lines this cannot read are DROPPED and counted by the caller's control
97
+ * rather than guessed at — a row with an unparseable age is a row nobody can
98
+ * apply an age floor to.
99
+ */
100
+ export function parseProcessTable(raw: string): ProcessRow[] {
101
+ const rows: ProcessRow[] = [];
102
+ for (const line of raw.split("\n")) {
103
+ const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
104
+ if (!m) continue;
105
+ const elapsedSeconds = parseEtime(m[3]);
106
+ if (elapsedSeconds === null) continue;
107
+ const command = m[4].trim();
108
+ if (!command) continue;
109
+ rows.push({ pid: Number(m[1]), ppid: Number(m[2]), elapsedSeconds, command });
110
+ }
111
+ return rows;
112
+ }
113
+
114
+ /** How the table is fetched. Injected so no test has to run `ps`. */
115
+ export type ProcessTableReader = () => string;
116
+
117
+ const defaultReader: ProcessTableReader = () =>
118
+ execFileSync("ps", PS_ARGS, { encoding: "utf-8", maxBuffer: 8 * 1024 * 1024 });
119
+
120
+ /**
121
+ * Read the process table, or throw `ProcessTableUnreadable`.
122
+ *
123
+ * The control is applied here and not left to callers: a reading that does
124
+ * not contain `selfPid` is refused. Every caller then gets rows it can trust
125
+ * or an exception it has to name, and neither can be mistaken for an idle
126
+ * machine.
127
+ */
128
+ export function readProcessTable(
129
+ options: { read?: ProcessTableReader; selfPid?: number } = {},
130
+ ): ProcessRow[] {
131
+ const selfPid = options.selfPid ?? process.pid;
132
+ let raw: string;
133
+ try {
134
+ raw = (options.read ?? defaultReader)();
135
+ } catch (e) {
136
+ throw new ProcessTableUnreadable(`ps could not be run (${(e as Error).message})`);
137
+ }
138
+ const rows = parseProcessTable(raw);
139
+ if (!rows.some((r) => r.pid === selfPid)) {
140
+ throw new ProcessTableUnreadable(
141
+ `the reading does not contain the reader's own pid ${selfPid}, ` +
142
+ `so ${rows.length} rows is not a count of what is running`,
143
+ );
144
+ }
145
+ return rows;
146
+ }
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Does THIS project generate `PROJECT-STATE.md` from `project-state.json`?
3
+ * (#781)
4
+ *
5
+ * `.claude/rules/key-files.md` is generated, and one of its rows was a
6
+ * hardcoded literal in two places — `lib/scanner.ts` and
7
+ * `lib/scaffold/steps.ts` — reading *"Live status + handoff (generated from
8
+ * project-state.json — don't edit directly)"*. Every consumer got that
9
+ * sentence, whether or not it was true of them.
10
+ *
11
+ * Measured on one consumer at `e58ab6bb` (named on #781): **no generator exists there.**
12
+ * Nothing in `src/`, `scripts/`, `dashboard/src/` or the `Makefile` reads
13
+ * `project-state.json`, and the two files carry unrelated content — the JSON
14
+ * has priorities and sessions, the Markdown has 27 KB of page inventory, API
15
+ * groups and architecture. An agent that reads the rule, believes it, and
16
+ * regenerates destroys the only authoritative snapshot that repo has, and
17
+ * **the loss presents as a success**: exit 0, `git status` showing `M`, not
18
+ * `D`.
19
+ *
20
+ * ## The generator was asserting a relationship it had no way to check
21
+ *
22
+ * That is the part worth fixing rather than wording around. *"Generated from
23
+ * X"* is a claim about the CONSUMER's build. The sentence that authorises the
24
+ * destructive action was emitted unconditionally by a generator that had
25
+ * never looked.
26
+ *
27
+ * So the row is now a reading. A project with something that reads
28
+ * `project-state.json` is told the file is derived; a project with nothing
29
+ * that reads it is told it is maintained directly; and a scan that could not
30
+ * look at anything says so instead of defaulting to either
31
+ * (`.claude/rules/config-access.md`, *Silent Default Substitution* — `0`,
32
+ * `{}` and silence are indistinguishable from success).
33
+ *
34
+ * ## The cheapest wrong fix, named before the repair
35
+ *
36
+ * **Soften the literal.** Replace both copies with *"Live status + handoff.
37
+ * DA-owned."* and stop. It is one find-and-replace, it removes the
38
+ * authorisation, and #781 lists it as option 1.
39
+ *
40
+ * It is wrong because it is wrong in the other direction for everybody else:
41
+ * this repository DOES generate `PROJECT-STATE.md`, from
42
+ * `scripts/update-project-state.ts`, and a consumer told to edit it directly
43
+ * will have its edits overwritten on the next run. The derivation claim is
44
+ * not false — it is *conditional*, and a fix that deletes it trades one
45
+ * untrue sentence for another.
46
+ *
47
+ * The case that does not survive it is the GENERATOR_FOUND one: a fixture
48
+ * that does read `project-state.json` must still be told the file is
49
+ * derived. A battery with only the no-generator shape in it would have
50
+ * certified the softening.
51
+ *
52
+ * ## Why the scan reports its own coverage
53
+ *
54
+ * #492: a scan that reports a verdict should report how much it read. An
55
+ * empty tree and a tree with no generator produce the same `found: false`,
56
+ * and only one of them is a measurement. `filesScanned` and `bytesScanned`
57
+ * are both carried, and both must be non-zero — a byte count alone is
58
+ * walked past by a single newline, which is measured in that issue.
59
+ */
60
+
61
+ import { existsSync, readFileSync, readdirSync, statSync } from "fs";
62
+ import { join } from "path";
63
+
64
+ /** The one spelling of the ownership fact, so no site states it twice. */
65
+ export const PROJECT_STATE_OWNERSHIP = "DA-owned (#296)";
66
+
67
+ export const PROJECT_STATE_DERIVED =
68
+ "Live status + handoff (generated from project-state.json — don't edit directly)";
69
+
70
+ export const PROJECT_STATE_UNDERIVED =
71
+ `Live status + handoff. ${PROJECT_STATE_OWNERSHIP} — nothing in this project reads ` +
72
+ "project-state.json, so this file is maintained directly and regenerating it would " +
73
+ "destroy its contents";
74
+
75
+ export const PROJECT_STATE_UNMEASURED =
76
+ `Live status + handoff. ${PROJECT_STATE_OWNERSHIP} — whether anything in this project ` +
77
+ "generates it could not be determined, so do not regenerate it";
78
+
79
+ export type DerivationVerdict = "GENERATOR_FOUND" | "NO_GENERATOR" | "UNMEASURED";
80
+
81
+ export interface DerivationReading {
82
+ verdict: DerivationVerdict;
83
+ /** Project-relative paths that read `project-state.json`. */
84
+ evidence: string[];
85
+ /** How many files the walk actually opened, so a PASS can report its coverage. */
86
+ filesScanned: number;
87
+ /** And how much of them it read — one empty file is not a scan. */
88
+ bytesScanned: number;
89
+ /** Present only on UNMEASURED, and never empty when it is. */
90
+ unmeasuredReason: string | null;
91
+ }
92
+
93
+ /**
94
+ * Where a generator could live. Deliberately wider than the source
95
+ * directories `scanner.ts` detects: `scripts/` and `bin/` are where this
96
+ * repository's own updater lives, and a walk that missed them would report
97
+ * NO_GENERATOR for the tree it is running in.
98
+ */
99
+ const SEARCH_DIRS = ["src", "lib", "gates", "workflows", "hooks", "scripts", "bin", "dashboard/src"];
100
+ const SEARCH_FILES = ["Makefile", "package.json", "justfile", "Taskfile.yml"];
101
+
102
+ /** `.claude/` is excluded on purpose: the rule file naming the claim is not evidence for it. */
103
+ const SKIP_DIRS = new Set([".git", ".claude", "node_modules", "dist", "build", "coverage"]);
104
+
105
+ /**
106
+ * This module is excluded from its own walk.
107
+ *
108
+ * #646's trap, in the form that is easiest to ship by accident: the file that
109
+ * DECIDES whether a generator exists quotes both of the strings it looks for,
110
+ * so without this it is evidence for itself and every project carrying a copy
111
+ * of rungate's source reads GENERATOR_FOUND. The store quoting the subject
112
+ * back is not a witness.
113
+ */
114
+ const SELF = "project-state-derivation.ts";
115
+ const TEXTLIKE = /\.(ts|tsx|js|jsx|mjs|cjs|py|rb|go|rs|sh|bash|zsh|json|ya?ml|toml|mk)$/;
116
+
117
+ function walk(dir: string, root: string, acc: { files: string[] }, depth = 0): void {
118
+ if (depth > 8) return;
119
+ let entries;
120
+ try {
121
+ entries = readdirSync(dir, { withFileTypes: true });
122
+ } catch {
123
+ return;
124
+ }
125
+ for (const e of entries) {
126
+ if (SKIP_DIRS.has(e.name)) continue;
127
+ const p = join(dir, e.name);
128
+ if (e.isDirectory()) walk(p, root, acc, depth + 1);
129
+ else if (TEXTLIKE.test(e.name) && e.name !== SELF) acc.files.push(p);
130
+ }
131
+ }
132
+
133
+ /**
134
+ * Read the project and say whether anything in it consumes
135
+ * `project-state.json`.
136
+ *
137
+ * One binding, so there is one thing to mutate and one answer. A second
138
+ * notion of "does this project generate it" would agree on every tree anyone
139
+ * has and diverge on the one that matters
140
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
141
+ */
142
+ export function projectStateDerivation(root: string): DerivationReading {
143
+ const acc = { files: [] as string[] };
144
+ for (const d of SEARCH_DIRS) {
145
+ const full = join(root, d);
146
+ if (existsSync(full)) walk(full, root, acc);
147
+ }
148
+ for (const f of SEARCH_FILES) {
149
+ const full = join(root, f);
150
+ try {
151
+ if (existsSync(full) && statSync(full).isFile()) acc.files.push(full);
152
+ } catch {
153
+ /* unreadable is not present */
154
+ }
155
+ }
156
+
157
+ const evidence: string[] = [];
158
+ let filesScanned = 0;
159
+ let bytesScanned = 0;
160
+ for (const f of acc.files) {
161
+ let text: string;
162
+ try {
163
+ text = readFileSync(f, "utf-8");
164
+ } catch {
165
+ continue;
166
+ }
167
+ filesScanned++;
168
+ bytesScanned += text.length;
169
+ // BOTH names, not either. A generator reads the JSON and writes the
170
+ // Markdown, and that is the claim being made; a file that merely mentions
171
+ // `project-state.json` — a doc lint, a gitignore check, a path constant —
172
+ // is not one. The direction of a loose predicate matters here: a false
173
+ // GENERATOR_FOUND is the reading that re-authorises destroying the file.
174
+ if (text.includes("project-state.json") && text.includes("PROJECT-STATE.md")) {
175
+ evidence.push(f.startsWith(root) ? f.slice(root.length).replace(/^[/\\]/, "") : f);
176
+ }
177
+ }
178
+
179
+ if (filesScanned === 0 || bytesScanned === 0) {
180
+ return {
181
+ verdict: "UNMEASURED",
182
+ evidence: [],
183
+ filesScanned,
184
+ bytesScanned,
185
+ unmeasuredReason:
186
+ filesScanned === 0
187
+ ? "no source file in this project could be read, so nothing was searched for a " +
188
+ "generator — which is not the same fact as there being none (#781)"
189
+ : `${filesScanned} file(s) were walked and none had any content, so the search ` +
190
+ "read nothing (#781)",
191
+ };
192
+ }
193
+
194
+ return {
195
+ verdict: evidence.length > 0 ? "GENERATOR_FOUND" : "NO_GENERATOR",
196
+ evidence: evidence.sort(),
197
+ filesScanned,
198
+ bytesScanned,
199
+ unmeasuredReason: null,
200
+ };
201
+ }
202
+
203
+ /**
204
+ * The `what` column of `key-files.md`'s PROJECT-STATE.md row.
205
+ *
206
+ * One binding for the three sentences, so the two generators cannot drift —
207
+ * #781's SC-2 is exactly that: a fix applied to one hardcoded copy leaves the
208
+ * other.
209
+ */
210
+ export function projectStateKeyFileNote(reading: DerivationReading): string {
211
+ switch (reading.verdict) {
212
+ case "GENERATOR_FOUND":
213
+ return PROJECT_STATE_DERIVED;
214
+ case "NO_GENERATOR":
215
+ return PROJECT_STATE_UNDERIVED;
216
+ default:
217
+ return PROJECT_STATE_UNMEASURED;
218
+ }
219
+ }
@@ -0,0 +1,258 @@
1
+ /**
2
+ * Where `ProjectStateSync` is allowed to run a generator — and everywhere it
3
+ * is not (#1001).
4
+ *
5
+ * ## The defect this exists to close
6
+ *
7
+ * The hook took a `project-state.json` path out of a tool call, stripped the
8
+ * filename, and ran `scripts/update-project-state.ts` from whatever was left:
9
+ *
10
+ * const projectRoot = filePath.replace(/\/project-state\.json$/, "");
11
+ * const script = join(projectRoot, "scripts", "update-project-state.ts");
12
+ * if (!existsSync(script)) …decline…
13
+ * execFileSync("bun", [script, "--skip-tests"], { cwd: projectRoot });
14
+ *
15
+ * `projectRoot` is wherever the tool call pointed. Anything able to write two
16
+ * files — `<anywhere>/project-state.json` and
17
+ * `<anywhere>/scripts/update-project-state.ts` — got code execution as the
18
+ * user, on the next `Write` or `Edit`, in every session on this machine.
19
+ *
20
+ * **It is a permission-gate bypass, and that is the part that matters.**
21
+ * `Bash` is gated far more tightly than `Write`. The agent never runs a
22
+ * command; the hook runs it on the agent's behalf, with the agent's choice of
23
+ * directory. #971/#999 converted the spawn from a shell string to an argv,
24
+ * which closed metacharacter injection and left this untouched — the hook's
25
+ * own header says so: *"`existsSync(script)` above is a bar, not a wall — it
26
+ * only requires the payload to be a real directory, and /tmp is writable."*
27
+ *
28
+ * ## The cheapest wrong fix, named so it cannot be mistaken for this one
29
+ *
30
+ * *"Allow anything under `$HOME/Projects`."* It satisfies the symptom, it is
31
+ * a prefix test, and it is **a new list of trusted paths** — a fourth
32
+ * position declaring something this repo already decides elsewhere. It also
33
+ * does not work: a planted root inside the prefix passes it. `AC-4` is that
34
+ * input, and it is red against that fix.
35
+ *
36
+ * The cheapest wrong fix for the SECOND round is different and more
37
+ * tempting: *"also `realpath` the leaf."* It closes the symlinked-directory
38
+ * hole completely, reads like a security fix in a diff, and leaves the
39
+ * forged repository exactly as open as it was — a forgery's generator is a
40
+ * perfectly ordinary file. `AC-14` is the input it does not survive.
41
+ *
42
+ * ## What is checked instead, and why it delegates
43
+ *
44
+ * **The generator may only run at the root of a real git repository, and it
45
+ * must be a TRACKED file of that repository.** Neither is a list; both are
46
+ * questions something else already answers — `lib/paths.ts:repoRootFrom`
47
+ * resolves `--git-common-dir` and `realpathSync`es the result so callers can
48
+ * compare stable strings, and `git ls-files --error-unmatch` decides
49
+ * membership. No second definition of "trusted root" is declared here.
50
+ *
51
+ * ### Why the repo-root test alone was not enough
52
+ *
53
+ * The first version of this module shipped with only the root test, and its
54
+ * limits note claimed an attacker needed "to create a directory AND run
55
+ * `git init`". That is false, and measured false on this machine:
56
+ *
57
+ * mkdir -p $D/.git/objects $D/.git/refs/heads $D/scripts
58
+ * printf 'ref: refs/heads/main\n' > $D/.git/HEAD
59
+ * git -C $D rev-parse --show-toplevel → $D
60
+ * git -C $D rev-parse --git-common-dir → .git
61
+ *
62
+ * Three `mkdir`s and a 24-byte file, every one of them reachable with
63
+ * `Write` — the exact primitive this issue exists to contain. "Any writable
64
+ * directory" became "any writable directory plus three mkdirs", which is not
65
+ * a narrowing, and saying it was is worse than the gap: a reader checking
66
+ * the limits would have stopped there.
67
+ *
68
+ * The tracked test refuses it, because **the barrier is `.git/index`** — a
69
+ * binary file with a trailing checksum, not something a text write produces.
70
+ * It also asks the better question: *is this generator part of a project*
71
+ * rather than *is there a `.git` directory here*. `AC-14` is the forgery and
72
+ * `AC-15` is an untracked file dropped into a REAL repository, which is what
73
+ * an attacker gets from any checkout on the machine.
74
+ *
75
+ * ### Both sides must be resolved, and this machine is why
76
+ *
77
+ * The obvious spelling of the anchor is wrong:
78
+ *
79
+ * if (claimedRoot !== repoRootFrom(claimedRoot)) decline // WRONG
80
+ *
81
+ * `repoRootFrom` realpaths its answer and the claimed path has not been
82
+ * realpathed, so the two can never agree through a symlink. Measured:
83
+ * `/Users/jhorn/Projects/pai-harness` is a symlink to
84
+ * `/Users/jhorn/Projects/rungate`, and the live `project-state.json` is
85
+ * written through the former. That spelling **refuses the only real caller
86
+ * there is**, silently, as a security improvement. `AC-3` is that input.
87
+ *
88
+ * ### The whole path is resolved, not the leaf
89
+ *
90
+ * `lstat` on the last component sees a link AT the leaf and is blind to one
91
+ * above it: a `scripts` directory symlinked anywhere, with an ordinary file
92
+ * at the end of it, reports no link at all. `projectRoot` is already
93
+ * resolved, so comparing `realpathSync(script)` against the expected path
94
+ * catches a link at ANY depth. `AC-16` is that input, and it asserts the
95
+ * leaf-level `lstat` reads false on it so the arm cannot quietly become a
96
+ * duplicate of `AC-7`.
97
+ *
98
+ * ### A linked worktree is NOT the root of its repository
99
+ *
100
+ * `repoRootFrom` resolves `--git-common-dir`, so from a linked worktree it
101
+ * returns the MAIN checkout. A worktree therefore reads as `not-repo-root`
102
+ * and the generator does not run there. That is a behaviour change and it is
103
+ * deliberate: `PROJECT-STATE.md` is DA-owned and an agent in a worktree must
104
+ * never write it (#296), which #910's SC-3 raised as an open question while
105
+ * the hook was registered on `Write` **and** `Edit` and taking the other
106
+ * answer by default. The outcome is recorded distinctly so the decision is
107
+ * visible in the evidence rather than buried in a refusal count.
108
+ *
109
+ * ## WHAT THIS DOES NOT COVER
110
+ *
111
+ * - **A repository whose CONFIG is hostile.** `repoRootFrom` shells out to
112
+ * `git` in the candidate directory before the tracked-file test can run,
113
+ * and that call is not isolated. `rev-parse --git-common-dir` neither
114
+ * refreshes the index nor fires a hook, so `core.fsmonitor` and
115
+ * `core.hooksPath` do not execute on it — but that is a property of the
116
+ * subcommand, not a boundary. Isolating `repoRootFrom` itself is the right
117
+ * fix and is not done here: `test/harness-root.test.ts` stages
118
+ * `lib/paths.ts` into a scratch directory, so an import added to it fails
119
+ * to load there (`.claude/rules/self-referential-tests.md`, Tier 1).
120
+ * - **A real project someone else controls.** Tracked means part of a
121
+ * project, not part of YOUR project. An attacker who can commit to a
122
+ * repository on this machine can change what the generator does, which is
123
+ * the next item and not a smaller problem.
124
+ * - **A generator that is a regular file with hostile contents.** Confining
125
+ * WHERE is not reviewing WHAT.
126
+ * - **A race between the checks and the spawn.** Everything here resolves
127
+ * paths once; a component swapped for a symlink afterwards is not seen.
128
+ *
129
+ * Issue: #1001. Refs #971, #999, #910, #296.
130
+ */
131
+
132
+ import { spawnSync } from "child_process";
133
+ import { realpathSync, statSync } from "fs";
134
+ import { isAbsolute, join } from "path";
135
+ import { repoRootFrom } from "./paths";
136
+ import { gitIsolatedArgs, gitIsolatedEnv } from "./git-isolation";
137
+
138
+ /** The generator this hook runs, relative to a project root. */
139
+ export const GENERATOR_RELPATH = join("scripts", "update-project-state.ts");
140
+
141
+ export type ProjectStateTarget =
142
+ | { ok: true; projectRoot: string; script: string }
143
+ /**
144
+ * `outcome` is the string the hook records. Every refusal has one: a
145
+ * decline and a hook that never ran are otherwise the same observation,
146
+ * which is #910.
147
+ */
148
+ | { ok: false; outcome: string; detail: Record<string, unknown> };
149
+
150
+ /**
151
+ * Resolve a `project-state.json` path to the generator that may run for it.
152
+ *
153
+ * Pure apart from the filesystem reads it is about, and separate from the
154
+ * hook so every refusal has an input that reaches it — a guard that only the
155
+ * hook can exercise is a guard whose ordering nothing can test.
156
+ */
157
+ export function projectStateTarget(filePath: string): ProjectStateTarget {
158
+ const claimed = filePath.replace(/\/project-state\.json$/, "");
159
+ const detail: Record<string, unknown> = { filePath, claimedRoot: claimed };
160
+
161
+ // Resolve the CLAIMED side too. Without this the comparison below is a
162
+ // string match between a resolved and an unresolved path, which disagrees
163
+ // through any symlink — including the one the real caller arrives through.
164
+ let projectRoot: string;
165
+ try {
166
+ projectRoot = realpathSync(claimed);
167
+ } catch (e) {
168
+ return { ok: false, outcome: "declined-unresolvable-root", detail: { ...detail, error: (e as Error).message } };
169
+ }
170
+ detail.projectRoot = projectRoot;
171
+
172
+ const repoRoot = repoRootFrom(projectRoot);
173
+ if (repoRoot === null) {
174
+ // No repository at all: the planted-directory case this issue is about.
175
+ return { ok: false, outcome: "declined-outside-repo", detail };
176
+ }
177
+ if (repoRoot !== projectRoot) {
178
+ // A subdirectory, or a LINKED WORKTREE — `--git-common-dir` resolves to
179
+ // the main checkout from inside one. Recorded distinctly because of the
180
+ // #296 interaction; `repoRoot` in the detail tells the two apart.
181
+ return { ok: false, outcome: "declined-not-repo-root", detail: { ...detail, repoRoot } };
182
+ }
183
+
184
+ const script = join(projectRoot, GENERATOR_RELPATH);
185
+ // INVARIANT, not a guard. `realpathSync` returns an absolute path and
186
+ // `join` keeps it absolute, so `script` can never be read as a flag by the
187
+ // spawned `bun`. Stated because the pre-fix code had no such guarantee —
188
+ // a `file_path` of `-rf/project-state.json` built the argv
189
+ // `-rf/scripts/update-project-state.ts`, which `bun` parses as options.
190
+ // Asserted rather than branched on: a condition no input can satisfy is
191
+ // not a check (`.claude/rules/checks-must-be-able-to-fail.md`), and
192
+ // pretending otherwise would hide which mechanism actually closes this.
193
+ if (!isAbsolute(script)) {
194
+ throw new Error(`projectStateTarget produced a relative generator path: ${script}`);
195
+ }
196
+
197
+ // Resolve the WHOLE path, not the leaf. `lstat` on the last component is
198
+ // blind to a symlinked INTERMEDIATE: `scripts` may be a link to anywhere
199
+ // with a perfectly ordinary file at the end of it, and `lstat` reports no
200
+ // link. `projectRoot` is already resolved, so any disagreement here is a
201
+ // link at some depth below it.
202
+ let realScript: string;
203
+ try {
204
+ realScript = realpathSync(script);
205
+ } catch {
206
+ return { ok: false, outcome: "declined-no-generator", detail: { ...detail, script } };
207
+ }
208
+ if (realScript !== script) {
209
+ return {
210
+ ok: false,
211
+ outcome: "declined-symlinked-generator",
212
+ detail: { ...detail, script, resolved: realScript },
213
+ };
214
+ }
215
+ if (!statSync(realScript).isFile()) {
216
+ return { ok: false, outcome: "declined-no-generator", detail: { ...detail, script } };
217
+ }
218
+
219
+ if (!trackedInRepo(projectRoot, GENERATOR_RELPATH)) {
220
+ // THE ANCHOR. A `.git` directory is three `mkdir`s and a 24-byte `HEAD`
221
+ // away from any `Write`; a TRACKED file is not.
222
+ //
223
+ // LAST, so that every check above it stays reachable. Tracking is the
224
+ // strongest test here, and putting it first would make the symlink
225
+ // branches unreachable — git does not descend a symlinked directory, so
226
+ // a link would be refused as untracked and the branch that exists to
227
+ // name it could never be taken (`.claude/rules/checks-must-be-able-to-fail.md`).
228
+ // Order changes which refusal is RECORDED, never whether one happens:
229
+ // nothing is spawned until all of them pass.
230
+ return { ok: false, outcome: "declined-untracked-generator", detail: { ...detail, script } };
231
+ }
232
+
233
+ return { ok: true, projectRoot, script };
234
+ }
235
+
236
+ /**
237
+ * Is `relPath` a tracked file of the repository at `root`?
238
+ *
239
+ * `ls-files --error-unmatch` rather than a filesystem test, because the
240
+ * question is *is this part of a project* and only git can answer it. The
241
+ * barrier is the INDEX: `.git/index` is a binary file carrying a trailing
242
+ * checksum, so the three-`mkdir`s forgery that satisfies `rev-parse` has no
243
+ * index at all and this refuses it. Committed content raises the bar again,
244
+ * but the index alone is already past what writing text files can reach.
245
+ *
246
+ * ISOLATED, because this runs `git` in a directory the caller chose and git
247
+ * executes that repository's config — `lib/git-isolation.ts`. `--` so a
248
+ * relative path can never be read as a revision or a flag.
249
+ */
250
+ function trackedInRepo(root: string, relPath: string): boolean {
251
+ const r = spawnSync("git", gitIsolatedArgs(["-C", root, "ls-files", "--error-unmatch", "--", relPath]), {
252
+ encoding: "utf-8",
253
+ timeout: 5000,
254
+ stdio: ["ignore", "ignore", "ignore"],
255
+ env: gitIsolatedEnv(),
256
+ });
257
+ return r.status === 0;
258
+ }