@trevonistrevon/pi-loop 0.4.0 → 0.4.2

package/AGENTS.md

@@ -32,9 +32,15 @@ src/
 - Tool descriptions follow Claude Code format: `## When to Use`, `## When NOT to Use`
 - Cross-extension communication via `pi.events` with `requestId` + reply channels
 - File-backed stores use atomic write (write tmp → rename) + pid-based file locking
-- Widget uses `UICtx.setWidget()` with `render()` callback pattern
+- Runtime tracker UI uses `UICtx.setStatus()` for compact single-line state
 - Tests co-located in `test/`, named `<module>.test.ts`
 
+## Tool Schema Discipline
+- Tool calls must use the exact schema field names from the tool definition. Do not invent aliases.
+- Example: `TaskUpdate` uses `id`, not `taskId`.
+- When a tool validation error clearly indicates an immediately recoverable schema mismatch, correct it silently and retry. Do not emit user-facing chatter like "retrying with the correct shape" unless the recovery itself changes the user's understanding.
+- When adding or revising tool prompt guidance, include concrete parameter-name reminders for commonly miscalled tools.
+
 ## File Locking Pattern
 Copy TaskStore from pi-tasks: `O_EXCL` lockfile, stale PID detection, `LOCK_RETRY_MS`/`LOCK_MAX_RETRIES`
 
@@ -44,14 +50,8 @@ Three trigger types, all stored as `LoopEntry.trigger`:
 - `{ type: "event", source: "tool_execution_start", filter?: "regex:..." | '{"key":"value"}' }` — eventbus-based
 - `{ type: "hybrid", cron: "...", event: { source, filter? }, debounceMs: 30000 }` — both with debounce
 
-## Re-wake via System Reminder
-When a loop fires, the scheduler calls `onLoopFire()` which emits `pi.events("loop:fire", ...)`. The extension's listener queues a reminder. On the next `tool_result` event, the reminder is injected as `<system-reminder>` text (mirroring pi-tasks' pattern):
-```
-<system-reminder>
-Scheduled loop "deploy check" fired. Trigger: schedule: */5 * * * *.
-[loop:abc12345]
-</system-reminder>
-```
+## Re-wake via In-Memory Pending Notifications
+When a loop fires, the scheduler calls `onLoopFire()` which emits `pi.events("loop:fire", ...)`. The extension buffers a pending notification in memory, re-checks whether the wake is still relevant, and only then injects a `pi.sendMessage()` custom message to wake the agent. Do not rely on early queued follow-up user messages for loop delivery; those are not extension-cancelable once handed to pi's queue.
 
 ## Monitor Streaming via PI Events
 Monitor stdout/stderr lines are emitted as `pi.events("monitor:output", { monitorId, line, timestamp })`. Tool consumers subscribe to these events. Completion emits `"monitor:done"` / `"monitor:error"`.

package/DIFFERENTIAL_REVIEW_REPORT.md

@@ -1,5 +1,27 @@
 # Differential Review Report
 
+## Update — 2026-06-02
+
+### Resolved audit finding
+- **Resolved:** recurring `event` / `hybrid` loops now clean themselves up immediately when `maxFires` is reached on the final allowed fire.
+- **Implementation:** `src/trigger-system.ts` now removes and deletes recurring event/hybrid loops as soon as `fireCount >= maxFires` after `onFire(...)` completes.
+- **Why this mattered:** the previous behavior left one stale active loop behind until the next matching event arrived, which was a real runtime cleanup bug.
+
+### Regression coverage added
+- `test/trigger-system.test.ts`
+  - recurring `event` loop is deleted immediately at final `maxFires`
+  - recurring `hybrid` loop is deleted immediately at final `maxFires`
+  - hybrid cleanup also clears scheduled cron state
+- `test/index.test.ts`
+  - extension-level `LoopCreate`/`LoopList` path confirms the loop is gone immediately after the final allowed event fire
+
+### Validation status
+- `npm run lint` ✅
+- `npm run typecheck` ✅
+- `npm run test` ✅
+- `npm run build` ✅
+- Current suite: **112 passing tests**
+
 ## Scope
 Reviewed recent uncommitted changes in:
 - `src/index.ts`

package/dist/index.js

@@ -180,6 +180,87 @@ export default function (pi) {
             widget.update();
         }
     }
