@gotgenes/pi-permission-system 34.0.0 → 34.0.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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)
 
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "34.0.0",
+  "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,12 +9,14 @@ 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,
@@ -739,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/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,6 +1,7 @@
 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.
@@ -25,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.
@@ -95,7 +109,8 @@ export function redirectMayWriteFile(redirect: TSNode): boolean {
 
 /**
  * The child index of the node `redirect` reads or writes (its first named
- * child after the operator), or `undefined` when it names none (`>&-`).
+ * 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
@@ -104,19 +119,52 @@ export function redirectMayWriteFile(redirect: TSNode): boolean {
  * 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 (#977). An index rather than a node, because a caller iterating
- * the children compares positions rather than wrapper identity.
+ * 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 {
-  let seenOperator = false;
+  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++) {
-    const child = redirect.child(i);
-    if (!child) continue;
-    if (!child.isNamed) {
-      seenOperator = true;
-      continue;
-    }
-    if (seenOperator) return 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;
 }
@@ -141,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

@@ -128,8 +128,10 @@ export function collectCommandTokens(node: TSNode): PathToken[] {
  *
  * 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 belongs to the redirected command (#977).
+ * 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).
@@ -314,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));
   }
@@ -334,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",
 ]);
@@ -372,8 +373,7 @@ 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];

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