@gotgenes/pi-permission-system 33.0.5 → 33.0.7

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.7](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.0.6...pi-permission-system-v33.0.7) (2026-09-22)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** stop a second permission ask from replacing the first ([e01fca6](https://github.com/gotgenes/pi-packages/commit/e01fca6f40a836e41286306b092db03f53601b54))
+* **pi-permission-system:** answer pending permission asks when the session ends ([e0eb7f8](https://github.com/gotgenes/pi-packages/commit/e0eb7f8b6c511bf874d48d241f28c5bc5f7f6aee))
+
+### Documentation
+
+* **pi-permission-system:** document per-session ask serialization ([fa3a16a](https://github.com/gotgenes/pi-packages/commit/fa3a16a48e7919ae5eed2a82caec83ce9bd9c755))
+
+## [33.0.6](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.0.5...pi-permission-system-v33.0.6) (2026-09-22)
+
+
+### Documentation
+
+* snapshot fallow vital signs per package and trend them at phase close ([bc8bbc3](https://github.com/gotgenes/pi-packages/commit/bc8bbc34e32f30c99260aaa05a044df3f445857a)), closes [#966](https://github.com/gotgenes/pi-packages/issues/966)
+
 ## [33.0.5](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.0.4...pi-permission-system-v33.0.5) (2026-09-20)
 
 

package/README.md

@@ -20,8 +20,8 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
 - **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry and a matching `permissions:decision` broadcast), and a bash command the parser could not resolve, in whole or in part — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently, unless the wrapped command is a pure reader whose direction is provable whatever it is fed (`xargs grep -l foo`); where a partial parse failure's own region re-parses cleanly on its own, the commands and paths it holds are recovered and gated rather than merely prompted for
-- **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
-- **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI, and every prompt it announces — including one forwarded up from a subagent — is answered by a `permissions:decision` on the same bus
+- **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts, and a forwarded prompt queues behind whatever dialog is already open instead of replacing it
+- **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI (for a queued ask, when its turn comes rather than when it was raised), and every prompt it announces — including one forwarded up from a subagent — is answered by a `permissions:decision` on the same bus
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration
 
 ## Install

package/docs/cross-extension-api.md

@@ -384,6 +384,8 @@ Policy decisions that resolve without an active UI prompt, such as `policy_allow
 Non-UI child sessions also do not emit this event when they create a forwarded permission request; the parent UI session emits it immediately before showing the forwarded permission dialog.
 A forwarded request the parent's own recorded policy decides (a matching `allow` or `deny`) is answered without a prompt and emits no event; the event fires only when the parent is actually about to ask the human.
 The matching terminal `permissions:decision` is emitted in the parent session too, so a consumer that reacts to this event has a signal on the same bus telling it the prompt is over.
+Asks are presented one at a time: the host holds a single inline dialog slot, so a session that raises a second ask while one is still open queues it rather than mounting over the first.
+The event marks the moment the queued ask is presented, not the moment it was raised, which is what keeps "the user needs to respond now" true for a consumer that alerts on it.
 Forwarded prompts that do reach the human are not degraded: the parent emits the child's original `source` and the same `surface`/`value` display projection, plus a populated `forwarding` context identifying the requesting subagent.
 
 The payload is lean by design — `surface`/`value` are the normalized display projection a notification consumer reads, not a mirror of the internal review log.

package/package.json

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

package/src/authority/ask-dialog-queue.ts

@@ -0,0 +1,145 @@
+/**
+ * The shutdown-facing slice of {@link AskDialogQueue}: settle everything this
+ * session still owes an answer for.
+ *
+ * Narrow on purpose (ISP) — the lifecycle handler releases asks and never
+ * admits one.
+ */
+export interface AskDialogRelease {
+  releaseAll(reason: string): void;
+}
+
+/**
+ * The admission-facing slice of {@link AskDialogQueue}: present this ask once
+ * every earlier one has settled.
+ *
+ * The terminal that shows a dialog admits asks and never releases them, and
+ * depending on the slice rather than the class keeps the queue's private state
+ * out of its dependency type.
+ */
+export interface AskDialogAdmission {
+  run<T>(
+    present: () => Promise<T>,
+    released: (reason: string) => T,
+  ): Promise<T>;
+}
+
+/**
+ * Serializes the human-facing presentations one session owns.
+ *
+ * Pi's inline `ctx.ui.custom` slot holds one component: a second presentation
+ * clears the editor container and mounts over the first, whose promise then
+ * never settles and whose component is never disposed. This extension raises
+ * asks from two independent tasks — the gate's local ask and the forwarded ask
+ * a poll tick drains — so without a queue whichever arrives second silently
+ * strands the first, and a forwarded ask stranded that way holds the
+ * forwarding inbox closed behind it (#965).
+ *
+ * The queue cannot see the host's slot, so its contract is only that it never
+ * lets two of *its own* presentations overlap. A presentation another
+ * extension mounts is outside its evidence; upstream declined to arbitrate
+ * globally (earendil-works/pi#7007), so that case stays open by design.
+ *
+ * Logger-free, following `transient-fs-retry.ts`: `PermissionPrompter` already
+ * brackets each ask with review entries, so a queue wait reads as the gap
+ * between them and a released ask reads as its terminal entry.
+ */
+export class AskDialogQueue implements AskDialogAdmission, AskDialogRelease {
+  /** Settles once every ask admitted so far has been presented or released. */
+  private tail: Promise<void> = Promise.resolve();
+  /**
+   * The asks that still owe their caller a value, queued and in-flight alike.
+   * Typed as the release capability rather than `AdmittedAsk<unknown>` so the
+   * set does not have to name a value type it never reads.
+   */
+  private readonly outstanding = new Set<{ release(reason: string): void }>();
+
+  /**
+   * Admit an ask, presenting it only once every earlier one has settled.
+   *
+   * `released` is the caller's own fallback, supplied at admission: the queue
+   * never constructs a decision, because a decision is stamped at the site
+   * that decides and the queue does not know what it is presenting.
+   */
+  run<T>(
+    present: () => Promise<T>,
+    released: (reason: string) => T,
+  ): Promise<T> {
+    const ask = new AdmittedAsk(released);
+    this.outstanding.add(ask);
+    this.tail = this.tail.then(async () => {
+      // A release while this ask waited its turn means nothing may render:
+      // presenting it now would put a dialog on screen for a decision that
+      // has already been answered.
+      if (ask.isSettled) {
+        return;
+      }
+      try {
+        ask.settle(await present());
+      } catch (error) {
+        ask.fail(error);
+      } finally {
+        this.outstanding.delete(ask);
+      }
+    });
+    return ask.decision;
+  }
+
+  /**
+   * Settle every outstanding ask with its own released value.
+   *
+   * The tail is reset rather than chained on, because the in-flight ask's
+   * presentation is still pending in the host and nothing would ever settle
+   * it — a session that keeps running must not queue behind a dialog nobody
+   * can answer.
+   */
+  releaseAll(reason: string): void {
+    const releasing = [...this.outstanding];
+    this.outstanding.clear();
+    this.tail = Promise.resolve();
+    for (const ask of releasing) {
+      ask.release(reason);
+    }
+  }
+}
+
+/**
+ * One admitted ask and the promise its caller is holding.
+ *
+ * A release while a presentation is in flight leaves the host's own promise
+ * pending, and it may resolve later; that late answer is discarded because the
+ * caller's promise has already settled. `settled` is therefore read rather
+ * than enforced — it is what lets the queue skip presenting an ask that was
+ * released while it waited its turn.
+ */
+class AdmittedAsk<T> {
+  readonly decision: Promise<T>;
+  private settled = false;
+  private readonly resolve: (value: T) => void;
+  private readonly reject: (error: unknown) => void;
+
+  constructor(private readonly released: (reason: string) => T) {
+    const { promise, resolve, reject } = Promise.withResolvers<T>();
+    this.decision = promise;
+    this.resolve = resolve;
+    this.reject = reject;
+  }
+
+  get isSettled(): boolean {
+    return this.settled;
+  }
+
+  settle(value: T): void {
+    this.settled = true;
+    this.resolve(value);
+  }
+
+  fail(error: unknown): void {
+    this.settled = true;
+    this.reject(error);
+  }
+
+  release(reason: string): void {
+    this.settle(this.released(reason));
+  }
+}

package/src/authority/authorizer.ts

@@ -3,6 +3,7 @@ import type { DebugReviewLogger } from "#src/logging/session-logger";
 import type { AuthorizerLog, PermissionQuery } from "#src/service";
 import type { PermissionEventBus } from "#src/service/permission-events";
 import { ParentAuthorizer } from "./approval-escalator";
+import type { AskDialogAdmission } from "./ask-dialog-queue";
 import { DenyingAuthorizer } from "./denying-authorizer";
 import { getSessionId } from "./forwarder-context";
 import type { TargetServingLookup } from "./forwarding-liveness";
@@ -110,6 +111,13 @@ export interface AuthorizerSelectionDeps {
   detection: SubagentDetector;
   /** Event bus used by `LocalUserAuthorizer` for the `permissions:ui_prompt` broadcast. */
   events: PermissionEventBus;
+  /**
+   * The session's dialog queue, threaded into `LocalUserAuthorizer`.
+   *
+   * Shared rather than owned by the terminal, because a terminal is rebuilt on
+   * every activation and a per-activation queue would serialize nothing (#965).
+   */
+  dialogs: AskDialogAdmission;
   /** Read live at prompt time; threaded into `LocalUserAuthorizer`. */
   getPromptPreferences: () => PromptPreferences;
   /** Injected for testability; production callers pass the real function. */
@@ -147,6 +155,7 @@ export function selectAuthorizer(
           ui: ctx.ui,
           mode: ctx.mode,
           events: deps.events,
+          dialogs: deps.dialogs,
           getPromptPreferences: deps.getPromptPreferences,
           requestPermissionDecision: deps.requestPermissionDecision,
         }),

package/src/authority/local-user-authorizer.ts

@@ -10,6 +10,7 @@ import {
 } from "#src/service/permission-events";
 import { buildUiPrompt } from "#src/service/permission-ui-prompt";
 import { provenDirectionOf } from "#src/session/approval-grant";
+import type { AskDialogAdmission } from "./ask-dialog-queue";
 import type { TerminalAuthorizer } from "./authorizer";
 import type {
   PermissionPromptDecision,
@@ -30,6 +31,8 @@ export interface LocalUserAuthorizerDeps {
   mode: ExtensionContext["mode"];
   /** Event bus used for the `permissions:ui_prompt` broadcast. */
   events: PermissionEventBus;
+  /** Serializes this session's dialogs so no ask replaces another (#965). */
+  dialogs: AskDialogAdmission;
   /** Read live at prompt time so a settings-modal toggle takes effect on the next prompt. */
   getPromptPreferences: () => PromptPreferences;
   /** Injected for testability; production callers pass the real function. */
@@ -45,6 +48,10 @@ export interface LocalUserAuthorizerDeps {
  * forwarded ask carries its provenance on `details.forwarding`, which this
  * class renders (populated `forwarding` context + "(Subagent)" title) so the
  * broadcast stays non-degraded (#292) without a second emission path.
+ *
+ * Every ask goes through the session's `AskDialogAdmission`, because the host
+ * holds one inline dialog slot: a second presentation mounts over the first and
+ * strands its promise (#965).
  */
 export class LocalUserAuthorizer implements TerminalAuthorizer {
   constructor(private readonly deps: LocalUserAuthorizerDeps) {}
@@ -52,8 +59,24 @@ export class LocalUserAuthorizer implements TerminalAuthorizer {
   authorize(
     details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision> {
-    const uiPrompt = buildUiPrompt(details);
-    emitUiPromptEvent(this.deps.events, uiPrompt);
+    return this.deps.dialogs.run(
+      () => this.present(details),
+      unansweredDecision,
+    );
+  }
+
+  /**
+   * Announce the imminent prompt, then show it.
+   *
+   * Both live inside the queued region: `permissions:ui_prompt` is documented
+   * as firing immediately before the user-facing UI is invoked, so an emit at
+   * admission would alert a notification consumer for a dialog that is still
+   * minutes of deliberation away.
+   */
+  private present(
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision> {
+    emitUiPromptEvent(this.deps.events, buildUiPrompt(details));
     return this.deps.requestPermissionDecision(
       {
         mode: this.deps.mode,
@@ -69,6 +92,25 @@ export class LocalUserAuthorizer implements TerminalAuthorizer {
   }
 }
 
+/**
+ * The answer an ask gets when the session released it before a human ruled.
+ *
+ * Mirrors `ParentAuthorizer`'s abandonment: `confirmationUnavailable` keeps it
+ * out of the "User denied" family, since a user who was never asked denied
+ * nothing (#719), and the agent-facing reason and the provenance record reuse
+ * one string so what the model is told and what the log attributes cannot
+ * drift (#726).
+ */
+function unansweredDecision(reason: string): PermissionPromptDecision {
+  return {
+    approved: false,
+    state: "denied",
+    confirmationUnavailable: true,
+    denialReason: reason,
+    decidedBy: { kind: "unavailable", reason },
+  };
+}
+
 /**
  * The dialog options this ask offers, composed from three independent groups.
  *

package/src/handlers/lifecycle.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AskDialogRelease } from "#src/authority/ask-dialog-queue";
 import type { ConfigIssueReporting } from "#src/config/config-issue-reporter";
 import { PERMISSION_SYSTEM_STATUS_KEY } from "#src/config/status";
 import type { DecisionSummaryWriter } from "#src/logging/decision-audit";
@@ -21,6 +22,15 @@ interface ResourcesDiscoverPayload {
  * Shown when project config is skipped because the project is untrusted, so the
  * reduced-scope state is never silent (#644). Exported for assertion in tests.
  */
+/**
+ * What a permission request still open at shutdown is answered with.
+ *
+ * Reaches the agent as the block reason and the review log as the decider's
+ * `reason`, so both name the same thing (#726).
+ */
+export const SESSION_ENDED_REASON =
+  "The session ended before this permission request was answered";
+
 export const UNTRUSTED_PROJECT_MESSAGE =
   "pi-permission-system: project is not trusted — skipping project-scoped " +
   "permission configuration. Only global policy applies. Grant project trust " +
@@ -40,6 +50,8 @@ export const UNTRUSTED_PROJECT_MESSAGE =
  * - `configIssues` — reports what is wrong with the extension config, latched
  *   per issue; driven here and on every turn, so an issue already on disk when
  *   the session opens is shown rather than swallowed (#933)
+ * - `dialogs` — the session's ask queue, released on shutdown so a gate waiting
+ *   on a dialog nobody can answer any more is unblocked (#965)
  */
 export class SessionLifecycleHandler {
   constructor(
@@ -49,6 +61,7 @@ export class SessionLifecycleHandler {
     private readonly logger: SessionLogger,
     private readonly audit: DecisionSummaryWriter,
     private readonly configIssues: ConfigIssueReporting,
+    private readonly dialogs: AskDialogRelease,
   ) {}
 
   handleSessionStart(
@@ -131,6 +144,9 @@ export class SessionLifecycleHandler {
       ctx.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
     }
     this.audit.writeSummary(this.logger);
+    // Ahead of the session shutdown that stops forwarding: a drain awaiting a
+    // forwarded ask can only write its response file once that ask is settled.
+    this.dialogs.releaseAll(SESSION_ENDED_REASON);
     this.session.shutdown();
     this.serviceLifecycle.teardown();
     return Promise.resolve();

package/src/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
 import { warmBashParser } from "#src/access-intent/bash/parser";
 import { buildResolvedIntentFromMatchValues } from "#src/access-intent/input-normalizer";
+import { AskDialogQueue } from "#src/authority/ask-dialog-queue";
 import { AuthorizerChainAudit } from "#src/authority/authorizer-chain-audit";
 import {
   AuthorizerRegistry,
@@ -132,6 +133,11 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const prompter = new PermissionPrompter({ logger });
 
+  // One queue per factory invocation, so it is rebuilt with the session rather
+  // than outliving it: the host holds a single inline dialog slot, and a second
+  // presentation there strands the first ask's promise (#965).
+  const askDialogQueue = new AskDialogQueue();
+
   // The filesystem half of the serving announcement. `servingRegistry` reaches
   // an in-process child through `globalThis`; a child in its own process shares
   // nothing but this directory, so the served session publishes a heartbeat
@@ -149,6 +155,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const authorizerSelection = new AuthorizerSelection({
     detection: subagentDetection,
     events: pi.events,
+    dialogs: askDialogQueue,
     getPromptPreferences: () => ({
       doublePressToConfirm: configStore.current().doublePressToConfirm,
       budget: resolveRenderBudget(configStore.current()),
@@ -321,6 +328,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     logger,
     audit,
     configIssueReporter,
+    askDialogQueue,
   );
   const turnPrep = new SessionTurnPrep(
     session,