rungate 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/hooks/ActionVerificationGate.hook.ts +96 -0
  2. package/hooks/AgentBriefGuard.hook.ts +38 -0
  3. package/hooks/AgentVerdictCapture.hook.ts +87 -0
  4. package/hooks/AutoVerifyGate.hook.ts +79 -0
  5. package/hooks/BashToolGuard.hook.ts +65 -0
  6. package/hooks/BashWriteGuard.hook.ts +60 -0
  7. package/hooks/CommitEnforcement.hook.ts +130 -0
  8. package/hooks/DocHygiene.hook.ts +148 -0
  9. package/hooks/GateEnforcement.hook.ts +58 -0
  10. package/hooks/GateResultProtection.hook.ts +69 -0
  11. package/hooks/HarnessAFKGate.hook.ts +85 -0
  12. package/hooks/HookCurrency.hook.ts +99 -0
  13. package/hooks/IssueCloseGuard.hook.ts +149 -0
  14. package/hooks/MergeGuard.hook.ts +58 -0
  15. package/hooks/PostCompact.hook.ts +60 -0
  16. package/hooks/ProjectStateSync.hook.ts +103 -0
  17. package/hooks/SkillGuard.hook.ts +69 -0
  18. package/hooks/SpecConformityTrigger.hook.ts +43 -0
  19. package/hooks/SpecSCGuard.hook.ts +123 -0
  20. package/hooks/StaleTTLCleanup.hook.ts +141 -0
  21. package/hooks/TaskCompleted.hook.ts +51 -0
  22. package/hooks/TeamInit.hook.ts +85 -0
  23. package/hooks/TestSuiteGuard.hook.ts +70 -0
  24. package/hooks/TestSuiteRelease.hook.ts +85 -0
  25. package/hooks/TopLevelCdGuard.hook.ts +108 -0
  26. package/hooks/VerifyPhaseLock.hook.ts +84 -0
  27. package/hooks/WorkflowStateGuard.hook.ts +40 -0
  28. package/hooks/lib/agent-config.json +9 -0
  29. package/hooks/lib/agentDetection.ts +201 -0
  30. package/hooks/lib/comment-template.ts +86 -0
  31. package/hooks/lib/findWorkflow.ts +101 -0
  32. package/hooks/lib/parseStdin.ts +37 -0
  33. package/hooks/lib/paths.ts +111 -0
  34. package/hooks/lib/utils.ts +338 -0
  35. package/lib/affected-tests.ts +427 -0
  36. package/lib/agent-audit.ts +2 -3
  37. package/lib/agent-worktree.ts +287 -0
  38. package/lib/agents-md-sections.ts +81 -16
  39. package/lib/bash-write-guard.ts +373 -0
  40. package/lib/behavioral-cache.ts +150 -2
  41. package/lib/branch-cleanup.ts +279 -7
  42. package/lib/branch-protection.ts +790 -0
  43. package/lib/brief-ac-alignment.ts +104 -0
  44. package/lib/brief-references.ts +205 -0
  45. package/lib/bun-version.ts +93 -14
  46. package/lib/check-remedy.ts +140 -0
  47. package/lib/ci-checkout.ts +17 -0
  48. package/lib/ci-history-depth.ts +159 -0
  49. package/lib/ci-setup-step.ts +96 -0
  50. package/lib/claude-code-action.ts +85 -0
  51. package/lib/claude-tool-vocabulary.ts +188 -0
  52. package/lib/cli-commands.ts +15 -0
  53. package/lib/commit-sha.ts +42 -0
  54. package/lib/commit-subject.ts +90 -0
  55. package/lib/compliance-report.ts +377 -45
  56. package/lib/compliance.ts +191 -17
  57. package/lib/config-loader.ts +39 -1
  58. package/lib/config-trackable.ts +400 -0
  59. package/lib/conformity.ts +1087 -100
  60. package/lib/containment.ts +238 -0
  61. package/lib/content-hash.ts +24 -0
  62. package/lib/create-sc.ts +249 -16
  63. package/lib/dev-liveness.ts +180 -0
  64. package/lib/discovery-branch-points.ts +432 -0
  65. package/lib/discovery-stability.ts +481 -0
  66. package/lib/distribution-currency.ts +236 -0
  67. package/lib/doc-routing.ts +157 -0
  68. package/lib/evidence-prevalidator.ts +224 -2
  69. package/lib/evidence-satisfiability.ts +534 -12
  70. package/lib/failure-intake.ts +323 -0
  71. package/lib/fallow-availability.ts +157 -0
  72. package/lib/fs-write-capabilities.ts +232 -0
  73. package/lib/gate-enforcement.ts +222 -28
  74. package/lib/gate-names.ts +72 -0
  75. package/lib/gate-result-protection.ts +427 -0
  76. package/lib/gate-run-split.ts +147 -0
  77. package/lib/generators/agents-md.ts +140 -32
  78. package/lib/git-isolation.ts +140 -0
  79. package/lib/github.ts +15 -0
  80. package/lib/google-auth-action.ts +93 -0
  81. package/lib/harness-project.ts +48 -0
  82. package/lib/harness-provenance.ts +255 -0
  83. package/lib/hook-evidence.ts +235 -0
  84. package/lib/hook-scopes.ts +386 -0
  85. package/lib/hook-target-tree.ts +398 -0
  86. package/lib/hook-trees.ts +447 -0
  87. package/lib/intake-sources.ts +380 -0
  88. package/lib/js-top-level-code.ts +78 -10
  89. package/lib/junit-checks.ts +52 -0
  90. package/lib/late-env-spawn.ts +331 -0
  91. package/lib/launch-base.ts +376 -0
  92. package/lib/line-citation.ts +372 -0
  93. package/lib/orphan-reaper.ts +468 -0
  94. package/lib/parity-binding.ts +205 -0
  95. package/lib/paths.ts +96 -3
  96. package/lib/per-test-timeouts.ts +219 -0
  97. package/lib/phase2-decomposition.ts +1 -1
  98. package/lib/plan-coverage.ts +151 -0
  99. package/lib/prior-branch.ts +201 -8
  100. package/lib/process-table.ts +146 -0
  101. package/lib/project-state-derivation.ts +219 -0
  102. package/lib/project-state-root.ts +258 -0
  103. package/lib/published-artifact.ts +669 -0
  104. package/lib/readdir-sorted.ts +45 -0
  105. package/lib/review-execution-reading.ts +206 -0
  106. package/lib/review-tool-agreement.ts +433 -0
  107. package/lib/rule-promotion.ts +234 -0
  108. package/lib/rule-retirement.ts +525 -0
  109. package/lib/run-branch.ts +612 -0
  110. package/lib/rungate-schema.ts +19 -0
  111. package/lib/runner-home.ts +274 -0
  112. package/lib/sc-id-cross-tree.ts +103 -15
  113. package/lib/sc-ids.ts +121 -13
  114. package/lib/sc-reservations.ts +289 -0
  115. package/lib/scaffold/ai-review-findings.ts +409 -0
  116. package/lib/scaffold/ai-review-step.ts +5406 -64
  117. package/lib/scaffold/defaults.ts +82 -1
  118. package/lib/scaffold/managed-workflow.ts +587 -192
  119. package/lib/scaffold/owned-files.ts +152 -45
  120. package/lib/scaffold/pre-push-hook.ts +49 -5
  121. package/lib/scaffold/steps.ts +1836 -275
  122. package/lib/scaffold/workflow-census.ts +217 -0
  123. package/lib/scaffold/workflow-drift.ts +217 -0
  124. package/lib/scaffold/write-steps.ts +4 -0
  125. package/lib/scan-budget.ts +247 -0
  126. package/lib/scanner.ts +43 -51
  127. package/lib/scratch-roots.ts +50 -5
  128. package/lib/screenshot-discovery.ts +121 -0
  129. package/lib/screenshot-upload.ts +41 -1
  130. package/lib/secret-patterns.ts +511 -8
  131. package/lib/security-verdict.ts +1 -1
  132. package/lib/shell-path-interpolation.ts +594 -0
  133. package/lib/ship-mode.ts +219 -0
  134. package/lib/source-slice.ts +294 -0
  135. package/lib/stale-cleanup.ts +37 -3
  136. package/lib/suite-flake.ts +278 -0
  137. package/lib/suite-measurement.ts +23 -4
  138. package/lib/suite-run-reading.ts +241 -1
  139. package/lib/suite-timeout-margin.ts +193 -0
  140. package/lib/test-case-bodies.ts +883 -0
  141. package/lib/test-case-deletion.ts +653 -0
  142. package/lib/test-census.ts +97 -29
  143. package/lib/test-command-positions.ts +274 -0
  144. package/lib/test-suite-lock.ts +159 -16
  145. package/lib/text-dependents.ts +875 -0
  146. package/lib/tool-probe.ts +31 -9
  147. package/lib/top-level-cd.ts +393 -0
  148. package/lib/tree-entries.ts +89 -0
  149. package/lib/ts-ast.ts +200 -0
  150. package/lib/walk-test-files.ts +97 -0
  151. package/lib/workflow-actions.ts +263 -0
  152. package/lib/workflow-security.ts +29 -0
  153. package/lib/workflow-taint.ts +732 -0
  154. package/lib/worktree-cleanup.ts +65 -38
  155. package/lib/worktree-collect.ts +177 -5
  156. package/lib/worktree-repo.ts +68 -3
  157. package/package.json +4 -1
  158. package/scripts/ai-review-findings.ts +45 -0
  159. package/scripts/check-installed-hook-currency.ts +825 -0
  160. package/scripts/create-sc.ts +21 -1
  161. package/scripts/extract-constraints.ts +107 -7
  162. package/scripts/generate-code-map.ts +23 -30
  163. package/scripts/scaffold-project.ts +8 -1
  164. package/scripts/sync-sc-status.ts +77 -16
