create-agent-rig 0.4.0 → 0.6.0

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

@@ -14,7 +14,9 @@
 // be a snapshot that nothing updates when the blocker lands; this cannot go stale,
 // 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 { duplicateOf, fingerprintOf, lifecycleOf, ownerOfLabels, validateProposal } from './core.mjs';
+import { withAsOf } from './as-of.mjs';
+import { recordEscalation, recordTakeUp } from '../run-state.mjs';
 
 export const name = 'github-issues';
 
@@ -74,6 +76,11 @@ export const toTicket = (issue, states = {}) => {
     blocks: [],
     priority: priorityLabel ? Number(priorityLabel[1]) : 999,
     createdAt: issue.createdAt ?? null,
+    // The take-up marker for revalidation at SELECT: the tracker's own
+    // last-modified field, whose contract (moves on edits, comments and state
+    // changes) is assumed and not checked here. `null` when the listing did not
+    // carry it.
+    updatedAt: issue.updatedAt ?? null,
     // The body travels on the neutral shape so the hygiene checks live in one
     // place (core.mjs) instead of once per adapter. This adapter also parses it
     // internally for blocker links — the two readings are independent on
@@ -86,6 +93,10 @@ export const toTicket = (issue, states = {}) => {
       : labels.includes('trigger-human')
         ? 'human'
         : null,
+    // The repository this item belongs to (AR-132): `owner-<name>`, or null.
+    owner: ownerOfLabels(labels),
+    // The lifecycle and the scheduling flag (AR-144), read above the seam.
+    ...lifecycleOf(labels),
   };
 };
 
@@ -119,7 +130,7 @@ const ghText = (args) =>
 
 const ghJson = (args) => JSON.parse(ghText(args));
 
-const FIELDS = 'number,title,body,state,labels,url,createdAt';
+const FIELDS = 'number,title,body,state,labels,url,createdAt,updatedAt';
 
 // --- the adapter contract ------------------------------------------------------
 
@@ -145,21 +156,63 @@ export const listEligible = ({ limit = 100, issues = null } = {}) => {
 export const resolveBlockers = (ticket) => (ticket.blockedBy ?? []).filter((b) => !b.resolved);
 
 /** `To Do → In Progress` before the first file is edited, not when the PR opens. */
+/**
+ * Re-record the item's marker after a write of this adapter's own (AR-140) —
+ * the same rule and the same limit as `jira.mjs` › rebaseline: only writes
+ * made through this adapter re-baseline, and a read-back that fails is
+ * announced, never thrown.
+ */
+const rebaseline = (ticket) => {
+  const runDir = process.env.RIG_RUN_DIR;
+  if (!runDir) return;
+  try {
+    const after = ghJson(['issue', 'view', ticket.id, '--json', 'updatedAt']);
+    recordTakeUp(runDir, { id: ticket.id, updatedAt: after?.updatedAt ?? null });
+  } catch (error) {
+    process.stderr.write(
+      `#${ticket.id}: the write landed, but its marker was NOT re-recorded in ${runDir} — ` +
+        `${error.message}\n`,
+    );
+  }
+};
+
 export const claim = (ticket) => {
   ghText(['issue', 'edit', ticket.id, '--add-label', 'in-progress']);
+  rebaseline(ticket);
   return { ok: true };
 };
 
+/**
+ * One issue by number, closed included — `gh issue view` sees every state,
+ * where `listEligible` drops CLOSED for selection's sake. The offline `issues`
+ * seam is honoured. `blocks` is empty here: the cross-index needs the whole
+ * list, and a single view does not carry it.
+ */
+export const find = (id, { issues = null } = {}) => {
+  const raw = issues
+    ? (issues.find((issue) => String(issue.number) === String(id)) ?? null)
+    : ghJson(['issue', 'view', String(id), '--json', FIELDS]);
+  return raw ? toTicket(raw, {}) : null;
+};
+
 export const close = (ticket, { prUrl = null } = {}) => {
   const note = prUrl ? `Landed in ${prUrl}.` : 'Closed by the run.';
   ghText(['issue', 'comment', ticket.id, '--body', note]);
   ghText(['issue', 'close', ticket.id]);
-  ghText(['issue', 'edit', ticket.id, '--remove-label', 'in-progress']);
-  return { ok: true };
+  // Read back, never inferred: `gh issue close` exits 0 on an issue that was
+  // already closed, or that a workflow reopened a moment later (AR-135). The
+  // claim label goes only once the read-back says CLOSED — a close that did
+  // not land leaves the item claimed, exactly as it was found.
+  const after = ghJson(['issue', 'view', ticket.id, '--json', 'state']);
+  const transitioned = String(after?.state ?? '').toUpperCase() === 'CLOSED';
+  if (transitioned) ghText(['issue', 'edit', ticket.id, '--remove-label', 'in-progress']);
+  rebaseline(ticket);
+  return { ok: true, transitioned };
 };
 
 export const comment = (ticket, body) => {
   ghText(['issue', 'comment', ticket.id, '--body', body]);
+  rebaseline(ticket);
   return { ok: true };
 };
 
@@ -168,9 +221,13 @@ 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']);
+  rebaseline(ticket);
+  // 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 };
 };
 
