@feigi/fleet-ctl 3.109.1 → 3.110.1

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.
@@ -13,8 +13,8 @@ against your `bash` cwd, which they share no `cwd` parameter with. Give them
13
13
  the absolute worktree path on every call, mutation-probe copies included.**
14
14
  The main checkout is the parent of `git rev-parse --path-format=absolute
15
15
  --git-common-dir`. A `member-write-guard` refusal means the path hit the
16
- main checkout — for `bash`, a missing or main-checkout `cwd` — so re-issue
17
- it absolute, under your worktree.
16
+ main checkout or the Install root — for `bash`, a missing or main-checkout
17
+ `cwd` — so re-issue it absolute, under your worktree.
18
18
 
19
19
  **Every factual claim your diff restates needs a settling command run
20
20
  against the tree first** — the issue body is a lead, never a citation.
@@ -27,9 +27,9 @@ substitutes it for you.
27
27
  So: prefix every `edit` and `read` path with an absolute path — the
28
28
  worktree `<abs-path>` for repo files, `<scratch>/impl-<N>/` for scratch —
29
29
  never a bare relative one, and never `plugin/scripts/foo.mjs` on its own.
30
- A `member-write-guard` refusal means the path hit the main checkout — for
31
- `bash`, a missing or main-checkout `cwd` — so re-issue it absolute, under
32
- your worktree.
30
+ A `member-write-guard` refusal means the path hit the main checkout or the
31
+ Install root — for `bash`, a missing or main-checkout `cwd` — so re-issue it
32
+ absolute, under your worktree.
33
33
 
34
34
  Here is the ticket's distilled brief, already read once at the Pull —
35
35
  title, plus whichever of the `## Agent Brief` comment or the issue body
@@ -27,9 +27,9 @@ substitutes it for you.
27
27
  So: prefix every `edit` and `read` path with an absolute path — the
28
28
  worktree `<abs-path>` for repo files, `<scratch>/impl-<N>/` for scratch —
29
29
  never a bare relative one, and never `plugin/scripts/foo.mjs` on its own.
30
- A `member-write-guard` refusal means the path hit the main checkout — for
31
- `bash`, a missing or main-checkout `cwd` — so re-issue it absolute, under
32
- your worktree.
30
+ A `member-write-guard` refusal means the path hit the main checkout or the
31
+ Install root — for `bash`, a missing or main-checkout `cwd` — so re-issue it
32
+ absolute, under your worktree.
33
33
 
34
34
  Here is the ticket's distilled brief, already read once at the Pull —
35
35
  title, plus whichever of the `## Agent Brief` comment or the issue body
@@ -27,9 +27,9 @@ substitutes it for you.
27
27
  So: prefix every `edit` and `read` path with an absolute path — the
28
28
  worktree `<abs-path>` for repo files, `<scratch>/impl-<N>/` for scratch —
29
29
  never a bare relative one, and never `plugin/scripts/foo.mjs` on its own.
30
- A `member-write-guard` refusal means the path hit the main checkout — for
31
- `bash`, a missing or main-checkout `cwd` — so re-issue it absolute, under
32
- your worktree.
30
+ A `member-write-guard` refusal means the path hit the main checkout or the
31
+ Install root — for `bash`, a missing or main-checkout `cwd` — so re-issue it
32
+ absolute, under your worktree.
33
33
 
34
34
  Here is the ticket's distilled brief, already read once at the Pull —
35
35
  title, plus whichever of the `## Agent Brief` comment or the issue body
@@ -27,9 +27,9 @@ substitutes it for you.
27
27
  So: prefix every `edit` and `read` path with an absolute path — the
28
28
  worktree `<abs-path>` for repo files, `<scratch>/impl-<N>/` for scratch —
29
29
  never a bare relative one, and never `plugin/scripts/foo.mjs` on its own.
30
- A `member-write-guard` refusal means the path hit the main checkout — for
31
- `bash`, a missing or main-checkout `cwd` — so re-issue it absolute, under
32
- your worktree.
30
+ A `member-write-guard` refusal means the path hit the main checkout or the
31
+ Install root — for `bash`, a missing or main-checkout `cwd` — so re-issue it
32
+ absolute, under your worktree.
33
33
 
34
34
  Here is the ticket's distilled brief, already read once at the Pull —
35
35
  title, plus whichever of the `## Agent Brief` comment or the issue body
@@ -27,9 +27,9 @@ substitutes it for you.
27
27
  So: prefix every `edit` and `read` path with an absolute path — the
28
28
  worktree `<abs-path>` for repo files, `<scratch>/impl-<N>/` for scratch —
29
29
  never a bare relative one, and never `plugin/scripts/foo.mjs` on its own.
30
- A `member-write-guard` refusal means the path hit the main checkout — for
31
- `bash`, a missing or main-checkout `cwd` — so re-issue it absolute, under
32
- your worktree.
30
+ A `member-write-guard` refusal means the path hit the main checkout or the
31
+ Install root — for `bash`, a missing or main-checkout `cwd` — so re-issue it
32
+ absolute, under your worktree.
33
33
 
34
34
  Here is the ticket's distilled brief, already read once at the Pull —
35
35
  title, plus whichever of the `## Agent Brief` comment or the issue body
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.109.1",
3
+ "version": "3.110.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -5,10 +5,9 @@
5
5
  # the Install root — the realpath of
6
6
  # `~/.omp/plugins/node_modules/@feigi/fleet-ctl`, the tree fleet-run executes
7
7
  # and omp loads the runbooks from — and every member can write to that tree.
