@codyswann/lisa 4.34.7 → 4.34.9

package/plugins/lisa-cursor/hooks/block-direct-issue-create.sh

@@ -1399,12 +1399,190 @@ def nested_operands(argv):
 inspected_files = set()
 
 
+# Interpreters whose OPERAND is a program they run. Broader than a shell list
+# because `file_creation` recognises a creation in any language — the
+# `node wrapper.mjs` that speaks HTTP directly is exactly the shape #3484
+# measured as a fail-open, so narrowing this to shells would reopen it.
+EXECUTING_INTERPRETERS = {
+    "bash", "dash", "ksh", "sh", "zsh",
+    "bun", "deno", "node", "nodejs", "perl", "php",
+    "python", "python3", "ruby", "ts-node", "tsx",
+}
+
+# `.` and its `source` alias run the named file in the CURRENT shell.
+SOURCE_BUILTINS = {"source", "."}
+
+# Wrappers that run what FOLLOWS them without changing what it is, mapped to
+# (options whose value is a SEPARATE token, positional operands consumed).
+# The positional count is why this is a table: `timeout 5 bash create.sh` puts
+# an operand between the wrapper and the interpreter, so a walk that steps over
+# `-flags` only stops at `5` and never reaches the interpreter.
+EXEC_WRAPPERS = {
+    "builtin": (frozenset(), 0),
+    "command": (frozenset(), 0),
+    "exec": (frozenset({"-a"}), 0),
+    "env": (frozenset({"-u", "--unset", "-C", "--chdir", "--argv0"}), 0),
+    "nice": (frozenset({"-n", "--adjustment"}), 0),
+    "nohup": (frozenset(), 0),
+    "setsid": (frozenset(), 0),
+    "stdbuf": (frozenset({"-i", "-o", "-e"}), 0),
+    "sudo": (frozenset({"-u", "--user", "-g", "--group", "-C", "--close-from"}), 0),
+    "time": (frozenset(), 0),
+    "timeout": (frozenset({"-k", "--kill-after", "-s", "--signal"}), 1),
+}
+
+# Interpreter options that mean "no script file follows": a command string or a
+# module name, both of which the guard reads by other means or not at all.
+NO_SCRIPT_OPTIONS = {"-c", "-e", "-m", "--eval", "--command", "--module"}
+
+# Programs that READ their operands and never execute them as programs.
+#
+# This is an allowlist of readers rather than the inverse, and the asymmetry is
+# deliberate. An UNKNOWN program with a file operand is still followed, because
+# whether it executes that operand is genuinely unknowable from the command —
+# and a probe in this guard's own suite drives it with a runner nobody
+# enumerated precisely so a fix keyed on a list of interpreters fails. Failing
+# closed on the unknown keeps that coverage.
+#
+# What the list buys is the measured population of #3705, every member of which
+# is a well-known inspector: `git diff`, `grep -n`, `wc -l`, a `git grep`
+# PATHSPEC, `sed -n '1,50p'`, and a test run. `git` is here wholesale because no
+# git subcommand executes a named file as a program — `git commit -F <file>` and
+# `git grep -- <pathspec>` both take the path as data.
+#
+# Test runners are here on purpose and it is the one entry worth arguing about.
+# `vitest <file>` does run that file, so the executes-rule would follow it — but
+# running a test is not filing an issue, and refusing a test run is the sharpest
+# harm #3705 records, because it can block the verification of a fix while
+# saying nothing about why.
+#
+# RESIDUAL, stated rather than hidden: a reader NOT on this list is still
+# followed and can still over-refuse. The set of read-only tools is unbounded,
+# so this closes the measured population and not the class. Add names here as
+# they are measured; do not invert the default to close it by fiat, or the
+# executed-script reach that #3484 bought is lost.
+READ_ONLY_PROGRAMS = {
+    "awk", "bat", "cat", "cksum", "cmp", "column", "comm", "cut", "diff",
+    "du", "file", "fold", "git", "grep", "head", "hexdump", "jest", "jq",
+    "less", "ls", "md5", "md5sum", "more", "nl", "od", "pytest", "rg",
+    "sed", "sha1sum", "sha256sum", "shellcheck", "shfmt", "sort", "stat",
+    "strings", "tail", "tee", "uniq", "vitest", "wc", "xxd", "yamllint",
+}
+
+
+def executing_command(argv):
+    """The program this command runs, and the tokens after it.
+
+    Steps over leading variable assignments and over wrappers that do not
+    change what runs. Reading a wrapper as the command is how a payload hides
+    from a classifier that inspects only a segment's first word.
+
+    Args:
+        argv: One command's tokens.
+
+    Returns:
+        A triple (token, program, args); (None, None, []) when none is named.
+        The raw token is carried alongside the basename because a script run by
+        bare path — `./create.sh`, relying on its shebang — has no interpreter
+        to recognise, and the command word IS the thing being executed.
+    """
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if "=" in token and not token.startswith(("=", "-")):
+            index += 1
+            continue
+        program = basename(token)
+        if program not in EXEC_WRAPPERS:
+            return (token, program, argv[index + 1 :])
+        separate, positional = EXEC_WRAPPERS[program]
+        index += 1
+        while index < len(argv) and argv[index].startswith("-"):
+            option = argv[index]
+            if option == "--":
+                index += 1
+                break
+            index += 2 if option in separate else 1
+        index += positional
+    return (None, None, [])
+
+
+def executed_operand(argv):
+    """The path this command EXECUTES, or None.
+
+    THIS IS THE COMMAND-POSITION QUESTION, and declining to ask it is what
+    #3705 records: the guard opened any readable file any token named, then
+    justified a refusal from that FILE's contents rather than from the
+    COMMAND's behaviour. Measured refusals included `git diff`, `grep -n`,
+    `wc -l`, a `git grep` PATHSPEC and a test run — every one of them read-only,
+    and one of them blocked running the tests that would have proved a fix.
+
+    `parity-safety-net.sh` already states the rule this restores, and names the
+    opposite as the known-wrong fix (`origin/main`, lines 337-346 and 704-705):
+    "Only a COMMAND POSITION can execute something. A path anywhere else is an
+    argument, and an argument is data." `block-no-verify.sh:495-513`
+    (`strip_command_prefix`) implements the same split with a fail-closed third
+    state. Both live in this directory; this guard was the one that declined.
+
+    NOT narrowed to shells, and NOT narrowed to an enumerated interpreter list.
+    `file_creation` recognises a creation in any language, so `node wrapper.mjs`
+    must still be followed — a measured fail-open in #3484 — and this guard's
+    own suite drives it with a runner nobody enumerated, precisely so a fix
+    keyed on such a list fails. So the default for an unrecognised program is to
+    FOLLOW, and only a known reader is exempt. A script run by bare path with no
+    interpreter at all (`./create.sh`, via its shebang) is followed too: there
+    the command word is itself the thing being executed.
+
+    Reading a REQUEST PAYLOAD is a separate question with a separate answer:
+    `payload_text` resolves `--data-binary @file` and friends by flag name, so
+    narrowing this walk does not stop a creation whose body lives in a file
+    from being seen.
+
+    Args:
+        argv: One command's tokens.
+
+    Returns:
+        The operand token naming a program that will run, or None.
+    """
+    token, program, args = executing_command(argv)
+    if program is None:
+        return None
+    # A reader takes its operands as data. This is the #3705 population.
+    if program in READ_ONLY_PROGRAMS:
+        return None
+    if program in SOURCE_BUILTINS:
+        return args[0] if args else None
+    # A command word that is ITSELF a readable file is being executed by its
+    # shebang — `./create.sh` names no interpreter and runs all the same.
+    if program not in EXECUTING_INTERPRETERS and resolve_operand(token) is not None:
+        return token
+    # `bash < create.sh` runs that file as surely as `bash create.sh` does, and
+    # `<` is not a segment boundary, so the pair survives in one argv.
+    for index, argument in enumerate(args):
+        if argument == "<" and index + 1 < len(args):
+            return args[index + 1]
+    # Reached by a known interpreter AND by a program this parser cannot name.
+    # The unknown case is followed on purpose — see READ_ONLY_PROGRAMS.
+    for argument in args:
+        if argument == "--":
+            continue
+        if argument.startswith("-"):
+            # A command string or a module name; no script file follows.
+            head = argument.split("=", 1)[0]
+            if argument in NO_SCRIPT_OPTIONS or head in NO_SCRIPT_OPTIONS:
+                return None
+            continue
+        return argument
+    return None
+
+
 def file_operands(argv):
