@trevonistrevon/pi-loop 0.2.7 → 0.3.0

package/dist/index.js

@@ -106,9 +106,36 @@ export default function (pi) {
             return undefined;
         }
     }
+    async function hasPendingTasks() {
+        if (!tasksAvailable)
+            return -1;
+        try {
+            const requestId = randomUUID();
+            const count = await new Promise((resolve) => {
+                const timer = setTimeout(() => { unsub(); resolve(-1); }, 3000);
+                const unsub = pi.events.on(`tasks:rpc:pending:reply:${requestId}`, (raw) => {
+                    unsub();
+                    clearTimeout(timer);
+                    const reply = raw;
+                    resolve(reply.success && reply.data ? reply.data.pending : -1);
+                });
+                pi.events.emit("tasks:rpc:pending", { requestId });
+            });
+            return count;
+        }
+        catch {
+            return -1;
+        }
+    }
     // ── Loop fire handler ──
     function onLoopFire(entry) {
         debug(`loop:fire #${entry.id}`, { prompt: entry.prompt.slice(0, 50) });
+        if (entry.maxFires && (entry.fireCount ?? 0) >= entry.maxFires) {
+            debug(`loop #${entry.id} — reached maxFires ${entry.maxFires}, expiring`);
+            store.update(entry.id, { status: "expired" });
+            return;
+        }
+        store.update(entry.id, { fireCount: (entry.fireCount ?? 0) + 1 });
         if (entry.autoTask) {
             autoCreateTask(entry).then((taskId) => {
                 if (taskId)
@@ -121,6 +148,8 @@ export default function (pi) {
             trigger: entry.trigger,
             timestamp: Date.now(),
             readOnly: entry.readOnly,
+            recurring: entry.recurring,
+            autoTask: entry.autoTask,
         });
     }
     // ── Session lifecycle ──
@@ -179,12 +208,19 @@ export default function (pi) {
         showPersistedLoops(isResume);
     });
     // ── Loop fire handler — sends a user message to re-wake the agent ──
-    pi.events.on("loop:fire", (event) => {
+    pi.events.on("loop:fire", async (event) => {
         const data = event;
-        if (_latestCtx?.hasPendingMessages()) {
-            debug(`loop:fire #${data.loopId} — agent has pending messages, skipping`);
+        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`);
+                return;
+            }
+        }
         const triggerInfo = typeof data.trigger === "string"
             ? data.trigger
             : data.trigger?.type === "cron"
@@ -236,12 +272,26 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **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
-- **readOnly**: restrict the agent to read-only tools when this loop fires (default: false)`,
+- **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: [
-            "When the user asks for a loop, repeating task, periodic check, or scheduled reminder, use LoopCreate — not raw Bash for/sleep/while.",
-            "Use LoopCreate for any 'every X seconds/minutes/hours' requests.",
+            "Use LoopCreate when the user asks for a repeating task, periodic check, scheduled reminder, or 'every X' — never use raw Bash for/sleep/while.",
+            "## Choosing trigger type",
+            "Prefer event triggers over cron when possible — they fire exactly when needed instead of polling.",
+            "Use event triggers for: tool completion ('tool_execution_end'), task creation ('tasks:created'), monitor completion ('monitor:done').",
+            "Use cron triggers only when: the user explicitly asks for a time interval, or there's no relevant pi event to subscribe to.",
+            "Hybrid triggers (cron + event) give you both: event-driven responsiveness with a cron safety-net fallback.",
+            "## Choosing an interval",
+            "Default to 5m unless the user specifies differently. Use shorter intervals only when time-sensitive.",
+            "## maxFires — prevent infinite token burn",
+            "Always set maxFires on polling loops so they don't run forever. For task-continuation loops, use maxFires: 20-50.",
+            "When a loop fires and finds nothing to do, call LoopDelete on its own ID to stop it — don't keep polling.",
+            "## readOnly mode",
+            "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.",
             "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
-            "After creating tasks with TaskCreate, create a loop to keep working through them: LoopCreate trigger='30s' prompt='Run TaskList, pick the next available pending task, work on it. Continue until all tasks are completed.' This ensures the agent keeps making progress across turns instead of stopping after one task.",
         ],
         parameters: Type.Object({
             trigger: Type.String({ description: "Cron expression (e.g., '5m', '1h', '0 9 * * 1-5'), event source (e.g., 'tool_execution_start'), or JSON hybrid spec" }),
@@ -251,9 +301,10 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             triggerType: Type.Optional(Type.String({ description: "cron, event, or hybrid (inferred from trigger string if omitted)", enum: ["cron", "event", "hybrid"] })),
             debounceMs: Type.Optional(Type.Number({ description: "Debounce for hybrid triggers (default: 30000)", default: 30000 })),
             readOnly: Type.Optional(Type.Boolean({ description: "Restrict the agent to read-only tools when this loop fires (default: false)", default: false })),
+            maxFires: Type.Optional(Type.Number({ description: "Auto-stop after N fires. Prevents infinite token burn on polling loops." })),
         }),
         execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-            const { trigger: triggerInput, prompt, recurring, autoTask, triggerType, debounceMs, readOnly } = params;
+            const { trigger: triggerInput, prompt, recurring, autoTask, triggerType, debounceMs, readOnly, maxFires } = params;
             let trigger;
             const inferred = triggerType ?? inferTriggerType(triggerInput);
             if (inferred === "cron") {
@@ -282,8 +333,24 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
                 autoTask,
                 selfPaced: triggerInput === "self-paced" || prompt.toLowerCase().includes("self-paced"),
                 readOnly,
+                maxFires,
             });
             triggerSystem.add(entry);
+            if (trigger.type === "event" && trigger.source === "monitor:done" && trigger.filter) {
+                try {
+                    const filterObj = JSON.parse(trigger.filter);
+                    const monitorId = filterObj.monitorId;
+                    if (monitorId) {
+                        const monitor = monitorManager.get(monitorId);
+                        if (monitor && monitor.status !== "running") {
+                            debug(`loop #${entry.id} — monitor #${monitorId} already ${monitor.status}, expiring`);
+                            triggerSystem.remove(entry.id);
+                            store.update(entry.id, { status: "expired" });
+                        }
+                    }
+                }
+                catch { /* filter parse failure, ignore */ }
+            }
             widget.update();
             const triggerDesc = trigger.type === "cron"
                 ? `schedule: ${trigger.schedule}`
@@ -298,6 +365,15 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
                 `ID: ${entry.id} (use LoopDelete to cancel)`));
         },
     });
