@hank-warren/pi-auto-permissions 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @hank-warren/pi-auto-permissions
 
+## 0.16.0
+
+### Minor Changes
+
+- c079c51: Serialize guardian-backed reviews, show a queued command instead of a blank gap, and stage `request_override`.
+
+  Two guarded commands issued in the same assistant turn used to open two reviewer conversations at once and race for the same widget and bash review row, letting the second verdict land against the first command's display. Guardian reviews now run one at a time behind a FIFO queue. Denies, convention blocks, trusted commands, and already-approved execution never enter it, so the ordinary path is unchanged.
+
+  Because the critical section spans the human approval prompt, a queued command now renders a `queued behind another review` row as soon as it starts waiting, and the wait is cancellable: `Esc` or a reviewer-lifecycle reset releases it immediately instead of stranding it behind a review it is no longer waiting for. An aborted waiter never lets the command behind it overtake the review still in progress.
+
+  `request_override` activates only after a convention denial in an interactive session, so a session that is never blocked does not carry its schema. The tool stays registered for transcript replay.
+
 ## 0.15.0
 
 ### Minor Changes

package/index.ts

@@ -3,6 +3,7 @@ import { resolveGuardianCompleteSimple } from "./guardian-transport.js";
 import { isOpenAICodexModel } from "./openai-codex-transport.js";
 import { detectSubagentContext } from "./subagent-context.js";
 import { detectLoopContext } from "./loop-context.js";
