@bacnh85/pi-advisor 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.2.3 (2026-09-11)
+
+- **Fix 20–30s+ TUI freeze after every settled turn**: pi core awaits
+  `agent_settled` handlers before the prompt regains input, and the advisor
+  review (a full model call — measured median ~11s, p90 ~96s) ran inside that
+  awaited barrier, freezing the TUI — most visibly after `write_plan`, where
+  the prefilled `/plan-approve` was dead until the review finished. The review
+  now runs fire-and-forget: notes deliver via `sendUserMessage`, which the SDK
+  queues as a steer when a run is already active or fires as a follow-up turn
+  when idle. A still-running review makes the next settle skip (bounded loss).
+- **Watch is skipped in headless modes** (print/rpc/json): a floating review
+  would die at process exit, and a note there fired an unrequested follow-up
+  agent run. The on-demand `/advisor` consult tool is unaffected.
+- **Hardened against stale/edge contexts** (review follow-up): a review still
+  in flight when a new session starts is silently discarded instead of
+  steering the new session; the in-flight guard moved to per-runtime state so
+  a draining old review can't suppress the new session's first review; a
+  mode-less context is treated as headless (fail-safe skip).
+- **Delivery-time liveness + teardown self-disarm** (final review round): a
+  review in flight across `/new`, `/resume`, `/fork`, `/reload`, or quit is
+  discarded silently — `session_shutdown` disarms the watch before the runner
+  invalidates, so no stale-ctx error toast lands in the replaced session; the
+  pause toast routes through the same liveness gate; the watch-disabled state
+  mid-review (`/advisor off`, `watch-off`) also suppresses delivery.
+
 ## 0.2.2 (2026-09-07)
 
 - **Fix TUI hang on stalled reviewer provider**: every chain candidate now

package/README.md

@@ -68,7 +68,7 @@ Settings live in `~/.pi/agent/settings.json` (global) and `.pi/settings.json`
   time, the next candidate serves automatically; a whole-chain failure counts
   as one review failure (the 3-strike pause still applies). The advisor never
   falls back to the primary model — it must never review its own turns.
-- `watch.enabled` (default `true`) — turn-end reviewing on session start
+- `watch.enabled` (default `true`) — turn-end reviewing on session start (TUI only — print/rpc/json runs skip the watch; the on-demand advisor tool still works)
 - `watch.minToolCalls` (default `3`, `0` = every turn) — skip trivial turns
 - `watch.immuneTurns` (default `3`) — review window during which the same
   normalized note is not re-delivered (loop protection); distinct concerns and

package/extensions/index.ts

