create-agent-rig 0.8.0 → 0.9.1

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/core.mjs

@@ -485,6 +485,18 @@ export const hygieneOf = (ticket, { owner = null } = {}) => {
     };
   }
 
+  const removed = removedDependencyIn(body, ticket);
+  if (removed) {
+    return {
+      kind: 'link-contradicted-by-body',
+      id: ticket.id,
+      why:
+        `body line ${removed.line} declares "The Blocks link ${removed.source} -> ` +
+        `${removed.target} is removed", but that dependency is still carried in ` +
+        `${removed.direction}. Reconcile the declaration and link before relying on either`,
+    };
+  }
+
   return null;
 };
 
@@ -502,6 +514,37 @@ export const hygieneOf = (ticket, { owner = null } = {}) => {
  */
 const BLOCKER_IN_BODY = /^[-*\t ]{0,4}(?:blocked by|depends on|blocker)[ \t:]{0,8}[#A-Za-z0-9]/im;
 
+// See test/template/queue.test.ts (absent in a generated rig) ›
+// "reports its carried outgoing Blocks link that its own body says was removed".
+const REMOVAL_ID = '(?:[A-Z][A-Z0-9_]{0,31}-[0-9]{1,16}|#[0-9]{1,16})';
+const REMOVED_DEPENDENCY = new RegExp(
+  `^[ \\t]{0,4}(?:[-*][ \\t]{1,4})?The[ \\t]{1,8}Blocks[ \\t]{1,8}link[ \\t]{1,8}` +
+    `(${REMOVAL_ID})[ \\t]{1,8}->[ \\t]{1,8}(${REMOVAL_ID})[ \\t]{1,8}is[ \\t]{1,8}removed` +
+    '(?=[ \\t]{0,8}(?:$|[.;(]))',
+  'i',
+);
+const dependencyId = (value) => String(value).replace(/^#/, '').toUpperCase();
+const removedDependencyIn = (body, ticket) => {
+  const ownId = dependencyId(ticket.id);
+  const outgoingIds = new Set((ticket.blocks ?? []).map(dependencyId));
+  const incomingIds = new Set((ticket.blockedBy ?? []).map((link) => dependencyId(link.id)));
+  const lines = body.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = REMOVED_DEPENDENCY.exec(lines[index]);
+    if (!match) continue;
+    const [, source, target] = match;
+    const outgoing =
+      dependencyId(source) === ownId &&
+      outgoingIds.has(dependencyId(target));
+    const incoming =
+      dependencyId(target) === ownId &&
+      incomingIds.has(dependencyId(source));
+    if (outgoing || incoming)
+      return { source, target, line: index + 1, direction: outgoing ? 'blocks' : 'blockedBy' };
+  }
+  return null;
+};
+
 /** The item saying, in its own words, that it was broken into other items. */
 const SPLIT_IN_BODY = /\b(?:split into|split up into|broken into|broken up into|superseded by|subtasks?:)/i;
 

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 },
+      );
+    }
+  }
+};

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

@@ -12,7 +12,7 @@
 // defaults to `plan-md`, which is the only adapter that works in a freshly
 // generated project. An unknown adapter is a hard error, never a fallback: a loop
 // that silently reads the wrong queue is worse than one that refuses to start.
-import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { lstatSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { basename, dirname, join } from 'node:path';
 import {
@@ -57,11 +57,19 @@ export const COMMANDS = ['next', 'list', 'hygiene', 'gate-round', 'board'];
  * trailing comma in `queue.json` made the loop read a different queue than the one
  * configured, which is the exact failure this file's header refuses for adapters.
  */
-export const loadConfig = (configPath) => {
+export const loadConfig = (configPath, { strictRead = false } = {}) => {
   let raw;
   try {
     raw = readFileSync(configPath, 'utf8');
-  } catch {
+  } catch (error) {
+    if (
+      strictRead &&
+      (error?.code !== 'ENOENT' || lstatSync(configPath, { throwIfNoEntry: false }) !== undefined)
+    ) {
+      throw new Error(`${configPath} could not be read (${error?.code ?? 'unknown error'})`, {
+        cause: error,
+      });
+    }
     return {};
   }
   let parsed;
@@ -70,7 +78,7 @@ export const loadConfig = (configPath) => {
   } catch (error) {
     throw new Error(
       `${configPath} exists but is not valid JSON, so the configured queue cannot be ` +
-        `read: ${String(error?.message ?? error).split('\n')[0]}. Fix the file — ` +
+        'read. Fix the file — ' +
         'silently reading a different queue is worse than refusing to start.',
       { cause: error },
     );

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

@@ -680,6 +680,23 @@ export const escalate = async (ticket, diagnosis, { env = process.env } = {}) =>
   return { ok: true };
 };
 
+/**
+ * Jira refuses a summary longer than this, and creates nothing: `400
+ * {"errors":{"summary":"Summary can't exceed 255 characters."}}` (RP-121). The
+ * summary is therefore a prefix; the full `change` stays in the description,
+ * where the fingerprint lives too, so the dedupe does not depend on the cut.
+ * The cut never leaves half of a surrogate pair behind. Pinned in
+ * `test/template/queue-jira.test.ts` › "bounds the POSTed summary so a
+ * 2186-character change still files, keeping the full text in the body".
+ */
+const MAX_SUMMARY_LENGTH = 255;
+
+const boundedSummary = (text) => {
+  if (text.length <= MAX_SUMMARY_LENGTH) return text;
+  const cut = text.slice(0, MAX_SUMMARY_LENGTH);
+  return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut;
+};
+
 /**
  * 🔴 INVARIANT 2: the agent never creates its own work. A proposal is labelled
  * `triage`, which `buildJql` excludes explicitly, and it never receives a ready
@@ -689,7 +706,7 @@ export const triageItemFor = (proposal) => {
   validateProposal(proposal);
   const fingerprint = fingerprintOf(proposal);
   return {
-    title: `proposal: ${proposal.change}`,
+    title: boundedSummary(`proposal: ${proposal.change}`),
     body: [
       `- finding — ${proposal.finding}`,
       `- part to change — ${proposal.part}`,