create-agent-rig 0.4.0 → 0.5.0

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

@@ -5,6 +5,7 @@
 //   node .claude/scripts/queue/index.mjs next --json
 //   node .claude/scripts/queue/index.mjs list            # every item, with skip reasons
 //   node .claude/scripts/queue/index.mjs hygiene         # stale labels and link anomalies
+//   node .claude/scripts/queue/index.mjs gate-round --branch <b>   # count a gate round
 //
 // The adapter comes from `.claude/queue.json` (`{"adapter": "plan-md"}`) and
 // defaults to `plan-md`, which is the only adapter that works in a freshly
@@ -12,8 +13,13 @@
 // that silently reads the wrong queue is worse than one that refuses to start.
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { hygieneOf, selectNext, stopConditionOf } from './core.mjs';
+// One resolver, imported rather than re-derived: writer and reader disagreeing
+// about which checkout they are in is the whole of the worktree defect. It lives
+// apart from `state.mjs` so the read path does not drag the tier computation —
+// and `detect-missed-gate.mjs` behind it — into a CLI that never calls either.
+import { mainCheckoutRoot } from './checkout.mjs';
 
 const ADAPTERS = {
   'plan-md': './plan-md.mjs',
@@ -33,7 +39,7 @@ export const resolveAdapter = async (adapterName) => {
   return import(new URL(modulePath, import.meta.url).href);
 };
 
-export const COMMANDS = ['next', 'list', 'hygiene'];
+export const COMMANDS = ['next', 'list', 'hygiene', 'gate-round'];
 
 /**
  * A missing config is the normal state of a fresh project. A config that exists
@@ -60,11 +66,158 @@ export const loadConfig = (configPath) => {
   }
 };
 
+/**
+ * The state file that travels with a config: `<name>.json` → `<name>.state.json`.
+ *
+ * Derived from the config path rather than from the project root on purpose. The
+ * two must stay a pair: a run pointed at a temp config by `--config` would
+ * otherwise read the developer's own leftover state and let a tier from an
+ * unrelated checkout decide its selection.
+ */
+export const statePathFor = (configPath) => configPath.replace(/(\.json)?$/, '.state.json');
+
+/**
+ * The project root a config path implies, or `null` when it implies none.
+ *
+ * A config inside a directory named `.claude` names a project: the rig puts it
+ * there, so its parent is the root. Anything else — `--config /tmp/x.json`, a
+ * config nested for a test fixture — is a bare file with no project around it,
+ * and this returns `null` so the caller keeps whatever default it had.
+ *
+ * 🔴 Deliberately NOT `join(dirname(configPath), '..')`, which assumes every
+ * config sits in a `.claude` directory: pointed at `<dir>/.claude-queue.json` it
+ * climbs a level out of the project and looks for the plan in the parent.
+ */
+export const projectRootOfConfig = (configPath) => {
+  const dir = dirname(configPath);
+  return basename(dir) === '.claude' ? dirname(dir) : null;
+};
+
+/**
+ * The adapter options the CLI hands down, with a plan path that does not depend
+ * on the directory the command was typed in.
+ *
+ * 🔴 The asymmetry this closes: this file resolves its config from
+ * `import.meta.url`, so the config is found from any directory — while
+ * `plan-md`'s default is the bare relative `'PLAN.md'`, resolved against `cwd`.
+ * Running the CLI from a subdirectory therefore found the adapter and then
+ * reported `queue-unreadable`, which a run reads as a broken queue rather than as
+ * a wrong directory.
+ *
+ * Two things are left exactly as they were, and both are load-bearing. An
+ * explicit `options.planPath` still wins. And when the config implies no project
+ * root, nothing is injected — so `plan-md`'s own `'PLAN.md'` still resolves
+ * against the caller's cwd, which is the right answer when the adapter is
+ * imported directly rather than through this CLI, as the `loop` skill does for
+ * `proposeTriage`.
+ */
+export const optionsWithPlanPath = (options, configPath) => {
+  const root = projectRootOfConfig(configPath);
+  if (options?.planPath || root === null) return { ...options };
+  return { ...options, planPath: join(root, 'PLAN.md') };
+};
+
+/**
+ * Every tier a state file may carry, and the reason there are four.
+ *
+ * `state.mjs` writes three of them: `normal`, and the elevated tier split into
+ * `elevated-prose` and `elevated-mechanism` — only the last of which spaces the
+ * next item (`core.mjs`). The fourth, the bare `elevated`, is what a state file
+ * written before that split still holds; it stays **readable** because a
+ * checkout that upgrades mid-run would otherwise refuse to select at all, and
+ * `core.mjs` reads it restrictively, so the legacy value rations exactly as it
+ * did when it was written.
+ */
+const KNOWN_TIERS = ['normal', 'elevated', 'elevated-prose', 'elevated-mechanism'];
+
+/**
+ * Per-checkout state, kept OUT of the composed config.
+ *
+ * The config is a template-layer file: a runtime value written into it is drift
+ * here and an upgrade conflict in a generated project. So the tier of the last
+ * closed item lands beside it, in a gitignored file.
+ *
+ * Missing is not an error — it means no item has closed yet, and selection
+ * proceeds with no spacing. Present-and-unparseable IS: the tier is then
+ * *unknown*, and the silent reading of unknown is `null`, which is the
+ * permissive value that lets a second elevated item straight through. That is
+ * the exact failure this state file exists to end, so it refuses instead.
+ */
+export const loadState = (statePath) => {
+  let raw;
+  try {
+    raw = readFileSync(statePath, 'utf8');
+  } catch (error) {
+    // 🔴 ONLY a genuinely absent file means "nothing has closed yet". A bare
+    // `catch` here read EACCES, a directory at the path, and a file left by a
+    // container run under another uid as "absent" — each of them silently
+    // yielding the permissive `null`, with nothing printed. One failed write
+    // would have disabled the ration for good, and no adversary is needed.
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return {};
+    throw new Error(
+      `${statePath} exists but could not be read (${error?.code ?? 'unknown error'}), ` +
+        'so the last completed tier is unknown. Refusing rather than continuing: ' +
+        'unknown reads as "nothing has closed yet", which is the value that lets a ' +
+        'second elevated item through.',
+      { cause: error },
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${statePath} exists but is not valid JSON, so the last completed tier cannot ` +
+        `be read: ${String(error?.message ?? error).split('\n')[0]}. Delete the file ` +
+        'if you are unsure — an absent state means "nothing has closed yet", which is ' +
+        'safe; a tier that cannot be read would silently disable the elevated ration.',
+      { cause: error },
+    );
+  }
+
+  // Syntax is not shape. `"elevated"`, `["elevated"]`, `123` and `"Elevated"` all
+  // parse, and a state file shaped like any of them carries no tier at all — the
+  // dereference below answers `undefined`, which reads as "nothing has closed
+  // yet" and hands out an elevated item while the file looks like a working one.
+  // (`core.mjs` now holds on an unrecognised tier rather than shrugging, but a
+  // top-level array or number never reaches it as a tier in the first place.)
+  // A top-level `null` was worse still: it parsed, then threw a raw TypeError
+  // from the dereference, past the message that says the file is safe to delete.
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(
+      `${statePath} is valid JSON but not a state object, so the last completed tier ` +
+        'cannot be read. Expected `{ "lastCompletedTier": "normal" | "elevated-prose" ' +
+        '| "elevated-mechanism" }` — the legacy `"elevated"` is still accepted, and ' +
+        'held. ' +
+        'Delete the file if you are unsure — an absent state means "nothing has ' +
+        'closed yet", which is safe.',
+    );
+  }
+
+  // `null` is allowed and means exactly what an absent file means: nothing has
+  // closed yet. It is the honest spelling of an absence, and refusing it would
+  // protect nothing — deleting the file has the identical effect.
+  const tier = parsed.lastCompletedTier;
+  if (tier !== undefined && tier !== null && !KNOWN_TIERS.includes(tier)) {
+    throw new Error(
+      `${statePath} carries lastCompletedTier: ${JSON.stringify(tier)}, which is not ` +
+        `one of ${KNOWN_TIERS.map((t) => `"${t}"`).join(' | ')}. A tier outside the ` +
+        'vocabulary rations on a value nobody wrote, so it would report a working ' +
+        'state file while the spacing rule ran on a guess. Delete the file if you ' +
+        'are unsure.',
+    );
+  }
+
+  return parsed;
+};
+
 const parseArgs = (argv) => {
-  const args = { command: argv[0] ?? 'next', json: false, config: null };
+  const args = { command: argv[0] ?? 'next', json: false, config: null, branch: null };
   for (let i = 1; i < argv.length; i += 1) {
     if (argv[i] === '--json') args.json = true;
     else if (argv[i] === '--config') args.config = argv[++i];
+    else if (argv[i] === '--branch') args.branch = argv[++i];
   }
   return args;
 };
@@ -118,21 +271,193 @@ if (invokedDirectly()) {
     process.exit(1);
   }
 
+  // 🔴 **`gate-round` returns before the tracker is ever touched, and that is
+  // load-bearing rather than an optimisation.** `pr-ship` calls this once per
+  // round, and every other command below reaches the adapter — so routing this one
+  // through the normal path would spend a network call per gate round and, worse,
+  // would refuse to count a round while the tracker is unreachable. The counter is
+  // a local file and a local config; a Jira outage must not hand a run unlimited
+  // rounds.
+  if (args.command === 'gate-round') {
+    try {
+      // 🔴 Inside the `try`, and a review round is why. Left outside it, a rig whose
+      // `.claude/scripts/` predates this CLI printed a raw `ERR_MODULE_NOT_FOUND`
+      // and exited 1 — which `pr-ship` step 0 would have read as "rounds
+      // exhausted" and escalated a healthy item on. This file already records that
+      // exact lesson about `resolveAdapter` fifty lines below; the reason it
+      // repeated is that the lesson was written as prose and not as a test.
+      const { gateRoundVerdict } = await import('./core.mjs');
+      const { recordGateRound, gateRoundsPathFor } = await import('./gate-rounds.mjs');
+
+      const configPath = args.config ?? join(projectRoot, '.claude', 'queue.json');
+      const config = loadConfig(configPath);
+      // An explicit `--config` keeps its counter beside it, so a run pointed at a
+      // temp config never touches this checkout's real counts.
+      const roundsPath = args.config
+        ? configPath.replace(/(\.json)?$/, '.gate-rounds.json')
+        : gateRoundsPathFor(projectRoot);
+
+      // 🔴 Validate the cap BEFORE counting. A review round measured what the other
+      // order costs: with `maxGateRounds: 0` every attempt recorded a round and then
+      // exited 1, while this command's own message told the caller to fix the cause
+      // and run step 0 again — so three attempts at a broken config left the branch
+      // at three rounds and the next honest call refused a healthy item. A failed
+      // run must not spend budget, and the message below must not have to lie about
+      // whether it did.
+      const verdictFor = (rounds) => gateRoundVerdict(rounds, config.options?.maxGateRounds);
+      verdictFor(0);
+
+      const { rounds } = recordGateRound({ branch: args.branch, roundsPath });
+      const verdict = verdictFor(rounds);
+
+      if (!verdict.exceeded) {
+        process.stdout.write(
+          `gate round ${verdict.rounds} of ${verdict.max} on ${args.branch}.\n` +
+            (verdict.rounds === verdict.max
+              ? '  This is the last round this branch gets. If it holds again, the item ' +
+                'is escalated rather than re-reviewed.\n'
+              : ''),
+        );
+        process.exit(0);
+      }
+
+      process.stderr.write(
+        `GATE ROUNDS EXHAUSTED — ${verdict.rounds} rounds on ${args.branch}, cap is ` +
+          `${verdict.max}: ${verdict.stop}.\n` +
+          '  Do not run another round. The item stops here and goes back to a human ' +
+          'with the round count and whatever the last gate reported — the fixes are ' +
+          'not converging, and another pass buys a full reviewer fan-out to discover ' +
+          'that again.\n' +
+          '  Raising the cap to get one more pass on THIS item is the move this ' +
+          'refusal exists to prevent.\n',
+      );
+      process.exit(2);
+    } catch (error) {
+      // 🔴 Exit 1, never 2, and the message says so. Exit 2 means one thing only —
+      // the rounds are spent — because `pr-ship` acts on it by ending the task. A
+      // broken config, an unreadable counter or a detached checkout must not be
+      // read as a converging-failure stall.
+      process.stderr.write(
+        `gate-round could not run: ${error.message}\n` +
+          '  This is NOT an exhausted cap (that is exit 2). Fix the cause and run step ' +
+          '0 again: a bad config, a bad cap or a detached checkout is refused before ' +
+          'any round is counted, so retrying costs nothing.\n',
+      );
+      process.exit(1);
+    }
+  }
+
+  // A missing module is NOT read as "no state". A run that could not read its
+  // state would silently lose the escalation streak and the regression verdict
+  // — the two conditions that exist to stop it — so this fails closed, into a
+  // message the operator can act on.
+  //
+  // 🔴 **Loaded unconditionally, and ahead of the adapter, because the adapters
+  // import it statically.** An earlier version loaded it dynamically and only
+  // behind `RIG_RUN_DIR`, reasoning that a rig carrying an older
+  // `.claude/scripts/` should still get a readable message. That reasoning was
+  // sound and the code did not deliver it: all three adapters now
+  // `import { recordEscalation } from '../run-state.mjs'`, so a rig missing the
+  // module died inside `resolveAdapter` below and the operator saw a raw
+  // `Cannot find module` naming an adapter. The refusal was unreachable — and
+  // its test passed anyway, because the module's own filename satisfied the
+  // pattern it matched on. The load lives here; the READ stays behind the
+  // declaration, because a session with no run directory has no state to read
+  // and must keep working exactly as before.
+  let readState;
+  let stopInputsOf;
+  try {
+    ({ readState, stopInputsOf } = await import('../run-state.mjs'));
+  } catch (error) {
+    process.stderr.write(
+      `run state: ${error.message}\n` +
+        '  the run state module could not be loaded, so the escalation streak and the ' +
+        'deploy verdict cannot be read. Those are stop conditions, and a run that ' +
+        'cannot read them must not select work.\n',
+    );
+    process.exit(1);
+  }
+
   let config;
+  let state;
   let adapter;
+  // Declared out here because the plan path is derived from it further down.
+  let configPath;
   try {
-    config = loadConfig(args.config ?? join(projectRoot, '.claude', 'queue.json'));
+    configPath = args.config ?? join(projectRoot, '.claude', 'queue.json');
+    config = loadConfig(configPath);
+    // An explicit `--config` keeps its own state beside it, verbatim: a run
+    // pointed at a temp config must not pick up this checkout's real tier.
+    // Without one, the state comes from the MAIN checkout, so a selection made
+    // inside a worktree sees what a close made anywhere recorded.
+    state = loadState(
+      args.config
+        ? statePathFor(configPath)
+        : join(mainCheckoutRoot(projectRoot), '.claude', 'queue.state.json'),
+    );
     adapter = await resolveAdapter(config.adapter ?? 'plan-md');
   } catch (error) {
     process.stderr.write(`${error.message}\n`);
     process.exit(1);
   }
 
+  // 🔴 The run-level stop is decided BEFORE the queue is read, because those
+  // conditions are not about the queue. A run that has escalated twice in a row
+  // has hit a systemic wall, and a run that deployed a regression must start no
+  // new work on top of it — asking the tracker first would spend a network call
+  // and, worse, would report `queue-unreadable` for an unreachable tracker when
+  // the truthful answer is that this run was already over.
+  //
+  // The values come from the run's own state file rather than from the
+  // session's memory, which is what three of `stopConditionOf`'s parameters
+  // were waiting for: every branch was live, and nothing ever supplied them.
+  //
+  // The fourth, `killSwitch`, is still not passed here and that is deliberate —
+  // `guard-bash` denies the merge at the tool layer and preflight reads the flag,
+  // so a second answer to "is the brake on" would be the disagreement
+  // `invariants.md` forbids. Selection therefore does NOT stop on the brake, and
+  // the `loop` skill tells the run to keep checking it between tasks.
+  //
+  const runState = process.env.RIG_RUN_DIR ? readState(process.env.RIG_RUN_DIR) : {};
+  let stopInputs;
+  try {
+    // Read through the module that owns the vocabulary, never field by field
+    // here: a value the reader cannot interpret must not arrive as "no stop",
+    // and deciding that at the call site is how the two halves drift.
+    stopInputs = stopInputsOf(runState);
+  } catch (error) {
+    process.stderr.write(
+      `${error.message}\n  the run declared a state file this cannot act on, so no ` +
+        'item is selected. Stop conditions read from it, and an unreadable one is ' +
+        'not the same as an absent one.\n',
+    );
+    process.exit(1);
+  }
+  const runStop = stopConditionOf({
+    // `candidates: 1` says "not the empty-queue case" — the queue has not been
+    // read yet and must not be reported on here. Only the conditions that
+    // outrank it can fire from this call.
+    candidates: 1,
+    ...stopInputs,
+  });
+  if (runStop) {
+    // `renderNext`, not a second copy of its format — an operator reading two
+    // differently-worded stop lines has no way to know they came from one rule.
+    process.stdout.write(
+      args.json ? `${JSON.stringify({ stop: runStop }, null, 2)}\n` : renderNext(null, runStop),
+    );
+    // The exit code follows `stop.success`, exactly as the empty-queue path
+    // does. A budget stop is a clean end of session — reporting it as a failure
+    // would tell a wrapper that the run broke, and `--json` already says
+    // `"success": true` right beside the code that contradicted it.
+    process.exit(runStop.success ? 0 : 1);
+  }
+
   let tickets;
   try {
     // Awaited so an adapter may be async (jira) or plain (plan-md, github-issues)
     // without the CLI caring which.
-    tickets = await adapter.listEligible(config.options ?? {});
+    tickets = await adapter.listEligible(optionsWithPlanPath(config.options, configPath));
   } catch (error) {
     // Never fall back to memory or to a stale copy for a queue.
     const stop = stopConditionOf({ queueReadable: false });
@@ -157,16 +482,96 @@ if (invokedDirectly()) {
   }
 
   const result = selectNext(tickets, {
-    lastCompletedTier: config.lastCompletedTier ?? null,
-    triggersFired: config.triggersFired ?? null,
+    // The state file wins: it is what a close actually recorded. A tier left in
+    // the config is a hand-written hint at best, and it is the composed file, so
+    // it cannot be the live value.
+    lastCompletedTier: state.lastCompletedTier ?? config.lastCompletedTier ?? null,
+    // Same precedence, for the same reason as the tier above: `queue.json` is
+    // composed by the sync script and drift-checked, so declaring a trigger
+    // fired there means editing a generated file — and the declaration is a
+    // fact about THIS run, not about the rig's configuration.
+    //
+    // The config keeps working as a fallback rather than being dropped: nothing
+    // in this repository or its templates ever writes the key, but a rig owner
+    // who hand-added one would otherwise find their auto-trigger items silently
+    // unselectable, and an item that stops being offered announces itself
+    // nowhere.
+    //
+    // Replacement, not a merge: a per-key merge would make a stale config entry
+    // impossible to retract, so "not this time" would again require editing the
+    // generated file this move exists to get out of.
+    triggersFired: runState.triggersFired ?? config.triggersFired ?? null,
   });
-  const stop = result.ticket ? null : stopConditionOf({ candidates: 0 });
+  // The skipped records travel with the count: without them "nothing left" and
+  // "everything left is held back" both print as an empty queue, and only one of
+  // the two means the queue needs refilling.
+  const stop = result.ticket
+    ? null
+    : stopConditionOf({ candidates: 0, skipped: result.skipped });
 
   if (args.command === 'list') {
     process.stdout.write(`${JSON.stringify({ tickets, ...result }, null, 2)}\n`);
     process.exit(0);
   }
 
+  // 🔴 A journal nothing calls records nothing. Selection is a gate — it decides
+  // what the run works on and why every other item was passed over — so this is
+  // the call site the run journal ships with, rather than a writer nobody
+  // invokes.
+  //
+  // It writes only when the run DECLARED its directory. Inventing one here would
+  // make this CLI a second owner of the `.claude/runs/<run-id>/` convention, and
+  // a default derived from `projectRoot` would land the trace inside the very
+  // template tree this repository publishes.
+  const runDir = process.env.RIG_RUN_DIR;
+  if (runDir) {
+    let journal = null;
+    try {
+      journal = await import('../run-journal.mjs');
+      journal.recordDecision({
+        runDir,
+        gate: 'item-selection',
+        verdict: result.ticket ? `taken ${result.ticket.id}` : `stopped ${stop.kind}`,
+        why: result.ticket ? result.ticket.title : stop.why,
+        // The edge is where the clock is read: the journal itself takes `now` as
+        // an argument, which is what keeps its records reproducible.
+        now: new Date().toISOString(),
+      });
+    } catch (error) {
+      // 🔴 Two failures wearing one face, and treating them alike was a defect
+      // this gate caught. The journal asks the module which one this is — never
+      // the message text, which would put the decision in two files and let them
+      // drift the day someone improves the wording.
+      // `?.` would guard a MISSING module and not a missing export. A rig can
+      // carry a run journal older than this CLI — `upgrade` leaves a
+      // locally-edited copy beside a new caller — and calling through to an
+      // absent export crashed the CLI inside its own error handler: a raw stack
+      // trace instead of the failure it was reporting.
+      const classify = journal?.isTraceExhausted;
+      if (typeof classify === 'function' && classify(error)) {
+        // The trace is over and the work is not. This journal cannot accept
+        // another record — it is append-only and every write re-reads it — so
+        // exiting here would make one collision between two sessions leave the
+        // queue unselectable FOREVER. Loud on stderr, and the selection still
+        // goes out on stdout, because the queue was never the thing that failed.
+        process.stderr.write(
+          `run journal: ${error.message}\n` +
+            `  the selection below was NOT recorded in ${runDir}. This run's trace ends ` +
+            'here; the queue is fine, and a new run needs a new run directory.\n',
+        );
+      } else {
+        // The other half: the declaration is empty, its directory is not there,
+        // the path is not a directory, or the journal module is missing. Each is
+        // the run pointing at something that was never set up — one `mkdir` or
+        // one corrected variable away — and continuing would produce a run with
+        // no trace at all, so this half does stop the selection. (A directory
+        // deleted mid-run lands here too, and the same `mkdir` restores it.)
+        process.stderr.write(`run journal: ${error.message}\n`);
+        process.exit(1);
+      }
+    }
+  }
+
   process.stdout.write(
     args.json
       ? `${JSON.stringify({ ticket: result.ticket, skipped: result.skipped, stop }, null, 2)}\n`

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

@@ -18,6 +18,7 @@
 //     { "adapter": "jira", "options": { "project": "ABC" } }
 //     { "adapter": "jira", "options": { "jql": "project = ABC AND ..." } }
 import { duplicateOf, fingerprintOf, validateProposal } from './core.mjs';
+import { recordEscalation } from '../run-state.mjs';
 
 export const name = 'jira';
 
@@ -91,7 +92,13 @@ export const toTicket = (issue) => {
     url: issue.self ?? null,
     state: category === 'done' ? 'closed' : category === 'indeterminate' ? 'in-progress' : 'open',
     labels,
-    tier: labels.includes('human-review') ? 'elevated' : 'normal',
+    // The marker is `elevated`, the same word the plan-md adapter reads out of an
+    // `[elevated]` line — one name for one fact, so `core.mjs` rations the same
+    // way whichever tracker the item came from. It is deliberately NOT
+    // `human-review`: on a Jira board that is a workflow label meaning "a human
+    // is looking at it", which is a different claim entirely, and reading it as
+    // the tier rations the queue on a signal that means something else.
+    tier: labels.includes('elevated') ? 'elevated' : 'normal',
     blockedBy,
     blocks,
     priority: PRIORITY[String(fields.priority?.name ?? '').toLowerCase()] ?? 999,
@@ -108,17 +115,38 @@ export const toTicket = (issue) => {
   };
 };
 
+/**
+ * The lanes selection never takes, named once so the query and the post-filter
+ * below cannot drift apart (`invariants.md`: one mechanism, one implementation).
+ *
+ * - `triage` is the loop's own filed proposals. Excluding them only by the
+ *   absence of a ready marker means one careless hand adding that marker closes
+ *   the loop's feedback path into its own input.
+ * - `operator-queue` is the owner's lane. An item sitting there is work a HUMAN
+ *   has taken, so the loop picking one up is two sessions on one task.
+ */
+export const EXCLUDED_LABELS = ['triage', 'operator-queue'];
+
 /**
  * The selection query.
  *
- * `labels != triage` is belt and braces, and it is deliberate: excluding a
- * proposal only by the absence of a ready marker means one careless hand adding
- * that marker closes the loop's feedback path into its own input. Excluded
- * explicitly, an item carrying BOTH markers is still unselectable.
+ * Both lanes are excluded here by label, in the adapter's own filter rather than
+ * in an `options.jql` a reinstall would drop.
  *
  * ⚠ JQL gotcha that makes the parenthesised form necessary: `labels != x` does
  * **not** match issues whose labels field is empty. Without `OR labels IS EMPTY`
  * this query would silently skip every unlabelled item — which is most of them.
+ * Both exclusions therefore live INSIDE that one group; a second, unguarded
+ * exclusion anywhere in the query reintroduces the hole while still reading right.
+ *
+ * ⚠ And the group stays FLAT — `labels != a AND labels != b OR labels IS EMPTY`,
+ * not `labels NOT IN (a, b) OR …`. Both forms are valid JQL and both were run
+ * against a live Jira, returning identical result sets — so this is a
+ * readability choice with no behaviour attached, and switching back would be
+ * behaviour-neutral. Flat wins because the `NOT IN` form's nested parentheses
+ * hide the `IS EMPTY` guard from any reader — human or test — that matches
+ * innermost groups. `AND` binds tighter than `OR` in JQL, so the flat form means
+ * `(a AND b) OR empty`, which is the intent.
  */
 export const buildJql = ({ project = null, jql = null } = {}) => {
   if (jql) return jql;
@@ -129,9 +157,10 @@ export const buildJql = ({ project = null, jql = null } = {}) => {
         'is worse than refusing to start.',
     );
   }
+  const excluded = EXCLUDED_LABELS.map((label) => `labels != "${label}"`).join(' AND ');
   return (
     `project = ${project} AND statusCategory != Done ` +
-    'AND (labels != triage OR labels IS EMPTY) ' +
+    `AND (${excluded} OR labels IS EMPTY) ` +
     'ORDER BY priority DESC, created ASC'
   );
 };
@@ -179,7 +208,13 @@ const request = async (route, { method = 'GET', body = null, env = process.env }
 // `description` is requested because the triage dedupe matches the fingerprint
 // inside it. Without it the dedupe silently never matched, so every "queue empty"
 // stop filed a fresh issue instead of incrementing the one already there.
-const FIELDS = 'summary,status,labels,priority,created,issuelinks,description';
+//
+// A LIST, not a comma-joined string: the replacement endpoint takes its arguments
+// in a JSON body, where `fields` is an array. Measured, because the failure mode
+// decides how hard this is to notice: sending the joined form the retired query
+// parameter wanted answers `400 Invalid request payload`, not a 200 with empty
+// fields. It fails loudly, so a wrong value here cannot sit undetected.
+const FIELDS = ['summary', 'status', 'labels', 'priority', 'created', 'issuelinks', 'description'];
 
 // --- the adapter contract ------------------------------------------------------
 
@@ -198,15 +233,39 @@ export const listEligible = async ({
   // `issues` is the offline seam: the mapping is pure, so every shape it has to
   // handle is testable without a network or a credential.
   const response = issues ? { issues } : await search({ project, jql, limit, env });
-  return response.issues.map(toTicket).filter((ticket) => ticket.state !== 'closed');
+  return (
+    response.issues
+      .map(toTicket)
+      .filter((ticket) => ticket.state !== 'closed')
+      // Deliberately a SECOND enforcement of the same list the query already
+      // carries, and only here: `core.mjs` drops `triage` itself, with its own
+      // stated reason, but nothing downstream knows about `operator-queue`. This
+      // filter is what still holds when the query is bypassed — an `options.jql`
+      // override, or a board whose labels were renamed. Both read EXCLUDED_LABELS,
+      // so the two can disagree only by someone editing one of them.
+      .filter((ticket) => !ticket.labels.some((label) => EXCLUDED_LABELS.includes(label)))
+  );
 };
 
+/**
+ * 🔴 `POST /rest/api/3/search/jql`, never `GET /rest/api/3/search` — the latter
+ * was retired by Atlassian and answers `410 Gone`. Measured against a live Jira,
+ * with the same credential answering `200` on `/rest/api/3/myself`, so it is the
+ * path and not the auth. Both searching call sites (`listEligible` and the
+ * `proposeTriage` dedupe) come through here, which is why one fix covers both.
+ *
+ * Not handled here on purpose: the response also carries `nextPageToken` for
+ * cursor pagination, so a board with more open issues than `limit` still loses
+ * its tail — as does a retry policy and a request timeout. Those belong together
+ * in one change; half a pagination interface with nothing testing it is worse
+ * than none.
+ */
 export const search = async ({ project = null, jql = null, limit = 100, env = process.env } = {}) =>
-  request(
-    `/rest/api/3/search?jql=${encodeURIComponent(buildJql({ project, jql }))}` +
-      `&maxResults=${limit}&fields=${FIELDS}`,
-    { env },
-  );
+  request('/rest/api/3/search/jql', {
+    method: 'POST',
+    body: { jql: buildJql({ project, jql }), maxResults: limit, fields: FIELDS },
+    env,
+  });
 
 export const resolveBlockers = (ticket) => (ticket.blockedBy ?? []).filter((b) => !b.resolved);
 
@@ -272,6 +331,9 @@ export const escalate = async (ticket, diagnosis, { env = process.env } = {}) =>
     body: { update: { labels: [{ add: 'escalated' }] } },
     env,
   });
+  // 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 };
 };