create-agent-rig 0.8.0 → 0.9.0

package/templates/agent-os/universal/.claude/hooks/guard-subagent-model.mjs

@@ -0,0 +1,234 @@
+// PreToolUse hook (Claude Code's Agent tool): a subagent whose project
+// definition pins its model is never dispatched with a call-site `model`.
+//
+// Why it exists. Claude Code takes a subagent's model from the per-invocation
+// `model` parameter FIRST, and only then from the definition's `model:` line
+// (Claude Code's sub-agents documentation, "model resolution"). A pin is
+// therefore only as strong as every call site: the generator's
+// docs/capability-evidence.json (absent in a generated rig) records a pinned
+// agent that ran the call-site model instead — mechanism `subagent-model-pin`,
+// surface `Agent tool call-site model, without guard-subagent-model`. Which
+// model a role reads with is the routing policy's decision
+// (docs/decisions/subagent-routing.md), not one dispatch's.
+//
+// What "pinned" means here: `<project>/.claude/agents/<subagent_type>.md` is a
+// regular file whose leading frontmatter carries a `model:` line with a value
+// other than `inherit`. The project root is CLAUDE_PROJECT_DIR, else the working
+// directory. One leading byte-order mark is not content and is skipped.
+//
+// The three outcomes (.claude/rules/invariants.md):
+// - allow — nothing it can read, another event, no call-site model, or an
+//   ad-hoc subagent: no `subagent_type`, a built-in, a name that is not a plain
+//   file name (`plugin:agent`, `../x`), no such file, a path that is not a
+//   regular file (a directory, a FIFO — opened without waiting, never read), or
+//   no pin in it;
+// - block — a call-site model for a pinned agent;
+// - refuse to inspect — `model` or `subagent_type` PRESENT in a shape other
+//   than a string (resend it as one), or a frontmatter that does not close
+//   within MAX_HEAD_BYTES (a bound crossed).
+// An error opening or reading the agent file fails open, like every guard here.
+//
+// Bounded work: one non-blocking open, one fstat, one read of at most
+// MAX_HEAD_BYTES + 1 bytes, one frontmatter match, and one pass over its lines
+// with a prefix test per line. Nothing recurses or rescans.
+//
+// Limits, stated so nobody relies on cover that is not here:
+// - project agents only. A user-level or plugin agent that pins a model is not
+//   a role of this project, and its call-site model is allowed;
+// - the file is found by the dispatched name, so a project agent whose
+//   frontmatter `name` differs from its file name is not matched;
+// - `model:` is read as a frontmatter line, not through a YAML parser, so a pin
+//   spelled another YAML way (a quoted key) is not seen.
+// Pinned in the generator's test/template/subagent-routing-hooks.test.ts
+// (absent in a generated rig) › "blocks a call-site model on a project agent
+// that pins one, and says to re-dispatch without it", › "never resolves %s to a
+// project agent file, so the call is allowed", › "refuses an agent file whose
+// frontmatter does not close within the read bound, and names the bound", ›
+// "allows a call-site model without waiting when the agent path is not a regular
+// file", › "reads a pin in an agent file that starts with a byte-order mark", ›
+// "echoes a model pinned in the agent file bounded and escaped" (the bound) and
+// › "escapes a control byte inside the echoed part of both model names".
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readHookInput } from './lib/hook-input.mjs';
+
+/** How much of an agent file is read to find its frontmatter. */
+export const MAX_HEAD_BYTES = 64 * 1024;
+
+/** How much of a model name a refusal repeats, from either side of the comparison. */
+const MAX_ECHOED_MODEL = 64;
+
+/** A name that can only ever be a file directly under `.claude/agents/`. */
+const AGENT_FILE_NAME = /^[A-Za-z0-9_-]{1,128}$/;
+
+/**
+ * Open without blocking: a FIFO at the agent path would otherwise hold the open
+ * until a writer appears. Windows has no such flag and no such file there.
+ */
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NONBLOCK ?? 0);
+
+const ALLOW = Object.freeze({ outcome: 'allow' });
+
+/** The shape word for a value, bounded: never the value itself. */
+const shapeOf = (value) => {
+  if (Array.isArray(value)) return 'an array';
+  const type = typeof value;
+  return type === 'object' ? 'an object' : `a ${type}`;
+};
+
+/**
+ * A model name as a refusal may print it: at most MAX_ECHOED_MODEL characters,
+ * through JSON.stringify — which escapes C0 control bytes such as ESC, and
+ * leaves other non-ASCII characters (C1 controls, bidi overrides) as they are.
+ */
+const echoed = (model) => JSON.stringify(model.slice(0, MAX_ECHOED_MODEL));
+
+const unreadable = (field, value, expected) => ({
+  outcome: 'refuse',
+  message:
+    `BLOCKED — ${field} is present as ${shapeOf(value)}, and this guard reads ${expected}. ` +
+    'An input it cannot read is refused, never allowed: whether this dispatch overrides a ' +
+    'pinned model is decided by reading it (.claude/rules/invariants.md, "Refusing to ' +
+    `inspect is a third outcome"). Resend the Agent call with ${field} as ${expected}.`,
+});
+
+/**
+ * The first MAX_HEAD_BYTES of a regular file, and whether it went on past them;
+ * null when the path is absent, is not a regular file, or cannot be read.
+ */
+function readHead(file) {
+  let fd;
+  try {
+    fd = openSync(file, OPEN_FLAGS);
+    if (!fstatSync(fd).isFile()) return null;
+    const buffer = Buffer.alloc(MAX_HEAD_BYTES + 1);
+    let filled = 0;
+    while (filled < buffer.length) {
+      const read = readSync(fd, buffer, filled, buffer.length - filled, null);
+      if (read === 0) break;
+      filled += read;
+    }
+    return {
+      text: buffer.subarray(0, Math.min(filled, MAX_HEAD_BYTES)).toString('utf8'),
+      cut: filled > MAX_HEAD_BYTES,
+    };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // nothing left to release
+      }
+    }
+  }
+}
+
+/**
+ * `{ kind: 'pinned', model }`, `{ kind: 'none' }`, or `{ kind: 'unbounded' }`
+ * when a frontmatter opens and does not close inside the bytes that were read.
+ */
+function pinOf({ text: raw, cut }) {
+  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  if (!/^---\r?\n/.test(text)) return { kind: 'none' };
+  // A head that was cut may end in the middle of a line, so only a closer
+  // followed by a newline counts there; an uncut head may end at the closer.
+  const closed = (
+    cut
+      ? /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/
+      : /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/
+  ).exec(text);
+  if (!closed) return cut ? { kind: 'unbounded' } : { kind: 'none' };
+  for (const line of closed[1].split(/\r?\n/)) {
+    if (!line.startsWith('model:')) continue;
+    const value = line.slice('model:'.length).trim();
+    const quoted =
+      value.length >= 2 && (value[0] === '"' || value[0] === "'") && value.at(-1) === value[0];
+    const model = quoted ? value.slice(1, -1) : value;
+    return model !== '' && model !== 'inherit' ? { kind: 'pinned', model } : { kind: 'none' };
+  }
+  return { kind: 'none' };
+}
+
+/** The verdict for one hook payload, judged against the project at `root`. */
+export function judge(input, root) {
+  if (input === null || typeof input !== 'object' || input.hook_event_name !== 'PreToolUse') {
+    return ALLOW;
+  }
+  const toolInput = input.tool_input;
+  if (toolInput === undefined || toolInput === null) return ALLOW;
+  if (typeof toolInput !== 'object' || Array.isArray(toolInput)) {
+    return unreadable('tool_input', toolInput, 'an object');
+  }
+
+  const model = toolInput.model;
+  if (model === undefined || model === null) return ALLOW;
+  if (typeof model !== 'string') return unreadable('tool_input.model', model, 'a string');
+  if (model.trim() === '') return ALLOW;
+
+  const name = toolInput.subagent_type;
+  if (name === undefined || name === null) return ALLOW;
+  if (typeof name !== 'string') return unreadable('tool_input.subagent_type', name, 'a string');
+  if (!AGENT_FILE_NAME.test(name)) return ALLOW;
+
+  const relative = `.claude/agents/${name}.md`;
+  const head = readHead(path.join(root, '.claude', 'agents', `${name}.md`));
+  if (head === null) return ALLOW;
+  const pin = pinOf(head);
+  if (pin.kind === 'unbounded') {
+    return {
+      outcome: 'refuse',
+      message:
+        `BLOCKED — ${relative} opens a frontmatter that does not close within the first ` +
+        `${MAX_HEAD_BYTES} bytes, the limit this guard reads, so it cannot tell whether ` +
+        `\`${name}\` pins its model. Close the frontmatter near the top of the file, or ` +
+        're-dispatch without `model`.',
+    };
+  }
+  if (pin.kind !== 'pinned') return ALLOW;
+  return {
+    outcome: 'block',
+    message:
+      `BLOCKED — \`${name}\` pins its model in ${relative} (${echoed(pin.model)}), and this ` +
+      `dispatch passes model ${echoed(model)}, which Claude Code would run instead.\n` +
+      'Re-dispatch without `model`: the agent definition decides which model a role runs on. ' +
+      "Changing a role's model is a policy change — make it in the agent definition, in a " +
+      'reviewed change, never in one call (docs/decisions/subagent-routing.md).',
+  };
+}
+
+/**
+ * Whether this file is being run as a script rather than imported — the realpath
+ * on both sides, as `inject-rules.mjs` explains, so a symlinked checkout still runs.
+ */
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+}
+
+function main() {
+  let verdict;
+  try {
+    const input = readHookInput();
+    if (input === null) return 0;
+    verdict = judge(input, process.env.CLAUDE_PROJECT_DIR || process.cwd());
+  } catch {
+    return 0;
+  }
+  if (verdict.outcome === 'allow') return 0;
+  process.stderr.write(`${verdict.message}\n`);
+  return 2;
+}
+
+if (invokedDirectly()) {
+  process.exit(main());
+}

