@codyswann/lisa 4.24.1 → 4.25.0

package/all/copy-overwrite/scripts/check-orphaned-branches.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+/**
+ * Report remote branches carrying work that was pushed and never submitted
+ * (issue #3446).
+ *
+ * ## The state this exists for
+ *
+ * `lisa-git-submit-pr` lists **Push** and **PR Management** as separate steps
+ * with nothing binding them: no atomicity, no post-condition, no terminal check
+ * that a pull request exists when the flow ends. An agent that stops between
+ * them — context exhaustion, a turn limit, an interruption, a refused call —
+ * leaves a branch on the remote carrying finished work that is in no review, no
+ * CI run, and no report.
+ *
+ * The skill's own `Never` list contained the rule for exactly this pair of
+ * steps, pointing the other way: *"skip pushing before PR creation"* forbids a
+ * PR without a push. Push without a PR was unprohibited and undetected.
+ *
+ * **The last signal such an agent receives is green.** The pre-push hook prints
+ * `no pull request exists yet, so gates 4 and 5 could not be checked here — CI
+ * will verify both`, which is accurate and reads as an informational pass.
+ * Downstream the silence holds: the work item keeps its in-progress role, so
+ * intake will not re-dispatch it, and nothing counts a branch without a pull
+ * request. The state is unreachable by every other check.
+ *
+ * Measured when this was written: 15 such branches in one repository, roughly
+ * 12,900 insertions, every one dated within a single day. Fifteen simultaneous
+ * stops at the same step is not fifteen coincidences.
+ *
+ * ## What it reports, and what it deliberately does not
+ *
+ * Reported: a remote branch **ahead** of the default branch, with **no** pull
+ * request of any state.
+ *
+ * A branch level with the default branch has nothing to submit. A branch whose
+ * pull request already MERGED is an un-deleted leftover, not lost work — and
+ * keying on "no OPEN pull request" instead would report every such branch in
+ * the repository. Both exclusions exist because a check that reports everything
+ * is one nobody reads, which is the same outcome as no check at all.
+ *
+ * Determinism: Node built-ins only, no `Date`, no `Math.random`. Branch and
+ * pull-request facts come from `git` and `gh`; with neither available the
+ * script reports that it could not look rather than that it found nothing.
+ * @module check-orphaned-branches
+ */
+
+import { spawnSync } from "node:child_process";
+
+import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+
+/** Branch name prefixes that are never work-in-flight. */
+const IGNORED_PREFIXES = Object.freeze(["backup/", "gh-readonly-queue/"]);
+
+/** Exit codes. `FOUND` is advisory by default; see `--fail-on-found`. */
+const EXIT = Object.freeze({ OK: 0, FOUND: 1, UNAVAILABLE: 70 });
+
+/**
+ * Run a command and return its trimmed stdout, or undefined on any failure.
+ *
+ * Undefined means "could not look", never "looked and found nothing" — the two
+ * are reported differently, because a check that turns a broken command into a
+ * clean result is the vacuous-success failure this file's family exists to
+ * refuse.
+ * @param {string} command Executable name.
+ * @param {string[]} args Arguments.
+ * @returns {string | undefined} Trimmed stdout, or undefined.
+ */
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) return undefined;
+  return result.stdout.trim();
+}
+
+/**
+ * The repository's default branch, as the remote reports it.
+ * @param {string} remote Remote name.
+ * @returns {string | undefined} Short branch name, or undefined.
+ */
+export function defaultBranch(remote = "origin") {
+  const symref = run("git", [
+    "symbolic-ref",
+    "--quiet",
+    `refs/remotes/${remote}/HEAD`,
+  ]);
+  return symref?.startsWith(`refs/remotes/${remote}/`)
+    ? symref.slice(`refs/remotes/${remote}/`.length)
+    : undefined;
+}
+
+/**
+ * Every branch name that has a pull request, in any state.
+ *
+ * Any state, not just OPEN. A branch whose pull request merged is a leftover
+ * ref, not unsubmitted work, and reporting it would bury the real findings
+ * under every branch nobody deleted.
+ * @returns {Set<string> | undefined} Branch names, or undefined if `gh` failed.
+ */
+export function branchesWithPullRequests() {
+  const json = run("gh", [
+    "pr",
+    "list",
+    "--state",
+    "all",
+    "--limit",
+    "1000",
+    "--json",
+    "headRefName",
+  ]);
+  if (json === undefined) return undefined;
+  try {
+    const rows = JSON.parse(json);
+    return new Set(
+      Array.isArray(rows)
+        ? rows
+            .map(row => row?.headRefName)
+            .filter(name => typeof name === "string")
+        : []
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Remote branches ahead of the default branch, with their commit counts.
+ * @param {string} remote Remote name.
+ * @param {string} base Default branch name.
+ * @returns {ReadonlyArray<{branch: string, ahead: number}> | undefined} Rows.
+ */
+export function branchesAhead(remote = "origin", base = "main") {
+  const listed = run("git", [
+    "for-each-ref",
+    "--format=%(refname:strip=3)",
+    `refs/remotes/${remote}`,
+  ]);
+  if (listed === undefined) return undefined;
+  const rows = [];
+  for (const branch of listed.split("\n").map(line => line.trim())) {
+    if (!branch || branch === base || branch === "HEAD") continue;
+    if (IGNORED_PREFIXES.some(prefix => branch.startsWith(prefix))) continue;
+    const count = run("git", [
+      "rev-list",
+      "--count",
+      `${remote}/${base}..${remote}/${branch}`,
+    ]);
+    const ahead = Number.parseInt(count ?? "", 10);
+    if (Number.isFinite(ahead) && ahead > 0) rows.push({ ahead, branch });
+  }
+  return rows;
+}
+
+/**
+ * Branches carrying commits that no pull request has ever covered.
+ * @param {object} inputs Inputs.
+ * @param {ReadonlyArray<{branch: string, ahead: number}>} inputs.ahead Branches ahead of base.
+ * @param {Set<string>} inputs.submitted Branch names that have a pull request.
+ * @returns {ReadonlyArray<{branch: string, ahead: number}>} The orphans.
+ */
+export function orphanedBranches({ ahead, submitted }) {
+  return ahead.filter(row => !submitted.has(row.branch));
+}
+
+/**
+ * Report orphaned branches.
+ * @param {string[]} argv Arguments.
+ * @returns {number} Exit code.
+ */
+export function main(argv = process.argv.slice(2)) {
+  const remote = "origin";
+  const base = defaultBranch(remote);
+  if (!base) {
+    console.error(
+      "check-orphaned-branches: could not resolve the remote default branch, so nothing was checked. This is NOT a clean result."
+    );
+    return EXIT.UNAVAILABLE;
+  }
+  const ahead = branchesAhead(remote, base);
+  const submitted = branchesWithPullRequests();
+  if (ahead === undefined || submitted === undefined) {
+    console.error(
+      `check-orphaned-branches: could not read ${ahead === undefined ? "branches" : "pull requests"}, so nothing was checked. This is NOT a clean result.`
+    );
+    return EXIT.UNAVAILABLE;
+  }
+  const orphans = orphanedBranches({ ahead, submitted });
+  if (orphans.length === 0) {
+    console.log(
+      `check-orphaned-branches: every remote branch ahead of ${base} has a pull request.`
+    );
+    return EXIT.OK;
+  }
+  console.log(
+    `check-orphaned-branches: ${orphans.length} branch(es) carry commits that were pushed and never submitted.\n`
+  );
+  for (const { branch, ahead: count } of [...orphans].sort((a, b) =>
+    a.branch.localeCompare(b.branch)
+  ))
+    console.log(
+      `  ${branch} — ${count} commit(s) ahead of ${base}, no pull request`
+    );
+  console.log(
+    "\nWork on these branches is in no review, no CI run, and no report, and it drifts from " +
+      `${base} until it is submitted or deleted. Open a pull request for each, or delete the branch ` +
+      "if the work is abandoned — but decide, rather than leaving it invisible."
+  );
+  return argv.includes("--fail-on-found") ? EXIT.FOUND : EXIT.OK;
+}
+
+if (invokedAsScript(import.meta.url)) {
+  // exitCode (not process.exit): when stdout is a pipe, writes are async and
+  // process.exit() truncates the report mid-flush.
+  process.exitCode = main(process.argv.slice(2));
+}

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]