@gotgenes/pi-permission-system 33.0.0 → 33.0.2

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [33.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.0.1...pi-permission-system-v33.0.2) (2026-09-19)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** stop writing a named secret inside an inline-shell payload ([eaeb297](https://github.com/gotgenes/pi-packages/commit/eaeb297e0f20b5ceeb935f0d1a062ebf9daa17ec)), closes [#923](https://github.com/gotgenes/pi-packages/issues/923)
+* **pi-permission-system:** mask a secret in a quote-stitched inline-shell payload ([4b79c10](https://github.com/gotgenes/pi-packages/commit/4b79c105c21d3400ff25050eb19490f6c71ede61)), closes [#923](https://github.com/gotgenes/pi-packages/issues/923)
+* **pi-permission-system:** mask a secret in a payload behind an indirection wrapper ([c17959a](https://github.com/gotgenes/pi-packages/commit/c17959a87b2a43816796c9deb9f7b28ae9ceb436)), closes [#923](https://github.com/gotgenes/pi-packages/issues/923)
+
+### Documentation
+
+* **pi-permission-system:** record the payload widening and accept the heredoc residual ([8544508](https://github.com/gotgenes/pi-packages/commit/85445088fad6ce7d10df95cd661e98c0c3fd587f)), closes [#923](https://github.com/gotgenes/pi-packages/issues/923)
+* **pi-permission-system:** record the coarse and wrapper-peeled payload cases ([c3644d6](https://github.com/gotgenes/pi-packages/commit/c3644d60e8dbcd9f332d2509711df05356844e03)), closes [#923](https://github.com/gotgenes/pi-packages/issues/923)
+
+## [33.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.0.0...pi-permission-system-v33.0.1) (2026-09-19)
+
+
+### Documentation
+
+* **pi-permission-system:** document the serving-liveness and bound-channel mechanism in the integration spec ([#942](https://github.com/gotgenes/pi-packages/issues/942)) ([2786acc](https://github.com/gotgenes/pi-packages/commit/2786accaf40136f192e6f8d187058ae60c7555b5)), closes [#942](https://github.com/gotgenes/pi-packages/issues/942)
+
 ## [33.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.1.0...pi-permission-system-v33.0.0) (2026-09-18)
 
 

package/docs/configuration.md

@@ -1292,6 +1292,7 @@ The command is parsed, and a value is masked when it is bound to a sensitive nam
 KEY="sk-or-v1-…" curl https://x        →  KEY=[redacted] curl https://x
 env MY_KEY=… deploy                    →  env MY_KEY=[redacted] deploy
 curl -H "Authorization: Bearer sk-…"   →  curl -H "Authorization:[redacted]"
+bash -c 'TOKEN=sk-… deploy'            →  bash -c 'TOKEN=[redacted] deploy'
 ```
 
 The boundary is worth stating exactly, because it is easy to over-read:
@@ -1301,7 +1302,15 @@ The boundary is worth stating exactly, because it is easy to over-read:
 
 So `grep -r "sk-ant-…" .` and `deploy --token abc123` are both logged unredacted: the first binds the secret to nothing, and the second binds it to a flag rather than a name.
 The extension deliberately does not try to guess which parts of a command look secret-shaped — see [ADR 0010] for the measured reasoning.
-A command the parser could not fully resolve, and a secret inside an inline-shell payload (`bash -c '…'`) or a heredoc body, are masked only as far as the parse reached.
+A command the parser could not fully resolve is masked only as far as the parse reached.
+A secret inside a **heredoc body** (`cat > .env <<'EOF'` / `API_KEY=…` / `EOF`) is not masked at all: a heredoc body is literal data rather than shell, and re-parsing one as shell is how the log's own Python and TypeScript heredocs come to read as assignments — measured at six false positives and no true ones, so [ADR 0010] declines it.
+An **inline-shell payload** (`bash -c '…'`, `sh -c "…"`, `eval '…'`) *is* masked, because the package already knows that argument is shell — including one reached through a wrapper (`sudo bash -c '…'`, `xargs -I{} sh -c '…'`).
+An interpreter's payload (`python3 -c '…'`) is not, for the same reason a heredoc body is not.
+Where a payload is stitched together across quote boundaries (`bash -c 'TOKEN='"$SECRET"`), the whole argument is replaced rather than just the value, because no single offset maps the value back onto the command:
+
+```text
+bash -c 'TOKEN='"$SECRET"               →  bash -c [redacted]
+```
 
 Every value the **review** log writes is narrowed to `reviewLogFieldMaxWidth` (1000 characters by default) and marked with an ellipsis, so a single pathological command cannot put tens of kilobytes in one entry.
 This is a length bound, not redaction: it never inspects a value to decide what to hide, and it applies to every field alike.

package/docs/subagent-integration.md

@@ -160,7 +160,9 @@ The polling session publishes the session id it polls, and a child checks that i
 
 The announcement goes out on two channels, because a child cannot always reach the same one.
 A child running inside its parent's process reads a process-global registry.
+A stale mark left in that registry by a session that died without `session_shutdown` suppresses the fast-fail and falls back to the timeout — the safe direction for that channel.
 A child running as a separate `pi` process (the `PI_SUBAGENT_PARENT_SESSION` path) shares no memory with its parent, so it reads a heartbeat record the serving session refreshes under `<agent dir>/sessions/permission-forwarding/serving/`, holding the served session id, the serving process id, and the time it was last refreshed.
+That `serving/` directory is created on demand and never removed.
 
 For an out-of-process target, four things count as "not draining":
 
@@ -171,7 +173,7 @@ For an out-of-process target, four things count as "not draining":
 | A record nobody has refreshed for several seconds | The parent's process survives but has stopped polling                        |
 | A record for a different session id               | The child is forwarding somewhere nobody is listening                        |
 
-If the target is not draining its inbox, the child gives up after a two-second grace window rather than waiting out `forwardingTimeoutMs`, and the tool is blocked with:
+If the target is not draining its inbox, the child gives up after a two-second grace window (`PERMISSION_FORWARDING_SERVING_GRACE_MS`) rather than waiting out `forwardingTimeoutMs`, and the tool is blocked with:
 
 ```text
 [pi-permission-system] Running bash command 'pwd' requires approval, but no
@@ -180,6 +182,7 @@ permission requests.
 ```
 
 The grace window exists so a request that arrives while the parent is switching sessions is not abandoned in the gap.
+Absence of a record is deliberately **not** read as unknown: a cleanly exited parent leaves nothing behind, so treating absence as "maybe serving" would restore the full-timeout stall that the heartbeat exists to end.
 A target that *is* draining its inbox is waited on for the full `forwardingTimeoutMs`, however long the human takes to decide.
 That includes a parent whose human is still deliberating at an earlier forwarded prompt: it keeps refreshing its heartbeat throughout, so a second child does not read it as gone.
 
@@ -188,6 +191,7 @@ None of them is reported as a user denial, because no user was ever asked.
 
 The two sides of the exchange are correlatable in the review log: the serving session writes `forwarded_permission.serving_started` with the id it polls, and the child writes `forwarded_permission.request_created` with the `targetSessionId` it forwarded to.
 When a forwarded request goes unanswered, comparing those two entries distinguishes a parent that was not polling from one polling a different session.
+The child's `forwarded_permission.no_serving_session` entry also records `servingChannel` and `servingState` beside the ids observed, since "exited", "killed", and "polling a different session id" are different diagnoses the shared denial string does not distinguish.
 
 When a forwarded request *is* answered, the child's own terminal entry names both which session answered and what within it decided.
 The serving node records its decider on the response — a rule of its own (with the surface, pattern, and origin that matched), the link that ruled, or the human who answered its dialog — and the child records it nested under a `forwarded` frame:

package/package.json

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

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

@@ -6,6 +6,7 @@ import {
   type CommandWord,
   classifyWrapperWords,
   executedUnitOf,
+  inlineShellPayloadIndex,
   isTransparentWrapper,
   type WrapperKind,
 } from "./wrapper-analysis";
@@ -263,6 +264,30 @@ export function collectSalvagedCommands(node: TSNode): BashCommand[] {
   return out;
 }
 
+/**
+ * The node holding a `command` node's inline-shell payload — the inner program
+ * of `bash -c '…'`, `sh -c "…"`, or `eval '…'` — or `null` for any other
+ * command.
+ *
+ * The node rather than its text, because the log's command masker re-parses the
+ * payload and offsets the spans it recovers by the node's `startIndex`
+ * (`logging/command-redaction.ts`, #923). {@link executedUnitOf} answers the
+ * text question for display and cannot serve that one: it unquotes, unwraps
+ * nested indirection, and drops a result that adds nothing — all of which lose
+ * the correspondence to the command as written.
+ *
+ * The payload set is the *shell* set, which is what keeps an interpreter
+ * (`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 {
+  const nodes = commandWordNodes(command);
+  const index = inlineShellPayloadIndex(
+    nodes.map((node) => ({ text: node.text, offset: node.startIndex })),
+  );
+  return index === -1 ? null : (nodes.at(index) ?? null);
+}
+
 function collectCommandsInto(
   node: TSNode,
   inherited: UnitScope,
@@ -433,16 +458,32 @@ function redirectedScope(node: TSNode, scope: UnitScope): UnitScope {
  * list means a pure assignment with no `command_name`.
  */
 function readCommandWords(node: TSNode): CommandWord[] {
-  const words: CommandWord[] = [];
-  let unitStart: number | undefined;
+  const nodes = commandWordNodes(node);
+  const unitStart = nodes.at(0)?.startIndex ?? 0;
+  return nodes.map((child) => ({
+    text: child.text,
+    offset: child.startIndex - unitStart,
+  }));
+}
+
+/**
+ * The nodes {@link readCommandWords} reports words for, in the same order.
+ *
+ * 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.
+ */
+function commandWordNodes(node: TSNode): TSNode[] {
+  const nodes: TSNode[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child?.isNamed) continue;
     if (child.type === "variable_assignment") continue;
-    unitStart ??= child.startIndex;
-    words.push({ text: child.text, offset: child.startIndex - unitStart });
+    nodes.push(child);
   }
-  return words;
+  return nodes;
 }
 
 /**

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

@@ -59,6 +59,57 @@ export function classifyWrapperWords(
   return undefined;
 }
 
+/**
+ * Index within `words` of the inline-shell payload — the inner program a shell or
+ * `eval` runs — or `-1` when the unit carries none.
+ *
+ * Indirection layers are peeled first, so `sudo bash -c '…'` answers the
+ * payload's index rather than `-1`. That is not a convenience:
+ * {@link executedUnitOf} peels them too, so a consumer that did not would mask a
+ * secret under `executedUnit` and write it verbatim under `command` — the
+ * inconsistency #923 reports, reintroduced one wrapper layer up.
+ *
+ * The index names the payload's *position*, which a vacant one still has
+ * (`bash -c`), so each caller decides for itself what reading past the end of
+ * `words` is worth.
+ */
+export function inlineShellPayloadIndex(words: readonly CommandWord[]): number {
+  let base = 0;
+  let current = words;
+
+  for (let depth = 0; depth < MAX_UNWRAP_DEPTH; depth++) {
+    const direct = directPayloadIndex(current);
+    if (direct !== -1) return base + direct;
+    if (classifyWrapperWords(current) !== "indirection") return -1;
+
+    const start = innerCommandIndex(current);
+    if (start === -1 || start >= current.length) return -1;
+    const end = execTerminatorIndex(current, start);
+    base += start;
+    current = current.slice(start, end);
+  }
+  return -1;
+}
+
+/**
+ * The payload index of a unit that is *already* the shell or `eval` running it.
+ *
+ * `eval` takes its program as the first argument (no `-c`, so the flag scan
+ * answers -1 and the index falls out as 1); a shell takes it after the `-c`
+ * cluster. Any other command name carries no inline program at all, which is
+ * what keeps an interpreter (`python3 -c`, `node -e`) out: its payload is
+ * another language, not shell.
+ */
+function directPayloadIndex(words: readonly CommandWord[]): number {
+  const commandName = wrapperName(words);
+  if (commandName === undefined) return -1;
+  const isShell = SHELL_WRAPPER_NAMES.has(commandName);
+  if (commandName !== "eval" && !isShell) return -1;
+  const flagIndex = shortFlagCIndex(words.slice(1).map((word) => word.text));
+  if (isShell && flagIndex === -1) return -1;
+  return flagIndex + 2;
+}
+
 // ── Wrapper vocabulary ───────────────────────────────────────────────────────
 
 /**
@@ -201,13 +252,16 @@ function nothingNew(text: string | null, unitText: string): string | null {
   return text.startsWith("-") ? null : text;
 }
 
-/** The inline-shell payload argument, unquoted; `null` when absent. */
+/**
+ * The inline-shell payload argument, unquoted; `null` when absent.
+ *
+ * Reads the **direct** index: {@link unwrapIndirection} has already peeled every
+ * wrapper layer by the time it reaches its opaque branch, so peeling again would
+ * look past a shell that is itself an outer wrapper's payload.
+ */
 function opaquePayload(words: readonly CommandWord[]): string | null {
-  const args = words.slice(1);
-  // `eval` takes its program as the first argument (no `-c`, so the index is
-  // -1); a shell takes it after the `-c` cluster.
-  const flagIndex = shortFlagCIndex(args.map((word) => word.text));
-  const payload = args[flagIndex + 1] as CommandWord | undefined;
+  const index = directPayloadIndex(words);
+  const payload = index === -1 ? undefined : words.at(index);
   return payload === undefined ? null : unquote(payload.text);
 }
 

package/src/logging/command-redaction.ts

@@ -1,8 +1,13 @@
+import { inlineShellPayloadNode } from "#src/access-intent/bash/command-enumeration";
 import {
   ARG_NODE_TYPES,
   resolveNodeText,
 } from "#src/access-intent/bash/node-text";
-import { getWarmBashParser, type TSNode } from "#src/access-intent/bash/parser";
+import {
+  type BashReparser,
+  getWarmBashParser,
+  type TSNode,
+} from "#src/access-intent/bash/parser";
 import { isPlainRecord } from "#src/value-guards";
 import { isSensitiveName, REDACTED_PLACEHOLDER } from "./log-redaction";
 
@@ -25,6 +30,14 @@ import { isSensitiveName, REDACTED_PLACEHOLDER } from "./log-redaction";
  *
  * A value with no name bound to it — a secret typed as a `grep` pattern — is
  * out of reach of a structural rule and stays unmasked.
+ *
+ * An inline-shell payload (`bash -c '…'`, `eval "…"`) is one opaque token to
+ * the outer parse, so it is re-parsed on its own and the recovered spans are
+ * shifted onto the command as written. The widening is restricted to the
+ * payloads the wrapper analyzer already identifies as shell: a heredoc body is
+ * not one, and applying these rules to the 915 `<<'EOF'` bodies in the same
+ * corpus matched six commands, every one embedded Python or TypeScript written
+ * to a file (#923).
  */
 
 /** The log keys whose value is a bash command string. */
@@ -55,20 +68,167 @@ export function redactCommandSecrets(command: string): string {
   try {
     const parser = getWarmBashParser();
     if (!parser) return command;
-    const tree = parser.parse(command);
-    if (!tree) return command;
-    try {
-      const spans: MaskSpan[] = [];
-      collectMaskSpans(tree.rootNode, spans);
-      return applyMaskSpans(command, spans);
-    } finally {
-      tree.delete();
-    }
+    return applyMaskSpans(command, collectSpansIn(parser, command, 0, 0));
   } catch {
     return command;
   }
 }
 
+/**
+ * Every mask span in `source`, shifted by `offset` to its place in the command
+ * being masked, including the spans of any inline-shell payload `source`
+ * carries.
+ *
+ * A payload is re-parsed from its **verbatim inner slice** rather than
+ * `resolveNodeText`'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.
+ *
+ * `parser` is the narrow {@link BashReparser} rather than the warmed parser's own
+ * type, so the recursion structurally cannot `delete()` the process-wide parser
+ * out from under every later command — the same reason `unresolved-salvage.ts`
+ * takes that interface.
+ */
+function collectSpansIn(
+  parser: BashReparser,
+  source: string,
+  offset: number,
+  depth: number,
+): MaskSpan[] {
+  const tree = parser.parse(source);
+  if (!tree) return [];
+  try {
+    const own: MaskSpan[] = [];
+    collectMaskSpans(tree.rootNode, own);
+    const spans = own.map((span) => ({
+      ...span,
+      start: span.start + offset,
+      end: span.end + offset,
+    }));
+    if (depth >= MAX_PAYLOAD_DEPTH) return spans;
+    for (const payload of inlineShellPayloads(tree.rootNode)) {
+      const sliced = payload.kind === "slice";
+      const inner = collectSpansIn(
+        parser,
+        payload.text,
+        sliced ? offset + payload.start : 0,
+        depth + 1,
+      );
+      if (sliced) spans.push(...inner);
+      else if (inner.length > 0) spans.push(wholeOf(payload, offset));
+    }
+    return spans;
+  } finally {
+    tree.delete();
+  }
+}
+
+/**
+ * How many payload layers to descend.
+ *
+ * A payload is a strict sub-span of its own command, so the recursion terminates
+ * regardless; the bound is what makes its cost statable, and it matches the
+ * unwrap depth `wrapper-analysis.ts` already applies to nested wrappers.
+ */
+const MAX_PAYLOAD_DEPTH = 4;
+
+/**
+ * An inline-shell payload's program, and how a span found in it maps back onto
+ * the command being masked.
+ *
+ * `"slice"` — the program is a verbatim span of the command: a bare word, or
+ * literal text inside one pair of quotes. A span found in it shifts onto the
+ * command by the constant {@link PayloadSource.start}.
+ *
+ * `"stitched"` — the program is assembled across quote boundaries
+ * (`bash -c 'TOKEN='"$SECRET"`, one `concatenation` node), so no constant shift
+ * exists and an offset into the program names nothing in the command. The
+ * program still decides *whether* a secret is bound inside, so the whole
+ * argument is masked when one is — coarser than a slice, and the alternative is
+ * writing the secret.
+ */
+interface PayloadSource {
+  readonly kind: "slice" | "stitched";
+  readonly text: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+/** The span covering a stitched payload argument whole, quotes included. */
+function wholeOf(payload: PayloadSource, offset: number): MaskSpan {
+  return {
+    start: payload.start + offset,
+    end: payload.end + offset,
+    replacement: REDACTED_PLACEHOLDER,
+  };
+}
+
+function inlineShellPayloads(root: TSNode): PayloadSource[] {
+  const payloads: PayloadSource[] = [];
+  collectInlineShellPayloads(root, payloads);
+  return payloads;
+}
+
+function collectInlineShellPayloads(
+  node: TSNode,
+  payloads: PayloadSource[],
+): void {
+  if (node.type === "command") {
+    const payload = inlineShellPayloadNode(node);
+    if (payload) payloads.push(payloadSourceOf(payload));
+  }
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) collectInlineShellPayloads(child, payloads);
+  }
+}
+
+/**
+ * The program a payload node carries, sliced where the grammar spells it as one
+ * contiguous run of the command and stitched where it does not.
+ *
+ * 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
+ * value's own offsets describe no span of the command.
+ */
+function payloadSourceOf(node: TSNode): PayloadSource {
+  const bounds = { start: node.startIndex, end: node.endIndex };
+  if (node.type === "word") {
+    return { kind: "slice", text: node.text, ...bounds };
+  }
+
+  const text = node.text;
+  const quoteAt = text.startsWith("$") ? 1 : 0;
+  const quote = text.at(quoteAt);
+  const singlyQuoted =
+    SINGLY_QUOTED_PAYLOAD_TYPES.has(node.type) &&
+    (quote === "'" || quote === '"') &&
+    text.length >= quoteAt + 2 &&
+    text.endsWith(quote);
+
+  return singlyQuoted
+    ? {
+        kind: "slice",
+        text: text.slice(quoteAt + 1, -1),
+        start: node.startIndex + quoteAt + 1,
+        end: node.endIndex - 1,
+      }
+    : { kind: "stitched", text: resolveNodeText(node), ...bounds };
+}
+
+/**
+ * Payload node types whose program sits inside exactly one pair of quotes, so
+ * removing them (and a leading `$`) leaves a verbatim span of the command.
+ */
+const SINGLY_QUOTED_PAYLOAD_TYPES: ReadonlySet<string> = new Set([
+  "string",
+  "raw_string",
+  "ansi_c_string",
+]);
+
 /**
  * Apply {@link redactCommandSecrets} to every command-bearing key in a log
  * record.