create-agent-rig 0.5.0 → 0.6.0

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

@@ -17,8 +17,14 @@
 //
 //     { "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';
+//     { "adapter": "jira", "options": { "project": "ABC", "owner": "my-repo" } }
+//
+// `owner` names this checkout for the `owner-<name>` label (AR-132): an item
+// marked for another repository is held, and a checkout that declares no
+// owner holds every marked item, since it cannot confirm a match.
+import { duplicateOf, fingerprintOf, validateProposal, ownerOfLabels, lifecycleOf } from './core.mjs';
+import { withAsOf } from './as-of.mjs';
+import { recordEscalation, recordTakeUp } from '../run-state.mjs';
 
 export const name = 'jira';
 
@@ -101,8 +107,21 @@ export const toTicket = (issue) => {
     tier: labels.includes('elevated') ? 'elevated' : 'normal',
     blockedBy,
     blocks,
-    priority: PRIORITY[String(fields.priority?.name ?? '').toLowerCase()] ?? 999,
+    // English names first; a localised board ("Höchste", "Mittel") falls back
+    // to the numeric priority id. Neither → 999.
+    priority:
+      PRIORITY[String(fields.priority?.name ?? '').toLowerCase()] ??
+      (Number.isFinite(Number(fields.priority?.id)) && Number(fields.priority?.id) > 0
+        ? Number(fields.priority?.id)
+        : 999),
     createdAt: toIso(fields.created),
+    // The take-up marker for revalidation at SELECT (`core.mjs` › revalidationOf):
+    // the tracker's own last-modified field. That it moves on every status
+    // change, edit and comment is Jira's contract, assumed and not checked
+    // here. `null` when the search did not carry it — never `''`, which would
+    // compare equal to itself and read as "unchanged" where the truth is "not
+    // looked".
+    updatedAt: toIso(fields.updated),
     // Flattened from the document description — the same text this adapter
     // already reads internally, now visible to the shared hygiene checks.
     body: descriptionTextOf(issue) || null,
@@ -112,6 +131,11 @@ export const toTicket = (issue) => {
       : 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): `lifecycleOf` above the seam
+    // owns the semantics; this adapter only hands it the labels.
+    ...lifecycleOf(labels),
   };
 };
 
@@ -148,8 +172,55 @@ export const EXCLUDED_LABELS = ['triage', 'operator-queue'];
  * innermost groups. `AND` binds tighter than `OR` in JQL, so the flat form means
  * `(a AND b) OR empty`, which is the intent.
  */
+/**
+ * A Jira project key: one uppercase letter, then up to nine of [A-Z0-9_].
+ * Exported so the refusal below can name the rule it applied (AR-51).
+ */
+export const PROJECT_KEY = /^[A-Z][A-Z0-9_]{1,9}$/;
+
+/**
+ * The one place `options.project` and `options.jql` from `.claude/queue.json`
+ * reach the query. Both used to be interpolated raw (AR-51): a committed
+ * `queue.json` — a file a pull request can edit — could make this adapter read
+ * another board, or anything the JQL grammar allows. A project key is now
+ * validated against PROJECT_KEY, and an explicit `jql` must begin with
+ * `project = <KEY>` — the same key when `options.project` is also given — so
+ * an override has to NAME this board. ⚠ Naming is not confinement: a query
+ * that leads with `project = AR` may still say `OR project = X` after it, and
+ * the credential's own scope is what bounds that. The residual is accepted
+ * because `.claude/queue.json` is part of the rulebook (`guard-rulebook`) and
+ * a declared elevated path, so a change widening it reaches the model lane.
+ */
+/** The project key a config names — options.project, or the key options.jql leads with. */
+export const projectKeyOf = ({ project = null, jql = null } = {}) => {
+  buildJql({ project, jql }); // the same refusals, once
+  if (project) return String(project);
+  return /^\s*project\s*=\s*([A-Z][A-Z0-9_]{1,9})\b/.exec(String(jql))[1];
+};
+
 export const buildJql = ({ project = null, jql = null } = {}) => {
-  if (jql) return jql;
+  if (project !== null && project !== undefined && !PROJECT_KEY.test(String(project))) {
+    throw new Error(
+      `options.project ${JSON.stringify(project)} is not a Jira project key — it must match ` +
+        `${PROJECT_KEY.source}. It is interpolated into JQL, so anything else is refused, not quoted.`,
+    );
+  }
+  if (jql) {
+    const lead = /^\s*project\s*=\s*([A-Z][A-Z0-9_]{1,9})\b/.exec(String(jql));
+    if (!lead) {
+      throw new Error(
+        'options.jql must begin with `project = <KEY>` (a key matching ' +
+          `${PROJECT_KEY.source}) — a query that does not name its project can read any board.`,
+      );
+    }
+    if (project && lead[1] !== project) {
+      throw new Error(
+        `options.jql names project ${lead[1]} while options.project is ${project} — an override ` +
+          'may narrow the query, never point it at another board.',
+      );
+    }
+    return jql;
+  }
   if (!project) {
     throw new Error(
       'the jira adapter needs either options.project or options.jql in ' +
@@ -186,23 +257,91 @@ export const requireCredentials = (env = process.env) => {
   return { baseUrl, email: env.JIRA_EMAIL, token: env.JIRA_API_TOKEN };
 };
 
-const request = async (route, { method = 'GET', body = null, env = process.env } = {}) => {
+/** Statuses worth one more try: rate-limited, or a gateway that will be back. */
+const TRANSIENT = new Set([429, 502, 503, 504]);
+const MAX_ATTEMPTS = 4;
+const DEFAULT_TIMEOUT_MS = 20_000;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * The wait before the next attempt: `Retry-After` in seconds when the server
+ * names one, otherwise 500 ms doubling per attempt. Bounded by the attempt cap.
+ */
+const MAX_RETRY_AFTER_MS = 60_000;
+const retryDelayMs = (response, attempt) => {
+  // Seconds form only; the HTTP-date form is not parsed and falls to backoff
+  // (› "falls back to the backoff when Retry-After is an HTTP-date, which it
+  // does not parse"). Capped, because a header is input like any other:
+  // `Retry-After: 86400` must not sleep the loop for a day (› "caps Retry-After
+  // so a hostile header cannot sleep the loop for a day").
+  const header = Number(response?.headers?.get?.('Retry-After'));
+  if (Number.isFinite(header) && header > 0) return Math.min(header * 1000, MAX_RETRY_AFTER_MS);
+  return 500 * 2 ** (attempt - 1);
+};
+
+/**
+ * One HTTP call to Jira, with the three things AR-54 added to it:
+ *
+ * - a timeout (`timeoutMs`, default 20 s) through an AbortController — a stalled
+ *   connection used to block selection forever, and a loop that cannot read its
+ *   queue must stop, not hang;
+ * - a retry on 429/502/503/504, at most `MAX_ATTEMPTS`, honouring `Retry-After`;
+ *   401/403/404 and every other status fail at once — a bad credential is not
+ *   transient, and retrying it only delays the diagnosis;
+ * - `retry.sleep` injectable, so a test measures the delay it would have waited
+ *   instead of waiting it.
+ *
+ * Pinned in the generator's `test/template/queue-jira.test.ts` (absent in a
+ * generated rig) › "hands fetch an AbortSignal", › "rejects naming the timeout
+ * and the route when fetch never resolves", › "a 429 followed by a 200 yields
+ * the 200 body", › "sleeps for the Retry-After the 429 carried, in
+ * milliseconds", › "gives up after four consecutive 503s, naming the status and
+ * the attempts" and › "does not retry a 401 — a bad credential is not transient".
+ */
+const request = async (
+  route,
+  { method = 'GET', body = null, env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS, retry = {} } = {},
+) => {
   const { baseUrl, email, token } = requireCredentials(env);
-  const response = await fetch(`${baseUrl}${route}`, {
-    method,
-    headers: {
-      Authorization: `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`,
-      Accept: 'application/json',
-      ...(body ? { 'Content-Type': 'application/json' } : {}),
-    },
-    ...(body ? { body: JSON.stringify(body) } : {}),
-  });
-  if (!response.ok) {
+  const sleep = retry.sleep ?? defaultSleep;
+  for (let attempt = 1; ; attempt += 1) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    let payload = null;
+    try {
+      response = await fetch(`${baseUrl}${route}`, {
+        method,
+        headers: {
+          Authorization: `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`,
+          Accept: 'application/json',
+          ...(body ? { 'Content-Type': 'application/json' } : {}),
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+        signal: controller.signal,
+      });
+      // The body is read INSIDE the timed region: headers can arrive and the
+      // body then stall, which is the same hung connection with a 200 on it
+      // (› "keeps the timeout armed while the body is read").
+      if (response.ok && response.status !== 204) payload = await response.json();
+    } catch (error) {
+      if (error?.name === 'AbortError' || controller.signal.aborted) {
+        throw new Error(`jira ${method} ${route} timed out after ${timeoutMs} ms`, { cause: error });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.ok) return payload;
+    if (TRANSIENT.has(response.status) && attempt < MAX_ATTEMPTS) {
+      await sleep(retryDelayMs(response, attempt));
+      continue;
+    }
     // The status alone; never echo the response body, which can carry the token
     // back in an error envelope.
-    throw new Error(`jira ${method} ${route} failed: ${response.status} ${response.statusText}`);
+    const attempts = TRANSIENT.has(response.status) ? ` after ${attempt} attempts` : '';
+    throw new Error(`jira ${method} ${route} failed: ${response.status} ${response.statusText}${attempts}`);
   }
-  return response.status === 204 ? null : response.json();
 };
 
 // `description` is requested because the triage dedupe matches the fingerprint
@@ -214,14 +353,26 @@ const request = async (route, { method = 'GET', body = null, env = process.env }
 // 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'];
+const FIELDS = [
+  'summary',
+  'status',
+  'labels',
+  'priority',
+  'created',
+  'updated',
+  'issuelinks',
+  'description',
+];
 
 // --- the adapter contract ------------------------------------------------------
 
 /**
  * Query fresh every time — the queue changes as the loop closes items and
  * unblocks their dependents, so a list read at the start of a run is wrong by the
- * second task. `issues` is the offline seam the tests use.
+ * second task. `issues` is the offline seam the tests use. Since AR-54 `limit`
+ * is the PAGE size, not a result cap: `search` walks every page up to its own
+ * `hardCap`, which this function leaves at the default (› "returns both pages
+ * as one list").
  */
 export const listEligible = async ({
   issues = null,
@@ -254,18 +405,106 @@ export const listEligible = async ({
  * 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.
+ * Pages through `nextPageToken` until the server sends none, or `hardCap`
+ * issues (default 1000) are in hand, or `maxPages` requests (default 100) have
+ * been made — each cap is announced on stderr, never
+ * silent, because a board whose tail is dropped is exactly the board the loop
+ * would otherwise believe it had read. `timeoutMs` and `retry` travel down to
+ * every page. Pinned in the generator's `test/template/queue-jira.test.ts`
+ * (absent in a generated rig) › "returns both pages as one list", › "sends the
+ * token from page 1 in the body of the request for page 2" and › "stops at
+ * hardCap and says on stderr that the list was capped".
  */
-export const search = async ({ project = null, jql = null, limit = 100, env = process.env } = {}) =>
-  request('/rest/api/3/search/jql', {
-    method: 'POST',
-    body: { jql: buildJql({ project, jql }), maxResults: limit, fields: FIELDS },
-    env,
-  });
+export const search = async ({
+  project = null,
+  jql = null,
+  limit = 100,
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  retry = {},
+  hardCap = 1000,
+  maxPages = 100,
+} = {}) => {
+  const query = buildJql({ project, jql });
+  const issues = [];
+  // Bounds beside hardCap, because a cap on issues alone is no bound at all
+  // against a server that repeats a token: a token equal to the one just sent
+  // ends the walk, and so does `maxPages` (default 100 requests), each with a
+  // stderr line. An EMPTY page with a fresh token is NOT a stop — the enhanced
+  // search endpoint may return short or empty pages while later pages exist,
+  // and stopping there drops a real tail (› "keeps walking past an empty page
+  // that carries a fresh token", › "stops paging when a page brings no issues,
+  // even if the token repeats", › "caps the number of requests outright, and
+  // says so on stderr").
+  let nextPageToken = null;
+  let pages = 0;
+  do {
+    pages += 1;
+    const page = await request('/rest/api/3/search/jql', {
+      method: 'POST',
+      body: {
+        jql: query,
+        maxResults: limit,
+        fields: FIELDS,
+        ...(nextPageToken ? { nextPageToken } : {}),
+      },
+      env,
+      timeoutMs,
+      retry,
+    });
+    const received = page?.issues ?? [];
+    issues.push(...received.slice(0, Math.max(0, hardCap - issues.length)));
+    const sent = nextPageToken;
+    nextPageToken = page?.isLast === true ? null : (page?.nextPageToken ?? null);
+    if (nextPageToken && nextPageToken === sent) {
+      process.stderr.write(
+        `jira search: the server repeated page token ${JSON.stringify(sent)} — ` +
+          'stopping the walk; the tail of this board may not have been read\n',
+      );
+      break;
+    }
+    if (nextPageToken && pages >= maxPages) {
+      process.stderr.write(
+        `jira search: capped at ${maxPages} requests with more pages available — ` +
+          'the tail of this board was not read; raise maxPages or narrow the JQL\n',
+      );
+      break;
+    }
+    if (issues.length >= hardCap && nextPageToken) {
+      process.stderr.write(
+        `jira search: capped at ${hardCap} issues with more pages available — ` +
+          'the tail of this board was not read; raise hardCap or narrow the JQL\n',
+      );
+      break;
+    }
+  } while (nextPageToken);
+  return { issues };
+};
+
+/**
+ * One item by key, mapped raw — closed included. `listEligible` drops closed
+ * items because selection must never take one; the close point needs to see
+ * exactly that one. Honours the same offline `issues` seam.
+ */
+export const find = async (id, { issues = null, env = process.env } = {}) => {
+  if (issues) {
+    return issues.map(toTicket).find((ticket) => String(ticket.id) === String(id)) ?? null;
+  }
+  // 🔴 By key, never through `search`: `buildJql` carries `statusCategory != Done`
+  // for selection's sake, so a search can never return the closed item this
+  // point exists to see. A 404 is "the tracker has no such item" — `null`;
+  // every other failure is raised as it is.
+  try {
+    const issue = await request(
+      `/rest/api/3/issue/${encodeURIComponent(String(id))}?fields=${FIELDS.join(',')}`,
+      { env },
+    );
+    return issue ? toTicket(issue) : null;
+  } catch (error) {
+    if (/ 404 /.test(String(error?.message))) return null;
+    throw error;
+  }
+};
 
 export const resolveBlockers = (ticket) => (ticket.blockedBy ?? []).filter((b) => !b.resolved);
 
@@ -274,6 +513,52 @@ export const resolveBlockers = (ticket) => (ticket.blockedBy ?? []).filter((b) =
  * worked while it still reads as available is invisible to the human and
  * re-selectable by the very next query.
  */
+/**
+ * Re-record the item's marker after a write of this adapter's own (AR-140).
+ *
+ * Every write here — a claim, a comment, a close, an escalation — moves the
+ * tracker's `updated`, and the next revalidation compared against the take-up
+ * from before it — the generator's journal records one run whose every
+ * BEFORE_PR catch was a hold on its own comment (`revalidation-report.mjs`
+ * over that run). So the marker is read back after the write
+ * and recorded as the take-up in the declared run; a hold that still fires is
+ * a move by something other than this adapter.
+ *
+ * ⚠ Limit: only writes made THROUGH this adapter re-baseline. A comment the
+ * session posts by another route — a REST call by hand, a connector — moves
+ * the marker like anyone else's, and the next check holds on it.
+ *
+ * Best-effort, like `proposeTriage`'s baseline: the write has landed by now,
+ * and a read-back the tracker refused or a stale run directory is announced on
+ * stderr, never thrown — a thrown write is retried and lands twice.
+ */
+const recordMarker = (ticket, updatedAt, env) => {
+  try {
+    recordTakeUp(env.RIG_RUN_DIR, { id: ticket.id, updatedAt });
+  } catch (error) {
+    process.stderr.write(
+      `${ticket.id}: the write landed, but its marker was NOT re-recorded in ` +
+        `${env.RIG_RUN_DIR} — ${error.message}\n`,
+    );
+  }
+};
+
+const rebaseline = async (ticket, env) => {
+  if (!env?.RIG_RUN_DIR) return;
+  let updatedAt;
+  try {
+    const after = await request(`/rest/api/3/issue/${ticket.id}?fields=updated`, { env });
+    updatedAt = toIso(after?.fields?.updated);
+  } catch (error) {
+    process.stderr.write(
+      `${ticket.id}: the write landed, but its marker was NOT re-recorded in ` +
+        `${env.RIG_RUN_DIR} — ${error.message}\n`,
+    );
+    return;
+  }
+  recordMarker(ticket, updatedAt, env);
+};
+
 export const claim = async (ticket, { transitionId = null, env = process.env } = {}) => {
   if (!transitionId) {
     const available = await request(`/rest/api/3/issue/${ticket.id}/transitions`, { env });
@@ -293,6 +578,7 @@ export const claim = async (ticket, { transitionId = null, env = process.env } =
     body: { transition: { id: transitionId } },
     env,
   });
+  await rebaseline(ticket, env);
   return { ok: true };
 };
 
@@ -304,9 +590,17 @@ export const comment = async (ticket, body, { env = process.env } = {}) => {
     },
     env,
   });
+  await rebaseline(ticket, env);
   return { ok: true };
 };
 
+/**
+ * 🔴 `transitioned` is read back from the tracker, never inferred from the
+ * argument. The first version returned `Boolean(transitionId)` — a fact about
+ * the call, reported as a fact about the issue — so a transition the workflow
+ * rejected, or one that landed in a status outside the `done` category, was
+ * published as a close (AR-135).
+ */
 export const close = async (ticket, { prUrl = null, transitionId = null, env = process.env } = {}) => {
   await comment(ticket, prUrl ? `Landed in ${prUrl}.` : 'Closed by the run.', { env });
   if (transitionId) {
@@ -316,7 +610,20 @@ export const close = async (ticket, { prUrl = null, transitionId = null, env = p
       env,
     });
   }
-  return { ok: true, transitioned: Boolean(transitionId) };
+  // One read-back for both facts the close needs: the status that proves the
+  // transition, and the marker the write produced (AR-140) — `comment` above
+  // already re-baselined once; this is the read after the transition.
+  const after = await request(`/rest/api/3/issue/${ticket.id}?fields=status,updated`, { env });
+  const fields = after?.fields ?? {};
+  // Through the same announce-never-throw path as `rebaseline`: the round
+  // that inlined `recordTakeUp` here reintroduced a throw on a stale run
+  // directory after the transition had landed.
+  if (env?.RIG_RUN_DIR) recordMarker(ticket, toIso(fields.updated), env);
+  return {
+    ok: true,
+    transitioned: statusCategory(fields) === 'done',
+    status: fields.status?.name ?? null,
+  };
 };
 
 /**
@@ -331,6 +638,7 @@ export const escalate = async (ticket, diagnosis, { env = process.env } = {}) =>
     body: { update: { labels: [{ add: 'escalated' }] } },
     env,
   });
+  await rebaseline(ticket, 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);
@@ -352,8 +660,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.',
@@ -365,22 +675,36 @@ export const triageItemFor = (proposal) => {
 };
 
 /** File the proposal, or increment the one already carrying this fingerprint. */
+/**
+ * The proposals on file, as `{ id, body }` — every `triage`-labelled issue, the
+ * body being its DESCRIPTION, which is where the fingerprint and `asOf` were
+ * written. An earlier dedupe mapped candidates through `toTicket` — which emits
+ * no body at all — so the predicate was always false and twenty identical stops
+ * filed twenty issues against the tracker.
+ */
+export const listProposals = async ({
+  existing = null,
+  project = null,
+  jql = null,
+  env = process.env,
+  retry = {},
+} = {}) => {
+  if (existing) return existing;
+  // Project-qualified, like every query this adapter sends (AR-51): the key is
+  // options.project, or the one options.jql leads with — `buildJql` refuses
+  // both when they disagree, so the triage query can only read this board.
+  const key = projectKeyOf({ project, jql });
+  const response = await search({ jql: `project = ${key} AND labels = triage ORDER BY created DESC`, env, retry });
+  return response.issues.map((issue) => ({ id: issue.key, body: descriptionTextOf(issue) }));
+};
+
 export const proposeTriage = async (
-  proposal,
-  { project = null, existing = null, env = process.env } = {},
+  rawProposal,
+  { project = null, jql = null, existing = null, env = process.env, retry = {} } = {},
 ) => {
+  const proposal = withAsOf(rawProposal);
   const item = triageItemFor(proposal);
-  // Compared against the issue's DESCRIPTION, which is where the fingerprint was
-  // written. The previous version mapped candidates through `toTicket` — which
-  // emits no body at all — so the predicate was always false and twenty identical
-  // stops filed twenty issues against the tracker.
-  const found =
-    existing ??
-    (await search({ jql: 'labels = triage ORDER BY created DESC', env })).issues.map((issue) => ({
-      id: issue.key,
-      body: descriptionTextOf(issue),
-    }));
-  const duplicate = duplicateOf(item, found);
+  const duplicate = duplicateOf(item, await listProposals({ existing, project, jql, env, retry }));
 
   if (duplicate) {
     await comment(duplicate, `Seen again (fingerprint ${item.fingerprint}). Incrementing.`, { env });
@@ -389,7 +713,7 @@ export const proposeTriage = async (
   if (!project) {
     throw new Error('filing a triage proposal needs options.project');
   }
-  await request('/rest/api/3/issue', {
+  const created = await request('/rest/api/3/issue', {
     method: 'POST',
     body: {
       fields: {
@@ -406,5 +730,29 @@ export const proposeTriage = async (
     },
     env,
   });
-  return { ok: true, filed: item.title, item };
+  // The proposal's own baseline (AR-138): its marker as filed, recorded as a
+  // take-up in the run that filed it, so the next run that is offered it
+  // compares against something. Read back rather than assumed — the marker is
+  // the tracker's, and `created` carries only the key. No run directory →
+  // nothing recorded, and the proposal is still filed.
+  //
+  // 🔴 Best-effort, and it says so: the proposal is FILED by now, and a throw
+  // here — a read-back the tracker refused, a stale or unwritable run
+  // directory in `updateState` — would tell the caller the filing failed when
+  // it succeeded, and the natural response (file again) double-files. The same
+  // defect `recordEscalation` closes for escalations; announced on stderr,
+  // because a baseline silently missing reads as a first sight later.
+  const id = created?.key ?? null;
+  if (id && env.RIG_RUN_DIR) {
+    try {
+      const after = await request(`/rest/api/3/issue/${id}?fields=updated`, { env });
+      recordTakeUp(env.RIG_RUN_DIR, { id, updatedAt: toIso(after?.fields?.updated) });
+    } catch (error) {
+      process.stderr.write(
+        `proposeTriage: ${id} is filed, but its baseline was NOT recorded in ` +
+          `${env.RIG_RUN_DIR} — ${error.message}\n`,
+      );
+    }
+  }
+  return { ok: true, filed: item.title, id, item };
 };