+import { createReviewQueue } from "./review-queue.js";
 import {
   LoopReviseBudget,
   loopBlockReason,
@@ -318,9 +319,28 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   const permissionOverrides: PermissionOverride[] = [];
   let overrideSeq = 0;
   let standingApprovalCapNotified = false;
+  let overrideToolActivated = false;
+  const guardianReviewQueue = createReviewQueue();
   /** Captured once per session; see session-environment.ts for why once. */
   let sessionEnvironment: SessionEnvironmentSnapshot | undefined;
 
+  function reconcileOverrideTool(): void {
+    if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+    const active = pi.getActiveTools();
+    const present = active.includes("request_override");
+    if (overrideToolActivated === present) return;
+    pi.setActiveTools(
+      overrideToolActivated
+        ? [...active, "request_override"]
+        : active.filter((name) => name !== "request_override"),
+    );
+  }
+
+  function activateOverrideTool(): void {
+    overrideToolActivated = true;
+    reconcileOverrideTool();
+  }
+
   /**
    * Overrides persist as custom session entries the way the loop budget does,
    * so a resumed session keeps the user's prompt decisions instead of
@@ -1276,6 +1296,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     }
     const convention = matches.find((gate) => gate.level === "convention");
     if (convention && !allowedConventionCommands.has(command)) {
+      if (ctx.hasUI) activateOverrideTool();
       recordDenial(
         config,
         ctx,
@@ -1299,10 +1320,32 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     }
     if (!gate) return;
 
-    const signal = ctx.signal;
-    showReviewDisplay(ctx, config, gate, command, target, "waiting");
+    // Show the queued row *before* waiting, and only when there is actually
+    // something to wait for: the critical section spans the human prompt, so a
+    // second guarded command in the same turn can sit here for as long as it
+    // takes someone to answer. Rendering nothing for that whole time reads as a
+    // hang. A lone review never flashes this, because the queue is idle.
+    if (guardianReviewQueue.busy) {
+      showReviewDisplay(ctx, config, gate, command, target, "queued");
+    }
+    // Same composite the ask path builds, so Esc and a reviewer-lifecycle reset
+    // both release a queued command instead of stranding it behind a review it
+    // is no longer waiting for.
+    const queueSignal = ctx.signal ? AbortSignal.any([ctx.signal, lifecycleSignal]) : lifecycleSignal;
+    let releaseReviewSlot: () => void;
+    try {
+      releaseReviewSlot = await guardianReviewQueue.acquire(queueSignal);
+    } catch {
+      return { block: true, reason: "Auto Permissions review cancelled" };
+    }
     try {
-      const verdict = await reviewCommand(
+      if (lifecycleStale() || reviewCancelled(ctx.signal)) {
+        return { block: true, reason: "Auto Permissions review cancelled" };
+      }
+      const signal = ctx.signal;
+      showReviewDisplay(ctx, config, gate, command, target, "waiting");
+      try {
+        const verdict = await reviewCommand(
         gate,
         event.toolName,
         event.toolCallId,
@@ -1389,17 +1432,20 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
           reason: `${gate.label} could not be reviewed (${reason}), and this session is running an unattended /loop, so there is no one to ask. Do not retry the same command hoping the reviewer recovers: call loop_wait naming the reviewer failure, or advance the objective another way.`,
         };
       }
-      return askUser(
-        gate,
-        command,
-        `Automatic review failed: ${reason}`,
-        config,
-        signal,
-        ctx,
-        target,
-        lifecycleSignal,
-        "review_failure",
-      );
+        return askUser(
+          gate,
+          command,
+          `Automatic review failed: ${reason}`,
+          config,
+          signal,
+          ctx,
+          target,
+          lifecycleSignal,
+          "review_failure",
+        );
+      }
+    } finally {
+      releaseReviewSlot();
     }
   });
 
@@ -1491,6 +1537,11 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     },
   });
 
+  // The override schema is useful only after a convention denial has named an
+  // exact command. It is kept registered for replay and narrowed out of the
+  // active set at session_start — never here, because Pi refuses action methods
+  // during extension loading.
+
   /**
    * `/auto-permissions`: edit the reviewer model, thinking level, timeout and
    * the enabled flag without hand-editing config.json.
@@ -1722,6 +1773,8 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    overrideToolActivated = false;
+    reconcileOverrideTool();
     warnAboutMissingReviewerProvider(ctx);
 
     reviewerLifecycleController.abort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-auto-permissions",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Fork of @ogulcancelik/pi-auto-permissions with dialog-answer user evidence: context-aware Bash permissions for Pi with automated guardian review.",
   "type": "module",
   "keywords": [
@@ -58,6 +58,7 @@
     "gates.ts",
     "override-evidence.ts",
     "review.ts",
+    "review-queue.ts",
     "session-environment.ts",
     "standing-overrides.ts",
     "usage-log.ts",

package/review-queue.ts

@@ -0,0 +1,103 @@
+/**
+ * FIFO serialization for guardian-backed reviews.
+ *
+ * Two guarded commands issued in the same assistant turn used to open two
+ * reviewer conversations at once, which raced for the same widget/bash review
+ * row and let the second verdict land against the first command's display. The
+ * queue serializes the *decisions* only: denies, convention blocks, trusted
+ * commands and already-approved execution never enter it.
+ *
+ * Every acquirer releases in a `finally`, and a release that throws (or is
+ * never observed) must not poison later requests — so the tail is always a
+ * settled-or-settling promise that swallows rejection.
+ *
+ * The critical section spans the human prompt as well as the model call, which
+ * is deliberate: two approval dialogs fighting over one surface is the thing
+ * this exists to prevent. That makes the wait unbounded in wall-clock time, so
+ * it is cancellable (`acquire(signal)`) and visible (`busy`, which the caller
+ * uses to render a "queued" row instead of a blank gap).
+ */
+export interface ReviewQueue {
+	/**
+	 * Waits for the queue, then returns the release function for this slot.
+	 *
+	 * Rejects with the signal's reason if `signal` aborts first. An aborted
+	 * waiter never takes the slot, and never lets the next waiter overtake the
+	 * live holder — see the catch in the implementation.
+	 */
+	acquire(signal?: AbortSignal): Promise<() => void>;
+	/** Slots currently waiting, excluding the one holding the queue. */
+	readonly waiting: number;
+	/** True while a slot is held, so a caller can show a queued state. */
+	readonly busy: boolean;
+}
+
+export function createReviewQueue(): ReviewQueue {
+	let tail: Promise<void> = Promise.resolve();
+	let waiting = 0;
+	let held = 0;
+
+	return {
+		async acquire(signal?: AbortSignal): Promise<() => void> {
+			signal?.throwIfAborted();
+			const previous = tail;
+			let release = () => {};
+			tail = new Promise<void>((resolve) => {
+				release = resolve;
+			});
+			let released = false;
+			const releaseOnce = () => {
+				if (released) return;
+				released = true;
+				held -= 1;
+				release();
+			};
+			waiting += 1;
+			try {
+				await (signal ? raceAbort(previous, signal) : previous.catch(() => undefined));
+			} catch (error) {
+				// Keep the chain intact: our slot resolves when the one ahead of us
+				// does, so an aborted waiter never lets the next one overtake the live
+				// holder. Resolving `release()` here instead would hand the queue to
+				// the next waiter while the current holder is still inside its
+				// critical section — silently undoing the mutual exclusion this class
+				// exists to provide.
+				released = true;
+				void previous.catch(() => undefined).then(release);
+				throw error;
+			} finally {
+				waiting -= 1;
+			}
+			held += 1;
+			return releaseOnce;
+		},
+		get waiting() {
+			return waiting;
+		},
+		get busy() {
+			return held > 0;
+		},
+	};
+}
+
+/**
+ * Resolve when `previous` settles, or reject when `signal` aborts.
+ *
+ * The listener is always removed: a session-lifetime signal outlives many
+ * reviews, and one dangling listener per queued command is a slow leak that
+ * would only show up under exactly the load this queue was added to handle.
+ */
+function raceAbort(previous: Promise<void>, signal: AbortSignal): Promise<void> {
+	return new Promise<void>((resolve, reject) => {
+		const onAbort = () => {
+			cleanup();
+			reject(signal.reason);
+		};
+		const cleanup = () => signal.removeEventListener("abort", onAbort);
+		signal.addEventListener("abort", onAbort, { once: true });
+		previous.catch(() => undefined).then(() => {
+			cleanup();
+			resolve();
+		}, cleanup);
+	});
+}

package/widget-status.ts

@@ -4,9 +4,15 @@
  * free of TUI dependencies so they are unit-testable.
  */
 
-export type ReviewDisplayState = "waiting" | "approved" | "revise" | "ask_user" | "blocked";
+export type ReviewDisplayState =
+  | "queued"
+  | "waiting"
+  | "approved"
+  | "revise"
+  | "ask_user"
+  | "blocked";
 
-export type ReviewStatusTone = "warning" | "success" | "accent" | "error";
+export type ReviewStatusTone = "muted" | "warning" | "success" | "accent" | "error";
 
 export interface ReviewStatusFrame {
   glyph: string;
@@ -26,6 +32,17 @@ export function reviewStatusFrame(
 ): ReviewStatusFrame {
   const index = Math.max(0, Math.floor(frameIndex));
   switch (state) {
+    // Static rather than animated: the row is replaced by `waiting` the moment
+    // the queue hands over, so a spinner here would promise progress the
+    // command is not making. It exists so a second guarded command in one turn
+    // renders *something* instead of a blank gap while it waits its turn.
+    case "queued":
+      return {
+        glyph: "⋯",
+        label: "queued behind another review",
+        tone: "muted",
+        done: true,
+      };
     case "waiting":
       return {
         glyph: WAITING_FRAMES[index % WAITING_FRAMES.length],