8
- # member-write-guard.mjs refuses a `write`/`edit`/`ast_edit` inside the MAIN
9
- # checkout only, which is the Install root only when that checkout is linked;
10
- # a `bash` or `eval` write lands either way, and under a package install
11
- # nothing refuses any of them. Worktree isolation
8
+ # member-write-guard.mjs refuses a `write`/`edit`/`ast_edit` inside the Install
9
+ # root, whatever the install kind, but a `bash` or `eval` write lands there
10
+ # anyway and nothing refuses it. Worktree isolation
12
11
  # and `./agent-test` port derivation protect members from each other; neither
13
12
  # protects the tree the controller measures from. Measured: a member edited two
14
13
  # files in the main checkout instead of its worktree while the CI monitor was
@@ -39,7 +39,7 @@
39
39
  // cause instead (see `headMove`).
40
40
  //
41
41
  // THE PROTECTED SET is the non-ignored paths of the main checkout — what the
42
- // member-write-guard protects — and its HEAD. `.fleet/`, `.worktrees/` and
42
+ // member-write-guard protects there — and its HEAD. `.fleet/`, `.worktrees/` and
43
43
  // `.agent-brain/` are gitignored in a fleet repo, so run state, members'
44
44
  // worktrees and agent-brain's cache never appear in porcelain and never trip
45
45
  // this.
@@ -26,7 +26,7 @@
26
26
  // A top-level (`kind: "main"`) session is never guarded: that is the
27
27
  // controller, whose own writes into its checkout are its job.
28
28
  //
29
- // TWO RULES.
29
+ // THREE RULES.
30
30
  // - Path writers (`write`, `edit`, `ast_edit`), for everyone guarded: refuse
31
31
  // when a target resolves inside the main checkout and `git check-ignore`
32
32
  // says it is not ignored. `.worktrees/`, `.fleet/` and `.agent-brain/` are
@@ -34,6 +34,14 @@
34
34
  // stay writable, and what is protected is exactly what the main
35
35
  // checkout's `git status` would show dirty (main-checkout.mjs watches the
36
36
  // same set, and the checkout's HEAD besides).
37
+ // - The Install root, for the same path writers and the same agents: refuse
38
+ // when a target resolves inside the live Install root — the realpath of
39
+ // `~/.omp/plugins/node_modules/@feigi/fleet-ctl`, the installed plugin
40
+ // fleet-run executes scripts from and omp loads the runbooks from — the
41
+ // root itself included. No gitignore exemption: nothing under it is a
42
+ // member's to write. It holds whichever repository the session runs in,
43
+ // or none, and for every install kind; under a linked checkout the
44
+ // Install root is that checkout's `plugin/`.
37
45
  // - `bash` cwd, for every `fleet-implementer-<cell>` (ledger-grammar.mjs's
38
46
  // `CELL_DEF`), and for a fix-applier's own id (`fix-pr-<n>`) directly,
39
47
  // since its definition, `fleet-fix-applier`, is no implementer cell and
@@ -45,17 +53,28 @@
45
53
  // `git worktree add` from there, and children follow ad-hoc briefs — so
46
54
  // none of them gets this rule.
47
55
  // Never a rewrite: a refusal names the resolved path and tells the member to
48
- // re-issue it absolute under its worktree. Relative READS and `eval` are not
49
- // guarded here; main-checkout.mjs's dirty detection covers `eval`.
56
+ // re-issue it absolute under its worktree — save one for an Install root that
57
+ // does not resolve, which no path the member picks clears, so it says the
58
+ // package entry needs repair instead. Relative READS and `eval` are not
59
+ // guarded here; main-checkout.mjs's dirty detection covers `eval`. A `bash` or
60
+ // `eval` write into the Install root lands, by design: the `bash` cwd rule is
61
+ // the main checkout's only, since members read from the Install root with a
62
+ // `cwd` there, and instruments.sh's re-check is what detects such a write.
50
63
  //
51
- // WHEN IT CANNOT DECIDE. A cwd outside any git repository is allowed — there
52
- // is no main checkout to protect. A git that fails while resolving the main
53
- // checkout or answering `check-ignore` BLOCKS, naming the failure: a guard
54
- // that fails open on "could not look" protects nothing. omp fails closed the
55
- // same way on a handler that throws or times out.
64
+ // WHEN IT CANNOT DECIDE. A cwd outside any git repository is allowed by the
65
+ // main-checkout rules — there is no main checkout to protect. No package entry
66
+ // at all turns the Install-root rule off. A git that fails while resolving
67
+ // the main checkout or answering `check-ignore`, a package entry that exists
68
+ // but does not resolve (a dangling link, any other lstat or realpath error),
69
+ // and a path-writer target that cannot be canonicalised (EACCES, ELOOP,
70
+ // ENOTDIR), BLOCK, naming the failure: a guard that fails open on "could not
71
+ // look" protects nothing. omp fails closed the same way on a handler that
72
+ // throws or times out.
56
73
  //
57
74
  // `decide()` is the whole policy and touches nothing: the handler resolves the
58
- // main checkout, then hands it and a `check-ignore` probe in. The main
75
+ // main checkout and, for a path writer, the Install root, then hands them and
76
+ // a `check-ignore` probe in. The Install root is resolved on every such call,
77
+ // so a relink or reinstall mid-run is followed. The main
59
78
  // checkout is the parent of `git rev-parse --git-common-dir` (git-env.mjs's
60
79
  // `mainCheckoutDirFromGitCommonDir`) — the work tree, which a symlinked `.git`
