@feigi/fleet-ctl 3.82.4 → 3.82.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.82.4",
+  "version": "3.82.6",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/derive-testcmd.sh

@@ -21,8 +21,10 @@
 # directory git-env.mjs's resolveWorkspace() names for the repository: the
 # common git dir's parent when the common dir is named `.git` or that parent's
 # own `.git` resolves to it, otherwise the common git dir itself (a bare
-# repository, a submodule). That is the same place the
-# ledger and the heartbeat live — so a claimed worktree and a
+# repository, a submodule). Only an absent `<parent>/.git` is "not this
+# parent"; one that exists and that git refuses fails the probe, so a linked
+# worktree never re-keys the cache to the common dir. The ledger and the
+# heartbeat live in that same place — so a claimed worktree and a
 # review worktree read the one cache the main checkout holds rather than a
 # private copy each. A single JSON object:
 #
@@ -179,9 +181,18 @@ common=$(git -C "$repo" rev-parse --path-format=absolute --git-common-dir 2>&1)
 # shell rather than asked of node: the interpreter probe below must stay the
 # first node call, since its refusals are pinned in that order. A common dir
 # named `.git` belongs to its parent checkout. Otherwise the parent's `.git`,
-# a symlink or a gitfile, that resolves to the common dir makes the parent the
-# workspace. Otherwise the common dir is the workspace itself (a bare
-# repository, a submodule's git dir).
+# a symlink, a gitfile or a directory, that git resolves to the common dir
+# makes the parent the workspace. Only an absent `<parent>/.git` is "not this
+# parent": one that exists and that git refuses (a dangling or invalid gitfile,
+# an unreadable one) fails the probe, never re-keys the cache to the common dir.
+# Otherwise the common dir is the workspace itself (a bare repository, a
+# submodule's git dir). git prints the realpath for a gitfile but the path as
+# spelled for a `.git` directory, so its answer is canonicalised before the
+# compare; `$target` stays absolute, since a relative operand is answered
+# relative to the cwd. Only git's stdout is the answer: anything it writes to
+# stderr on a success would otherwise land inside the path and fail the
+# compare, re-keying the cache in silence. A refusal asks once more for the
+# reason, its stderr alone.
 real=$(cd -P "$common" 2>/dev/null && pwd -P) || real=$common
 parent=${common%/*}
 case ${real##*/} in