@@ -0,0 +1,376 @@
1
+ /**
2
+ * Is the session's cwd a safe place to cut agent worktrees from? (#644)
3
+ *
4
+ * ## The thing this does NOT do, stated first
5
+ *
6
+ * It does not derive the worktree base. `workflows/ship.js:1235` has pinned
7
+ * `opts.cwd = PROJECT_ROOT` for every worktree-isolated spawn since
8
+ * `804b9a43` on 2026-09-23, and there is no spawn path that bypasses it —
9
+ * all six roles resolve to `isolation: 'worktree'` and no call site sets it
10
+ * explicitly. **Rungate already passes the explicit argument.**
11
+ *
12
+ * It does not hold. `isolation: 'worktree'` is resolved by the agent
13
+ * runtime against the SESSION'S cwd, and `opts.cwd` is applied to the
14
+ * spawned agent afterwards. Run `wf_5e3ed885-98c` on 2026-10-14 put a
15
+ * remediation Marcus in a worktree of one consumer's repository while
16
+ * working an issue in another — three weeks after the pin landed. The
17
+ * repositories are named on #218; they are deliberately not named here,
18
+ * because the harness must not name its consumers (#304, SC-A1).
19
+ *
20
+ * So the one thing rungate controls is whether the run STARTS. This refuses
21
+ * at launch, before any agent is spawned, when the session's cwd would
22
+ * produce a worktree the run does not want.
23
+ *
24
+ * ## Two failures, one input
25
+ *
26
+ * Both of #644's failures are the same fact wearing different clothes, and
27
+ * the silent one is worse:
28
+ *
29
+ * 1. cwd is not a git repository at all. The runtime says *"not in a git
30
+ * repository and no WorktreeCreate hooks are configured… to use
31
+ * worktree isolation with other VCS systems"*, which is about the
32
+ * session's cwd while naming neither it nor the session. A reader
33
+ * configures hooks they do not need and still has the bug.
34
+ * 2. cwd IS a git repository, in another project or on another branch.
35
+ * Nothing fails. The run cuts its worktrees from somebody else's work
36
+ * and succeeds onto the wrong base, found later by the PR behaving
37
+ * oddly.
38
+ *
39
+ * A check that covers only the first is the cheapest wrong fix for this
40
+ * issue, named in #644's own body: it fixes the symptom that announces
41
+ * itself and leaves the one that does not.
42
+ *
43
+ * ## Why a refusal and not a repair
44
+ *
45
+ * `process.chdir()` would be the repair, and it is not available to a
46
+ * workflow script, nor would it be right: the session's cwd is shared with
47
+ * the operator and with whatever they do next. A run that quietly moved it
48
+ * would be a side effect outside its own worktrees, which is #640's
49
+ * complaint about the shared primary, arriving from the other direction.
50
+ *
51
+ * ## Three readings, not two
52
+ *
53
+ * `SAME_REPO` is not the same as `SAME_CHECKOUT`. The shared primary sits on
54
+ * `rungate/run-<issue>` for the life of a run (#640) — the same repository
55
+ * as `projectRoot`, a different working tree, on a branch belonging to
56
+ * another issue. Collapsing that into "same repo, fine" is the precondition
57
+ * blindness in `.claude/rules/checks-must-be-able-to-fail.md`: every natural
58
+ * fixture runs from the right directory, so the branch where cwd and
59
+ * `projectRoot` are the same repo and disagree anyway is outside the
60
+ * battery's reach entirely.
61
+ */
62
+ import { spawnSync } from "child_process";
63
+ import { resolve } from "path";
64
+
65
+ import { canonicalRoot } from "./paths";
66
+ import { readWorktreeRemote, redactRemote, repoSlug } from "./worktree-repo";
67
+
68
+ /**
69
+ * A path or branch name, quoted and redacted.
70
+ *
71
+ * `worktreeDiskIdentity` in the sibling module redacts everything it
72
+ * interpolates, and a control that does not is a parity gap a reader has
73
+ * to notice. Paths and branch names are not usually credential-bearing —
74
+ * but they come from the environment, a worktree can live under a
75
+ * directory named after one, and `redactRemote` leaves an ordinary path
76
+ * untouched, so the check costs nothing and the omission costs a leak
77
+ * nobody is looking for.
78
+ */
79
+ const safe = (v: unknown) => JSON.stringify(redactRemote(String(v)));
80
+
81
+ /** Every refusal and every pass travels through one of these. */
82
+ export type LaunchBaseReading =
83
+ /** cwd and projectRoot are the same working tree. The only clean answer. */
84
+ | { reading: "SAME_CHECKOUT"; cwd: string; projectRoot: string }
85
+ /** cwd is a git repository, and not one git can resolve a toplevel for. */
86
+ | { reading: "CWD_NOT_A_REPO"; cwd: string; projectRoot: string; refusal: string }
87
+ /** cwd is a repository in a DIFFERENT project. Failure 2, loud version. */
88
+ | { reading: "DIFFERENT_REPO"; cwd: string; projectRoot: string; refusal: string }
89
+ /** Same repository, different working tree or branch. Failure 2, quiet version. */
90
+ | { reading: "DIFFERENT_CHECKOUT"; cwd: string; projectRoot: string; refusal: string }
91
+ /**
92
+ * A root is reached through a symlink, so it has two spellings (#1129).
93
+ *
94
+ * This reading exists because its absence was the gap. `--show-toplevel`
95
+ * RESOLVES symlinks, so both spellings of one directory produce one
96
+ * answer and the comparison below reads `SAME_CHECKOUT` — the one gate
97
+ * that sees both the session and the root is structurally blind to the
98
+ * difference, and then hands the unresolved string onward to a workflow
99
+ * that can only compare strings. "The roots are canonical" and "the roots
100
+ * are two spellings that happen to resolve alike" were indistinguishable
101
+ * in this output; they no longer are.
102
+ */
103
+ | { reading: "NON_CANONICAL_ROOT"; cwd: string; projectRoot: string; refusal: string }
104
+ /**
105
+ * Something could not be read. NOT a pass: a reading that could not be
106
+ * taken is indistinguishable from a clean one, and only one of them is
107
+ * reportable (`.claude/rules/config-access.md`).
108
+ */
109
+ | { reading: "UNMEASURED"; cwd: string; projectRoot: string; refusal: string };
110
+
111
+ /** `git -C <dir> rev-parse --show-toplevel`, or `null`. */
112
+ function toplevel(dir: string): string | null {
113
+ if (typeof dir !== "string" || !dir.trim()) return null;
114
+ const got = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
115
+ timeout: 10_000,
116
+ encoding: "utf-8",
117
+ });
118
+ if (got.error || got.status !== 0) return null;
119
+ const out = String(got.stdout || "").trim();
120
+ return out === "" ? null : out;
121
+ }
122
+
123
+ /** `git -C <dir> rev-parse --abbrev-ref HEAD`, or `null`. */
124
+ function branchOf(dir: string): string | null {
125
+ const got = spawnSync("git", ["-C", dir, "rev-parse", "--abbrev-ref", "HEAD"], {
126
+ timeout: 10_000,
127
+ encoding: "utf-8",
128
+ });
129
+ if (got.error || got.status !== 0) return null;
130
+ const out = String(got.stdout || "").trim();
131
+ return out === "" ? null : out;
132
+ }
133
+
134
+ /**
135
+ * The reading for one launch.
136
+ *
137
+ * ONE discriminator, `reading`. Every other field is a projection of the
138
+ * same two probes taken here and nowhere else, so no two of them can
139
+ * disagree — and a caller that only wants a boolean derives it with
140
+ * `launchBaseRefusal` rather than re-asking git.
141
+ *
142
+ * The comparison is by RESOLVED TOPLEVEL first and by remote slug second,
143
+ * in that order and for a reason. Two worktrees of one repository have
144
+ * different toplevels and the same remote; two clones of one repository
145
+ * have different toplevels and the same remote as well. Only the toplevel
146
+ * separates "the tree the run was handed" from "another tree of the same
147
+ * project", and that distinction is the whole of failure 2's quiet half.
148
+ */
149
+ /**
150
+ * The roots that are not their own canonical spelling, as a reading (#1129).
151
+ *
152
+ * Returns `null` when every root given resolves to itself — which is the
153
+ * only state the rest of `launchBaseReading` can reason about, because
154
+ * every comparison downstream of it is between strings.
155
+ *
156
+ * `harnessRoot` is optional and skipped when absent rather than treated as
157
+ * canonical. `harnessRootFor()` in `lib/paths.ts` canonicalises the roots it
158
+ * produces, but it is not the only producer — a hand-typed `--harness-root`
159
+ * never goes through it, which is why this takes the value rather than
160
+ * trusting the producer.
161
+ *
162
+ * An unresolvable root is UNMEASURED and refuses. It is deliberately NOT
163
+ * folded into NON_CANONICAL_ROOT: "this root has two names" is fixed by
164
+ * relaunching with the other one, and "this root does not exist" is not, so
165
+ * collapsing them would hand the operator a remedy that cannot work.
166
+ */
167
+ function nonCanonicalRoots(roots: {
168
+ projectRoot: string;
169
+ harnessRoot?: string;
170
+ }): { reading: "NON_CANONICAL_ROOT" | "UNMEASURED"; refusal: string } | null {
171
+ for (const [name, given] of Object.entries(roots)) {
172
+ if (typeof given !== "string" || !given.trim()) continue;
173
+ let canonical: string;
174
+ try {
175
+ canonical = canonicalRoot(given);
176
+ } catch (e: any) {
177
+ return {
178
+ reading: "UNMEASURED",
179
+ refusal:
180
+ `${name} ${safe(given)} cannot be resolved to a real path (${redactRemote(String(e?.message || e))}). ` +
181
+ "Whether this run's containment checks would agree with the paths git reports is therefore " +
182
+ "unknown, and unknown is not canonical — it is refused rather than passed through unresolved (#1129)",
183
+ };
184
+ }
185
+ if (canonical === given) continue;
186
+
187
+ // TWO conditions, and they are reported apart because only one of them
188
+ // is about symlinks. Comparing `canonical` straight back against the raw
189
+ // string folds them together, and then a root spelled `…/rungate/` is
190
+ // refused with "which is a symlink to …/rungate" — a false statement
191
+ // about the operator's disk, offering as a remedy the path they just
192
+ // typed with one character removed. Found by the AI review of PR #1150.
193
+ //
194
+ // Both still refuse. A non-normalised root breaks the comparison in
195
+ // ship.js just as surely: it builds `${root}/.claude/worktrees/` and a
196
+ // trailing slash makes that a doubled separator no git-reported path
197
+ // matches. The verdict is the same; the sentence is not.
198
+ const normalised = resolve(given);
199
+ const why =
200
+ canonical !== normalised
201
+ ? `it is a symlink to ${safe(canonical)} — one directory under two names`
202
+ : `it is not a normalised path; it names ${safe(canonical)} with redundant or relative segments`;
203
+
204
+ return {
205
+ reading: "NON_CANONICAL_ROOT",
206
+ refusal:
207
+ `${name} was given as ${safe(given)}, and ${why}. ` +
208
+ "`git rev-parse --show-toplevel` resolves symlinks and every path git reports is canonical, " +
209
+ "but `collectDestination` in workflows/ship.js compares roots as STRINGS and cannot resolve " +
210
+ "anything: the sandbox has no filesystem (#69). So this run would refuse its own agent " +
211
+ `worktrees, and the refusal would read as "this directory is not yours". Relaunch with ` +
212
+ `${name} set to ${safe(canonical)}`,
213
+ };
214
+ }
215
+ return null;
216
+ }
217
+
218
+ export function launchBaseReading(
219
+ cwd: string,
220
+ projectRoot: string,
221
+ harnessRoot?: string,
222
+ ): LaunchBaseReading {
223
+ // RAW for probing, REDACTED for reporting, and the two are never mixed
224
+ // up: `git -C` must receive the real path, and a redacted one would send
225
+ // the probe to a directory that does not exist — which resolves to
226
+ // CWD_NOT_A_REPO and reads exactly like the finding this module exists
227
+ // to report. Everything returned is built from `here`; everything handed
228
+ // to git comes from `raw`.
229
+ const raw = {
230
+ cwd: String(cwd ?? ""),
231
+ projectRoot: String(projectRoot ?? ""),
232
+ // Absent stays absent rather than becoming "": the canonicality check
233
+ // skips a root it was not given, and an empty string would be
234
+ // indistinguishable from a caller that passed one and got it wrong.
235
+ harnessRoot: harnessRoot === undefined ? undefined : String(harnessRoot ?? ""),
236
+ };
237
+ // Redacted ON THE READING, not at each call site. `check-launch-base.ts`
238
+ // serialises the whole object, and a caller that had to remember to
239
+ // redact is a control one caller will forget.
240
+ const here = { cwd: redactRemote(raw.cwd), projectRoot: redactRemote(raw.projectRoot) };
241
+
242
+ if (!raw.projectRoot.trim()) {
243
+ return {
244
+ ...here,
245
+ reading: "UNMEASURED",
246
+ refusal:
247
+ "no projectRoot was given, so there is nothing for the launching session's working directory to be " +
248
+ "compared against — a run that cannot state which tree it is for cannot check that it is in it",
249
+ };
250
+ }
251
+
252
+ const rootTop = toplevel(raw.projectRoot);
253
+ if (rootTop === null) {
254
+ return {
255
+ ...here,
256
+ reading: "UNMEASURED",
257
+ refusal:
258
+ `projectRoot ${safe(here.projectRoot)} is not a git repository git can resolve. ` +
259
+ "This is the run's own argument and not the launching session's working directory, so it is reported " +
260
+ "as unmeasured rather than as the cwd problem this check exists for",
261
+ };
262
+ }
263
+
264
+ const cwdTop = toplevel(raw.cwd);
265
+ if (cwdTop === null) {
266
+ // Failure 1, said about the right input. The runtime's own message for
267
+ // this state names neither the directory nor the fact that it is the
268
+ // SESSION's, and recommends VCS hook configuration that is irrelevant.
269
+ return {
270
+ ...here,
271
+ reading: "CWD_NOT_A_REPO",
272
+ refusal:
273
+ `the launching session's working directory ${safe(here.cwd)} is not a git repository. ` +
274
+ `projectRoot ${safe(here.projectRoot)} is one, and is correct — but agent worktrees ` +
275
+ "are cut by the runtime from the SESSION's directory, not from projectRoot, so this run " +
276
+ "would die at the first isolated spawn. This is not a VCS-configuration problem and " +
277
+ "WorktreeCreate hooks will not fix it: cd into projectRoot and relaunch",
278
+ };
279
+ }
280
+
281
+ if (cwdTop === rootTop) {
282
+ // #1129 refines THIS answer and only this one, and the position is the
283
+ // whole point. `--show-toplevel` resolves symlinks, so two spellings of
284
+ // one directory arrive here as one toplevel and the comparison above
285
+ // cannot tell them apart — the unresolved string then travels on to
286
+ // `collectDestination`, which compares it by `startsWith` against paths
287
+ // git has already resolved.
288
+ //
289
+ // It is NOT checked earlier. A symlinked root is the mildest thing that
290
+ // can be wrong here: CWD_NOT_A_REPO, DIFFERENT_REPO and
291
+ // DIFFERENT_CHECKOUT are all worse and all more urgent, and a
292
+ // canonicality check placed above them MASKS them. Measured — on macOS
293
+ // `tmpdir()` is `/var/folders/...`, itself a symlink to `/private/var`,
294
+ // so every fixture built under it is non-canonical by accident: the
295
+ // early placement turned 15 cases in this module's own suite into
296
+ // NON_CANONICAL_ROOT, on macOS only, while Linux CI (`tmpdir()` is
297
+ // `/tmp`, not a link) stayed green. A check that changes which defect
298
+ // you are told about, per platform, is worse than the defect.
299
+ const nonCanonical = nonCanonicalRoots({
300
+ projectRoot: raw.projectRoot,
301
+ harnessRoot: raw.harnessRoot,
302
+ });
303
+ if (nonCanonical) return { ...here, ...nonCanonical };
304
+ return { ...here, reading: "SAME_CHECKOUT" };
305
+ }
306
+
307
+ // Different trees. Which KIND of different decides what the operator does
308
+ // next, so the two are never collapsed.
309
+ const cwdRemote = readWorktreeRemote(cwdTop);
310
+ const rootRemote = readWorktreeRemote(rootTop);
311
+ const cwdSlug = repoSlug(cwdRemote.url);
312
+ const rootSlug = repoSlug(rootRemote.url);
313
+
314
+ if (cwdSlug === null || rootSlug === null) {
315
+ // A tree with no resolvable origin is not a tree we can clear. Refusing
316
+ // rather than passing: the guard must not go inert for exactly the
317
+ // misconfigured checkout most likely to need it (#218's reasoning).
318
+ return {
319
+ ...here,
320
+ reading: "UNMEASURED",
321
+ refusal:
322
+ `the launching session's working directory ${safe(cwdTop)} and projectRoot ` +
323
+ `${safe(rootTop)} are different trees, and at least one of them has no origin ` +
324
+ `remote this can resolve (cwd: ${cwdSlug ?? redactRemote(String(cwdRemote.error ?? cwdRemote.url))}, ` +
325
+ `projectRoot: ${rootSlug ?? redactRemote(String(rootRemote.error ?? rootRemote.url))}). ` +
326
+ "Whether they are the same project is therefore unknown, and unknown is not clean",
327
+ };
328
+ }
329
+
330
+ if (cwdSlug !== rootSlug) {
331
+ return {
332
+ ...here,
333
+ reading: "DIFFERENT_REPO",
334
+ refusal:
335
+ `the launching session's working directory ${safe(cwdTop)} is a checkout of ${cwdSlug}, but ` +
336
+ `this run targets ${rootSlug} at ${safe(rootTop)}. Agent worktrees are cut by the ` +
337
+ "runtime from the SESSION's directory, so this run would do its work in the wrong repository " +
338
+ "and succeed — which is how run wf_5e3ed885-98c put a remediation agent in a checkout of " +
339
+ "one consumer's repository while working an issue in another (#218). cd into projectRoot and relaunch",
340
+ };
341
+ }
342
+
343
+ // Same project, different working tree. The quiet one: nothing fails, and
344
+ // the run lands on whatever branch that tree happens to be parked on.
345
+ const cwdBranch = branchOf(cwdTop);
346
+ const rootBranch = branchOf(rootTop);
347
+ return {
348
+ ...here,
349
+ reading: "DIFFERENT_CHECKOUT",
350
+ refusal:
351
+ `the launching session's working directory ${safe(cwdTop)} and projectRoot ` +
352
+ `${safe(rootTop)} are two different working trees of the same repository ` +
353
+ `(${rootSlug}) — cwd is on ${cwdBranch ?? "an unreadable branch"} and projectRoot is on ` +
354
+ `${rootBranch ?? "an unreadable branch"}. Agent worktrees are cut by the runtime from the ` +
355
+ "SESSION's directory, so this run would cut from a tree it was not handed, and nothing would " +
356
+ "fail. A shared primary parked on another issue's run branch is exactly this state (#640). " +
357
+ "cd into projectRoot and relaunch",
358
+ };
359
+ }
360
+
361
+ /**
362
+ * The refusal string for a launch, or `null` when there is nothing to say.
363
+ *
364
+ * Derived from `launchBaseReading` and never from a second probe, so the
365
+ * boolean and the reading cannot disagree. `SAME_CHECKOUT` is the only
366
+ * reading that clears: UNMEASURED refuses with the rest, because a check
367
+ * that could not be run is not a check that passed.
368
+ */
369
+ export function launchBaseRefusal(
370
+ cwd: string,
371
+ projectRoot: string,
372
+ harnessRoot?: string,
373
+ ): string | null {
374
+ const reading = launchBaseReading(cwd, projectRoot, harnessRoot);
375
+ return reading.reading === "SAME_CHECKOUT" ? null : reading.refusal;
376
+ }