61
80
  // does not move, never git-env.mjs's store rule — and never `--show-toplevel`,
@@ -65,7 +84,7 @@
65
84
  // Zero deps: node builtins and sibling scripts only.
66
85
 
67
86
  import { spawn } from "node:child_process";
68
- import { realpathSync } from "node:fs";
87
+ import { lstatSync, realpathSync } from "node:fs";
69
88
  import { homedir } from "node:os";
70
89
  import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
71
90
  import { fileURLToPath } from "node:url";
@@ -78,6 +97,10 @@ const FIX_APPLIER_ID = /^fix-pr-\d+(-[a-z])?$/;
78
97
  const PATH_WRITERS = new Set(["write", "edit", "ast_edit"]);
79
98
  const GIT_TIMEOUT_MS = 10_000;
80
99
  const REISSUE = "Re-issue it with an absolute path under your worktree `.worktrees/<n>-<slug>/`.";
100
+ /** What a refusal for an unresolvable Install root says instead of REISSUE: no path the member picks clears it. */
101
+ const REPAIR = "No re-issue clears this, whatever path it names: the package entry needs repair (a relink or a reinstall), so report this refusal rather than retry it.";
102
+ /** omp's package entry for this plugin, under the home directory: its realpath is the Install root. */
103
+ const INSTALL_ENTRY = [".omp", "plugins", "node_modules", "@feigi", "fleet-ctl"];
81
104
 
82
105
  /** Whether `decide()` could refuse this call — the handler's cheap gate before it spends a git call. Never throws: it runs for every tool call in every session. */
