@gotgenes/pi-permission-system 27.1.0 → 27.1.2

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [27.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.1...pi-permission-system-v27.1.2) (2026-08-29)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** claim no arity for awk's long forms, whose parser the bare name does not fix ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([6c8e4a0](https://github.com/gotgenes/pi-packages/commit/6c8e4a0b813d17750296cbd065aec20377c82d2a))
+* **pi-permission-system:** discharge a flag argument on whatever node type follows ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([228f6fb](https://github.com/gotgenes/pi-packages/commit/228f6fb235310b304557ec501567373e33d4cfab))
+* **pi-permission-system:** read --context per tool, whose arity differs between grep and rg ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([bba8317](https://github.com/gotgenes/pi-packages/commit/bba83175d1f9f8079cd9613412c65868e4a2fa09))
+* **pi-permission-system:** read awk's long forms only for gawk ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([52488f0](https://github.com/gotgenes/pi-packages/commit/52488f02cc902b8669f893cc1cfee090482f2e72))
+* **pi-permission-system:** recognize the long, embedded, and glued spellings of a pattern-first flag ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([ce7b65e](https://github.com/gotgenes/pi-packages/commit/ce7b65eb607cc2e6f61a6eceda1d1a9bb22aea85))
+* **pi-permission-system:** spend a pattern positional on a computed or numeric pattern ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([dce4d3f](https://github.com/gotgenes/pi-packages/commit/dce4d3f06b164f6f45df3c5550ec624f3acba896))
+
+
+### Documentation
+
+* **pi-permission-system:** record the optional-argument flag residuals ([#823](https://github.com/gotgenes/pi-packages/issues/823)) ([94e51fc](https://github.com/gotgenes/pi-packages/commit/94e51fc5a05acf3b2c4bc49479b45b0b7797b9ac))
+
+## [27.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.0...pi-permission-system-v27.1.1) (2026-08-28)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** project glob-bearing bash path tokens to the path surfaces ([706c75d](https://github.com/gotgenes/pi-packages/commit/706c75da10d03c61ef0d53f9571d249b91986db5)), closes [#821](https://github.com/gotgenes/pi-packages/issues/821)
+
 ## [27.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.0.1...pi-permission-system-v27.1.0) (2026-08-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "27.1.0",
+  "version": "27.1.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/bash/token-classification.ts

@@ -16,9 +16,17 @@
  * `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
  *
  * All three classifiers share the private `rejectNonPathToken` predicate that
- * captures the six rejection cases common to them (the production clone this
+ * captures the five rejection cases common to them (the production clone this
  * module was extracted to eliminate).
  *
+ * None of them reads a token's glob or regex metacharacters. A shell bracket
+ * glob and a regex character class are spelled identically, so "contains a
+ * metacharacter" cannot decide path-hood — and it silently dropped tokens the
+ * shell really does expand into filesystem paths (`/etc/[p]asswd`,
+ * `rm -rf /tmp/tmp.*`, #821). What a pattern argument is instead settled by
+ * *position*: `PATTERN_FIRST_COMMANDS` in `token-collection.ts` skips a
+ * pattern-first command's inline pattern positional at collection time.
+ *
  * Both `classifyTokenAsPathCandidate` and `classifyTokenAsRuleCandidate` recognize
  * Windows drive-letter absolute paths (`C:/…`, `C:\…`) unconditionally on all
  * platforms. On POSIX the token resolves as a real in-CWD relative path and is
@@ -106,8 +114,8 @@ export function classifyTokenAsRuleCandidate(
  * *shape* name a path at all?
  *
  * It runs only the shared `rejectNonPathToken` prelude, so a flag,
- * env-assignment, URL, `@scope` token, or regex-shaped token is never a
- * candidate. Everything else is returned for the caller to probe.
+ * env-assignment, URL, or `@scope` token is never a candidate. Everything else
+ * is returned for the caller to probe.
  *
  * Deliberately consults no policy: candidacy is settled by the filesystem and
  * the decision by the ruleset, which keeps this module a pure shape function
@@ -137,19 +145,14 @@ const WINDOWS_DRIVE_PATH_PATTERN = /^[a-zA-Z]:[/\\]/;
  */
 const URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
 
-/**
- * Regex metacharacter sequences that are never found in real filesystem paths.
- * If a token contains any of these, it is almost certainly a regex pattern
- * (e.g. a grep argument) rather than a path.
- */
-const REGEX_METACHAR_PATTERN = /\.\*|\.\+|\\\||\\\(|\\\)|\[.*?\]|\^\//;
-
 /**
  * Shared rejection prelude: returns `true` when a token can never be a
  * filesystem path, regardless of which classifier is asking.
  *
  * Rejects: empty tokens, flags (leading `-`), env assignments (`FOO=/bar`),
- * URLs, `@scope/package` patterns, and regex metacharacter sequences.
+ * URLs, and `@scope/package` patterns. Each rules a token out by syntax; a
+ * glob or regex metacharacter does not, since the two are indistinguishable
+ * and the shell expands the former into real paths (#821).
  *
  * A bare `/` (or `//`, `///`) is NOT rejected: it denotes the filesystem root,
  * a deliberate external-directory access (`find /`, `ls /`), so it must reach
@@ -172,7 +175,5 @@ function rejectNonPathToken(token: string): boolean {
   // since it looks like an absolute-rooted path, not an npm scope.
   if (token.startsWith("@") && !token.startsWith("@/")) return true;
 
-  if (REGEX_METACHAR_PATTERN.test(token)) return true;
-
   return false;
 }

package/src/access-intent/bash/token-collection.ts

@@ -79,10 +79,11 @@ export function collectCommandTokens(node: TSNode): PathToken[] {
   const config = commandName
     ? PATTERN_FIRST_COMMANDS.get(commandName)
     : undefined;
-  const tokens = config
-    ? collectPatternCommandTokens(node, config, effect)
-    : collectGenericCommandTokens(node, effect);
-  return [...tokens, ...collectEmbeddedOptionValues(node, effect)];
+  if (config) return collectPatternCommandTokens(node, config, effect);
+  return [
+    ...collectGenericCommandTokens(node, effect),
+    ...collectEmbeddedOptionValues(node, effect),
+  ];
 }
 
 /**
@@ -208,11 +209,11 @@ function commandArgumentWords(node: TSNode): string[] {
 const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
 
 /**
- * The values embedded in this command's `--opt=value` argument tokens.
+ * The values embedded in a **generic** command's `--opt=value` argument tokens.
  *
  * Read straight from the argument nodes rather than from the collected token
- * list, because a pattern-first command's collector classifies a flag and never
- * emits it — so `grep --file=/tmp/patterns` would otherwise lose the path.
+ * list, because a collector classifies a flag and never emits it — so
+ * `tar --directory=/etc` would otherwise lose the path.
  *
  * This is token *preprocessing*, not classification: the extracted value is
  * handed to the ordinary shape classifiers and existence probe, so
@@ -220,6 +221,10 @@ const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
  * yields a bare `json` that names nothing and is dropped. Keeping the split
  * here is what lets the projection see option-embedded paths without per-command
  * option tables (ADR 0009, #645).
+ *
+ * A pattern-first command runs the same split from inside its own walker
+ * instead, because there the flag's *role* is known: splitting blindly emits a
+ * pattern flag's value as a path candidate (#823).
  */
 function collectEmbeddedOptionValues(
   node: TSNode,
@@ -239,11 +244,64 @@ function collectEmbeddedOptionValues(
   return values;
 }
 
+/** The value embedded in a single `--opt=value` token, if it carries one. */
+function embeddedOptionValueToken(
+  text: string,
+  effect: TokenEffect,
+): PathToken[] {
+  const value = OPTION_VALUE_PATTERN.exec(text)?.[1];
+  return value === undefined ? [] : [{ token: value, effect }];
+}
+
+/**
+ * What a recognized flag's argument is, for the pattern-first walker.
+ *
+ * `script` and `script-file` mark the inline pattern positional as already
+ * supplied; `value` and `suffix` do not. Only `script-file` contributes a path
+ * candidate — the others name a pattern, a count, or a backup suffix.
+ */
+type PatternFlagRole =
+  /** Supplies the pattern/script inline (`grep -e`, `sed --expression`). */
+  | "script"
+  /** Supplies the pattern/script from a file (`grep -f`, `sed --file`). */
+  | "script-file"
+  /** Consumes a value that is neither pattern nor path (`grep -A`, `rg -g`). */
+  | "value"
+  /**
+   * Consumes the following argument only when it is empty.
+   *
+   * BSD `sed` requires a separate suffix argument (`sed -i '' 's/a/b/' f`)
+   * while GNU `sed` requires it glued (`-i`, `-i.bak`). Consuming
+   * unconditionally is right for one and eats the *script* on the other,
+   * leaving the file operand to be skipped as the inline pattern — a write
+   * target that reaches no path surface. The argument's own emptiness decides
+   * it, so the walk needs no knowledge of which sed is installed (#823).
+   *
+   * BSD also accepts a separate *non-empty* suffix (`sed -i bak 's/a/b/' f`),
+   * which this rule declines: the suffix then spends the pattern positional
+   * and the script surfaces as a candidate. The file operand still survives,
+   * so the residual is on ADR 0009's recoverable side.
+   */
+  | "suffix"
+  /**
+   * Recognized, but whose arity depends on which implementation the command's
+   * *name* resolves to — so it takes neither the following argument nor the
+   * pattern positional.
+   *
+   * `awk` is GNU awk on Fedora/RHEL, where `--file prog.awk` reads `prog.awk`,
+   * and one-true-awk or mawk elsewhere, where the long option is ignored
+   * outright and `prog.awk` is the program *text*. Asserting either arity
+   * drops a real operand on the other family, and the projection cannot see
+   * which binary the name will reach. Claiming neither over-surfaces on both
+   * — the recoverable direction — and the extra token names nothing, so the
+   * existence probe discards it. Prefer a precise role wherever the name does
+   * fix the parser: `gawk` gets the real ones (#823).
+   */
+  | "unknown-arity";
+
 interface PatternCommandConfig {
-  /** Flags that consume the next argument as a non-path value (pattern, separator, etc.) */
-  readonly argConsumingFlags: ReadonlySet<string>;
-  /** Flags that consume the next argument as a file path */
-  readonly fileConsumingFlags: ReadonlySet<string>;
+  /** Recognized flag spellings, short and long, mapped to their roles. */
+  readonly flags: ReadonlyMap<string, PatternFlagRole>;
   /**
    * Number of leading positional arguments that are patterns/scripts, not paths.
    * Default: 1 (covers sed, awk, grep, rg).
@@ -252,130 +310,186 @@ interface PatternCommandConfig {
   readonly patternPositionals?: number;
 }
 
+const GREP_FLAGS = new Map<string, PatternFlagRole>([
+  ["-e", "script"],
+  ["--regexp", "script"],
+  ["-f", "script-file"],
+  ["--file", "script-file"],
+  ["-A", "value"],
+  ["--after-context", "value"],
+  ["-B", "value"],
+  ["--before-context", "value"],
+  ["-C", "value"],
+  // `--context` is deliberately absent, though `-C` is present and `rg` lists
+  // the long form below. grep parses with getopt, which declares `context`
+  // with an *optional* argument (`-C[NUM]`'s history), and a long option
+  // declared that way never takes a separate `argv`: `grep --context 2 pat f`
+  // searches for `2` in the files `pat` and `f`. Listing it would consume the
+  // `2`, leaving `pat` — a real file operand — to be skipped as the inline
+  // pattern. Its absence costs only a bare `2` token from `--context=2`, which
+  // names nothing and the existence probe drops (#823).
+  ["-m", "value"],
+  ["--max-count", "value"],
+]);
+
+const SED_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ["-e", "script"],
+    ["--expression", "script"],
+    ["-f", "script-file"],
+    ["--file", "script-file"],
+    ["-i", "suffix"],
+  ]),
+};
+
+/**
+ * The short flags are POSIX and consume on every awk; the GNU long forms are
+ * `unknown-arity` because the bare name does not fix the parser.
+ *
+ * `awk` is GNU awk on Fedora/RHEL, where `--file prog.awk` reads `prog.awk`,
+ * and one-true-awk or mawk on macOS and Debian/Ubuntu, where the long option
+ * is ignored outright (`awk: unknown option --field-separator ignored`) and
+ * the following words are the program text and its input files. Asserting
+ * either arity drops a real operand on the other family, so the table asserts
+ * neither. `nawk` shares this for the same reason (#823).
+ */
+const AWK_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ["-e", "script"],
+    ["-f", "script-file"],
+    ["-F", "value"],
+    ["-v", "value"],
+    ["--source", "unknown-arity"],
+    ["--file", "unknown-arity"],
+    ["--field-separator", "unknown-arity"],
+    ["--assign", "unknown-arity"],
+  ]),
+};
+
+/** `gawk` names GNU awk outright, so its long forms carry their real roles. */
+const GAWK_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ...AWK_CONFIG.flags,
+    ["--source", "script"],
+    ["--file", "script-file"],
+    ["--field-separator", "value"],
+    ["--assign", "value"],
+  ]),
+};
+
+const GREP_CONFIG: PatternCommandConfig = { flags: GREP_FLAGS };
+
+const RG_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ...GREP_FLAGS,
+    // rg parses with clap rather than getopt, where `--context` takes a
+    // required argument, so its separated spelling really does consume:
+    // `rg --context 2 pat f` searches for `pat` in `f`. Same spelling as
+    // grep's, opposite arity — which is why it is listed per tool rather than
+    // shared above (#823).
+    ["--context", "value"],
+    ["-g", "value"],
+    ["--glob", "value"],
+    ["-t", "value"],
+    ["--type", "value"],
+    ["-T", "value"],
+    ["--type-not", "value"],
+    ["-j", "value"],
+    ["--threads", "value"],
+    ["-M", "value"],
+    ["--max-columns", "value"],
+    ["-r", "value"],
+    ["--replace", "value"],
+    ["-E", "value"],
+    ["--encoding", "value"],
+  ]),
+};
+
+const SD_CONFIG: PatternCommandConfig = {
+  flags: new Map<string, PatternFlagRole>([
+    ["-f", "value"],
+    ["--flags", "value"],
+    ["-n", "value"],
+    ["--max-replacements", "value"],
+  ]),
+  patternPositionals: 2,
+};
+
 /**
  * Commands whose first N positional arguments are inline patterns/scripts,
  * not filesystem paths. The map stores per-command flag configuration so
  * the walker can correctly identify which arguments are consumed by flags
  * vs. which are positional.
+ *
+ * Names share a configuration object only when they share a *parser*, which is
+ * narrower than being aliases: `egrep`/`fgrep` are the same binary as `grep`
+ * here, and `nawk` is one-true-awk like `awk` — but `gawk` has its own config,
+ * because it is the only one of the three that certainly means GNU awk and so
+ * the only one whose long options certainly consume (#823).
  */
 const PATTERN_FIRST_COMMANDS: ReadonlyMap<string, PatternCommandConfig> =
   new Map([
-    [
-      "sed",
-      {
-        argConsumingFlags: new Set(["-e", "-i"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "awk",
-      {
-        argConsumingFlags: new Set(["-e", "-F", "-v"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "gawk",
-      {
-        argConsumingFlags: new Set(["-e", "-F", "-v"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "nawk",
-      {
-        argConsumingFlags: new Set(["-e", "-F", "-v"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "grep",
-      {
-        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "egrep",
-      {
-        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "fgrep",
-      {
-        argConsumingFlags: new Set(["-e", "-A", "-B", "-C", "-m"]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "rg",
-      {
-        argConsumingFlags: new Set([
-          "-e",
-          "-A",
-          "-B",
-          "-C",
-          "-m",
-          "-g",
-          "-t",
-          "-T",
-          "-j",
-          "-M",
-          "-r",
-          "-E",
-        ]),
-        fileConsumingFlags: new Set(["-f"]),
-      },
-    ],
-    [
-      "sd",
-      {
-        argConsumingFlags: new Set(["-n", "-f"]),
-        fileConsumingFlags: new Set([]),
-        patternPositionals: 2,
-      },
-    ],
+    ["sed", SED_CONFIG],
+    ["awk", AWK_CONFIG],
+    ["gawk", GAWK_CONFIG],
+    ["nawk", AWK_CONFIG],
+    ["grep", GREP_CONFIG],
+    ["egrep", GREP_CONFIG],
+    ["fgrep", GREP_CONFIG],
+    ["rg", RG_CONFIG],
+    ["sd", SD_CONFIG],
   ]);
 
 /**
  * Describes what the walker should do when it encounters a flag word inside
  * a pattern-first command.  Using a discriminated union lets the `switch` in
- * `collectPatternCommandTokens` narrow `nextArgAction` without a non-null
+ * `collectPatternCommandTokens` narrow the flag's role without a non-null
  * assertion (which would trigger the Biome/ESLint assertion conflict).
  */
 type PatternCommandFlagDirective =
   | { kind: "end-of-flags" }
   | { kind: "regular-flag" }
-  | {
-      kind: "consume-arg";
-      nextArgAction: "skip" | "extract";
-      setsExplicitScript: boolean;
-    };
+  /** A recognized flag whose value is the argument that follows it. */
+  | { kind: "consume-next"; role: PatternFlagRole }
+  /** A recognized flag carrying its value in the same token. */
+  | { kind: "inline-value"; role: PatternFlagRole; value: string };
+
+/** A long option carrying its value inline: `--name=value`. */
+const LONG_OPTION_VALUE_PATTERN = /^(--[^=\s]+)=(.+)$/;
 
 /**
  * Classify a flag word from a pattern-first command into a directive that
- * tells the walker how to handle the flag and its following argument.
+ * tells the walker how to handle the flag and its value.
+ *
+ * Matched in the order the tools accept: the exact spelling (short or long),
+ * then a long option's `=`-embedded value, then a glued short value. The glued
+ * form matches only the **first** short flag, which is getopt's own rule —
+ * `grep -ei pattern` really is `-e` with the value `i`. A cluster whose
+ * argument-taking flag is not first (`grep -ie pattern`) therefore stays a
+ * plain flag, which over-surfaces the pattern rather than dropping the
+ * command's operand (ADR 0009's recoverable direction).
  */
 function classifyPatternCommandFlag(
   text: string,
   config: PatternCommandConfig,
 ): PatternCommandFlagDirective {
   if (text === "--") return { kind: "end-of-flags" };
-  if (config.argConsumingFlags.has(text)) {
-    return {
-      kind: "consume-arg",
-      nextArgAction: "skip",
-      setsExplicitScript: text === "-e" || text === "-f",
-    };
+
+  const exact = config.flags.get(text);
+  if (exact) return { kind: "consume-next", role: exact };
+
+  const longOption = LONG_OPTION_VALUE_PATTERN.exec(text);
+  if (longOption) {
+    const [, name, value] = longOption;
+    const role = config.flags.get(name);
+    return role === undefined
+      ? { kind: "regular-flag" }
+      : { kind: "inline-value", role, value };
   }
-  if (config.fileConsumingFlags.has(text)) {
-    return {
-      kind: "consume-arg",
-      nextArgAction: "extract",
-      setsExplicitScript: true,
-    };
+
+  if (!text.startsWith("--") && text.length > 2) {
+    const role = config.flags.get(text.slice(0, 2));
+    if (role) return { kind: "inline-value", role, value: text.slice(2) };
   }
   return { kind: "regular-flag" };
 }
@@ -389,11 +503,13 @@ function classifyPatternCommandFlag(
  * inline patterns/scripts and are skipped. Remaining positional
  * arguments are collected as path candidates.
  *
- * Flags listed in `argConsumingFlags` consume the next argument
- * (skipped). Flags in `fileConsumingFlags` consume the next
- * argument as a file path (collected). The flags `-e` and `-f`
- * additionally signal that an explicit script was provided via
- * flag, so no inline positional script is expected.
+ * A recognized flag's role (see {@link PatternFlagRole}) decides three things
+ * at once: whether the pattern positional is still expected, whether the
+ * flag's value is a path candidate, and — for `suffix` — whether the
+ * following argument belongs to the flag at all. The `=`-embedded and glued
+ * spellings carry the value in the flag's own token, so the walker splits it
+ * here rather than letting {@link collectEmbeddedOptionValues} emit a
+ * pattern's text as a path (#823).
  */
 function collectPatternCommandTokens(
   node: TSNode,
@@ -403,7 +519,7 @@ function collectPatternCommandTokens(
   const patternPositionals = config.patternPositionals ?? 1;
   let hasExplicitScript = false;
   let positionalsSeen = 0;
-  let nextArgAction: "skip" | "extract" | null = null;
+  let pendingConsumption: PatternFlagRole | null = null;
   let pastEndOfFlags = false;
   const tokens: PathToken[] = [];
 
@@ -415,23 +531,50 @@ function collectPatternCommandTokens(
     if (child.type === "command_name" || child.type === "variable_assignment")
       continue;
 
-    // Only process argument-like nodes; recurse into others
-    // (e.g. command_substitution) for nested commands.
-    if (!ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(...collectPathCandidateTokens(child));
-      continue;
-    }
-
+    const isArgNode = ARG_NODE_TYPES.has(child.type);
     const text = resolveNodeText(child);
 
-    // Handle consumed argument from previous flag.
-    if (nextArgAction === "skip") {
-      nextArgAction = null;
-      continue;
+    // Handle the argument a previous flag consumed. The consumption discharges
+    // on whatever node type follows, not only on an ARG_NODE_TYPES one: a bare
+    // number (`-A 3`), an expansion (`-A $N`), and a substitution
+    // (`-A $(echo 3)`) are all this flag's argument, and carrying the pending
+    // skip past them lands it on the *pattern* — shifting the positional count
+    // by one and eating the command's real file operand (#823).
+    if (pendingConsumption !== null) {
+      const consumption = pendingConsumption;
+      pendingConsumption = null;
+      if (!isArgNode) {
+        // Contributes no operand text of its own, but may host a nested
+        // execution whose operands are candidates (#741).
+        tokens.push(...collectPathCandidateTokens(child));
+        continue;
+      }
+      const discharge = dischargePendingConsumption(consumption, text, effect);
+      if (discharge.token) tokens.push(discharge.token);
+      if (discharge.consumed) continue;
     }
-    if (nextArgAction === "extract") {
-      tokens.push({ token: text, effect });
-      nextArgAction = null;
+
+    // A node outside ARG_NODE_TYPES is still one word the shell passes as an
+    // argument (`grep 42 f`, `grep $PATTERN f`, `grep $(cmd) f`), so it spends
+    // a pattern positional even though no reliable operand text can be read
+    // from it. Counting only argument nodes left a numeric or computed pattern
+    // unseen, so the slot was spent on the command's real operand instead and
+    // the operand reached no path surface (#823).
+    //
+    // A redirect hosted on the command node is not an argument and is excluded;
+    // counting it would push the real pattern out as an operand token. The
+    // exclusion is the narrow side on purpose: miscounting an argument as a
+    // redirect drops an operand, while the reverse only over-surfaces.
+    if (!isArgNode) {
+      if (
+        !EXECUTION_HOST_TYPES.has(child.type) &&
+        !hasExplicitScript &&
+        positionalsSeen < patternPositionals
+      ) {
+        positionalsSeen++;
+      }
+      // Recurse for nested commands (e.g. command_substitution).
+      tokens.push(...collectPathCandidateTokens(child));
       continue;
     }
 
@@ -447,11 +590,19 @@ function collectPatternCommandTokens(
         case "end-of-flags":
           pastEndOfFlags = true;
           break;
-        case "consume-arg":
-          nextArgAction = directive.nextArgAction;
-          if (directive.setsExplicitScript) hasExplicitScript = true;
+        case "consume-next":
+          pendingConsumption = directive.role;
+          if (suppliesScript(directive.role)) hasExplicitScript = true;
+          break;
+        case "inline-value":
+          if (directive.role === "script-file")
+            tokens.push({ token: directive.value, effect });
+          if (suppliesScript(directive.role)) hasExplicitScript = true;
           break;
         case "regular-flag":
+          // Unrecognized: fall back to the blind `--opt=value` split, which is
+          // safe precisely because the flag's role is unknown (#645).
+          tokens.push(...embeddedOptionValueToken(text, effect));
           break;
       }
       continue;
@@ -459,17 +610,63 @@ function collectPatternCommandTokens(
 
     // Positional argument.
     if (!hasExplicitScript && positionalsSeen < patternPositionals) {
-      positionalsSeen++;
-      continue; // Skip: this is an inline pattern/script.
+      positionalsSeen++; // Skip: this is an inline pattern/script.
+    } else {
+      tokens.push({ token: text, effect });
     }
-
-    // File argument — collect as path candidate.
-    tokens.push({ token: text, effect });
+    // A quoted flag never reaches the flag branch above, so its embedded value
+    // is split here instead.
+    tokens.push(...embeddedOptionValueToken(text, effect));
   }
 
   return tokens;
 }
 
+/**
+ * Whether a flag in this role means the inline pattern positional is spent.
+ *
+ * `unknown-arity` says so for the opposite reason to the others: not because
+ * the script was supplied, but because the walker cannot tell which word the
+ * script is, and skipping the wrong one drops a real operand.
+ */
+function suppliesScript(role: PatternFlagRole): boolean {
+  return (
+    role === "script" || role === "script-file" || role === "unknown-arity"
+  );
+}
+
+/**
+ * What a pending flag consumption made of the argument node that followed it.
+ *
+ * `consumed` is the flag's own verdict, not the walker's: a `suffix` flag
+ * declines a non-empty argument, which the walker then reads as an ordinary
+ * argument.
+ */
+interface ConsumptionDischarge {
+  readonly consumed: boolean;
+  /** The path candidate the consumed argument contributes, if any. */
+  readonly token?: PathToken;
+}
+
+/** Apply a pending consumption to the argument text that follows its flag. */
+function dischargePendingConsumption(
+  role: PatternFlagRole,
+  text: string,
+  effect: TokenEffect,
+): ConsumptionDischarge {
+  switch (role) {
+    case "script-file":
+      return { consumed: true, token: { token: text, effect } };
+    case "script":
+    case "value":
+      return { consumed: true };
+    case "suffix":
+      return { consumed: text === "" };
+    case "unknown-arity":
+      return { consumed: false };
+  }
+}
+
 /**
  * Collect all argument tokens from a generic (non-pattern-first) command node,
  * skipping the command name and variable assignments.