@@ -189,13 +200,16 @@ case ${real##*/} in
   *)
     ws=$common
     target=${real%/*}/.git
-    if [ -f "$target" ]; then
-      IFS= read -r gl < "$target" || :
-      gl=${gl#gitdir: }
-      case $gl in /*) target=$gl ;; *) target=${real%/*}/$gl ;; esac
+    if [ -e "$target" ] || [ -L "$target" ]; then
+      named=$(git rev-parse --resolve-git-dir "$target" 2>/dev/null) || {
+        gitrc=$?
+        why=$(git rev-parse --resolve-git-dir "$target" 2>&1 >/dev/null) || :
+        case $gitrc in 128) die "cannot resolve the workspace of $repo: $target — $why" ;; esac
+        unrunnable "git did not resolve $target (exit $gitrc), so the Recipe cache was not read${why:+ — $why}"
+      }
+      named=$(cd -P "$named" 2>/dev/null && pwd -P) || named=
+      if [ "$named" = "$real" ]; then ws=$parent; fi
     fi
-    named=$(cd -P "$target" 2>/dev/null && pwd -P) || named=
-    if [ "$named" = "$real" ]; then ws=$parent; fi
     ;;
 esac
 cache="$ws/.fleet/recipe.json"

package/scripts/fleet-dir.mjs

@@ -10,13 +10,16 @@
 // every worktree of one repository shares, and git-env.mjs's resolveWorkspace()
 // turns that answer into the workspace it names: the common git dir's parent
 // when the common dir is named `.git` or that parent's own `.git` resolves to
-// it, otherwise the common git dir itself. This module is the spawn around
-// that function — the scrubbed env, the bound, the join onto `.fleet/` — so a
-// new `.fleet/`-rooted file is one `fleetFile("name")` call rather than
-// another hand-spelled probe. The bound is per git child, not per call: when
-// the common git dir is not named `.git`, resolveWorkspace() runs a second
-// `rev-parse` after this module's own, with a bound of its own, so one call's
-// worst case approaches twice `timeoutMs`.
+// it, otherwise the common git dir itself. Only an absent `<parent>/.git` is
+// "not this parent"; one that exists and that git refuses fails the probe, so
+// a linked worktree never re-keys to the common dir. This module is the spawn
+// around that function — the scrubbed env, the bound, the join onto `.fleet/`
+// — so a new `.fleet/`-rooted file is one `fleetFile("name")` call rather
+// than another hand-spelled probe. The bound is per git child, not per call:
+// when the common git dir is not named `.git` and the parent's `.git`
+// exists, resolveWorkspace() runs a second `rev-parse` after this module's
+// own, with a bound of its own, so one call's worst case approaches twice
+// `timeoutMs`.
 //
 // One error policy: anything that leaves no workspace THROWS
 // FleetDirUnresolvable, never a null or an empty path. What a caller does
@@ -115,15 +118,16 @@ function workspaceOf(cwd, timeoutMs, canonicalise) {
  * that spelling without changing which file it names.
  *
  * `timeoutMs` (default git-env.mjs's DEFAULT_GIT_TIMEOUT_MS) bounds each git
- * child, not the call. When the common git dir is not named `.git` (the
- * `.bare` layout, a bare repository, a submodule, a `--separate-git-dir`
- * clone), resolveWorkspace() runs a second probe after `--git-common-dir`,
- * with its own full `timeoutMs`, so one call's worst case approaches twice
- * `timeoutMs`.
+ * child, not the call. When the common git dir is not named `.git` and the
+ * `.git` in its parent exists (the `.bare` layout, or any other git dir that
+ * shares a parent with a `.git`), resolveWorkspace()
+ * runs a second probe after `--git-common-dir`, with its own full `timeoutMs`,
+ * so one call's worst case approaches twice `timeoutMs`.
  *
  * Throws FleetDirUnresolvable for every probe that leaves no workspace — no
- * repository, an unreadable `.git`, git missing, a probe killed at
- * `timeoutMs` — with git's own reason in the message.
+ * repository, an unreadable `.git`, a parent's `.git` that git refuses, git
+ * missing, a probe killed at `timeoutMs` — with git's own reason in the
+ * message.
  */
 export function fleetFile(name, { cwd = process.cwd(), timeoutMs, canonicalise = false } = {}) {
   const { dir } = workspaceOf(cwd, timeoutMs, canonicalise);
@@ -146,9 +150,9 @@ export function fleetFile(name, { cwd = process.cwd(), timeoutMs, canonicalise =
  *
  * `home` exists for tests; it defaults to the user's home directory.
  * `timeoutMs` bounds each git child exactly as in fleetFile(): two may run in
- * sequence when the common git dir is not named `.git`, so one call's worst
- * case approaches twice `timeoutMs`. Throws FleetDirUnresolvable exactly as
- * fleetFile() does.
+ * sequence when the common git dir is not named `.git` and its parent's `.git`
+ * exists, so one call's worst case approaches twice `timeoutMs`. Throws
+ * FleetDirUnresolvable exactly as fleetFile() does.
  */
 export function scratchRoot({ cwd = process.cwd(), timeoutMs, home = homedir() } = {}) {
   const { dir, gitDir } = workspaceOf(cwd, timeoutMs, true);

package/scripts/git-env.mjs

@@ -63,8 +63,10 @@ export function gitEnv(overrides = {}, base = process.env) {
 // `.git` or when that parent's own `.git` resolves to it (the `.bare`
 // layout's gitfile); otherwise it is the common dir itself — a bare
 // repository's, a submodule's or a `--separate-git-dir` clone's git dir — so
-// two such dirs sharing a parent do not collapse onto one workspace. The
-// rule's full statement sits beside `resolveWorkspace()` below. The main
+// two such dirs sharing a parent do not collapse onto one workspace. Only an
+// absent `<parent>/.git` is "not this parent"; one that git refuses fails the
+// probe, so a linked worktree never re-keys to the common dir. The rule's
+// full statement sits beside `resolveWorkspace()` below. The main
 // checkout's work tree is a separate question with its own answer,
 // `mainCheckoutDirFromGitCommonDir()`: a `.git` symlinked to a git dir
 // elsewhere moves the workspace out of the checkout, never the work tree.
@@ -79,7 +81,7 @@ export function gitEnv(overrides = {}, base = process.env) {
 // composes the rest around it.
 
 import { spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 
 // A `rev-parse` answers in milliseconds; this bound exists so a git that never
@@ -87,8 +89,10 @@ import { basename, dirname, join, resolve } from "node:path";
 export const DEFAULT_GIT_TIMEOUT_MS = 10_000;
 
 // Thrown when the one probe the rule needs beyond `--git-common-dir` could not
-// run to an answer: git missing, or killed at its bound. Not thrown for a git
-// that ran and refused — that is an answer, and the rule reads it as "no".
+// run to an answer: git missing, killed at its bound, or a `<parent>/.git`
+// that exists and that git refuses. Only an absent `<parent>/.git` is "no";
+// one git refuses fails the probe, so a linked worktree never re-keys to the
+// common dir.
 export class WorkspaceProbeFailed extends Error {
   constructor(message) {
     super(message);
@@ -107,25 +111,32 @@ function canonicalPath(path) {
 }
 
 // Why a probe that did not answer did not: the spawn error, the signal that
-// killed it, or its stderr. Its caller reaches it only for a spawn error or a
-// probe with no exit status, so no exit code is ever left to name.
+// killed it, its stderr, or its exit status when stderr says nothing.
 function probeWhy(r) {
   if (r.error && r.error.message) return r.error.message;
   if (r.signal) return `killed by ${r.signal}`;
-  return String(r.stderr ?? "").trim() || "no answer";
+  return String(r.stderr ?? "").trim() || `git exited ${r.status}`;
 }
 
 // Does `<parent>/.git` name `gitDir` (a realpath)? `--resolve-git-dir` follows
-// a gitfile, so the `.bare` layout's `.git` file answers with `.bare`.
+// a gitfile, so the `.bare` layout's `.git` file answers with `.bare`. Only an
+// absent `<parent>/.git` is no, without a spawn; one that exists and that git
+// refuses (a dangling or invalid gitfile, an unreadable one) fails the probe.
+// Git's stderr is only quoted, never read: its text depends on the locale.
 function parentGitDirNames(parent, gitDir, cwd, timeoutMs) {
   const candidate = join(parent, ".git");
+  try {
+    lstatSync(candidate);
+  } catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw new WorkspaceProbeFailed(`could not resolve ${candidate}: ${e.message}`);
+  }
   const r = spawnSync("git", ["rev-parse", "--resolve-git-dir", candidate], {
     cwd, encoding: "utf8", timeout: timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS, env: gitEnv(),
   });
-  if (r.error || r.status === null) {
+  if (r.error || r.status !== 0) {
     throw new WorkspaceProbeFailed(`could not resolve ${candidate}: ${probeWhy(r)}`);
   }
-  if (r.status !== 0) return false;
   return realpathOr(resolve(parent, r.stdout.trim())) === gitDir;
 }
 
@@ -138,8 +149,9 @@ function parentGitDirNames(parent, gitDir, cwd, timeoutMs) {
  * The rule, on the common dir `C` (the realpath of the answer):
  *   1. `C` is named `.git`: the workspace is its parent. No spawn.
  *   2. Otherwise `<parent of C>/.git` is probed with `--resolve-git-dir`. If it
- *      names `C`, the workspace is that parent (the `.bare` layout). A git that
- *      refuses, or names something else, is "no".
+ *      names `C`, the workspace is that parent (the `.bare` layout). A
+ *      `.git` that is absent, or that git names as something else, is "no".
+ *      A `.git` that exists and that git refuses fails the probe.
  *   3. Otherwise the workspace is `C` itself, with `gitDir: true`.
  *
  * `gitDir` is what the scratch root's key reads: a git dir's `.git` suffix
@@ -160,12 +172,13 @@ function parentGitDirNames(parent, gitDir, cwd, timeoutMs) {
  * uncanonicalised path.
  *
  * `timeoutMs` (default DEFAULT_GIT_TIMEOUT_MS) bounds this function's own
- * step-2 probe only, the one spawn it makes. The caller's `--git-common-dir`
+ * step-2 probe only, the one spawn it can make. The caller's `--git-common-dir`
  * probe that produced `gitCommonDir` is the caller's to bound, so a caller
  * passing the same `timeoutMs` to both can wait close to twice that in all.
  *
- * Throws WorkspaceProbeFailed only when the step-2 probe could not run to an
- * answer.
+ * Throws WorkspaceProbeFailed when the step-2 probe could not run to an
+ * answer: git missing or killed at its bound, or a `<parent of C>/.git` that
+ * exists and that git refuses.
  */
 export function resolveWorkspace(gitCommonDir, cwd = process.cwd(), { canonicalise = false, timeoutMs } = {}) {
   const common = String(gitCommonDir ?? "").trim();

package/scripts/ledger.mjs

@@ -126,20 +126,23 @@ function cause(...candidates) {
 // though "dominant" overstates that relationship: a normal invocation
 // without `--file` can pay this same budget TWICE in sequence, once here and
 // once more in repoCheck() below, before ever reaching `gh` at all — and
-// THREE times in layouts whose common git dir is not named `.git` (the
-// `.bare` layout, a bare repository, a submodule, a `--separate-git-dir`
-// clone), where fleetFile() runs a second probe with its own full budget:
+// THREE times where the common git dir is not named `.git` and its parent
+// holds a `.git` (the `.bare` layout, or any other git dir sharing a parent
+// with a `.git`), where fleetFile() runs a second probe with its own full budget:
 // fleetFile()'s bound is per git child, not per call. At default settings
 // two stalled probes TIE `gh`'s own 20 s bound and three exceed it, and even
 // one stall can EXCEED it — up to GIT_TIMEOUT_MS + 20 s — when `gh` still
 // runs (measured). `check`'s worst case is the sum of whichever of its
 // children actually stall, not a single fixed term. That is three children
-// normally; in those layouts it is three git children and `gh` is a fourth.
+// normally; in the `.bare` layout it is three git children and `gh` is a fourth.
+// A bare repository, a submodule or a `--separate-git-dir` clone has no `.git`
+// beside its git dir, so fleetFile() runs no second probe there.
 // Where the ledger's repository has no work tree (the `.bare` layout, a bare
 // repository, a `--separate-git-dir` clone; not a submodule) repoCheck()'s
 // `--show-toplevel` is refused and it asks the same directory for
-// `--git-common-dir` to bind `gh` to, so there it is four git children and
-// `gh` a fifth. `gh` runs in every one of those layouts. With `--file` the
+// `--git-common-dir` to bind `gh` to: four git children and `gh` a fifth in
+// the `.bare` layout, three and `gh` a fourth in the other two. `gh` runs in
+// every one of those layouts. With `--file` the
 // fleetFile() children drop out: two children normally, three where the
 // repository has no work tree.
 //

package/skills/run-team/SKILL.md

@@ -599,7 +599,7 @@ worktree re-created for an already-open PR is in references/isolation.md.
 | 1 `LEFT #N: taken …` | in-flight hit, an in-flight check that could not answer, or `claim-ticket.sh` exit 2 | next entry |
 | 1 `LEFT #N: relabelled elsewhere` | no longer labelled `ready-for-agent` | next entry |
 | 1 `LEFT #N: closed: fixed by …` | `close` answered `yes` | next entry |
-| 1 `LEFT #N: relabelled <label>: …` | `decided` answered with a cause | next entry |
+| 1 `LEFT #N: relabelled <label>: …` | `decided` answered with a cause, or a stranded ruling | next entry |
 | 1 `LEFT #N: excluded …` | `collision` answered `behind-pr:#M` or `behind-issue:#M`, or its ledger exclusion stands | next entry |
 | 1 `EMPTY` | the shortlist holds no entry to pull | run `shortlist.mjs` once and Pull again; still empty, hold the slot idle until the next refresh trigger |
 | 2 | could not look, named on stderr | as the entry paragraph says |
@@ -1771,7 +1771,7 @@ above and every row of the table below already applied; every wake
 ends in it. The deficit is then *computed, not remembered*, which is
 the whole point: a table you must remember to consult is one you will not
 consult under a merge-side event storm, and that is how implementers reached
-0/target with one approved ticket waiting and ~57 `ready-for-agent` in supply while nobody
+0/target with ~57 `ready-for-agent` in supply while nobody
 noticed (#3). What follows stays here as the explanation of what the script decides —
 never as a second, hand-run copy of it. The table's shortlist counts no head
 whose Pull ended this run. A refresh at unclaimed < B leaves `unclaimed=` at

package/skills/run-team/references/pull.md

@@ -242,6 +242,7 @@ does:
 |---|---|
 | in-flight hit, or an in-flight check that could not answer | drop, next entry |
 | no longer labelled `ready-for-agent` | drop, next entry |
+| a stranded ruling: a `## Ruling` or `## Triage` comment newer than the last `## Agent Brief`, or on a ticket with none | relabel `ready-for-human`, next entry |
 | `staleness.mjs` exit 1 — provably fixed | close citing the commit, next entry |
 | brief names no *what* | relabel `needs-triage`, next entry |
 | genuine fork — options named, none ruled | relabel `ready-for-human`, next entry |
@@ -266,8 +267,11 @@ that trusted a list built before the relabel landed would hand a ticket the
 fleet has already judged unimplementable straight to the next member.
 
 **Relabel by cause.** An unclaimed ticket is yours to reclassify at the Pull —
-three causes, two labels: `ready-for-human` for hands or a fork;
-`needs-triage` for a brief that names no *what*.
+`ready-for-human` for hands or a fork; `needs-triage` for a brief that names no
+*what*. A stranded ruling relabels to `ready-for-human` as well, but it is never
+yours to judge: `pull.mjs` finds it at step 3 and posts its own comment naming
+the stranded comment's heading line and URL, which is not one of the
+`briefs/relabel.md` comments.
 `gh issue edit <N> --remove-label ready-for-agent --add-label <label>` (no
 `in-progress` to drop — it was never claimed), preceded by exactly one comment,
 the one `~/.fleet/bin/fleet-run dispatch-prompt.mjs render relabel --kind <kind> …`
@@ -280,8 +284,9 @@ live in `briefs/relabel.md`; `pull.mjs` posts its own one-line copy of the same
 words when a Pull answer relabels, so a change to either is a change to both.
 
 Neither label invokes anything: `/triage` is maintainer-run, and both labels
-only stop the ticket costing a read per scan. These comments are the only
-writes the fleet makes to a ticket it did not claim.
+only stop the ticket costing a read per scan. These comments, the
+stranded-ruling comment and the comment closing a provably fixed ticket are the
+only writes the fleet makes to a ticket it did not claim.
 
 **Exclusion is a ticket row with a premise.** `ledger.mjs row <N> "excluded ·
 behind-pr:#M"` or `ledger.mjs row <N> "excluded · behind-issue:#M"` — `#M` is