@codyswann/lisa 2.332.4 → 2.333.0

package/package.json

@@ -115,7 +115,7 @@
     "brace-expansion": ">=5.0.9"
   },
   "name": "@codyswann/lisa",
-  "version": "2.332.4",
+  "version": "2.333.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.332.4",
+  "version": "2.333.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.332.4",
+  "version": "2.333.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -126,13 +126,50 @@ auto-merge against a stale head you have not verified.
 `gh pr merge <pr> --auto --<merge_method>`. Enabling auto-merge is **not terminal**
 — continue the loop below until the PR is actually `MERGED` or `CLOSED`.
 
-If any later step will push commits, temporarily remove the auto-merge latch
-before the push when GitHub exposes that mutation (`disablePullRequestAutoMerge`),
-or otherwise treat the push as a merge race: immediately re-read `headRefOid`,
-reset `verify_commit` to the pushed head, wait until that head's checks have
-started, then re-enable auto-merge. Do not leave auto-merge armed while a
-required fix, CodeRabbit follow-up, generated artifact update, or CI auto-fix is
-still in flight.
+**With `auto_merge=true`, leave the latch ARMED — never disable auto-merge.**
+(Under `auto_merge=false` the deliberate disarm above still applies: that mode
+must leave the PR open for a human, so a pre-existing latch is removed on
+purpose. Everything below is the `auto_merge=true` path.)
+
+Once a fix is PUSHED the latch is safe: GitHub evaluates required checks against
+the PR's current head, so a new commit whose checks have not reported leaves the
+PR blocked. Auto-merge cannot ship a commit nothing has verified.
+
+The only window a disarm ever protected is the gap between deciding to fix
+something and that fix landing — during which the PR is genuinely green and
+genuinely mergeable, and auto-merge firing is GitHub behaving correctly. Two
+merges in this repo's history are attributed to that window (#1392, and the
+release that shipped the `./hooks/` Cursor bug). Both were fixed forward within
+minutes; one was a one-line docs inconsistency.
+
+That evidence is also weaker than it looks: **auto-merge attributes the merge to
+whoever enabled it**, so an auto-merge and a human pressing Merge are
+indistinguishable in the timeline. The record cannot tell us those PRs were not
+simply merged by hand while the latch happened to be armed.
+
+Against that, disarming costs something certain. Disabling is a durable state
+change on GitHub; re-enabling is one more step the run has to reach. When a run
+ends in between — turns exhausted, job timeout, or you concluding the work while
+checks are still pending — the latch stays off and nothing restores it. The PR is
+left WORSE OFF THAN IF THIS SKILL HAD NEVER RUN: it has lost the mechanism that
+merges it while no agent is watching, and the run reports success. Measured on
+`gunnertech/frontend#282`, the latch went off 14s before the fix commit and the
+PR sat 26 minutes after going green, against ~3 minutes for PRs this skill never
+touched.
+
+So the trade is a rare, unproven miss that costs a fix-forward PR, against a
+frequent, silent stall on every PR this skill repairs. Take the rare one.
+
+What still applies on a push: immediately re-read `headRefOid` and reset
+`verify_commit` to the pushed head, so the shipped-verification in step 3 checks
+what you actually pushed rather than the commit you replaced. That ancestry check
+is what CATCHES a raced merge — it fails loudly when the fix SHA is not an
+ancestor of the base branch — so the rare miss is detected rather than silent.
+
+**Invariant:** never terminate having left auto-merge OFF on an open PR when
+`auto_merge=true`. If some future path does disable it, restoring it is a
+terminal obligation on EVERY exit — including give-up, budget-exhausted and error
+paths — not a later step in a sequence.
 
 - **Capability fallback** (`auto_merge=true` only): if the repo disallows
   auto-merge, do not fail. Keep watching; once checks are green, the review gate
@@ -215,10 +252,9 @@ registered you will instead see real conflict markers — run
 ### c. Failing CI / deploy checks (`statusCheckRollup` has FAILURE)
 Inspect the failing check's logs (`gh pr checks <pr>`, `gh run view <run> --log-failed`).
 Fix the underlying code inline — **never lower thresholds, skip tests, or disable
