@bacnh85/pi-advisor 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.2.4 (2026-09-12)
+
+### Removed
+
+- Dead `AdvisorState.getThinking` knob (sole impl returned `undefined`; the
+  value flowed nowhere meaningful).
+
+### Fixed
+
+- `saveModels` / `migrateLegacyAdvisorModel` no longer leave a `*.tmp-*` file
+  behind when the final rename throws (best-effort unlink, error re-thrown).
+
+### Documentation
+
+- README: added `/advisor watch-off` to the command list.
+
+## 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

@@ -14,10 +14,10 @@ consult tool. Inspired by the advisor subsystem in
     turn during the post-steer calm-down window. The severity sets the note's
     authority wording (“nit — consider” vs “concern — address this” vs
     “blocker — fix before continuing”).
-  - Post-steer cooldown: after a note steers, non-blocker notes within the
-    next `immuneTurns` settled turns are deferred (LLM-visible next turn)
-    instead of waking the agent again — bounds ping-pong. Blockers always
-    steer immediately.
+  - Post-steer cooldown: after a note steers, nit notes within the next
+    `immuneTurns` settled turns are deferred (LLM-visible next turn)
+    instead of waking the agent again — bounds ping-pong. Concerns and
+    blockers always steer immediately.
 - **Emission guard** (noise control): content-free phrases ("lgtm", "done", …)
   are dropped, identical notes are deduped (severity escalation still passes),
   and at most one note is delivered per review cycle.
@@ -47,6 +47,7 @@ npm install -g @bacnh85/pi-advisor
 /advisor models             # edit the full model chain (TUI panel; non-TUI prints it)
 /advisor status             # model chain, watch state, counters
 /advisor on                 # enable watch for this session (also clears a pause)
+/advisor watch-off          # disable background watch for this session
 /advisor off                # clear the chain (disables tool + watch)
 ```
 
@@ -68,7 +69,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/commands/advisor.ts

@@ -19,7 +19,6 @@ export function parseChainArgument(raw: string): string[] {
 export interface AdvisorState {
   getModels(): string[];
   setModels(models: string[]): Promise<void> | void;
-  getThinking(): string | undefined;
   getRuntime(): WatcherRuntime | undefined;
   isWatchEnabled(): boolean;
   setWatchEnabled(value: boolean): void;
@@ -100,7 +99,6 @@ export function registerAdvisor(pi: ExtensionAPI, state: AdvisorState): void {
       const transcriptEvidence = buildEvidence(ctx, models, transcript.messages, SYSTEM);
       const chain = models.join(" → ");
       onUpdate?.({ content: [{ type: "text", text: `Consulting ${chain}…` }], details: { models } });
-      const reasoning = state.getThinking();
       // Progressive display resets per attempt: a candidate that dies mid-stream
       // must not leave its partial output above the next candidate's response.
       let output = "";
@@ -116,7 +114,7 @@ export function registerAdvisor(pi: ExtensionAPI, state: AdvisorState): void {
         if (forAttempt !== attempt) { attempt = forAttempt; output = ""; }
         output += delta;
         onUpdate?.({ content: [{ type: "text", text: output }], details: { models } });
-      }, signal, reasoning);
+      }, signal);
       return {
         content: [{ type: "text", text: `Advice from ${result.model}:\n${result.text}` }],
         details: { models, served: result.model },

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.";
@@ -92,10 +94,6 @@ export default function piAdvisor(pi: ExtensionAPI): void {
       if (legacy) {
         models = [legacy];
         ctx.ui.notify(`Advisor model migrated from pi-plan: ${legacy}`, "info");
-        // If we migrated on top of a pi-plan that had legacyMigrated:true already,
-        // the user config may still lack migrationVersion. Backfill it idempotently
-        // so no future manual patch is needed (code writes, agent never touches
-        // the real global config directly).
       }
     }
     runtime = createRuntime(config, models);
@@ -108,13 +106,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, {
@@ -123,7 +147,6 @@ export default function piAdvisor(pi: ExtensionAPI): void {
       await saveModels(models);
       if (runtime) runtime.models = models;
     },
-    getThinking: () => undefined,
     getRuntime: () => runtime,
     isWatchEnabled: () => watchEnabled,
     setWatchEnabled: (value) => {

package/extensions/lib/config.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
+import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { CONFIG_DIR_NAME, type ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -94,7 +94,12 @@ export async function saveModels(models: string[]): Promise<void> {
   const tmp = `${file}.tmp-${process.pid}`;
   await mkdir(path.dirname(file), { recursive: true });
   await writeFile(tmp, JSON.stringify(settings, null, 2) + "\n", "utf8");
-  await rename(tmp, file);
+  try {
+    await rename(tmp, file);
+  } catch (e) {
+    try { await unlink(tmp); } catch { /* best-effort cleanup */ }
+    throw e;
+  }
 }
 
 export function parseModel(value: string): { provider: string; id: string } | undefined {
@@ -130,7 +135,12 @@ export async function migrateLegacyAdvisorModel(): Promise<string | undefined> {
     const tmp = `${settingsPath}.tmp-${process.pid}`;
     await mkdir(path.dirname(settingsPath), { recursive: true });
     await writeFile(tmp, JSON.stringify({ ...settings, [KEY]: { ...block, model: legacy, migrationVersion: MIGRATION_VERSION } }, null, 2) + "\n", "utf8");
-    await rename(tmp, settingsPath);
+    try {
+      await rename(tmp, settingsPath);
+    } catch (e) {
+      try { await unlink(tmp); } catch { /* best-effort cleanup */ }
+      throw e;
+    }
     return legacy;
   } catch { return undefined; }
 }

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.4",
   "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",