@gotgenes/pi-permission-system 33.1.1 → 34.0.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [34.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v34.0.0...pi-permission-system-v34.0.1) (2026-09-26)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate a command whose redirect comes before or inside its words ([cdfea17](https://github.com/gotgenes/pi-packages/commit/cdfea17f9169890d33a50eec447d26bb1d001ebf)), closes [#977](https://github.com/gotgenes/pi-packages/issues/977)
+* **pi-permission-system:** resolve paths after a cd whose redirect precedes its target ([3f62169](https://github.com/gotgenes/pi-packages/commit/3f6216967e4e44dfabe68de18382298c8915a274)), closes [#977](https://github.com/gotgenes/pi-packages/issues/977)
+* **pi-permission-system:** check the words after a mid-command redirect against the command's own rules ([73c41a5](https://github.com/gotgenes/pi-packages/commit/73c41a5ccb6b62b17451a197612983af5a3eb8e7)), closes [#977](https://github.com/gotgenes/pi-packages/issues/977)
+
+### Documentation
+
+* **pi-permission-system:** list downstream packages in README ([629a174](https://github.com/gotgenes/pi-packages/commit/629a174d6d8f2aab9025f1780ae9b24c7557d7eb)), closes [#472](https://github.com/gotgenes/pi-packages/issues/472)
+* **pi-permission-system:** record that a redirect's trailing words are reattached at the parser boundary ([2f72602](https://github.com/gotgenes/pi-packages/commit/2f72602260deb7a84d21eeb50b15fa4d0c38e8e2)), closes [#977](https://github.com/gotgenes/pi-packages/issues/977)
+
+## [34.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.1.1...pi-permission-system-v34.0.0) (2026-09-25)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** **breaking:** check a redirect's target against path rules even when the file does not exist yet ([aa88e23](https://github.com/gotgenes/pi-packages/commit/aa88e23be9d6d994728855000eae95e00e0ca03e)), closes [#609](https://github.com/gotgenes/pi-packages/issues/609)
+
+### Documentation
+
+* **pi-permission-system:** record that a redirect's target is projected by its role ([c709401](https://github.com/gotgenes/pi-packages/commit/c70940154c63bb8d1c0b92ca1ef262ec22215102)), closes [#609](https://github.com/gotgenes/pi-packages/issues/609)
+
 ## [33.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.1.0...pi-permission-system-v33.1.1) (2026-09-24)
 
 

package/README.md

@@ -142,6 +142,16 @@ A subagent's ask is reviewed by the chain of the session serving it, one hop up,
 
 For the full reference — all surfaces, runtime knobs, per-agent overrides, merge semantics, and common recipes — see [docs/configuration.md](docs/configuration.md).
 
+## Downstream packages
+
+These packages build on this extension's seams.
+Each one that registers an authorizer link decides nothing until you name it in `authorizerChain`.
+
+- [`@gotgenes/pi-permission-model-judge`](https://www.npmjs.com/package/@gotgenes/pi-permission-model-judge) (first-party): a deny-first model reviewer that auto-denies mistyped out-of-directory paths.
+- [`pi-permission-classifier`](https://github.com/TacoTakumi/pi-permission-classifier) by [@TacoTakumi](https://github.com/TacoTakumi): an auto-approve mode in which a light model reviews each `ask` and returns allow, deny with a short reason, or defer to you; every failure path defers.
+
+Third-party packages are maintained by their authors; review one before granting it a place in your chain.
+
 ## Upgrading
 
 ### 22.0.0 — project config requires project trust

package/docs/configuration.md

@@ -739,7 +739,7 @@ Quoting is understood, so `ls "$HOME/x"` and `ls $HOME/x` are treated alike.
 
 What the bash projection resolves:
 
-- Absolute, home-relative (`~/`), parent-traversal (`../`), and separator-bearing tokens, plus redirect targets (`> out.txt`) and values embedded in long options (`--file=/tmp/patterns`).
+- Absolute, home-relative (`~/`), parent-traversal (`../`), and separator-bearing tokens, plus redirect targets (`> out.txt`, including a file the redirect creates) and values embedded in long options (`--file=/tmp/patterns`).
 - The plain shell variables `$HOME` / `${HOME}` and `$PWD` / `${PWD}`, so `$HOME/x` is gated exactly as `~/x` and the literal absolute spelling, whether or not the target exists.
 - Relative tokens, against the working directory produced by folding literal current-shell `cd` commands.
 - A bare token (`cat id_rsa`) when it names an existing filesystem entry.
@@ -860,6 +860,9 @@ A tool's identity establishes its direction, and on the bash surface a redirect
 An access whose direction cannot be established consults **both** surfaces and takes the more restrictive answer.
 That is deliberate: an unproven access is never treated as the narrower one.
 
+A redirect's target reaches its surface whether or not the file exists yet, so a `path_write` pattern governs what a command may create through `>`, not only what it may overwrite.
+Only the redirect's literal target counts: a computed one (`> "$OUT"`) is not resolved, as for any other computed path.
+
 A redirect the parser could not make sense of is unproven for the same reason.
 The read-write open `<>` is the clearest case: `tree-sitter-bash` has no node for it, so neither half of the operator can be trusted to describe the whole, and its destination consults both surfaces rather than the one the surviving half would name.
 The rule is about the parse rather than about `<>`, so it also covers a redirect that is itself well-formed but sits beside something the parser could not read: in `cat $(( > out.txt`, the `> out.txt` consults both surfaces too.

package/package.json

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

package/src/access-intent/bash/bash-path-resolver.ts

@@ -9,17 +9,20 @@ import type { PathNormalizer } from "#src/path/path-normalizer";
 import { isSafeSystemPath } from "#src/path/safe-system-paths";
 import { ARG_NODE_TYPES, SKIP_SUBTREE_TYPES } from "./node-text";
 import type { TSNode } from "./parser";
+import { REDIRECT_NODE_TYPES } from "./redirect-analysis";
 import {
   classifyBareTokenCandidate,
   classifyTokenAsPathCandidate,
   classifyTokenAsRuleCandidate,
 } from "./token-classification";
 import {
+  COMMAND_PREFIX_TYPES,
   collectCommandTokens,
   collectPathCandidateTokens,
   collectRedirectTokens,
   extractCommandName,
   type PathToken,
+  type TokenRole,
 } from "./token-collection";
 
 // ── Internal types ───────────────────────────────────────────────────────────
@@ -40,13 +43,14 @@ type EffectiveBase =
 
 /**
  * A path-candidate token paired with the effective working directory projected
- * onto the point in the command stream where it appears, and the effect its
- * position proved.
+ * onto the point in the command stream where it appears, the effect its
+ * position proved, and the role its collector gave it.
  */
 interface PathCandidate {
   readonly token: string;
   readonly base: EffectiveBase;
   readonly effect: TokenEffect;
+  readonly role: TokenRole;
 }
 
 /** A promoted bare token and its resolved path, before an effect is attached. */
@@ -101,9 +105,12 @@ const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
  * decision — so no walk step re-reads the platform or threads the cwd.
  *
  * A bare token that fails both shape gates is admitted when the normalizer's
- * existence probe says it names a real filesystem entry (ADR 0009, #645). The
- * resolver consults no ruleset: candidacy is a filesystem question, and the
- * policy decision belongs to the gates downstream.
+ * existence probe says it names a real filesystem entry (ADR 0009, #645). A
+ * redirect's own target needs neither: its collector proved it names a file,
+ * so its `redirect-destination` role admits it whether or not the file exists
+ * yet (#609). The resolver consults no ruleset: candidacy is a syntax and
+ * filesystem question, and the policy decision belongs to the gates
+ * downstream.
  *
  * Tell-don't-ask: callers hand it a parsed tree and receive the resolved
  * {@link ResolvedBashPaths} slices in one {@link resolve} call; the AST walk,
@@ -448,7 +455,8 @@ export class BashPathResolver {
    * Project the collected candidates into deduplicated external paths.
    *
    * Filters candidates through the strict path classifier
-   * (`classifyTokenAsPathCandidate`), resolves each against its effective working
+   * (`classifyTokenAsPathCandidate`) unless their role already admits them,
+   * resolves each against its effective working
    * directory base, and returns only paths that resolve outside the baked cwd in
    * their lexical (as-typed, normalized but not symlink-resolved) form.
    *
@@ -462,8 +470,10 @@ export class BashPathResolver {
     const seen = new Map<string, number>();
     const externalPaths: BashExternalPath[] = [];
 
-    for (const { token, base, effect } of candidates) {
-      const candidate = classifyTokenAsPathCandidate(token);
+    for (const { token, base, effect, role } of candidates) {
+      const candidate = admittedByRole(role)
+        ? token
+        : classifyTokenAsPathCandidate(token);
       if (!candidate) {
         // A bare token the strict shape gate rejects can still escape the tree
         // through a symlink, so probe it and apply the ordinary boundary
@@ -542,7 +552,8 @@ export class BashPathResolver {
    * Filters candidates through the broad path classifier
    * (`classifyTokenAsRuleCandidate`), falling back to {@link probeBareToken}
    * for a bare token the broad classifier rejects for shape — admitted only
-   * when it names an existing filesystem entry (#645).
+   * when it names an existing filesystem entry (#645). A token its role
+   * admits skips both (#609).
    * On win32 the broad classifier is told to treat a backslash as a path
    * separator, so a backslash-relative token (`dir\file`) is recognized as a
    * rule candidate the same as its forward-slash equivalent (#520); on POSIX
@@ -558,11 +569,10 @@ export class BashPathResolver {
     const seen = new Map<string, number>();
     const result: BashPathRuleCandidate[] = [];
 
-    for (const { token, base, effect } of candidates) {
-      const shaped = classifyTokenAsRuleCandidate(
-        token,
-        this.normalizer.flavor,
-      );
+    for (const { token, base, effect, role } of candidates) {
+      const shaped = admittedByRole(role)
+        ? token
+        : classifyTokenAsRuleCandidate(token, this.normalizer.flavor);
       const probed =
         shaped === null
           ? this.probeBareToken(token, base)
@@ -677,7 +687,18 @@ function tagTokens(
   base: EffectiveBase,
   out: PathCandidate[],
 ): void {
-  for (const { token, effect } of tokens) out.push({ token, base, effect });
+  for (const { token, effect, role } of tokens) {
+    out.push({ token, base, effect, role });
+  }
+}
+
+/**
+ * Whether a candidate's role settles its candidacy, so neither shape gate nor
+ * the existence probe is consulted: a redirect's own target is proven by
+ * syntax to name a file, including one the command is about to create.
+ */
+function admittedByRole(role: TokenRole): boolean {
+  return role === "redirect-destination";
 }
 
 /**
@@ -720,8 +741,9 @@ function cdLiteralTarget(commandNode: TSNode): string | null {
   for (let i = 0; i < commandNode.childCount; i++) {
     const child = commandNode.child(i);
     if (!child) continue;
-    if (child.type === "command_name" || child.type === "variable_assignment")
-      continue;
+    if (COMMAND_PREFIX_TYPES.has(child.type)) continue;
+    // A redirect is not cd's operand, wherever it sits (`2>/dev/null cd a`).
+    if (REDIRECT_NODE_TYPES.has(child.type)) continue;
     if (!child.isNamed) continue;
     // Skip the `--` end-of-flags marker; the next argument is the target.
     if (child.type === "word" && child.text === "--") continue;

package/src/access-intent/bash/command-enumeration.ts

@@ -1,7 +1,8 @@
 import type { BashCommandContext, FloorExemption } from "#src/types";
 import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
-import { parseUnresolvedWithin, type TSNode } from "./parser";
-import { redirectMayWriteFile } from "./redirect-analysis";
+import { parseUnresolvedWithin } from "./parse-health";
+import type { TSNode } from "./parser";
+import { REDIRECT_NODE_TYPES, redirectMayWriteFile } from "./redirect-analysis";
 import {
   type CommandWord,
   classifyWrapperWords,
@@ -414,25 +415,30 @@ function makeUnit(
  * Build the unit for a `command` node, reading its words once to answer all
  * three wrapper questions: whether the unit is floored, what it actually runs,
  * and whether the floor still has a reason to hold.
+ *
+ * The floor question also reads the command's own redirects: one written
+ * before or between the words (`>/tmp/o xargs grep foo`) writes a file as
+ * surely as one on the enclosing statement.
  */
 function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
-  const text = commandUnitText(node);
-  const words = readCommandWords(node);
+  const { text, words } = readCommandUnit(node);
   return makeUnit(text, scope, {
     wrapperKind: classifyWrapperWords(words),
     executedUnit: executedUnitOf(text, words) ?? undefined,
-    floorExemption: isTransparentWrapper(words, scope)
+    floorExemption: isTransparentWrapper(words, redirectedScope(node, scope))
       ? "core-reader"
       : undefined,
   });
 }
 
 /**
- * The scope a `redirected_statement`'s children run under: the enclosing one,
- * plus a write unless every one of its redirects provably only reads.
+ * The scope a node's own children run under: the enclosing one, plus a write
+ * unless every `file_redirect` among its children provably only reads.
  *
- * The redirect belongs to the last element of a pipeline, but it hangs off the
- * whole statement in the parse tree, so every command beneath it is marked.
+ * Asked of a `redirected_statement` and of a `command`, since a redirect may
+ * hang off either. On a statement, the redirect belongs to the last element of
+ * a pipeline, but it hangs off the whole statement in the parse tree, so every
+ * command beneath it is marked.
  * Over-attributing is the fail-closed direction — the flag can only withhold an
  * exemption, never grant one — which is also why the question asked of each
  * redirect is a refusal rather than a proof.
@@ -450,27 +456,75 @@ function redirectedScope(node: TSNode, scope: UnitScope): UnitScope {
 }
 
 /**
- * A `command` node's words — its `command_name` followed by its arguments — each
- * carrying its offset into the unit text `commandUnitText` produces.
+ * A `command` node's unit: the command-pattern text a bash rule is matched
+ * against, and its words (the `command_name` followed by its arguments), each
+ * carrying its offset into that text.
+ *
+ * The text runs from the first word to the last, so it leaves out two kinds of
+ * child that are not words of the command:
  *
- * A leading `variable_assignment` prefix is skipped (matching
- * `commandUnitText`), so offsets are relative to the `command_name`. An empty
- * list means a pure assignment with no `command_name`.
+ * - An env-var prefix (`AWS_PROFILE=prod aws …`, `PGPASSWORD=…`), which is part
+ *   of the `command` node's text but must not defeat a rule that gates the
+ *   underlying command.
+ * - A redirect, wherever it sits (`2>/dev/null git push`, `git <<< x push`).
+ *   Bash accepts one anywhere in a simple command, and its position does not
+ *   change which command runs, so it must not change which rule applies either
+ *   (#977).
+ *
+ * The source between two consecutive words is kept verbatim, so a command with
+ * no hosted redirect keeps its exact spacing and line continuations; where a
+ * redirect sat between two words, one space joins them instead.
+ * A pure assignment (`FOO=bar`, no `command_name`) runs no command, has no
+ * words, and keeps its whole text.
  */
-function readCommandWords(node: TSNode): CommandWord[] {
+function readCommandUnit(node: TSNode): {
+  text: string;
+  words: CommandWord[];
+} {
   const nodes = commandWordNodes(node);
-  const unitStart = nodes.at(0)?.startIndex ?? 0;
-  return nodes.map((child) => ({
-    text: child.text,
-    offset: child.startIndex - unitStart,
-  }));
+  if (nodes.length === 0) return { text: node.text, words: [] };
+
+  const redirects = hostedRedirects(node);
+  const words: CommandWord[] = [];
+  let text = "";
+  let previous: TSNode | undefined;
+  for (const word of nodes) {
+    if (previous) text += gapBetween(node, previous, word, redirects);
+    words.push({ text: word.text, offset: text.length });
+    text += word.text;
+    previous = word;
+  }
+  return { text, words };
+}
+
+/**
+ * The text that joins two consecutive words of a unit: the command's own
+ * source between them, or one space where a hosted redirect sat there.
+ */
+function gapBetween(
+  command: TSNode,
+  before: TSNode,
+  after: TSNode,
+  redirects: readonly TSNode[],
+): string {
+  const hostsRedirect = redirects.some(
+    (redirect) =>
+      redirect.startIndex >= before.endIndex &&
+      redirect.startIndex < after.startIndex,
+  );
+  if (hostsRedirect) return " ";
+  return command.text.slice(
+    before.endIndex - command.startIndex,
+    after.startIndex - command.startIndex,
+  );
 }
 
 /**
- * The nodes {@link readCommandWords} reports words for, in the same order.
+ * The nodes {@link readCommandUnit} reports words for, in the same order: every
+ * named child except a prefix assignment and a hosted redirect.
  *
- * Split out so a consumer that needs a *node* rather than a word — the log's
- * command masker, which offsets a re-parse by the payload node's `startIndex` —
+ * Split out so a consumer that needs a *node* rather than a word (the log's
+ * command masker, which offsets a re-parse by the payload node's `startIndex`)
  * walks the identical filtered list. Two walks over the same children with the
  * same filter, written twice, is how the two come to disagree about which word
  * is at which index.
@@ -481,30 +535,20 @@ function commandWordNodes(node: TSNode): TSNode[] {
     const child = node.child(i);
     if (!child?.isNamed) continue;
     if (child.type === "variable_assignment") continue;
+    if (REDIRECT_NODE_TYPES.has(child.type)) continue;
     nodes.push(child);
   }
   return nodes;
 }
 
-/**
- * The command-pattern text of a `command` node, with any leading
- * `variable_assignment` prefix stripped.
- *
- * An env-var prefix (`AWS_PROFILE=prod aws …`, `PGPASSWORD=…`) is part of the
- * `command` node's text but must not defeat a rule that gates the underlying
- * command, so matching targets the text from the first non-assignment child
- * (the `command_name`) onward, sliced verbatim to preserve spacing. A pure
- * assignment (`FOO=bar`, no `command_name`) runs no command and is returned
- * unchanged.
- */
-function commandUnitText(node: TSNode): string {
+/** The redirects a `command` node hosts among its own children. */
+function hostedRedirects(node: TSNode): TSNode[] {
+  const redirects: TSNode[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (child?.isNamed && child.type !== "variable_assignment") {
-      return node.text.slice(child.startIndex - node.startIndex);
-    }
+    if (child && REDIRECT_NODE_TYPES.has(child.type)) redirects.push(child);
   }
-  return node.text;
+  return redirects;
 }
 
 function descendCommandChildren(

package/src/access-intent/bash/node-text.ts

@@ -27,6 +27,42 @@ export const ARG_NODE_TYPES = new Set([
   "raw_string",
 ]);
 
+/**
+ * Whether an argument node's value is decided at run time: it contains a
+ * command or process substitution, an arithmetic expansion, or a variable
+ * expansion {@link resolvePlainVariableExpansion} cannot resolve.
+ *
+ * The complement of what {@link resolveNodeText} can spell exactly. A plain
+ * `$HOME` / `$PWD` reference resolves, so `"$HOME/out"` is not computed; any
+ * other expansion falls back to its own source text there, which names a file
+ * that is not the one the shell will touch (ADR 0009's computed-path residual).
+ * A single-quoted `'$x'` is a literal.
+ */
+export function hasComputedPart(node: TSNode): boolean {
+  if (COMPUTED_NODE_TYPES.has(node.type)) return true;
+  if (VARIABLE_EXPANSION_TYPES.has(node.type)) {
+    return resolvePlainVariableExpansion(node) === null;
+  }
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && hasComputedPart(child)) return true;
+  }
+  return false;
+}
+
+/** Node types whose value only running the command can produce. */
+const COMPUTED_NODE_TYPES: ReadonlySet<string> = new Set([
+  "command_substitution",
+  "process_substitution",
+  "arithmetic_expansion",
+]);
+
+/** Variable references, computed unless they resolve as a plain reference. */
+const VARIABLE_EXPANSION_TYPES: ReadonlySet<string> = new Set([
+  "simple_expansion",
+  "expansion",
+]);
+
 /**
  * Resolve the "shell value" of an argument node — the string the shell
  * would pass to the command after quote removal.

package/src/access-intent/bash/parse-health.ts

@@ -0,0 +1,72 @@
+import type { TSNode } from "./parser";
+
+/**
+ * Whether `tree-sitter-bash` resolved the syntax it was given: the parse's own
+ * health, as opposed to the structure of a successful parse.
+ *
+ * Kept apart from `parser.ts`, which says where a tree comes from, so that a
+ * module the parser depends on (the redirect-argument correction reads a
+ * redirect through `redirect-analysis.ts`) can still ask these questions
+ * without an import cycle.
+ */
+
+/**
+ * Whether tree-sitter failed to resolve the syntax at `node`.
+ *
+ * Error recovery disposes of text it cannot attach in one of two places, and
+ * which one it picks depends on what follows. The read-write open `<>`, which
+ * `tree-sitter-bash` 0.25.1 has no node for, shows both: `cat <> rw.txt` keeps
+ * the discarded `>` as an `ERROR` *child* of the redirect, while
+ * `cat <> ~/rw.txt` strands the `<` as an `ERROR` *sibling* ahead of a redirect
+ * that is otherwise indistinguishable from a genuine `> ~/rw.txt`. A reader
+ * that consults only the node's own subtree sees the first and not the second.
+ *
+ * The immediate predecessor, rather than the enclosing statement, is what makes
+ * the answer per-redirect: in `cat a > out.txt <> ~/rw.txt` the statement has
+ * an error but its first redirect is a fully resolved write, and condemning it
+ * would forfeit a proof the parse really did establish.
+ *
+ * The question is about the parse, not about `<>`, so the population is wider
+ * than the form that exposed it: `cat $(( > out.txt` and `echo ) > out.txt`
+ * both carry a perfectly good `> out.txt` whose predecessor failed for an
+ * unrelated reason, and both go unproven. That is the accepted cost, and it is
+ * the same shape as the only real occurrence measured across 5000+ logged
+ * commands — `git commit -F - <<'MSG' 2>&1 | tail -4`, valid bash the grammar
+ * cannot parse (ADR 0013's 2026-08-29 amendment), where the demoted token
+ * belongs to no `<>` either. Over-refusing costs a prompt; under-refusing hands
+ * a write to a read grant.
+ *
+ * This module is the one place {@link TSNode.hasError} and
+ * {@link TSNode.previousSibling} are read. Keeping the lateral navigation here
+ * is deliberate: recovering-parser behavior is a fact about tree-sitter rather
+ * than about any construct, so a caller asks this question instead of
+ * hand-rolling a sibling walk of its own.
+ */
+export function parseUnresolvedAt(node: TSNode): boolean {
+  return node.hasError || (node.previousSibling?.hasError ?? false);
+}
+
+/**
+ * Whether tree-sitter failed to resolve the syntax anywhere within `node`.
+ *
+ * The subtree-only question, and the one a walker descending statements asks:
+ * a statement holding an unresolved region is one whose recovered shape is
+ * invented rather than observed, so nothing beneath it is evidence of what
+ * runs. The failure can sit well below the statement that exposes it —
+ * `git commit -F - <<'MSG' 2>&1 | tail -4` strands its `ERROR` under
+ * `heredoc_redirect → file_redirect`, where no command node sees it.
+ *
+ * {@link parseUnresolvedAt} answers the redirect-shaped question instead,
+ * widening to the immediate predecessor because error recovery strands a
+ * discarded operator ahead of the redirect it belonged to. That widening is a
+ * fact about redirects, not about statements: a statement whose *predecessor*
+ * failed is not itself unparsed, and borrowing the wider predicate here would
+ * condemn every statement following a failed one.
+ *
+ * `unresolved-salvage.ts` asks the same question twice over: to locate the
+ * innermost region worth re-parsing, and to refuse the re-parse's own result
+ * when it failed too (#875).
+ */
+export function parseUnresolvedWithin(node: TSNode): boolean {
+  return node.hasError;
+}

package/src/access-intent/bash/parser.ts

@@ -1,13 +1,14 @@
 import { createRequire } from "node:module";
 import { memoizeAsyncWithRetry } from "./async-cache";
+import { reattachRedirectArguments } from "./redirect-arguments";
 
 /**
  * Minimal subset of web-tree-sitter's SyntaxNode used by the AST walker.
  * Defined locally so callers do not need to import web-tree-sitter types.
  *
  * The last two members are the parse's own health, where every other member
- * describes a *successful* parse's structure. They are read only by this
- * module's two `parseUnresolved*` predicates — see their doc comments for why
+ * describes a *successful* parse's structure. They are read only by
+ * `parse-health.ts`'s two `parseUnresolved*` predicates — see their doc comments for why
  * that boundary matters.
  */
 export interface TSNode {
@@ -27,67 +28,6 @@ export interface TSNode {
   child(index: number): TSNode | null;
 }
 
-/**
- * Whether tree-sitter failed to resolve the syntax at `node`.
- *
- * Error recovery disposes of text it cannot attach in one of two places, and
- * which one it picks depends on what follows. The read-write open `<>`, which
- * `tree-sitter-bash` 0.25.1 has no node for, shows both: `cat <> rw.txt` keeps
- * the discarded `>` as an `ERROR` *child* of the redirect, while
- * `cat <> ~/rw.txt` strands the `<` as an `ERROR` *sibling* ahead of a redirect
- * that is otherwise indistinguishable from a genuine `> ~/rw.txt`. A reader
- * that consults only the node's own subtree sees the first and not the second.
- *
- * The immediate predecessor, rather than the enclosing statement, is what makes
- * the answer per-redirect: in `cat a > out.txt <> ~/rw.txt` the statement has
- * an error but its first redirect is a fully resolved write, and condemning it
- * would forfeit a proof the parse really did establish.
- *
- * The question is about the parse, not about `<>`, so the population is wider
- * than the form that exposed it: `cat $(( > out.txt` and `echo ) > out.txt`
- * both carry a perfectly good `> out.txt` whose predecessor failed for an
- * unrelated reason, and both go unproven. That is the accepted cost, and it is
- * the same shape as the only real occurrence measured across 5000+ logged
- * commands — `git commit -F - <<'MSG' 2>&1 | tail -4`, valid bash the grammar
- * cannot parse (ADR 0013's 2026-08-29 amendment), where the demoted token
- * belongs to no `<>` either. Over-refusing costs a prompt; under-refusing hands
- * a write to a read grant.
- *
- * This module is the one place {@link TSNode.hasError} and
- * {@link TSNode.previousSibling} are read. Keeping the lateral navigation here
- * is deliberate: recovering-parser behavior is a fact about tree-sitter rather
- * than about any construct, so a caller asks this question instead of
- * hand-rolling a sibling walk of its own.
- */
-export function parseUnresolvedAt(node: TSNode): boolean {
-  return node.hasError || (node.previousSibling?.hasError ?? false);
-}
-
-/**
- * Whether tree-sitter failed to resolve the syntax anywhere within `node`.
- *
- * The subtree-only question, and the one a walker descending statements asks:
- * a statement holding an unresolved region is one whose recovered shape is
- * invented rather than observed, so nothing beneath it is evidence of what
- * runs. The failure can sit well below the statement that exposes it —
- * `git commit -F - <<'MSG' 2>&1 | tail -4` strands its `ERROR` under
- * `heredoc_redirect → file_redirect`, where no command node sees it.
- *
- * {@link parseUnresolvedAt} answers the redirect-shaped question instead,
- * widening to the immediate predecessor because error recovery strands a
- * discarded operator ahead of the redirect it belonged to. That widening is a
- * fact about redirects, not about statements: a statement whose *predecessor*
- * failed is not itself unparsed, and borrowing the wider predicate here would
- * condemn every statement following a failed one.
- *
- * `unresolved-salvage.ts` asks the same question twice over: to locate the
- * innermost region worth re-parsing, and to refuse the re-parse's own result
- * when it failed too (#875).
- */
-export function parseUnresolvedWithin(node: TSNode): boolean {
-  return node.hasError;
-}
-
 /**
  * The one parse capability a consumer needs to re-parse a fragment of a
  * command on its own.
@@ -125,7 +65,46 @@ async function initParser(): Promise<TSParser> {
 // Memoize on success but drop a rejected result so a transient init failure
 // (e.g. a slow WASM load) is retried on the next tool call instead of poisoning
 // the parser for the process lifetime.
-export const getParser = memoizeAsyncWithRetry(initParser);
+
+/**
+ * The parser every consumer reads the bash grammar through.
+ *
+ * Its trees are the grammar's with one correction applied where they enter the
+ * package: a word `tree-sitter-bash` hung on a redirect is handed back to the
+ * command it belongs to (`reattachRedirectArguments`, #977). Every walker, the
+ * salvage re-parse, and the log masker read that corrected tree, so none of
+ * them has to learn the grammar's quirk on its own.
+ */
+export const getParser = memoizeAsyncWithRetry(async () =>
+  correctingParser(await getGrammarParser()),
+);
+
+function correctingParser(grammar: TSParser): TSParser {
+  return {
+    parse: (input) => {
+      const tree = grammar.parse(input);
+      if (!tree) return null;
+      return {
+        rootNode: reattachRedirectArguments(tree.rootNode),
+        delete: () => {
+          tree.delete();
+        },
+      };
+    },
+    delete: () => {
+      grammar.delete();
+    },
+  };
+}
+
+/**
+ * `tree-sitter-bash`'s own parser, whose trees are exactly what the grammar
+ * produced.
+ *
+ * Production code reads {@link getParser}; this one exists so a test whose
+ * subject is the grammar's own shape can still see it.
+ */
+export const getGrammarParser = memoizeAsyncWithRetry(initParser);
 
 // Resolved parser cached for synchronous access after warm-up. The tree-sitter
 // parser is stateless (parse is a pure function of its input), so caching it at

package/src/access-intent/bash/redirect-analysis.ts

@@ -1,14 +1,16 @@
 import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
 import { redirectDestinationEffect } from "./command-effects";
-import { parseUnresolvedAt, type TSNode } from "./parser";
+import { parseUnresolvedAt } from "./parse-health";
+import type { TSNode } from "./parser";
 
 /**
  * What a redirect node in the parse tree proves.
  *
  * `command-effects.ts` owns the operator *table* — which spelling means read,
  * which means write — and this module owns reading a `file_redirect` node well
- * enough to consult it: finding the operator among the node's children, and
- * telling a destination that names a file from one that names a descriptor.
+ * enough to consult it: finding the operator among the node's children,
+ * telling a destination that names a file from one that names a descriptor,
+ * and naming which destination is the redirect's own target.
  *
  * The split exists because two callers need different answers from the same
  * read, and — importantly — they need them under different burdens of proof.
@@ -24,6 +26,19 @@ import { parseUnresolvedAt, type TSNode } from "./parser";
  * (#814).
  */
 
+/**
+ * The redirect node types a `command` or a statement can host.
+ *
+ * A redirect is not a word of the command it sits in, wherever it sits: bash
+ * accepts one before, between, or after the words (`2>/dev/null git push`), and
+ * none of them changes which command runs (#977).
+ */
+export const REDIRECT_NODE_TYPES: ReadonlySet<string> = new Set([
+  "file_redirect",
+  "herestring_redirect",
+  "heredoc_redirect",
+]);
+
 /**
  * The effect `redirect` proves for `destination`, or `null` when the redirect
  * names no file and no token should be collected.
@@ -92,6 +107,68 @@ export function redirectMayWriteFile(redirect: TSNode): boolean {
   return false;
 }
 
+/**
+ * The child index of the node `redirect` reads or writes (its first named
+ * child after the operator), or `undefined` when it names none: nothing
+ * follows the operator, or the operator closes a descriptor (`>&-`, `<&-`).
+ *
+ * The operator is the redirect's only unnamed child, and a source descriptor
+ * (`2` in `2>`) precedes it, so the first named child after it is the
+ * target without asking its type.
+ *
+ * Only the first: tree-sitter-bash 0.25.1 declares the destination
+ * `repeat1`, so the words after it in `grep pat 2>/dev/null f.txt` parse as
+ * further destinations, while bash passes them to the redirected command as
+ * arguments ({@link trailingArgumentIndex} names where they begin, #977). A
+ * close operator takes an optional destination in the grammar, but it closes a
+ * descriptor and names no file, so a word after it is the command's too. An
+ * index rather than a node, because a caller iterating the children compares
+ * positions rather than wrapper identity.
+ */
+export function redirectTargetIndex(redirect: TSNode): number | undefined {
+  const operator = redirectOperatorIndex(redirect);
+  if (operator === undefined) return undefined;
+  if (CLOSE_OPERATORS.has(redirect.child(operator)?.type ?? "")) {
+    return undefined;
+  }
+  return namedChildIndexAfter(redirect, operator);
+}
+
+/**
+ * The child index of the first word the grammar appended after `redirect`'s
+ * own target, or `undefined` when none follows.
+ *
+ * Every named child from there on is a word bash passes to the redirected
+ * command rather than a destination of the redirect: `f.txt` in
+ * `grep pat 2>/dev/null f.txt`, and `arg` in `cmd >&- arg`, where the close
+ * operator has no target at all (#977).
+ */
+export function trailingArgumentIndex(redirect: TSNode): number | undefined {
+  const operator = redirectOperatorIndex(redirect);
+  if (operator === undefined) return undefined;
+  const target = redirectTargetIndex(redirect);
+  return namedChildIndexAfter(redirect, target ?? operator);
+}
+
+/** Operators that close a descriptor, naming no file (`>&-`, `<&-`). */
+const CLOSE_OPERATORS: ReadonlySet<string> = new Set([">&-", "<&-"]);
+
+/** The index of `redirect`'s operator, its only unnamed child. */
+function redirectOperatorIndex(redirect: TSNode): number | undefined {
+  for (let i = 0; i < redirect.childCount; i++) {
+    if (redirect.child(i)?.isNamed === false) return i;
+  }
+  return undefined;
+}
+
+/** The index of the first named child of `node` after index `after`. */
+function namedChildIndexAfter(node: TSNode, after: number): number | undefined {
+  for (let i = after + 1; i < node.childCount; i++) {
+    if (node.child(i)?.isNamed) return i;
+  }
+  return undefined;
+}
+
 /**
  * Destination node types that name a file descriptor rather than a file, so
  * `>&` / `<&` duplicate a stream instead of touching the filesystem.
@@ -112,9 +189,6 @@ const DESCRIPTOR_NODE_TYPES: ReadonlySet<string> = new Set([
  * syntax proof is a lookup on the first one found.
  */
 function redirectOperatorOf(node: TSNode): string {
-  for (let i = 0; i < node.childCount; i++) {
-    const child = node.child(i);
-    if (child && !child.isNamed) return child.type;
-  }
-  return "";
+  const operator = redirectOperatorIndex(node);
+  return operator === undefined ? "" : (node.child(operator)?.type ?? "");
 }

package/src/access-intent/bash/redirect-arguments.ts

@@ -0,0 +1,285 @@
+import { parseUnresolvedWithin } from "./parse-health";
+import type { TSNode } from "./parser";
+import { trailingArgumentIndex } from "./redirect-analysis";
+
+/**
+ * `tree-sitter-bash`'s parse with each word it hung on a redirect handed back
+ * to the command it belongs to.
+ *
+ * The grammar (0.25.1) declares a file redirect's destination `repeat1`, so in
+ * `git 2>/dev/null push --force` the words `push --force` parse as further
+ * destinations of the statement's redirect, where bash passes them to `git`
+ * (tree-sitter/tree-sitter-bash#233). Every consumer of the parse (the command
+ * enumerator, the path walkers, the effect proofs, the log masker) would
+ * otherwise have to learn that quirk on its own, so it is corrected once, here,
+ * where the tree enters the package (#977).
+ *
+ * The corrected shape is the one the grammar already produces for a redirect
+ * written before the command: the redirect becomes a child of the `command`,
+ * between its words. Every redirect from the body up to the last one carrying
+ * words moves into the command, each truncated after its own target and
+ * followed by its words; a redirect after the last word stays at the
+ * statement, and a statement left with no redirect gives way to its body.
+ *
+ * Three kinds of statement are left exactly as the grammar produced them:
+ *
+ * - One whose parse failed. Its units are floored already, and moving a word
+ *   out of an unresolvable redirect would hand it the command's effect proof in
+ *   place of the redirect's refusal to prove one (#814).
+ * - One whose body is not a command (`{ a; } 2>/dev/null b`), which bash
+ *   rejects as a syntax error, so nothing runs.
+ * - One with no words after any redirect's target, which is almost every one.
+ *
+ * Returns `root` itself when nothing in the tree needs correcting. A corrected
+ * node reads its offsets and text from the source, so `startIndex`/`endIndex`
+ * stay positions in the command string every caller already slices.
+ */
+export function reattachRedirectArguments(root: TSNode): TSNode {
+  return correct(root) ?? root;
+}
+
+/** The corrected node, or `undefined` when nothing beneath `node` changed. */
+function correct(node: TSNode): TSNode | undefined {
+  const children: TSNode[] = [];
+  let changed = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    const corrected = correct(child);
+    if (corrected) changed = true;
+    children.push(corrected ?? child);
+  }
+
+  if (node.type === "redirected_statement" && !parseUnresolvedWithin(node)) {
+    const reattached = reattachStatement(node, children);
+    if (reattached) return reattached;
+  }
+  return changed
+    ? adoptingView(node, children, parseUnresolvedWithin(node))
+    : undefined;
+}
+
+/**
+ * Move the words the grammar hung on `statement`'s redirects into the command
+ * they belong to, or `undefined` when there are none or no command to take
+ * them. `children` are the statement's children, already corrected.
+ */
+function reattachStatement(
+  statement: TSNode,
+  children: readonly TSNode[],
+): TSNode | undefined {
+  const bodyIndex = children.findIndex((child) => child.isNamed);
+  const body = children.at(bodyIndex);
+  if (!body || !reachesCommand(body)) return undefined;
+
+  const lastCarrier = children.findLastIndex(
+    (child) =>
+      child.type === "file_redirect" &&
+      trailingArgumentIndex(child) !== undefined,
+  );
+  if (lastCarrier === -1) return undefined;
+
+  const source = sourceOf(statement);
+  const moved = children
+    .slice(bodyIndex + 1, lastCarrier + 1)
+    .flatMap((child) => splitRedirect(child, source));
+  const newBody = appendToRightmostCommand(body, moved, source);
+  const rest = children.slice(lastCarrier + 1);
+  if (!rest.some((child) => child.isNamed)) return newBody;
+  return rewrittenNode(
+    statement,
+    [...children.slice(0, bodyIndex), newBody, ...rest],
+    statement.startIndex,
+    statement.endIndex,
+    source,
+  );
+}
+
+/**
+ * Whether the words after a redirect on `body` belong to a command: `body` is
+ * one, or is a `list` or `pipeline` whose last element reaches one. The grammar
+ * hangs a redirect on the last command of `cd a && git 2>/dev/null push` or
+ * `rg x | xargs ls 2>&1 ~/x` off the whole list or pipeline, while bash gives
+ * it, and its words, to that last command.
+ */
+function reachesCommand(body: TSNode): boolean {
+  if (body.type === "command") return true;
+  if (!GROUPING_TYPES.has(body.type)) return false;
+  const last = lastNamedChild(body);
+  return last !== undefined && reachesCommand(last);
+}
+
+/** The bodies whose last element a statement-level redirect belongs to. */
+const GROUPING_TYPES: ReadonlySet<string> = new Set(["list", "pipeline"]);
+
+/**
+ * `redirect` as it belongs in the command: truncated after its own target and
+ * followed by the words the grammar appended to it. A redirect carrying no
+ * words, or a node that is not a file redirect, moves as it is.
+ */
+function splitRedirect(redirect: TSNode, source: Source): TSNode[] {
+  const trailing =
+    redirect.type === "file_redirect"
+      ? trailingArgumentIndex(redirect)
+      : undefined;
+  if (trailing === undefined) return [redirect];
+
+  const kept: TSNode[] = [];
+  const words: TSNode[] = [];
+  for (let i = 0; i < redirect.childCount; i++) {
+    const child = redirect.child(i);
+    if (child) (i < trailing ? kept : words).push(child);
+  }
+  const end = kept.at(-1)?.endIndex ?? redirect.startIndex;
+  return [
+    rewrittenNode(redirect, kept, redirect.startIndex, end, source),
+    ...words,
+  ];
+}
+
+/**
+ * `body` with `moved` appended to its rightmost command: the command itself,
+ * or the last element of a `list` or `pipeline`, recursively. Each node on the way grows to
+ * the end of the last moved node.
+ */
+function appendToRightmostCommand(
+  body: TSNode,
+  moved: readonly TSNode[],
+  source: Source,
+): TSNode {
+  const children = childrenOf(body);
+  const end = moved.at(-1)?.endIndex ?? body.endIndex;
+  if (body.type === "command") {
+    return rewrittenNode(
+      body,
+      [...children, ...moved],
+      body.startIndex,
+      end,
+      source,
+    );
+  }
+  const lastIndex = children.findLastIndex((child) => child.isNamed);
+  const last = children[lastIndex];
+  const replaced = children.with(
+    lastIndex,
+    appendToRightmostCommand(last, moved, source),
+  );
+  return rewrittenNode(body, replaced, body.startIndex, end, source);
+}
+
+/** A node the correction built, reading its text from the statement's source. */
+function rewrittenNode(
+  original: TSNode,
+  children: readonly TSNode[],
+  startIndex: number,
+  endIndex: number,
+  source: Source,
+): TSNode {
+  return adoptingView(
+    {
+      type: original.type,
+      isNamed: original.isNamed,
+      startIndex,
+      endIndex,
+      text: source(startIndex, endIndex),
+    },
+    children,
+    false,
+  );
+}
+
+/**
+ * A view whose children are views too, so each one's `previousSibling` is its
+ * neighbor in the corrected tree rather than the one the grammar gave it.
+ */
+function adoptingView(
+  fields: NodeFields,
+  children: readonly TSNode[],
+  hasError: boolean,
+): TSNode {
+  return new NodeView(fields, children.map(asView), hasError);
+}
+
+/** A slice of the command by absolute offsets. */
+type Source = (startIndex: number, endIndex: number) => string;
+
+/** The source slicer for every node within `statement`. */
+function sourceOf(statement: TSNode): Source {
+  return (startIndex, endIndex) =>
+    statement.text.slice(
+      startIndex - statement.startIndex,
+      endIndex - statement.startIndex,
+    );
+}
+
+function childrenOf(node: TSNode): TSNode[] {
+  const children: TSNode[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) children.push(child);
+  }
+  return children;
+}
+
+function lastNamedChild(node: TSNode): TSNode | undefined {
+  return childrenOf(node).findLast((child) => child.isNamed);
+}
+
+/**
+ * `node` as a view, so a new parent can give it a new previous sibling.
+ *
+ * Its own children stay the grammar's nodes: nothing beneath it moved, so their
+ * siblings are still the grammar's too.
+ */
+function asView(node: TSNode): TSNode {
+  return node instanceof NodeView
+    ? node
+    : new NodeView(node, childrenOf(node), parseUnresolvedWithin(node));
+}
+
+/** The fields a {@link NodeView} copies from the node it stands for. */
+interface NodeFields {
+  readonly type: string;
+  readonly isNamed: boolean;
+  readonly startIndex: number;
+  readonly endIndex: number;
+  readonly text: string;
+}
+
+/**
+ * A parse-tree node the correction presents in place of the grammar's.
+ *
+ * Adopting its children sets each view child's `previousSibling` to the child
+ * before it, which is what lets a redirect moved into a command ask
+ * `parseUnresolvedAt` about its new neighbor.
+ */
+class NodeView implements TSNode {
+  readonly type: string;
+  readonly isNamed: boolean;
+  readonly startIndex: number;
+  readonly endIndex: number;
+  readonly text: string;
+  readonly childCount: number;
+  previousSibling: TSNode | null = null;
+
+  constructor(
+    fields: NodeFields,
+    private readonly children: readonly TSNode[],
+    readonly hasError: boolean,
+  ) {
+    this.type = fields.type;
+    this.isNamed = fields.isNamed;
+    this.startIndex = fields.startIndex;
+    this.endIndex = fields.endIndex;
+    this.text = fields.text;
+    this.childCount = children.length;
+    children.forEach((child, i) => {
+      if (child instanceof NodeView)
+        child.previousSibling = children[i - 1] ?? null;
+    });
+  }
+
+  child(index: number): TSNode | null {
+    return this.children[index] ?? null;
+  }
+}

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

@@ -4,14 +4,31 @@ import { proveCommandEffect } from "./command-effects";
 import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
 import {
   ARG_NODE_TYPES,
+  hasComputedPart,
   resolveNodeText,
   SKIP_SUBTREE_TYPES,
 } from "./node-text";
 import type { TSNode } from "./parser";
-import { redirectEffectForDestination } from "./redirect-analysis";
+import {
+  redirectEffectForDestination,
+  redirectTargetIndex,
+} from "./redirect-analysis";
+
+/**
+ * What a collected token is, as the collector that produced it established.
+ *
+ * The role decides candidacy and the effect decides direction; both are
+ * stamped at the same site and never re-derived downstream.
+ */
+export type TokenRole =
+  /** An operand of unknown path-hood: shape and the existence probe decide. */
+  | "operand"
+  /** A redirect's own target, which the syntax proves names a file. */
+  | "redirect-destination";
 
 /**
- * A collected path-candidate token paired with the effect its position proved.
+ * A collected path-candidate token paired with the effect its position proved
+ * and the role its collector gave it.
  *
  * The pairing is made where the token is *produced*, never by mapping a whole
  * result: a nested execution's tokens carry their own command's attribution
@@ -20,6 +37,7 @@ import { redirectEffectForDestination } from "./redirect-analysis";
 export interface PathToken {
   readonly token: string;
   readonly effect: TokenEffect;
+  readonly role: TokenRole;
 }
 
 // ── Public surface ─────────────────────────────────────────────────────────
@@ -108,23 +126,57 @@ export function collectCommandTokens(node: TSNode): PathToken[] {
  * in front of it is. A destination the operator names as a file descriptor
  * (`2>&1`) contributes no token at all.
  *
+ * The redirect's own target carries the `redirect-destination` role when the
+ * syntax proves it names a file, so the projection admits it whether or not
+ * the file exists yet (#609). Every other child is an `operand`. A word the
+ * grammar appends after the target reaches here only in a statement whose parse
+ * failed: everywhere else `getParser` has already handed it back to the command
+ * it belongs to (#977).
+ *
  * Reading the redirect node itself belongs to `redirect-analysis.ts`, which
  * the command enumerator consults for the same fact (#803).
  */
 export function collectRedirectTokens(node: TSNode): PathToken[] {
+  const target = redirectTargetIndex(node);
   const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
     if (ARG_NODE_TYPES.has(child.type)) {
       const effect = redirectEffectForDestination(node, child);
-      if (effect) tokens.push({ token: resolveNodeText(child), effect });
+      if (effect) {
+        const token = resolveNodeText(child);
+        const role: TokenRole =
+          i === target && provesTarget(effect, child, token)
+            ? "redirect-destination"
+            : "operand";
+        tokens.push({ token, effect, role });
+      }
     }
     tokens.push(...collectHostedExecutionTokens(child));
   }
   return tokens;
 }
 
+/**
+ * Whether a redirect's target is proven to name this literal file.
+ *
+ * The operator must have proved an effect: a redirect the parse could not
+ * resolve proves nothing (#814). The value must be literal: a computed one
+ * names a file only running the command decides (ADR 0009's computed-path
+ * residual). And it must be non-empty, since bash refuses `> ""` rather than
+ * writing anything.
+ */
+function provesTarget(
+  effect: TokenEffect,
+  destination: TSNode,
+  token: string,
+): boolean {
+  return (
+    effect.source === "syntax" && !hasComputedPart(destination) && token !== ""
+  );
+}
+
 /**
  * Collect the path-candidate tokens of every command nested inside `node`'s
  * execution contexts, reading none of the host subtree's own text.
@@ -204,7 +256,11 @@ function collectStatementOperandTokens(
       tokens.push(...collectPathCandidateTokens(child));
       continue;
     }
-    tokens.push({ token: resolveNodeText(child), effect: UNPROVEN_EFFECT });
+    tokens.push({
+      token: resolveNodeText(child),
+      effect: UNPROVEN_EFFECT,
+      role: "operand",
+    });
     tokens.push(...collectHostedExecutionTokens(child));
   }
   return tokens;
@@ -260,8 +316,7 @@ function commandArgumentWords(node: TSNode): string[] {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
-    if (child.type === "command_name" || child.type === "variable_assignment")
-      continue;
+    if (COMMAND_PREFIX_TYPES.has(child.type)) continue;
     if (!ARG_NODE_TYPES.has(child.type)) continue;
     words.push(resolveNodeText(child));
   }
@@ -280,7 +335,7 @@ function commandArgumentWords(node: TSNode): string[] {
  * different state machines and so each carry their own skip, which is why the
  * question is named here once rather than spelled twice (#742).
  */
-const COMMAND_PREFIX_TYPES: ReadonlySet<string> = new Set([
+export const COMMAND_PREFIX_TYPES: ReadonlySet<string> = new Set([
   "command_name",
   "variable_assignment",
 ]);
@@ -318,12 +373,13 @@ function collectEmbeddedOptionValues(
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
-    if (child.type === "command_name" || child.type === "variable_assignment")
-      continue;
+    if (COMMAND_PREFIX_TYPES.has(child.type)) continue;
     if (!ARG_NODE_TYPES.has(child.type)) continue;
 
     const value = OPTION_VALUE_PATTERN.exec(resolveNodeText(child))?.[1];
-    if (value !== undefined) values.push({ token: value, effect });
+    if (value !== undefined) {
+      values.push({ token: value, effect, role: "operand" });
+    }
   }
   return values;
 }
@@ -334,7 +390,7 @@ function embeddedOptionValueToken(
   effect: TokenEffect,
 ): PathToken[] {
   const value = OPTION_VALUE_PATTERN.exec(text)?.[1];
-  return value === undefined ? [] : [{ token: value, effect }];
+  return value === undefined ? [] : [{ token: value, effect, role: "operand" }];
 }
 
 /**
@@ -802,7 +858,11 @@ function collectPatternCommandTokens(
             break;
           case "inline-value":
             if (directive.role === "script-file")
-              tokens.push({ token: directive.value, effect });
+              tokens.push({
+                token: directive.value,
+                effect,
+                role: "operand",
+              });
             if (suppliesScript(directive.role)) hasExplicitScript = true;
             break;
           case "regular-flag":
@@ -819,7 +879,7 @@ function collectPatternCommandTokens(
     if (!hasExplicitScript && positionalsSeen < patternPositionals) {
       positionalsSeen++; // Skip: this is an inline pattern/script.
     } else {
-      tokens.push({ token: text, effect });
+      tokens.push({ token: text, effect, role: "operand" });
     }
     // A quoted token that did not act as a flag above has its embedded value
     // split here instead.
@@ -874,7 +934,10 @@ function dischargePendingConsumption(
 ): ConsumptionDischarge {
   switch (role) {
     case "script-file":
-      return { consumed: true, token: { token: text, effect } };
+      return {
+        consumed: true,
+        token: { token: text, effect, role: "operand" },
+      };
     case "script":
     case "value":
       return { consumed: true };
@@ -923,7 +986,7 @@ function collectGenericCommandTokens(
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push({ token: resolveNodeText(child), effect });
+      tokens.push({ token: resolveNodeText(child), effect, role: "operand" });
       continue;
     }
 

package/src/access-intent/bash/unresolved-salvage.ts

@@ -1,8 +1,5 @@
-import {
-  type BashReparser,
-  parseUnresolvedWithin,
-  type TSNode,
-} from "./parser";
+import { parseUnresolvedWithin } from "./parse-health";
+import type { BashReparser, TSNode } from "./parser";
 
 /**
  * Run `use` over the roots of every region the primary parse could not resolve