@codyswann/lisa 4.24.2 → 4.25.1

package/all/copy-overwrite/scripts/lisa-hooks/block-no-verify.sh

@@ -15,7 +15,13 @@
 #   5. GIT_CONFIG_KEY_<n>=core.hooksPath env-var-style command-scope config;
 #   6. GIT_CONFIG_PARAMETERS carrying core.hooksPath command-scope config;
 #   7. the short `-n`, as a real argv token of a `git commit` — bare, or bundled
-#      into a short-option cluster such as `-nm "msg"`.
+#      into a short-option cluster such as `-nm "msg"`;
+#   8. a nested shell carrying any of the above as its `-c` command string,
+#      including behind long shell options such as `bash --norc -c`;
+#   9. `env --split-string` in EVERY abbreviation GNU accepts (`--s` upward,
+#      with or without an attached `=value`);
+#  10. those forms behind a wrapper that does not change what runs —
+#      `command`, `exec`, `builtin`, `nohup`, `setsid`, and nested `env`.
 #
 # The line below is what lets `lisa apply` tell a downstream copy of this guard
 # that is BEHIND from one that is AHEAD. Byte comparison cannot: both look like
@@ -26,7 +32,7 @@
 # Add a name here in the same commit that closes a vector. A hardening that
 # forgets to is invisible to refresh, and shows up as an unexplained diff at
 # review time instead of a named capability.
-# lisa-guard-capabilities: no-verify-abbrev, husky-env, hookspath-allowlist, config-env, env-split-string, git-config-key, git-config-parameters, git-config-parameters-append, git-config-parameters-expansion, heredoc-shell-word, herestring-aware, no-verify-short, nested-shell-no-verify
+# lisa-guard-capabilities: no-verify-abbrev, husky-env, hookspath-allowlist, config-env, env-split-string, git-config-key, git-config-parameters, git-config-parameters-append, git-config-parameters-expansion, heredoc-shell-word, herestring-aware, no-verify-short, nested-shell-no-verify, nested-shell-long-options, env-split-string-abbrev, command-wrapper-normalization
 #
 # Shell-token matching avoids false positives from issue bodies, heredocs, and
 # commit-message prose while still catching quoted real argv values such as
