@gotgenes/pi-permission-system 30.2.0 → 31.0.1

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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).
 
+## [31.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.0.0...pi-permission-system-v31.0.1) (2026-09-03)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** consult both path directions for a redirect the parser could not resolve ([0327feb](https://github.com/gotgenes/pi-packages/commit/0327feb9d2cefc47fcebe724ee94cf9949a8749a)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+
+### Documentation
+
+* **pi-permission-system:** commit the instrument behind the unresolved-redirect measurement ([757affe](https://github.com/gotgenes/pi-packages/commit/757affeac19400bf7764c9f06fa58bf18ccafc1e)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+* **pi-permission-system:** mark Phase 14 Step 12 complete ([07d23ef](https://github.com/gotgenes/pi-packages/commit/07d23ef6cffb954058ff2f8fe43917a937de437f)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+* **pi-permission-system:** register the unresolved-redirect measurement script ([8203898](https://github.com/gotgenes/pi-packages/commit/8203898bd2dadb62ae72e5bedb579bbaf062cf03)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+* **pi-permission-system:** state the unresolved-redirect residual as a parse fact ([e74c2fc](https://github.com/gotgenes/pi-packages/commit/e74c2fc3c63bf4a18b63334e1fb9b24565fb36b2)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+* **pi-permission-system:** describe the unresolvable-redirect rule as users meet it ([9e57a90](https://github.com/gotgenes/pi-packages/commit/9e57a909e7719fbfa670ad3ec153e5aa2faf1510)), closes [#814](https://github.com/gotgenes/pi-packages/issues/814)
+
+## [31.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.2.0...pi-permission-system-v31.0.0) (2026-09-02)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** **breaking:** gate a path named as a for or select loop operand ([6189d81](https://github.com/gotgenes/pi-packages/commit/6189d81dc48a26d572bacb91a1b2e7c062634ad9)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** **breaking:** gate a path named as a case subject ([dfd2f8d](https://github.com/gotgenes/pi-packages/commit/dfd2f8d682c39dcfe6a903cdeadde18b08a7cc60)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+
+### Documentation
+
+* **pi-permission-system:** commit the instrument behind the statement-operand measurement ([6a708b7](https://github.com/gotgenes/pi-packages/commit/6a708b716f038bf192875a0166ae6a6ab012c3d8)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** register the statement-operand measurement script ([e3e8799](https://github.com/gotgenes/pi-packages/commit/e3e879935c6f395d4b2387a6e30e0791bb8fb765)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** correct the drift note in the operand measurement ([e300934](https://github.com/gotgenes/pi-packages/commit/e300934c0aad34b3bfd127695219250ca6f4613f)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+
 ## [30.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.1.0...pi-permission-system-v30.2.0) (2026-09-02)
 
 

package/docs/configuration.md

@@ -766,6 +766,11 @@ 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 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.
+That is deliberate — a command nobody could parse is the last place to assume a file is only being read — and it does not reach past the neighbour, so a redirect in a later statement keeps its proof.
+
 Attribution is per **token**, not per command, so one invocation can do both: in `cat notes.md > /backup/notes.md`, `notes.md` is a read and `/backup/notes.md` is a write.
 A redirect operator's proof is absolute — it overrides whatever the command in front of it proved, because `> out.txt` writes `out.txt` however read-only that command is.
 When the same path is reached twice with disagreeing directions (`cat a.txt > a.txt`), the two fold to unproven, which consults both surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "30.2.0",
+  "version": "31.0.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -91,6 +91,8 @@
     "verify:public-types": "bash scripts/verify-public-types.sh",
     "measure:core-coverage": "node scripts/measure-core-coverage.mjs",
     "measure:statement-descent": "node scripts/measure-statement-descent.mjs",
+    "measure:statement-operands": "node scripts/measure-statement-operands.mjs",
+    "measure:unresolved-redirects": "node scripts/measure-unresolved-redirects.mjs",
     "measure:wrapper-transparency": "node scripts/measure-wrapper-transparency.mjs",
     "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && eslint . && pnpm run lint:md"

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

@@ -4,6 +4,11 @@ import { memoizeAsyncWithRetry } from "#src/async-cache";
 /**
  * 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, which every other member
+ * describes a *successful* parse's structure. They exist for
+ * {@link parseUnresolvedAt} and are read nowhere else — see its doc comment for
+ * why that boundary matters.
  */
 export interface TSNode {
   readonly type: string;
@@ -13,9 +18,49 @@ export interface TSNode {
   readonly childCount: number;
   /** False for anonymous tokens (operators, delimiters); true for named nodes. */
   readonly isNamed: boolean;
+  /** True when this node is an error or missing token, or contains one. */
+  readonly hasError: boolean;
+  /** The node immediately before this one under the same parent, named or not. */
+  readonly previousSibling: TSNode | null;
   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 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);
+}
+
 /**
  * Minimal subset of web-tree-sitter's Parser used by this module.
  */

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

@@ -1,6 +1,6 @@
 import { redirectDestinationEffect } from "#src/access-intent/bash/command-effects";
-import type { TSNode } from "#src/access-intent/bash/parser";
-import type { TokenEffect } from "#src/access-intent/effect";
+import { parseUnresolvedAt, type TSNode } from "#src/access-intent/bash/parser";
+import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
 
 /**
  * What a redirect node in the parse tree proves.
@@ -17,6 +17,11 @@ import type { TokenEffect } from "#src/access-intent/effect";
  * whether it is safe to *remove* the wrapper floor, so it answers with a
  * refusal: anything it cannot resolve counts against the exemption (#803).
  * One reader of the node keeps the two from drifting on what a redirect is.
+ *
+ * The two burdens meet at one fact: whether the parse resolved at all. Both
+ * answers ask `parseUnresolvedAt`, so a syntax form the grammar could not
+ * handle cannot be a proof to one caller and a resolvable read to the other
+ * (#814).
  */
 
 /**
@@ -26,15 +31,28 @@ import type { TokenEffect } from "#src/access-intent/effect";
  * `>&` and `<&` are the two operators that may name either a file descriptor
  * (`2>&1`) or a real file (`cmd >& out`); the destination node's type is the
  * parse-tree fact that tells them apart.
+ *
+ * A redirect the parse could not resolve proves nothing — ADR 0013 §10's base
+ * case, which consults both directional surfaces. Reading a proof off whichever
+ * operator survived error recovery made `cat <> rw.txt` a read and
+ * `cat <> ~/rw.txt` a write, so one command's answer was a function of its
+ * filename, and the read half was a fail-open on a destination the shell may
+ * truncate (#814).
+ *
+ * The demotion applies to a *proof*, never to the `null`: a descriptor
+ * duplication names no file whatever the operator around it did, so demoting
+ * first would emit a descriptor number as a path candidate.
  */
 export function redirectEffectForDestination(
   redirect: TSNode,
   destination: TSNode,
 ): TokenEffect | null {
-  return redirectDestinationEffect(
+  const proven = redirectDestinationEffect(
     redirectOperatorOf(redirect),
     DESCRIPTOR_NODE_TYPES.has(destination.type),
   );
+  if (proven === null) return null;
+  return parseUnresolvedAt(redirect) ? UNPROVEN_EFFECT : proven;
 }
 
 /**
@@ -49,20 +67,24 @@ export function redirectEffectForDestination(
  * shapes least visible to every other surface — the path projection does not
  * collect them either (#609).
  *
- * Only two things clear it: a descriptor duplication (`2>&1`), which names no
- * file, and an operator that proves a read — reading a file alongside a pure
- * reader leaves it a pure reader.
+ * An unresolved parse is refused up front rather than left to the loop. The
+ * loop would usually reach the same answer — a demoted destination is unproven,
+ * which is not a read — but `cat <>&1` parses to a redirect whose only children
+ * are the operator and a descriptor, so the loop finds nothing to refuse on and
+ * clears the exemption for a form nobody understood (#814).
+ *
+ * Past that, only two things clear it: a descriptor duplication (`2>&1`), which
+ * names no file, and an operator that proves a read — reading a file alongside
+ * a pure reader leaves it a pure reader.
  */
 export function redirectMayWriteFile(redirect: TSNode): boolean {
+  if (parseUnresolvedAt(redirect)) return true;
   for (let i = 0; i < redirect.childCount; i++) {
     const child = redirect.child(i);
     // The operator itself is the redirect's only unnamed child.
     if (!child?.isNamed) continue;
     // A source or duplicated descriptor (`2`, `&1`) names no file.
     if (DESCRIPTOR_NODE_TYPES.has(child.type)) continue;
-    // A shape the grammar could not resolve (`<>` degrades to one) says nothing
-    // about direction, so it cannot clear the check.
-    if (child.type === "ERROR") return true;
     if (redirectEffectForDestination(redirect, child)?.effect !== "read") {
       return true;
     }

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

@@ -11,7 +11,7 @@ import {
 } from "#src/access-intent/bash/node-text";
 import type { TSNode } from "#src/access-intent/bash/parser";
 import { redirectEffectForDestination } from "#src/access-intent/bash/redirect-analysis";
-import type { TokenEffect } from "#src/access-intent/effect";
+import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
 
 /**
  * A collected path-candidate token paired with the effect its position proved.
@@ -29,7 +29,8 @@ export interface PathToken {
 
 /**
  * Recursively visit the AST and collect resolved text of nodes that
- * represent command arguments or redirect destinations.
+ * represent command arguments, redirect destinations, or a statement's own
+ * path operands.
  *
  * Reads no text from `heredoc_body`, `heredoc_end`, or `comment` subtrees, but
  * still descends an execution host for the commands it hosts — an interpolating
@@ -46,6 +47,12 @@ export interface PathToken {
 export function collectPathCandidateTokens(node: TSNode): PathToken[] {
   if (node.type === "command") return collectCommandTokens(node);
   if (node.type === "file_redirect") return collectRedirectTokens(node);
+  if (node.type === "for_statement") {
+    return collectStatementOperandTokens(node, "after-in");
+  }
+  if (node.type === "case_statement") {
+    return collectStatementOperandTokens(node, "before-in");
+  }
   if (EXECUTION_HOST_TYPES.has(node.type)) {
     return collectHostedExecutionTokens(node);
   }
@@ -139,6 +146,70 @@ function collectHostedExecutionTokens(node: TSNode): PathToken[] {
   return tokens;
 }
 
+/**
+ * Which side of a statement's `in` keyword carries its path operands.
+ *
+ * A `for`/`select` word list follows `in`; a `case` subject precedes it.
+ */
+type OperandSide = "before-in" | "after-in";
+
+/**
+ * Collect the tokens of a statement that names its own path operands, rather
+ * than reaching them through a command.
+ *
+ * A path in a `for`/`select` word list or a `case` subject is a child of the
+ * statement node, so the command and redirect collectors never see it and the
+ * loop body cannot recover it — `for f in /etc/shadow; do cat $f; done` carries
+ * the literal only here, and ADR 0009 declines to resolve the body's `$f`
+ * (#839).
+ *
+ * The two statements ask one question with one parameter — which side of the
+ * anonymous `in` keyword is the operand side — so the walk is named here once
+ * rather than spelled twice, as `COMMAND_PREFIX_TYPES` is for the two command
+ * walkers.
+ *
+ * Three properties carry the design:
+ *
+ * 1. A non-operand child falls through to the ordinary recursion, not to
+ *    nothing. That is what keeps the `do_group` reaching the loop body's
+ *    commands; searching it for hosted executions alone would silently drop
+ *    every ordinary body command.
+ * 2. An operand-side child outside {@link ARG_NODE_TYPES} falls through the
+ *    same way, so a bare substitution in the word list is descended for its
+ *    command as before and its operands keep that command's own attribution
+ *    (#807) instead of the statement's.
+ * 3. An operand-side argument node is read *and* searched for hosted
+ *    executions, since a `concatenation` can be both — the pairing
+ *    {@link collectRedirectTokens} already performs on a destination.
+ *
+ * The token carries {@link UNPROVEN_EFFECT}: no command word owns it and no
+ * redirect operator names it, so neither proof source can speak and the gates
+ * consult both directional surfaces.
+ */
+function collectStatementOperandTokens(
+  node: TSNode,
+  operandSide: OperandSide,
+): PathToken[] {
+  const tokens: PathToken[] = [];
+  let seenIn = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (!child.isNamed) {
+      if (child.type === "in") seenIn = true;
+      continue;
+    }
+    const side: OperandSide = seenIn ? "after-in" : "before-in";
+    if (side !== operandSide || !ARG_NODE_TYPES.has(child.type)) {
+      tokens.push(...collectPathCandidateTokens(child));
+      continue;
+    }
+    tokens.push({ token: resolveNodeText(child), effect: UNPROVEN_EFFECT });
+    tokens.push(...collectHostedExecutionTokens(child));
+  }
+  return tokens;
+}
+
 /**
  * Extract the command name from a `command` node.
  * Returns the basename (e.g. `/usr/bin/sed` → `sed`), or undefined