@codyswann/lisa 4.45.16 → 4.46.0

package/plugins/src/base/scripts/pr-arming-sweep.mjs

@@ -0,0 +1,561 @@
+#!/usr/bin/env node
+/**
+ * Unarmed open pull request detection for `/lisa:queue-status` (#3903).
+ *
+ * ## The gap this closes
+ *
+ * A pull request can be fully green and permanently unmergeable because
+ * `autoMergeRequest` is `null`, and nothing surfaces it. Green-and-unarmed and
+ * green-and-waiting read identically on every surface anyone checks: the checks
+ * list is green, `mergeStateStatus` is green, the PR page shows no complaint,
+ * and the PR simply sits. **There is no failing signal to notice**, which is
+ * why "waits forever" is accurate and why nobody catches it by watching for
+ * failures.
+ *
+ * Gates answer *"is this change acceptable?"*. None of them asks *"is anything
+ * going to act on the answer?"* — the observer that would notice sits outside
+ * the gate entirely, which is where this module sits.
+ *
+ * ## Report-only, and why
+ *
+ * **This is a report surface, not a gate.** It is registered in no `gates`
+ * block, runs on no commit/push/PR hook, and blocks nothing. Two reasons, both
+ * load-bearing:
+ *
+ * 1. Arming is a decision with its own arm-time control (`block-blind-automerge`,
+ *    #3806). #3903 is about VISIBILITY of the unarmed state and explicitly puts
+ *    automatic arming out of scope; a control that blocked on this would be
+ *    making the arming decision by the back door.
+ * 2. Unarmed-ness is a property of the QUEUE, not of a change. Blocking a
+ *    contributor's push because some other PR is unarmed punishes the wrong
+ *    party. A governor about throughput fails open on its findings.
+ *
+ * ## But the MEASUREMENT fails closed
+ *
+ * The healthy state of this check is an EMPTY report — so a mistyped field
+ * path, a wrong JSON accessor, or a filter that excludes everything returns
+ * empty and looks exactly like a clean queue. That is the failure this module
+ * is most prone to, so the two are never allowed to share a verdict:
+ *
+ * - `UNARMED` means *examined, and `autoMergeRequest` was `null`*.
+ * - `NOT_EXAMINED` means *the arming state was never read* — the
+ *   `autoMergeRequest` key is absent from the payload, which is what a caller
+ *   that forgot the field in `gh pr list --json` produces. It is NOT `null`,
+ *   and it must never be reported as armed or folded into a clean sweep.
+ *
+ * A sweep containing even one `NOT_EXAMINED` pull request returns
+ * `NOT_MEASURED`, never `MEASURED_CLEAN`. `MEASURED_CLEAN` is a POSITIVE
+ * ASSERTION — "I read the arming state of all N open pull requests and every
+ * one is armed or deliberately unarmed" — not an absence of complaints. The CLI
+ * exit codes carry the same split: 0 clean, 1 findings, **2 not measured**, so
+ * a scheduled sweep whose query broke fails loudly instead of reporting a
+ * healthy queue.
+ *
+ * ## Current state, never arming history
+ *
+ * Measured on this repository the night #3903 was built: a PR armed earlier in
+ * the same session, and verbally confirmed as armed, was later observed with
+ * `autoMergeRequest: null`; re-arming it succeeded immediately. **Arming can be
+ * silently dropped after the fact** — most plausibly when the branch is updated
+ * or force-updated underneath it. That defeats the obvious fix: arming at
+ * PR-creation time is not sufficient if the latch can come off afterwards. So
+ * this module classifies from CURRENT state only and has no notion of whether
+ * an arm ever happened.
+ *
+ * `autoMergeRequest` is one of the few PR fields that is trustworthy — a stored
+ * setting rather than a computed one, unlike `mergeStateStatus` (#3694). So
+ * detection is cheap; nothing was asking.
+ *
+ * ## Deliberately unarmed
+ *
+ * `lisa-drive-pr-to-merge`'s `auto_merge=false` mode deliberately leaves a PR
+ * open and unarmed for a human to merge. Reporting those would train operators
+ * to ignore the report, so a deliberate hold is declarable — by the
+ * `[lisa-auto-merge-off]` body marker (the same shape as Lisa's existing
+ * `[lisa-human-gate]` marker: a token with no other meaning, so its presence
+ * anywhere in the body IS the declaration) or by the `lisa:auto-merge-off`
+ * label, for operators who prefer a surface visible in the PR list. Drafts are
+ * excluded too: GitHub will not arm a draft, so an unarmed draft is the
+ * expected state rather than a finding.
+ *
+ * **A held pull request is suppressed from the findings, never from the
+ * report.** This is a suppression mechanism, and this repository has been bitten
+ * by the shape before — an allowlist added to harden a guard became its bypass.
+ * Anyone who wants a red sweep to go green now has a one-label remedy that will
+ * look like housekeeping, so every held PR is counted AND named, on the clean
+ * path as much as the findings path. "4 armed, 0 unarmed" and "4 armed, 0
+ * unarmed, 9 held" describe very different queues, and only the second lets a
+ * human notice the label spreading.
+ *
+ * The marker may carry `reason=<text>`, which the report prints. It is optional
+ * on purpose — a required field on a suppression gets satisfied with `reason=x`
+ * and buys nothing — but its absence is printed as "no reason declared", so an
+ * unexplained hold is visibly cheaper than an explained one.
+ */
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** Per-pull-request arming verdicts. */
+export const PR_ARMING_VERDICTS = Object.freeze([
+  "ARMED",
+  "UNARMED",
+  "DELIBERATELY_UNARMED",
+  "NOT_EXAMINED",
+]);
+
+/** Whole-sweep verdicts. */
+export const PR_ARMING_SWEEP_VERDICTS = Object.freeze([
+  "MEASURED_CLEAN",
+  "UNARMED_PRS_FOUND",
+  "NOT_MEASURED",
+]);
+
+/** Body marker declaring a pull request deliberately left unarmed. */
+export const AUTO_MERGE_OFF_MARKER = "[lisa-auto-merge-off]";
+
+/** Label spelling of the same declaration, for PR-list visibility. */
+export const AUTO_MERGE_OFF_LABEL = "lisa:auto-merge-off";
+
+/**
+ * The `gh pr list --json` field selection this module needs.
+ *
+ * Exported so the skill that shells out and the tests that pin the contract
+ * read the same list — a caller that drops `autoMergeRequest` from it produces
+ * `NOT_EXAMINED`, which is the designed outcome rather than a silent pass.
+ */
+export const REQUIRED_PR_FIELDS = Object.freeze([
+  "number",
+  "title",
+  "url",
+  "isDraft",
+  "labels",
+  "body",
+  "autoMergeRequest",
+]);
+
+/**
+ * @typedef {"ARMED" | "UNARMED" | "DELIBERATELY_UNARMED" | "NOT_EXAMINED"} PullRequestArmingVerdict
+ *
+ * @typedef {{
+ *   readonly number: number | null
+ *   readonly title: string
+ *   readonly url: string
+ *   readonly verdict: PullRequestArmingVerdict
+ *   readonly reason: string
+ *   readonly declaredReason?: string | null
+ *   readonly examined: boolean
+ * }} PullRequestArming
+ */
+
+/**
+ * Classify one pull request's CURRENT auto-merge arming state.
+ *
+ * The single most important line in this function is the `hasOwnProperty`
+ * check: a payload with no `autoMergeRequest` key was never asked about arming,
+ * and answering "unarmed" or "armed" for it would be an invented measurement.
+ * `undefined` and `null` mean opposite things here and are never conflated.
+ *
+ * @param {Record<string, any>} pullRequest - One `gh pr view/list --json` object.
+ * @returns {PullRequestArming} The verdict, with the reason that produced it.
+ */
+export function classifyPullRequestArming(pullRequest) {
+  const source =
+    pullRequest !== null && typeof pullRequest === "object" ? pullRequest : {};
+  const identity = {
+    number: Number.isFinite(Number(source.number))
+      ? Number(source.number)
+      : null,
+    title: typeof source.title === "string" ? source.title : "",
+    url: typeof source.url === "string" ? source.url : "",
+  };
+
+  if (
+    !Object.hasOwn(source, "autoMergeRequest") ||
+    source.autoMergeRequest === undefined
+  ) {
+    return {
+      ...identity,
+      verdict: "NOT_EXAMINED",
+      reason: "auto-merge-field-absent",
+      examined: false,
+    };
+  }
+
+  if (typeof source.autoMergeRequest === "object") {
+    if (source.autoMergeRequest !== null) {
+      return {
+        ...identity,
+        verdict: "ARMED",
+        reason: "auto-merge-request-present",
+        examined: true,
+      };
+    }
+  } else {
+    // Neither `null` nor an auto-merge object. JSON from `gh` never produces
+    // this, so it means the value came from somewhere other than the field
+    // being asked about — an unanswered question, not an answer.
+    return {
+      ...identity,
+      verdict: "NOT_EXAMINED",
+      reason: "auto-merge-field-unrecognized",
+      examined: false,
+    };
+  }
+
+  const deliberate = deliberateHoldReason(source);
+  if (deliberate) {
+    return {
+      ...identity,
+      verdict: "DELIBERATELY_UNARMED",
+      reason: deliberate.reason,
+      declaredReason: deliberate.declaredReason,
+      examined: true,
+    };
+  }
+
+  return {
+    ...identity,
+    verdict: "UNARMED",
+    reason: "auto-merge-request-null",
+    examined: true,
+  };
+}
+
+/**
+ * Why an unarmed pull request is a deliberate hold rather than a finding.
+ *
+ * @param {Record<string, any>} pullRequest
+ * @returns {string | null} A reason slug, or `null` when the hold is undeclared.
+ */
+function deliberateHoldReason(pullRequest) {
+  if (pullRequest.isDraft === true) {
+    return { reason: "draft-pull-request", declaredReason: null };
+  }
+
+  const body = typeof pullRequest.body === "string" ? pullRequest.body : "";
+  const declaration = DECLARATION_LINE.exec(declarativeText(body));
+  if (declaration) {
+    return {
+      reason: "auto-merge-off-marker",
+      declaredReason: declaredReasonIn(declaration[1]),
+    };
+  }
+
+  const labels = Array.isArray(pullRequest.labels) ? pullRequest.labels : [];
+  const names = labels.map(label =>
+    typeof label === "string"
+      ? label
+      : typeof label?.name === "string"
+        ? label.name
+        : ""
+  );
+  if (names.some(name => name.trim().toLowerCase() === AUTO_MERGE_OFF_LABEL)) {
+    return { reason: "auto-merge-off-label", declaredReason: null };
+  }
+
+  return null;
+}
+
+/**
+ * The one shape that DECLARES a hold: the marker alone on a line, inside an
+ * HTML comment, optionally carrying `reason=<text>`.
+ *
+ * Deliberately NOT "the marker appearing anywhere". Lisa's `[lisa-human-gate]`
+ * marker is matched anywhere on the reasoning that it is a token with no other
+ * meaning, so its presence IS the declaration. **That reasoning does not
+ * transfer here, and this repository proved it the first time this control ran
+ * live**: the pull request that introduced the marker was suppressed by its own
+ * description, because the description explains what the marker is. A token
+ * that appears in prose about itself has a second meaning — being discussed —
+ * and matching it anywhere makes "write about the suppression" a way to be
+ * suppressed. Same rule as `ready-role-filing`: before matching a token, ask
+ * what it means in every position it can occupy.
+ */
+const DECLARATION_LINE =
+  /^[ \t]*<!--[ \t]*\[lisa-auto-merge-off\][ \t]*(.*?)-->[ \t]*$/im;
+
+/**
+ * The body with code spans and fenced blocks removed.
+ *
+ * Documentation of the declaration is not a declaration. Fenced examples and
+ * backticked mentions are how the marker is written ABOUT, so they are stripped
+ * before the declaration is looked for — the same move `block-direct-issue-create.sh`
+ * makes when it strips heredoc bodies before tokenising argv.
+ *
+ * @param {string} body - The raw pull request body.
+ * @returns {string} The body with quoted/code regions blanked out.
+ */
+function declarativeText(body) {
+  return body.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
+}
+
+/**
+ * Read the `reason=<text>` a declaration carries, if it carries one.
+ *
+ * A bare marker is a claim; a reason costs the writer something to write, which
+ * is what makes a declaration in this repository worth trusting. The reason is
+ * OPTIONAL rather than required — a required field on a suppression mechanism
+ * gets satisfied with `reason=x` and buys nothing — but its absence is carried
+ * through to the report and shown as "no reason declared", so a queue full of
+ * unexplained holds is visible as one.
+ *
+ * @param {string} tail - The declaration's text after the marker.
+ * @returns {string | null} The declared reason, or `null` when none was given.
+ */
+function declaredReasonIn(tail) {
+  const match = /^\s*reason[=:]\s*(.+)$/i.exec(String(tail ?? "").trim());
+  if (!match) return null;
+  const reason = match[1].replace(/--+>?\s*$/, "").trim();
+  return reason.length > 0 ? reason : null;
+}
+
+/**
+ * Sweep the open pull requests and report the unarmed ones.
+ *
+ * Read-only and total: it mutates nothing, reaches nothing over the network,
+ * and returns every finding rather than the first.
+ *
+ * @param {readonly Record<string, any>[] | {
+ *   readonly pullRequests?: readonly Record<string, any>[]
+ *   readonly fetchError?: string | null
+ * }} input - A bare `gh pr list --json` array, or the same wrapped with an
+ *   optional `fetchError` describing a query that failed.
+ * @returns {{
+ *   readonly verdict: "MEASURED_CLEAN" | "UNARMED_PRS_FOUND" | "NOT_MEASURED"
+ *   readonly reasons: readonly string[]
+ *   readonly examinedCount: number
+ *   readonly unarmed: readonly PullRequestArming[]
+ *   readonly deliberatelyUnarmed: readonly PullRequestArming[]
+ *   readonly armed: readonly PullRequestArming[]
+ *   readonly notExamined: readonly PullRequestArming[]
+ *   readonly reportOnly: true
+ * }}
+ */
+export function sweepPullRequestArming(input = []) {
+  const wrapped = Array.isArray(input)
+    ? { pullRequests: input }
+    : (input ?? {});
+  const fetchError =
+    typeof wrapped.fetchError === "string" &&
+    wrapped.fetchError.trim().length > 0
+      ? wrapped.fetchError.trim()
+      : null;
+  const list = Array.isArray(wrapped.pullRequests)
+    ? wrapped.pullRequests
+    : null;
+
+  if (fetchError !== null || list === null) {
+    return {
+      verdict: "NOT_MEASURED",
+      reasons: [
+        fetchError !== null
+          ? "pull-request-query-failed"
+          : "pull-request-list-unavailable",
+      ],
+      examinedCount: 0,
+      unarmed: [],
+      deliberatelyUnarmed: [],
+      armed: [],
+      notExamined: [],
+      reportOnly: true,
+    };
+  }
+
+  const classified = list.map(classifyPullRequestArming);
+  const bucket = verdict =>
+    classified.filter(entry => entry.verdict === verdict);
+  const buckets = {
+    unarmed: bucket("UNARMED"),
+    deliberatelyUnarmed: bucket("DELIBERATELY_UNARMED"),
+    armed: bucket("ARMED"),
+    notExamined: bucket("NOT_EXAMINED"),
+  };
+  const examinedCount = classified.filter(entry => entry.examined).length;
+
+  // Blindness outranks findings. A sweep that could not read part of the queue
+  // has no standing to call the rest of it clean, and must not print the
+  // reassuring answer for pull requests it never looked at.
+  if (buckets.notExamined.length > 0) {
+    return {
+      verdict: "NOT_MEASURED",
+      reasons: [...new Set(buckets.notExamined.map(entry => entry.reason))],
+      examinedCount,
+      ...buckets,
+      reportOnly: true,
+    };
+  }
+
+  if (buckets.unarmed.length > 0) {
+    return {
+      verdict: "UNARMED_PRS_FOUND",
+      reasons: ["unarmed-open-pull-requests"],
+      examinedCount,
+      ...buckets,
+      reportOnly: true,
+    };
+  }
+
+  return {
+    verdict: "MEASURED_CLEAN",
+    reasons: ["all-open-pull-requests-armed-or-deliberately-unarmed"],
+    examinedCount,
+    ...buckets,
+    reportOnly: true,
+  };
+}
+
+/**
+ * The CLI exit status for a sweep.
+ *
+ * `2` is the load-bearing one: an unmeasurable sweep must not exit `0` beside
+ * an empty finding list, because that is indistinguishable from a healthy
+ * queue — the exact confusion #3903 is about.
+ *
+ * @param {{ readonly verdict?: string }} sweep
+ * @returns {0 | 1 | 2}
+ */
+export function pullRequestArmingExitCode(sweep) {
+  if (sweep?.verdict === "MEASURED_CLEAN") return 0;
+  if (sweep?.verdict === "UNARMED_PRS_FOUND") return 1;
+  return 2;
+}
+
+/**
+ * Render the sweep as an operator-readable report.
+ *
+ * The clean line states what was examined rather than saying nothing, so an
+ * operator can tell a measured clean queue from a query that returned nothing.
+ *
+ * @param {ReturnType<typeof sweepPullRequestArming>} sweep
+ * @returns {string} A terminal-first report, newline-terminated.
+ */
+export function formatPullRequestArmingReport(sweep) {
+  const lines = [`Auto-merge arming: ${sweep.verdict}`];
+
+  if (sweep.verdict === "NOT_MEASURED") {
+    lines.push(
+      sweep.notExamined.length > 0
+        ? `Arming state was NOT read for ${sweep.notExamined.length} open pull request(s) (${sweep.reasons.join(", ")}).`
+        : `The open pull request list could not be read at all (${sweep.reasons.join(", ")}).`,
+      `This is not a clean queue — it is an unanswered question. Re-run the query with --json ${REQUIRED_PR_FIELDS.join(",")}.`
+    );
+    for (const entry of sweep.notExamined) {
+      lines.push(`  ? #${entry.number ?? "?"} ${entry.title}`.trimEnd());
+    }
+    return `${lines.join("\n")}\n`;
+  }
+
+  lines.push(
+    `Examined ${sweep.examinedCount} open pull request(s): ${sweep.armed.length} armed, ${sweep.unarmed.length} unarmed, ${sweep.deliberatelyUnarmed.length} deliberately unarmed.`
+  );
+
+  if (sweep.verdict === "MEASURED_CLEAN") {
+    lines.push(
+      "Every open pull request is armed or deliberately unarmed. Nothing is waiting on an absent latch."
+    );
+    lines.push(...heldLines(sweep));
+    return `${lines.join("\n")}\n`;
+  }
+
+  lines.push(
+    "These pull requests will never merge on their own. Arm each, or declare the hold:"
+  );
+  for (const entry of sweep.unarmed) {
+    lines.push(`  ! #${entry.number ?? "?"} ${entry.title}`.trimEnd());
+    if (entry.url) lines.push(`      ${entry.url}`);
+  }
+  lines.push(
+    `Arm: gh pr merge <n> --auto --merge, then read it back with gh pr view <n> --json autoMergeRequest.`,
+    `Declare a deliberate hold: add the ${AUTO_MERGE_OFF_LABEL} label, or the ${AUTO_MERGE_OFF_MARKER} marker to the body.`
+  );
+  lines.push(...heldLines(sweep));
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The held-pull-request block, which is never omitted when the bucket is
+ * non-empty.
+ *
+ * A suppression mechanism that hides what it suppresses is the next defect,
+ * not the fix for this one. This repository has already been bitten by the
+ * shape: an allowlist added to harden a guard BECAME its bypass. `lisa:auto-merge-off`
+ * is a one-label remedy for a red sweep and will look like housekeeping to
+ * whoever applies it, so every held pull request is COUNTED AND NAMED. "4 armed,
+ * 0 unarmed" and "4 armed, 0 unarmed, 9 held" describe very different queues,
+ * and only the second lets a human notice the label spreading.
+ *
+ * @param {ReturnType<typeof sweepPullRequestArming>} sweep
+ * @returns {string[]} Report lines, empty when nothing is held.
+ */
+function heldLines(sweep) {
+  if (sweep.deliberatelyUnarmed.length === 0) return [];
+
+  return [
+    `Held (declared, not merging): ${sweep.deliberatelyUnarmed.length}. Each is suppressed from the finding list above:`,
+    ...sweep.deliberatelyUnarmed.map(entry => {
+      const why = entry.declaredReason
+        ? `reason: ${entry.declaredReason}`
+        : entry.reason === "draft-pull-request"
+          ? "draft"
+          : "no reason declared";
+      const label = `#${entry.number ?? "?"} ${entry.title}`.trim();
+      return `  - ${label} (${why})`;
+    }),
+  ];
+}
+
+/**
+ * CLI: read `gh pr list --json <fields>` output on stdin, print the report.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+
+  let sweep;
+  try {
+    sweep = sweepPullRequestArming(raw.length === 0 ? {} : JSON.parse(raw));
+  } catch (error) {
+    sweep = sweepPullRequestArming({ fetchError: error.message });
+  }
+
+  const asJson = process.argv.includes("--json");
+  process.stdout.write(
+    asJson
+      ? `${JSON.stringify(sweep, null, 2)}\n`
+      : formatPullRequestArmingReport(sweep)
+  );
+  process.exitCode = pullRequestArmingExitCode(sweep);
+}
+
+/**
+ * True when `moduleUrl` names the module node was asked to run.
+ *
+ * Written out rather than imported: this is a plugin payload, which has no
+ * `./lib/` to resolve against. Same rule and reasoning as
+ * `scripts/lib/invoked-as-script.mjs` and `scoping-label-audit.mjs`.
+ *
+ * @param {string} moduleUrl - The caller's own `import.meta.url`.
+ * @param {string | undefined} [argv1] - Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the caller should run its CLI body.
+ */
+export function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  main().catch(error => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/plugins/src/base/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -229,6 +229,30 @@ fi
 gh pr view <pr> --json autoMergeRequest -q .autoMergeRequest   # must print null
 ```
 
+**Then declare the hold**, so the deliberate case stays distinguishable from the
+defect. `/lisa:queue-status`'s arming sweep (#3903) reports every open PR whose
+`autoMergeRequest` is `null`, because a green unarmed PR waits forever and no
+other surface says so. An undeclared deliberate hold appears there as a finding
+on every run, and a report that is wrong every run is one operators learn to
+ignore:
+
+```bash
+gh pr edit <pr> --add-label "lisa:auto-merge-off"
+```
+
+Where that label does not exist in the repo, put the marker in the PR body
+instead — the sweep reads either spelling — and **give it a reason**, because
+the sweep prints one and prints `no reason declared` when it cannot:
+
+```text
+<!-- [lisa-auto-merge-off] reason=<why a human owns this merge> -->
+```
+
+Declaring the hold **suppresses it from the findings, not from the report**: the
+sweep still counts and names every held PR. That is deliberate — a label that
+turned a red sweep green and left no trace would be a bypass wearing the costume
+of a fix.
+
 If the disarm fails or the re-read still shows an armed `autoMergeRequest`,
 **fail closed**: treat the PR as a hard block (section 4) and report that the
 `awaiting-human` state was NOT reached — never proceed to a state in which the

package/plugins/src/base/skills/lisa-queue-status/SKILL.md

@@ -69,6 +69,30 @@ For each inspected queue, report:
 
 The report should stay terminal-first and immediately actionable: observable queue facts first, then the smallest useful next step.
 
+## Pull request arming (#3903)
+
+Alongside the two work queues, report the **arming state of the repo's open pull requests**. A PR whose `autoMergeRequest` is `null` is fully green and permanently unmergeable: every check passes, `mergeStateStatus` is green, nothing complains, and it waits forever. Green-and-unarmed and green-and-waiting read identically on every other surface, so this is the one place that asks the question.
+
+Run the sweep rather than eyeballing the list — an LLM reading PR pages one at a time is exactly the shell-loop-by-prose failure #3512 records:
+
+```bash
+gh pr list --state open --limit 200 \
+  --json number,title,url,isDraft,labels,body,autoMergeRequest \
+  | node "${CLAUDE_PLUGIN_ROOT}/scripts/pr-arming-sweep.mjs"
+```
+
+Report the verdict verbatim, and never translate it into an absence:
+
+- `MEASURED_CLEAN` — a **positive assertion**: N open PRs were read and every one is armed or deliberately unarmed. Say the count. "Nothing to report" is not the same sentence and must not be substituted for it.
+- `UNARMED_PRS_FOUND` — list each PR. The next step is `gh pr merge <n> --auto --merge` **followed by reading the state back** (`gh pr view <n> --json autoMergeRequest`); arming can be silently dropped after the fact, so an arm that was not read back is not a fact.
+- `NOT_MEASURED` — the arming state was **not read** for at least one PR (usually a `--json` selection missing `autoMergeRequest`). This is an unanswered question, not a clean queue. Fix the query and re-run; do **not** report the queue as healthy.
+
+Arming state feeds no queue verdict and gates nothing — this stays a report, per #3903's Out of Scope. Never arm a PR from this skill; `/lisa:queue-status` is read-only.
+
+A PR deliberately left for a human (`lisa-drive-pr-to-merge`'s `auto_merge=false` mode) declares itself with the `lisa:auto-merge-off` label or a `[lisa-auto-merge-off] reason=<text>` body marker. Drafts are excluded — GitHub will not arm a draft.
+
+**Held PRs are suppressed from the findings, never from the report.** Always show the `Held (declared, not merging): N` block and the numbers under it, including when the verdict is `MEASURED_CLEAN`. This is a one-label remedy for a red sweep and it will look like housekeeping to whoever applies it — "4 armed, 0 unarmed" and "4 armed, 0 unarmed, 9 held" describe very different queues, and only the second lets an operator notice the label spreading. Flag it when holds outnumber armed PRs, or when several read `no reason declared`.
+
 ## Highlight semantics
 
 Each queue section may include one or more highlighted items. A highlight is not a raw dump of every issue in that role; it is the single oldest or otherwise most actionable item Lisa can justify surfacing without mutating work.

package/scripts/lib/per-agent-hook-filter.mjs

@@ -151,6 +151,25 @@ const SCRIPT_RULES = {
     agy: false,
     copilot: true,
   },
+  // Ships wherever the agent has a session-start event, on the same reasoning
+  // as `inject-resolved-config.sh`. The question it answers — WHICH COPY of
+  // Lisa is executing in this session — is not vendor-specific: every harness
+  // resolves a plugin copy once at session start and then runs it unchanged,
+  // so every harness can hand an agent a stale contract while the repository
+  // is green.
+  //
+  // Documented gap: agy has no SessionStart event at all, so agy sessions get
+  // no vintage block. The compensating rung is the shared one AGENTS.md
+  // requires when a harness cannot represent a control — the Bash enforcement
+  // dispatcher still names the producing copy and its vintage in every refusal
+  // it prints, and `lisa doctor` reports the same resolution on every agent.
+  "enforcement-vintage.sh": {
+    claude: true,
+    codex: true,
+    cursor: true,
+    agy: false,
+    copilot: true,
+  },
   "inject-flow-context.sh": {
     claude: true,
     codex: true,