@bacnh85/pi-advisor 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.7 (2026-08-30)
+
+### Changed
+
+- Only nits defer during the post-steer cooldown; concerns now always steer
+  (wake the agent) even inside the cooldown window. A deferred concern
+  contradicted its own delivery template ("address this or state why it does
+  not apply") — the agent couldn't address what it wasn't woken for, and the
+  note just sat visible-but-unacted until the user's next prompt (session
+  01a051c6: 1h21m). Blockers already always steered; nit ping-pong guard is
+  unchanged.
+
+## 0.1.6 (2026-08-30)
+
+### Fixed
+
+- Deferred (cooldown) advisor notes are now visible immediately as a display-only
+  card ("Advisor (deferred — next turn)") at settle time. Previously they sat in
+  the SDK's pending-next-turn queue with no visual presence and only materialized
+  when the user's next prompt flushed them into the agent's context — looking
+  like the advisor stayed silent and then blurted a note out after user input
+  (session 01a05099, 1h37m gap). The flushed LLM message is now `display:false`
+  so the note never renders twice. Anti-ping-pong deferral behavior unchanged.
+
 ## 0.1.5 (2026-08-29)
 
 ### Added

package/extensions/index.ts

@@ -18,6 +18,7 @@ interface NoteData {
   note: string;
   timestamp: number;
   downgraded?: boolean;
+  deferred?: boolean;
 }
 
 export default function piAdvisor(pi: ExtensionAPI): void {
@@ -32,7 +33,7 @@ export default function piAdvisor(pi: ExtensionAPI): void {
       ? { ...entry.data, note: sanitizeNote(entry.data.note) }
       : { severity: "nit" as Severity, note: "(unavailable)", timestamp: 0 };
     const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
-    const label = data.downgraded ? "Advisor (downgraded)" : "Advisor";
+    const label = data.downgraded ? "Advisor (downgraded)" : data.deferred ? "Advisor (deferred — next turn)" : "Advisor";
     const sev = data.severity === "blocker"
       ? theme.fg("error", data.severity)
       : data.severity === "concern"
@@ -45,7 +46,9 @@ export default function piAdvisor(pi: ExtensionAPI): void {
   });
 
   // Message renderer for next-turn asides (LLM-visible deferred notes). Guard for
-  // older Pi builds/tests that only mock registerEntryRenderer.
+  // older Pi builds/tests that only mock registerEntryRenderer. In the TUI the
+  // deferred message is display:false (the immediate card is the visible surface),
+  // so this is a fallback for non-TUI surfaces that render flushed messages.
   if (typeof (pi as unknown as { registerMessageRenderer?: unknown }).registerMessageRenderer === "function") {
     (pi as unknown as { registerMessageRenderer: typeof pi.registerEntryRenderer }).registerMessageRenderer<NoteData>(REVIEW_ENTRY, (message, { expanded }, theme) => {
       const raw = (message as unknown as { details?: unknown }).details as NoteData | undefined;
@@ -53,7 +56,7 @@ export default function piAdvisor(pi: ExtensionAPI): void {
         ? { ...raw, note: sanitizeNote(raw.note) }
         : { severity: "nit" as Severity, note: "(unavailable)", timestamp: 0 };
       const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
-      const label = data.downgraded ? "Advisor (downgraded)" : "Advisor";
+      const label = data.downgraded ? "Advisor (downgraded)" : data.deferred ? "Advisor (deferred — next turn)" : "Advisor";
       const sev = data.severity === "blocker"
         ? theme.fg("error", data.severity)
         : data.severity === "concern"
@@ -110,6 +113,7 @@ export default function piAdvisor(pi: ExtensionAPI): void {
     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);
   });
 

package/extensions/lib/watcher.ts

@@ -121,6 +121,8 @@ export interface WatcherHost {
   /** Defer a note as an LLM-visible next-turn aside (never wakes the agent now). */
   sendMessage(message: { customType: string; content: string; display: boolean; details?: unknown }, options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }): void;
   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;
 }
 
 /** Injectable isolated-model call — defaults to the real one; tests pass a fake. */
@@ -192,20 +194,30 @@ export async function reviewTurn(rt: WatcherRuntime, ctx: ExtensionContext, host
     else if (verdict.severity === "blocker") rt.stats.blockers++;
     else rt.stats.concerns++;
     const isBlocker = verdict.severity === "blocker";
-    // OMP-parity post-steer cooldown: after any note steers a turn, non-blocker
-    // notes within the next immuneTurns settled turns are deferred to next-turn
-    // asides rather than waking the agent again. Otherwise every new settled turn
-    // produces fresh transcript text, so the reviewer can emit a NEW note each
-    // cycle and the emission guard's identical-note dedupe never trips — an
-    // unbounded nit/concern ping-pong. Blockers always steer (OMP #5628: handing
-    // off broken work must be acknowledged), and each steer (any severity) re-arms
-    // the cooldown. Deferred asides are LLM-visible on the next user- or
-    // blocker-driven turn — never lost, only deferred.
-    if (!isBlocker && rt.steerCooldownTurns > 0) {
+    const isConcern = verdict.severity === "concern";
+    // Post-steer cooldown: only nits defer. Concerns carry a must-address contract
+    // ("address this or state why it does not apply") — deferring one while its own
+    // template claims authority contradicts the injected agent instructions, and
+    // waiting for the user's next prompt looks like the advisor was ignored.
+    // Blockers always steer (OMP #5628: handing off broken work must be
+    // acknowledged). Nits within the next immuneTurns settled turns after a steer
+    // are deferred to next-turn asides rather than waking the agent again;
+    // otherwise every settled turn's fresh transcript text lets the reviewer emit
+    // a NEW note each cycle and the identical-note dedupe never trips — an
+    // unbounded nit ping-pong. Each steer re-arms the cooldown. Deferred asides are
+    // LLM-visible on the next turn — never lost, only deferred.
+    if (!isBlocker && !isConcern && rt.steerCooldownTurns > 0) {
       // The cooldown ticks once per settled turn at the top of reviewTurn — no
       // extra decrement here (OMP's window is purely turn-count based).
       // nextTurn injects into the agent's context on the next turn without waking it now.
-      host.sendMessage({ customType: REVIEW_ENTRY, content: templates[verdict.severity], display: true, details: { severity: verdict.severity, note: verdict.note, timestamp: Date.now() } }, { deliverAs: "nextTurn" });
+      // display:false — the immediate card below is the visible surface; the flushed
+      // message stays LLM-only so the note doesn't render twice.
+      const at = Date.now();
+      host.sendMessage({ customType: REVIEW_ENTRY, content: templates[verdict.severity], display: false, details: { severity: verdict.severity, note: verdict.note, timestamp: at, deferred: true } }, { deliverAs: "nextTurn" });
+      // Immediate display-only card: without it the deferred note is invisible
+      // until the next user prompt flushes it, looking like the advisor stayed
+      // silent then blurted out a note after user input.
+      host.appendEntry(REVIEW_ENTRY, { severity: verdict.severity, note: verdict.note, timestamp: at, deferred: true });
       return;
     }
     // Steering delivery (blockers always steer; non-blockers steer when off-cooldown).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-advisor",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",