create-agent-rig 0.3.2 → 0.5.0

package/templates/agent-os/universal/.claude/scripts/queue/core.mjs

@@ -63,19 +63,88 @@ export const ADAPTER_CONTRACT = [
   'proposeTriage',
 ];
 
+/**
+ * Why an item was passed over, as a closed vocabulary.
+ *
+ * The reason strings below are written for a human and change freely; a counter
+ * that grouped them by re-parsing that prose would break the first time a word
+ * did. `SPACING` is the one cause no filter produces — it belongs to the tier
+ * ration in `selectNext`, which is why it lives here rather than in `selectionOf`.
+ */
+export const SKIP_CAUSES = Object.freeze([
+  'closed',
+  'in-progress',
+  'triage',
+  'escalated',
+  'blocked',
+  'trigger-auto',
+  'trigger-human',
+  'spacing',
+]);
+
+/**
+ * The causes that hold a takeable item back — and the reason the stop conditions
+ * cannot treat "something was skipped" as one thing.
+ *
+ * Each of these clears without the QUEUE being refilled: a normal item lands, a
+ * blocker closes, another session finishes, a human declares the window. Two of
+ * them do need something written, and the distinction cost three rewrites of the
+ * stop line to get right — a `trigger-auto` item stays held until the
+ * declaration is recorded in the run state, and a `trigger-human` item is freed
+ * only by a human editing the item's own marker. They are separate tags for
+ * that reason: one tag standing for two remedies makes every sentence about it
+ * wrong for one of them. The
+ * three causes NOT in this list — `closed`, `triage`, `escalated` — are items
+ * out of play, waiting on a human. On a tracker-backed adapter they accumulate:
+ * an escalated issue stays open and merely gains a label, and a proposal the
+ * loop files stays open too. Counting those as "the queue is full, wait"
+ * would make `queue-empty` unreachable from the first stop that escalated or
+ * proposed anything — so a drained queue would report "wait and interleave" and
+ * the owner would never be told to refill. That is the same refill-versus-wait
+ * inversion this split exists to remove, pointing the other way.
+ *
+ * Under `plan-md` only `triage` is reachable of the three, and it matters that it
+ * is: `parsePlan` reads the marker out of the bullet text, which is exactly the
+ * case of a proposal that ended up under the wrong heading. `escalated` and
+ * `closed` cannot appear there at all — a flat list carries no per-item state, so
+ * `parsePlan` hands back `labels: []` and `state: 'open'` for every line. That is
+ * an absence of state, NOT an adapter that filed the escalation somewhere safe.
+ * `plan-md`'s own `escalate` says so: it writes nothing, returns `ok: false`, and
+ * hands back the instruction to move the item to the Operator queue in the same
+ * edit — because if that move is not made, the next run picks the item straight
+ * back up.
+ */
+export const HOLDING_CAUSES = Object.freeze([
+  'blocked',
+  'in-progress',
+  'spacing',
+  'trigger-auto',
+  'trigger-human',
+]);
+
 /**
  * Is this item takeable, and if not, why not?
  *
  * The filters run in order and every rejection carries a reason: an unexplained
- * skip is indistinguishable from a bug in the filter.
+ * skip is indistinguishable from a bug in the filter. Each reason also carries a
+ * `cause` tag, so the stop line can say what is holding the queue back without
+ * reading the prose back.
  */
 export const selectionOf = (ticket, { triggersFired = null } = {}) => {
   const reasons = [];
+  const causes = [];
   const labels = ticket.labels ?? [];
 
-  if (ticket.state === 'closed') reasons.push('already closed');
+  // Filter order is the order these are pushed in; a cause repeats at most once,
+  // because two trigger reasons are still one thing holding the item back.
+  const reject = (cause, why) => {
+    reasons.push(why);
+    if (!causes.includes(cause)) causes.push(cause);
+  };
+
+  if (ticket.state === 'closed') reject('closed', 'already closed');
   if (ticket.state === 'in-progress') {
-    reasons.push('already in progress — another session may be on it');
+    reject('in-progress', 'already in progress — another session may be on it');
   }
 
   // Belt and braces, and deliberately so. A triage item is a proposal the loop
@@ -83,11 +152,11 @@ export const selectionOf = (ticket, { triggersFired = null } = {}) => {
   // one careless hand adding that marker closes the loop's feedback path into its
   // own input — the exact circuit the firewall exists to break.
   if (ticket.triage || labels.includes('triage')) {
-    reasons.push('a triage proposal: promotion to work is a human act');
+    reject('triage', 'a triage proposal: promotion to work is a human act');
   }
 
   if (labels.includes('escalated')) {
-    reasons.push('escalated — it is waiting on a human, not on another attempt');
+    reject('escalated', 'escalated — it is waiting on a human, not on another attempt');
   }
 
   // 🔴 INVARIANT 1: blockers resolve from LINKS, never from labels.
@@ -99,21 +168,31 @@ export const selectionOf = (ticket, { triggersFired = null } = {}) => {
   // and takes work whose blocker is still open. Both directions have been seen.
   const open = (ticket.blockedBy ?? []).filter((blocker) => !blocker.resolved);
   if (open.length > 0) {
-    reasons.push(`blocked by ${open.map((b) => b.id).join(', ')} (from links, not labels)`);
+    reject('blocked', `blocked by ${open.map((b) => b.id).join(', ')} (from links, not labels)`);
   }
 
   // No trigger label means unconditional, not missing data. Work that is
   // genuinely conditional says so.
+  // ⚠ **The markers are resolved by the adapter, `auto` first**, so an item
+  // carrying BOTH reaches here as `auto` and one recorded declaration takes it.
+  // Nothing refuses that combination and no hygiene check reports it — so this
+  // branch describes the item as the adapter classified it, and claims nothing
+  // about what the item's author wrote. "Never self-taken" would be exactly
+  // that claim, and it would be false for the item most likely to carry both:
+  // one an owner tightened from auto-gated to human-gated without deleting the
+  // old marker, where the silent resolution goes to the LESS restrictive gate.
   if (ticket.trigger === 'human') {
-    reasons.push(
+    reject(
+      'trigger-human',
       'trigger-human: a window, a demand or a "pass" is a human declaration — ' +
-        'never self-taken, only handed over explicitly',
+        'handed over explicitly, never taken on this marker alone',
     );
   }
   if (ticket.trigger === 'auto') {
     const fired = triggersFired?.[ticket.id];
     if (fired !== true) {
-      reasons.push(
+      reject(
+        'trigger-auto',
         fired === undefined
           ? 'trigger-auto with no verification of the trigger this run — ' +
             'unverified is not fired'
@@ -122,7 +201,7 @@ export const selectionOf = (ticket, { triggersFired = null } = {}) => {
     }
   }
 
-  return { eligible: reasons.length === 0, reasons };
+  return { eligible: reasons.length === 0, reasons, causes };
 };
 
 /**
@@ -270,13 +349,98 @@ export const sortCandidates = (tickets) =>
     return String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? ''));
   });
 
+/**
+ * The tiers a close can record that leave the next elevated item selectable.
+ *
+ * `normal` is the obvious one. `elevated-prose` is the narrowing: an elevated
+ * change every one of whose elevated paths is a document (`state.mjs` decides
+ * this from the diff, never from the item's marker). It is still elevated for
+ * review — model lane, cold readers, the `human-review` label, the gate sweep —
+ * and it does not space the next item, because the ration buys protection from
+ * *unreviewed changes compounding overnight* and a document does not run.
+ */
+const CLEARS_SPACING = new Set(['normal', 'elevated-prose']);
+
+/**
+ * Does the last recorded tier leave the elevated ration open?
+ *
+ * 🔴 **Unknown means the RESTRICTIVE reading, never the permissive one.** Absent
+ * is not unknown: `null`/`undefined` is the honest statement that nothing has
+ * closed yet — what a fresh checkout with no state file says — and refusing it
+ * would make a clone unable to take its first item. Everything else outside the
+ * vocabulary holds: the legacy `'elevated'` an older state file still carries, a
+ * word in the wrong case, a value that is not a string at all. An `===`
+ * comparison against `'elevated-mechanism'` would read every one of those as
+ * "nothing elevated closed" and hand out the next elevated item — un-rationing
+ * the queue silently, which is the exact failure this seam exists to end.
+ *
+ * The CLI refuses an out-of-vocabulary tier before selection ever runs
+ * (`index.mjs`), so this is the second of two layers rather than the only one —
+ * and it is the layer that holds when `selectNext` is called directly.
+ */
+const clearsSpacing = (lastCompletedTier) =>
+  lastCompletedTier === null ||
+  lastCompletedTier === undefined ||
+  CLEARS_SPACING.has(lastCompletedTier);
+
+/**
+ * How many times one branch may enter the review gate before the item stops.
+ *
+ * 🔴 **Why a cap exists.** Every other stop in `autonomy.md` has something red
+ * behind it — a failing check, a conflicting rule, a false premise. A gate that
+ * keeps finding fixable prose has nothing red at all, so three strikes never fires
+ * and the run has no reason to stop re-entering it. That is not hypothetical: the
+ * repository this rulebook was extracted from journalled multi-round gates on single
+ * items with the whole suite green throughout, and its `budget` stop arriving "later
+ * than it should have".
+ *
+ * Two is the cap because the second round is what verifies the first round's fixes.
+ * A third means they are not converging, which is a diagnosis for a human rather
+ * than another pass to buy.
+ */
+export const DEFAULT_MAX_GATE_ROUNDS = 2;
+
+/**
+ * Is this round allowed, and if not, what stops?
+ *
+ * Pure, and separate from the counter on disk, because the rule and the storage
+ * fail differently: a wrong count is a bug in one file, a wrong rule is a bug in
+ * every caller. `gate-rounds.mjs` owns the count; this owns the verdict.
+ *
+ * `rounds` is the number of rounds **including the one about to run**, so a cap of
+ * 2 allows rounds 1 and 2 and refuses 3.
+ *
+ * The refusal is `documented-stall`, and what its diagnosis can contain is narrower
+ * than the name suggests: the previous rounds' blockers are not persisted anywhere, so
+ * what survives a compaction is the round count. The `loop` skill states the gap; do
+ * not write this as if the blockers were available.
+ *
+ * It is deliberately NOT in `SKIP_CAUSES`: those are reasons an item was passed over
+ * during selection, and this is a reason a task ends. One vocabulary holding both
+ * would make every sentence about either one wrong.
+ */
+export const gateRoundVerdict = (rounds, max = DEFAULT_MAX_GATE_ROUNDS) => {
+  // A cap under 1 refuses the FIRST round, which turns the gate off rather than
+  // bounding it — the opposite of what this is for. Fail loudly on the
+  // configuration rather than quietly on every PR.
+  if (!Number.isInteger(max) || max < 1) {
+    throw new Error(
+      `maxGateRounds must be an integer of at least 1, got ${JSON.stringify(max)}. ` +
+        'A cap below 1 would refuse the first gate round, which disables the gate ' +
+        'instead of bounding it.',
+    );
+  }
+  const exceeded = rounds > max;
+  return { rounds, max, exceeded, stop: exceeded ? 'documented-stall' : null };
+};
+
 /**
  * Pick the next item, or explain why nothing was taken.
  *
  * The elevated tier is rationed by **spacing, not counting**: a per-run count is
- * meaningless when the run has no end. Never two elevated items back to back —
- * one unreviewed schema or permissions change is recoverable; a chain of them
- * compounding overnight is not.
+ * meaningless when the run has no end. Never two mechanism-touching elevated
+ * items back to back — one unreviewed schema or permissions change is
+ * recoverable; a chain of them compounding overnight is not.
  */
 export const selectNext = (tickets, { lastCompletedTier = null, triggersFired = null } = {}) => {
   const skipped = [];
@@ -285,15 +449,21 @@ export const selectNext = (tickets, { lastCompletedTier = null, triggersFired =
   for (const ticket of tickets) {
     const selection = selectionOf(ticket, { triggersFired });
     if (!selection.eligible) {
-      skipped.push({ id: ticket.id, reason: selection.reasons.join('; ') });
+      skipped.push({
+        id: ticket.id,
+        reason: selection.reasons.join('; '),
+        causes: selection.causes,
+      });
       continue;
     }
-    if (ticket.tier === 'elevated' && lastCompletedTier === 'elevated') {
+    if (ticket.tier === 'elevated' && !clearsSpacing(lastCompletedTier)) {
       skipped.push({
         id: ticket.id,
         reason:
-          'elevated, and the last completed item was elevated too — never two back ' +
-          'to back. Land a normal item on a healthy runtime first.',
+          `elevated, and the last completed change (${JSON.stringify(lastCompletedTier)}) ` +
+          'did not clear the ration — never two back to back. Land a normal item, or ' +
+          'an elevated change that is only prose, on a healthy runtime first.',
+        causes: ['spacing'],
       });
       continue;
     }
@@ -304,6 +474,129 @@ export const selectNext = (tickets, { lastCompletedTier = null, triggersFired =
   return { ticket, skipped, candidates: candidates.length };
 };
 
+/**
+ * Split the skipped records into the ones holding takeable work back and the
+ * ones that are simply out of play.
+ *
+ * 🔴 **A parked cause outranks a holding one, per record** — and this precedence
+ * is the whole mechanism, not a detail. An escalated item is left CLAIMED on
+ * purpose (`escalate` labels it and nothing more), so on a tracker-backed
+ * adapter it arrives carrying `['in-progress', 'escalated']`. Let the holding
+ * cause win and every escalated item reads as "another session will finish it" —
+ * an item no session is on, which only a human clears — and `queue-empty` is
+ * unreachable from the first escalation onward. That is the exact defect this
+ * split exists to remove, one label over.
+ *
+ * The rule generalises past that case: a parked cause says the item does not
+ * come back into play without a human, and that outlasts any condition which
+ * would clear on its own.
+ *
+ * A record with no cause this module recognises counts as **held**: it is the
+ * reading that stops rather than the one that declares the queue drained, and an
+ * unclassified skip is exactly where a wrong declaration would come from.
+ *
+ * Bounded by construction: one forward pass, no recursion, and every array it
+ * builds is bounded by the input it walks.
+ */
+const partitionSkipped = (skipped) => {
+  const held = [];
+  const parked = [];
+  for (const skip of skipped) {
+    const causes = Array.isArray(skip?.causes) ? skip.causes : [];
+    const parking = causes.find(
+      (cause) => SKIP_CAUSES.includes(cause) && !HOLDING_CAUSES.includes(cause),
+    );
+    if (parking) {
+      parked.push(parking);
+      continue;
+    }
+    held.push(causes.find((cause) => HOLDING_CAUSES.includes(cause)) ?? 'an unnamed filter');
+  }
+  return { held, parked };
+};
+
+/**
+ * "3 X, 1 Y" — a list of causes counted, as a partition.
+ *
+ * Each item counts ONCE, under the one cause it was classified by, so the parts
+ * foot to the total beside them. Counting it under every cause it carries would
+ * read as a breakdown and silently sum past that number.
+ *
+ * Bounded by construction: one forward pass, and a tally whose key set is the
+ * closed vocabulary plus one bucket for a record that carries no tag at all.
+ */
+const breakdownOf = (causes, label = (count, tag) => `${count} ${tag}`) => {
+  const tally = new Map();
+  for (const cause of causes) tally.set(cause, (tally.get(cause) ?? 0) + 1);
+  return [...tally.entries()]
+    .sort(([tagA, countA], [tagB, countB]) => countB - countA || tagA.localeCompare(tagB))
+    .map(([tag, count]) => label(count, tag))
+    .join(', ');
+};
+
+const heldBreakdown = (held) => breakdownOf(held, (count, tag) => `${count} held by ${tag}`);
+
+/**
+ * The parked pile, named rather than left to grow unseen.
+ *
+ * Reported beside the held count and never summed with it: they ask the owner
+ * for different things, and one number covering both would ask for neither.
+ *
+ * It names the causes the pile actually carries rather than the vocabulary it
+ * could have carried. A fixed list would announce `closed` — which no adapter
+ * can present, since every one of them drops closed items before selection —
+ * while staying silent about which of the reachable ones this pile is made of.
+ *
+ * It also stops at what it can see. How the pile GROWS differs per adapter (see
+ * `HOLDING_CAUSES` above), so a line claiming one mechanism would be false on
+ * another, and the stop line is not where that belongs.
+ */
+const parkedNote = (parked) =>
+  parked.length === 0
+    ? ''
+    : ` A further ${parked.length} item(s) are parked — ${breakdownOf(parked)}. ` +
+      'Those are not work this run can take and they wait on a human, never on ' +
+      'time.';
+
+/**
+ * The trigger remedies, composed from the tags actually present.
+ *
+ * 🔴 **Why this is a function and not a sentence.** The two trigger kinds hold an
+ * item back through different mechanisms and are freed by different acts: an
+ * `auto` item waits for a declaration to be RECORDED, a `human` item is never
+ * self-taken at all and only a human editing the item's own marker frees it.
+ * When one cause tag stood for both, every fixed sentence keyed off it was
+ * wrong for one kind — the clause was rewritten three times, each revision
+ * repairing one sub-case and leaving the other, until the tags were split. So
+ * the remedy now follows the pile: unreachable unless the tag that earns it is
+ * in it, which makes a one-sided line structurally unavailable rather than
+ * merely discouraged.
+ *
+ * The cost of getting this wrong is not a confusing sentence. Told to record a
+ * declaration for a `human` item, an operator runs a command that reports
+ * success, changes nothing, and — under an adapter whose ids are list positions
+ * — leaves a live record that arms whatever occupies that slot next.
+ */
+const triggerNote = (held) => {
+  const auto = held.includes('trigger-auto');
+  const human = held.includes('trigger-human');
+  if (!auto && !human) return '';
+  return (
+    ' A trigger is the exception, and the two kinds are freed differently:' +
+    (auto
+      ? ' a trigger-auto item waits for the declaration to be RECORDED — ' +
+        '`node .claude/scripts/run-state.mjs trigger <item-id>` — so waiting it ' +
+        'out waits forever;'
+      : '') +
+    (human
+      ? ' an item held as trigger-human is not freed by recording a declaration ' +
+        "— that does nothing here; only a human changing the item's own marker " +
+        'frees it;'
+      : '') +
+    ' both are declarations, not delays.'
+  );
+};
+
 /**
  * Should the whole run stop? Checked in severity order, because a regression must
  * not be reported as an empty queue.
@@ -314,6 +607,7 @@ export const selectNext = (tickets, { lastCompletedTier = null, triggersFired =
  */
 export const stopConditionOf = ({
   candidates = 0,
+  skipped = [],
   lastDeployVerdict = null,
   consecutiveEscalations = 0,
   killSwitch = false,
@@ -370,13 +664,29 @@ export const stopConditionOf = ({
     };
   }
   if (candidates === 0) {
+    const { held, parked } = partitionSkipped(skipped);
+    if (held.length > 0) {
+      return {
+        kind: 'nothing-selectable',
+        success: true,
+        why:
+          `${held.length} item(s) are takeable work held back right now — ` +
+          `${heldBreakdown(held)}.${parkedNote(parked)} This is NOT an empty queue, ` +
+          'and the two ask for opposite things: an empty queue wants refilling, ' +
+          'whereas this one still holds work. Spacing clears when a normal item ' +
+          'lands, a blocker when its item closes, in-progress when the other ' +
+          `session finishes.${triggerNote(held)} Otherwise the action is to ` +
+          'interleave or to wait, never to refill and never to invent work.',
+      };
+    }
     return {
       kind: 'queue-empty',
       success: true,
       why:
-        'no item survives the filters. This is a legitimate end of session, not an ' +
-        'invitation to refactor: **do not invent work**. Refilling the queue is the ' +
-        "owner's job.",
+        'no item survives the filters and nothing is merely held back — the queue ' +
+        `is genuinely out of work.${parkedNote(parked)} This is a legitimate end of ` +
+        'session, not an invitation to refactor: **do not invent work**. Refilling ' +
+        "the queue is the owner's job.",
     };
   }
   return null;
@@ -385,9 +695,10 @@ export const stopConditionOf = ({
 /**
  * The stable fingerprint of an improvement proposal.
  *
- * Under a scheduler against a finite queue the most common stop is "queue empty";
- * twenty such stops must produce ONE proposal with a count of twenty, not twenty
- * proposals. Dedupe by fingerprint, then increment.
+ * Under a scheduler against a finite queue the most common stops are the two that
+ * hand out nothing — "queue empty" and "nothing selectable"; twenty such stops
+ * must produce ONE proposal with a count of twenty, not twenty proposals. Dedupe
+ * by fingerprint, then increment.
  */
 export const fingerprintOf = ({ finding, part, change }) =>
   [finding, part, change]

package/templates/agent-os/universal/.claude/scripts/queue/gate-rounds.mjs

@@ -0,0 +1,160 @@
+/**
+ * How many times a branch has entered the review gate.
+ *
+ * 🔴 **Its own file, and that is the whole design.** The item that asked for this
+ * named `queue.state.json` — the file holding `lastCompletedTier` — as the place to
+ * put the count. A review round measured what that costs: `recordCompletedTier`
+ * writes that file whole, so either the two writers merge or the first close of any
+ * item deletes the round count of every branch still in gate. Merging was
+ * implemented, and then it turned out to be worse: a state file that fails to parse
+ * reads as `{}` to a merging writer, which then writes its snapshot back and the
+ * tier is **silently gone** — and a missing tier is the permissive value that lets a
+ * second elevated item straight through. A lost round costs one extra review; a lost
+ * tier disables the ration the queue is spaced by.
+ *
+ * Two files, one writer each. The counter cannot damage the ration and `state.mjs`
+ * goes back to owning its file outright — so a lost round is now the worst this
+ * mechanism can do, where before it could lose the tier.
+ *
+ * ⚠ **What that does NOT fix, measured rather than reasoned:** `recordGateRound` is
+ * read-modify-write with no lock. Eight concurrent calls on one counter recorded
+ * **four** rounds — the file is shared across every worktree of a repo by design
+ * (`gateRoundsPathFor`), so this is reachable whenever two loops run in one
+ * repository at once, not only in one directory. Each lost increment buys one extra
+ * allowed round. A lock is not worth it for that: the loop is sequential per task,
+ * and the failure is bounded and in the generous direction. What was worth fixing is
+ * the crash it came with — a fixed temp filename made the losers of that race fail
+ * with `ENOENT` on rename, reporting "could not run" for a condition nothing named.
+ */
+
+import { renameSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { mainCheckoutRoot } from './checkout.mjs';
+
+/**
+ * Where the counter lives, unless a caller names the file.
+ *
+ * The default lands in the MAIN checkout even when the gate runs inside a worktree
+ * — the same rule `state.mjs` follows, and for the same reason: a task's worktree is
+ * shorter-lived than the task.
+ */
+export const gateRoundsPathFor = (projectRoot) =>
+  join(mainCheckoutRoot(projectRoot), '.claude', 'gate-rounds.json');
+
+/**
+ * The counts, keyed by branch.
+ *
+ * An absent file is zero rounds — the normal state of a fresh checkout. A file that
+ * exists and does not parse is **refused**, not read as zero: reading it as zero
+ * hands the branch a full cap again, and it does so at the exact moment something is
+ * already wrong with the file.
+ */
+const readRounds = (file) => {
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return Object.create(null);
+    throw new Error(
+      `${file} exists but could not be read (${error?.code ?? 'unknown error'}), so the ` +
+        'gate rounds for this branch are unknown. Refusing rather than starting the ' +
+        'count again, which would hand this branch a full cap.',
+      { cause: error },
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${file} is not valid JSON, so the gate rounds cannot be read: ` +
+        `${String(error?.message ?? error).split('\n')[0]}. Delete the file to start ` +
+        'the count over — deliberately, rather than by accident.',
+      { cause: error },
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(
+      `${file} is valid JSON but not an object of branch counts, so the gate rounds ` +
+        'cannot be read. Expected `{ "<branch>": <positive integer> }`. Delete the ' +
+        'file to start the count over.',
+    );
+  }
+
+  // A single malformed entry is dropped rather than refused: one bad key costs that
+  // branch a fresh cap, while refusing would block every branch in the checkout.
+  //
+  // 🔴 `Object.create(null)`, not `{}`. A branch named `__proto__` or `constructor`
+  // otherwise resolves to an inherited value rather than a count, so the increment
+  // produced `"[object Object]1"` — a string, which every numeric comparison against
+  // the cap answers `false`, i.e. unlimited rounds. Absurd branch name, real class of
+  // defect, and the failure was silent.
+  const clean = Object.create(null);
+  for (const [branch, count] of Object.entries(parsed)) {
+    if (Number.isInteger(count) && count > 0) clean[branch] = count;
+  }
+  return clean;
+};
+
+/**
+ * The branch a count belongs to.
+ *
+ * 🔴 `HEAD` is refused, and it is the case this check exists for. On a detached
+ * checkout — mid-rebase, after `gh pr checkout` of a fork, in CI —
+ * `git rev-parse --abbrev-ref HEAD` prints the literal string `HEAD`, which is a
+ * non-empty string and would key one shared counter for every task in the
+ * directory. A review round found exactly that hole under a comment claiming it was
+ * closed.
+ */
+const requireBranch = (branch) => {
+  if (typeof branch !== 'string' || branch.trim() === '') {
+    throw new Error(
+      `a gate round is counted per branch, and the branch was ${JSON.stringify(branch)}.`,
+    );
+  }
+  if (branch.trim() === 'HEAD') {
+    throw new Error(
+      'the branch is the literal "HEAD", which is what a detached checkout reports. ' +
+        'Counting under it would share one budget across every task in this ' +
+        'directory. Check out the branch under review, or pass its name explicitly.',
+    );
+  }
+  return branch.trim();
+};
+
+/** How many rounds this branch has recorded. Zero when the file is absent. */
+export const gateRoundsFor = ({ branch, projectRoot, roundsPath } = {}) =>
+  readRounds(roundsPath ?? gateRoundsPathFor(projectRoot))[requireBranch(branch)] ?? 0;
+
+/**
+ * Count one round for this branch and return the new total.
+ *
+ * Write-then-rename, because a plain write leaves a window where the file on disk is
+ * half a JSON document — and the reader above refuses such a file, which would turn
+ * a crash mid-write into a gate nobody can run. `run-state.mjs` reached the same
+ * conclusion about the same class of file.
+ *
+ * The temp name carries the pid. A fixed `${file}.tmp` was measured failing: under
+ * concurrent calls the first rename consumed the shared temp file and the rest died
+ * with `ENOENT` on rename, which this command reports as "could not run" — a
+ * diagnosis for a cause nothing named. Per-pid temps make a concurrent loser lose
+ * only its increment, which is the bounded failure the docblock above states.
+ */
+export const recordGateRound = ({ branch, projectRoot, roundsPath } = {}) => {
+  const key = requireBranch(branch);
+  const file = roundsPath ?? gateRoundsPathFor(projectRoot);
+  const rounds = readRounds(file);
+  const next = (rounds[key] ?? 0) + 1;
+
+  // Spread into a null-prototype object for the same reason `readRounds` builds one:
+  // `{ ...rounds }` would give the result a prototype again, and `JSON.stringify`
+  // then writes a `__proto__` key that the next read cannot see as its own.
+  const updated = Object.assign(Object.create(null), rounds, { [key]: next });
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(updated, null, 2)}\n`);
+  renameSync(temp, file);
+
+  return { rounds: next };
+};

package/templates/agent-os/universal/.claude/scripts/queue/github-issues.mjs

@@ -15,6 +15,7 @@
 // because it is re-resolved from the blockers themselves on every selection.
 import { execFileSync } from 'node:child_process';
 import { duplicateOf, fingerprintOf, validateProposal } from './core.mjs';
+import { recordEscalation } from '../run-state.mjs';
 
 export const name = 'github-issues';
 
@@ -168,9 +169,12 @@ export const comment = (ticket, body) => {
  * selection cannot pick it up again. It stays OPEN and stays claimed — moving it
  * back to a selectable state is how one stuck task gets worked three times.
  */
-export const escalate = (ticket, diagnosis) => {
+export const escalate = (ticket, diagnosis, { env = process.env } = {}) => {
   ghText(['issue', 'comment', ticket.id, '--body', diagnosis]);
   ghText(['issue', 'edit', ticket.id, '--add-label', 'escalated']);
+  // Counted through the one recorder, never a counter of this adapter's own —
+  // "twice in a row" has to mean the same thing on every tracker.
+  recordEscalation(env.RIG_RUN_DIR);
   return { ok: true };
 };
 
@@ -208,7 +212,8 @@ export const triageItemFor = (proposal) => {
 /**
  * File the proposal — or increment the one already there.
  *
- * Under a scheduler against a finite queue the most common stop is "queue empty";
+ * Under a scheduler against a finite queue the most common stops are the two that
+ * hand out nothing — "queue empty" and "nothing selectable";
  * twenty such stops must produce one proposal with a count of twenty.
  */
 export const proposeTriage = (proposal, { existing = null } = {}) => {