+    function handleMonitorDoneLoop(doneLoop, monitorId) {
+        triggerSystem.add(doneLoop);
+        const monitor = monitorManager.get(monitorId);
+        if (monitor && monitor.status !== "running") {
+            debug(`onDone loop #${doneLoop.id} — monitor #${monitorId} already ${monitor.status}, expiring`);
+            triggerSystem.remove(doneLoop.id);
+            store.update(doneLoop.id, { status: "expired" });
+        }
+    }
     function validateTrigger(trigger) {
         if (trigger.type === "cron") {
             const parts = trigger.schedule.trim().split(/\s+/);
@@ -452,7 +528,7 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
             if (params.onDone) {
                 const doneTrigger = { type: "event", source: "monitor:done", filter: JSON.stringify({ monitorId: entry.id }) };
                 const doneLoop = store.create(doneTrigger, params.onDone, { recurring: false });
-                triggerSystem.add(doneLoop);
+                handleMonitorDoneLoop(doneLoop, entry.id);
                 onDoneMsg = `\nonDone loop #${doneLoop.id}: fires when monitor completes — no polling needed`;
             }
             return Promise.resolve(textResult(`Monitor #${entry.id} started: ${entry.command.slice(0, 60)}\n` +
@@ -466,7 +542,7 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
     pi.registerTool({
         name: "MonitorList",
         label: "MonitorList",
-        description: `List all monitors with their status, command, and output line count.`,
+        description: `List all monitors with their status, command, exit code, output line count, and last 5 lines of buffered output.`,
         parameters: Type.Object({}),
         execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
             const monitors = monitorManager.list();
@@ -477,7 +553,16 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
                 const icon = m.status === "running" ? "◉" : m.status === "completed" ? "✓" : "✗";
                 const age = Date.now() - m.startedAt;
                 const ageStr = formatRemaining(age);
-                lines.push(`${icon} #${m.id} [${m.status}] ${m.command.slice(0, 50)} — ${m.outputLines} lines (${ageStr})`);
+                let line = `${icon} #${m.id} [${m.status}] ${m.command.slice(0, 60)} — ${m.outputLines} lines (${ageStr})`;
+                if (m.exitCode !== undefined)
+                    line += ` exit=${m.exitCode}`;
+                lines.push(line);
+                if (m.status !== "running" && m.outputBuffer.length > 0) {
+                    const tail = m.outputBuffer.slice(-5);
+                    for (const out of tail) {
+                        lines.push(`  | ${out.slice(0, 100)}`);
+                    }
+                }
             }
             return Promise.resolve(textResult(lines.join("\n")));
         },

package/dist/monitor-manager.js

@@ -16,6 +16,7 @@ export class MonitorManager {
             status: "running",
             startedAt: Date.now(),
             outputLines: 0,
+            outputBuffer: [],
         };
         const abortController = new AbortController();
         const child = spawn("sh", ["-c", command], {
@@ -36,6 +37,8 @@ export class MonitorManager {
                 if (line.length === 0)
                     continue;
                 entry.outputLines++;
+                if (entry.outputBuffer.length < 200)
+                    entry.outputBuffer.push(line);
                 this.pi.events.emit("monitor:output", {
                     monitorId: id,
                     line,
@@ -49,6 +52,8 @@ export class MonitorManager {
                 if (line.length === 0)
                     continue;
                 entry.outputLines++;
+                if (entry.outputBuffer.length < 200)
+                    entry.outputBuffer.push(line);
                 this.pi.events.emit("monitor:output", {
                     monitorId: id,
                     line,

package/dist/scheduler.js

@@ -49,7 +49,9 @@ export class CronScheduler {
     armTimer(entry) {
         const _scheduleExpr = entry.trigger.type === "hybrid" ? entry.trigger.cron : entry.trigger.schedule;
         const nextFire = computeNextFire(entry);
-        const jitter = computeJitter(entry.id, entry.recurring, 30);
+        const minuteField = _scheduleExpr.trim().split(/\s+/)[0];
+        const minuteStep = minuteField.startsWith("*/") ? parseInt(minuteField.slice(2), 10) || 30 : 30;
+        const jitter = computeJitter(entry.id, entry.recurring, minuteStep);
         const fireTime = nextFire.getTime() + jitter;
         const now = Date.now();
         if (fireTime > entry.expiresAt) {
@@ -77,6 +79,13 @@ export class CronScheduler {
             }
             this.onFire(current);
             if (current.recurring) {
+                const fresh = this.store.get(entry.id);
+                if (fresh?.maxFires && (fresh.fireCount ?? 0) >= fresh.maxFires) {
+                    this.store.update(entry.id, { status: "expired" });
+                    this.timers.delete(entry.id);
+                    this.fireTimes.delete(entry.id);
+                    return;
+                }
                 this.armTimer(current);
             }
             else {

package/dist/store.d.ts

@@ -13,6 +13,7 @@ export declare class LoopStore {
         autoTask?: boolean;
         selfPaced?: boolean;
         readOnly?: boolean;
+        maxFires?: number;
     }): LoopEntry;
     get(id: string): LoopEntry | undefined;
     list(): LoopEntry[];
@@ -20,6 +21,7 @@ export declare class LoopStore {
         status?: LoopStatus;
         trigger?: Trigger;
         prompt?: string;
+        fireCount?: number;
     }): {
         entry: LoopEntry | undefined;
         changedFields: string[];

package/dist/store.js

@@ -119,6 +119,8 @@ export class LoopStore {
                 autoTask: opts.autoTask,
                 selfPaced: opts.selfPaced,
                 readOnly: opts.readOnly,
+                maxFires: opts.maxFires,
+                fireCount: 0,
                 createdAt: now,
                 updatedAt: now,
                 expiresAt: now + MAX_EXPIRY_DAYS * 24 * 60 * 60 * 1000,
@@ -155,6 +157,10 @@ export class LoopStore {
                 entry.prompt = fields.prompt;
                 changedFields.push("prompt");
             }
+            if (fields.fireCount !== undefined) {
+                entry.fireCount = fields.fireCount;
+                changedFields.push("fireCount");
+            }
             entry.updatedAt = Date.now();
             return { entry, changedFields };
         });
@@ -183,16 +189,19 @@ export class LoopStore {
     expireEventLoops(sessionStartedAt) {
         return this.withLock(() => {
             let count = 0;
-            for (const [_id, entry] of this.loops) {
+            const toDelete = [];
+            for (const [id, entry] of this.loops) {
                 if (entry.status !== "active")
                     continue;
                 if (entry.trigger.type === "event" || entry.trigger.type === "hybrid") {
                     if (entry.createdAt < sessionStartedAt) {
-                        entry.status = "expired";
+                        toDelete.push(id);
                         count++;
                     }
                 }
             }
+            for (const id of toDelete)
+                this.loops.delete(id);
             return count;
         });
     }

package/dist/trigger-system.js

@@ -89,12 +89,21 @@ export class TriggerSystem {
         this.hybridTimers.set(entry.id, timer);
     }
     fireLoop(entry) {
+        if (entry.maxFires && (entry.fireCount ?? 0) >= entry.maxFires) {
+            this.store.update(entry.id, { status: "expired" });
+            this.remove(entry.id);
+            return;
+        }
+        this.store.update(entry.id, { fireCount: (entry.fireCount ?? 0) + 1 });
         this.lastFireTime.set(entry.id, Date.now());
         this.pi.events.emit("loop:fire", {
             loopId: entry.id,
             prompt: entry.prompt,
             trigger: entry.trigger,
             timestamp: Date.now(),
+            readOnly: entry.readOnly,
+            recurring: entry.recurring,
+            autoTask: entry.autoTask,
         });
         if (!entry.recurring) {
             this.remove(entry.id);

package/dist/types.d.ts

@@ -30,6 +30,8 @@ export interface LoopEntry {
     autoTask?: boolean;
     selfPaced?: boolean;
     readOnly?: boolean;
+    maxFires?: number;
+    fireCount?: number;
 }
 export interface LoopStoreData {
     nextId: number;
@@ -45,6 +47,7 @@ export interface MonitorEntry {
     completedAt?: number;
     exitCode?: number;
     outputLines: number;
+    outputBuffer: string[];
 }
 export interface MonitorProcess {
     entry: MonitorEntry;

package/dist/ui/widget.js

@@ -26,8 +26,9 @@ export class LoopWidget {
         if (!this.uiCtx)
             return;
         const loops = this.store.list().filter(l => l.status === "active");
-        const monitors = this.monitorManager.list().filter(m => m.status === "running");
-        if (loops.length === 0 && monitors.length === 0) {
+        const monitors = this.monitorManager.list();
+        const hasContent = loops.length > 0 || monitors.length > 0;
+        if (!hasContent) {
             if (this.widgetRegistered) {
                 this.uiCtx.setWidget("loops", undefined);
                 this.widgetRegistered = false;
@@ -54,14 +55,21 @@ export class LoopWidget {
     }
     renderWidget(tui, _theme) {
         const loops = this.store.list().filter(l => l.status === "active");
-        const monitors = this.monitorManager.list().filter(m => m.status === "running");
+        const runningMonitors = this.monitorManager.list().filter(m => m.status === "running");
+        const completedMonitors = this.monitorManager.list().filter(m => m.status === "completed");
+        const allMonitors = [...runningMonitors, ...completedMonitors];
         const w = tui.terminal.columns;
         const trunc = (line) => truncateToWidth(line, w);
         const lines = [];
-        const total = loops.length + monitors.length;
+        const total = loops.length + allMonitors.length;
         if (total === 0)
             return [];
-        lines.push(trunc(`⟳ ${loops.length} loops · ${monitors.length} monitors`));
+        const headerParts = [`⟳ ${loops.length} loops`];
+        if (runningMonitors.length > 0)
+            headerParts.push(`${runningMonitors.length} running`);
+        if (completedMonitors.length > 0)
+            headerParts.push(`${completedMonitors.length} done`);
+        lines.push(trunc(headerParts.join(" · ")));
         for (const loop of loops.slice(0, MAX_VISIBLE)) {
             const icon = "◷";
             let schedule = "";
@@ -82,11 +90,14 @@ export class LoopWidget {
             }
             lines.push(trunc(`  ${icon} #${loop.id} ${loop.prompt.slice(0, 50)} → ${schedule}${timing}`));
         }
-        for (const m of monitors.slice(0, Math.max(0, MAX_VISIBLE - loops.length))) {
-            const icon = "◉";
+        for (const m of allMonitors.slice(0, Math.max(0, MAX_VISIBLE - loops.length))) {
+            const icon = m.status === "running" ? "◉" : "✓";
             const age = Date.now() - m.startedAt;
             const label = m.description || m.command.replace(/\n/g, " ").replace(/\s+/g, " ").trim().slice(0, 50);
-            lines.push(trunc(`  ${icon} #${m.id} ${label} ${m.outputLines} lines (${formatDuration(age)})`));
+            let line = `  ${icon} #${m.id} ${label} ${m.outputLines} lines (${formatDuration(age)})`;
+            if (m.exitCode !== undefined && m.status !== "running")
+                line += ` exit=${m.exitCode}`;
+            lines.push(trunc(line));
         }
         return lines;
     }

package/package.json

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

package/src/index.ts

@@ -41,6 +41,8 @@ interface LoopFireEvent {
   trigger: Trigger | string;
   timestamp: number;
   readOnly?: boolean;
+  recurring?: boolean;
+  autoTask?: boolean;
 }
 
 interface SessionSwitchEvent {
@@ -119,11 +121,37 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
+  async function hasPendingTasks(): Promise<number> {
+    if (!tasksAvailable) return -1;
+    try {
+      const requestId = randomUUID();
+      const count = await new Promise<number>((resolve) => {
+        const timer = setTimeout(() => { unsub(); resolve(-1); }, 3000);
+        const unsub = pi.events.on(`tasks:rpc:pending:reply:${requestId}`, (raw: unknown) => {
+          unsub(); clearTimeout(timer);
+          const reply = raw as { success: boolean; data?: { pending: number }; error?: string };
+          resolve(reply.success && reply.data ? reply.data.pending : -1);
+        });
+        pi.events.emit("tasks:rpc:pending", { requestId });
+      });
+      return count;
+    } catch {
+      return -1;
+    }
+  }
+
   // ── Loop fire handler ──
 
   function onLoopFire(entry: LoopEntry): void {
     debug(`loop:fire #${entry.id}`, { prompt: entry.prompt.slice(0, 50) });
 
+    if (entry.maxFires && (entry.fireCount ?? 0) >= entry.maxFires) {
+      debug(`loop #${entry.id} — reached maxFires ${entry.maxFires}, expiring`);
+      store.update(entry.id, { status: "expired" });
+      return;
+    }
+    store.update(entry.id, { fireCount: (entry.fireCount ?? 0) + 1 });
+
     if (entry.autoTask) {
       autoCreateTask(entry).then((taskId) => {
         if (taskId) debug(`loop #${entry.id} → task #${taskId}`);
@@ -136,6 +164,8 @@ export default function (pi: ExtensionAPI) {
       trigger: entry.trigger,
       timestamp: Date.now(),
       readOnly: entry.readOnly,
+      recurring: entry.recurring,
+      autoTask: entry.autoTask,
     });
   }
 
@@ -204,14 +234,22 @@ export default function (pi: ExtensionAPI) {
 
   // ── Loop fire handler — sends a user message to re-wake the agent ──
 
-  pi.events.on("loop:fire", (event: unknown) => {
+  pi.events.on("loop:fire", async (event: unknown) => {
     const data = event as LoopFireEvent;
 
-    if (_latestCtx?.hasPendingMessages()) {
-      debug(`loop:fire #${data.loopId} — agent has pending messages, skipping`);
+    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`);
+        return;
+      }
+    }
+
     const triggerInfo = typeof data.trigger === "string"
       ? data.trigger
       : data.trigger?.type === "cron"
@@ -267,12 +305,26 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **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
-- **readOnly**: restrict the agent to read-only tools when this loop fires (default: false)`,
+- **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: [
-      "When the user asks for a loop, repeating task, periodic check, or scheduled reminder, use LoopCreate — not raw Bash for/sleep/while.",
-      "Use LoopCreate for any 'every X seconds/minutes/hours' requests.",
+      "Use LoopCreate when the user asks for a repeating task, periodic check, scheduled reminder, or 'every X' — never use raw Bash for/sleep/while.",
+      "## Choosing trigger type",
+      "Prefer event triggers over cron when possible — they fire exactly when needed instead of polling.",
+      "Use event triggers for: tool completion ('tool_execution_end'), task creation ('tasks:created'), monitor completion ('monitor:done').",
+      "Use cron triggers only when: the user explicitly asks for a time interval, or there's no relevant pi event to subscribe to.",
+      "Hybrid triggers (cron + event) give you both: event-driven responsiveness with a cron safety-net fallback.",
+      "## Choosing an interval",
+      "Default to 5m unless the user specifies differently. Use shorter intervals only when time-sensitive.",
+      "## maxFires — prevent infinite token burn",
+      "Always set maxFires on polling loops so they don't run forever. For task-continuation loops, use maxFires: 20-50.",
+      "When a loop fires and finds nothing to do, call LoopDelete on its own ID to stop it — don't keep polling.",
+      "## readOnly mode",
+      "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.",
       "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
-      "After creating tasks with TaskCreate, create a loop to keep working through them: LoopCreate trigger='30s' prompt='Run TaskList, pick the next available pending task, work on it. Continue until all tasks are completed.' This ensures the agent keeps making progress across turns instead of stopping after one task.",
     ],
     parameters: Type.Object({
       trigger: Type.String({ description: "Cron expression (e.g., '5m', '1h', '0 9 * * 1-5'), event source (e.g., 'tool_execution_start'), or JSON hybrid spec" }),
@@ -282,10 +334,11 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       triggerType: Type.Optional(Type.String({ description: "cron, event, or hybrid (inferred from trigger string if omitted)", enum: ["cron", "event", "hybrid"] })),
       debounceMs: Type.Optional(Type.Number({ description: "Debounce for hybrid triggers (default: 30000)", default: 30000 })),
       readOnly: Type.Optional(Type.Boolean({ description: "Restrict the agent to read-only tools when this loop fires (default: false)", default: false })),
+      maxFires: Type.Optional(Type.Number({ description: "Auto-stop after N fires. Prevents infinite token burn on polling loops." })),
     }),
 
     execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      const { trigger: triggerInput, prompt, recurring, autoTask, triggerType, debounceMs, readOnly } = params;
+      const { trigger: triggerInput, prompt, recurring, autoTask, triggerType, debounceMs, readOnly, maxFires } = params;
 
       let trigger: Trigger;
       const inferred = triggerType ?? inferTriggerType(triggerInput);
@@ -315,9 +368,26 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
         autoTask,
         selfPaced: triggerInput === "self-paced" || prompt.toLowerCase().includes("self-paced"),
         readOnly,
+        maxFires,
       });
 
       triggerSystem.add(entry);
+
+      if (trigger.type === "event" && trigger.source === "monitor:done" && trigger.filter) {
+        try {
+          const filterObj = JSON.parse(trigger.filter);
+          const monitorId = filterObj.monitorId as string | undefined;
+          if (monitorId) {
+            const monitor = monitorManager.get(monitorId);
+            if (monitor && monitor.status !== "running") {
+              debug(`loop #${entry.id} — monitor #${monitorId} already ${monitor.status}, expiring`);
+              triggerSystem.remove(entry.id);
+              store.update(entry.id, { status: "expired" });
+            }
+          }
+        } catch { /* filter parse failure, ignore */ }
+      }
+
       widget.update();
 
       const triggerDesc = trigger.type === "cron"
@@ -337,6 +407,16 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
     },
   });
 
+  function handleMonitorDoneLoop(doneLoop: LoopEntry, monitorId: string): void {
+    triggerSystem.add(doneLoop);
+    const monitor = monitorManager.get(monitorId);
+    if (monitor && monitor.status !== "running") {
+      debug(`onDone loop #${doneLoop.id} — monitor #${monitorId} already ${monitor.status}, expiring`);
+      triggerSystem.remove(doneLoop.id);
+      store.update(doneLoop.id, { status: "expired" });
+    }
+  }
+
   function validateTrigger(trigger: Trigger): string | null {
     if (trigger.type === "cron") {
       const parts = trigger.schedule.trim().split(/\s+/);
@@ -499,7 +579,7 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
       if (params.onDone) {
         const doneTrigger: Trigger = { type: "event", source: "monitor:done", filter: JSON.stringify({ monitorId: entry.id }) };
         const doneLoop = store.create(doneTrigger, params.onDone, { recurring: false });
-        triggerSystem.add(doneLoop);
+        handleMonitorDoneLoop(doneLoop, entry.id);
         onDoneMsg = `\nonDone loop #${doneLoop.id}: fires when monitor completes — no polling needed`;
       }
 
@@ -518,7 +598,7 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
   pi.registerTool({
     name: "MonitorList",
     label: "MonitorList",
-    description: `List all monitors with their status, command, and output line count.`,
+    description: `List all monitors with their status, command, exit code, output line count, and last 5 lines of buffered output.`,
     parameters: Type.Object({}),
 
     execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
@@ -530,7 +610,16 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
         const icon = m.status === "running" ? "◉" : m.status === "completed" ? "✓" : "✗";
         const age = Date.now() - m.startedAt;
         const ageStr = formatRemaining(age);
-        lines.push(`${icon} #${m.id} [${m.status}] ${m.command.slice(0, 50)} — ${m.outputLines} lines (${ageStr})`);
+        let line = `${icon} #${m.id} [${m.status}] ${m.command.slice(0, 60)} — ${m.outputLines} lines (${ageStr})`;
+        if (m.exitCode !== undefined) line += ` exit=${m.exitCode}`;
+        lines.push(line);
+
+        if (m.status !== "running" && m.outputBuffer.length > 0) {
+          const tail = m.outputBuffer.slice(-5);
+          for (const out of tail) {
+            lines.push(`  | ${out.slice(0, 100)}`);
+          }
+        }
       }
 
       return Promise.resolve(textResult(lines.join("\n")));

package/src/monitor-manager.ts

@@ -19,6 +19,7 @@ export class MonitorManager {
       status: "running",
       startedAt: Date.now(),
       outputLines: 0,
+      outputBuffer: [],
     };
 
     const abortController = new AbortController();
@@ -41,6 +42,7 @@ export class MonitorManager {
       for (const line of lines) {
         if (line.length === 0) continue;
         entry.outputLines++;
+        if (entry.outputBuffer.length < 200) entry.outputBuffer.push(line);
         this.pi.events.emit("monitor:output", {
           monitorId: id,
           line,
@@ -54,6 +56,7 @@ export class MonitorManager {
       for (const line of lines) {
         if (line.length === 0) continue;
         entry.outputLines++;
+        if (entry.outputBuffer.length < 200) entry.outputBuffer.push(line);
         this.pi.events.emit("monitor:output", {
           monitorId: id,
           line,

package/src/scheduler.ts

@@ -58,7 +58,9 @@ export class CronScheduler {
     const _scheduleExpr = entry.trigger.type === "hybrid" ? entry.trigger.cron : (entry.trigger as { schedule: string }).schedule;
 
     const nextFire = computeNextFire(entry);
-    const jitter = computeJitter(entry.id, entry.recurring, 30);
+    const minuteField = _scheduleExpr.trim().split(/\s+/)[0];
+    const minuteStep = minuteField.startsWith("*/") ? parseInt(minuteField.slice(2), 10) || 30 : 30;
+    const jitter = computeJitter(entry.id, entry.recurring, minuteStep);
     const fireTime = nextFire.getTime() + jitter;
     const now = Date.now();
 
@@ -92,6 +94,13 @@ export class CronScheduler {
       this.onFire(current);
 
       if (current.recurring) {
+        const fresh = this.store.get(entry.id);
+        if (fresh?.maxFires && (fresh.fireCount ?? 0) >= fresh.maxFires) {
+          this.store.update(entry.id, { status: "expired" });
+          this.timers.delete(entry.id);
+          this.fireTimes.delete(entry.id);
+          return;
+        }
         this.armTimer(current);
       } else {
         this.timers.delete(entry.id);

package/src/store.ts

@@ -95,7 +95,7 @@ export class LoopStore {
     }
   }
 
-  create(trigger: Trigger, prompt: string, opts: { recurring: boolean; autoTask?: boolean; selfPaced?: boolean; readOnly?: boolean }): LoopEntry {
+  create(trigger: Trigger, prompt: string, opts: { recurring: boolean; autoTask?: boolean; selfPaced?: boolean; readOnly?: boolean; maxFires?: number }): LoopEntry {
     return this.withLock(() => {
       if (this.loops.size >= MAX_LOOPS) {
         throw new Error(`Maximum of ${MAX_LOOPS} loops reached. Delete some before creating new ones.`);
@@ -110,6 +110,8 @@ export class LoopStore {
         autoTask: opts.autoTask,
         selfPaced: opts.selfPaced,
         readOnly: opts.readOnly,
+        maxFires: opts.maxFires,
+        fireCount: 0,
         createdAt: now,
         updatedAt: now,
         expiresAt: now + MAX_EXPIRY_DAYS * 24 * 60 * 60 * 1000,
@@ -129,7 +131,7 @@ export class LoopStore {
     return Array.from(this.loops.values()).sort((a, b) => Number(a.id) - Number(b.id));
   }
 
-  update(id: string, fields: { status?: LoopStatus; trigger?: Trigger; prompt?: string }): { entry: LoopEntry | undefined; changedFields: string[] } {
+  update(id: string, fields: { status?: LoopStatus; trigger?: Trigger; prompt?: string; fireCount?: number }): { entry: LoopEntry | undefined; changedFields: string[] } {
     return this.withLock(() => {
       const entry = this.loops.get(id);
       if (!entry) return { entry: undefined, changedFields: [] };
@@ -147,6 +149,10 @@ export class LoopStore {
         entry.prompt = fields.prompt;
         changedFields.push("prompt");
       }
+      if (fields.fireCount !== undefined) {
+        entry.fireCount = fields.fireCount;
+        changedFields.push("fireCount");
+      }
       entry.updatedAt = Date.now();
       return { entry, changedFields };
     });
@@ -177,15 +183,17 @@ export class LoopStore {
   expireEventLoops(sessionStartedAt: number): number {
     return this.withLock(() => {
       let count = 0;
-      for (const [_id, entry] of this.loops) {
+      const toDelete: string[] = [];
+      for (const [id, entry] of this.loops) {
         if (entry.status !== "active") continue;
         if (entry.trigger.type === "event" || entry.trigger.type === "hybrid") {
           if (entry.createdAt < sessionStartedAt) {
-            entry.status = "expired";
+            toDelete.push(id);
             count++;
           }
         }
       }
+      for (const id of toDelete) this.loops.delete(id);
       return count;
     });
   }

package/src/trigger-system.ts

@@ -94,12 +94,22 @@ export class TriggerSystem {
   }
 
   private fireLoop(entry: LoopEntry): void {
+    if (entry.maxFires && (entry.fireCount ?? 0) >= entry.maxFires) {
+      this.store.update(entry.id, { status: "expired" });
+      this.remove(entry.id);
+      return;
+    }
+    this.store.update(entry.id, { fireCount: (entry.fireCount ?? 0) + 1 });
+
     this.lastFireTime.set(entry.id, Date.now());
     this.pi.events.emit("loop:fire", {
       loopId: entry.id,
       prompt: entry.prompt,
       trigger: entry.trigger,
       timestamp: Date.now(),
+      readOnly: entry.readOnly,
+      recurring: entry.recurring,
+      autoTask: entry.autoTask,
     });
 
     if (!entry.recurring) {

package/src/types.ts

@@ -32,6 +32,8 @@ export interface LoopEntry {
   autoTask?: boolean;
   selfPaced?: boolean;
   readOnly?: boolean;
+  maxFires?: number;
+  fireCount?: number;
 }
 
 export interface LoopStoreData {
@@ -49,6 +51,7 @@ export interface MonitorEntry {
   completedAt?: number;
   exitCode?: number;
   outputLines: number;
+  outputBuffer: string[];
 }
 
 export interface MonitorProcess {

package/src/ui/widget.ts

@@ -35,9 +35,10 @@ export class LoopWidget {
     if (!this.uiCtx) return;
 
     const loops = this.store.list().filter(l => l.status === "active");
-    const monitors = this.monitorManager.list().filter(m => m.status === "running");
+    const monitors = this.monitorManager.list();
+    const hasContent = loops.length > 0 || monitors.length > 0;
 
-    if (loops.length === 0 && monitors.length === 0) {
+    if (!hasContent) {
       if (this.widgetRegistered) {
         this.uiCtx.setWidget("loops", undefined);
         this.widgetRegistered = false;
@@ -66,16 +67,21 @@ export class LoopWidget {
 
   private renderWidget(tui: TUI, _theme: Theme): string[] {
     const loops = this.store.list().filter(l => l.status === "active");
-    const monitors = this.monitorManager.list().filter(m => m.status === "running");
+    const runningMonitors = this.monitorManager.list().filter(m => m.status === "running");
+    const completedMonitors = this.monitorManager.list().filter(m => m.status === "completed");
+    const allMonitors = [...runningMonitors, ...completedMonitors];
     const w = tui.terminal.columns;
     const trunc = (line: string) => truncateToWidth(line, w);
 
     const lines: string[] = [];
-    const total = loops.length + monitors.length;
+    const total = loops.length + allMonitors.length;
 
     if (total === 0) return [];
 
-    lines.push(trunc(`⟳ ${loops.length} loops · ${monitors.length} monitors`));
+    const headerParts: string[] = [`⟳ ${loops.length} loops`];
+    if (runningMonitors.length > 0) headerParts.push(`${runningMonitors.length} running`);
+    if (completedMonitors.length > 0) headerParts.push(`${completedMonitors.length} done`);
+    lines.push(trunc(headerParts.join(" · ")));
 
     for (const loop of loops.slice(0, MAX_VISIBLE)) {
       const icon = "◷";
@@ -96,11 +102,13 @@ export class LoopWidget {
       lines.push(trunc(`  ${icon} #${loop.id} ${loop.prompt.slice(0, 50)} → ${schedule}${timing}`));
     }
 
-    for (const m of monitors.slice(0, Math.max(0, MAX_VISIBLE - loops.length))) {
-      const icon = "◉";
+    for (const m of allMonitors.slice(0, Math.max(0, MAX_VISIBLE - loops.length))) {
+      const icon = m.status === "running" ? "◉" : "✓";
       const age = Date.now() - m.startedAt;
       const label = m.description || m.command.replace(/\n/g, " ").replace(/\s+/g, " ").trim().slice(0, 50);
-      lines.push(trunc(`  ${icon} #${m.id} ${label} ${m.outputLines} lines (${formatDuration(age)})`));
+      let line = `  ${icon} #${m.id} ${label} ${m.outputLines} lines (${formatDuration(age)})`;
+      if (m.exitCode !== undefined && m.status !== "running") line += ` exit=${m.exitCode}`;
+      lines.push(trunc(line));
     }
 
     return lines;