+    let agentRunning = false;
+    const pendingNotifications = new Map();
+    let flushPromise;
+    function buildLoopFireMessage(data) {
+        const triggerInfo = typeof data.trigger === "string"
+            ? data.trigger
+            : data.trigger?.type === "cron"
+                ? `schedule: ${data.trigger.schedule}`
+                : data.trigger?.type === "event"
+                    ? `event: ${data.trigger.source}`
+                    : "hybrid";
+        const loopId = data.loopId || "?";
+        const prompt = data.prompt || "loop fired";
+        const constraint = data.readOnly
+            ? "\n\nREAD-ONLY MODE — use only read tools (Read, TaskList, LoopList, MonitorList, etc.). No file writes, shell execution, or destructive changes."
+            : "";
+        return [
+            `[pi-loop] Loop #${loopId} fired (${triggerInfo}).${constraint}`,
+            prompt,
+        ].join("\n");
+    }
+    function buildPendingNotification(data) {
+        const key = data.recurring ? `loop:${data.loopId}` : `loop:${data.loopId}:${data.timestamp}`;
+        return {
+            ...data,
+            key,
+            message: buildLoopFireMessage(data),
+        };
+    }
+    async function deliverNotification(notification) {
+        if (notification.autoTask) {
+            const pending = await hasPendingTasks();
+            if (pending === 0) {
+                debug(`loop:fire #${notification.loopId} — no pending tasks at delivery time, dropping wake`);
+                await cleanDoneTasks();
+                return false;
+            }
+        }
+        agentRunning = true;
+        pi.sendMessage({
+            customType: "pi-loop",
+            content: notification.message,
+            display: false,
+            details: {
+                loopId: notification.loopId,
+                trigger: notification.trigger,
+                recurring: notification.recurring,
+                readOnly: notification.readOnly,
+                autoTask: notification.autoTask,
+                timestamp: notification.timestamp,
+            },
+        }, {
+            deliverAs: "steer",
+            triggerTurn: true,
+        });
+        return true;
+    }
+    async function flushPendingNotifications() {
+        if (flushPromise)
+            return flushPromise;
+        flushPromise = (async () => {
+            if (agentRunning || _latestCtx?.hasPendingMessages())
+                return;
+            const entries = [...pendingNotifications.entries()]
+                .sort(([, left], [, right]) => left.timestamp - right.timestamp);
+            for (const [key, notification] of entries) {
+                pendingNotifications.delete(key);
+                const delivered = await deliverNotification(notification);
+                if (delivered)
+                    return;
+            }
+        })().finally(() => {
+            flushPromise = undefined;
+        });
+        return flushPromise;
+    }
+    async function queueOrDeliverNotification(data) {
+        const notification = buildPendingNotification(data);
+        pendingNotifications.set(notification.key, notification);
+        await flushPendingNotifications();
+    }
     // ── Loop fire handler ──
     function onLoopFire(entry) {
         debug(`loop:fire #${entry.id}`, { prompt: entry.prompt.slice(0, 50) });
@@ -248,10 +329,27 @@ export default function (pi) {
         showPersistedLoops();
         widget.update();
     });
