@feigi/fleet-ctl 3.85.0 → 3.86.0

package/package.json

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

package/scripts/controller-alarm.mjs

@@ -45,8 +45,8 @@
 // THE PROOF IT IS ARMED. At `session_start`, for the main session only, and
 // only AFTER the timer is set, it writes `~/.fleet/alarm/<pid>.json` holding
 // `{ pid, lstart, fleet }`: this process's pid, its start time as `proc.mjs`
-// reads it, and the `.fleet/` path it resolved. The file is for run-team's
-// phase 0 to check, and nothing reads it yet: this file only writes it. A
+// reads it, and the `.fleet/` path it resolved. Phase 0's `alarm` step reads
+// the file and refuses unless it names this omp and this `.fleet/`. A
 // session that set no timer writes no file, so the file proves the timer is
 // armed against that repository's `.fleet/` and not only that the extension
 // loaded. A start time that cannot be read writes no file, the safe direction:
@@ -59,13 +59,15 @@
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
 import { readState, stateFileIn } from "./fleet-state.mjs";
 import { processSource } from "./proc.mjs";
 
 export const POLL_MS = 30_000;
 export const ALARM_LINE = "[fleet-alarm] run ~/.fleet/bin/fleet-run fleet-event.mjs heartbeat";
+// Where the extension running as `pid` records that its timer is armed; phase 0 reads it there.
+export const alarmFile = (pid) => join(homedir(), ".fleet", "alarm", `${pid}.json`);
 
 /**
  * Whether the alarm fires now. `beat` is `{ at, interval, stopped }` (`at` in
@@ -132,7 +134,7 @@ function arm(pi, ctx) {
     // An unreadable process table is an unreadable start time.
   }
   if (typeof lstart !== "string" || lstart === "") return;
-  const dir = join(homedir(), ".fleet", "alarm");
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, `${process.pid}.json`), `${JSON.stringify({ pid: process.pid, lstart, fleet: fleetDir })}\n`);
+  const file = alarmFile(process.pid);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ pid: process.pid, lstart, fleet: fleetDir })}\n`);
 }

package/scripts/phase0-receipt.mjs

@@ -18,7 +18,7 @@ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x)
 // a step not yet run being `pending`. A receipt missing one was not written
 // by a finished phase 0.
 export const STEP_NAMES = Object.freeze([
-  "branch", "fast-forward", "pin", "baseline", "preflight", "ruleset", "tier-roles", "metrics",
+  "alarm", "branch", "fast-forward", "pin", "baseline", "preflight", "ruleset", "tier-roles", "metrics",
   "cockpit", "rotate", "reclaim", "recipe", "fold-in", "stranded", "shortlist",
 ]);
 

package/scripts/phase0.mjs

@@ -20,6 +20,9 @@
 // reclaim straight after the rotation, the metrics refresh before the first
 // Pull is routed:
 //
+//   alarm         `~/.fleet/alarm/<pid>.json` names this omp's pid and start time
+//                 and this `.fleet/`. Missing, malformed or mismatched, or no omp
+//                 above the script, refuses: restart omp.
 //   branch        `git symbolic-ref -q HEAD` is refs/heads/main. A checkout left
 //                 on a branch whose PR has merged would fast-forward that branch
 //                 and the baseline would record it as the run's ref.
@@ -82,29 +85,31 @@
 // is the In-flight bound this run used — `--in-flight`, or its default.
 //
 // RESUMABLE. A re-run reads the receipt. It continues it — skipping every `ok`
-// step and re-running the rest — only when its `run` equals the `at` the
-// controller record holds now AND its `session` equals this run's session. That
-// comparison alone does not separate two runs before the new run's rotation:
-// the record still carries the previous run's `at` until `ledger.mjs rotate`
-// writes the next, so the previous run's receipt still matches it, and a
-// re-run that trusted `run` alone would skip `rotate`. The session rule closes
-// a new session. A receipt of any other run (a `run` that is set and does not
-// match, or a different session) is held as `phase0.previous.json`, where
-// `closeout.mjs finish` also leaves a finished run's receipt, and the
-// script starts at `branch`; this run's own receipt is written at
-// `phase0.json` after every step. A receipt whose rotation has not run is
-// simply overwritten: every step before `rotate` is idempotent and is re-run
-// on every invocation until the rotation has run.
+// step but `alarm` and re-running the rest — only when its `run` equals the
+// `at` the controller record holds now AND its `session` equals this run's
+// session. That comparison alone does not separate two runs before the new
+// run's rotation: the record still carries the previous run's `at` until
+// `ledger.mjs rotate` writes the next, so the previous run's receipt still
+// matches it, and a re-run that trusted `run` alone would skip `rotate`. The
+// session rule closes a new session. `alarm` is re-run on every invocation,
+// `ok` or not: it proves something about the omp running this invocation, and
+// a resumed receipt may have been written under another. A receipt of any
+// other run (a `run` that is set and does not match, or a different session)
+// is held as `phase0.previous.json`, where `closeout.mjs finish` also leaves a
+// finished run's receipt, and the script starts at `alarm`; this run's own
+// receipt is written at `phase0.json` after every step. A receipt whose
+// rotation has not run is simply overwritten: every step before `rotate` is
+// idempotent and is re-run on every invocation until the rotation has run.
 //
 // THE ROTATION FILES THE PREVIOUS RUN'S RECEIPT. The `rotate` step takes this
 // run's partial receipt off disk, puts the held one back at `phase0.json` and
 // runs `ledger.mjs rotate`, which archives it as `phase0.<UTC stamp>.json`
 // beside `ledger.<UTC stamp>.md`, one stamp for both. A rotation that refused
 // leaves it held for the next attempt; one that archived the ledger and not
-// the receipt files it under a stamp of this script's own. With no omp process
-// above the run the rotation writes no controller record and `run` stays
-// null; a receipt whose `rotate` step is `ok` is then resumed on the session
-// alone.
+// the receipt files it under a stamp of this script's own. A rotation that
+// writes no controller record (the ledger finds no omp above itself) leaves
+// `run` null; a receipt whose `rotate` step is `ok` is then resumed on the
+// session alone.
 //
 // A step that fails stops the script; so does a pending one — nothing after
 // the recipe may run before it is proven, and the shortlist waits for the
@@ -133,16 +138,19 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync,
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { makeDie, defineFlags, isDigits } from "./arg.mjs";
+import { alarmFile } from "./controller-alarm.mjs";
 import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
 import { readState, stateFileIn } from "./fleet-state.mjs";
 import { gitEnv } from "./git-env.mjs";
 import { isCLI } from "./is-cli.mjs";
 import { RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
+import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
 import { IN_FLIGHT_DEFAULT } from "./phase0-receipt.mjs";
 
 const NAME = "phase0";
 const SCRIPTS = dirname(fileURLToPath(import.meta.url));
 const MAX_BUFFER = 64 * 1024 * 1024;
+const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
 const NETWORK_TIMEOUT_MS = 120_000;
 const PR_LIMIT = 1000;
 // The tail of a child's output is the part that says why it stopped.
@@ -419,8 +427,46 @@ function shortlist({ cwd }) {
   return ok("shortlist built");
 }
 
+// The controller alarm: this omp's own record that its timer is armed against
+// this checkout's `.fleet/` (controller-alarm.mjs writes it at session_start).
+// The record is read, not trusted: it must name this omp's pid and start time
+// and this `.fleet/`.
+function alarm({ fleetDir }) {
+  const tail = " — restart omp";
+  let controller;
+  try {
+    const source = processSource();
+    controller = controllerOf(source, ancestry(source));
+  } catch (e) {
+    if (!(e instanceof ProcUnreadable)) throw e;
+    return failed(`${e.message}${tail}`);
+  }
+  if (controller === null) return failed(`no omp process above phase 0: the controller alarm cannot be checked${tail}`);
+  const path = alarmFile(controller.pid);
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return failed(`controller alarm is not armed: ${path} does not exist${tail}`);
+    return failed(`controller alarm file ${path} cannot be read (${e.code ?? e.message})${tail}`);
+  }
+  let rec;
+  try {
+    rec = JSON.parse(text);
+  } catch (e) {
+    return failed(`controller alarm file ${path} is not JSON (${e.message})${tail}`);
+  }
+  if (!isRecord(rec)) return failed(`controller alarm file ${path} is not an object${tail}`);
+  const missing = ["pid", "lstart", "fleet"].filter((k) => !Object.hasOwn(rec, k));
+  if (missing.length > 0) return failed(`controller alarm file ${path} lacks ${missing.join(", ")}${tail}`);
+  if (rec.pid !== controller.pid) return failed(`controller alarm file ${path} names pid ${rec.pid}, but this omp is pid ${controller.pid}${tail}`);
+  if (rec.lstart !== controller.lstart) return failed(`controller alarm file ${path} was written by a process started at "${rec.lstart}", but this omp started at "${controller.lstart}"${tail}`);
+  if (rec.fleet !== fleetDir) return failed(`controller alarm file ${path} names fleet "${rec.fleet}", not ${fleetDir}${tail}`);
+  return ok(`controller alarm armed: pid ${controller.pid}, ${fleetDir}`);
+}
+
 const STEPS = {
-  "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "preflight": preflight,
+  "alarm": alarm, "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "preflight": preflight,
   "ruleset": ruleset, "tier-roles": tierRoles, "metrics": metrics, "cockpit": cockpit, "rotate": rotate,
   "reclaim": reclaim, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
 };
@@ -445,8 +491,7 @@ function readReceipt(path) {
   } catch (e) {
     throw new Error(`the receipt ${path} is not JSON (${e.message}) — move it aside and re-run`);
   }
-  const record = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
-  if (!(record(r) && record(r.steps) && Object.hasOwn(r, "run") && typeof r.session === "string")) {
+  if (!(isRecord(r) && isRecord(r.steps) && Object.hasOwn(r, "run") && typeof r.session === "string")) {
     throw new Error(`the receipt ${path} has no steps, run and session — move it aside and re-run`);
   }
   return r;
@@ -548,9 +593,9 @@ function main() {
     return;
   }
   // A receipt belongs to a rotated run when the rotation wrote a controller
-  // record it can be keyed on, or, with no omp process above the run to write
-  // one, when its rotation is recorded `ok`. Either way it is this run's only
-  // if the record now holds the `at` it names and the session is the same.
+  // record it can be keyed on, or, when it wrote none, when its rotation is
+  // recorded `ok`. Either way it is this run's only if the record now holds
+  // the `at` it names and the session is the same.
   const rotated = previous !== null && (previous.run !== null || previous.steps.rotate?.status === "ok");
   const resumed = rotated && previous.run === (record?.at ?? null) && previous.session === session;
   if (rotated && !resumed) {
@@ -564,7 +609,8 @@ function main() {
 
   const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, steps: {} };
   for (const name of STEP_NAMES) {
-    const was = resumed ? previous.steps[name] : undefined;
+    // `alarm` checks the omp running this invocation, so its `ok` is never carried.
+    const was = resumed && name !== "alarm" ? previous.steps[name] : undefined;
     receipt.steps[name] = was?.status === "ok" ? was : { status: "pending", at: now, output: "not run" };
   }
 

package/skills/run-team/SKILL.md

@@ -50,8 +50,8 @@ phase, or in any later one, asks the maintainer which tickets to take.
    when the repository has no workflow named CI. Its steps and receipt: See
    references/phase-0.md. Dispatch nothing before it exits 0. Exit 4 is a
    step that needs you: act on each `NEED` line below, then run it again. Once
-   `rotate` has run, a re-run skips every `ok` step and resumes where the last
-   one stopped; before it, a re-run runs every step again.
+   `rotate` has run, a re-run skips every `ok` step but `alarm` and resumes
+   where the last one stopped; before it, a re-run runs every step again.
 
    The `tier-roles` step runs `~/.fleet/bin/fleet-run tier-roles.mjs --check
    --in-flight <B>`, `<B>` being the `--in-flight` given, else the default.

package/skills/run-team/references/phase-0.md

@@ -13,13 +13,17 @@ Exit 3 is a step that failed: its line carries the refusal, so fix the cause
 and run it again.
 
 `phase0.mjs` runs the start sequence in
-its fixed order — branch, fast-forward, pin, baseline, preflight, ruleset,
+its fixed order — alarm, branch, fast-forward, pin, baseline, preflight, ruleset,
 tier-roles, metrics, cockpit, rotate, reclaim, recipe, fold-in, stranded,
 shortlist — prints one `phase0: <step>: <status>` line per step with the
 `NEED` lines last, and records each step in `.fleet/phase0.json`, which the
 tick reads: it prints `PHASE0-INCOMPLETE` and holds every dispatching row
 until the receipt is whole.
 
+## Check the controller alarm
+
+**Check the controller alarm first. Phase 0's first step refuses when this omp's timer is not armed.** The `alarm` step reads `~/.fleet/alarm/<pid>.json`, where `<pid>` is the omp process above the script, and checks that the file names that pid, that process's start time, and this checkout's `.fleet/`. A file that is missing, not JSON, or names something else, and no omp process above the script, each fail the step with exit 3 and a message ending `restart omp`. Restart omp, then run phase 0 again. The step runs on every run of phase 0, one its receipt records `ok` included, because it checks the omp running that run; nothing after it runs until it passes.
+
 ## Fast-forward the checkout
 
 **Fast-forward the checkout before you trust these rules — you are reading