@gotgenes/pi-permission-system 36.2.0 → 36.2.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).
 
+## [36.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.2.0...pi-permission-system-v36.2.1) (2026-10-01)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** a reassigned $HOME or $PWD is no longer resolved to its startup value ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([956fa32](https://github.com/gotgenes/pi-packages/commit/956fa32ecbe6ee3b2954cebbfed8d9a44857c617)), closes [#995](https://github.com/gotgenes/pi-packages/issues/995)
+* **pi-permission-system:** a name read, printf -v, nameref, eval, or source counts as reassigning $HOME ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([a05a6d3](https://github.com/gotgenes/pi-packages/commit/a05a6d391eb0281d5977a2264aa69958ce8d7549))
+* **pi-permission-system:** ~ is no longer read as the home directory after the command reassigns HOME ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([998d51b](https://github.com/gotgenes/pi-packages/commit/998d51b36989bf0397beb4028d76e75d3e37666d))
+* **pi-permission-system:** ~ may spell an option when the inherited HOME begins with a dash ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([f1ee69a](https://github.com/gotgenes/pi-packages/commit/f1ee69a19b3f6880228da88ad2683f9b1f79a980))
+* **pi-permission-system:** a quoted export, let, trap, or quoted eval counts as reassigning $HOME ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([4406ef4](https://github.com/gotgenes/pi-packages/commit/4406ef429706aa0b7cd77ba9608d0bcb1c2982bc))
+
+### Documentation
+
+* **pi-permission-system:** record that a reassigned $HOME or $PWD is not resolved ([#995](https://github.com/gotgenes/pi-packages/issues/995)) ([e7c8b88](https://github.com/gotgenes/pi-packages/commit/e7c8b88167f05531507cdfaf584dd9e4905a0387))
+
 ## [36.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.1.0...pi-permission-system-v36.2.0) (2026-09-30)
 
 

package/docs/configuration.md

@@ -785,11 +785,11 @@ 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`, 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.
+- 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, as long as the command does not reassign them.
 - 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.
 
-What it deliberately does not resolve: any other variable (`$CONFIG_DIR`), a command substitution (`$(cmd)`), an expansion carrying an operator (`${HOME:-/tmp}`), and a variable reached through an assignment (`CURRENT="$HOME"; ls "$CURRENT"`).
+What it deliberately does not resolve: any other variable (`$CONFIG_DIR`), a command substitution (`$(cmd)`), an expansion carrying an operator (`${HOME:-/tmp}`), a variable reached through an assignment (`CURRENT="$HOME"; ls "$CURRENT"`), and `$HOME`, `$PWD`, or a leading `~` in a command that reassigns the variable anywhere (`HOME=/etc; cat "$HOME/shadow"`), including through `read`, `unset`, `eval`, or `source`.
 A non-literal `cd` (`cd "$DIR"`) makes the working directory unknown, after which relative tokens are kept literal rather than resolved against a guess.
 Commands whose payload is opaque (`bash -c`, `eval`, `sudo`, `xargs`) are floored to `ask` instead of projected.
 The governing record is [ADR 0009](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0009-bash-path-projection-completeness-contract.md), which states what the projection guarantees and which gaps are accepted residuals rather than bugs.

package/package.json

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

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

@@ -7,7 +7,11 @@ import {
 import { normalizePathPolicyLiteral } from "#src/access-intent/path-normalization";
 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 {
+  ARG_NODE_TYPES,
+  SKIP_SUBTREE_TYPES,
+  type WordReader,
+} from "./node-text";
 import type { TSNode } from "./parser";
 import { REDIRECT_NODE_TYPES } from "./redirect-analysis";
 import {
@@ -121,6 +125,7 @@ const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
 export class BashPathResolver {
   constructor(
     private readonly normalizer: PathNormalizer,
+    private readonly words: WordReader,
     private readonly workdir?: string,
   ) {}
 
@@ -146,6 +151,10 @@ export class BashPathResolver {
    * could then allow this access. #393's unknown base declines the claim
    * instead, keeping an absolute token literal-only and unconditionally
    * external while a relative one is not projected at all.
+   *
+   * A token spelled from a `HOME` the program rebinds leaves both slices before
+   * projection: path normalization would otherwise expand its `~`/`$HOME` prefix
+   * to the startup home, naming a directory the shell never touches.
    */
   resolve(
     rootNode: TSNode,
@@ -155,10 +164,13 @@ export class BashPathResolver {
       this.workdir === undefined
         ? CWD_BASE
         : this.deriveBaseFromCdTarget(CWD_BASE, this.workdir);
-    const candidates = this.collectPathCandidates(rootNode, initialBase);
+    const collected = this.collectPathCandidates(rootNode, initialBase);
     for (const salvaged of salvagedRoots) {
-      this.walkForCandidates(salvaged, UNKNOWN_BASE, candidates);
+      this.walkForCandidates(salvaged, UNKNOWN_BASE, collected);
     }
+    const candidates = collected.filter(
+      ({ token }) => !this.words.spellsReboundHome(token),
+    );
     return {
       externalAccesses: this.withWorkdirExternal(
         this.projectExternalPaths(candidates),
@@ -236,7 +248,7 @@ export class BashPathResolver {
       case "redirected_statement":
         return this.walkCurrentShellSequence(node, base, out);
       case "command":
-        tagTokens(collectCommandTokens(node), base, out);
+        tagTokens(collectCommandTokens(node, this.words), base, out);
         return this.foldCd(node, base);
       case "pipeline":
         // tree-sitter-bash mis-groups a redirect-bearing `&&`/`;` list as the
@@ -261,7 +273,7 @@ export class BashPathResolver {
         // substitution interiors: collect every candidate in the subtree tagged
         // with the enclosing base and do not fold their internal `cd`s. (Folding
         // inside substitutions is deferred — conservative, never under-flags.)
-        tagTokens(collectPathCandidateTokens(node), base, out);
+        tagTokens(collectPathCandidateTokens(node, this.words), base, out);
         return base;
     }
   }
@@ -321,7 +333,7 @@ export class BashPathResolver {
       }
       // Downstream stage (after a `|`): subshell — collect against the folded
       // base, do not fold.
-      tagTokens(collectPathCandidateTokens(child), current, out);
+      tagTokens(collectPathCandidateTokens(child, this.words), current, out);
     }
     return current;
   }
@@ -351,7 +363,7 @@ export class BashPathResolver {
         if (child.type === "file_redirect") {
           // Redirect destinations are part of the piped stage; collect them
           // against the folded base without folding.
-          tagTokens(collectRedirectTokens(child), current, out);
+          tagTokens(collectRedirectTokens(child, this.words), current, out);
           continue;
         }
         // The inner statement is the `list`/`command` being redirected; fold its
@@ -361,7 +373,7 @@ export class BashPathResolver {
       return current;
     }
     // Bare `command` or any other shape: a true subshell first stage.
-    tagTokens(collectPathCandidateTokens(node), base, out);
+    tagTokens(collectPathCandidateTokens(node, this.words), base, out);
     return base;
   }
 
@@ -389,7 +401,7 @@ export class BashPathResolver {
         current = this.walkForCandidates(child, current, out);
       } else {
         // Terminal child = the real pipe stage; collect without folding.
-        tagTokens(collectPathCandidateTokens(child), current, out);
+        tagTokens(collectPathCandidateTokens(child, this.words), current, out);
       }
     }
     return current;
@@ -412,7 +424,7 @@ export class BashPathResolver {
    * {@link PathNormalizer}; this method owns only the base-folding state.
    */
   private foldCd(commandNode: TSNode, base: EffectiveBase): EffectiveBase {
-    if (extractCommandName(commandNode) !== "cd") return base;
+    if (extractCommandName(commandNode, this.words) !== "cd") return base;
     const target = cdLiteralTarget(commandNode);
     if (target === null) return UNKNOWN_BASE;
     return this.deriveBaseFromCdTarget(base, target);

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

@@ -1,6 +1,6 @@
 import type { BashCommandContext, FloorExemption } from "#src/types";
 import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
-import { readArgWord } from "./node-text";
+import type { WordReader } from "./node-text";
 import { parseUnresolvedWithin } from "./parse-health";
 import type { TSNode } from "./parser";
 import { REDIRECT_NODE_TYPES, redirectMayWriteFile } from "./redirect-analysis";
@@ -105,14 +105,22 @@ interface UnitScope {
    * everything found inside a salvaged region is salvaged.
    */
   readonly salvaged: boolean;
+  /**
+   * How the program's shell expands an argument word. Relayed unchanged: a
+   * program's variables are the same wherever in it a word sits.
+   */
+  readonly words: WordReader;
 }
 
 /** A top-level command in the current shell, writing no file, fully parsed. */
-const TOP_LEVEL_SCOPE: UnitScope = {
-  writesViaRedirect: false,
-  parseUnresolved: false,
-  salvaged: false,
-};
+function topLevelScope(words: WordReader): UnitScope {
+  return {
+    writesViaRedirect: false,
+    parseUnresolved: false,
+    salvaged: false,
+    words,
+  };
+}
 
 /**
  * The scope a salvaged region's own units run under.
@@ -123,11 +131,14 @@ const TOP_LEVEL_SCOPE: UnitScope = {
  * {@link collectHostedCommands} resets it: a redirect established outside the
  * region is the enclosing statement's, not the region's.
  */
-const SALVAGED_SCOPE: UnitScope = {
-  writesViaRedirect: false,
-  parseUnresolved: true,
-  salvaged: true,
-};
+function salvagedScope(words: WordReader): UnitScope {
+  return {
+    writesViaRedirect: false,
+    parseUnresolved: true,
+    salvaged: true,
+    words,
+  };
+}
 
 // ── Node-type vocabulary ─────────────────────────────────────────────────────
 
@@ -244,9 +255,12 @@ const STATEMENT_TYPES = new Set([
  * wrapper unit (`bash -c`/`eval`, or an indirection wrapper such as `sudo`) is
  * tagged with a {@link WrapperKind} so its decision is later floored to `ask`.
  */
-export function collectCommands(node: TSNode): BashCommand[] {
+export function collectCommands(
+  node: TSNode,
+  words: WordReader,
+): BashCommand[] {
   const out: BashCommand[] = [];
-  collectCommandsInto(node, TOP_LEVEL_SCOPE, out);
+  collectCommandsInto(node, topLevelScope(words), out);
   return out;
 }
 
@@ -260,9 +274,12 @@ export function collectCommands(node: TSNode): BashCommand[] {
  * explicit `deny` fires — while its `allow` is still floored to `ask` by the
  * verdict fold (#840).
  */
-export function collectSalvagedCommands(node: TSNode): BashCommand[] {
+export function collectSalvagedCommands(
+  node: TSNode,
+  words: WordReader,
+): BashCommand[] {
   const out: BashCommand[] = [];
-  collectCommandsInto(node, SALVAGED_SCOPE, out);
+  collectCommandsInto(node, salvagedScope(words), out);
   return out;
 }
 
@@ -282,11 +299,14 @@ export function collectSalvagedCommands(node: TSNode): BashCommand[] {
  * (`python3 -c`, `node -e`) out: its payload is another language, so re-parsing
  * it as bash would read a secret out of embedded Python.
  */
-export function inlineShellPayloadNode(command: TSNode): TSNode | null {
+export function inlineShellPayloadNode(
+  command: TSNode,
+  words: WordReader,
+): TSNode | null {
   const nodes = commandWordNodes(command);
   const index = inlineShellPayloadIndex(
     nodes.map((node) => ({
-      ...readArgWord(node),
+      ...words.argWord(node),
       text: node.text,
       offset: node.startIndex,
     })),
@@ -426,7 +446,7 @@ function makeUnit(
  * surely as one on the enclosing statement.
  */
 function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
-  const { text, words } = readCommandUnit(node);
+  const { text, words } = readCommandUnit(node, scope.words);
   return makeUnit(text, scope, {
     wrapperKind: classifyWrapperWords(words),
     executedUnit: executedUnitOf(text, words) ?? undefined,
@@ -482,7 +502,10 @@ function redirectedScope(node: TSNode, scope: UnitScope): UnitScope {
  * A pure assignment (`FOO=bar`, no `command_name`) runs no command, has no
  * words, and keeps its whole text.
  */
-function readCommandUnit(node: TSNode): {
+function readCommandUnit(
+  node: TSNode,
+  reader: WordReader,
+): {
   text: string;
   words: CommandWord[];
 } {
@@ -495,7 +518,11 @@ function readCommandUnit(node: TSNode): {
   let previous: TSNode | undefined;
   for (const word of nodes) {
     if (previous) text += gapBetween(node, previous, word, redirects);
-    words.push({ ...readArgWord(word), text: word.text, offset: text.length });
+    words.push({
+      ...reader.argWord(word),
+      text: word.text,
+      offset: text.length,
+    });
     text += word.text;
     previous = word;
   }
@@ -626,6 +653,7 @@ function collectHostedCommands(
         writesViaRedirect: false,
         parseUnresolved: false,
         salvaged: scope.salvaged,
+        words: scope.words,
       },
       out,
     );

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

@@ -1,5 +1,5 @@
 import type { TSNode } from "./parser";
-import { resolvePlainVariableExpansion } from "./shell-variable-expansion";
+import type { ShellVariables } from "./shell-variable-expansion";
 
 /**
  * Node types whose text content is never a command argument, so no path
@@ -35,13 +35,13 @@ export const ARG_NODE_TYPES = new Set([
  * since a word only the shell decides can spell any option at all.
  */
 export interface ArgWord {
-  /** The string the shell passes after quote removal ({@link resolveNodeText}). */
+  /** The string the shell passes after quote removal ({@link resolveText}). */
   readonly value: string;
   /**
    * Whether `value` may differ from what the program receives: a part only
-   * running the command decides ({@link hasComputedPart}), or a spelling the
+   * running the command decides ({@link computedPart}), or a spelling the
    * shell rewrites before the program sees it — an escape, a glob, a brace
-   * expansion, an ANSI-C string — which {@link resolveNodeText} passes through as written.
+   * expansion, an ANSI-C string — which {@link resolveText} passes through as written.
    */
   readonly computed: boolean;
   /**
@@ -53,17 +53,67 @@ export interface ArgWord {
   readonly mayLeadWithDash: boolean;
 }
 
-/** Read an argument node into the word the program receives. */
-export function readArgWord(node: TSNode): ArgWord {
-  const value = resolveNodeText(node);
-  const computed = hasComputedPart(node) || !isSpelledExactly(node);
-  return {
-    value,
-    computed,
-    mayLeadWithDash: computed
-      ? mayExpandToDashWord(node)
-      : value.startsWith("-"),
-  };
+/**
+ * Reads argument nodes as one program's shell expands them: the node-text
+ * reads bound to the {@link ShellVariables} that program rebinds.
+ */
+export class WordReader {
+  constructor(private readonly variables: ShellVariables) {}
+
+  /** Read an argument node into the word the program receives. */
+  argWord(node: TSNode): ArgWord {
+    const value = this.text(node);
+    const tilde = this.variables.readTilde(leadingUnquotedText(node));
+    if (tilde?.known === false) {
+      return { value, computed: true, mayLeadWithDash: true };
+    }
+    const computed =
+      this.isComputed(node) || !isSpelledExactly(node, this.variables);
+    if (tilde) {
+      // The spelling `~` is not what the program receives; it is exact enough
+      // to prove with only while the home it stands for cannot be an option.
+      return {
+        value,
+        computed: computed || tilde.leadsWithDash,
+        mayLeadWithDash:
+          tilde.leadsWithDash || (computed && maySplitIntoWords(node, false)),
+      };
+    }
+    return {
+      value,
+      computed,
+      mayLeadWithDash: computed
+        ? mayExpandToDashWord(node)
+        : value.startsWith("-"),
+    };
+  }
+
+  /** The string the shell passes after quote removal ({@link resolveText}). */
+  text(node: TSNode): string {
+    return resolveText(node, this.variables);
+  }
+
+  /** Whether the node's value is decided at run time ({@link computedPart}). */
+  isComputed(node: TSNode): boolean {
+    return computedPart(node, this.variables);
+  }
+
+  /** Whether a collected token is spelled from a rebound `HOME` ({@link ShellVariables.spellsReboundHome}). */
+  spellsReboundHome(token: string): boolean {
+    return this.variables.spellsReboundHome(token);
+  }
+}
+
+/**
+ * The unquoted literal an argument opens with, where bash expands a tilde
+ * prefix: the word itself, or a concatenation's first part when that is a
+ * word. A tilde after any other part, or inside quotes, stays literal.
+ */
+function leadingUnquotedText(node: TSNode): string {
+  if (node.type === "word") return node.text;
+  if (node.type !== "concatenation") return "";
+  const first = node.child(0);
+  return first?.type === "word" ? first.text : "";
 }
 
 /**
@@ -182,12 +232,12 @@ function quotedLiteralMayLeadWithDash(text: string): boolean | undefined {
 }
 
 /**
- * Whether {@link resolveNodeText} returns exactly the string the shell passes.
+ * Whether {@link resolveText} returns exactly the string the shell passes.
  *
  * Answers `false` for any node type it does not know, which is the
  * fail-closed direction for a caller proving what a word cannot be.
  */
-function isSpelledExactly(node: TSNode): boolean {
+function isSpelledExactly(node: TSNode, variables: ShellVariables): boolean {
   switch (node.type) {
     case "raw_string":
       return true;
@@ -197,27 +247,33 @@ function isSpelledExactly(node: TSNode): boolean {
       return !node.text.includes("\\");
     case "simple_expansion":
     case "expansion":
-      return resolvePlainVariableExpansion(node) !== null;
+      return variables.resolveReference(node) !== null;
     case "string":
     // A digit run is an ordinary word to the shell; the grammar's `10#$x` form
     // carries an expansion child, which answers for itself.
     case "number":
-      return childrenSpelledExactly(node);
+      return childrenSpelledExactly(node, variables);
     case "concatenation":
       // The grammar splits `{-i,-n}` into plain words, so the expansion is
       // visible only across the whole concatenation's text.
-      return !BRACE_EXPANSION.test(node.text) && childrenSpelledExactly(node);
+      return (
+        !BRACE_EXPANSION.test(node.text) &&
+        childrenSpelledExactly(node, variables)
+      );
     default:
       return false;
   }
 }
 
 /** A `"` delimiter is spelled exactly; every named child must be too. */
-function childrenSpelledExactly(node: TSNode): boolean {
+function childrenSpelledExactly(
+  node: TSNode,
+  variables: ShellVariables,
+): boolean {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child || child.type === '"') continue;
-    if (!isSpelledExactly(child)) return false;
+    if (!isSpelledExactly(child, variables)) return false;
   }
   return true;
 }
@@ -236,22 +292,22 @@ const BRACE_EXPANSION = /\{[^}]*(,|\.\.)[^}]*\}/;
 /**
  * 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.
+ * expansion {@link ShellVariables.resolveReference} cannot resolve.
  *
- * The complement of what {@link resolveNodeText} can spell exactly. A plain
+ * The complement of what {@link resolveText} 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 {
+function computedPart(node: TSNode, variables: ShellVariables): boolean {
   if (COMPUTED_NODE_TYPES.has(node.type)) return true;
   if (VARIABLE_EXPANSION_TYPES.has(node.type)) {
-    return resolvePlainVariableExpansion(node) === null;
+    return variables.resolveReference(node) === null;
   }
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (child && hasComputedPart(child)) return true;
+    if (child && computedPart(child, variables)) return true;
   }
   return false;
 }
@@ -281,7 +337,7 @@ const VARIABLE_EXPANSION_TYPES: ReadonlySet<string> = new Set([
  *   else `.text` (see `shell-variable-expansion.ts`)
  * - other           → `.text` as fallback
  */
-export function resolveNodeText(node: TSNode): string {
+function resolveText(node: TSNode, variables: ShellVariables): string {
   switch (node.type) {
     case "word":
       return node.text;
@@ -302,7 +358,7 @@ export function resolveNodeText(node: TSNode): string {
         if (!child) continue;
         // Skip the literal `"` delimiters
         if (child.type === '"') continue;
-        result += resolveNodeText(child);
+        result += resolveText(child, variables);
       }
       return result;
     }
@@ -310,13 +366,13 @@ export function resolveNodeText(node: TSNode): string {
       return node.text;
     case "simple_expansion":
     case "expansion":
-      return resolvePlainVariableExpansion(node) ?? node.text;
+      return variables.resolveReference(node) ?? node.text;
     case "concatenation": {
       let result = "";
       for (let i = 0; i < node.childCount; i++) {
         const child = node.child(i);
         if (!child) continue;
-        result += resolveNodeText(child);
+        result += resolveText(child, variables);
       }
       return result;
     }

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

@@ -9,7 +9,9 @@ import {
   collectCommands,
   collectSalvagedCommands,
 } from "./command-enumeration";
+import { WordReader } from "./node-text";
 import { getParser } from "./parser";
+import { ShellVariables } from "./shell-variable-expansion";
 import { withSalvagedRoots } from "./unresolved-salvage";
 
 export type { BashCommand, BashExternalPath, BashPathRuleCandidate };
@@ -62,15 +64,19 @@ export class BashProgram {
 
     try {
       return withSalvagedRoots(tree.rootNode, parser, (salvaged) => {
+        const words = new WordReader(
+          ShellVariables.scan([tree.rootNode, ...salvaged]),
+        );
         const { externalAccesses, ruleCandidates } = new BashPathResolver(
           normalizer,
+          words,
           options?.workdir,
         ).resolve(tree.rootNode, salvaged);
         return new BashProgram(
           command,
           [
-            ...collectCommands(tree.rootNode),
-            ...salvaged.flatMap(collectSalvagedCommands),
+            ...collectCommands(tree.rootNode, words),
+            ...salvaged.flatMap((root) => collectSalvagedCommands(root, words)),
           ],
           externalAccesses,
           ruleCandidates,

package/src/access-intent/bash/shell-variable-expansion.ts

@@ -17,24 +17,98 @@
  * See `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
  */
 import { homedir } from "node:os";
+import { hasHomePrefix } from "#src/path/expand-home";
 
 import type { TSNode } from "./parser";
 
 /**
- * The value of a plain `$NAME` / `${NAME}` reference, or `null` when the node
- * is not a plain reference or names a variable outside the resolvable set.
+ * The resolvable variables as one program sees them: which of them the program
+ * rebinds, so that a reference to a rebound one no longer reads as its startup
+ * value.
  *
- * Plainness is decided structurally, not by matching the node's text: a plain
- * reference carries exactly one `variable_name` child and nothing else but
- * delimiters. An operator form (`${HOME:-/tmp}`, `${#HOME}`, `${HOME%/*}`)
- * carries additional children and is therefore rejected without this module
- * needing to enumerate bash's expansion operators.
+ * A closed set of rebound names, never their values — tracking what a program
+ * assigns is the dataflow ADR 0009 declines.
  */
-export function resolvePlainVariableExpansion(node: TSNode): string | null {
-  const name = plainVariableName(node);
-  return name === null ? null : (RESOLVABLE_VARIABLES.get(name)?.() ?? null);
+export class ShellVariables {
+  /** A program that rebinds none of the resolvable variables. */
+  static readonly UNREBOUND = new ShellVariables(new Set());
+
+  /**
+   * The resolvable variables `roots` rebind: the primary parse and every
+   * salvaged region, since an assignment in one governs a reference in another.
+   *
+   * A resolvable name rebinds when a `variable_name` carries it anywhere but as
+   * a plain reference's name: an assignment (a prefix one too), a declaration, a
+   * `for` variable, `unset`, an arithmetic assignment, `${HOME:=x}`. It also
+   * rebinds when a name-binding builtin is handed it as an argument (`read`,
+   * `printf -v`, `let`, a quoted `export "HOME=…"`), and both rebind under a
+   * command running code the walk never parses (`eval`, `source`, `.`, `trap`). Position is
+   * ignored, because a loop or a function body can run a later assignment
+   * first; a prefix assignment and an operator read (`${HOME:-x}`) count
+   * although neither rebinds the current shell, which costs only the
+   * projection of a program already spelling the name oddly.
+   */
+  static scan(roots: readonly TSNode[]): ShellVariables {
+    const rebound = new Set<string>();
+    for (const root of roots) collectRebound(root, rebound, false);
+    return rebound.size === 0
+      ? ShellVariables.UNREBOUND
+      : new ShellVariables(rebound);
+  }
+
+  private constructor(private readonly rebound: ReadonlySet<string>) {}
+
+  /**
+   * The value of a plain `$NAME` / `${NAME}` reference, or `null` when the
+   * node is not a plain reference or names a variable outside the resolvable
+   * set.
+   *
+   * Plainness is decided structurally, not by matching the node's text: a
+   * plain reference carries exactly one `variable_name` child and nothing else
+   * but delimiters. An operator form (`${HOME:-/tmp}`, `${#HOME}`,
+   * `${HOME%/*}`) carries additional children and is therefore rejected without
+   * this module needing to enumerate bash's expansion operators.
+   */
+  resolveReference(node: TSNode): string | null {
+    const name = plainVariableName(node);
+    if (name === null || this.rebound.has(name)) return null;
+    return RESOLVABLE_VARIABLES.get(name)?.() ?? null;
+  }
+
+  /**
+   * Whether a collected path token is spelled from a `HOME` this program
+   * rebinds (`$HOME/x`, `${HOME}`, `~/x`).
+   *
+   * Such a token names no path the projection can know, yet path normalization
+   * expands its prefix to the startup home exactly as it does for a config
+   * pattern, so it must leave the path surfaces before it reaches them.
+   */
+  spellsReboundHome(token: string): boolean {
+    return this.rebound.has("HOME") && hasHomePrefix(token);
+  }
+
+  /**
+   * How a word's leading unquoted text expands when it opens with a tilde
+   * prefix that reads `HOME` (`~` or `~/…`; `~user` reads the password
+   * database instead), or `undefined` when it does not.
+   *
+   * Unknown once the program rebinds `HOME`: bash 3.2, which Pi runs as
+   * `/bin/bash` on macOS, expands it from the reassigned value. Otherwise it is
+   * the inherited `HOME`, which `homedir()` returns verbatim, so the word leads
+   * with whatever that does.
+   */
+  readTilde(leadingText: string): TildeReading | undefined {
+    if (leadingText !== "~" && !leadingText.startsWith("~/")) return undefined;
+    if (this.rebound.has("HOME")) return { known: false };
+    return { known: true, leadsWithDash: homedir().startsWith("-") };
+  }
 }
 
+/** What a leading tilde prefix expands to, as far as the program shows. */
+export type TildeReading =
+  | { readonly known: false }
+  | { readonly known: true; readonly leadsWithDash: boolean };
+
 /**
  * How each resolvable variable is spelled as a path.
  *
@@ -50,6 +124,129 @@ const RESOLVABLE_VARIABLES: ReadonlyMap<string, () => string> = new Map([
   ["PWD", () => "."],
 ]);
 
+/**
+ * Record each resolvable name `node` binds.
+ *
+ * `bindsNames` holds beneath a builtin that binds the names it is handed
+ * (`read HOME`, `export "HOME=/etc"`, `declare -n r=HOME`), and only there does
+ * an argument spelling a name count: `grep HOME ~/.bashrc` binds nothing, and
+ * reading it as a rebinding would drop the `~/.bashrc` it does read.
+ */
+function collectRebound(
+  node: TSNode,
+  rebound: Set<string>,
+  inheritedBindsNames: boolean,
+): void {
+  if (REFERENCE_TYPES.has(node.type) && plainVariableName(node) !== null) {
+    return;
+  }
+  const bindsNames = bindsNamesBeneath(node, inheritedBindsNames);
+  if (node.type === "variable_name" && RESOLVABLE_VARIABLES.has(node.text)) {
+    rebound.add(node.text);
+  }
+  if (bindsNames && NAME_ARGUMENT_TYPES.has(node.type)) {
+    const name = NAMED_ARGUMENT.exec(node.text.replace(QUOTING, ""))?.[1];
+    if (name) rebound.add(name);
+  }
+  if (node.type === "command" && UNSEEN_CODE_COMMANDS.has(commandName(node))) {
+    for (const name of RESOLVABLE_VARIABLES.keys()) rebound.add(name);
+  }
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) collectRebound(child, rebound, bindsNames);
+  }
+}
+
+/**
+ * Whether the arguments beneath `node` are names its command binds. A command
+ * decides for itself; a `declare`-family or `unset` statement always binds;
+ * anything else inherits.
+ */
+function bindsNamesBeneath(node: TSNode, inherited: boolean): boolean {
+  if (node.type === "declaration_command" || node.type === "unset_command") {
+    return true;
+  }
+  if (node.type !== "command") return inherited;
+  const name = commandName(node);
+  if (name === "printf") return hasArgument(node, "-v");
+  return NAME_BINDING_COMMANDS.has(name);
+}
+
+/**
+ * Builtins that bind a name passed as an argument. `declare` and its family
+ * parse as a `declaration_command` when spelled plainly and as a `command`
+ * when quoted, so they are listed here too; `printf` binds only under `-v`.
+ */
+const NAME_BINDING_COMMANDS: ReadonlySet<string> = new Set([
+  "read",
+  "mapfile",
+  "readarray",
+  "getopts",
+  "let",
+  "unset",
+  "declare",
+  "typeset",
+  "local",
+  "export",
+  "readonly",
+]);
+
+/**
+ * Argument nodes that can spell a name a builtin binds, whole or as the head
+ * of an assignment (`HOME=…`, `HOME+=…`, `HOME[0]=…`, `let HOME++`).
+ */
+const NAME_ARGUMENT_TYPES: ReadonlySet<string> = new Set([
+  "word",
+  "string",
+  "raw_string",
+  "concatenation",
+]);
+
+/** A resolvable name leading an argument, not followed by more of an identifier. */
+const NAMED_ARGUMENT = new RegExp(
+  `^(${[...RESOLVABLE_VARIABLES.keys()].join("|")})(?![A-Za-z0-9_])`,
+);
+
+/** Quote and escape characters, which the shell removes before a builtin sees the name. */
+const QUOTING = /["'\\]/g;
+
+/** A command's name as the shell reads it, quotes and escapes removed. */
+function commandName(command: TSNode): string {
+  for (let i = 0; i < command.childCount; i++) {
+    const child = command.child(i);
+    if (child?.type === "command_name") return child.text.replace(QUOTING, "");
+  }
+  return "";
+}
+
+/** Whether a command carries `flag` as one of its own arguments. */
+function hasArgument(command: TSNode, flag: string): boolean {
+  for (let i = 0; i < command.childCount; i++) {
+    const child = command.child(i);
+    if (child && child.type !== "command_name" && child.text === flag) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Commands that run code the walk never parses, which may rebind anything:
+ * `eval`'s joined arguments, a file `source`/`.` reads, and a `trap` action.
+ */
+const UNSEEN_CODE_COMMANDS: ReadonlySet<string> = new Set([
+  "eval",
+  "source",
+  ".",
+  "trap",
+]);
+
+/** The node types a variable reference parses as. */
+const REFERENCE_TYPES: ReadonlySet<string> = new Set([
+  "simple_expansion",
+  "expansion",
+]);
+
 /** Node types that delimit an expansion without altering what it evaluates to. */
 const EXPANSION_DELIMITERS: ReadonlySet<string> = new Set(["$", "${", "}"]);
 

package/src/access-intent/bash/sync-commands.ts

@@ -3,7 +3,9 @@ import {
   collectCommands,
   collectSalvagedCommands,
 } from "./command-enumeration";
+import { WordReader } from "./node-text";
 import { getWarmBashParser } from "./parser";
+import { ShellVariables } from "./shell-variable-expansion";
 import { withSalvagedRoots } from "./unresolved-salvage";
 
 /**
@@ -26,10 +28,15 @@ export function parseBashCommandsSync(command: string): BashCommand[] | null {
   const tree = parser.parse(command);
   if (!tree) return [];
   try {
-    return withSalvagedRoots(tree.rootNode, parser, (salvaged) => [
-      ...collectCommands(tree.rootNode),
-      ...salvaged.flatMap(collectSalvagedCommands),
-    ]);
+    return withSalvagedRoots(tree.rootNode, parser, (salvaged) => {
+      const words = new WordReader(
+        ShellVariables.scan([tree.rootNode, ...salvaged]),
+      );
+      return [
+        ...collectCommands(tree.rootNode, words),
+        ...salvaged.flatMap((root) => collectSalvagedCommands(root, words)),
+      ];
+    });
   } finally {
     tree.delete();
   }

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

@@ -5,10 +5,8 @@ import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
 import {
   ARG_NODE_TYPES,
   type ArgWord,
-  hasComputedPart,
-  readArgWord,
-  resolveNodeText,
   SKIP_SUBTREE_TYPES,
+  type WordReader,
 } from "./node-text";
 import type { TSNode } from "./parser";
 import {
@@ -63,24 +61,27 @@ export interface PathToken {
  * `script`-role flag's argument for an interpreter. For all other commands,
  * collects all arguments generically.
  */
-export function collectPathCandidateTokens(node: TSNode): PathToken[] {
-  if (node.type === "command") return collectCommandTokens(node);
-  if (node.type === "file_redirect") return collectRedirectTokens(node);
+export function collectPathCandidateTokens(
+  node: TSNode,
+  words: WordReader,
+): PathToken[] {
+  if (node.type === "command") return collectCommandTokens(node, words);
+  if (node.type === "file_redirect") return collectRedirectTokens(node, words);
   if (node.type === "for_statement") {
-    return collectStatementOperandTokens(node, "after-in");
+    return collectStatementOperandTokens(node, "after-in", words);
   }
   if (node.type === "case_statement") {
-    return collectStatementOperandTokens(node, "before-in");
+    return collectStatementOperandTokens(node, "before-in", words);
   }
   if (EXECUTION_HOST_TYPES.has(node.type)) {
-    return collectHostedExecutionTokens(node);
+    return collectHostedExecutionTokens(node, words);
   }
   if (SKIP_SUBTREE_TYPES.has(node.type)) return [];
 
   const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (child) tokens.push(...collectPathCandidateTokens(child));
+    if (child) tokens.push(...collectPathCandidateTokens(child, words));
   }
   return tokens;
 }
@@ -95,19 +96,22 @@ export function collectPathCandidateTokens(node: TSNode): PathToken[] {
  * spelling proves nothing. A nested execution collected along the way keeps
  * its own command's attribution instead.
  */
-export function collectCommandTokens(node: TSNode): PathToken[] {
+export function collectCommandTokens(
+  node: TSNode,
+  words: WordReader,
+): PathToken[] {
   const effect = proveCommandEffect(
-    extractCommandWord(node) ?? "",
-    commandArgumentWords(node),
+    extractCommandWord(node, words) ?? "",
+    commandArgumentWords(node, words),
   );
-  const commandName = extractCommandName(node);
+  const commandName = extractCommandName(node, words);
   const config = commandName
     ? PATTERN_FIRST_COMMANDS.get(commandName)
     : undefined;
-  if (config) return collectPatternCommandTokens(node, config, effect);
+  if (config) return collectPatternCommandTokens(node, config, effect, words);
   return [
-    ...collectGenericCommandTokens(node, effect),
-    ...collectEmbeddedOptionValues(node, effect),
+    ...collectGenericCommandTokens(node, effect, words),
+    ...collectEmbeddedOptionValues(node, effect, words),
   ];
 }
 
@@ -139,7 +143,10 @@ export function collectCommandTokens(node: TSNode): PathToken[] {
  * 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[] {
+export function collectRedirectTokens(
+  node: TSNode,
+  words: WordReader,
+): PathToken[] {
   const target = redirectTargetIndex(node);
   const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
@@ -148,15 +155,15 @@ export function collectRedirectTokens(node: TSNode): PathToken[] {
     if (ARG_NODE_TYPES.has(child.type)) {
       const effect = redirectEffectForDestination(node, child);
       if (effect) {
-        const token = resolveNodeText(child);
+        const token = words.text(child);
         const role: TokenRole =
-          i === target && provesTarget(effect, child, token)
+          i === target && provesTarget(effect, child, token, words)
             ? "redirect-destination"
             : "operand";
         tokens.push({ token, effect, role });
       }
     }
-    tokens.push(...collectHostedExecutionTokens(child));
+    tokens.push(...collectHostedExecutionTokens(child, words));
   }
   return tokens;
 }
@@ -174,9 +181,10 @@ function provesTarget(
   effect: TokenEffect,
   destination: TSNode,
   token: string,
+  words: WordReader,
 ): boolean {
   return (
-    effect.source === "syntax" && !hasComputedPart(destination) && token !== ""
+    effect.source === "syntax" && !words.isComputed(destination) && token !== ""
   );
 }
 
@@ -193,10 +201,13 @@ function provesTarget(
  * (`> ${DIR}/$(cmd)`), so the traversal is the root-inclusive
  * `forEachExecutionIn`.
  */
-function collectHostedExecutionTokens(node: TSNode): PathToken[] {
+function collectHostedExecutionTokens(
+  node: TSNode,
+  words: WordReader,
+): PathToken[] {
   const tokens: PathToken[] = [];
   forEachExecutionIn(node, (contextNode) => {
-    tokens.push(...collectPathCandidateTokens(contextNode));
+    tokens.push(...collectPathCandidateTokens(contextNode, words));
   });
   return tokens;
 }
@@ -244,6 +255,7 @@ type OperandSide = "before-in" | "after-in";
 function collectStatementOperandTokens(
   node: TSNode,
   operandSide: OperandSide,
+  words: WordReader,
 ): PathToken[] {
   const tokens: PathToken[] = [];
   let seenIn = false;
@@ -256,15 +268,15 @@ function collectStatementOperandTokens(
     }
     const side: OperandSide = seenIn ? "after-in" : "before-in";
     if (side !== operandSide || !ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(...collectPathCandidateTokens(child));
+      tokens.push(...collectPathCandidateTokens(child, words));
       continue;
     }
     tokens.push({
-      token: resolveNodeText(child),
+      token: words.text(child),
       effect: UNPROVEN_EFFECT,
       role: "operand",
     });
-    tokens.push(...collectHostedExecutionTokens(child));
+    tokens.push(...collectHostedExecutionTokens(child, words));
   }
   return tokens;
 }
@@ -279,8 +291,11 @@ function collectStatementOperandTokens(
  * capability claim, where the directory prefix is the whole point — use
  * {@link extractCommandWord} there.
  */
-export function extractCommandName(node: TSNode): string | undefined {
-  const word = extractCommandWord(node);
+export function extractCommandName(
+  node: TSNode,
+  words: WordReader,
+): string | undefined {
+  const word = extractCommandWord(node, words);
   return word === undefined ? undefined : basename(word);
 }
 
@@ -294,12 +309,15 @@ export function extractCommandName(node: TSNode): string | undefined {
  * Documented against {@link extractCommandName}, which answers the other
  * question.
  */
-export function extractCommandWord(node: TSNode): string | undefined {
+export function extractCommandWord(
+  node: TSNode,
+  words: WordReader,
+): string | undefined {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
     if (child.type === "command_name") {
-      const text = resolveNodeText(child);
+      const text = words.text(child);
       return text === "" ? undefined : text;
     }
   }
@@ -319,16 +337,16 @@ export function extractCommandWord(node: TSNode): string | undefined {
  * reaches the program as an argument too, and a proof that never saw it could
  * not know it might spell `-i`.
  */
-function commandArgumentWords(node: TSNode): ArgWord[] {
-  const words: ArgWord[] = [];
+function commandArgumentWords(node: TSNode, words: WordReader): ArgWord[] {
+  const argWords: ArgWord[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child?.isNamed) continue;
     if (COMMAND_PREFIX_TYPES.has(child.type)) continue;
     if (REDIRECT_NODE_TYPES.has(child.type)) continue;
-    words.push(readArgWord(child));
+    argWords.push(words.argWord(child));
   }
-  return words;
+  return argWords;
 }
 
 /**
@@ -376,6 +394,7 @@ const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
 function collectEmbeddedOptionValues(
   node: TSNode,
   effect: TokenEffect,
+  words: WordReader,
 ): PathToken[] {
   const values: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
@@ -384,7 +403,7 @@ function collectEmbeddedOptionValues(
     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];
+    const value = OPTION_VALUE_PATTERN.exec(words.text(child))?.[1];
     if (value !== undefined) {
       values.push({ token: value, effect, role: "operand" });
     }
@@ -768,6 +787,7 @@ function collectPatternCommandTokens(
   node: TSNode,
   config: PatternCommandConfig,
   effect: TokenEffect,
+  words: WordReader,
 ): PathToken[] {
   const patternPositionals = config.patternPositionals ?? 1;
   let hasExplicitScript = false;
@@ -782,12 +802,12 @@ function collectPatternCommandTokens(
 
     if (COMMAND_PREFIX_TYPES.has(child.type)) {
       // Supplies no operand of its own, but may host one that really runs.
-      tokens.push(...collectHostedExecutionTokens(child));
+      tokens.push(...collectHostedExecutionTokens(child, words));
       continue;
     }
 
     const isArgNode = ARG_NODE_TYPES.has(child.type);
-    const text = resolveNodeText(child);
+    const text = words.text(child);
 
     // An argument is read for its text below, and its text alone — but a
     // quoted substitution sitting there really runs, and its own operands are
@@ -796,7 +816,7 @@ function collectPatternCommandTokens(
     // recursions below; the quoted one parses as a `string` and would
     // otherwise stop here, whichever role the argument turns out to have
     // (#945).
-    if (isArgNode) tokens.push(...collectHostedExecutionTokens(child));
+    if (isArgNode) tokens.push(...collectHostedExecutionTokens(child, words));
 
     // Handle the argument a previous flag consumed. The consumption discharges
     // on whatever node type follows, not only on an ARG_NODE_TYPES one: a bare
@@ -810,7 +830,7 @@ function collectPatternCommandTokens(
       if (!isArgNode) {
         // Contributes no operand text of its own, but may host a nested
         // execution whose operands are candidates (#741).
-        tokens.push(...collectPathCandidateTokens(child));
+        tokens.push(...collectPathCandidateTokens(child, words));
         continue;
       }
       const discharge = dischargePendingConsumption(consumption, text, effect);
@@ -838,7 +858,7 @@ function collectPatternCommandTokens(
         positionalsSeen++;
       }
       // Recurse for nested commands (e.g. command_substitution).
-      tokens.push(...collectPathCandidateTokens(child));
+      tokens.push(...collectPathCandidateTokens(child, words));
       continue;
     }
 
@@ -963,6 +983,7 @@ function dischargePendingConsumption(
 function collectGenericCommandTokens(
   node: TSNode,
   effect: TokenEffect,
+  words: WordReader,
 ): PathToken[] {
   const tokens: PathToken[] = [];
   let seenCommandName = false;
@@ -974,7 +995,7 @@ function collectGenericCommandTokens(
     if (COMMAND_PREFIX_TYPES.has(child.type)) {
       // Supplies no operand of its own, but may host one that really runs.
       if (child.type === "command_name") seenCommandName = true;
-      tokens.push(...collectHostedExecutionTokens(child));
+      tokens.push(...collectHostedExecutionTokens(child, words));
       continue;
     }
 
@@ -983,7 +1004,7 @@ function collectGenericCommandTokens(
     // sits (ADR 0009's positional invariance, #945). The unquoted spelling
     // reaches the nested command through the trailing recursion.
     if (ARG_NODE_TYPES.has(child.type))
-      tokens.push(...collectHostedExecutionTokens(child));
+      tokens.push(...collectHostedExecutionTokens(child, words));
 
     // If there was no explicit command_name node, the first word-like
     // child is the command name itself — skip it.
@@ -994,12 +1015,12 @@ function collectGenericCommandTokens(
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push({ token: resolveNodeText(child), effect, role: "operand" });
+      tokens.push({ token: words.text(child), effect, role: "operand" });
       continue;
     }
 
     // Recurse into other children (e.g. command_substitution nested in args)
-    tokens.push(...collectPathCandidateTokens(child));
+    tokens.push(...collectPathCandidateTokens(child, words));
   }
 
   return tokens;

package/src/logging/command-redaction.ts

@@ -1,13 +1,11 @@
 import { inlineShellPayloadNode } from "#src/access-intent/bash/command-enumeration";
-import {
-  ARG_NODE_TYPES,
-  resolveNodeText,
-} from "#src/access-intent/bash/node-text";
+import { ARG_NODE_TYPES, WordReader } from "#src/access-intent/bash/node-text";
 import {
   type BashReparser,
   getWarmBashParser,
   type TSNode,
 } from "#src/access-intent/bash/parser";
+import { ShellVariables } from "#src/access-intent/bash/shell-variable-expansion";
 import { isPlainRecord } from "#src/value-guards";
 import { isSensitiveName, REDACTED_PLACEHOLDER } from "./log-redaction";
 
@@ -80,7 +78,7 @@ export function redactCommandSecrets(command: string): string {
  * carries.
  *
  * A payload is re-parsed from its **verbatim inner slice** rather than
- * `resolveNodeText`'s shell value: the resolved text concatenates children and
+ * `WordReader.text`'s shell value: the resolved text concatenates children and
  * expands `$HOME`, which destroys the offset correspondence this shift relies
  * on. Because the slice excludes the payload's quotes, no span recovered from it
  * can reach one, so the masked payload stays quoted as it was written.
@@ -124,6 +122,14 @@ function collectSpansIn(
   }
 }
 
+/**
+ * How the masker reads a word: at the startup values of `HOME` and `PWD`,
+ * whatever the command rebinds. What it masks is decided by the *name* a value
+ * is bound to, and neither spelling of either variable is a sensitive name, so
+ * reading them as rebound would change no span.
+ */
+const WORDS = new WordReader(ShellVariables.UNREBOUND);
+
 /**
  * How many payload layers to descend.
  *
@@ -175,7 +181,7 @@ function collectInlineShellPayloads(
   payloads: PayloadSource[],
 ): void {
   if (node.type === "command") {
-    const payload = inlineShellPayloadNode(node);
+    const payload = inlineShellPayloadNode(node, WORDS);
     if (payload) payloads.push(payloadSourceOf(payload));
   }
   for (let i = 0; i < node.childCount; i++) {
@@ -191,7 +197,7 @@ function collectInlineShellPayloads(
  * A `word` payload is the program already. A `string`/`raw_string` wraps it in
  * one quote pair and an `ansi_c_string` in a `$` plus one quote pair, so each is
  * a slice at a known offset. Anything else — a `concatenation`, an expansion —
- * is stitched: `resolveNodeText` knows how to read its shell value, and that
+ * is stitched: `WordReader.text` knows how to read its shell value, and that
  * value's own offsets describe no span of the command.
  */
 function payloadSourceOf(node: TSNode): PayloadSource {
@@ -216,7 +222,7 @@ function payloadSourceOf(node: TSNode): PayloadSource {
         start: node.startIndex + quoteAt + 1,
         end: node.endIndex - 1,
       }
-    : { kind: "stitched", text: resolveNodeText(node), ...bounds };
+    : { kind: "stitched", text: WORDS.text(node), ...bounds };
 }
 
 /**
@@ -318,7 +324,7 @@ const HEADER_FIELD = /^([A-Za-z][A-Za-z0-9_-]*)[ \t]*:[ \t]*\S/;
 
 function headerValueSpan(node: TSNode): MaskSpan | null {
   if (!ARG_NODE_TYPES.has(node.type)) return null;
-  const match = HEADER_FIELD.exec(resolveNodeText(node));
+  const match = HEADER_FIELD.exec(WORDS.text(node));
   const field = match?.[1];
   if (!field || !isSensitiveName(field) || isCamelCased(field)) return null;
   const colon = node.text.indexOf(":");

package/src/path/expand-home.ts

@@ -29,14 +29,30 @@ const HOME_PREFIXES = ["~", "$HOME", "${HOME}"] as const;
  * All other patterns are returned unchanged.
  */
 export function expandHomePath(pattern: string): string {
-  for (const prefix of HOME_PREFIXES) {
-    if (pattern === prefix) return homedir();
-    if (!pattern.startsWith(prefix)) continue;
+  const rest = afterHomePrefix(pattern);
+  if (rest === undefined) return pattern;
+  return rest === "" ? homedir() : join(homedir(), rest.slice(1));
+}
+
+/**
+ * Whether {@link expandHomePath} reads `value` as starting at the home
+ * directory.
+ */
+export function hasHomePrefix(value: string): boolean {
+  return afterHomePrefix(value) !== undefined;
+}
 
-    const rest = pattern.slice(prefix.length);
-    if (rest.startsWith("/") || rest.startsWith("\\")) {
-      return join(homedir(), rest.slice(1));
+/**
+ * What follows a recognized home prefix (`""`, or a separator and the rest),
+ * or `undefined` when `value` has none.
+ */
+function afterHomePrefix(value: string): string | undefined {
+  for (const prefix of HOME_PREFIXES) {
+    if (!value.startsWith(prefix)) continue;
+    const rest = value.slice(prefix.length);
+    if (rest === "" || rest.startsWith("/") || rest.startsWith("\\")) {
+      return rest;
     }
   }
-  return pattern;
+  return undefined;
 }