-checks** to force green. Before pushing the fix, disarm auto-merge or classify the
-run as race-prone, then after the push re-read the PR head, update `verify_commit`
-to that exact SHA, wait for checks on that head to start, and only then resume
-auto-merge. When the root cause is an upstream Lisa template/postinstall bug
+checks** to force green. Leave auto-merge armed across the push (section 1);
+after it, re-read the PR head and update `verify_commit` to that exact SHA so the
+shipped-verification checks what you pushed. When the root cause is an upstream Lisa template/postinstall bug
 rather than this project's code, fix it upstream and propagate down rather than
 patching only here.
 
@@ -227,10 +263,9 @@ Delegate to the `pull-request-review` skill with the PR number. It owns the whol
 comment cycle: fetch every unresolved human + bot thread (with resolution state via
 GraphQL), implement valid feedback (commit + push), reply to invalid feedback, and
 resolve every thread via `resolveReviewThread` so the branch-protection
-thread-resolution gate clears. If that skill needs to push a commit, auto-merge
-must be disabled first when possible; when it returns, re-read `headRefOid`, reset
-`verify_commit` to the returned/pushed head, wait for that head's checks to start,
-then re-enable auto-merge and continue. Do not re-implement review handling here
+thread-resolution gate clears. If that skill needs to push a commit, leave
+auto-merge armed (section 1); when it returns, re-read `headRefOid` and reset
+`verify_commit` to the returned/pushed head, then continue. Do not re-implement review handling here
 — it is the single source of truth for review-thread handling.
 
 ### e. Review gate stall (`reviewDecision == CHANGES_REQUESTED`)
@@ -252,9 +287,9 @@ branch (the CI auto-fix workflow engaged before this session took the lease),
 adjudicate it: merge it into the head branch if the fix is correct and still
 needed, otherwise close it and delete the side branch. Never leave it dangling
 — it represents a competing writer's pending work. Merging it mutates the
-driven branch, so treat it like any other push: disarm auto-merge first,
-re-read `headRefOid`, reset `verify_commit` to the merged head, wait for that
-head's checks to start, then re-enable auto-merge (section 1). In
+driven branch, so treat it like any other push: leave auto-merge armed
+(section 1), then re-read `headRefOid` and reset `verify_commit` to the merged
+head. In
 `on_blocker=report` mode this whole step is off-limits (diagnose-only): do not
 merge, close, or delete anything — return `blocked:pending-auto-fix`.
 

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/aws-bootstrap.mjs

@@ -33,9 +33,106 @@ const ACCESS_KEY = "AWS_ACCESS_KEY_ID";
 const SECRET_KEY = "AWS_SECRET_ACCESS_KEY";
 const REGION = "AWS_DEFAULT_REGION";
 
+/** Selects which environment's role a session assumes. */
+const PROFILE = "AWS_PROFILE";
+
 /** The bundle that carries the agent's identity. */
 export const BOOTSTRAP_KEY = "LISA_AWS_BOOTSTRAP_JSON";
 