@@ -70,7 +70,9 @@ export default function piAdvisor(pi: ExtensionAPI): void {
   }
 
   pi.on("before_agent_start", (event, ctx: ExtensionContext): any => {
-    if (!watchEnabled || !runtime || runtime.models.length === 0 || runtime.stats.paused) return;
+    // Headless runs can't receive watch notes anymore — don't make them pay
+    // dead prompt text claiming otherwise.
+    if (ctx.mode !== "tui" || !watchEnabled || !runtime || runtime.models.length === 0 || runtime.stats.paused) return;
     // Every turn the agent sees the authority line (static per session,
     // cache-safe): messages starting 'Advisor review' are reviewer findings.
     const line = "Advisor notes: messages starting 'Advisor review' are authoritative reviewer findings. Fix or explicitly justify ignoring each finding.";
@@ -108,13 +110,39 @@ export default function piAdvisor(pi: ExtensionAPI): void {
     runtime.cursor = entries.length ? entries[entries.length - 1].id : undefined;
   });
 
+  // Self-disarm on session teardown: session_shutdown is emitted and awaited
+  // BEFORE the runner invalidates (agent-session-runtime teardownCurrent), so
+  // flipping the flag here makes live() false in this (about-to-be-orphaned)
+  // closure — an in-flight fire-and-forget review is discarded silently
+  // instead of throwing the stale-ctx error into the .catch and toasting the
+  // NEW session. The factory re-runs per session, so this never touches a
+  // live session's flag.
+  pi.on("session_shutdown", () => { watchEnabled = false; });
+
   pi.on("agent_settled", async (_event, ctx) => {
     if (!runtime || !watchEnabled || runtime.stats.paused) return;
-    await reviewTurn(runtime, ctx, {
-      sendMessage: (message, options) => pi.sendMessage(message, options as never),
-      sendUserMessage: (content, options) => pi.sendUserMessage(content, options),
-      appendEntry: (customType, data) => pi.appendEntry(customType, data),
-    }, testIsolated);
+    // Only TUI: a floating review would die at process exit in headless
+    // modes, and a note there fired an unrequested follow-up run. Fail-safe:
+    // unknown/mode-less contexts skip too (missed review < surprise run).
+    if (ctx.mode !== "tui") return;
+    // ponytail: fire-and-forget — pi core awaits agent_settled handlers before
+    // the TUI regains input, so awaiting the 10-90s+ review here froze the UI
+    // after every turn. Notes deliver via sendUserMessage, which the SDK
+    // queues as a steer when a run is active or fires as a follow-up turn
+    // when idle. A still-running review makes the next settle skip (rt
+    // reviewing flag) — bounded loss, not queued.
+    const rt = runtime;
+    // Liveness guard evaluated at delivery time (not just settle time): a
+    // fresh session (/new) replaces runtime, /advisor off clears the chain,
+    // watch-off flips the flag, repeated failures pause — a review in flight
+    // across any of these must deliver nothing.
+    const live = () => runtime === rt && watchEnabled && rt.models.length > 0 && !rt.stats.paused;
+    void reviewTurn(rt, ctx, {
+      sendMessage: (message, options) => { if (live()) pi.sendMessage(message, options as never); },
+      sendUserMessage: (content, options) => { if (live()) pi.sendUserMessage(content, options); },
+      appendEntry: (customType, data) => { if (live()) pi.appendEntry(customType, data); },
+      notify: (message) => { if (live()) ctx.ui.notify(message, "error"); },
+    }, testIsolated).catch((err) => { if (live()) ctx.ui.notify(`Advisor review failed: ${String(err)}`, "error"); });
   });
 
   registerAdvisor(pi, {

package/extensions/lib/watcher.ts

@@ -49,13 +49,16 @@ export interface WatcherRuntime {
   guard: GuardState;
   stats: WatcherStats;
   failures: number;
+  /** Set while a review is in flight — per-runtime so a stale session's
+   *  draining review never blocks the new session's first review. */
+  reviewing: boolean;
   /** OMP-parity post-steer cooldown: remaining settled turns during which
    *  non-blocker notes are deferred to next-turn asides instead of steering. */
   steerCooldownTurns: number;
 }
 
 export function createRuntime(config: AdvisorConfig, models: string[]): WatcherRuntime {
-  return { config, models, cursor: undefined, guard: createGuard(), stats: createStats(), failures: 0, steerCooldownTurns: 0 };
+  return { config, models, cursor: undefined, guard: createGuard(), stats: createStats(), failures: 0, steerCooldownTurns: 0, reviewing: false };
 }
 
 /**
@@ -133,17 +136,16 @@ export interface WatcherHost {
   sendUserMessage(content: string, options?: { deliverAs?: "steer" | "followUp" }): void;
   /** Display-only immediate card (session entry; never enters LLM context). */
   appendEntry<T = unknown>(customType: string, data?: T): void;
+  /** Error/status toast, liveness-gated by the caller (never leaks into a replaced session). */
+  notify(message: string): void;
 }
 
 /** Injectable isolated-model call — defaults to the chain runner; tests pass a fake. */
 export type IsolatedCall = typeof runIsolatedChain;
 
 /** One review step, called from the agent_settled handler while watching is active. */
-// ponytail: module-level guard — one review at a time across the single session
-let reviewing = false;
-
 export async function reviewTurn(rt: WatcherRuntime, ctx: ExtensionContext, host: WatcherHost, isolated: IsolatedCall = runIsolatedChain): Promise<void> {
-  if (rt.stats.paused || reviewing) return;
+  if (rt.stats.paused || rt.reviewing) return;
   // No advisor models → no watching: never let the primary model review its own turns.
   if (rt.models.length === 0) return;
   const config = rt.config.watch;
@@ -158,7 +160,7 @@ export async function reviewTurn(rt: WatcherRuntime, ctx: ExtensionContext, host
   if (calls < config.minToolCalls) { rt.stats.skippedTrivial++; return; }
 
   rt.guard.reviewIndex++;
-  reviewing = true;
+  rt.reviewing = true;
   try {
     const transcript = buildSessionContext(entries, ctx.sessionManager.getLeafId());
     const evidence = buildEvidence(ctx, rt.models, transcript.messages, SYSTEM);
@@ -181,7 +183,7 @@ export async function reviewTurn(rt: WatcherRuntime, ctx: ExtensionContext, host
       rt.failures++;
       if (rt.failures >= MAX_CONSECUTIVE_FAILURES && !rt.stats.paused) {
         rt.stats.paused = true;
-        ctx.ui.notify(`Advisor watch paused after ${MAX_CONSECUTIVE_FAILURES} consecutive review failures (${String(error)}). Run /advisor on to retry.`, "error");
+        host.notify(`Advisor watch paused after ${MAX_CONSECUTIVE_FAILURES} consecutive review failures (${String(error)}). Run /advisor on to retry.`);
       }
       return;
     }
@@ -236,6 +238,6 @@ export async function reviewTurn(rt: WatcherRuntime, ctx: ExtensionContext, host
     host.sendUserMessage(templates[verdict.severity], { deliverAs: "followUp" });
     rt.steerCooldownTurns = config.immuneTurns;
   } finally {
-    reviewing = false;
+    rt.reviewing = false;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-advisor",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Pi extension for an automatic advisor: a second model that reviews each settled turn and injects severity-routed notes, plus an on-demand consult tool.",
   "type": "module",
   "license": "MIT",