@@ -222,26 +228,61 @@ COMMAND_SEPARATORS = {
 SHELL_PROGRAMS = {"bash", "dash", "ksh", "sh", "zsh"}
 MAX_SHELL_NESTING = 8
 
-# Prefix options accepted by `env` before the command name. Value-taking
-# options are separate because their operand must never be mistaken for the
-# command (`env -u bash -c ...` consumes `bash` as the variable name).
-ENV_OPTIONS_NO_VALUE = {
-    "-i", "--ignore-environment", "-0", "--null", "-v", "--debug",
+# GNU env's long options, listed in FULL so an abbreviation can be resolved
+# against them. getopt_long accepts any prefix that names exactly one option,
+# and no other env option begins with `s` — so `env --s`, `env --sp`, and
+# `env --split` are `env --split-string` just as completely as the full
+# spelling is. Matching only the full spelling is bypassed by deleting
+# characters, which is why the set below exists instead of a literal list of
+# the two spellings the guard used to know.
+ENV_LONG_OPTIONS = {
+    "--argv0", "--block-signals", "--chdir", "--debug", "--default-signal",
+    "--help", "--ignore-environment", "--ignore-signal",
+    "--list-signal-handling", "--null", "--split-string", "--unset",
+    "--version",
 }
-ENV_OPTIONS_SEPARATE_VALUE = {
-    "-u", "--unset", "-C", "--chdir", "-S", "--split-string",
-    "-a", "--argv0",
-}
-ENV_OPTIONS_INLINE_VALUE = (
-    "--unset=", "--chdir=", "--split-string=", "--argv0=",
-)
+# Of those, the ones whose value is a SEPARATE token, so the operand is never
+# mistaken for the command (`env -u bash -c ...` consumes `bash` as the
+# variable name). The signal options take an OPTIONAL value, which GNU reads
+# only when it is attached with `=`, so they never consume a following token.
+ENV_LONG_SEPARATE_VALUE = {"--argv0", "--chdir", "--split-string", "--unset"}
+
+# env's single-letter options, by whether the rest of a cluster is more
+# options or the option's value.
+ENV_SHORT_NO_VALUE = frozenset("i0v")
+ENV_SHORT_TAKES_VALUE = frozenset("uCaS")
+
+# Builtins and wrappers that run whatever FOLLOWS them without changing what
+# it is: `command env -S ...` runs exactly the `env` that `env -S ...` runs,
+# and `env -- env -S ...` runs exactly the inner `env`. Reading the wrapper as
+# the command is how a payload hides from a guard that inspects only the first
+# word of an invocation.
+COMMAND_PREFIX_WRAPPERS = {"command", "exec", "builtin", "nohup", "setsid"}
+# The only option of those that consumes a separate following token
+# (`exec -a NAME env -S ...`).
+COMMAND_PREFIX_SEPARATE_VALUE = {"-a"}
 
 # Shell options whose following token is an operand, not another option. The
 # generic recursive scanner must step over these before looking for `-c`.
 SHELL_OPTIONS_SEPARATE_VALUE = {
-    "-o", "+o", "-O", "+O", "--rcfile", "--init-file",
+    "-o", "+o", "-O", "+O", "--rcfile", "--init-file", "--emulate",
+}
+SHELL_OPTIONS_INLINE_VALUE = ("--rcfile=", "--init-file=", "--emulate=")
+
+# Boolean long options of the recognized shells. Listed only for PRECISION:
+# a long option is never the command-string flag either way, but naming the
+# ordinary ones keeps `bash --norc script.sh` from being treated as a possible
+# value-taking option whose operand must be scanned past. zsh and ksh accept a
+# long option per shell setting, so this set is deliberately not exhaustive —
+# the scanner stays correct on the ones it does not name.
+SHELL_LONG_OPTIONS_NO_VALUE = {
+    "--debugger", "--dump-po-strings", "--dump-strings", "--emacs",
+    "--globalrcs", "--help", "--interactive", "--login", "--monitor",
+    "--no-globalrcs", "--no-rcs", "--noediting", "--noprofile", "--norc",
+    "--norcs", "--posix", "--pretty-print", "--privileged", "--protected",
+    "--rcs", "--restricted", "--verbose", "--version", "--vi", "--wordexp",
+    "--xtrace",
 }
-SHELL_OPTIONS_INLINE_VALUE = ("--rcfile=", "--init-file=")
 
 # git's own options that take a SEPARATE value token, which therefore must be
 # skipped when looking for the subcommand: `git -c core.hooksPath=x commit` and
@@ -395,56 +436,143 @@ def subcommand_after_git(tokens, start):
     return None
 
 
-def shell_starts_command(tokens, index):
-    """Whether a recognized shell token occupies command position."""
-    start = index - 1
-    while start >= 0 and tokens[start] not in COMMAND_SEPARATORS:
-        start -= 1
-    prefix = tokens[start + 1:index]
-    if not prefix:
-        return True
-    if prefix[0].rsplit("/", 1)[-1] != "env":
-        return all("=" in token and not token.startswith("=") for token in prefix)
+def resolve_env_long_option(name):
+    """Resolve one GNU env long option, abbreviations included.
 
-    cursor = 1
+    Args:
+        name: A token beginning with `--`, with any `=value` already removed.
+
+    Returns:
+        The full option spelling; "" when the abbreviation names more than one
+        option, which real env refuses; None when nothing matches at all.
+    """
+    if not name.startswith("--") or name == "--":
+        return None
+    if name in ENV_LONG_OPTIONS:
+        return name
+    matches = [option for option in ENV_LONG_OPTIONS if option.startswith(name)]
+    if len(matches) == 1:
+        return matches[0]
+    return "" if matches else None
+
+
+def env_option_kind(token):
+    """Classify one token sitting in an `env` option position.
+
+    Returns:
+        "split-string" when env will reparse an argv value as shell words,
+        "separate-value" when the NEXT token is this option's operand,
+        "no-value" when the token stands alone, "ambiguous" when env accepts
+        the token but this parser cannot say which option it is, or None when
+        the token is not an option.
+    """
+    if not token.startswith("-") or token in {"-", "--"}:
+        return None
+    if token.startswith("--"):
+        name = token.split("=", 1)[0]
+        resolved = resolve_env_long_option(name)
+        if not resolved:
+            # Either unknown to this parser or an abbreviation naming several
+            # options. Neither can be reasoned about, so say so and let the
+            # caller fail closed rather than read past it.
+            return "ambiguous"
+        if resolved == "--split-string":
+            return "split-string"
+        if "=" in token:
+            return "no-value"
+        return (
+            "separate-value" if resolved in ENV_LONG_SEPARATE_VALUE else "no-value"
+        )
+    for position, letter in enumerate(token[1:], start=2):
+        if letter == "S":
+            return "split-string"
+        if letter in ENV_SHORT_TAKES_VALUE:
+            # The rest of this cluster is the option's value when there is
+            # one; otherwise the value is the following token.
+            return "no-value" if position <= len(token) - 1 else "separate-value"
+        if letter not in ENV_SHORT_NO_VALUE:
+            return "ambiguous"
+    return "no-value"
+
+
+def strip_command_prefix(prefix):
+    """Drop the tokens that precede a command without changing what it is.
+
+    Variable assignments, the `command`/`exec`/`builtin` builtins, and nested
+    `env` wrappers all leave the following word in command position. Reading
+    any of them as the command itself is what let `command env -S ...` and
+    `env -- env -S ...` slip past the split-string check: the prefix failed
+    the "assignments only" test, so the wrapped `env` was never classified.
+
+    Args:
+        prefix: The tokens between the last command separator and the
+            candidate program.
+
+    Returns:
+        A pair (status, remainder). "ok" carries the tokens still standing
+        between the separator and the candidate — empty means the candidate is
+        in command position. "operand" means the candidate is a wrapper
+        option's value rather than a command. "ambiguous" means a wrapper
+        option could not be classified and the caller must fail closed.
+    """
+    cursor = 0
     while cursor < len(prefix):
         token = prefix[cursor]
-        if token == "--":
-            return cursor == len(prefix) - 1
-        if "=" in token and not token.startswith("=") and not token.startswith("-"):
+        if "=" in token and not token.startswith(("=", "-")):
             cursor += 1
             continue
-        if token in ENV_OPTIONS_NO_VALUE or token.startswith(ENV_OPTIONS_INLINE_VALUE):
+        program = token.rsplit("/", 1)[-1]
+        if program in COMMAND_PREFIX_WRAPPERS:
             cursor += 1
+            while cursor < len(prefix) and prefix[cursor].startswith("-"):
+                if prefix[cursor] == "--":
+                    cursor += 1
+                    break
+                if prefix[cursor] in COMMAND_PREFIX_SEPARATE_VALUE:
+                    if cursor + 1 >= len(prefix):
+                        return ("operand", [])
+                    cursor += 2
+                    continue
+                cursor += 1
             continue
-        if token in ENV_OPTIONS_SEPARATE_VALUE:
-            # If the option has no operand inside the prefix, the shell token
-            # itself is that operand and therefore is not command position.
-            if cursor + 1 >= len(prefix):
-                return False
-            cursor += 2
+        if program == "env":
+            cursor += 1
+            while cursor < len(prefix):
+                option = prefix[cursor]
+                if option == "--":
+                    cursor += 1
+                    break
+                kind = env_option_kind(option)
+                if kind is None:
+                    break
+                if kind == "ambiguous":
+                    return ("ambiguous", [])
+                if kind == "split-string":
+                    # Everything after `-S` is env's own opaque payload, so the
+                    # candidate is not a command at all.
+                    return ("operand", [])
+                if kind == "separate-value":
+                    if cursor + 1 >= len(prefix):
+                        return ("operand", [])
+                    cursor += 2
+                    continue
+                cursor += 1
             continue
-        if token.startswith("-"):
-            # An unknown env option makes command-position parsing ambiguous.
-            # Fail closed for a recognized shell rather than trusting it.
-            return True
-        return False
-    return True
+        break
+    return ("ok", prefix[cursor:])
 
 
-def env_short_option_uses_split_string(token):
-    """Whether one GNU env short-option cluster enables split-string."""
-    if not token.startswith("-") or token.startswith("--") or token == "-":
-        return False
-    for letter in token[1:]:
-        if letter == "S":
-            return True
-        if letter in {"u", "C", "a"}:
-            # The rest of this token is the option's value, not more options.
-            return False
-        if letter not in {"i", "0", "v"}:
-            return False
-    return False
+def shell_starts_command(tokens, index):
+    """Whether a recognized shell token occupies command position."""
+    start = index - 1
+    while start >= 0 and tokens[start] not in COMMAND_SEPARATORS:
+        start -= 1
+    status, remainder = strip_command_prefix(tokens[start + 1:index])
+    if status == "ambiguous":
+        # A prefix option this parser cannot classify may still be launching
+        # the shell. Fail closed rather than trusting the wrapper.
+        return True
+    return status == "ok" and not remainder
 
 
 def env_uses_split_string(tokens, index):
@@ -464,8 +592,8 @@ def env_uses_split_string(tokens, index):
     start = index - 1
     while start >= 0 and tokens[start] not in COMMAND_SEPARATORS:
         start -= 1
-    prefix = tokens[start + 1:index]
-    if not all("=" in token and not token.startswith("=") for token in prefix):
+    status, remainder = strip_command_prefix(tokens[start + 1:index])
+    if status != "ok" or remainder:
         return False
 
     cursor = index + 1
@@ -473,40 +601,39 @@ def env_uses_split_string(tokens, index):
         token = tokens[cursor]
         if token in COMMAND_SEPARATORS or token == "--":
             return False
-        if (
-            token in {"-S", "--split-string"}
-            or token.startswith("--split-string=")
-            or env_short_option_uses_split_string(token)
-        ):
+        kind = env_option_kind(token)
+        if kind == "split-string":
             return True
-        if "=" in token and not token.startswith(("=", "-")):
-            cursor += 1
-            continue
-        if token in ENV_OPTIONS_NO_VALUE or token.startswith(
-            tuple(
-                option
-                for option in ENV_OPTIONS_INLINE_VALUE
-                if option != "--split-string="
-            )
-        ):
-            cursor += 1
-            continue
-        if token in ENV_OPTIONS_SEPARATE_VALUE:
-            cursor += 2
-            continue
-        return False
+        if kind == "ambiguous":
+            # An option env accepts but this parser cannot name makes the rest
+            # of the invocation unreadable; refuse instead of reading past it.
+            return True
+        if kind is None:
+            if "=" in token and not token.startswith(("=", "-")):
+                cursor += 1
+                continue
+            return False
+        cursor += 2 if kind == "separate-value" else 1
     return False
 
 
 def nested_shell_payload(tokens, index):
     """Return a shell `-c` payload, or True when option parsing is ambiguous."""
     cursor = index + 1
+    opaque_option_seen = False
     while cursor < len(tokens):
         option = tokens[cursor]
         if option in COMMAND_SEPARATORS or option == "--":
             return None
         if not option.startswith(("-", "+")):
-            return None
+            # Ordinarily the script operand, which ends option parsing. After
+            # a long option this parser cannot name it may instead be that
+            # option's value (`zsh --emulate ksh -c ...`), so keep scanning
+            # rather than concluding there is no command string.
+            if not opaque_option_seen:
+                return None
+            cursor += 1
+            continue
         if option in SHELL_OPTIONS_SEPARATE_VALUE:
             if cursor + 1 >= len(tokens) or tokens[cursor + 1] in COMMAND_SEPARATORS:
                 return True
@@ -515,8 +642,17 @@ def nested_shell_payload(tokens, index):
         if option.startswith(SHELL_OPTIONS_INLINE_VALUE):
             cursor += 1
             continue
-        body = option[1:]
-        if "c" in body:
+        # A LONG option is never the command-string flag, and testing it for a
+        # bare `c` was the bug: `--norc` and `--restricted` merely CONTAIN one,
+        # so the real `-c` that followed was consumed as their payload and the
+        # nested `git commit --no-verify` was never classified at all. The
+        # command string lives only in a single-dash cluster (`-c`, `-lc`).
+        if option.startswith("--"):
+            if option not in SHELL_LONG_OPTIONS_NO_VALUE:
+                opaque_option_seen = True
+            cursor += 1
+            continue
+        if "c" in option[1:]:
             if cursor + 1 >= len(tokens) or tokens[cursor + 1] in COMMAND_SEPARATORS:
                 return True
             return tokens[cursor + 1]

package/all/copy-overwrite/scripts/lisa-reconcile-policy.mjs

@@ -673,8 +673,10 @@ export function readLivePolicy({ repo, gh }) {
  *   One record per declared (ruleset, context) pair, from `declaredChecks`.
  *   Supplied, it is what the comparison is made of; absent, the name-keyed
  *   `homes`/`pins` projection is reconstituted into equivalent records.
- * @param {Array<{context:string, ruleset?:string}>} [options.awaited]
- *   Awaited declarations, preserving their ruleset identity.
+ * @param {Array<{context:string, ruleset?:string, integration_id?:number}>} [options.awaited]
+ *   Awaited declarations, preserving their ruleset identity and declared pin.
+ *   A declaration carrying a ruleset becomes a comparison record of its own,
+ *   unless `records` already declares that same (ruleset, context) pair.
  * @returns {ContextDrift} Three sets, plus the unsatisfied records.
  */
 export function reconcileContexts({
@@ -711,6 +713,37 @@ export function reconcileContexts({
     if (!byContext.has(record.context)) byContext.set(record.context, []);
     byContext.get(record.context).push(record);
   }
+  // An awaited declaration names a ruleset too — the home `awaitedHome`
+  // resolved, which is where its repair will be written. It has to reach the
+  // records the comparison is made of for exactly the reason a configured
+  // record does: without it, an awaited context required in `release` answered
+  // for the requirement `base` was missing, the pair read as matched, and the
+  // repair that would have added it was never planned.
+  for (const record of awaitedDeclarations) {
+    if (!declaredNames.has(record?.context)) continue;
+    // No home could be resolved — an ambiguous repository, or an explicit
+    // `--ruleset` naming one that is not here. Name-only matching is retained
+    // there on purpose: tightening would report drift against a ruleset nobody
+    // chose, and the repair has no place to write it either.
+    if (record.ruleset === undefined || record.ruleset === null) continue;
+    if (!byContext.has(record.context)) byContext.set(record.context, []);
+    const declarationsFor = byContext.get(record.context);
+    // An explicit `requiredChecks` declaration for the same pair is the one the
+    // project wrote down, and it stays in charge — including of its pin. Adding
+    // the awaited record beside it would state two expectations for one
+    // (ruleset, context) pair, and a pinned declaration and an unpinned one can
+    // never both be satisfied: the pair would be permanently missing.
+    if (declarationsFor.some(entry => entry.ruleset === record.ruleset)) {
+      continue;
+    }
+    declarationsFor.push({
+      context: record.context,
+      ruleset: record.ruleset,
+      ...(Number.isInteger(record.integration_id)
+        ? { integration_id: record.integration_id }
+        : {}),
+    });
+  }
   // A gate-derived context names no ruleset and no app, so it keeps matching on
   // name against any active ruleset; nothing is tightened that was never stated.
   const declarations = [...declaredNames]
@@ -1243,7 +1276,7 @@ function planContextRepairs({
   pins,
   homes,
 }) {
-  /** @type {Map<string, {add: string[], remove: string[], pins: Record<string, number>, unpinned: Set<string>}>} */
+  /** @type {Map<string, {add: string[], remove: string[], pins: Record<string, number>, unpinned: Set<string>, awaited: Set<string>}>} */
   const groups = new Map();
   const group = name => {
     if (!groups.has(name)) {
@@ -1252,11 +1285,26 @@ function planContextRepairs({
         remove: [],
         pins: {},
         unpinned: new Set(),
+        // Which of THIS ruleset's additions are awaited. A declaration that
+        // resolved a home of its own is matched by name below; this set is for
+        // the ones that did not, whose home only becomes knowable here.
+        awaited: new Set(),
       });
     }
     return groups.get(name);
   };
   const problems = [];
+  // An awaited declaration with no ruleset resolved no home of its own, yet it
+  // is still routed somewhere — through `homes`, or through the fallback. The
+  // payload matched awaited records against the target by their OWN ruleset,
+  // so these were dropped from the awaited list and written with the Actions
+  // pin: the one writer that can never post an external check, which leaves the
+  // repaired rule permanently unsatisfiable. Record where each one lands.
+  const unscopedAwaited = new Set(
+    awaited
+      .filter(record => record.ruleset === undefined || record.ruleset === null)
+      .map(record => record.context)
+  );
 
   // A removal goes to the ruleset that actually requires it. That ruleset is
   // reported alongside every EXTRA context precisely so this is knowable.
@@ -1281,6 +1329,7 @@ function planContextRepairs({
     const target = home ? group(home) : null;
     if (target) {
       target.add.push(context);
+      if (unscopedAwaited.has(context)) target.awaited.add(context);
       // A declared record is authoritative about its own pin — INCLUDING the
       // absence of one. `pins` is name-keyed and last-write-wins, so if `base`
       // declares a context unpinned and `release` pins it to app 99, the
@@ -1303,11 +1352,16 @@ function planContextRepairs({
       problems.push(fallback.problem);
       continue;
     }
-    group(fallback.ruleset.name).add.push(context);
+    const fallbackGroup = group(fallback.ruleset.name);
+    fallbackGroup.add.push(context);
+    if (unscopedAwaited.has(context)) fallbackGroup.awaited.add(context);
   }
 
   const actions = [];
-  for (const [name, { add, remove, pins: groupPins, unpinned }] of groups) {
+  for (const [
+    name,
+    { add, remove, pins: groupPins, unpinned, awaited: routedAwaited },
+  ] of groups) {
     const ruleset = (live.rulesets ?? []).find(entry => entry?.name === name);
     if (!ruleset) {
       actions.push({
@@ -1329,9 +1383,17 @@ function planContextRepairs({
       payload: rulesetPayload(ruleset, {
         add,
         remove,
-        awaited: awaited
-          .filter(record => record.ruleset === name)
-          .map(record => record.context),
+        // Both halves of the same question — which of this ruleset's additions
+        // an external app posts. A declaration that named this ruleset answers
+        // it directly; one that named none was answered by the routing above.
+        awaited: [
+          ...new Set([
+            ...awaited
+              .filter(record => record.ruleset === name)
+              .map(record => record.context),
+            ...routedAwaited,
+          ]),
+        ],
         // The name-keyed map still carries AWAITED pins, which are declared per
         // context and have no ruleset of their own, so it stays the base. A
         // declared record then overrides it — with its pin, or by deleting the
@@ -1478,13 +1540,24 @@ export function reconcile({
 
   // The structured declaration travels through the comparison, so a pinned
   // context is not reported as satisfied by an unpinned one somewhere else.
-  // Only `configured` is passed: it is what the project actually declared. The
-  // awaited-context homes below are a routing hint for repairs, not a stated
-  // expectation, and treating them as one would report drift nobody declared.
+  // The awaited-context home is part of that structure, not a repair-only
+  // routing hint: it is the ruleset this run WILL write the context to, so a
+  // comparison that ignored it reported the requirement satisfied by whichever
+  // other ruleset happened to carry the name — and then planned no repair for
+  // the one that lacked it. Where no home resolves, nothing is asserted and the
+  // context keeps matching on name alone, so no drift is invented either.
   const resolvedAwaitedHome = awaitedHome(live, rulesetName);
+  const declaredAwaitedPins = awaitedPins(gates, moment);
+  // The declared pin travels with the declaration. Once the awaited home is a
+  // comparison record, that record is what the repair reads its pin off — so
+  // omitting it here would have the repair write the context unpinned and
+  // silently discard the one app the project said may post it.
   const awaitedDeclarations = awaited.map(context => ({
     context,
     ...(resolvedAwaitedHome === null ? {} : { ruleset: resolvedAwaitedHome }),
+    ...(Object.hasOwn(declaredAwaitedPins, context)
+      ? { integration_id: declaredAwaitedPins[context] }
+      : {}),
   }));
   const contexts = reconcileContexts({
     declared,
@@ -1514,7 +1587,7 @@ export function reconcile({
         prune,
         rulesetName,
         awaited: awaitedDeclarations,
-        pins: { ...configured.pins, ...awaitedPins(gates, moment) },
+        pins: { ...configured.pins, ...declaredAwaitedPins },
         // An awaited context has no ruleset in its declaration — it is declared
         // on a GATE. Its home defaults to the ruleset Lisa generates from
         // config, which is where the applier writes it, so the two writers

package/all/copy-overwrite/scripts/lisa-work-item.mjs

@@ -2508,30 +2508,89 @@ function option(args, name, envName) {
 }
 
 /**
- * Resolve the canonical pull-request option without letting an environment
- * fallback outrank either explicit alias.
+ * Read one explicit pull-request alias, refusing a present-but-empty flag.
+ *
+ * Written as "absent, or a usable value" — never "absent, or absent-looking".
+ * The shared `option` helper treats a valueless flag as absent so a good value
+ * in the environment still wins, which is right for `--ref` and wrong here: an
+ * operator who typed `--pr-url` has NAMED the evidence, and quietly answering
+ * with `LISA_PR_URL` writes a backlink to whatever pull request the surrounding
+ * automation happened to export. Measured before this refusal existed:
+ * `backlink --ref <item> --pr-url --json` with `LISA_PR_URL` set to a different
+ * pull request wrote the managed comment pointing at the environment's pull
+ * request and exited 0, so the traceability gate went green having proved the
+ * work item was linked to the wrong change.
+ *
+ * A present flag whose value is empty, whitespace, or another option is the
+ * same typo with three spellings, and all three are refused rather than
+ * resolved — a refusal costs one re-run, and the alternative is evidence
+ * nobody chose.
+ * @param {string[]} args Command arguments.
+ * @param {string} name Alias to read, including leading dashes.
+ * @returns {string | undefined} The supplied value, or undefined when absent.
+ */
+function explicitPullRequestUrl(args, name) {
+  const index = args.indexOf(name);
+  if (index < 0) return undefined;
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("-") || value.trim() === "") {
+    throw new TrackingError(
+      `${name} was supplied without a pull-request URL. Pass ` +
+        `${name} https://github.com/owner/repo/pull/123, or omit the flag ` +
+        `entirely to fall back to LISA_PR_URL`
+    );
+  }
+  return value;
+}
+
+/**
+ * Resolve the canonical pull-request URL for backlink, validation and
+ * completion, without letting an environment fallback outrank either alias.
+ *
+ * Two rules, and both exist because the backlink is how completion is PROVEN.
  *
- * Resolving `--pr-url` with an environment fallback before inspecting `--url`
- * lets `LISA_PR_URL` hide an explicit alias. Conflicting explicit aliases are
- * refused instead of choosing completion evidence by argument order.
+ * Precedence: `LISA_PR_URL` is read only when neither explicit alias is
+ * present. Resolving `--pr-url` with an environment fallback before inspecting
+ * `--url` let the environment hide an explicit alias.
+ *
+ * Canonicalisation: the value returned is the parsed canonical URL, not the
+ * caller's string. `assertBacklink` compares URLs by equality — token equality
+ * in `textContainsBacklink`, `===` on both native link fields — and the
+ * completion path already canonicalises through `mergedPullRequestEvidence`.
+ * A backlink WRITTEN from the raw string therefore did not match the same pull
+ * request READ back a moment later if the two spellings differed by a trailing
+ * slash, and the failure surfaces as "no verified backlink" on work that is
+ * genuinely linked. Canonicalising here puts one spelling on both sides. It
+ * also means a value that is not a GitHub pull-request URL at all is refused
+ * where it is supplied, rather than written into the managed comment and
+ * discovered later by the check it was supposed to satisfy.
+ *
+ * Conflicting explicit aliases are refused on the RAW strings, so two
+ * spellings of one pull request conflict just as two different pull requests
+ * do. The looser rule would have to canonicalise first and then accept, and
+ * accepting evidence the caller spelled two ways is the direction that reports
+ * unproven work as proven.
+ *
+ * An empty `LISA_PR_URL` is absent, unlike an empty `--pr-url`: exporting an
+ * empty variable is how a shell says "unset" and no operator typed it, so the
+ * caller still gets the command's own "requires --pr-url <url>" refusal
+ * instead of a parse error about a string nobody wrote.
  * @param {string[]} args Command arguments.
- * @returns {string | undefined} The explicit or environment URL.
+ * @returns {string | undefined} The canonical URL, or undefined when none.
  */
 function pullRequestUrlOption(args) {
-  const explicit = name => {
-    const index = args.indexOf(name);
-    if (index < 0) return undefined;
-    const value = args[index + 1];
-    return value === undefined || value.startsWith("-") ? undefined : value;
-  };
-  const canonical = explicit("--pr-url");
-  const alias = explicit("--url");
+  const canonical = explicitPullRequestUrl(args, "--pr-url");
+  const alias = explicitPullRequestUrl(args, "--url");
   if (canonical && alias && canonical !== alias) {
     throw new TrackingError(
       "Conflicting pull-request evidence: --pr-url and --url name different values"
     );
   }
-  return canonical ?? alias ?? process.env.LISA_PR_URL;
+  const supplied = canonical ?? alias;
+  if (supplied !== undefined) return githubPullRequestUrl(supplied).url;
+  const fromEnvironment = String(process.env.LISA_PR_URL ?? "").trim();
+  if (fromEnvironment === "") return undefined;
+  return githubPullRequestUrl(fromEnvironment).url;
 }
 
 function bind(args) {