+    pi.on("agent_start", async (_event, ctx) => {
+        agentRunning = true;
+        _latestCtx = ctx;
+        widget.setUICtx(ctx.ui);
+    });
+    pi.on("agent_end", async (_event, ctx) => {
+        agentRunning = false;
+        _latestCtx = ctx;
+        widget.setUICtx(ctx.ui);
+        await flushPendingNotifications();
+    });
+    pi.on("session_shutdown", async () => {
+        agentRunning = false;
+        pendingNotifications.clear();
+    });
     pi.on("session_switch", async (event, ctx) => {
         _latestCtx = ctx;
         widget.setUICtx(ctx.ui);
         triggerSystem.stop();
+        agentRunning = false;
+        pendingNotifications.clear();
         const isResume = event?.reason === "resume";
         storeUpgraded = false;
         persistedShown = false;
@@ -262,36 +360,18 @@ export default function (pi) {
         showPersistedLoops(isResume);
         widget.update();
     });
-    // ── Loop fire handler — sends a user message to re-wake the agent ──
+    // ── Loop fire handler — queues an in-memory notification, then injects a custom message when delivery is safe ──
     pi.events.on("loop:fire", async (event) => {
         const data = event;
-        if (data.recurring && _latestCtx?.hasPendingMessages()) {
-            debug(`loop:fire #${data.loopId} — agent has pending messages, skipping recurring fire`);
-            return;
-        }
         if (data.autoTask) {
             const pending = await hasPendingTasks();
             if (pending === 0) {
                 debug(`loop:fire #${data.loopId} — no pending tasks, skipping, requesting cleanup`);
-                cleanDoneTasks();
+                await cleanDoneTasks();
                 return;
             }
         }
-        const triggerInfo = typeof data.trigger === "string"
-            ? data.trigger
-            : data.trigger?.type === "cron"
-                ? `schedule: ${data.trigger.schedule}`
-                : data.trigger?.type === "event"
-                    ? `event: ${data.trigger.source}`
-                    : `hybrid`;
-        const loopId = data.loopId || "?";
-        const prompt = data.prompt || "loop fired";
-        const constraint = data.readOnly ? "\n\nREAD-ONLY MODE — use only read tools (Read, TaskList, LoopList, MonitorList, LoopCreate, etc.). No file writes, shell execution, or destructive changes." : "";
-        const message = [
-            `[pi-loop] Loop #${loopId} fired (${triggerInfo}).${constraint}`,
-            prompt,
-        ].join("\n");
-        pi.sendUserMessage(message, { deliverAs: "followUp" });
+        await queueOrDeliverNotification(data);
     });
     // ──────────────────────────────────────────────────
     // Tool 1: LoopCreate
@@ -327,7 +407,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **trigger**: interval like "30s", "5m", "2h", event source, or hybrid spec
 - **prompt**: what to do when the loop fires (e.g., "check if the build passed")
 - **recurring**: repeat or fire once (default: true)
-- **autoTask**: if pi-tasks is loaded, auto-create a task on each fire
+- **autoTask**: when pi-tasks is loaded or native task fallback is active, auto-create a task on each fire
 - **readOnly**: restrict the agent to read-only tools when this loop fires (default: false)
 - **maxFires**: auto-stop after N fires — prevents infinite token burn on polling loops`,
         promptGuidelines: [
@@ -346,7 +426,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             "Set readOnly: true for loops that only observe and report (checks, status polls). This prevents unintended changes.",
             "## Task-driven workflows",
             "After creating tasks with TaskCreate, use an event loop with autoTask: true so the system checks for pending tasks before firing: LoopCreate trigger='tasks:created' triggerType='event' autoTask: true maxFires: 30 prompt='Run TaskList, pick the next available pending task, work on it.'",
-            "When no tasks are pending, the loop skips the follow-up — no tokens burned on empty polls.",
+            "When no tasks are pending, the loop skips the wake entirely — no tokens burned on empty polls.",
             "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
         ],
         parameters: Type.Object({
@@ -417,7 +497,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
                 `Trigger: ${triggerDesc}\n` +
                 `Recurring: ${entry.recurring}\n` +
                 (entry.autoTask ? `Auto-task: enabled\n` : "") +
-                (tasksAvailable ? "" : "(pi-tasks not detected — autoTask will have no effect)\n") +
+                ((tasksAvailable || nativeTasksRegistered) ? "" : "(task system not ready yet — autoTask may not fire until native fallback or pi-tasks becomes available)\n") +
                 `ID: ${entry.id} (use LoopDelete to cancel)`));
         },
     });
@@ -548,7 +628,7 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
 
 Fire off a build check, CI monitor, experiment, script, or any slow command — then keep working. Output streams back as "monitor:output" events. When the process exits, "monitor:done" fires (or "monitor:error" on failure).
 
-If you pass onDone with a prompt, the monitor auto-creates a one-shot completion loop — you get a system reminder with the exit code and output line count. No need to poll or create a separate loop.
+If you pass onDone with a prompt, the monitor auto-creates a one-shot completion loop — you get a completion wake with the exit code and output line count. No need to poll or create a separate loop.
 
 DO NOT use raw Bash while/sleep/for loops to watch something. DO NOT run slow commands inline that could be offloaded. Use MonitorCreate to run work in parallel while you continue.
 
@@ -562,7 +642,7 @@ Default to MonitorCreate for any long-running or background work:\n- Watch a CI/
 
 ## onDone — auto-notify on completion
 
-Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits. The system reminder includes the exit code and output line count.\n\nExample: MonitorCreate command="python train.py" onDone="Check training results and report best loss"\nExample: MonitorCreate command="hut builds show 1769753" onDone="Analyze the build result and report status"`,
+Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits. The completion wake includes the exit code and output line count.\n\nExample: MonitorCreate command="python train.py" onDone="Check training results and report best loss"\nExample: MonitorCreate command="hut builds show 1769753" onDone="Analyze the build result and report status"`,
         promptGuidelines: [
             "Default to MonitorCreate for any long-running or background command — releases the agent to keep working on other tasks in parallel.",
             "When the user asks to monitor CI builds, watch a build, check a remote job, or run an experiment, use MonitorCreate instead of inline bash/curl/wait.",
@@ -572,7 +652,7 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
             command: Type.String({ description: "Shell command to run in background" }),
             description: Type.Optional(Type.String({ description: "Human-readable description" })),
             timeout: Type.Optional(Type.Number({ description: "Auto-stop after N ms (default: 300000, 0 = no timeout)", default: 300000 })),
-            onDone: Type.Optional(Type.String({ description: "Prompt to run when the monitor completes. Auto-creates a one-shot completion loop — no need for a separate LoopCreate." })),
+            onDone: Type.Optional(Type.String({ description: "Prompt to run when the monitor completes. Auto-creates a one-shot completion wake — no need for a separate LoopCreate." })),
         }),
         execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
             if (monitorManager.list().filter(m => m.status === "running").length >= 25) {
@@ -892,6 +972,10 @@ Fields:
 - subject: brief actionable title
 - description: detailed requirements
 - metadata: optional tags/metadata`,
+            promptGuidelines: [
+                "Use TaskCreate to track complex multi-step work across turns.",
+                "TaskCreate accepts `subject` and `description` parameters only — do not invent extra fields unless the schema explicitly adds them.",
+            ],
             parameters: Type.Object({
                 subject: Type.String({ description: "Brief actionable title for the task" }),
                 description: Type.String({ description: "Detailed description of what needs to be done" }),
@@ -932,6 +1016,11 @@ Fields:
             description: `Update task status or details. Set status to "in_progress" before starting work, "completed" when done.
 
 Statuses: pending → in_progress → completed`,
+            promptGuidelines: [
+                "Use TaskUpdate with parameter `id`, not `taskId`.",
+                "TaskUpdate accepts only `id`, `status`, `subject`, and `description`.",
+                "When a tool validation error clearly indicates a recoverable schema mismatch, correct the arguments and retry without narrating the recovery unless the user needs to know.",
+            ],
             parameters: Type.Object({
                 id: Type.String({ description: "Task ID to update" }),
                 status: Type.Optional(Type.String({ description: "New status", enum: ["pending", "in_progress", "completed"] })),

package/dist/trigger-system.js

@@ -103,6 +103,11 @@ export class TriggerSystem {
             this.remove(entry.id);
             return;
         }
+        if (fresh.recurring && fresh.maxFires && (fresh.fireCount ?? 0) >= fresh.maxFires) {
+            this.remove(fresh.id);
+            this.store.delete(fresh.id);
+            return;
+        }
         if (!fresh.recurring) {
             this.remove(fresh.id);
             this.store.delete(fresh.id);

package/dist/ui/widget.d.ts

@@ -9,8 +9,6 @@ export declare class LoopWidget {
     private store;
     private monitorManager;
     private uiCtx;
-    private tui;
-    private widgetRegistered;
     private interval;
     private taskSummaryProvider;
     constructor(store: LoopStore, monitorManager: MonitorManager);
@@ -18,7 +16,7 @@ export declare class LoopWidget {
     setStore(store: LoopStore): void;
     setTaskSummaryProvider(provider: (() => TaskSummary) | undefined): void;
     update(): void;
-    private renderWidget;
+    private computeStatus;
     dispose(): void;
 }
 export {};

package/dist/ui/widget.js

@@ -1,10 +1,7 @@
-import { truncateToWidth } from "@earendil-works/pi-tui";
 export class LoopWidget {
     store;
     monitorManager;
     uiCtx;
-    tui;
-    widgetRegistered = false;
     interval;
     taskSummaryProvider;
     constructor(store, monitorManager) {
@@ -23,34 +20,22 @@ export class LoopWidget {
     update() {
         if (!this.uiCtx)
             return;
-        const taskSummary = this.taskSummaryProvider?.() ?? { count: 0 };
-        const hasContent = this.store.list().some(l => l.status === "active") || this.monitorManager.list().length > 0 || taskSummary.count > 0;
-        if (hasContent && !this.interval) {
+        const status = this.computeStatus();
+        if (status && !this.interval) {
             this.interval = setInterval(() => this.update(), 5000);
         }
-        if (!hasContent && this.interval) {
+        if (!status && this.interval) {
             clearInterval(this.interval);
             this.interval = undefined;
         }
-        if (!this.widgetRegistered) {
-            this.uiCtx.setWidget("loops", (tui, theme) => {
-                this.tui = tui;
-                return { render: () => this.renderWidget(tui, theme), invalidate: () => { } };
-            }, { placement: "aboveEditor" });
-            this.widgetRegistered = true;
-        }
-        else if (this.tui) {
-            this.tui.requestRender();
-        }
+        this.uiCtx.setStatus("loops", status);
     }
-    renderWidget(tui, _theme) {
+    computeStatus() {
         const loops = this.store.list().filter(l => l.status === "active");
         const monitors = this.monitorManager.list();
         const taskSummary = this.taskSummaryProvider?.() ?? { count: 0 };
-        const w = tui.terminal.columns;
-        const trunc = (line) => truncateToWidth(line, w);
         if (loops.length === 0 && monitors.length === 0 && taskSummary.count === 0) {
-            return [trunc("none")];
+            return undefined;
         }
         const parts = [];
         if (loops.length > 0)
@@ -62,17 +47,14 @@ export class LoopWidget {
         let line = parts.join(" · ");
         if (taskSummary.focusText)
             line += ` | ${taskSummary.focusText}`;
-        return [trunc(line)];
+        return line;
     }
     dispose() {
         if (this.interval) {
             clearInterval(this.interval);
             this.interval = undefined;
         }
-        if (this.uiCtx)
-            this.uiCtx.setWidget("loops", undefined);
-        this.widgetRegistered = false;
-        this.tui = undefined;
+        this.uiCtx?.setStatus("loops", undefined);
     }
 }
 function formatCount(count, noun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevonistrevon/pi-loop",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "A pi extension for cron/event-based agent re-wake loops and background process monitoring.",
   "author": "trevonistrevon",
   "license": "MIT",

package/src/index.ts

@@ -50,6 +50,10 @@ interface SessionSwitchEvent {
   reason?: string;
 }
 
+interface PendingNotification extends LoopFireEvent {
+  key: string;
+  message: string;
+}
 
 export default function (pi: ExtensionAPI) {
   const piLoopEnv = process.env.PI_LOOP;
@@ -191,6 +195,97 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
+  let agentRunning = false;
+  const pendingNotifications = new Map<string, PendingNotification>();
+  let flushPromise: Promise<void> | undefined;
+
+  function buildLoopFireMessage(data: LoopFireEvent): string {
+    const triggerInfo = typeof data.trigger === "string"
+      ? data.trigger
+      : data.trigger?.type === "cron"
+        ? `schedule: ${data.trigger.schedule}`
+        : data.trigger?.type === "event"
+          ? `event: ${data.trigger.source}`
+          : "hybrid";
+
+    const loopId = data.loopId || "?";
+    const prompt = data.prompt || "loop fired";
+    const constraint = data.readOnly
+      ? "\n\nREAD-ONLY MODE — use only read tools (Read, TaskList, LoopList, MonitorList, etc.). No file writes, shell execution, or destructive changes."
+      : "";
+
+    return [
+      `[pi-loop] Loop #${loopId} fired (${triggerInfo}).${constraint}`,
+      prompt,
+    ].join("\n");
+  }
+
+  function buildPendingNotification(data: LoopFireEvent): PendingNotification {
+    const key = data.recurring ? `loop:${data.loopId}` : `loop:${data.loopId}:${data.timestamp}`;
+    return {
+      ...data,
+      key,
+      message: buildLoopFireMessage(data),
+    };
+  }
+
+  async function deliverNotification(notification: PendingNotification): Promise<boolean> {
+    if (notification.autoTask) {
+      const pending = await hasPendingTasks();
+      if (pending === 0) {
+        debug(`loop:fire #${notification.loopId} — no pending tasks at delivery time, dropping wake`);
+        await cleanDoneTasks();
+        return false;
+      }
+    }
+
+    agentRunning = true;
+    pi.sendMessage({
+      customType: "pi-loop",
+      content: notification.message,
+      display: false,
+      details: {
+        loopId: notification.loopId,
+        trigger: notification.trigger,
+        recurring: notification.recurring,
+        readOnly: notification.readOnly,
+        autoTask: notification.autoTask,
+        timestamp: notification.timestamp,
+      },
+    }, {
+      deliverAs: "steer",
+      triggerTurn: true,
+    });
+    return true;
+  }
+
+  async function flushPendingNotifications(): Promise<void> {
+    if (flushPromise) return flushPromise;
+
+    flushPromise = (async () => {
+      if (agentRunning || _latestCtx?.hasPendingMessages()) return;
+
+      const entries = [...pendingNotifications.entries()]
+        .sort(([, left], [, right]) => left.timestamp - right.timestamp);
+
+      for (const [key, notification] of entries) {
+        pendingNotifications.delete(key);
+        const delivered = await deliverNotification(notification);
+        if (delivered) return;
+      }
+    })().finally(() => {
+      flushPromise = undefined;
+    });
+
+    return flushPromise;
+  }
+
+  async function queueOrDeliverNotification(data: LoopFireEvent): Promise<void> {
+    const notification = buildPendingNotification(data);
+    pendingNotifications.set(notification.key, notification);
+    await flushPendingNotifications();
+  }
+
   // ── Loop fire handler ──
 
   function onLoopFire(entry: LoopEntry): void {
@@ -267,10 +362,30 @@ export default function (pi: ExtensionAPI) {
     widget.update();
   });
 
+  pi.on("agent_start", async (_event, ctx) => {
+    agentRunning = true;
+    _latestCtx = ctx;
+    widget.setUICtx(ctx.ui);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    agentRunning = false;
+    _latestCtx = ctx;
+    widget.setUICtx(ctx.ui);
+    await flushPendingNotifications();
+  });
+
+  pi.on("session_shutdown", async () => {
+    agentRunning = false;
+    pendingNotifications.clear();
+  });
+
   pi.on("session_switch" as any, async (event: SessionSwitchEvent, ctx: ExtensionContext) => {
     _latestCtx = ctx;
     widget.setUICtx(ctx.ui);
     triggerSystem.stop();
+    agentRunning = false;
+    pendingNotifications.clear();
 
     const isResume = event?.reason === "resume";
     storeUpgraded = false;
@@ -285,42 +400,21 @@ export default function (pi: ExtensionAPI) {
     widget.update();
   });
 
-  // ── Loop fire handler — sends a user message to re-wake the agent ──
+  // ── Loop fire handler — queues an in-memory notification, then injects a custom message when delivery is safe ──
 
   pi.events.on("loop:fire", async (event: unknown) => {
     const data = event as LoopFireEvent;
 
-    if (data.recurring && _latestCtx?.hasPendingMessages()) {
-      debug(`loop:fire #${data.loopId} — agent has pending messages, skipping recurring fire`);
-      return;
-    }
-
     if (data.autoTask) {
       const pending = await hasPendingTasks();
       if (pending === 0) {
         debug(`loop:fire #${data.loopId} — no pending tasks, skipping, requesting cleanup`);
-        cleanDoneTasks();
+        await cleanDoneTasks();
         return;
       }
     }
 
-    const triggerInfo = typeof data.trigger === "string"
-      ? data.trigger
-      : data.trigger?.type === "cron"
-        ? `schedule: ${data.trigger.schedule}`
-        : data.trigger?.type === "event"
-          ? `event: ${data.trigger.source}`
-          : `hybrid`;
-
-    const loopId = data.loopId || "?";
-    const prompt = data.prompt || "loop fired";
-    const constraint = data.readOnly ? "\n\nREAD-ONLY MODE — use only read tools (Read, TaskList, LoopList, MonitorList, LoopCreate, etc.). No file writes, shell execution, or destructive changes." : "";
-    const message = [
-      `[pi-loop] Loop #${loopId} fired (${triggerInfo}).${constraint}`,
-      prompt,
-    ].join("\n");
-
-    pi.sendUserMessage(message, { deliverAs: "followUp" });
+    await queueOrDeliverNotification(data);
   });
 
   // ──────────────────────────────────────────────────
@@ -358,7 +452,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **trigger**: interval like "30s", "5m", "2h", event source, or hybrid spec
 - **prompt**: what to do when the loop fires (e.g., "check if the build passed")
 - **recurring**: repeat or fire once (default: true)
-- **autoTask**: if pi-tasks is loaded, auto-create a task on each fire
+- **autoTask**: when pi-tasks is loaded or native task fallback is active, auto-create a task on each fire
 - **readOnly**: restrict the agent to read-only tools when this loop fires (default: false)
 - **maxFires**: auto-stop after N fires — prevents infinite token burn on polling loops`,
     promptGuidelines: [
@@ -377,7 +471,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       "Set readOnly: true for loops that only observe and report (checks, status polls). This prevents unintended changes.",
       "## Task-driven workflows",
       "After creating tasks with TaskCreate, use an event loop with autoTask: true so the system checks for pending tasks before firing: LoopCreate trigger='tasks:created' triggerType='event' autoTask: true maxFires: 30 prompt='Run TaskList, pick the next available pending task, work on it.'",
-      "When no tasks are pending, the loop skips the follow-up — no tokens burned on empty polls.",
+      "When no tasks are pending, the loop skips the wake entirely — no tokens burned on empty polls.",
       "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
     ],
     parameters: Type.Object({
@@ -455,7 +549,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
         `Trigger: ${triggerDesc}\n` +
         `Recurring: ${entry.recurring}\n` +
         (entry.autoTask ? `Auto-task: enabled\n` : "") +
-        (tasksAvailable ? "" : "(pi-tasks not detected — autoTask will have no effect)\n") +
+        ((tasksAvailable || nativeTasksRegistered) ? "" : "(task system not ready yet — autoTask may not fire until native fallback or pi-tasks becomes available)\n") +
         `ID: ${entry.id} (use LoopDelete to cancel)`
       ));
     },
@@ -594,7 +688,7 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
 
 Fire off a build check, CI monitor, experiment, script, or any slow command — then keep working. Output streams back as "monitor:output" events. When the process exits, "monitor:done" fires (or "monitor:error" on failure).
 
-If you pass onDone with a prompt, the monitor auto-creates a one-shot completion loop — you get a system reminder with the exit code and output line count. No need to poll or create a separate loop.
+If you pass onDone with a prompt, the monitor auto-creates a one-shot completion loop — you get a completion wake with the exit code and output line count. No need to poll or create a separate loop.
 
 DO NOT use raw Bash while/sleep/for loops to watch something. DO NOT run slow commands inline that could be offloaded. Use MonitorCreate to run work in parallel while you continue.
 
@@ -608,7 +702,7 @@ Default to MonitorCreate for any long-running or background work:\n- Watch a CI/
 
 ## onDone — auto-notify on completion
 
-Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits. The system reminder includes the exit code and output line count.\n\nExample: MonitorCreate command="python train.py" onDone="Check training results and report best loss"\nExample: MonitorCreate command="hut builds show 1769753" onDone="Analyze the build result and report status"`,
+Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits. The completion wake includes the exit code and output line count.\n\nExample: MonitorCreate command="python train.py" onDone="Check training results and report best loss"\nExample: MonitorCreate command="hut builds show 1769753" onDone="Analyze the build result and report status"`,
     promptGuidelines: [
       "Default to MonitorCreate for any long-running or background command — releases the agent to keep working on other tasks in parallel.",
       "When the user asks to monitor CI builds, watch a build, check a remote job, or run an experiment, use MonitorCreate instead of inline bash/curl/wait.",
@@ -618,7 +712,7 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
       command: Type.String({ description: "Shell command to run in background" }),
       description: Type.Optional(Type.String({ description: "Human-readable description" })),
       timeout: Type.Optional(Type.Number({ description: "Auto-stop after N ms (default: 300000, 0 = no timeout)", default: 300000 })),
-      onDone: Type.Optional(Type.String({ description: "Prompt to run when the monitor completes. Auto-creates a one-shot completion loop — no need for a separate LoopCreate." })),
+      onDone: Type.Optional(Type.String({ description: "Prompt to run when the monitor completes. Auto-creates a one-shot completion wake — no need for a separate LoopCreate." })),
     }),
 
     execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
@@ -963,6 +1057,10 @@ Fields:
 - subject: brief actionable title
 - description: detailed requirements
 - metadata: optional tags/metadata`,
+      promptGuidelines: [
+        "Use TaskCreate to track complex multi-step work across turns.",
+        "TaskCreate accepts `subject` and `description` parameters only — do not invent extra fields unless the schema explicitly adds them.",
+      ],
       parameters: Type.Object({
         subject: Type.String({ description: "Brief actionable title for the task" }),
         description: Type.String({ description: "Detailed description of what needs to be done" }),
@@ -1005,6 +1103,11 @@ Fields:
       description: `Update task status or details. Set status to "in_progress" before starting work, "completed" when done.
 
 Statuses: pending → in_progress → completed`,
+      promptGuidelines: [
+        "Use TaskUpdate with parameter `id`, not `taskId`.",
+        "TaskUpdate accepts only `id`, `status`, `subject`, and `description`.",
+        "When a tool validation error clearly indicates a recoverable schema mismatch, correct the arguments and retry without narrating the recovery unless the user needs to know.",
+      ],
       parameters: Type.Object({
         id: Type.String({ description: "Task ID to update" }),
         status: Type.Optional(Type.String({ description: "New status", enum: ["pending", "in_progress", "completed"] })),

package/src/trigger-system.ts

@@ -110,6 +110,12 @@ export class TriggerSystem {
       return;
     }
 
+    if (fresh.recurring && fresh.maxFires && (fresh.fireCount ?? 0) >= fresh.maxFires) {
+      this.remove(fresh.id);
+      this.store.delete(fresh.id);
+      return;
+    }
+
     if (!fresh.recurring) {
       this.remove(fresh.id);
       this.store.delete(fresh.id);

package/src/ui/widget.ts

@@ -1,6 +1,4 @@
-import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
-import type { Component, TUI } from "@earendil-works/pi-tui";
-import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import type { MonitorManager } from "../monitor-manager.js";
 import type { LoopStore } from "../store.js";
 
@@ -11,8 +9,6 @@ interface TaskSummary {
 
 export class LoopWidget {
   private uiCtx: ExtensionUIContext | undefined;
-  private tui: TUI | undefined;
-  private widgetRegistered = false;
   private interval: ReturnType<typeof setInterval> | undefined;
   private taskSummaryProvider: (() => TaskSummary) | undefined;
 
@@ -36,36 +32,25 @@ export class LoopWidget {
   update() {
     if (!this.uiCtx) return;
 
-    const taskSummary = this.taskSummaryProvider?.() ?? { count: 0 };
-    const hasContent = this.store.list().some(l => l.status === "active") || this.monitorManager.list().length > 0 || taskSummary.count > 0;
-    if (hasContent && !this.interval) {
+    const status = this.computeStatus();
+    if (status && !this.interval) {
       this.interval = setInterval(() => this.update(), 5000);
     }
-    if (!hasContent && this.interval) {
+    if (!status && this.interval) {
       clearInterval(this.interval);
       this.interval = undefined;
     }
 
-    if (!this.widgetRegistered) {
-      this.uiCtx.setWidget("loops", (tui: TUI, theme: Theme) => {
-        this.tui = tui;
-        return { render: () => this.renderWidget(tui, theme), invalidate: () => {} } as Component & { dispose?(): void };
-      }, { placement: "aboveEditor" });
-      this.widgetRegistered = true;
-    } else if (this.tui) {
-      (this.tui as any).requestRender();
-    }
+    this.uiCtx.setStatus("loops", status);
   }
 
-  private renderWidget(tui: TUI, _theme: Theme): string[] {
+  private computeStatus(): string | undefined {
     const loops = this.store.list().filter(l => l.status === "active");
     const monitors = this.monitorManager.list();
     const taskSummary = this.taskSummaryProvider?.() ?? { count: 0 };
-    const w = tui.terminal.columns;
-    const trunc = (line: string) => truncateToWidth(line, w);
 
     if (loops.length === 0 && monitors.length === 0 && taskSummary.count === 0) {
-      return [trunc("none")];
+      return undefined;
     }
 
     const parts: string[] = [];
@@ -75,14 +60,15 @@ export class LoopWidget {
 
     let line = parts.join(" · ");
     if (taskSummary.focusText) line += ` | ${taskSummary.focusText}`;
-    return [trunc(line)];
+    return line;
   }
 
   dispose() {
-    if (this.interval) { clearInterval(this.interval); this.interval = undefined; }
-    if (this.uiCtx) this.uiCtx.setWidget("loops", undefined);
-    this.widgetRegistered = false;
-    this.tui = undefined;
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = undefined;
+    }
+    this.uiCtx?.setStatus("loops", undefined);
   }
 }