@gotgenes/pi-permission-system 31.0.0 → 31.0.1

package/CHANGELOG.md

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

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": "31.0.0",
+  "version": "31.0.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -92,6 +92,7 @@
     "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;
     }