package/templates/agent-os/universal/.claude/hooks/lib/edit-input.mjs

@@ -49,9 +49,73 @@ const MAX_PATCH_SECTIONS = 128;
 const MAX_MULTI_EDITS = 256;
 const MAX_PATCH_PATH_COMPONENTS = 512;
 
+/**
+ * The surfaces this normaliser answers for. A tool outside the set is one the
+ * hook does not understand, and the refusal below must not reach it: a guard
+ * that blocks payloads it was never asked about is a guard that gets deleted.
+ */
+const EDIT_TOOL_NAMES = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'apply_patch']);
+
+/**
+ * The one refusal for a container this file cannot read, on every surface it
+ * owns. `apply_patch` keeps its own wording because the shape it expects is a
+ * different shape — a patch string — and a remedy naming an object would be
+ * advice its caller cannot act on.
+ */
+const unreadableToolInput = (toolName) =>
+  toolName === 'apply_patch'
+    ? {
+        filePath: '',
+        fragment: '',
+        inspectionRefusal:
+          'the apply_patch command arrived in a shape this guard cannot read — it is a ' +
+          'string, or a list of strings, and nothing else. Nothing was inspected, so ' +
+          'nothing about this patch is vouched for.',
+        remedy: 'Send the command as a patch string, or a list of strings.',
+        appliesToAll: true,
+      }
+    : {
+        filePath: '',
+        fragment: '',
+        inspectionRefusal:
+          'the tool_input arrived in a shape this guard cannot read — it is an object ' +
+          'carrying the edit fields, and nothing else. Nothing was inspected, so nothing ' +
+          'about this edit is vouched for.',
+        remedy: 'Send the tool_input as an object carrying the edit fields.',
+        appliesToAll: true,
+      };
+
 export function editFragments(input) {
   const toolName = input?.tool_name;
-  const toolInput = input?.tool_input ?? {};
+  const rawToolInput = input?.tool_input;
+  // 🔴 **"I could not look" is not "there was nothing to look at" — and this
+  // file used to answer both ways depending on which arm you reached.**
+  // `?? {}` substitutes only for null/undefined, so a `tool_input` PRESENT as a
+  // string, a number or an array flowed on as that value: every field read came
+  // back `undefined`, and the Write/Edit/NotebookEdit arms returned a fragment
+  // with an empty path and empty text — which every consuming guard reads as a
+  // clean edit. Measured on master `6589db36`: a `tool_input` that is a string
+  // carrying a credential exited 0 through Write, Edit, MultiEdit and
+  // NotebookEdit, while the SAME shape through `apply_patch` exited 2. The
+  // divergence was between arms of this one file, which is why the contract
+  // belongs here rather than in each guard (RP-85, applying RP-80's ruling).
+  //
+  // ⚠ **ABSENT stays fail-open, and the difference is the whole rule.**
+  // `.claude/rules/invariants.md`: a field that is simply absent is the case the
+  // guard has nothing to judge — it must allow, exactly as a `Write` carrying no
+  // content does. A field PRESENT in a shape the guard does not accept is the
+  // case where it was handed something and could tell it could not read it,
+  // which is the one thing reporting is for. Getting these backwards costs a
+  // credential in either direction.
+  if (
+    EDIT_TOOL_NAMES.has(toolName) &&
+    rawToolInput !== null &&
+    rawToolInput !== undefined &&
+    (typeof rawToolInput !== 'object' || Array.isArray(rawToolInput))
+  ) {
+    return [unreadableToolInput(toolName)];
+  }
+  const toolInput = rawToolInput ?? {};
   if (toolName === 'Write' || toolName === 'Edit') {
     return [
       {
@@ -107,21 +171,10 @@ export function editFragments(input) {
   // they exited 1 with a stack trace, which neither harness treats as blocking, so
   // a crash here was an ALLOW. A `tool_input` that is not an object is the same
   // case as a `command` whose container this guard cannot read: detected, not
-  // readable, refused.
-  if (typeof toolInput !== 'object' || toolInput === null || Array.isArray(toolInput)) {
-    return [
-      {
-        filePath: '',
-        fragment: '',
-        inspectionRefusal:
-          'the apply_patch command arrived in a shape this guard cannot read — it is a ' +
-          'string, or a list of strings, and nothing else. Nothing was inspected, so ' +
-          'nothing about this patch is vouched for.',
-        remedy: 'Send the command as a patch string, or a list of strings.',
-        appliesToAll: true,
-      },
-    ];
-  }
+  // readable, refused. That check used to sit HERE, guarding this one arm; it is
+  // now the first thing `editFragments` does, for every surface in
+  // `EDIT_TOOL_NAMES`, so `toolInput` is an object by the time this line runs and
+  // `in` cannot throw (RP-85). One mechanism, one implementation.
   if (!('command' in toolInput)) return [];
   if (
     typeof rawCommand !== 'string' &&
@@ -140,22 +193,12 @@ export function editFragments(input) {
     // "a crashed guard that blocks everything gets deleted within the hour" —
     // and this branch is neither. Two opposite answers to one question, ten
     // lines apart, was the real defect.
-    return [
-      {
-        filePath: '',
-        fragment: '',
-        inspectionRefusal:
-          'the apply_patch command arrived in a shape this guard cannot read — it is a ' +
-          'string, or a list of strings, and nothing else. Nothing was inspected, so ' +
-          'nothing about this patch is vouched for.',
-        // 🔴 The remedy travels WITH the refusal that earns it. It was chosen by
-        // `/shape/i.test(reason)` in six copies — correct only by coincidence of
-        // wording, so rewording the reason silently restored the retry loop this
-        // remedy exists to replace. One field, one place.
-        remedy: 'Send the command as a patch string, or a list of strings.',
-        appliesToAll: true,
-      },
-    ];
+    // 🔴 The remedy travels WITH the refusal that earns it. It was chosen by
+    // `/shape/i.test(reason)` in six copies — correct only by coincidence of
+    // wording, so rewording the reason silently restored the retry loop this
+    // remedy exists to replace. One field, one place — and since RP-85 that
+    // place is `unreadableToolInput`, shared with the four edit surfaces.
+    return [unreadableToolInput(toolName)];
   }
   const command = typeof rawCommand === 'string' ? rawCommand : rawCommand.join('\n');
   if (command.length > MAX_PATCH_CHARACTERS) {

package/templates/agent-os/universal/.claude/hooks/warn-subagent-routing.mjs

@@ -0,0 +1,120 @@
+// SessionStart hook (Claude Code): says out loud when this session's
+// environment may keep the pinned subagent routing from holding.
+//
+// The pins live in each agent definition (`model:`, `effort:`) and in the
+// shipped settings (`env.CLAUDE_CODE_SUBAGENT_MODEL`). Four conditions are
+// invisible from inside the rulebook, and each is reported:
+// - CLAUDE_CODE_SUBAGENT_MODEL_FORCE is set: Claude Code applies one model to
+//   every subagent and ignores each definition's `model:` (its 2.1.257
+//   changelog);
+// - CLAUDE_CODE_EFFORT_LEVEL is set: its level replaced a definition's
+//   `effort:` in a live run — the generator's docs/capability-evidence.json
+//   (absent in a generated rig), mechanism `subagent-effort-pin`, surface
+//   `environment: CLAUDE_CODE_EFFORT_LEVEL=low`;
+// - Claude Code is older than MINIMUM_CLAUDE_CODE_VERSION: until 2.1.251,
+//   CLAUDE_CODE_SUBAGENT_MODEL overrode an agent definition's `model:` (its
+//   2.1.251 changelog), so the shipped unnamed default replaced every model pin;
+// - the version cannot be read: then whether the pins hold cannot be confirmed.
+//
+// The version is read from AI_AGENT, which Claude Code sets for its subprocesses
+// (its 2.1.120 changelog) and which a SessionStart hook's environment was
+// observed to carry (the same evidence file, mechanism
+// `claude-code-version-signal`). Its shape,
+// `claude-code_<major>-<minor>-<patch>_<role>`, is observed and not documented —
+// so a value this hook cannot parse is reported as an unknown version, never
+// taken for a supported one.
+//
+// It warns and never blocks: exit 0 always, the warning on stdout, which Claude
+// Code adds to the session's context at SessionStart. An empty variable counts
+// as unset. The rationale is docs/decisions/subagent-routing.md.
+//
+// Pinned in the generator's test/template/subagent-routing-hooks.test.ts
+// (absent in a generated rig) › "warns when %s is set, and never blocks the
+// session", › "warns on a Claude Code older than 2.1.251 and names the minimum"
+// and › "warns that it could not determine the version when %s".
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { readHookInput } from './lib/hook-input.mjs';
+
+/** The first Claude Code release in which an agent definition's `model:` outranks the env default. */
+export const MINIMUM_CLAUDE_CODE_VERSION = '2.1.251';
+
+const PIN_REPLACING_VARIABLES = [
+  [
+    'CLAUDE_CODE_SUBAGENT_MODEL_FORCE',
+    "replaces the `model:` every agent definition pins with one model for all subagents",
+  ],
+  ['CLAUDE_CODE_EFFORT_LEVEL', "replaces the `effort:` every agent definition pins with its own level"],
+];
+
+const VERSION = /^claude-code_(\d{1,6})-(\d{1,6})-(\d{1,6})(?:_|$)/;
+
+const numbers = (version) => version.split('.').map(Number);
+
+const olderThan = (found, minimum) => {
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (found[index] !== minimum[index]) return found[index] < minimum[index];
+  }
+  return false;
+};
+
+/** Every routing problem this environment has, as sentences; empty when there is none. */
+export function routingProblems(env) {
+  const problems = [];
+  for (const [variable, effect] of PIN_REPLACING_VARIABLES) {
+    const value = env[variable];
+    if (typeof value === 'string' && value !== '') {
+      problems.push(`${variable} is set: it ${effect}. Unset it for those pins to hold.`);
+    }
+  }
+  const agent = typeof env.AI_AGENT === 'string' ? VERSION.exec(env.AI_AGENT) : null;
+  if (agent === null) {
+    problems.push(
+      `could not determine the Claude Code version from AI_AGENT, so it cannot be confirmed ` +
+        `that the model pins hold: they need Claude Code ${MINIMUM_CLAUDE_CODE_VERSION} or later.`,
+    );
+  } else {
+    const found = [Number(agent[1]), Number(agent[2]), Number(agent[3])];
+    if (olderThan(found, numbers(MINIMUM_CLAUDE_CODE_VERSION))) {
+      problems.push(
+        `Claude Code ${found.join('.')} is older than ${MINIMUM_CLAUDE_CODE_VERSION}: before it, ` +
+          "CLAUDE_CODE_SUBAGENT_MODEL overrides every agent definition's `model:`. Upgrade Claude Code.",
+      );
+    }
+  }
+  return problems;
+}
+
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+}
+
+function main() {
+  try {
+    const input = readHookInput();
+    if (input === null || input.hook_event_name !== 'SessionStart') return 0;
+    const problems = routingProblems(process.env);
+    if (problems.length === 0) return 0;
+    process.stdout.write(
+      '[agent-os] WARNING — the pinned subagent routing may not hold in this session:\n' +
+        problems.map((problem) => `- ${problem}`).join('\n') +
+        '\nA gate may run on a model or effort the routing policy did not choose ' +
+        '(docs/decisions/subagent-routing.md).\n',
+    );
+  } catch {
+    // a broken warning must never make the session unusable
+  }
+  return 0;
+}
+
+if (invokedDirectly()) {
+  process.exit(main());
+}

package/templates/agent-os/universal/.claude/rules/workflow.md

@@ -38,6 +38,11 @@ subagent with a fresh context, and why the `pr-ship` gate fans reviewers out
 instead of self-checking. This isolation is load-bearing, not ceremony — do
 not "optimise" it away by reviewing in the authoring session.
 
+A reviewer whose definition pins its model is never dispatched with a call-site
+`model`: which model reads a change is the routing policy's decision, not the
+dispatching session's, and `guard-subagent-model` refuses the override
+(`docs/decisions/subagent-routing.md`).
+
 ## PR flow
 
 This applies **once the project has a remote and CI checks** — a freshly

package/templates/agent-os/universal/.claude/scripts/preflight.mjs

@@ -26,10 +26,10 @@ import { fileURLToPath } from 'node:url';
 // cycle, because preflight is the only scripted brake check and had no test.
 import { brakeIsOn } from './stop-flag.mjs';
 import { readRevalidationContract } from './lib/claim-records.mjs';
+import { loadConfig, optionsWithPlanPath, resolveAdapter } from './queue/index.mjs';
 
 /** The items this script cannot check: judgement, or a call worth more than it saves. */
 export const UNCHECKED = [
-  'the queue is reachable through its adapter (`node .claude/scripts/queue/index.mjs next`)',
   'no stray worktree from a dead session that this run might mistake for its own',
   'a budget is declared for this run, and it is written down somewhere the run can re-read',
 ];
@@ -136,6 +136,30 @@ export const checkDetectionContract = (projectRoot) => {
   }
 };
 
+// See test/template/preflight-queue.test.ts (absent in a generated rig) ›
+// "reads exactly one adapter listing without selecting, claiming, or writing queue and run files".
+export const checkQueue = async (projectRoot) => {
+  try {
+    const configPath = join(projectRoot, '.claude', 'queue.json');
+    const config = loadConfig(configPath, { strictRead: true });
+    const adapterName = config.adapter ?? 'plan-md';
+    const adapter = await resolveAdapter(adapterName);
+    await adapter.listEligible(optionsWithPlanPath(config.options, configPath));
+    return { ok: true, detail: `queue readable through ${adapterName}` };
+  } catch (error) {
+    const diagnostic = Array.from(String(error?.message ?? error), (character) => {
+      const code = character.codePointAt(0);
+      return code < 0x20 || (code >= 0x7f && code <= 0x9f)
+        ? `\\u${code.toString(16).padStart(4, '0')}`
+        : character;
+    }).join('');
+    return {
+      ok: false,
+      detail: `could not read queue: ${diagnostic}`,
+    };
+  }
+};
+
 /** The last deploy must have concluded successfully — never start on a broken runtime. */
 export const checkLastDeploy = ({ workflow = 'deploy' } = {}) => {
   try {
@@ -157,8 +181,7 @@ export const checkLastDeploy = ({ workflow = 'deploy' } = {}) => {
 
 /**
  * STOP on any hard failure; CAUTION on anything that is not a clean pass; GO only
- * when every scripted item genuinely passed. The three unscripted items are still
- * the reader's.
+ * when every scripted item genuinely passed. Unscripted checks remain the reader's.
  *
  * `stale` and `unknown` both give CAUTION but are never merged into one word:
  * "I looked and it is stale" is actionable, "I could not look" is not, and neither
@@ -216,6 +239,7 @@ if (invokedDirectly()) {
     killSwitch: checkKillSwitch(),
     runDirNotExported: checkRunDirNotExported(),
     detectionContract: checkDetectionContract(projectRoot),
+    queue: await checkQueue(projectRoot),
     defaultBranchFresh: checkDefaultBranchFresh(),
     lastDeploy: checkLastDeploy(),
   };

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

@@ -25,9 +25,26 @@
  * 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.
+ * Pinned by the generator's `test/template/concurrent-sessions.test.ts`
+ * (absent in a generated rig) › "eight concurrent recordGateRound calls all exit 0
+ * and leave one parseable counter between one and eight".
+ *
+ * ⚠ **And a second crash, Windows-only, measured on the same race (RP-120):** a
+ * rename over a file another process holds open is refused there with `EPERM`, for
+ * exactly as long as the handle is open — a reader's `readFileSync` is enough. Eight
+ * racing callers lost one to it in four rounds of thirty, and each loser left its
+ * temp file behind. So the rename is retried within a fixed budget
+ * (`RENAME_BUDGET_MS`: the pauses between attempts never exceed it; the rename
+ * calls themselves add their own wall time), and a loser that still cannot rename
+ * removes its temp file and reports the code and the file rather than a bare
+ * `EPERM`. That is a bounded retry, not a lock: the count can still lose an
+ * increment, and nothing waits on a holder past the budget. Pinned by the
+ * generator's `test/template/gate-rounds.test.ts` (absent in a generated rig) ›
+ * "retries the rename while another process holds the counter open, and still counts the round"
+ * and › "gives up past its budget, removes its temp file, keeps the old count, and names the code and the file".
  */
 
-import { renameSync, readFileSync, writeFileSync } from 'node:fs';
+import { renameSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { mainCheckoutRoot } from './checkout.mjs';
@@ -154,7 +171,58 @@ export const recordGateRound = ({ branch, projectRoot, roundsPath } = {}) => {
   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);
+  replaceWithRetry(temp, file);
 
   return { rounds: next };
 };
+
+// How many times the rename is tried, and how long each retry waits.
+const RENAME_ATTEMPTS = 20;
+const RENAME_BACKOFF_MS = 10;
+/** The whole budget a caller can spend pausing on a held-open counter. */
+export const RENAME_BUDGET_MS = RENAME_ATTEMPTS * RENAME_BACKOFF_MS;
+
+const RETRIED_CODES = new Set(['EPERM', 'EBUSY']);
+
+// A synchronous pause: this module is synchronous end to end (the CLI counts a round
+// and exits), and `Atomics.wait` on a throwaway buffer is the one sleep that shape
+// allows without a spin.
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+/**
+ * Rename `temp` over `file`, retrying a Windows-style refusal within the budget.
+ *
+ * Every attempt past the last, and every failure of another kind, ends the same way:
+ * the temp file is removed so the counter's directory holds nothing but the counter,
+ * and the error names the file and the code — the CLI prints that as "could not run",
+ * which pr-ship reads as a command failure to retry, not as an exhausted cap.
+ */
+const replaceWithRetry = (temp, file) => {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      renameSync(temp, file);
+      return;
+    } catch (error) {
+      const code = error?.code ?? 'unknown error';
+      if (RETRIED_CODES.has(code) && attempt < RENAME_ATTEMPTS) {
+        pause(RENAME_BACKOFF_MS);
+        continue;
+      }
+      // The cleanup must not displace the diagnosis: a temp file that cannot be
+      // removed (held open too, on Windows) is reported beside the rename
+      // failure, and the rename failure stays the error the caller sees.
+      let cleanup = 'and the temp file was removed';
+      try {
+        rmSync(temp, { force: true });
+      } catch (removal) {
+        cleanup = `but the temp file ${temp} could not be removed (${removal?.code ?? 'unknown error'})`;
+      }
+      throw new Error(
+        `${file} could not be replaced after ${attempt} attempt${attempt === 1 ? '' : 's'} ` +
+          `(${code}): another process may be holding it open. The round was NOT counted ` +
+          `${cleanup}; run the command again.`,
+        { cause: error },
+      );
+    }
+  }
+};