-    """Files this command names, in the order they appear.
+    """The file this command EXECUTES, if it executes one.
 
-    Every token is offered, and the ones that name a readable regular file are
-    kept. Deciding WHICH programs execute their operands is the unbounded
-    question this file already refuses to ask, so it is not asked here either.
+    Deciding WHICH programs execute their operands is the question this file
+    used to refuse to ask, and refusing it is what made the guard read a path
+    quoted as prose inside a `--body-file` markdown and attribute its contents
+    to the command. It is answered in `executed_operand` now.
 
     Args:
         argv: One command's tokens.
@@ -1413,7 +1591,8 @@ def file_operands(argv):
         Existing paths, deduplicated across the whole scan and capped.
     """
     paths = []
-    for token in argv:
+    operand = executed_operand(argv)
+    for token in [operand] if operand is not None else []:
         if len(paths) >= FILE_OPERANDS_PER_SEGMENT:
             break
         path = resolve_operand(token)

package/plugins/lisa-cursor/hooks/block-managed-file-edits.sh

@@ -415,11 +415,17 @@ EOF
     # what a tokenizer is for.
     #
     # The analyzer is read into a variable by `read -d ''` rather than run
-    # inside a `$(python3 - <<'PY' … PY)`. Bash has to find the closing paren of
-    # a command substitution by re-scanning its text, and a heredoc body nested
-    # there is scanned too: the lone backtick in `re.compile(r"[$`]")` below
-    # reads as an unterminated backtick substitution and the whole script fails
-    # to parse. Keeping the heredoc out of the substitution is the fix.
+    # inside a command substitution wrapping a here-document. Bash finds the
+    # closing paren of a command substitution by re-scanning its text, and a
+    # here-document body nested there is scanned too: the lone backtick in
+    # `re.compile(r"[$`]")` below then reads as an unterminated backtick
+    # substitution and the whole script fails to parse. Keeping the
+    # here-document out of the substitution is the fix. This is also the shape
+    # `block-direct-issue-create.sh` already uses for its own classifier.
+    #
+    # The delimiter is deliberately not spelled out in this comment: a tool that
+    # greps for here-document starts would otherwise match the prose and read
+    # the wrong span.
     analyzer=''
     IFS= read -r -d '' analyzer <<'PY' || true
 import os

package/plugins/lisa-cursor/rules/rejection-detection-reference.mdc

@@ -167,3 +167,72 @@ Naming the decline date, the recurrence date, and the recurrence reference in bo
 ### Concurrency honesty
 
 The search-then-write here is **not** an atomic claim: two truly concurrent runs can each miss the other's in-flight proposal and file a transient duplicate. It therefore guarantees **convergence, not mutual exclusion** — the duplicate is found and closed by the next run's marker search, and because the key is a stable content hash, a duplicate never multiplies. State this rather than implying a lock; a cross-run locking protocol would be disproportionate to the risk.
+
+## Automation-reversal memory (repair-side — a human undoing a transition this flow made)
+
+Both sections above remember something a **human or QA did to work**: claim-time memory reads an item bounced backward through the review lanes; proposal-time memory reads a proposal closed as *not planned*. This third section remembers something a human did **to the flow itself** — an automated repair moved an item's lifecycle role, and a human moved it straight back.
+
+Every loop that writes a lifecycle role as a **repair** rather than as a claim consults this section before re-making a transition. `lisa-repair-intake` is the first consumer and the skill this contract was written from.
+
+The failure it exists to stop is not forgetfulness, it is **inversion**. A loop with a state-only recurrence brake reads the human's revert as *changed state*, and changed state is normally a reason to look again — so the correction becomes the trigger. That inverts the assumption every operator brings to an unattended fleet: the more promptly a reviewer undoes a wrong transition, the sooner it comes back. A mechanism in which human correction is indistinguishable from new state converts your best reviewers into the loop's most reliable trigger.
+
+### Why this is a third classification, not a wider `rejection-reclaim`
+
+`rejection-reclaim` is anchored on the **ready** lane — an item that reached a `review`/`done`-ward lane and is now back in `$READY`. A reversed repair lands in the **blocked** lane instead: automation moved `$BLOCKED → $READY`, and a human moved it back to `$BLOCKED`. Widening `rejection-reclaim` to cover that would fire it on a lane it was never written for, and its response is wrong for this case anyway — reflecting on rejection evidence and handing it into a re-implementation is what you do when the work was rejected, not when a human said *stop doing that*. The two are **orthogonal** and are **never merged into `rejection-reclaim`**: one teaches a re-implementation, the other withdraws a decision.
+
+### Seam — before any lifecycle write, not at claim
+
+Detection runs at the **top of the repair walk for each candidate item, BEFORE the loop writes any lifecycle role**. The reasoning is the claim-time seam's: a write overwrites the current lane, and the signal depends on reading the current lane against history. Detection is a pure read — idempotent, headless-safe, no side effects.
+
+### Classification
+
+Detection is a pure read of the item's transition history **and its authorship** (via the vendor access layers). It returns exactly one:
+
+| Classification | Condition |
+|---|---|
+| `automation-reversal` | History shows a lifecycle role change **authored by** this flow, and a later **backward** move of that same role **authored by** a human, with no automation move after it. |
+| `no-reversal` | History shows no such pair — the flow made no prior transition, or its transition still stands, or the later move was itself automation. |
+| `unknown` | The vendor history query failed, was inconclusive, or **did not expose authorship**. |
+
+### Authorship is the whole signal — a backward move alone proves nothing
+
+The state-only reading is what fails today, so a backward move is **not** sufficient: an item can return to `$BLOCKED` because a genuine new blocker appeared, which is the world moving on and is a legitimate reason to look again. What distinguishes a correction is **who moved it, and against what**. Read authorship from the same history surfaces:
+
+- **GitHub** — timeline `LabeledEvent` / `UnlabeledEvent` nodes carry an `actor`; read them through `lisa-github-read-issue`'s Label-Event History surface.
+- **JIRA** — `lisa-atlassian-access operation: changelog key:<K>`; each changelog entry carries an `author` alongside its `from`/`to` status items.
+- **Linear** — `lisa-linear-access operation: history id:<ID>`; each history node carries an `actor` alongside `fromState` / `toState`.
+
+An actor is **this flow** when it is the configured automation identity, or when the flow's own marker note (`[lisa-repair-intake]`) sits at that transition's timestamp. Any other actor is a human. Where the surface does not expose an actor at all, the result is `unknown` — never an assumed human.
+
+**A marker and a transition on the same item say nothing until you know their order.** A hold label, a comment and a lane move routinely coexist on a reversed item, and co-occurrence reads equally well in both directions — a label applied *before* a transition guards it, the same label applied *after* records that the transition was undone. Sourcing the facts, attributing them correctly and reading the artifact all pass cleanly on an invented sequence; only ordering disconfirms it. Compare timestamps explicitly and treat an unorderable pair as `unknown`.
+
+### Lane names are configuration here too
+
+The lanes compared ALWAYS come from `.lisa.config.json` — `github.labels.build.blocked` and `github.labels.build.ready` on GitHub, the JIRA status and Linear state equivalents — resolved per `config-resolution` against the `src/sync/registry.ts` `BUILD_LABEL_DEFAULTS` (`blocked: status:blocked`) fallback. **Never hardcode** a lane string; a project that renames its blocked lane must still detect reversals.
+
+### Never block the sweep
+
+`unknown` is a first-class result here exactly as it is at claim time, but the safe direction is the opposite one and must be stated so it is not "simplified" later. At claim time an unreadable history degrades to *implement the item anyway*, because reflection is a bonus. Here an unreadable history degrades to **neither a reversal nor a clearance**: the item is evaluated by the loop's normal rules, unchanged, and the run **never blocks the sweep** on a failed detection. `unknown` must not be read as "no reversal, proceed to re-attempt" any more than as "reversal, suppress" — it removes the signal, it does not supply one.
+
+### Learning-loop exclusion
+
+The same learning-loop exclusion applies, for the same reason and by the same markers: an item carrying `[lisa-learning-drop]`, `[lisa-learning-pr]`, `[lisa-learning-upstream-handoff]` or the `learning:needs-triage` label is never classified `automation-reversal`, no matter how it moved. The flow must not remember being corrected about its own learning artifacts.
+
+### The rule — a reversal raises the bar, it never resets the clock
+
+On `automation-reversal`:
+
+1. **Do not re-apply the classification that was reversed.** The reversal is the strongest available evidence that the classification was wrong, and re-deriving it from the same facts reaches the same wrong answer.
+2. **Leave the item where the human put it** and ensure the `human_needed` marker is present. A decision that was overturned needs a person, not another cycle.
+3. **Name it in the run record** — the reversed transition, and the classification that produced it. A suppression nobody can see is indistinguishable from a loop that found nothing.
+4. **Re-attempt only on evidence that postdates the reversal** — a blocker state change, or a human comment supplying what was missing. This mirrors the re-proposal rule the proposal half already enforces: the memory is durable, not permanent, and new evidence reopens it. Cite that evidence in the run record.
+
+A changed lifecycle role is therefore **no longer sufficient on its own** to warrant a fresh attempt. The consuming loop's recurrence brake must be able to tell "the state changed because the world moved" from "the state changed because a human undid me", which means carrying **authorship and an overturn bit**, not state alone.
+
+### The fix is signed per path — do not apply one sign globally
+
+This is the trap in implementing this section, and it will not be caught in review because the wrong version reads as tightening.
+
+On a **repair-transition** path, human activity must **stop** being a warrant to re-attempt — that is this whole contract. On a **staleness** path, a human comment is counted as forward progress and *suppresses* action, which means an objecting comment already protects the item. That protection is correct and a global "human activity no longer counts" switches it off while everyone believes a hole was closed.
+
+So: apply the inversion **only** where the loop is deciding whether to re-make a transition. Leave every keep-alive and staleness reading exactly as it is. Any consumer of this section states which of its paths are signed which way.

package/plugins/lisa-cursor/rules/rejection-detection.mdc

@@ -53,4 +53,17 @@ A **loop-proposed** item that a human **closed as _not planned_** is a durable d
 - **Outcomes:** an all-suppressed cycle ends `nothing-needed` naming the **suppression count**; a memory check that cannot read the tracker ends `recovery-required`, never a silent `nothing-needed` (e.g. `Tracker unreachable during the decline check — restore credentials; nothing was filed this run.`).
 - **Concurrency:** search-then-write = convergence, not mutual exclusion — a transient duplicate is closed by the next run; no cross-run lock.
 
-Full contract (classification table, per-vendor bindings, reflection & evidence handoff, Proposal rejection memory): [reference/rejection-detection.md](rejection-detection-reference.mdc).
+## Automation-reversal memory (repair-side — orthogonal to both halves above)
+
+A human who **undoes a lifecycle transition this flow made** is correcting the flow, not supplying new state. Every loop that writes a lifecycle role as a **repair** (`lisa-repair-intake`) consults this before re-making a transition. It is a third classification, never merged into `rejection-reclaim`: that one is anchored on the ready lane and answers a rejection with re-implementation; this one lands in `$BLOCKED` and answers a correction by withdrawing a decision.
+
+- **Seam:** top of the repair walk for each item, **before any lifecycle write** — after the write the current-lane signal is gone.
+- **Classify:** `automation-reversal` — a role change **authored by** this flow, then a later **backward** move of that role **authored by** a human, with no automation move after it. Otherwise `no-reversal`. Authorship unavailable or history unreadable → `unknown`.
+- **Authorship is the signal, not the backward move.** An item can return to `$BLOCKED` because a real new blocker appeared — that is the world moving on. Read the `actor` (GitHub timeline, Linear history) or `author` (JIRA changelog) through the access layers; an unexposed actor is `unknown`, never an assumed human. **A marker and a transition on the same item say nothing until you know their order** — compare timestamps, and treat an unorderable pair as `unknown`.
+- **Lanes from config** (`github.labels.build.blocked` + the JIRA/Linear equivalents, `config-resolution`) — never hardcode.
+- **Degrade:** `unknown` is **neither a reversal nor a clearance** — the item is judged by the loop's normal rules and detection **never blocks the sweep**. The learning-loop exclusion above applies unchanged.
+- **Rule:** on `automation-reversal`, do not re-apply the reversed classification; leave the item where the human put it, ensure `human_needed`, and **name the reversed transition in the run record**. Re-attempt **only** on evidence that **postdates the reversal**, cited in the run record — mirroring the re-proposal rule the proposal half enforces.
+- **A changed lifecycle role is no longer a sufficient warrant on its own.** A consuming loop's recurrence brake must carry **authorship and an overturn bit**, not state alone.
+- **Signed per path.** Apply the inversion only where the loop decides whether to re-make a transition. A staleness/keep-alive path where a human comment already *suppresses* action is protective — leave it. One global sign reads as tightening and removes that protection.
+
+Full contract (classification table, per-vendor bindings, reflection & evidence handoff, Proposal rejection memory, Automation-reversal memory): [reference/rejection-detection.md](rejection-detection-reference.mdc).

package/plugins/lisa-cursor/rules/settled-decisions-reference.mdc

@@ -32,3 +32,13 @@ Asking after the research answered the question is also a violation. When gather
 ## Reporting
 
 Record settled decisions in a short clause, such as "auto-merge on, per standing preference" or "scoped app-wide, because the Android finding decides it." This gives the operator a chance to correct the decision without requiring an avoidable question first.
+
+## Re-read the instruction file from disk before escalating
+
+This rule is delivered at session start; the re-read it requires happens at the escalation boundary. Re-reading at session start would re-read the same moment the context was built from.
+
+Before forming an escalation, handing a decision back, or re-opening a question that may already be settled, open `AGENTS.md` (or `CLAUDE.md`) from disk and read its `## Standing rulings` section. If the file has no such heading, re-read the file.
+
+The instruction is to open the file rather than to assess the context, because context completeness is not observable from inside. An instruction file is injected at session start and can arrive shortened, and a cut landing on a section boundary is indistinguishable from a document that never carried that section. Rulings are also written after sessions begin, so an injected copy is a snapshot of the moment the session started.
+
+This is a pointer, not a copy. It stays correct as rulings accumulate and survives a shortened copy of the file it points at, because it does not travel inside that file.

package/plugins/lisa-cursor/rules/settled-decisions.mdc

@@ -58,3 +58,23 @@ honored.
 When you take a settled decision, make it auditable in one clause — "auto-merge on, per your standing
 preference", "scoped app-wide, because the Android finding decides it". That gives the operator the
 chance to correct it without requiring them to answer first.
+
+## Before you escalate, re-read the instruction file from disk
+
+**This rule is delivered at session start; the re-read it demands happens at the escalation
+boundary.** Re-reading at session start would re-read the same moment your context was built from
+and buys nothing.
+
+So before you form an escalation, hand a decision back, or re-open a question that may already be
+settled: **open `AGENTS.md` (or `CLAUDE.md`) from disk and read its `## Standing rulings` section.**
+If the file has no such heading, re-read the file.
+
+The instruction is to open the file — not to "check whether your context looks complete", because
+**context completeness is not observable from inside.** An instruction file is injected at session
+start and can arrive shortened, and the cut can land on a clean section boundary, where a truncated
+document is indistinguishable from one that never had that section: your copy ends tidily, so you
+conclude you read all of it. Rulings are also written *after* sessions begin — your copy is a
+snapshot of the moment you started, and nothing tells you when it stops being current.
+
+This is a **pointer, not a copy**. It stays correct as rulings accumulate, and it survives a
+shortened copy of the file it points at precisely because it does not travel inside that file.

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

@@ -41,6 +41,11 @@ merges" loop. Other skills delegate here instead of re-implementing it. Runs
   green, open, un-merged PR is the *success* outcome of this mode, not a hang.
   Used by learning-persistence flows whose low-confidence PRs must wait for a
   human (`lisa-persist-learning`).
+
+  **`auto_merge` is caller-time and nothing re-reads it.** That is what the hold
+  label (section 0) exists for: the same behaviour, raisable by anyone at any
+  point while the loop runs. Both routes land in `awaiting-human`; they differ
+  only in who can take them and when.
 - `on_blocker=<fix|report>` — what to do when a blocker needs code or review work.
   Default `fix`.
   - **`fix`** (the full loop): resolve conflicts, fix failing checks, address +
@@ -97,9 +102,115 @@ gh pr edit <pr> --add-label "lisa:babysitter-on-duty"
 closed, or a hard block handed to a human. A crashed session that never
 releases is why the TTL exists; do not rely on it as the normal release path.
 
+### The hold gate — a stop anyone can raise
+
+Section 0 owns this skill's two PR labels: the lease it **writes** to declare
+ownership, and the hold it **reads** to be told to stop. Same mechanism, pointed
+at different things — a lease is a claim, a hold is a decision.
+
+**The label** is `lisa:hold` by default, overridable per project at
+`github.labels.merge.hold`, resolved local-over-global like every other
+configured name. Resolve it ONCE at startup and reuse the resolved string; a
+name re-resolved each iteration can change identity mid-loop for no reason a
+reader could reconstruct afterwards.
+
+```bash
+HOLD_LABEL=$(
+  jq -r 'first(.github.labels.merge.hold | strings)' \
+    .lisa.config.local.json .lisa.config.json 2>/dev/null | head -n1
+)
+HOLD_LABEL="${HOLD_LABEL:-lisa:hold}"
+```
+
+**What it means:** exactly `auto_merge=false`, for as long as it is present. Not
+a new concept and not a new terminal state — the same disarm, the same
+fail-closed re-read, the same `awaiting-human` landing. The only new surface is
+one label read.
+
+**Why it exists.** `auto_merge` is decided by the caller at invocation, and
+nothing re-reads it, so the only person who can stop the merge is the person who
+started it. Anyone else — a reviewer who opens the PR while the loop is driving
+it, someone holding a PR another session armed — has no lever and loses the
+race. Measured (#3558): four explicit `gh pr merge --disable-auto` calls were
+each followed by a re-arm 7–25 seconds later, and the PR merged two seconds
+after its final check went green. **The hold did not fail; it lost a race.** A
+signal the loop itself reads cannot be raced, because the loop is what reads it.
+
+#### Evaluate it in two places, and re-read it every iteration
+
+- **Before arming** (section 1) — a PR already carrying the label is never armed.
+- **On every watch-loop iteration** (section 2), before acting on any blocker.
+
+Re-reading is the entire point. A check that runs once at startup is a
+caller-time signal wearing a loop's clothing and fixes nothing, because the case
+that matters is a label applied **after** the loop is already running. If you
+are changing this and it is convenient to read the label once, you have
+reintroduced the defect.
+
+```bash
+gh pr view <pr> --json labels --jq "[.labels[].name] | index(\"$HOLD_LABEL\") != null"
+```
+
+**Match the resolved name exactly — never a prefix.** `lisa:babysitter-on-duty`
+is a label this skill applies to itself and shares the `lisa:` prefix; a
+prefix match would make the loop stop on its own lease, which is a deadlock
+that looks like a human decision.
+
+#### When held
+
+1. Run the existing `auto_merge=false` disarm (section 1) — disable the latch
+   once and prove with the fail-closed re-read that it took.
+2. Return `awaiting-human:held` (section 4).
+3. **Do not remove the label.** Removing a human's signal is unrecoverable from
+   inside the loop; leaving a stale one costs a cycle and is visible. Only
+   whoever applied it takes it off, and a later invocation then resumes normally.
+
+Do not keep polling while held. Held is terminal for this run, not a pause to
+wait out — the loop has been told a human is looking, and continuing to drive is
+the behaviour the label exists to stop.
+
+**The disarm is once and terminal: never re-arm the latch afterwards, and never
+resume driving in the same run.** This is what keeps a hold compatible with the
+armed-across-fix-pushes rule in section 1, which otherwise forbids disarming on
+the `auto_merge=true` path. That rule exists to prevent a *race* — disarm, then
+re-arm, repeatedly, while still driving — and a hold does neither half of it: it
+turns the latch off exactly once and then stops. A hold that re-armed, or that
+kept driving afterwards, would be the race that rule names, wearing a label.
+
+#### When the read fails
+
+**Fail toward hold.** The asymmetry decides it: a false hold costs one cycle and
+is visible in a terminal report someone can act on, while a false no-hold merges
+past a human's objection and cannot be undone. Where the two errors are
+unequal, take the recoverable one.
+
+But a read that keeps failing must not become a silent deadlock, so the failure
+is **reported as its own outcome** rather than dressed up as a decision:
+
+- retry the read once;
+- if it still fails, disarm as above and return **`awaiting-human:hold-unknown`**,
+  naming the error.
+
+`awaiting-human:held` and `awaiting-human:hold-unknown` are different facts and
+an operator needs to know which: the first says *a human stopped this*, the
+second says *I could not tell whether a human stopped this.* Collapsing them
+would hide a broken permission behind a human decision, and nobody would ever
+look.
+
+**A PR with no hold label is driven exactly as it is today.** This gate adds a
+stop; it does not add a block. If the label is absent and the read succeeded,
+nothing about the run changes.
+
 ## 1. Enable auto-merge
 
-**Gate: only when `auto_merge=true` (the default).** When `auto_merge=false`,
+**Gate: the hold label is absent (section 0's hold gate), and `auto_merge=true`
+(the default).** Evaluate the hold gate BEFORE anything in this section,
+including the arm gate below and the direct-merge capability fallback: a held PR
+is not armed, not merged directly, and not driven — it disarms once and returns
+`awaiting-human:held`. Checking after arming would authorise the merge the label
+exists to prevent, which is the same ordering error the arm gate itself fixes.
+
+When `auto_merge=false`,
 skip the enable step and its capability fallback — do not enable auto-merge,
 and do **not** use the capability fallback below: on a repo that disallows
 auto-merge, an `auto_merge=false` PR must stay OPEN for human triage, never be
@@ -357,6 +468,12 @@ Poll the live state each iteration:
 gh pr view <pr> --json state,mergeStateStatus,mergeable,reviewDecision,statusCheckRollup,headRefName,baseRefName
 ```
 
+**Re-read the hold label on every iteration, before handling any blocker**
+(section 0's hold gate). It is polled separately from the line above rather than
+folded into it, because `labels` is not part of the blocker state: the hold is a
+question about whether to keep going at all, asked before the blocker questions,
+and a run that answers it once at startup has not implemented it.
+
 Handle every blocker class; after any fix, re-poll and continue. Do not stop while
 the PR is still open and progress is possible. On each iteration, refresh the
 babysitter lease if its last stamp is older than ~30 minutes (section 0).
@@ -393,6 +510,13 @@ and return per the input contract above. That includes (f): adjudicating a pendi
 auto-fix PR (merging, closing, or deleting its branch) is destructive work, not
 diagnosis — return its classification (`blocked:pending-auto-fix`) instead.
 
+**The hold gate binds in report mode too**, and it binds first: a held PR
+returns `awaiting-human:held` without arming, without the mechanical step (a)
+nudge, and without an `update-branch`. Hold is not a blocker classification and
+never returns as one — `blocked:*` says *this PR cannot proceed yet*, while a
+hold says *someone asked me not to proceed*, and reporting the second as the
+first would file a human's decision as a defect for something else to clear.
+
 The arm gate binds in report mode too, and this is the mode where forgetting it
 does the most damage: a diagnose-only run that arms the latch has not diagnosed
 anything, it has authorised a merge. Under a vacuous review context, report mode
@@ -938,6 +1062,22 @@ Loop until one of:
   merge but nobody reviewed it: the review tool says it skips public
   repositories, and that will not change on its own. Merge it yourself or ask
   for a human review."*
+- **`awaiting-human:held`** → success, and the only terminal state a person can
+  cause on purpose from outside the run. The hold label (section 0) was present,
+  the latch was disarmed once and the re-read proved it, and the label was left
+  in place. Report the PR URL, the resolved label name, and that removing the
+  label lets a later invocation resume — for example: *"PR #123 is on hold:
+  someone added the `lisa:hold` label, so I stopped instead of merging it.
+  Remove that label when you want it to continue."* Not a stall and not a
+  failure: a human asked for the PR to stop, and it stopped.
+- **`awaiting-human:hold-unknown`** → the hold label could not be read (twice),
+  so whether a human asked for a stop is **unknown**. The latch is disarmed and
+  the PR sits OPEN, on the fail-toward-hold rule in section 0. Report the read
+  error verbatim. This is deliberately NOT reported as `awaiting-human:held`:
+  that would file a broken permission or a rate limit as a human decision, and
+  the one thing nobody would then do is investigate it. Usually a missing
+  `issues: read` / label-read permission, which is fixable and invisible from
+  the merge outcome alone.
 - **`CLOSED`** → report (PR was closed without merge).
 - **Hard block needing a human**: an unresolvable conflict, a failing check that
   needs design input, or genuine unresolved human objection (not a bot gate). Stop

package/plugins/lisa-cursor/skills/lisa-git-submit-pr/SKILL.md

@@ -48,6 +48,8 @@ Recognized optional hints:
 
    This delegation is now load-bearing rather than a convenience: it is the only path that arms auto-merge, so skipping it leaves the PR open rather than quietly merging it. Reporting submission as complete without invoking it is a failed submit, not a partial one — say so instead of implying the PR is on its way to merged.
 
+   **The hold label needs no check here, and adding one would be dead code.** `drive-pr-to-merge` evaluates its hold gate before it arms anything, so a PR created with the label already on it is never armed — by the delegation, not by a second check in this skill. That guarantee used to require one: while step 5 armed the latch at creation, a hold that covered only the loop left the creation-time arm wide open, which is why CodySwannGT/lisa#3558 asked for a check in both places. Step 5 no longer arms, so there is nothing here for a label to gate. If you are adding one because the ticket says to, re-read step 5 first.
+
 ### Native Development Linkage
 
 Add provider-appropriate linkage to the PR title and/or body without changing the status lifecycle: