create-agent-rig 0.6.1 → 0.7.0

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

@@ -26,8 +26,10 @@
 import { duplicateOf, fingerprintOf, validateProposal, ownerOfLabels, lifecycleOf } from './core.mjs';
 import { withAsOf } from './as-of.mjs';
 import { recordEscalation, recordTakeUp } from '../run-state.mjs';
+import { recordClaimTransition } from '../lib/claim-records.mjs';
 
 export const name = 'jira';
+export const claimedState = 'in-progress';
 
 /** Jira's own default priority ladder. An unrecognised name sorts last, never first. */
 const PRIORITY = { highest: 1, high: 2, medium: 3, low: 4, lowest: 5 };
@@ -76,6 +78,14 @@ export const toTicket = (issue) => {
   const labels = fields.labels ?? [];
   const links = fields.issuelinks ?? [];
   const category = statusCategory(fields);
+  const comments = Array.isArray(fields.comment?.comments) ? fields.comment.comments : [];
+  const commentaryIds = comments
+    .map((comment) => comment?.id)
+    .filter((id) => id !== undefined && id !== null)
+    .map(String);
+  const commentaryCount = Number.isInteger(fields.comment?.total)
+    ? fields.comment.total
+    : comments.length;
 
   // 🔴 INVARIANT 1: the dependency is the LINK, and the blocker's own status
   // decides. A `blocked` label is a snapshot nobody updates when the blocker
@@ -116,16 +126,22 @@ export const toTicket = (issue) => {
         ? 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".
+    // Compatibility evidence only: Jira's last-modified field is retained in
+    // `takeUps`, but content-blind claim fingerprints decide drift.
     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,
+    commentary: {
+      count: commentaryCount,
+      ids: commentaryIds,
+      // Jira may return only the first page while still declaring the total.
+      // A partial set cannot truthfully fingerprint commentary; the shared
+      // claim resolver turns this explicit false into UNVERIFIABLE.
+      complete:
+        commentaryIds.length === commentaryCount &&
+        new Set(commentaryIds).size === commentaryIds.length,
+    },
     triage: labels.includes('triage'),
     trigger: labels.includes('trigger-auto')
       ? 'auto'
@@ -286,22 +302,32 @@ const retryDelayMs = (response, attempt) => {
  * - 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;
+ * - safe reads retry 429/502/503/504 at most `MAX_ATTEMPTS`, honouring
+ *   `Retry-After`; mutating calls do not retry an ambiguous response, because
+ *   Jira may have applied the write before a proxy returned the error. The
+ *   search endpoint opts in explicitly: it is a POST at the transport layer and
+ *   a read at the operation layer;
  * - `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
+ * and the route when fetch never resolves", › "retries a semantically read-only
+ * search POST after a 429", › "keeps bounded retry for a safe issue GET", ›
+ * "does not retry %s", › "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 = {} } = {},
+  {
+    method = 'GET',
+    body = null,
+    env = process.env,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    retry = {},
+    retryTransient = method === 'GET',
+  } = {},
 ) => {
   const { baseUrl, email, token } = requireCredentials(env);
   const sleep = retry.sleep ?? defaultSleep;
@@ -334,13 +360,14 @@ const request = async (
       clearTimeout(timer);
     }
     if (response.ok) return payload;
-    if (TRANSIENT.has(response.status) && attempt < MAX_ATTEMPTS) {
+    const retryable = retryTransient && TRANSIENT.has(response.status);
+    if (retryable && 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.
-    const attempts = TRANSIENT.has(response.status) ? ` after ${attempt} attempts` : '';
+    const attempts = retryable ? ` after ${attempt} attempts` : '';
     throw new Error(`jira ${method} ${route} failed: ${response.status} ${response.statusText}${attempts}`);
   }
 };
@@ -363,6 +390,7 @@ const FIELDS = [
   'updated',
   'issuelinks',
   'description',
+  'comment',
 ];
 
 // --- the adapter contract ------------------------------------------------------
@@ -443,6 +471,7 @@ export const search = async ({
     pages += 1;
     const page = await request('/rest/api/3/search/jql', {
       method: 'POST',
+      retryTransient: true,
       body: {
         jql: query,
         maxResults: limit,
@@ -517,17 +546,9 @@ export const resolveBlockers = (ticket) => (ticket.blockedBy ?? []).filter((b) =
 /**
  * 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.
+ * Every write here moves Jira's `updated`, so it is read back and retained for
+ * attribution and compatibility. It does not re-baseline `.rig/claims/` and
+ * cannot produce or clear a drift decision.
  *
  * 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
@@ -560,7 +581,10 @@ const rebaseline = async (ticket, env) => {
   recordMarker(ticket, updatedAt, env);
 };
 
-export const claim = async (ticket, { transitionId = null, env = process.env } = {}) => {
+export const claim = async (
+  ticket,
+  { transitionId = null, env = process.env, projectRoot = process.cwd() } = {},
+) => {
   if (!transitionId) {
     const available = await request(`/rest/api/3/issue/${ticket.id}/transitions`, { env });
     const target = available.transitions.find(
@@ -579,8 +603,18 @@ export const claim = async (ticket, { transitionId = null, env = process.env } =
     body: { transition: { id: transitionId } },
     env,
   });
+  let workflowClaimRecorded = false;
+  try {
+    workflowClaimRecorded =
+      recordClaimTransition({ projectRoot, ticket, claimedState }) !== null;
+  } catch (error) {
+    process.stderr.write(
+      `${ticket.id}: the workflow claim landed, but its durable acknowledgement was NOT recorded — ` +
+        `${error.message}\n`,
+    );
+  }
   await rebaseline(ticket, env);
-  return { ok: true };
+  return { ok: true, workflowClaimRecorded };
 };
 
 export const comment = async (ticket, body, { env = process.env } = {}) => {

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

@@ -17,6 +17,7 @@ import { withAsOf } from './as-of.mjs';
 import { recordEscalation } from '../run-state.mjs';
 
 export const name = 'plan-md';
+export const claimedState = 'open';
 
 const AGENT_QUEUE = /^##\s+Agent queue\s*$/i;
 const OPERATOR_QUEUE = /^##\s+Operator queue\s*$/i;
@@ -129,9 +130,10 @@ export const parsePlan = (plan) => {
       blocks: [],
       priority: items.length,
       createdAt: null,
-      // A flat list carries no marker at all, so revalidation at SELECT records
-      // `changed: null` for it — a blind spot, never an "unchanged".
+      // A flat list carries no compatibility marker; claim fingerprints still
+      // provide the authoritative revalidation baseline.
       updatedAt: null,
+      commentary: { count: 0, ids: [] },
       triage: MARKERS.triage.test(raw),
       trigger: MARKERS.triggerAuto.test(raw)
         ? 'auto'

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

@@ -6,13 +6,22 @@
  *
  *   node .claude/scripts/revalidate.mjs --point BEFORE_PR --ticket <id> [--base origin/master] [--config <queue.json>] [--json]
  *
- * Two sources, compared and named separately, because a hold that cannot say
- * WHAT moved sends the run to re-read everything:
+ * One existing checkpoint chain, with one authoritative durable baseline:
  *
- * - `task:updatedAt` — the item's marker now, read through the queue adapter,
- *   against the take-up snapshot `queue/index.mjs next` recorded in the run's
- *   `state.json` (`takeUps`, AR-133). No snapshot, no marker or no run → that
- *   source is `null`: not looked, never "unchanged".
+ * - `.rig/claims/<ticket>.json` carries versioned, content-blind `scope` and
+ *   `commentary` fingerprint sets. Scope is authoritative at BEFORE_PR;
+ *   commentary is observed but does not hold until BEFORE_CLOSE. Missing,
+ *   untracked or unreadable claim state is `UNVERIFIABLE` and exits 2. So is a
+ *   tracker whose adapter this script cannot READ (RP-64) — that one means the
+ *   question was never put, rather than that the claim record is unreadable.
+ *   ⚠ Reads, precisely: the queue CONFIG failing to resolve at all — an unknown
+ *   adapter name, a malformed `queue.json` — is exit 1, the refusal path, not a
+ *   hold, and it is the operator's to fix rather than a claim waiting on a
+ *   tracker. Pinned in the generator's
+ *   `test/template/revalidate-adapter.test.ts` — absent in a generated rig —
+ *   › "refuses an adapter name it cannot resolve with a readable message, not a
+ *   stack trace" and › "refuses a queue config that is not valid JSON with a
+ *   readable message, not a stack trace".
  * - `main:<path>` — what the default branch changed since this branch forked
  *   (`git merge-base <base> HEAD` … `<base>`), intersected with the CITED
  *   paths. Cited is a labelled assumption, not a recorded fact: the paths the
@@ -20,33 +29,34 @@
  *   record in this run's journal — the files the run said its premises rest
  *   on. An unrelated change on the default branch does not hold.
  *
- * At BEFORE_CLOSE (AR-135) there is no git and no main: the sources are
- * `task:updatedAt` against the LAST VALIDATION — the `task.to` of this run's
- * latest `revalidation` event for the item, falling back to the take-up
- * snapshot — and `task:state`, which is expected `in-progress` at close and
- * is a change when someone closed the item or moved it back. The item comes
+ * `updatedAt` and `takeUps` are still projected into `task` as compatibility
+ * evidence, but never contribute a source or action.
+ *
+ * At BEFORE_CLOSE (AR-135) there is no main comparison: both claim fingerprint
+ * sets are authoritative. Workflow state is already inside `claim:scope`,
+ * normalised to the adapter's expected claimed state, so an expected claim
+ * transition stays current while a close or rollback moves scope. The item comes
  * from the adapter's `find`, which sees closed items where `listEligible`
  * drops them; one the tracker no longer offers at all reads `missing`, and
- * either holds on `task:state` (revalidate.test.ts › "holds on task:state when
- * someone already closed the item", › "holds on task:state when the tracker no
- * longer offers the item"). The result lists the item's dependants (`blocks`)
+ * holds on `claim:scope` (revalidate.test.ts › "holds on claim:scope when
+ * someone already closed the item", › "holds on claim:scope when the item was
+ * moved back to open"). The result lists the item's dependants (`blocks`)
  * and re-reads each one's state through the same `find` (revalidate.test.ts ›
  * "re-reads each dependant's state, and names one the tracker no longer
  * offers") for the loop's write-back.
  *
- * The aggregates are `queue/core.mjs` › beforePrRevalidationOf and
- * beforeCloseRevalidationOf; this file is the I/O around them.
- *
  * `outcome --point <P> --ticket <id> --action-changed true|false [--note …]`
  * (AR-136) is the second half of the evidence: after the re-read, it appends a
  * `revalidation-outcome` record whose `answers` is the seq of the latest
  * `revalidation` for that ticket and point in this run — the join a report
  * needs, made by the writer rather than guessed by the reader. It refuses
  * without a run, without a matching revalidation, and with any word but
- * `true`/`false`, and writes nothing then. Exit 2 on `hold`, 0 on `continue` and `unverifiable`, 1 when
- * the arguments cannot be acted on (unknown point, no ticket, a base that is
- * not a revision) — and then nothing is journalled, because a refusal is not
- * an answer.
+ * `true`/`false`, and writes nothing then. The typed resolution names the
+ * stable detection id and clears only the matching run-level hold. Exit 2 on
+ * `hold` or `unverifiable`, 0 on `continue`, and 1 when the call cannot be
+ * acted on (unknown point, no ticket, a base that is not a revision — or, on
+ * the paths that reach it, a queue config that does not resolve) — and then
+ * nothing is journalled, because a refusal is not an answer.
  *
  * ⚠ It reads `<base>` as it is in this checkout and never updates the remote
  * ref itself; `pr-ship` step 1 does that before calling this. A stale ref
@@ -61,10 +71,18 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withoutGitLocation } from './git-env.mjs';
 import { readRun, recordEvent } from './run-journal.mjs';
-import { readState } from './run-state.mjs';
+import { clearRevalidationHold, readState, recordRevalidationHold } from './run-state.mjs';
 import { POINTS as ALL_POINTS, REVALIDATES } from './lib/revalidation-points.mjs';
-import { beforeCloseRevalidationOf, beforePrRevalidationOf, revalidationOf } from './queue/core.mjs';
+import { takeUpEvidenceOf } from './queue/core.mjs';
 import { loadConfig, optionsWithPlanPath, resolveAdapter } from './queue/index.mjs';
+import { projectRootOfConfig } from './queue/index.mjs';
+import {
+  revalidateClaim,
+  targetShaOf,
+  unverifiableResult,
+  withAdditionalDrift,
+} from './lib/claim-records.mjs';
+import { DEFAULT_SCAN_LIMIT, findSecretValues } from './lib/secrets.mjs';
 
 // Derived from the one source, never restated here (AR-137).
 export const POINTS = REVALIDATES;
@@ -132,7 +150,7 @@ const citedByPremises = (runDir) => {
     .filter((file) => typeof file === 'string' && file !== '');
 };
 
-/** The last validation's marker for this item: the latest revalidation event, any point. */
+/** The last compatibility marker observed for this item, at any revalidation point. */
 const lastValidationOf = (runDir, id) => {
   if (!runDir) return null;
   const { events } = readRun({ runDir });
@@ -155,6 +173,150 @@ const invokedDirectly = () => {
   return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
 };
 
+/**
+ * The adapter's own message, unless it carries something credential-shaped.
+ *
+ * The messages this is written for name environment VARIABLES rather than their
+ * values, and naming them is exactly what the caller acts on. But an adapter is
+ * free to put a URL or a response body into a message, and this text is
+ * published to stdout and into a verdict a run journals — neither of which
+ * `guard-secret-file` or `validate-no-secrets` can see — so it is checked
+ * against the one credential vocabulary this repository has before it goes
+ * anywhere.
+ *
+ * ⚠ **It is defence in depth, not a general redacter.** Measured on the shapes
+ * an adapter could plausibly produce: an Atlassian token value, an opaque token
+ * after a credential keyword, and a token in a query string are caught by
+ * `findSecretValues`; `Authorization: Bearer <opaque>` and `Authorization: Basic
+ * <base64>` are NOT, and no shape outside the vocabulary is.
+ *
+ * 🔴 **URL userinfo is matched HERE rather than left to the vocabulary, because
+ * it is reachable through the adapter this repository configures.** `jira.mjs`
+ * builds its own errors from method, route and status — but its network arm
+ * re-raises the underlying error untouched, and `requireCredentials` accepts any
+ * `JIRA_BASE_URL` that begins with `https://`, userinfo included. Undici then
+ * throws "Request cannot be constructed from a URL that includes credentials:
+ * https://user:<password>@host/…". `findSecretValues` does not see that shape,
+ * and unlike the pre-RP-64 crash — which put it on stderr — this path PERSISTS
+ * it into the run journal. So the reason is withheld on userinfo as well.
+ *
+ * An earlier version of this comment argued the blind spots were acceptable
+ * because no adapter here produces them. That was false, and resting a safety
+ * property on a claim about every present and future adapter is the wrong shape
+ * of argument regardless.
+ *
+ * All-or-nothing on purpose: `findSecretValues` never returns the matched text,
+ * so redacting in place would need a second matcher, and a partial redacter is
+ * where redacters leak.
+ *
+ * Exported so the control itself is testable rather than only reachable through
+ * a subprocess. Pinned in the generator's `test/template/revalidate-adapter.test.ts`
+ * — absent in a generated rig — › "publishes a message that names only environment variables"
+ * and › "withholds a message carrying a credential-shaped value".
+ */
+/**
+ * Userinfo present in a URL at all — `//<anything but a slash or space>@host`.
+ * One forward pass, one negated bounded class, so it cannot backtrack.
+ *
+ * 🔴 It matches the CLASS, not a list of spellings, and that is the whole
+ * lesson of how it got here. It first required `user:pass@`, which published
+ * `//<token>@host`. Widened to make the password optional, it published
+ * `//:<token>@host` — the shape `https://${JIRA_EMAIL}:${JIRA_API_TOKEN}@host`
+ * degrades to when the first variable is unset, so the likeliest accident of
+ * the three. Two rounds of enumerating forms; the invariant was always "there
+ * is userinfo here", and it is shorter than any enumeration of it.
+ *
+ * The class excludes `/` and whitespace, which is what keeps an ordinary URL,
+ * a bare email address in prose, and a registry path carrying an `@scope`
+ * published. Pinned in the generator's `test/template/revalidate-adapter.test.ts`
+ * — absent in a generated rig — › "withholds a URL whose userinfo is %s — every
+ * shape, not the ones enumerated so far" and › "still publishes a message
+ * carrying %s", which are tables rather than cases so a future narrowing that
+ * handles the known spellings and reopens the class goes red.
+ */
+const URL_USERINFO = /\/\/[^\s/@]*@/;
+
+export const safeReason = (text) => {
+  // Scan and publish the SAME prefix: findSecretValues reads at most
+  // DEFAULT_SCAN_LIMIT, and publishing more than was scanned would ship the
+  // unscanned tail verbatim.
+  const scanned = String(text ?? '').slice(0, DEFAULT_SCAN_LIMIT);
+  return findSecretValues(scanned).length === 0 && !URL_USERINFO.test(scanned)
+    ? scanned
+    : 'the queue adapter could not be read; its message is withheld because it carries a credential-shaped value';
+};
+
+/**
+ * The revalidation boundary for a tracker that cannot be read (RP-64).
+ *
+ * 🔴 It answers `UNVERIFIABLE` and exits 2 — the same hold path a real drift
+ * takes, and never 0. "The adapter was unreachable" is not evidence that the
+ * branch is still the branch the run took up, and a caller that read it as a
+ * pass would carry an unchecked claim into a PR. A drift the adapter DID report
+ * still comes back as `hold`, and an unchanged claim still as `continue`;
+ * this only replaces the crash. Pinned in the generator's
+ * `test/template/revalidate-adapter.test.ts` — absent in a generated rig — ›
+ * "holds the same way at BEFORE_CLOSE, which reads the adapter through a different call"
+ * and › "still refuses an unusable invocation as before — this did not swallow argument errors".
+ *
+ * The detection `identity` names the point and the operation and NOT the
+ * message, so it is stable across retries of the same outage — which also means
+ * two unrelated failures at one operation share an id, and one `outcome`
+ * answers both.
+ */
+const answerUnverifiable = ({ runDir, ticket, point, json }, operation, cause) => {
+  const result = unverifiableResult({
+    ticket: { id: ticket },
+    point,
+    reason: safeReason(
+      `the queue adapter could not be read (${operation}): ${cause?.message ?? cause}`,
+    ),
+    identity: `adapter-unreadable:${operation}`,
+  });
+  if (runDir) {
+    // Announce, never throw: a stale or unwritable RIG_RUN_DIR made these throw
+    // INSIDE the catch that was handling the adapter failure, and the run ended
+    // on the Node stack trace this whole change exists to remove.
+    try {
+      recordEvent({ runDir, kind: 'revalidation', data: result, now: new Date().toISOString() });
+      recordRevalidationHold(runDir, result);
+    } catch (error) {
+      process.stderr.write(
+        `could not journal this revalidation into ${runDir}: ${error?.message ?? error}\n`,
+      );
+    }
+  }
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(
+      `revalidate ${point}: ${ticket} unverifiable — the queue adapter could not be read (${operation})\n`,
+    );
+    process.stdout.write(`  ${result.evidence.error}\n`);
+    process.stdout.write(
+      '  this is NOT a pass: nothing about the claim was observed. Fix the adapter and run it again.\n',
+    );
+  }
+  process.exit(2);
+};
+
+/** Every adapter call in this script goes through here, or it can still crash. */
+const readAdapter = async (operation, read, context) => {
+  try {
+    return await read();
+  } catch (error) {
+    answerUnverifiable(context, operation, error);
+  }
+  // Reached only if answerUnverifiable failed to exit. Throwing rather than
+  // returning null keeps a null ticket from reaching revalidateClaim and
+  // resolving to `continue` — the silent pass this whole change forbids.
+  //
+  // Outside the catch on purpose, and it carries no `cause`: the caught error
+  // is the raw adapter message, the one thing the frame above exists to
+  // withhold, and Node's uncaught printer walks a cause chain.
+  throw new Error('unreachable: answerUnverifiable did not exit');
+};
+
 const refuse = (message) => {
   process.stderr.write(`${message}\n`);
   process.exit(1);
@@ -191,18 +353,26 @@ if (invokedDirectly()) {
     if (!target) {
       refuse(`no revalidation of ${args.ticket} at ${args.point} in ${runDir} for this outcome to answer.`);
     }
+    const now = new Date().toISOString();
+    const actionRequired = args.actionChanged === 'true';
     const record = recordEvent({
       runDir,
       kind: 'revalidation-outcome',
       data: {
+        detectionId: target.data?.id,
+        action: actionRequired ? 'semantic decision' : 'continue',
+        actionRequired,
+        driftOrigin: 'unknown',
+        resolvedAt: now,
         ticket: args.ticket,
         point: args.point,
-        actionChanged: args.actionChanged === 'true',
+        actionChanged: actionRequired,
         note: args.note,
         answers: target.seq,
       },
-      now: new Date().toISOString(),
+      now,
     });
+    clearRevalidationHold(runDir, target.data?.id);
     process.stdout.write(
       args.json
         ? `${JSON.stringify(record, null, 2)}\n`
@@ -213,16 +383,35 @@ if (invokedDirectly()) {
 
   const projectRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
   const configPath = args.config ?? join(projectRoot, '.claude', 'queue.json');
-  const config = loadConfig(configPath);
-  const adapter = await resolveAdapter(config.adapter ?? 'plan-md');
+  // 🔴 The queue CONFIG, not the tracker behind it. `readAdapter` covers every
+  // adapter CALL, but resolving the config sat outside it, so an unknown
+  // adapter name or a malformed `queue.json` still crashed with the raw Node
+  // stack trace this script exists to remove — and the `[cause]` chain of the
+  // malformed case printed the parse error underneath it.
+  //
+  // It stays exit 1 rather than becoming `UNVERIFIABLE`: a config the operator
+  // has to fix is the command refusing, not a claim held pending a tracker
+  // that might come back. `refuse` is the path this file already uses for that.
+  let config;
+  let adapter;
+  try {
+    config = loadConfig(configPath);
+    adapter = await resolveAdapter(config.adapter ?? 'plan-md');
+  } catch (error) {
+    refuse(
+      `the queue configuration at ${configPath} could not be resolved: ` +
+        safeReason(error?.message ?? String(error)),
+    );
+  }
   const options = optionsWithPlanPath(config.options, configPath);
+  const claimRoot = projectRootOfConfig(configPath) ?? projectRoot;
 
   if (args.point === 'BEFORE_CLOSE') {
-    const ticket = await adapter.find(args.ticket, options);
+    const context = { runDir, ticket: args.ticket, point: args.point, json: args.json };
+    const ticket = await readAdapter('find', () => adapter.find(args.ticket, options), context);
     const takeUp = runDir ? (readState(runDir).takeUps?.[args.ticket] ?? null) : null;
-    // The NEWER of the two, not the last validation first (AR-140): an adapter
-    // re-records the take-up after each write of its own, and a comment posted
-    // after BEFORE_PR would otherwise hold this close on the run's own move.
+    // Preserve the newest compatibility marker as evidence. This comparison
+    // never decides drift; the durable claim below is the authority.
     // ISO strings compare as text; a missing side yields to the other.
     const lastValidation = lastValidationOf(runDir, args.ticket);
     const baseline =
@@ -233,7 +422,7 @@ if (invokedDirectly()) {
         : (lastValidation ?? takeUp);
     const task =
       ticket && baseline !== null
-        ? revalidationOf({ ticket, snapshot: baseline })
+        ? takeUpEvidenceOf({ ticket, snapshot: baseline })
         : { changed: null, task: { from: baseline, to: ticket?.updatedAt ?? null } };
     // Not found is not "in progress": the tracker no longer offers the item.
     const actual = ticket ? ticket.state : 'missing';
@@ -243,18 +432,33 @@ if (invokedDirectly()) {
     const dependants = Array.isArray(ticket?.blocks) ? ticket.blocks : [];
     const dependantState = {};
     for (const dependant of dependants) {
-      dependantState[dependant] = (await adapter.find(dependant, options))?.state ?? 'missing';
+      dependantState[dependant] =
+        (await readAdapter('find dependant', () => adapter.find(dependant, options), context))
+          ?.state ?? 'missing';
     }
-    const aggregate = beforeCloseRevalidationOf({ ticket: args.ticket, task, state: actual });
+    const claim = revalidateClaim({
+      projectRoot: claimRoot,
+      ticket: ticket ?? { id: args.ticket },
+      point: 'BEFORE_CLOSE',
+      claimedState: adapter.claimedState,
+      // Close has no caller-selected comparison base. Resolve the same default
+      // target SELECT pinned, so a missing `origin/master` cannot turn an
+      // otherwise current local rig into claim:scope drift.
+      targetSha: targetShaOf(claimRoot),
+    });
     const result = {
-      ...aggregate,
+      ...claim,
+      observedAt: new Date().toISOString(),
       task: { changed: task.changed, from: task.task.from, to: task.task.to },
-      state: { expected: 'in-progress', actual },
+      state: { expected: adapter.claimedState, actual },
       dependants,
       dependantState,
     };
     if (runDir) {
       recordEvent({ runDir, kind: 'revalidation', data: result, now: new Date().toISOString() });
+      if (result.action === 'hold' || result.action === 'unverifiable') {
+        recordRevalidationHold(runDir, result);
+      }
     }
     if (args.json) {
       process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
@@ -265,7 +469,7 @@ if (invokedDirectly()) {
         process.stdout.write('  re-read the item before closing it; a late change is not published as Done.\n');
       }
     }
-    process.exit(result.action === 'hold' ? 2 : 0);
+    process.exit(result.action === 'hold' || result.action === 'unverifiable' ? 2 : 0);
   }
 
   let mergeBase;
@@ -275,33 +479,49 @@ if (invokedDirectly()) {
     refuse(`--base ${args.base} is not a revision this checkout can compare against: ${error.message}`);
   }
 
-  const tickets = await adapter.listEligible(options);
+  const tickets = await readAdapter('listEligible', () => adapter.listEligible(options), {
+    runDir,
+    ticket: args.ticket,
+    point: args.point,
+    json: args.json,
+  });
   const ticket = tickets.find((candidate) => String(candidate.id) === String(args.ticket)) ?? null;
 
   const snapshot = runDir ? (readState(runDir).takeUps?.[args.ticket] ?? null) : null;
-  // At SELECT a missing snapshot is a first sight only when no earlier run
-  // took the item up either — `queue/index.mjs` asks `previousTakeUp` (AR-138);
-  // here the question is this run's own take-up, which SELECT wrote — and it
-  // becomes the baseline;
-  // here it is a comparison that cannot be made — the run never recorded a
-  // take-up for this item, so `null`, not the SELECT point's `false`.
+  // BEFORE_PR reports this run's marker snapshot as compatibility evidence.
+  // A missing marker is evidence that cannot be compared, but it does not make
+  // the authoritative claim unverifiable; `revalidateClaim` decides that.
   const unverifiable = { changed: null, task: { from: snapshot, to: ticket?.updatedAt ?? null } };
-  const task = ticket && snapshot !== null ? revalidationOf({ ticket, snapshot }) : unverifiable;
+  const task = ticket && snapshot !== null ? takeUpEvidenceOf({ ticket, snapshot }) : unverifiable;
 
   const branchPaths = pathsOf(git(['diff', '--name-only', '-z', mergeBase, 'HEAD']));
   const mainPaths = pathsOf(git(['diff', '--name-only', '-z', mergeBase, args.base]));
   const cited = [...new Set([...branchPaths, ...citedByPremises(runDir)])];
   const mainChanged = mainPaths.filter((path) => cited.includes(path));
 
-  const aggregate = beforePrRevalidationOf({ ticket: args.ticket, task, mainChanged });
+  const claim = revalidateClaim({
+    projectRoot: claimRoot,
+    ticket: ticket ?? { id: args.ticket },
+    point: 'BEFORE_PR',
+    claimedState: adapter.claimedState,
+    targetSha: targetShaOf(claimRoot, args.base),
+  });
+  const aggregate = withAdditionalDrift(
+    claim,
+    mainChanged.map((path) => `main:${path}`),
+  );
   const result = {
     ...aggregate,
+    observedAt: new Date().toISOString(),
     task: { changed: task.changed, from: task.task.from, to: task.task.to },
     main: { base: args.base, mergeBase, cited, changed: mainChanged },
   };
 
   if (runDir) {
     recordEvent({ runDir, kind: 'revalidation', data: result, now: new Date().toISOString() });
+    if (result.action === 'hold' || result.action === 'unverifiable') {
+      recordRevalidationHold(runDir, result);
+    }
   }
 
   if (args.json) {
@@ -313,5 +533,5 @@ if (invokedDirectly()) {
       process.stdout.write('  re-read the item and the default branch before opening or updating the PR.\n');
     }
   }
-  process.exit(result.action === 'hold' ? 2 : 0);
+  process.exit(result.action === 'hold' || result.action === 'unverifiable' ? 2 : 0);
 }