@@ -192,8 +249,10 @@ export const triageItemFor = (proposal) => {
       `- **part to change** — ${proposal.part}`,
       `- **proposed change** — ${proposal.change}`,
       `- **how the next run proves it** — ${proposal.proof}`,
+      ...(proposal.measured ? [`- **measured** — ${proposal.measured}`, `- **inferred** — ${proposal.inferred}`] : []),
       '',
       `fingerprint: ${fingerprint}`,
+      ...(proposal.asOf ? [`asOf: ${proposal.asOf}`] : []),
       '',
       'The loop proposes; the owner patches. Self-applying a change to its own',
       'rulebook is how an unattended run drifts irreversibly — and it collides with',
@@ -208,18 +267,21 @@ 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 } = {}) => {
-  const item = triageItemFor(proposal);
-  const found =
+/** The proposals on file, as `{ id, body }` — every `triage`-labelled issue. */
+export const listProposals = ({ existing = null } = {}) =>
+  (
     existing ??
-    ghJson(['issue', 'list', '--label', 'triage', '--state', 'all', '--limit', '100', '--json', FIELDS]);
-  const duplicate = duplicateOf(
-    item,
-    found.map((issue) => ({ id: String(issue.number), body: issue.body })),
-  );
+    ghJson(['issue', 'list', '--label', 'triage', '--state', 'all', '--limit', '100', '--json', FIELDS])
+  ).map((issue) => ({ id: String(issue.number), body: issue.body }));
+
+export const proposeTriage = (rawProposal, { existing = null } = {}) => {
+  const proposal = withAsOf(rawProposal);
+  const item = triageItemFor(proposal);
+  const duplicate = duplicateOf(item, listProposals({ existing }));
 
   if (duplicate) {
     ghText([
@@ -232,6 +294,23 @@ export const proposeTriage = (proposal, { existing = null } = {}) => {
     return { ok: true, incremented: String(duplicate.number), item };
   }
 
-  ghText(['issue', 'create', '--title', item.title, '--body', item.body, '--label', 'triage']);
-  return { ok: true, filed: item.title, item };
+  const url = ghText(['issue', 'create', '--title', item.title, '--body', item.body, '--label', 'triage']);
+  // The proposal's own baseline (AR-138), as in jira.mjs: `gh issue create`
+  // prints the new issue's URL, whose last segment is its number; the marker
+  // is read back with `gh issue view`. No run directory → nothing recorded.
+  // Best-effort for the same reason as there: the issue exists by now, and a
+  // throw would make the caller file it again.
+  const id = /\/(\d+)\s*$/.exec(String(url ?? ''))?.[1] ?? null;
+  if (id && process.env.RIG_RUN_DIR) {
+    try {
+      const after = ghJson(['issue', 'view', id, '--json', 'updatedAt']);
+      recordTakeUp(process.env.RIG_RUN_DIR, { id, updatedAt: after?.updatedAt ?? null });
+    } catch (error) {
+      process.stderr.write(
+        `proposeTriage: #${id} is filed, but its baseline was NOT recorded in ` +
+          `${process.env.RIG_RUN_DIR} — ${error.message}\n`,
+      );
+    }
+  }
+  return { ok: true, filed: item.title, id, item };
 };