+/**
+ * The profile that holds the bootstrap key pair and is assumed FROM.
+ *
+ * Named rather than `default` so it can never be picked up by accident: this
+ * identity can assume roles and do nothing else, so a call that silently ran as
+ * it would fail with a permissions error far from its cause.
+ */
+export const SOURCE_PROFILE = "lisa-bootstrap";
+
+/**
+ * Read the bundle's `profiles`, which may be an object OR a JSON string.
+ *
+ * The real bundle stores it double-encoded — a string containing JSON — so a
+ * plain `typeof === "object"` check silently yields zero profiles and every
+ * environment quietly disappears. Failing that way is worse than throwing:
+ * everything still "works", as the assume-only identity, with no permissions.
+ * @param {object|null} bundle Parsed bootstrap bundle.
+ * @returns {Record<string, {roleArn?: string, region?: string}>} Profiles by name.
+ */
+export function readProfiles(bundle) {
+  const raw = bundle?.profiles;
+  if (!raw) return {};
+  if (typeof raw === "object") return raw;
+  if (typeof raw !== "string") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Render `~/.aws/credentials` and `~/.aws/config` from the bundle.
+ *
+ * The bundle carries a `profiles` map — one entry per environment, each a
+ * `roleArn` in a DIFFERENT account — plus the `externalId` those roles require.
+ * Nothing consumed any of it, so `--profile agent-dev` failed with "profile not
+ * found" and every call fell back to the bootstrap identity in the shared
+ * account. That identity can assume roles and nothing else, which is why
+ * `aws sts get-caller-identity` could succeed while real work had no
+ * permissions anywhere: a green check that proved only the first link.
+ *
+ * Writing the pair here rather than exporting it is deliberate. Exported
+ * environment credentials OUTRANK `AWS_PROFILE`, so a session that exports them
+ * ignores whichever profile it selects — the profiles would exist and never be
+ * used.
+ * @param {object} bundle Parsed bootstrap bundle.
+ * @returns {{credentials: string, config: string, profiles: string[]}|null}
+ *   Rendered file contents and the profile names, or null when unusable.
+ */
+export function renderAwsProfiles(bundle) {
+  if (!bundle) return null;
+
+  const accessKeyId = bundle.accessKeyId ?? bundle.aws_access_key_id;
+  const secretAccessKey =
+    bundle.secretAccessKey ?? bundle.aws_secret_access_key;
+  if (!accessKeyId || !secretAccessKey) return null;
+
+  const profiles = readProfiles(bundle);
+
+  const credentials = [
+    `[${SOURCE_PROFILE}]`,
+    `aws_access_key_id = ${accessKeyId}`,
+    `aws_secret_access_key = ${secretAccessKey}`,
+    "",
+  ].join("\n");
+
+  const sections = [];
+  const names = [];
+  for (const [name, entry] of Object.entries(profiles)) {
+    const roleArn = entry?.roleArn ?? entry?.role_arn;
+    if (!roleArn) continue;
+
+    // A name is only usable if it can be written as an ini section header and
+    // read back as the same string. Anything with a bracket or newline would
+    // either truncate or inject extra lines into ~/.aws/config, and a config
+    // file this corrupts is worse than one it never wrote.
+    if (!/^[\w.@-]+$/.test(name)) continue;
+
+    const lines = [`[profile ${name}]`, `role_arn = ${roleArn}`];
+    lines.push(`source_profile = ${SOURCE_PROFILE}`);
+    if (bundle.externalId) lines.push(`external_id = ${bundle.externalId}`);
+    if (entry.region) lines.push(`region = ${entry.region}`);
+    sections.push(`${lines.join("\n")}\n`);
+    // Collected here, where the name is already in scope. Recovering it by
+    // re-parsing the rendered text made the header format load-bearing: a
+    // change to it would silently corrupt every returned name.
+    names.push(name);
+  }
+
+  return { credentials, config: sections.join("\n"), profiles: names };
+}
+
 /**
  * Read the bootstrap bundle, treating anything malformed as absent.
  *
@@ -80,16 +177,64 @@ export function deriveAwsEnvironment(selected) {
   // explicit. Overriding that would be this module guessing against an operator.
   if (selected.has(ACCESS_KEY) || selected.has(SECRET_KEY)) return derived;
 
-  const note =
-    `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access. Exported ` +
-    `deliberately so it overrides any ambient ${ACCESS_KEY} the host injects — ` +
-    `environment variables outrank profile files in the AWS credential chain, ` +
-    `so without this a stale host value wins and every call fails with ` +
-    `InvalidClientTokenId. This is the assume-only bootstrap identity; real ` +
-    `work assumes a role from it.`;
+  // The key pair is deliberately NOT exported.
+  //
+  // It used to be, to out-shout the ambient pair a cloud container injects. That
+  // worked and cost more than it bought: exported environment credentials
+  // outrank `AWS_PROFILE`, so every call ran as the bootstrap identity — which
+  // can assume roles and do nothing else. `aws sts get-caller-identity`
+  // succeeded while real work had no permissions in any environment account,
+  // because each environment is a SEPARATE account reached by assuming a role.
+  //
+  // The pair now lives in ~/.aws/credentials as the source profile, and the
+  // session selects an environment instead. The ambient pair is unset by the
+  // shell profile rather than overridden — removing the poison beats out-
+  // shouting it, and it is what makes `--profile agent-staging` behave exactly
+  // as it does on a developer's machine.
+  // Only profiles that actually get WRITTEN are candidates. Selecting a name
+  // that ~/.aws/config never contains — an entry with no roleArn, or a name too
+  // exotic to be an ini header — fails with "profile not found", which is the
+  // exact failure this whole change removes.
+  const names = renderAwsProfiles(bundle)?.profiles ?? [];
 
-  derived.set(ACCESS_KEY, { value: String(accessKeyId), note });
-  derived.set(SECRET_KEY, { value: String(secretAccessKey), note });
+  // No usable profiles is not a reason to hand back a session with NOTHING.
+  //
+  // The pair stops being exported only because a profile supersedes it. With no
+  // profile to select, exporting it is the difference between a degraded
+  // session (the assume-only identity, which at least authenticates) and a dead
+  // one — and the managed shell block unsets the ambient pair, so nothing would
+  // fill the gap.
+  if (names.length === 0) {
+    const note =
+      `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access. The bundle ` +
+      `declares no usable per-environment profile, so this falls back to the ` +
+      `bootstrap identity. It can assume roles and little else — if AWS calls ` +
+      `fail with permission errors, the bundle's "profiles" map is the thing ` +
+      `to check.`;
+    derived.set(ACCESS_KEY, { value: String(accessKeyId), note });
+    derived.set(SECRET_KEY, { value: String(secretAccessKey), note });
+  }
+
+  if (names.length > 0 && !selected.has(PROFILE)) {
+    // Never production by default. An implicit production profile is one
+    // careless command away from a bad afternoon; that one must be typed.
+    const preferred =
+      names.find(name => /dev/i.test(name)) ??
+      names.find(name => !/prod/i.test(name)) ??
+      names[0];
+
+    derived.set(PROFILE, {
+      value: preferred,
+      note:
+        `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access. Selects the ` +
+        `environment whose role this session assumes, via ~/.aws/config. ` +
+        `Defaults to a non-production profile deliberately — reach production ` +
+        `by naming it (\`--profile ${names.find(n => /prod/i.test(n)) ?? "…"}\`). ` +
+        `The bootstrap key pair is NOT exported: environment credentials ` +
+        `outrank AWS_PROFILE, so exporting them would ignore this selection ` +
+        `and run everything as the assume-only identity.`,
+    });
+  }
 
   const region = bundle.region ?? bundle.defaultRegion;
   if (region && !selected.has(REGION)) {

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/materialize-secrets.mjs

@@ -31,7 +31,12 @@ import {
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-import { deriveAwsEnvironment } from "./aws-bootstrap.mjs";
+import {
+  BOOTSTRAP_KEY,
+  deriveAwsEnvironment,
+  parseBootstrap,
+  renderAwsProfiles,
+} from "./aws-bootstrap.mjs";
 import { renderEnv, renderNotes } from "./envfile.mjs";
 import { fetchAll } from "./providers.mjs";
 import { materializedPaths, readConfig } from "./surfaces.mjs";
@@ -68,6 +73,15 @@ const PROFILE_MARKER = "# >>> lisa secrets (managed) >>>";
 /** Closes the managed block. */
 const PROFILE_END = "# <<< lisa secrets (managed) <<<";
 
+/**
+ * Identifies an `~/.aws` file as one this wrote, and may therefore replace.
+ *
+ * `#` is a comment in the AWS shared-config format, so this is inert to every
+ * consumer while still being the thing that distinguishes "our file, refresh
+ * it" from "someone else's file, leave it alone".
+ */
+const MANAGED_MARKER = "# managed by lisa-secrets-access";
+
 /**
  * Make every shell in this container load the materialized secrets.
  *
@@ -95,6 +109,14 @@ export function installProfileSourcing(valuesFile, options = {}) {
 
   const block = [
     PROFILE_MARKER,
+    // Unset BEFORE sourcing. A cloud container injects its own AWS key pair,
+    // and environment credentials outrank both ~/.aws profiles and AWS_PROFILE
+    // — so leaving them set means the session ignores whichever environment it
+    // selected and runs as whatever the host injected. That is how a perfectly
+    // valid credential produced InvalidClientTokenId for a day. Removing the
+    // poison beats out-shouting it, and it is what lets `--profile agent-dev`
+    // behave here exactly as it does on a developer's machine.
+    `unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN`,
     `if [ -f "${valuesFile}" ]; then`,
     `  set -a`,
     `  . "${valuesFile}"`,
@@ -126,6 +148,61 @@ export function installProfileSourcing(valuesFile, options = {}) {
   return updated;
 }
 
+/**
+ * Write `~/.aws/credentials` and `~/.aws/config` from the bootstrap bundle.
+ *
+ * Both at 0600 inside a 0700 directory, matching how the materialized secrets
+ * themselves are protected — the credentials file holds the source key pair.
+ * @param {object|null} bundle Parsed bootstrap bundle.
+ * @param {object} [options] Home directory and file seams, for tests.
+ * @returns {string[]} The profile names written.
+ */
+export function installAwsProfiles(bundle, options = {}) {
+  const {
+    home = process.env.HOME || homedir(),
+    mkdir = mkdirSync,
+    write = writeFileSync,
+    read = readFileSync,
+    exists = existsSync,
+    chmod = chmodSync,
+  } = options;
+
+  const rendered = renderAwsProfiles(bundle);
+  if (!rendered) return [];
+
+  const dir = join(home, ".aws");
+
+  // Never overwrite an ~/.aws this did not write.
+  //
+  // These are whole-file writes, so a pre-existing credentials file — a
+  // developer's own profiles, or something another tool set up — would be
+  // destroyed rather than merged. This only runs on a surface allowed to write
+  // secrets to disk (a disposable container), but "usually disposable" is not a
+  // reason to be able to delete someone's credentials. The marker makes our own
+  // file re-writable while anything else is left alone and reported.
+  for (const name of ["credentials", "config"]) {
+    const file = join(dir, name);
+    if (exists(file) && !String(read(file, "utf8")).includes(MANAGED_MARKER)) {
+      return [];
+    }
+  }
+
+  mkdir(dir, { recursive: true, mode: 0o700 });
+  chmod(dir, 0o700);
+  write(
+    join(dir, "credentials"),
+    `${MANAGED_MARKER}\n${rendered.credentials}`,
+    {
+      mode: 0o600,
+    }
+  );
+  write(join(dir, "config"), `${MANAGED_MARKER}\n${rendered.config}`, {
+    mode: 0o600,
+  });
+
+  return rendered.profiles;
+}
+
 export function materialize(cfg = readConfig()) {
   if (!cfg.capabilities.mayWriteValues) {
     throw new Error(
@@ -170,7 +247,21 @@ export function materialize(cfg = readConfig()) {
   // materialized" and "the credential is usable" the same statement.
   const sourced = installProfileSourcing(valuesFile);
 
-  return { count: selected.size, derived: derived.size, dir, sourced };
+  // The environments live in separate AWS accounts, reached by assuming a role
+  // per environment. Without these files `--profile agent-dev` fails with
+  // "profile not found" and everything silently falls back to the bootstrap
+  // identity, which can assume roles and do nothing else.
+  const profiles = installAwsProfiles(
+    parseBootstrap(selected.get(BOOTSTRAP_KEY)?.value)
+  );
+
+  return {
+    count: selected.size,
+    derived: derived.size,
+    dir,
+    sourced,
+    profiles,
+  };
 }
 
 function main() {

package/plugins/lisa/hooks/block-no-verify.sh

@@ -20,18 +20,41 @@ set -euo pipefail
 
 input="$(cat)"
 
-tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
+# Both interpreters must be probed BEFORE they are used, and a missing one must
+# be announced rather than swallowed.
+#
+# `jq` used to be called unguarded here while `python3` two lines below was
+# guarded. Under `set -e` an absent jq aborted the script with 127, and Claude
+# Code treats any non-2 exit as a NON-BLOCKING hook error — so the hook that
+# enforces "never --no-verify" silently permitted the very thing it exists to
+# stop. It was not hypothetical: agent containers routinely ship no jq (that is
+# why jq is now a pinned toolchain entry). The Codex variant of this script has
+# always had the guard, so this was a parity gap rather than a design choice.
+#
+# Degrading to "allow" is still the right behaviour — a hook that cannot parse
+# its input cannot tell a bypass from an ordinary command, and failing closed
+# would block every Bash call on a machine missing an interpreter. What is NOT
+# right is doing it quietly, so the operator gets one line on stderr saying the
+# protection is off. A guard that is silently absent reads exactly like a guard
+# that is passing.
+for required in jq python3; do
+  if ! command -v "$required" >/dev/null 2>&1; then
+    printf 'block-no-verify: %s not found; --no-verify protection is NOT active\n' \
+      "$required" >&2
+    exit 0
+  fi
+done
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
 if [ "$tool_name" != "Bash" ]; then
   exit 0
 fi
 
-command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty')"
+command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
 if [ -z "$command_str" ]; then
   exit 0
 fi
 
-command -v python3 >/dev/null 2>&1 || exit 0
-
 if ! BLOCK_NO_VERIFY_COMMAND="$command_str" python3 - <<'PY'
 import os
 import re

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

@@ -126,13 +126,50 @@ auto-merge against a stale head you have not verified.
 `gh pr merge <pr> --auto --<merge_method>`. Enabling auto-merge is **not terminal**
 — continue the loop below until the PR is actually `MERGED` or `CLOSED`.
 
-If any later step will push commits, temporarily remove the auto-merge latch
-before the push when GitHub exposes that mutation (`disablePullRequestAutoMerge`),
-or otherwise treat the push as a merge race: immediately re-read `headRefOid`,
-reset `verify_commit` to the pushed head, wait until that head's checks have
-started, then re-enable auto-merge. Do not leave auto-merge armed while a
-required fix, CodeRabbit follow-up, generated artifact update, or CI auto-fix is
-still in flight.
+**With `auto_merge=true`, leave the latch ARMED — never disable auto-merge.**
+(Under `auto_merge=false` the deliberate disarm above still applies: that mode
+must leave the PR open for a human, so a pre-existing latch is removed on
+purpose. Everything below is the `auto_merge=true` path.)
+
+Once a fix is PUSHED the latch is safe: GitHub evaluates required checks against
+the PR's current head, so a new commit whose checks have not reported leaves the
+PR blocked. Auto-merge cannot ship a commit nothing has verified.
+
+The only window a disarm ever protected is the gap between deciding to fix
+something and that fix landing — during which the PR is genuinely green and
+genuinely mergeable, and auto-merge firing is GitHub behaving correctly. Two
+merges in this repo's history are attributed to that window (#1392, and the
+release that shipped the `./hooks/` Cursor bug). Both were fixed forward within
+minutes; one was a one-line docs inconsistency.
+
+That evidence is also weaker than it looks: **auto-merge attributes the merge to
+whoever enabled it**, so an auto-merge and a human pressing Merge are
+indistinguishable in the timeline. The record cannot tell us those PRs were not
+simply merged by hand while the latch happened to be armed.
+
+Against that, disarming costs something certain. Disabling is a durable state
+change on GitHub; re-enabling is one more step the run has to reach. When a run
+ends in between — turns exhausted, job timeout, or you concluding the work while
+checks are still pending — the latch stays off and nothing restores it. The PR is
+left WORSE OFF THAN IF THIS SKILL HAD NEVER RUN: it has lost the mechanism that
+merges it while no agent is watching, and the run reports success. Measured on
+`gunnertech/frontend#282`, the latch went off 14s before the fix commit and the
+PR sat 26 minutes after going green, against ~3 minutes for PRs this skill never
+touched.
+
+So the trade is a rare, unproven miss that costs a fix-forward PR, against a
+frequent, silent stall on every PR this skill repairs. Take the rare one.
+
+What still applies on a push: immediately re-read `headRefOid` and reset
+`verify_commit` to the pushed head, so the shipped-verification in step 3 checks
+what you actually pushed rather than the commit you replaced. That ancestry check
+is what CATCHES a raced merge — it fails loudly when the fix SHA is not an
+ancestor of the base branch — so the rare miss is detected rather than silent.
+
+**Invariant:** never terminate having left auto-merge OFF on an open PR when
+`auto_merge=true`. If some future path does disable it, restoring it is a
+terminal obligation on EVERY exit — including give-up, budget-exhausted and error
+paths — not a later step in a sequence.
 
 - **Capability fallback** (`auto_merge=true` only): if the repo disallows
   auto-merge, do not fail. Keep watching; once checks are green, the review gate
@@ -215,10 +252,9 @@ registered you will instead see real conflict markers — run
 ### c. Failing CI / deploy checks (`statusCheckRollup` has FAILURE)
 Inspect the failing check's logs (`gh pr checks <pr>`, `gh run view <run> --log-failed`).
 Fix the underlying code inline — **never lower thresholds, skip tests, or disable
-checks** to force green. Before pushing the fix, disarm auto-merge or classify the
-run as race-prone, then after the push re-read the PR head, update `verify_commit`
-to that exact SHA, wait for checks on that head to start, and only then resume
-auto-merge. When the root cause is an upstream Lisa template/postinstall bug
+checks** to force green. Leave auto-merge armed across the push (section 1);
+after it, re-read the PR head and update `verify_commit` to that exact SHA so the
+shipped-verification checks what you pushed. When the root cause is an upstream Lisa template/postinstall bug
 rather than this project's code, fix it upstream and propagate down rather than
 patching only here.
 
@@ -227,10 +263,9 @@ Delegate to the `pull-request-review` skill with the PR number. It owns the whol
 comment cycle: fetch every unresolved human + bot thread (with resolution state via
 GraphQL), implement valid feedback (commit + push), reply to invalid feedback, and
 resolve every thread via `resolveReviewThread` so the branch-protection
-thread-resolution gate clears. If that skill needs to push a commit, auto-merge
-must be disabled first when possible; when it returns, re-read `headRefOid`, reset
-`verify_commit` to the returned/pushed head, wait for that head's checks to start,
-then re-enable auto-merge and continue. Do not re-implement review handling here
+thread-resolution gate clears. If that skill needs to push a commit, leave
+auto-merge armed (section 1); when it returns, re-read `headRefOid` and reset
+`verify_commit` to the returned/pushed head, then continue. Do not re-implement review handling here
 — it is the single source of truth for review-thread handling.
 
 ### e. Review gate stall (`reviewDecision == CHANGES_REQUESTED`)
@@ -252,9 +287,9 @@ branch (the CI auto-fix workflow engaged before this session took the lease),
 adjudicate it: merge it into the head branch if the fix is correct and still
 needed, otherwise close it and delete the side branch. Never leave it dangling
 — it represents a competing writer's pending work. Merging it mutates the
-driven branch, so treat it like any other push: disarm auto-merge first,
-re-read `headRefOid`, reset `verify_commit` to the merged head, wait for that
-head's checks to start, then re-enable auto-merge (section 1). In
+driven branch, so treat it like any other push: leave auto-merge armed
+(section 1), then re-read `headRefOid` and reset `verify_commit` to the merged
+head. In
 `on_blocker=report` mode this whole step is off-limits (diagnose-only): do not
 merge, close, or delete anything — return `blocked:pending-auto-fix`.