@feigi/fleet-ctl 3.81.1 → 3.81.3

package/package.json

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

package/scripts/ledger.mjs

@@ -2337,11 +2337,6 @@ async function runSettleFromReport() {
   const report = read.report;
   const invalid = (violation) => die(`${where}: ${read.path} is not a ${reportFamily(member)} report — ${violation}; nothing written`);
   if (report.member !== member) invalid(`$.member: ${JSON.stringify(report.member)} is not ${member}`);
-  // An issue number is a positive integer. A negative id writes a row `#-3 …`
-  // that `filed` refuses and `check`'s subjectOf() cannot strip.
-  for (const [k, { issue }] of (report.unrecorded ?? []).entries()) {
-    if (!Number.isInteger(issue) || issue < 1) invalid(`$.unrecorded[${k}].issue: ${JSON.stringify(issue)} is not an issue number`);
-  }
 
   // Every child runs from the ledger's repository with runCheck()'s
   // environment, for runCheck()'s reasons: GH_REPO would point gh at another
@@ -2411,7 +2406,7 @@ async function runSettleFromReport() {
   let outcome;
   if (live.family === "impl") {
     if (report.outcome === "pr") {
-      if (report.pr === null || report.pr < 1) invalid(`$.pr: ${JSON.stringify(report.pr)} is not a PR number, with outcome "pr"`);
+      if (report.pr === null) invalid('$.pr: null is not a PR number, with outcome "pr"');
       if (report.head === null) invalid('$.head: null, with outcome "pr"');
       outcome = `PR#${report.pr}`;
       const sha = look(`verify-sha.sh ${report.branch} ${report.head}`, "sh", [verifySha, report.branch, report.head], [0, 1]);

package/scripts/main-checkout.mjs

@@ -446,10 +446,17 @@ export function describe(check, live = null) {
   switch (check.state) {
     case "clean":
       return null;
-    case "dirty":
-      // The HEAD entry is text, not a path: quoting it would blur it.
+    case "dirty": {
+      // The HEAD entry is text, not a path: quoting it would blur it, and
+      // ignoring cannot clear it, so only a path entry names the ignore remedy.
+      // An exclude hides untracked paths alone, and changedPaths reads a
+      // baseline entry that vanishes as changed, so the remedy is limited to
+      // untracked paths new since the baseline.
+      const hasPath = check.changed.some((p) => p !== check.headMove);
       return `MAIN-CHECKOUT-DIRTY ${check.changed.map((p) => (p === check.headMove ? p : shown(p))).join(" ")} — changed since the run's baseline${members}`
-        + ` — dispatch held: resolve the stray paths FIRST, then re-baseline with ${RECORD_COMMAND} (it overwrites, it does not compare)`;
+        + ` — dispatch held: resolve the stray paths FIRST, then re-baseline with ${RECORD_COMMAND} (it overwrites, it does not compare)`
+        + (hasPath ? " — or, for an untracked path new since the baseline, the maintainer may instead ignore it in .git/info/exclude or the global excludes file: it clears on the next check with no re-baseline, so long as the pattern matches no path the baseline holds; ignoring never clears a tracked or staged file's change" : "");
+    }
     case "absent":
       return `MAIN-CHECKOUT-NO-BASELINE no baseline at ${check.baseline} — dispatch held: record it at run start with ${RECORD_COMMAND}`;
     default:

package/scripts/report-files.mjs

@@ -14,7 +14,7 @@
 
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { SCHEMAS, validate } from "./report-schema.mjs";
+import { SCHEMAS, parseReport, validate } from "./report-schema.mjs";
 import { parseMember } from "./ledger-grammar.mjs";
 import { scratchRoot } from "./fleet-dir.mjs";
 
@@ -53,14 +53,9 @@ export function readReportIn(dir, member) {
     if (e.code === "ENOENT" || e.code === "ENOTDIR") return { state: "absent", path };
     return { state: "invalid", path, violation: `$: unreadable (${e.code ?? e.message})` };
   }
-  let report;
-  try {
-    report = JSON.parse(text);
-  } catch (e) {
-    return { state: "invalid", path, violation: `$: not JSON (${e.message})` };
-  }
-  const violation = validate(SCHEMAS[family], report);
-  return violation === null ? { state: "ok", path, report } : { state: "invalid", path, violation };
+  const parsed = parseReport(text);
+  const violation = parsed.violation ?? validate(SCHEMAS[family], parsed.value);
+  return violation === null ? { state: "ok", path, report: parsed.value } : { state: "invalid", path, violation };
 }
 
 /** `ok`, `invalid`, `absent`, or `-` when no schema covers the member. */

package/scripts/report-schema.mjs

@@ -17,7 +17,8 @@
 //
 //   0  print: the schema is on stdout. validate: `valid` on stdout
 //   1  validate: `invalid: <violation>` on stdout, naming the FIRST violation;
-//      a file that is not JSON is invalid too, as `$: not JSON (...)`
+//      a file that is not JSON is invalid too, as `$: not JSON (...)`, and so
+//      is one that repeats a key, as `$.merged: duplicate key "merged"`
 //   2  usage: no or unknown subcommand, a wrong argument count, an unknown
 //      family, any flag; or <file> could not be read; or print could not
 //      write the schema to stdout. Refused on stderr, nothing on stdout
@@ -31,16 +32,21 @@
 // their schema names.
 //
 // The validator below is hand-written and covers exactly the keywords these
-// schemas use: `type` (one or a list; `integer` is a whole number), `enum`,
-// `required`, `properties`, `additionalProperties: false`, `items` and
-// `pattern`. A keyword it does not know is not checked, so a schema here
-// that starts using one needs the validator to learn it first. It walks in a
-// fixed order, which is what makes "the first violation" one answer: at
-// each value `type`, then `enum`, then `pattern`; in an object every
-// `required` field in the schema's order, then any unexpected field in the
-// report's order, then each property in the schema's order; in an array each
-// item in turn. A violation is named by its path from the report's root, `$`,
-// as `$.merged[1].sha`.
+// schemas use: `type` (one or a list), `enum`, `pattern`, `minimum` and
+// `maximum` (numbers only: a value that is not a number, `null` included,
+// passes them), `required`, `properties`, `additionalProperties: false` and
+// `items`. A keyword it does not know is not checked, so a schema here that
+// starts using one needs the validator to learn it first. An integer is
+// bounded by the schema, not by `type`: ids by 1 and the largest safe
+// integer, the other integers by the safe range, beyond which JSON.parse has
+// already rounded the number. A duplicate key, compared decoded and at any
+// depth, is a violation named before any schema check. The walk is in a
+// fixed order, which is what makes "the first violation" one answer: at each
+// value `type`, then `enum`, then `pattern`, then `minimum`, then `maximum`;
+// in an object every `required` field in the schema's order, then any
+// unexpected field in the report's order, then each property in the schema's
+// order; in an array each item in turn. A violation is named by its path
+// from the report's root, `$`, as `$.merged[1].sha`.
 //
 // Strict mode. A `task` call can carry this schema as `outputSchema` with
 // `schemaMode: "strict"`. Measured 2026-10-14 under omp/18.10.3, and only on
@@ -85,7 +91,10 @@ const USAGE = "usage: report-schema.mjs print <family> | validate <family> <file
 
 const HEX = "^[0-9a-f]{40}$";
 const str = { type: "string" };
-const int = { type: "integer" };
+// An id is a positive safe integer; a negative one writes a ledger row `#-3 …` that `filed` refuses and `check`'s subjectOf() cannot strip.
+const id = { type: "integer", minimum: 1, maximum: Number.MAX_SAFE_INTEGER };
+// A position or a count: the safe range only, so a truthful negative `exit` stays valid.
+const int = { type: "integer", minimum: -Number.MAX_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER };
 const sha = { type: "string", pattern: HEX };
 const strings = { type: "array", items: str };
 
@@ -96,13 +105,13 @@ const listOf = (properties) => ({ type: "array", items: obj(properties) });
 // A family's top level: every field required, nothing else allowed.
 const report = (properties) => ({ ...obj(properties), additionalProperties: false });
 
-const issues = listOf({ issue: int, subject: str });
+const issues = listOf({ issue: id, subject: str });
 
 export const SCHEMAS = {
   impl: report({
     member: str,
     outcome: { type: "string", enum: ["pr", "bailed"] },
-    pr: { type: ["integer", "null"] },
+    pr: { ...id, type: ["integer", "null"] },
     head: { type: ["string", "null"], pattern: HEX },
     branch: str,
     sizing: obj(
@@ -119,7 +128,7 @@ export const SCHEMAS = {
     head: sha,
     branch: str,
     applied: listOf({ bucket: str, index: int }),
-    deferred: listOf({ bucket: str, index: int, issue: int }),
+    deferred: listOf({ bucket: str, index: int, issue: id }),
     filed: issues,
     unrecorded: issues,
     dispositionsRecord: { type: "string", pattern: "^/" },
@@ -141,11 +150,11 @@ export const SCHEMAS = {
   }),
   "merge-bot": report({
     member: str,
-    merged: listOf({ pr: int, sha }),
-    held: listOf({ pr: int, behind: int }),
-    conflictHold: { type: "array", items: int },
-    refused: listOf({ pr: int, reason: str }),
-    branchKept: listOf({ pr: int, by: int }),
+    merged: listOf({ pr: id, sha }),
+    held: listOf({ pr: id, behind: id }),
+    conflictHold: { type: "array", items: id },
+    refused: listOf({ pr: id, reason: str }),
+    branchKept: listOf({ pr: id, by: id }),
   }),
 };
 
@@ -172,6 +181,10 @@ export function validate(schema, value, path = "$") {
   if (typeof value === "string" && schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) {
     return `${path}: ${show(value)} does not match ${schema.pattern}`;
   }
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum) return `${path}: ${show(value)} is below minimum ${schema.minimum}`;
+    if (schema.maximum !== undefined && value > schema.maximum) return `${path}: ${show(value)} is above maximum ${schema.maximum}`;
+  }
   if (isObject(value)) {
     for (const key of schema.required ?? []) {
       if (!Object.hasOwn(value, key)) return `${path}: missing required field ${show(key)}`;
@@ -196,6 +209,57 @@ export function validate(schema, value, path = "$") {
   return null;
 }
 
+// The first duplicate key of `text` in text order, as `<path>: duplicate key
+// "<key>"`, or null. `text` is well-formed JSON, so nothing here can meet a
+// malformed token. Keys are compared decoded, as JSON.parse collides them.
+function firstDuplicateKey(text) {
+  // One frame per open container: an object's keys so far, an array's index.
+  const open = [];
+  let next = "$"; // the path of the value that starts next
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    const top = open[open.length - 1];
+    if (c === "{") {
+      open.push({ path: next, keys: new Set(), wantKey: true });
+    } else if (c === "[") {
+      open.push({ path: next, index: 0 });
+      next = `${next}[0]`;
+    } else if (c === "}" || c === "]") {
+      open.pop();
+    } else if (c === ",") {
+      if (top.keys === undefined) next = `${top.path}[${++top.index}]`;
+      else top.wantKey = true;
+    } else if (c === '"') {
+      let end = i + 1;
+      while (text[end] !== '"') end += text[end] === "\\" ? 2 : 1;
+      if (top?.wantKey) {
+        const key = JSON.parse(text.slice(i, end + 1));
+        next = `${top.path}.${key}`;
+        if (top.keys.has(key)) return `${next}: duplicate key ${show(key)}`;
+        top.keys.add(key);
+        top.wantKey = false;
+      }
+      i = end;
+    }
+    i++;
+  }
+  return null;
+}
+
+/** `text` read as a report: `{ value }`, or `{ violation }` for text that is
+ * not JSON or that repeats a key in any object at any depth. */
+export function parseReport(text) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (e) {
+    return { violation: `$: not JSON (${e.message})` };
+  }
+  const violation = firstDuplicateKey(text);
+  return violation === null ? { value } : { violation };
+}
+
 function familyOf(name) {
   if (!Object.hasOwn(SCHEMAS, name)) die(`unknown family '${name}' — known: ${Object.keys(SCHEMAS).join(", ")}`);
   return SCHEMAS[name];
@@ -222,14 +286,8 @@ function main() {
   } catch (e) {
     die(`cannot read ${path}: ${e.code ?? e.message}`);
   }
-  let value;
-  try {
-    value = JSON.parse(text);
-  } catch (e) {
-    writeAll(1, `invalid: $: not JSON (${e.message})\n`);
-    process.exit(1);
-  }
-  const violation = validate(schema, value);
+  const parsed = parseReport(text);
+  const violation = parsed.violation ?? validate(schema, parsed.value);
   if (violation !== null) {
     writeAll(1, `invalid: ${violation}\n`);
     process.exit(1);

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

@@ -75,6 +75,7 @@ older-version baseline and a baseline whose commit is missing from the
 repository; Phase 3's tick lines say how each is cleared.
 `main-checkout.mjs --check` prints the same answer
 without a tick.
+On `MAIN-CHECKOUT-DIRTY` the maintainer may instead ignore a stray path that is untracked and new since the baseline: an entry in `.git/info/exclude` or in the global excludes file hides it from the check, and the hold clears on the next tick with no re-record. Ignoring never clears a tracked or staged file's change, which `git status` reports whatever the excludes say, nor a pattern that also matches a path the baseline holds, which then reads as changed. Ignoring is the maintainer's decision, never the controller's: the controller never writes an exclude or a `.gitignore` entry. Keep the pattern narrow, because an ignored path is invisible to this check, so a later member write that matches it is never seen.
 
 ## Run the pre-flight
 

package/skills/run-team/references/tick-rows.md

@@ -129,6 +129,7 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
   checkout and the close-out commit's round trip through a branch; **Fix the
   tooling mid-run** and the commit section of references/close-out.md say how
   each is cleared.
+  The maintainer may instead ignore a stray path that is untracked and new since the baseline: an entry in `.git/info/exclude` or in the global excludes file hides it from the check, and the hold clears on the next tick with no re-baseline. Ignoring never clears a tracked or staged file's change, which `git status` reports whatever the excludes say, nor a pattern that also matches a path the baseline holds, which then reads as changed. Ignoring is the maintainer's decision; the controller never writes an exclude or a `.gitignore` entry. Keep the pattern narrow, because an ignored path is invisible to this check, so a member write that matches it is never seen.
 - `MAIN-CHECKOUT-UNKNOWN …` with `HOLD (main checkout unknown)` — the tick
   could not look: a git or hash read failed (`could not look:`), or the
   baseline exists but cannot be read (`baseline unreadable:`). Never clean,