83
106
  function applies(agent, toolName) {
@@ -131,10 +154,12 @@ function targets(toolName, input) {
131
154
  // A raw path as omp's own resolver reads it (path-utils.ts `expandPath`): a
132
155
  // stray `:` or `@` ahead of an absolute or `~` path is dropped, `file://` is a
133
156
  // path, `~` is home. Any other `scheme://` is an internal URL (`local://`,
134
- // `xd://`, `agent://`) and names no file in any checkout: null. An ast_edit
135
- // glob needs no cutting: its literal spelling lies inside or outside the main
136
- // checkout exactly as the directory it scans from does, and `check-ignore`
137
- // reads it as a plain pathname.
157
+ // `xd://`, `agent://`) and names no file in any checkout: null. For the
158
+ // main-checkout rule an ast_edit glob needs no cutting: its literal spelling
159
+ // lies inside the main checkout exactly when the directory it scans from
160
+ // does, and `check-ignore` reads it as a plain pathname. A scan from above a
161
+ // root reaches into it, though, so the Install-root rule also reads the
162
+ // directory an ast_edit scans from (`scanRoot`).
138
163
  function fsPath(raw, cwd) {
139
164
  let p = raw;
140
165
  if (/^:(?=[/\\~]|\.\.?[/\\])/.test(p)) p = p.slice(1);
@@ -150,28 +175,81 @@ function fsPath(raw, cwd) {
150
175
 
151
176
  const within = (root, p) => p === root || p.startsWith(root.endsWith(sep) ? root : root + sep);
152
177
 
178
+ /** The directory an ast_edit target scans from: its path up to the first segment holding a glob character, or the whole path when none does. */
179
+ function scanRoot(abs) {
180
+ const segs = abs.split(sep);
181
+ const i = segs.findIndex((s) => /[*?[\]{}]/.test(s));
182
+ return i === -1 ? abs : segs.slice(0, i).join(sep) || sep;
183
+ }
184
+
185
+ /** A refusal for a root `decide()` was handed as neither a usable path nor the "no root" null, ending with what the member is to do about it. */
186
+ function unusable(toolName, what, root, remedy = REISSUE) {
187
+ if (root instanceof Error) {
188
+ return { block: true, reason: `member-write-guard: refused ${toolName} — could not resolve ${what} (${root.message}), and a guard that cannot look does not let the call through. ${remedy}` };
189
+ }
190
+ if (typeof root !== "string" || root === "") {
191
+ return { block: true, reason: `member-write-guard: refused ${toolName} — ${what} resolved to an unusable value, and a guard that cannot look does not let the call through. ${remedy}` };
192
+ }
193
+ return undefined;
194
+ }
195
+
153
196
  /**
154
197
  * The policy: `undefined` to let the call run, `{block: true, reason}` to
155
198
  * refuse it. Pure — every effect is passed in:
156
199
  * - `mainRoot`: the main checkout's absolute path, `null` when `cwd` is in
157
- * no git repository (allow), or an `Error` when git could not say (block);
200
+ * no git repository (the main-checkout rule is off), or an `Error` when
201
+ * git could not say (block);
202
+ * - `installRoot`: the Install root's realpath, `null` when there is no
203
+ * package entry (the Install-root rule is off), or an `Error` naming the
204
+ * entry when it exists but does not resolve (block). Read for path
205
+ * writers only;
158
206
  * - `isIgnored(absPath)`: resolves true/false from `git check-ignore`, and
159
207
  * rejects when git fails (block);
160
- * - `canonical(absPath)`: the symlink-free spelling of a path that may not
161
- * exist yet, so `/var/…` and `/private/var/…` compare equal. Identity by
162
- * default; the handler passes the real one.
208
+ * - `canonical(absPath)`: the symlink-free, on-disk spelling of a path that
209
+ * may not exist yet, so `/var/…` and `/private/var/…` compare equal, and
210
+ * so do two letter cases of one path on a case-insensitive filesystem.
211
+ * Identity by default; the handler passes the real one. A target it
212
+ * throws on is refused, naming the error.
163
213
  * `cwd` is the session cwd relative paths resolve against, `path.resolve(cwd, p)`.
164
214
  */
165
- export async function decide({ toolName, input, cwd, agent, mainRoot, isIgnored, canonical = (p) => p }) {
215
+ export async function decide({ toolName, input, cwd, agent, mainRoot, installRoot = null, isIgnored, canonical = (p) => p }) {
166
216
  if (!applies(agent, toolName)) return undefined;
167
- if (mainRoot === null) return undefined;
168
- if (mainRoot instanceof Error) {
169
- return { block: true, reason: `member-write-guard: refused ${toolName} — could not resolve the main checkout from ${cwd} (${mainRoot.message}), and a guard that cannot look does not let the call through. ${REISSUE}` };
170
- }
171
- if (typeof mainRoot !== "string" || mainRoot === "") {
172
- return { block: true, reason: `member-write-guard: refused ${toolName} — the main checkout resolved to an unusable value, and a guard that cannot look does not let the call through. ${REISSUE}` };
217
+ let located;
218
+ // Each target: `at` its canonical spelling, and for an ast_edit `scan` the
219
+ // canonical directory it scans from; `error` when canonicalising threw.
220
+ const writes = () => (located ??= targets(toolName, input).flatMap((raw) => {
221
+ const abs = fsPath(raw, cwd);
222
+ if (abs === null) return [];
223
+ try {
224
+ return [{ raw, at: canonical(abs), scan: toolName === "ast_edit" ? canonical(scanRoot(abs)) : null }];
225
+ } catch (error) {
226
+ return [{ raw, at: abs, error }];
227
+ }
228
+ }));
229
+ const said = ({ raw, at }) => (isAbsolute(raw) ? at : `${at} ("${raw}" resolved against the session cwd ${cwd})`);
230
+ const unresolved = (t) => ({ block: true, reason: `member-write-guard: refused ${toolName} to ${said(t)} — could not resolve it (${t.error?.code ?? t.error?.message ?? t.error}), and a guard that cannot look does not let the call through. ${REISSUE}` });
231
+
232
+ // The Install root, for path writers: whatever repository the session runs
233
+ // in, or none, and with no gitignore exemption — nothing under it is a
234
+ // member's to write.
235
+ if (toolName !== "bash" && installRoot !== null) {
236
+ const cannot = unusable(toolName, "the Install root", installRoot, REPAIR);
237
+ if (cannot) return cannot;
238
+ for (const t of writes()) {
239
+ if (t.error) return unresolved(t);
240
+ if (within(installRoot, t.at)) {
241
+ return { block: true, reason: `member-write-guard: refused ${toolName} to ${said(t)} — it is inside the Install root ${installRoot}, the installed plugin the fleet executes, and nothing under it is a member's to write. ${REISSUE}` };
242
+ }
243
+ if (t.scan !== null && within(t.scan, installRoot)) {
244
+ return { block: true, reason: `member-write-guard: refused ${toolName} over ${said(t)} — it scans from ${t.scan}, which holds the Install root ${installRoot}, the installed plugin the fleet executes, and nothing under it is a member's to write. ${REISSUE}` };
245
+ }
246
+ }
173
247
  }
174
248
 
249
+ if (mainRoot === null) return undefined;
250
+ const cannot = unusable(toolName, mainRoot instanceof Error ? `the main checkout from ${cwd}` : "the main checkout", mainRoot);
251
+ if (cannot) return cannot;
252
+
175
253
  if (toolName === "bash") {
176
254
  const asked = typeof input?.cwd === "string" && input.cwd.trim() !== "" ? input.cwd : cwd;
177
255
  const at = canonical(fsPath(asked, cwd) ?? resolve(cwd, asked));
@@ -181,20 +259,17 @@ export async function decide({ toolName, input, cwd, agent, mainRoot, isIgnored,
181
259
  return undefined;
182
260
  }
183
261
 
184
- for (const raw of targets(toolName, input)) {
185
- const abs = fsPath(raw, cwd);
186
- if (abs === null) continue;
187
- const at = canonical(abs);
188
- if (!within(mainRoot, at)) continue;
189
- const said = isAbsolute(raw) ? at : `${at} ("${raw}" resolved against the session cwd ${cwd})`;
262
+ for (const t of writes()) {
263
+ if (t.error) return unresolved(t);
264
+ if (!within(mainRoot, t.at)) continue;
190
265
  let ignored;
191
266
  try {
192
- ignored = await isIgnored(at);
267
+ ignored = await isIgnored(t.at);
193
268
  } catch (e) {
194
- return { block: true, reason: `member-write-guard: refused ${toolName} to ${said} — could not tell whether it is gitignored (${e?.message ?? e}), and a guard that cannot look does not let the call through. ${REISSUE}` };
269
+ return { block: true, reason: `member-write-guard: refused ${toolName} to ${said(t)} — could not tell whether it is gitignored (${e?.message ?? e}), and a guard that cannot look does not let the call through. ${REISSUE}` };
195
270
  }
196
271
  if (!ignored) {
197
- return { block: true, reason: `member-write-guard: refused ${toolName} to ${said} — it is inside the main checkout ${mainRoot} and not gitignored. ${REISSUE}` };
272
+ return { block: true, reason: `member-write-guard: refused ${toolName} to ${said(t)} — it is inside the main checkout ${mainRoot} and not gitignored. ${REISSUE}` };
198
273
  }
199
274
  }
200
275
  return undefined;
@@ -238,8 +313,10 @@ async function resolveMainRoot(cwd) {
238
313
  // by the dead path rather than "(or any …": that is a broken repo, and blocks.
239
314
  if (!r.error && r.status !== 0 && /not a git repository \(or any/i.test(r.stderr)) return null;
240
315
  if (r.error || r.status !== 0) return new Error(failure(r, "git rev-parse --git-common-dir"));
241
- return mainCheckoutDirFromGitCommonDir(r.stdout, cwd, { canonicalise: true })
242
- ?? new Error("git rev-parse --git-common-dir answered nothing");
316
+ const dir = mainCheckoutDirFromGitCommonDir(r.stdout, cwd, { canonicalise: true });
317
+ if (dir === null) return new Error("git rev-parse --git-common-dir answered nothing");
318
+ // In the on-disk letter case canonicalPath gives every target compared against it.
319
+ try { return realpathSync.native(dir); } catch { return dir; }
243
320
  }
244
321
 
245
322
  /** `git check-ignore` from `mainRoot`: true ignored, false not; rejects on anything else. */
@@ -250,10 +327,38 @@ async function checkIgnored(mainRoot, absPath) {
250
327
  throw new Error(failure(r, "git check-ignore"));
251
328
  }
252
329
 
253
- /** The symlink-free spelling of `p`, whose tail need not exist yet. */
330
+ // The Install root, resolved the way fleet-run's Resolver resolves it — lstat,
331
+ // then realpath, of the package entry under the home directory — on every
332
+ // guarded path-writer call, so a relink or reinstall mid-run is followed. Not
333
+ // this module's own location: that names the copy omp loaded at session start.
334
+ // The realpath is the native one, which answers in the on-disk letter case,
335
+ // as canonicalPath does for every target compared against it.
336
+ /** The live Install root: its realpath, `null` when there is no package entry, or an `Error` naming the entry. */
337
+ function resolveInstallRoot() {
338
+ const entry = join(homedir(), ...INSTALL_ENTRY);
339
+ let isLink;
340
+ try {
341
+ isLink = lstatSync(entry).isSymbolicLink();
342
+ } catch (e) {
343
+ if (e?.code === "ENOENT") return null;
344
+ return new Error(`cannot read the omp plugin entry ${entry}: ${e?.code ?? e?.message ?? e}`);
345
+ }
346
+ try {
347
+ return realpathSync.native(entry);
348
+ } catch (e) {
349
+ const code = e?.code ?? e?.message ?? e;
350
+ return new Error(isLink ? `the omp plugin link ${entry} is dangling: ${code}` : `cannot resolve the omp plugin entry ${entry}: ${code}`);
351
+ }
352
+ }
353
+
354
+ // The native realpath, not the JS one: on a case-insensitive filesystem
355
+ // (macOS's default) the JS realpath keeps the caller's letter case, so
356
+ // `…/@FEIGI/fleet-ctl` would name the Install root's files while comparing
357
+ // unequal to it.
358
+ /** The symlink-free, on-disk spelling of `p`, whose tail need not exist yet. */
254
359
  function canonicalPath(p) {
255
360
  try {
256
- return realpathSync(p);
361
+ return realpathSync.native(p);
257
362
  } catch (e) {
258
363
  if (e?.code !== "ENOENT") throw e;
259
364
  const parent = dirname(p);
@@ -274,6 +379,7 @@ export default function memberWriteGuard(pi) {
274
379
  cwd,
275
380
  agent,
276
381
  mainRoot,
382
+ installRoot: PATH_WRITERS.has(event.toolName) ? resolveInstallRoot() : null,
277
383
  isIgnored: (p) => checkIgnored(mainRoot, p),
278
384
  canonical: canonicalPath,
279
385
  });
@@ -56,7 +56,19 @@
56
56
  // whose model changed is judged afresh once its new generation reaches MIN_N
57
57
  // merged PRs. Each older generation prints on its own line beside the newest,
58
58
  // with no verdict and no interval.
59
+ //
60
+ // THE GUARD FILE keeps each cell's whole entry as the report computed it —
61
+ // `n` (its `n_merged`, which readers key on) beside every figure above and its
62
+ // older generations nested under `older`, never as extra `cells[]` entries,
63
+ // since a reader keys entries by cell — and, per generation, three counts
64
+ // that never enter its figures: `by_hand`, the counted merged Pulls whose
65
+ // Ruling's note is not one `tier-outcomes.mjs append` derives (`isDerivedNote`);
66
+ // `no_ruling`, the Pulls whose PR merged on GitHub with no Ruling, which stay
67
+ // not merged; and `pending`, the Pulls whose PR is still open or not in the
68
+ // list. Beside `min_n` it records `trip_points`, the floor's margin, and
69
+ // `tsv_blobs`: the git blob id of each TSV it read, by the path it read it at.
59
70
 
71
+ import { createHash } from "node:crypto";
60
72
  import { execFileSync } from "node:child_process";
61
73
  import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
62
74
  import { dirname, join } from "node:path";
@@ -66,7 +78,7 @@ import { gitEnv } from "./git-env.mjs";
66
78
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
67
79
  import { isCLI } from "./is-cli.mjs";
68
80
  import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
69
- import { AttributionError, attribute, bootUnit, bootstrapDiffCI, parseFeatures, tally, underFloor } from "./pull-attribution.mjs";
81
+ import { AttributionError, TRIP_POINTS, attribute, bootUnit, bootstrapDiffCI, parseFeatures, tally, underFloor } from "./pull-attribution.mjs";
70
82
  import { RulingError, parseTierOutcomes } from "./tier-outcomes.mjs";
71
83
 
72
84
  const NAME = "pr-cost";
@@ -117,6 +129,9 @@ export function computeReport({ members, tiers, features, prs, routerTable = nul
117
129
  fail_rate: g.claims ? round(g.failed / g.claims) : null,
118
130
  mean_usd: round(meanUsd(g), 2),
119
131
  median_usd: round(median(g.pulls.filter((u) => u.merged).map((u) => u.spend)), 2),
132
+ by_hand: g.by_hand,
133
+ no_ruling: g.no_ruling,
134
+ pending: g.pending,
120
135
  router_usd: round(g.pulls.reduce((s, u) => s + routerUsd(u.pull), 0), 4),
121
136
  usd_diff_ci95: !newest || cell === BASELINE_CELL || !base ? null : bootstrapDiffCI(bootUnits(g), bootUnits(base)),
122
137
  left_out: g.left_out,
@@ -245,18 +260,27 @@ export function formatReport(report) {
245
260
  return lines.join("\n") + "\n";
246
261
  }
247
262
 
248
- export function guardFile(report, computedAt) {
263
+ // The git blob id of `bytes` — what `git hash-object` prints for a file of them.
264
+ export const blobId = (bytes) => createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex");
265
+
266
+ // `tsvBlobs` is the blob id of each TSV the guard read, keyed by path.
267
+ export function guardFile(report, computedAt, tsvBlobs = {}) {
249
268
  return {
250
269
  computed_at: computedAt,
251
270
  window_start: report.window_start,
252
271
  baseline: report.baseline,
253
- cells: report.cells.map((f) => ({ cell: f.cell, generation: f.generation, n: f.n_merged, mean_usd: f.mean_usd, fail_rate: f.fail_rate, untimed: f.untimed })),
272
+ cells: report.cells.map((f) => {
273
+ const { cell, generation, ...rest } = f;
274
+ return { cell, generation, n: f.n_merged, ...rest };
275
+ }),
254
276
  tripped: report.tripped,
255
277
  verdict: report.verdict,
256
278
  retire: report.retire,
257
- // The n the baseline and every judged cell need, so a reader prints it
258
- // rather than restating it.
279
+ // The n the baseline and every judged cell need, and the margin the fail
280
+ // leg applies, so a reader prints them rather than restating them.
259
281
  min_n: MIN_N,
282
+ trip_points: TRIP_POINTS,
283
+ tsv_blobs: Object.fromEntries(Object.entries(tsvBlobs).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
260
284
  };
261
285
  }
262
286
 
@@ -288,8 +312,14 @@ function main() {
288
312
  });
289
313
  sweep();
290
314
  stray();
291
- const read = (path, ifMissing = "") => {
292
- try { return readFileSync(path, "utf8"); }
315
+ const tsvBlobs = {};
316
+ // `blobbed` records the file's git blob id, off the bytes as read.
317
+ const read = (path, ifMissing = "", blobbed = false) => {
318
+ try {
319
+ const bytes = readFileSync(path);
320
+ if (blobbed) tsvBlobs[path] = blobId(bytes);
321
+ return bytes.toString("utf8");
322
+ }
293
323
  catch (e) { die(`cannot read ${path}: ${e.code ?? e.message}${e.code === "ENOENT" ? ifMissing : ""}`); }
294
324
  };
295
325
  const parse = (what, fn) => {
@@ -301,9 +331,9 @@ function main() {
301
331
  const featuresPath = arg("ticket-features") ?? "docs/metrics/ticket-features.tsv";
302
332
  const pricingArg = arg("pricing");
303
333
  const pricingPath = pricingArg ?? "docs/metrics/pricing.json";
304
- const members = parse(membersPath, () => parseMemberTsv(read(membersPath)));
305
- const tiers = parse(tiersPath, () => parseTierOutcomes(read(tiersPath)));
306
- const features = parse(featuresPath, () => parseFeatures(read(featuresPath, " — the router script writes it at dispatch, so there is nothing to price before it has dispatched")));
334
+ const members = parse(membersPath, () => parseMemberTsv(read(membersPath, "", true)));
335
+ const tiers = parse(tiersPath, () => parseTierOutcomes(read(tiersPath, "", true)));
336
+ const features = parse(featuresPath, () => parseFeatures(read(featuresPath, " — the router script writes it at dispatch, so there is nothing to price before it has dispatched", true)));
307
337
  // The default pricing.json is optional; one named on the command line is not.
308
338
  const pricing = pricingArg === null && !existsSync(pricingPath) ? null : parse(pricingPath, () => JSON.parse(read(pricingPath)));
309
339
  const tablePath = join(SCRIPT_DIR, "router-table.json");
@@ -338,7 +368,7 @@ function main() {
338
368
  const file = arg("out") ?? defaultGuardPath();
339
369
  try {
340
370
  mkdirSync(dirname(file), { recursive: true });
341
- writeFileSync(`${file}.tmp`, JSON.stringify(guardFile(report, new Date().toISOString()), null, 2) + "\n");
371
+ writeFileSync(`${file}.tmp`, JSON.stringify(guardFile(report, new Date().toISOString(), tsvBlobs), null, 2) + "\n");
342
372
  renameSync(`${file}.tmp`, file);
343
373
  } catch (e) {
344
374
  die(`cannot write ${file}: ${e.code ?? e.message}`);
@@ -36,6 +36,9 @@
36
36
  // MERGED: the Pull holds a Ruling and, when PR states are given, its PR is
37
37
  // MERGED. With PR states, a ruled PR that is OPEN or not in the list, or an
38
38
  // unruled Pull whose implementer opened a PR still OPEN, is pending.
39
+ // A Pull with no Ruling whose implementer's PR is MERGED, and whose PR no
40
+ // other Pull holds the Ruling of, is `noRuling`: still not merged, its status
41
+ // unchanged — a count beside the figures, not a state.
39
42
  //
40
43
  // STATUS, first that applies:
41
44
  // excluded no Admissible row among the Pull's implementer rows;
@@ -84,7 +87,7 @@ import { isDigits } from "./arg.mjs";
84
87
  import { CELL } from "./ledger-grammar.mjs";
85
88
  import { parseMemberName } from "./member-record.mjs";
86
89
  import { isImplementer } from "./member-outcomes.mjs";
87
- import { DATE, rulingFor, rulingsByTicket } from "./tier-outcomes.mjs";
90
+ import { DATE, isDerivedNote, rulingFor, rulingsByTicket } from "./tier-outcomes.mjs";
88
91
 
89
92
  // The ticket-features row, one per Pull, in this order. `objective` came last
90
93
  // and is optional on read: a file whose header lacks it reads it blank.
@@ -277,7 +280,7 @@ function numberOf(row, field, column = field) {
277
280
  /**
278
281
  * One unit per ticket-features row dated on or after `windowStart` (every dated
279
282
  * row when null), in file order: `{ pull, cell, stratum, generation, status,
280
- * merged, pr, ruling, pendingPr, claims, falseClaims, rows, spend, workS }`,
283
+ * merged, pr, ruling, pendingPr, noRuling, claims, falseClaims, rows, spend, workS }`,
281
284
  * `generation` null exactly when the Pull is excluded. `spend` is null when a
282
285
  * booked `cost` is blank, and `workS`, its work time in seconds, when a booked
283
286
  * `work_s` of a row naming no parent is. `prs` is `gh pr list`'s
@@ -342,6 +345,8 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
342
345
  const ruling = cands.reduce((a, c) => (fileOrder.get(c.ruling) > fileOrder.get(a) ? c.ruling : a), cands[0].ruling);
343
346
  ruled.set(cands.at(-1).pull, { pr, ruling, carried: false });
344
347
  }
348
+ // Every PR some Pull holds the Ruling of, carried or taken by date.
349
+ const held = new Set([...ruled.values()].map((r) => r.pr));
345
350
 
346
351
  const state = prs && new Map(prs.map((p) => [String(p.number), p.state]));
347
352
  return inWindow.map((pull) => {
@@ -350,12 +355,16 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
350
355
  const r = ruled.get(pull) ?? null;
351
356
  let merged = r !== null;
352
357
  let pendingPr = null;
358
+ let noRuling = false;
353
359
  if (state) {
354
360
  if (r) {
355
361
  const s = state.get(r.pr);
356
362
  if (s === undefined || s === "OPEN") pendingPr = r.pr;
357
363
  merged = s === "MERGED";
358
- } else pendingPr = own.find((m) => m.pr && state.get(m.pr) === "OPEN")?.pr ?? null;
364
+ } else {
365
+ pendingPr = own.find((m) => m.pr && state.get(m.pr) === "OPEN")?.pr ?? null;
366
+ noRuling = own.some((m) => m.pr && state.get(m.pr) === "MERGED" && !held.has(m.pr));
367
+ }
359
368
  }
360
369
  let claims = 0, falseClaims = 0;
361
370
  if (merged) {
@@ -384,7 +393,7 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
384
393
  else if (blank || (r && !r.carried)) status = "unpriced";
385
394
  else if (untimed) status = "untimed";
386
395
  return {
387
- pull, cell: pull.chosen_cell, stratum: stratum(pull), generation, status, merged, pr: r?.pr ?? null, ruling: r?.ruling ?? null,
396
+ pull, cell: pull.chosen_cell, stratum: stratum(pull), generation, status, merged, pr: r?.pr ?? null, ruling: r?.ruling ?? null, noRuling,
388
397
  pendingPr, claims, falseClaims, rows: booked, spend: blank ? null : spend, workS: untimed ? null : workS,
389
398
  };
390
399
  });
@@ -410,13 +419,16 @@ export function generations(units) {
410
419
 
411
420
  /**
412
421
  * Per cell, in cell-name order: `{ cell, generation, n, merged, claims, failed,
413
- * spend, workS, pulls, excluded, left_out, unpriced, untimed, pending, older }`.
422
+ * spend, workS, pulls, excluded, left_out, unpriced, untimed, pending,
423
+ * by_hand, no_ruling, older }`.
414
424
  * `generation` is the cell's newest (null when no Pull of it has one), and the
415
425
  * figures beside it are that generation's alone: `n`, `merged`, `claims`,
416
426
  * `failed`, `spend` and `workS` (work time, in seconds) over its counted
417
427
  * Pulls, `pulls` those counted units themselves in the order of `units`, then
418
- * its left-out, unpriced, untimed and pending Pull counts.
419
- * `excluded` counts the cell's excluded Pulls, which have no generation.
428
+ * its left-out, unpriced, untimed and pending Pull counts. `by_hand` counts
429
+ * those counted merged Pulls whose Ruling's note is not one `append` derives
430
+ * (`isDerivedNote`); `no_ruling` counts the generation's Pulls of any status
431
+ * whose unit is `noRuling`.
420
432
  * `older` is an array, newest first, of every other generation's figures in
421
433
  * the same shape, each carrying its `generation`. `order` is `generations()`
422
434
  * of the units that place each cell's generations; by default these same
@@ -427,7 +439,7 @@ export function tally(units, order = generations(units)) {
427
439
  // `n` is read off `pulls`, so the count and the list cannot drift apart.
428
440
  const figures = (generation) => ({
429
441
  generation, get n() { return this.pulls.length; }, merged: 0, claims: 0, failed: 0, spend: 0, workS: 0, pulls: [],
430
- left_out: 0, unpriced: 0, untimed: 0, pending: 0,
442
+ left_out: 0, unpriced: 0, untimed: 0, pending: 0, by_hand: 0, no_ruling: 0,
431
443
  });
432
444
  const cells = new Map();
433
445
  for (const u of units) {
@@ -438,8 +450,12 @@ export function tally(units, order = generations(units)) {
438
450
  }
439
451
  const g = u.generation ?? null;
440
452
  const f = c.gens.get(g) ?? c.gens.set(g, figures(g)).get(g);
453
+ if (u.noRuling) f.no_ruling++;
441
454
  if (u.status === "counted") {
442
- if (u.merged) f.merged++;
455
+ if (u.merged) {
456
+ f.merged++;
457
+ if (u.ruling && !isDerivedNote(u.ruling.note)) f.by_hand++;
458
+ }
443
459
  f.claims += u.claims;
444
460
  f.failed += u.falseClaims;
445
461
  f.spend += u.spend;
@@ -308,7 +308,8 @@ function fitPulls({ features, members, verdicts, window }) {
308
308
 
309
309
  // Per stratum and `*`, per cell, its newest generation's figures: `n` counted
310
310
  // Pulls, `merged`, $ per merged PR, minutes of work time per merged PR, false
311
- // claims over claims, fix rounds per merged PR, and its left-out, unpriced and
311
+ // claims over claims, fix rounds per merged PR, `by_hand` (the counted merged Pulls whose
312
+ // Ruling was given by hand), and its left-out, unpriced and
312
313
  // untimed Pull counts. Both per merged PR figures take every counted Pull,
313
314
  // merged or not, over the merged ones. Beside them the cell's
314
315
  // excluded Pull count, `generation` naming the newest generation's model, and
@@ -329,6 +330,7 @@ function estimate(units, order) {
329
330
  return {
330
331
  n: g.n,
331
332
  merged: g.merged,
333
+ by_hand: g.by_hand,
332
334
  claims: g.claims,
333
335
  failed: g.failed,
334
336
  usd_per_merged: g.merged ? round4(g.spend / g.merged) : null,
@@ -747,6 +747,15 @@ export function deriveRuling({ run, head, review, record }) {
747
747
  };
748
748
  }
749
749
 
750
+ // Is `note` one `append` derives — deriveRuling's opening, `review <run> at
751
+ // <head7>`, then `, record <file>: …` or `, no record: …`, with ` — <--note>`
752
+ // after it when `--note` was given — rather than typed by hand with the
753
+ // verdicts? Pure: the note alone is read, never the verdicts. A blank or
754
+ // missing note is by hand.
755
+ export function isDerivedNote(note) {
756
+ return /^review \S+ at [0-9a-fA-F]{7}, (?:no record: |record \S+: )/.test(String(note ?? ""));
757
+ }
758
+
750
759
  // PR `pr`'s first review read from scratch and tied to the ledger, then ruled
751
760
  // by deriveRuling: its Ruling plus `review`, the review's run, or `{missing}`
752
761
  // saying what is not there to read. `scratch` is `{root}` or `{unresolvable}`.
@@ -9,10 +9,10 @@ them before every gate decision.** Per-member worktrees and `./agent-test`'s por
9
9
  derivation protect members from each other; neither protects the Install root,
10
10
  the tree you run every gate probe out of and read these runbooks from. It is
11
11
  the main checkout only when that checkout is linked as the install. The
12
- `member-write-guard` extension refuses a `write`/`edit`/`ast_edit` inside the
13
- main checkout only, and a `bash` or `eval` write lands anyway; under a package
14
- install nothing prevents a write to the Install root, and this re-check is
15
- what catches one. Measured: a
12
+ `member-write-guard` extension refuses a `write`/`edit`/`ast_edit` into the
13
+ Install root, as it does into the main checkout, but a `bash` or `eval` write
14
+ into the Install root still lands, and this re-check is what catches one.
15
+ Measured: a
16
16
  member edited two files in the main checkout instead of in its worktree while
17
17
  the CI monitor was polling one of them every 120s and a live finisher was using
18
18
  it to decide a label. It caught itself; nothing in the fleet would have. That is
@@ -185,8 +185,9 @@ practice: the recipe is the absolute-path discipline above, not a placeholder
185
185
  for a `cwd` field that does not exist. The gap is now enforced rather than only
186
186
  written down: the plugin's `member-write-guard` omp extension
187
187
  refuses a fleet member's `write`/`edit`/`ast_edit` into the main checkout's
188
- non-ignored tree and an implementer's `bash` from a main-checkout cwd, and the
189
- missing field itself is requested upstream in `can1357/oh-my-pi`.
188
+ non-ignored tree or into the Install root, and an implementer's `bash` from a
189
+ main-checkout cwd, and the missing field itself is requested upstream in
190
+ `can1357/oh-my-pi`.
190
191
 
191
192
  ## `task`-dispatched members share one `eval` kernel
192
193