@trevonistrevon/pi-loop 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.6.3](https://github.com/trvon/pi-loop/compare/pi-loop-v0.6.2...pi-loop-v0.6.3) (2026-07-17)
+
+
+### Bug Fixes
+
+* **loop:** prevent premature self-deletion ([6049e15](https://github.com/trvon/pi-loop/commit/6049e1599d9c6c1ab99a9eada72ec75307f25ca1))
+* **ui:** restore loop status after resets ([da580f0](https://github.com/trvon/pi-loop/commit/da580f0d2f5ac414bc3cd884e27b757decd44b5d))
+
+## [0.6.2](https://github.com/trvon/pi-loop/compare/pi-loop-v0.6.1...pi-loop-v0.6.2) (2026-07-17)
+
+
+### Bug Fixes
+
+* **deps:** require patched pi runtime ([459a44a](https://github.com/trvon/pi-loop/commit/459a44af75dce174e53d70ef0427ca773845a912))
+* **loop:** start dynamic goals immediately ([790959c](https://github.com/trvon/pi-loop/commit/790959c02d3c2b301526f780122aacf533429bc5))
+* **monitor:** wake after timeouts ([478535b](https://github.com/trvon/pi-loop/commit/478535b3c837e74074dc022ea35ec3ba9b18f533))
+
 ## [0.6.1](https://github.com/trvon/pi-loop/compare/pi-loop-v0.6.0...pi-loop-v0.6.1) (2026-07-16)
 
 

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
 <h1 align="center">@trevonistrevon/pi-loop</h1>
-<h6 align="center">Cron, event, and dynamic goal loops for the pi coding agent. Background monitors, scheduled re-wakes, pi-tasks integration, and native task fallback.</h6>
+<h6 align="center">Scheduled and event-driven agent re-wakes for pi, with dynamic goals and background process monitoring.</h6>
 </p>
 
 ## Install
@@ -11,177 +11,50 @@ pi install npm:@trevonistrevon/pi-loop
 
 ## Quick start
 
-```text
-LoopCreate trigger="5m" prompt="Check if the build passed"
-LoopCreate trigger="tool_execution_start" prompt="Log the tool being used" triggerType="event"
-LoopList
-LoopDelete id="1"
-```
+Create scheduled, event-driven, or self-paced loops:
 
 ```text
-MonitorCreate command="tail -n0 -f build.log" description="Watch build"
-MonitorCreate command="python train.py" onDone="Analyze results and report best loss"
-MonitorList
-MonitorStop monitorId="1"
+/loop 5m check the deploy
+/loop event tasks:created process the backlog
+/loop finish the release
 ```
 
-When `pi-tasks` is not installed, `pi-loop` also exposes native task tools after startup detection:
+Or use the tools directly:
 
 ```text
-TaskCreate subject="Fix deploy polling" description="Switch deploy check to event-driven loop"
-TaskList
-TaskUpdate id="1" status="in_progress"
-TaskDelete id="1"
+LoopCreate trigger="5m" prompt="Check if the build passed" maxFires=12
+LoopCreate trigger="tool_execution_start" prompt="Log the tool" triggerType="event" recurring=true
+LoopList
+LoopDelete id="1"
 ```
 
-## Commands
-
-`/loop` creates scheduled, event-triggered, or self-paced dynamic goal loops.
+Run work in the background and wake the agent when it succeeds, fails, or times out:
 
 ```text
-/loop                                      # menu
-/loop 5m check the deploy                  # 5-minute cron loop
-/loop event tasks:created process backlog  # event loop
-/loop finish the release                   # dynamic goal loop
+MonitorCreate command="python train.py" onDone="Analyze results and report best loss"
+MonitorList
+MonitorStop monitorId="1"
 ```
 
-Dynamic goal loops wake immediately when the agent is idle. After each iteration, the agent calls `LoopUpdate` with one of:
-
-- `status="continue"` to save progress and wake again when idle
-- `status="continue" nextInterval="3m"` to schedule a timed next wake
-- `status="paused"` when blocked
-- `status="completed"` to finish and delete the loop
+## What it provides
 
-Paused dynamic loops can be resumed from the `/loop` menu. Dynamic loops recover their wake after a process restart or session switch if an in-memory notification was lost.
+- Cron, event, hybrid, and dynamic goal loops
+- Idle-safe agent re-wakes with dynamic-loop restart/session-switch recovery
+- Background command monitoring with buffered output and `onDone` wakes
+- Optional `pi-tasks` integration and a native task fallback
+- Session-isolated persistence and a compact TUI status line
 
-`/tasks` — interactive native task viewer/manager, only registered when `pi-tasks` is absent.
+## Commands and tools
 
-```text
-/tasks                        # open native task viewer
-/tasks Write README updates   # quick-create native task
-```
-
-## Tools
-
-| Tool | What it does |
+| Surface | Purpose |
 |---|---|
-| `LoopCreate` | Schedule a prompt on a cron timer, a pi event, or both with debounce |
-| `LoopList` | Show active loops with IDs, triggers, and next-fire times |
-| `LoopUpdate` | Continue, pause, or complete a dynamic goal loop and save its progress |
-| `LoopDelete` | Delete or pause a loop |
-| `MonitorCreate` | Run a background command, stream output as `monitor:output` events. Use `onDone` for auto-notify on completion |
-| `MonitorList` | Show monitors with status, uptime, and output line count |
-| `MonitorStop` | Stop a monitor (SIGTERM → 5s → SIGKILL) |
-| `TaskCreate` | Create a native fallback task when `pi-tasks` is absent |
-| `TaskList` | List native fallback tasks |
-| `TaskUpdate` | Update native fallback task status/details |
-| `TaskDelete` | Delete a native fallback task |
-
-Trigger types: `cron` (`5m`, `1h`, `0 9 * * 1-5`), `event` (any pi event source), `hybrid` (both, debounced), or `dynamic` (self-paced goal loops created with `/loop <goal>`).
-
-## Tasks
-
-### With `pi-tasks`
-
-Works with [@tintinweb/pi-tasks](https://github.com/tintinweb/pi-tasks). Pass `autoTask: true` on `LoopCreate` and each loop fire auto-creates a tracked task. Detection happens over pi's event bus — no manual wiring.
-
-### Without `pi-tasks`
-
-If `pi-tasks` does not respond during startup detection, `pi-loop` registers a native fallback task system for the session:
-
-- session- or project-scoped task files under `.pi/tasks/` depending on `PI_LOOP_SCOPE`
-- `TaskCreate`, `TaskList`, `TaskUpdate`, `TaskDelete`
-- `/tasks` interactive viewer
-- compact status-line task tracking
-- native task RPC replies on `tasks:rpc:ping`, `tasks:rpc:create`, `tasks:rpc:pending`, `tasks:rpc:clean`, and `tasks:rpc:update`
-
-This fallback is session-sticky: `pi-loop` decides once at startup whether `pi-tasks` or native tasks own task management for that session.
-
-### Task and backlog events
-
-`pi-loop` emits native task lifecycle events that other extensions can consume directly:
-
-- `tasks:created`
-- `tasks:started`
-- `tasks:completed`
-- `tasks:reopened`
-- `tasks:updated`
-- `tasks:deleted`
-
-Payloads carry `previousStatus`. Transition events (`tasks:started` /
-`tasks:completed` / `tasks:reopened`) report the status before the transition;
-`tasks:updated` (a details edit) reports the status current at edit time — so a
-combined status+details update never fabricates a second transition. (Changed
-in 0.6.0: the tool path previously reused the pre-transition status.)
-- `tasks:backlog_empty` — emitted when a task-backlog worker observes zero pending tasks and is about to auto-delete
-- `loops:autodeleted` — emitted for each loop that `pi-loop` auto-deletes, including backlog workers removed because the task queue drained
-
-### Cross-extension task RPC
-
-Other extensions can create and manage native tasks without importing `pi-loop` internals. `pi-loop` answers `ping` over `pi.events` from extension init; the other verbs unlock once the pi-tasks detection probe settles (a few seconds at most, immediate when no provider replies race it). The whole server stands down (silent no-op) once an external `pi-tasks` is detected:
-
-| Channel | Request | Reply |
-|---|---|---|
-| `tasks:rpc:ping` | `{}` | `{ version, provider }` |
-| `tasks:rpc:pending` | `{}` | `{ pending }` |
-| `tasks:rpc:create` | `{ subject, description, metadata? }` | `{ id, task }` |
-| `tasks:rpc:clean` | `{}` | `{ pruned }` |
-| `tasks:rpc:update` | `{ id, status?, subject?, description? }` | `{ task }` |
-
-Every request/reply pair follows the same contract: emit `{ requestId, ...params }` on the channel, receive an envelope on `<channel>:reply:<requestId>` — `{ success: true, data }` or `{ success: false, error }`.
-
-`@trevonistrevon/pi-loop/api` exports typed channel constants and a client helper so consumers don't hand-roll the envelope:
-
-```ts
-import { TASKS_RPC, rpcCall } from "@trevonistrevon/pi-loop/api";
-
-const { id, task } = await rpcCall(pi.events, TASKS_RPC.create, {
-  subject: "Fix deploy polling",
-  description: "Switch deploy check to event-driven loop",
-});
-```
-
-`rpcCall` rejects on failure or timeout instead of returning a sentinel; wrap it in `try/catch` if you want fallback behavior. Import only from `@trevonistrevon/pi-loop/api` — the package's `exports` map blocks deep `src/` imports.
-
-## Status line
-
-`pi-loop` keeps a compact persistent status line in the TUI.
-
-When active work exists, it shows a single focus-friendly line such as:
-
-```text
-1 loop · 1 monitor
-2 tasks | active: Fix deploy polling
-1 loop · 2 monitors · 3 tasks | next: Update README
-```
-
-When no loops, monitors, or native tasks are active, the status line clears completely.
-
-Only task counts and the single active/next task are shown there so attention stays on what is currently happening. Use `LoopList`, `MonitorList`, and `/tasks` for detail.
-
-## Configuration
-
-| Variable | Effect | Default |
-|---|---|---|
-| `PI_LOOP` | Store path override. `off` to disable, absolute or project-relative path | unset → derived from `PI_LOOP_SCOPE` |
-| `PI_LOOP_SCOPE` | `memory` (ephemeral), `session` (per-session file), `project` (shared) | `session` |
-| `PI_LOOP_DEBUG` | Debug logging to stderr | unset |
-
-In `session` scope (default), loop and task files are saved per session ID (e.g. `.pi/loops/loops-<sessionId>.json` and `.pi/tasks/tasks-<sessionId>.json`) so concurrent sessions and worktree agents do not share state. In `memory` scope nothing persists to disk.
-
-### Recommended scope policy
-
-Keep `PI_LOOP_SCOPE=session` as the default.
-
-- `session` is the best balance for normal use: it preserves loops/tasks across a session restart while isolating concurrent sessions and worktrees.
-- `memory` is best for disposable scratch work, tests, or situations where you explicitly do not want any persisted loop/task state.
-- `project` should be opt-in for intentionally shared automation, because it allows multiple sessions in the same repo to see the same persisted state.
-
-
-
-## Limits
+| `/loop` | Create or manage scheduled, event, and dynamic goal loops |
+| `/tasks` | Manage native fallback tasks when `pi-tasks` is absent |
+| `LoopCreate`, `LoopList`, `LoopUpdate`, `LoopDelete` | Create and control loops |
+| `MonitorCreate`, `MonitorList`, `MonitorStop` | Run and inspect background commands |
+| `TaskCreate`, `TaskList`, `TaskUpdate`, `TaskDelete` | Native fallback task management |
 
-25 active loops, 25 running monitors. Recurring loops expire after 7 days.
+See the [usage guide](./docs/USAGE_GUIDE.md) for trigger types, dynamic loop lifecycle, monitor behavior, task integration, configuration, events, and the public RPC API.
 
 ## Development
 

package/dist/commands/loop-command.d.ts

@@ -24,6 +24,7 @@ export interface LoopCommandOptions {
     getStore: () => LoopStoreLike;
     getTriggerSystem: () => TriggerSystemLike;
     updateWidget: () => void;
+    onDynamicLoopActivated?: (entry: LoopEntry) => void;
 }
 export declare function registerLoopCommand(options: LoopCommandOptions): void;
 export {};

package/dist/commands/loop-command.js

@@ -29,7 +29,7 @@ function parseLoopCommandRoute(input) {
     return { type: "dynamic", goal: trimmed };
 }
 export function registerLoopCommand(options) {
-    const { pi, getStore, getTriggerSystem, updateWidget } = options;
+    const { pi, getStore, getTriggerSystem, updateWidget, onDynamicLoopActivated } = options;
     function createCronLoop(ui, interval, prompt, notifyEvery) {
         let entry;
         try {
@@ -82,6 +82,7 @@ export function registerLoopCommand(options) {
         getTriggerSystem().add(entry);
         updateWidget();
         ui.notify(`Dynamic loop #${entry.id} created — ${goal.slice(0, 50)}`, "info");
+        onDynamicLoopActivated?.(entry);
     }
     async function viewLoops(ui) {
         const loops = getStore().list();
@@ -127,6 +128,8 @@ export function registerLoopCommand(options) {
                     getTriggerSystem().add(resumed);
                     updateWidget();
                     ui.notify(`Loop #${entry.id} resumed`, "info");
+                    if (resumed.trigger.type === "dynamic")
+                        onDynamicLoopActivated?.(resumed);
                 }
             }
         }

package/dist/index.js

@@ -181,7 +181,9 @@ export default function (pi) {
             timestamp: Date.now(),
             readOnly: entry.readOnly,
             recurring: false,
+            persistent: entry.recurring,
             autoTask: true,
+            taskBacklog: entry.taskBacklog,
         });
         return true;
     }
@@ -250,7 +252,9 @@ export default function (pi) {
             timestamp: firedAt,
             readOnly: firedEntry.readOnly,
             recurring: firedEntry.recurring,
+            persistent: firedEntry.recurring,
             autoTask: firedEntry.autoTask,
+            taskBacklog: firedEntry.taskBacklog,
             dynamic: firedEntry.dynamic,
         });
     }
@@ -331,6 +335,9 @@ export default function (pi) {
         updateWidget: () => {
             widget.update();
         },
+        onDynamicLoopActivated: (entry) => {
+            onLoopFire(entry);
+        },
     });
     // ── Native task tools (only when pi-tasks is absent) ──
     // Only tool/command registration stays deferred: the tool names collide with

package/dist/monitor-manager.d.ts

@@ -22,7 +22,7 @@ export declare class MonitorManager {
     create(command: string, description?: string, timeout?: number): MonitorEntry;
     get(id: string): MonitorEntry | undefined;
     list(): MonitorEntry[];
-    stop(id: string): Promise<boolean>;
+    stop(id: string, reason?: "manual" | "timeout"): Promise<boolean>;
     onComplete(id: string, callback: () => void): boolean;
     getProcess(id: string): MonitorProcess | undefined;
 }

package/dist/monitor-manager.js

@@ -190,7 +190,7 @@ export class MonitorManager {
         if (timeout > 0) {
             setTimeout(() => {
                 if (bp.entry.status === "running") {
-                    this.stop(id);
+                    void this.stop(id, "timeout");
                 }
             }, timeout);
         }
@@ -206,7 +206,7 @@ export class MonitorManager {
             .map(bp => bp.entry)
             .sort((a, b) => Number(a.id) - Number(b.id));
     }
-    async stop(id) {
+    async stop(id, reason = "manual") {
         const bp = this.processes.get(id);
         if (!bp || bp.entry.status !== "running")
             return false;
@@ -218,7 +218,7 @@ export class MonitorManager {
             entityId: id,
             payload: {
                 id,
-                reason: "manual",
+                reason,
             },
         });
         this.schedulePrune(id);
@@ -236,6 +236,15 @@ export class MonitorManager {
                 resolve();
             });
         });
+        if (reason === "timeout") {
+            this.pi.events.emit("monitor:error", {
+                monitorId: id,
+                error: `Timed out after ${bp.entry.timeout}ms`,
+                outputLines: bp.entry.outputLines,
+            });
+            for (const callback of bp.completionCallbacks)
+                callback();
+        }
         bp.completionCallbacks = [];
         for (const resolve of bp.waiters)
             resolve();

package/dist/notification-reducer.d.ts

@@ -7,7 +7,9 @@ export interface ReducerNotification {
     timestamp: number;
     trigger: unknown;
     recurring?: boolean;
+    persistent?: boolean;
     autoTask?: boolean;
+    taskBacklog?: boolean;
     readOnly?: boolean;
     dynamic?: DynamicLoopState;
 }

package/dist/runtime/notification-runtime.d.ts

@@ -7,7 +7,9 @@ export interface LoopFireEvent {
     timestamp: number;
     readOnly?: boolean;
     recurring?: boolean;
+    persistent?: boolean;
     autoTask?: boolean;
+    taskBacklog?: boolean;
     dynamic?: DynamicLoopState;
 }
 export interface PendingNotification extends LoopFireEvent {

package/dist/runtime/notification-runtime.js

@@ -63,12 +63,18 @@ export function createNotificationRuntime(options) {
                 lines.push(`Metrics: ${dynamic.metrics}`);
             if (dynamic?.doneCriteria)
                 lines.push(`Done criteria: ${dynamic.doneCriteria}`);
-            lines.push("Continue toward the goal. When done call LoopUpdate with status=\"completed\". If more work remains, call LoopUpdate with status=\"continue\" plus state/metrics. Omit nextInterval for idle-driven rewake; include nextInterval for a timed wake. If blocked, use status=\"paused\".");
+            lines.push(`Loop lifecycle: Loop #${loopId} is the persistent controller for the overall goal. Do not call LoopDelete after this iteration.`, "Before ending this turn, call LoopUpdate exactly once: use status=\"completed\" only when the overall goal and done criteria are satisfied; use status=\"continue\" when any work remains, with state/metrics and optional nextInterval; use status=\"paused\" only when genuinely blocked. Omit nextInterval for an idle-driven rewake.");
             return lines.join("\n");
         }
+        const lifecycle = data.taskBacklog
+            ? `Backlog lifecycle: Loop #${loopId} is managed automatically. Do not call LoopDelete; when no pending tasks remain, report that and end this iteration.`
+            : (data.persistent ?? data.recurring)
+                ? `Loop lifecycle: Loop #${loopId} is recurring and remains active after this iteration. Do not call LoopDelete or pause it merely because this run finished, found no changes, or has no immediate work. Stop it only when the user or the loop prompt explicitly requires cancellation.`
+                : `Loop lifecycle: Loop #${loopId} is a one-shot wake and cleanup is automatic. Do not call LoopDelete.`;
         return [
             `[pi-loop] Loop #${loopId} fired (${triggerInfo}).${constraint}`,
             prompt,
+            lifecycle,
         ].join("\n");
     }
     function buildPendingNotification(data) {
@@ -97,8 +103,10 @@ export function createNotificationRuntime(options) {
                 loopId: notification.loopId,
                 trigger: notification.trigger,
                 recurring: notification.recurring,
+                persistent: notification.persistent,
                 readOnly: notification.readOnly,
                 autoTask: notification.autoTask,
+                taskBacklog: notification.taskBacklog,
                 dynamic: notification.dynamic,
                 timestamp: notification.timestamp,
             },

package/dist/runtime/session-runtime.js

@@ -15,8 +15,11 @@ export function registerSessionRuntimeHooks(options) {
             return;
         heartbeatTimer = setInterval(() => {
             // Swallow pump failures so a transient error never surfaces as an
-            // unhandled rejection; the next tick retries.
-            void pumpLoops().catch(() => { });
+            // unhandled rejection; repaint still runs so cleared harness UI heals.
+            void pumpLoops()
+                .catch(() => { })
+                .then(() => widget.update())
+                .catch(() => { });
         }, HEARTBEAT_MS);
         heartbeatTimer.unref?.();
     }
@@ -45,7 +48,6 @@ export function registerSessionRuntimeHooks(options) {
             getStore().expireEventLoops(sessionStartedAt);
             getTriggerSystem().start();
             ensureHeartbeat();
-            widget.update();
         }
     }
     async function pumpLoops() {
@@ -66,6 +68,15 @@ export function registerSessionRuntimeHooks(options) {
         }
         getScheduler().pump(Date.now(), (entry) => !pendingTasks.has(entry.id));
     }
+    pi.on("session_start", async (_event, ctx) => {
+        setLatestCtx(ctx);
+        setSessionId(ctx.sessionManager.getSessionId());
+        widget.setUICtx(ctx.ui);
+        upgradeStoreIfNeeded(ctx);
+        ensureHeartbeat();
+        showPersistedLoops();
+        widget.update();
+    });
     pi.on("turn_start", async (_event, ctx) => {
         setLatestCtx(ctx);
         setSessionId(ctx.sessionManager.getSessionId());

package/dist/runtime/task-backlog-runtime.d.ts

@@ -2,7 +2,7 @@ import type { TaskStore } from "../task-store.js";
 import type { LoopDeletionTombstoneInput, LoopEntry, Trigger } from "../types.js";
 import { type LoopAutodeletedPayload, type TaskBacklogEmptyPayload } from "./loop-events.js";
 export declare const AUTO_TASK_WORKER_THRESHOLD = 5;
-export declare const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, complete it. If no pending tasks remain, call LoopDelete on your own loop ID.";
+export declare const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, and complete it. If no pending tasks remain, report that and end this iteration; pi-loop manages the worker lifecycle automatically.";
 export interface TaskBacklogRuntimeOptions {
     getLoops: () => LoopEntry[];
     createLoop: (trigger: Trigger, prompt: string, options: {

package/dist/runtime/task-backlog-runtime.js

@@ -2,7 +2,7 @@ import { createCoordinator, } from "../coordinator.js";
 import { reduceTaskBacklogEvent, } from "../task-backlog-coordinator.js";
 import { buildLoopAutodeletedPayload, buildTaskBacklogEmptyPayload, } from "./loop-events.js";
 export const AUTO_TASK_WORKER_THRESHOLD = 5;
-export const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, complete it. If no pending tasks remain, call LoopDelete on your own loop ID.";
+export const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, and complete it. If no pending tasks remain, report that and end this iteration; pi-loop manages the worker lifecycle automatically.";
 export function createTaskBacklogRuntime(options) {
     const { getLoops, createLoop, deleteLoop, recordDeletionTombstone, addTrigger, removeTrigger, updateWidget, hasPendingTasks, bootstrapTaskLoop, triggerHasEventSource, emitLoopAutodeleted, emitTaskBacklogEmpty, debug, } = options;
     function isAutoTaskWorkerLoop(entry) {

package/dist/tools/loop-tools.js

@@ -138,7 +138,11 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **autoTask**: when pi-tasks is loaded or native task fallback is active, auto-create a task on each fire
 - **taskBacklog**: mark this as a task-backlog worker loop so it auto-deletes when pending tasks reach zero
 - **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`,
+- **maxFires**: auto-stop after N fires — prevents infinite token burn on polling loops
+
+## Loop Lifecycle
+
+Recurring loops persist across fires. A completed iteration, unchanged result, or temporarily empty check is not a reason to delete the loop. Delete only when the user explicitly cancels it or its stated stop condition is satisfied. Dynamic loops must be advanced with LoopUpdate, not LoopDelete.`,
         promptGuidelines: [
             "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",
@@ -150,14 +154,14 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             "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.",
+            "Recurring loops are persistent controllers. Do not call LoopDelete after a normal fire, an unchanged check, or one completed iteration; only delete when the user explicitly asks to cancel or the loop's stated stop condition is satisfied.",
             "## readOnly mode",
             "Set readOnly: true for loops that only observe and report (checks, status polls). This prevents unintended changes.",
             "## Task-driven workflows",
             "Do not rely on a past 'tasks:created' event to replay. If tasks already exist, bootstrap the first pass in the current turn or use a hybrid/event loop that can catch future task creation and a cron safety-net.",
             "Use autoTask only when you want the loop itself to create a task on each fire. For processing an existing task backlog, leave autoTask off and have the loop run TaskList to pick the next pending task.",
             "Set taskBacklog: true for backlog worker loops that process the existing pending queue. Backlog worker loops bootstrap against existing pending tasks and auto-delete when the queue reaches zero.",
-            "When no tasks are pending, the loop should stop itself or skip the wake entirely — no tokens burned on empty polls.",
+            "For taskBacklog loops, do not instruct the agent to delete the loop; pi-loop auto-deletes it when the pending count reaches zero.",
             "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
         ],
         parameters: Type.Object({
@@ -230,7 +234,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
                 (entry.taskBacklog ? "Backlog worker: enabled\n" : "") +
                 (bootstrapped ? "Backlog: initial wake queued for existing pending tasks\n" : "") +
                 (isTaskSystemReady() ? "" : "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)`));
+                `ID: ${entry.id} (persists until explicitly canceled or a configured stop condition is met)`));
         },
     });
     pi.registerTool({
@@ -269,7 +273,7 @@ Use this before creating new loops to avoid duplicates, or to find IDs for LoopD
         label: "LoopUpdate",
         description: `Update progress for a dynamic loop.
 
-Use this after a dynamic loop wake. Mark status as "continue" with updated state/metrics and optional nextInterval, "completed" when the goal is done, or "paused" to stop temporarily.`,
+Use this exactly once after each dynamic loop wake. Mark status as "continue" with updated state/metrics and optional nextInterval whenever any work remains, "completed" only when the overall goal and done criteria are satisfied, or "paused" when genuinely blocked. Do not use LoopDelete to finish an iteration.`,
         parameters: Type.Object({
             id: Type.String({ description: "Dynamic loop ID to update" }),
             status: Type.String({ description: "continue, completed, or paused", enum: ["continue", "completed", "paused"] }),
@@ -300,7 +304,9 @@ Use this after a dynamic loop wake. Mark status as "continue" with updated state
         label: "LoopDelete",
         description: `Delete or pause a loop by its ID.
 
-Use "pause" to temporarily stop a loop without removing it. Use "delete" to permanently remove it.`,
+Use "pause" to temporarily stop a loop without removing it. Use "delete" to permanently remove it.
+
+Do not use this after a normal loop fire, an unchanged check, an empty iteration, or one step of a dynamic goal. Recurring loops remain active across iterations; dynamic loops use LoopUpdate. Delete only when the user explicitly asks to cancel the loop or its stated stop condition is satisfied.`,
         parameters: Type.Object({
             id: Type.String({ description: "Loop ID to delete or pause" }),
             action: Type.Optional(Type.String({ description: "delete or pause (default: delete)", enum: ["delete", "pause"], default: "delete" })),

package/dist/tools/monitor-tools.js

@@ -30,7 +30,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 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"`,
+Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits, fails, or times out. The completion wake lets the agent inspect the final status and buffered output.\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.",

package/docs/USAGE_GUIDE.md

@@ -0,0 +1,185 @@
+# pi-loop usage guide
+
+`pi-loop` re-wakes a pi agent from schedules and events, runs self-paced goal loops, and monitors background commands. This guide covers the operational details; see the [README](../README.md) for installation and a quick start.
+
+## Loops
+
+### Scheduled loops
+
+Use `/loop <interval> <prompt>` or `LoopCreate`:
+
+```text
+/loop 5m check the deploy
+LoopCreate trigger="0 9 * * 1-5" prompt="Review weekday alerts" maxFires=10
+```
+
+Intervals such as `5m`, `2h`, and `1d` are converted to cron expressions. Full five-field cron expressions are also accepted. Cron and hybrid loops track their next fire time and deliver only when the agent is idle.
+
+Use `maxFires` for polling or other bounded work so a loop cannot run indefinitely. Recurring loops expire after seven days.
+
+### Event loops
+
+Event loops react to pi events instead of polling:
+
+```text
+/loop event tasks:created process the backlog
+LoopCreate trigger="tool_execution_end" prompt="Review the completed tool call" triggerType="event" recurring=true
+```
+
+`LoopCreate` event loops are one-shot by default. Set `recurring=true` to keep listening. Prefer events when a relevant source exists; use hybrid triggers when an event needs a scheduled safety net.
+
+### Hybrid loops
+
+A hybrid trigger combines cron and event delivery with a debounce window:
+
+```text
+LoopCreate trigger="cron:5m event:tasks:created" prompt="Process pending tasks" triggerType="hybrid" debounceMs=30000
+```
+
+### Dynamic goal loops
+
+Free text passed to `/loop` creates a self-paced dynamic goal:
+
+```text
+/loop finish the release
+```
+
+The first wake is immediate when the agent is idle. After each iteration, the agent calls `LoopUpdate`:
+
+```text
+LoopUpdate id="1" status="continue" state="Tests pass; reviewing package"
+LoopUpdate id="1" status="continue" nextInterval="3m"
+LoopUpdate id="1" status="paused" state="Waiting for credentials"
+LoopUpdate id="1" status="completed"
+```
+
+- `continue` saves progress and wakes again when idle.
+- `continue` with `nextInterval` schedules a timed wake.
+- `paused` preserves progress without firing.
+- `completed` finishes and deletes the loop.
+
+Paused dynamic loops can be resumed from the `/loop` menu. If an in-memory wake is lost during a restart or session switch, persisted dynamic state recovers it.
+
+### Inspecting and stopping loops
+
+```text
+LoopList
+LoopDelete id="1" action="pause"
+LoopDelete id="1" action="delete"
+```
+
+`LoopDelete` defaults to `action="delete"`.
+
+## Background monitors
+
+`MonitorCreate` runs a shell command without blocking the agent:
+
+```text
+MonitorCreate command="npm test" description="Run test suite" onDone="Inspect the result and fix failures"
+```
+
+Output is buffered and emitted as `monitor:output`. A monitor finishes as one of:
+
+- clean exit: emits `monitor:done`
+- nonzero exit or spawn failure: emits `monitor:error`
+- timeout: stops the process, emits `monitor:error`, and reports the timeout
+- explicit `MonitorStop`: cancels the monitor without an `onDone` wake
+
+Pass `onDone` whenever the agent should resume work after completion. Its one-shot wake fires on success, failure, or timeout. The default timeout is five minutes; use `timeout=0` to disable it.
+
+```text
+MonitorList
+MonitorStop monitorId="1"
+```
+
+`MonitorList` includes status, exit code when available, output count, and the last five buffered lines. Finished monitors remain briefly available before pruning.
+
+## Task integration
+
+### With pi-tasks
+
+When [@tintinweb/pi-tasks](https://github.com/tintinweb/pi-tasks) is available, `pi-loop` uses it over the task RPC channels. Set `autoTask=true` on `LoopCreate` to create a tracked task for each fire.
+
+### Native fallback
+
+If `pi-tasks` does not answer during startup detection, `pi-loop` registers:
+
+```text
+TaskCreate subject="Fix deploy polling" description="Replace polling with an event-driven loop"
+TaskList
+TaskUpdate id="1" status="in_progress"
+TaskUpdate id="1" status="completed"
+TaskDelete id="1"
+```
+
+The native provider is selected for the session and exposes `/tasks`, compact status-line tracking, persisted task state, lifecycle events, and task RPC replies.
+
+Set `taskBacklog=true` on a loop that processes existing pending tasks. Backlog workers bootstrap when tasks already exist and delete themselves when the queue drains. `autoTask` serves a different purpose: it creates a new task on each loop fire.
+
+## Events
+
+Monitor events:
+
+- `monitor:output`
+- `monitor:done`
+- `monitor:error`
+
+Native task lifecycle events:
+
+- `tasks:created`
+- `tasks:started`
+- `tasks:completed`
+- `tasks:reopened`
+- `tasks:updated`
+- `tasks:deleted`
+- `tasks:backlog_empty`
+- `loops:autodeleted`
+
+Task event payloads include `previousStatus`. Transition events report the status before the transition; details-only `tasks:updated` events report the status current at edit time.
+
+## Cross-extension task RPC
+
+External consumers should import only from `@trevonistrevon/pi-loop/api`; deep `src/` imports are blocked by the package export map.
+
+```ts
+import { TASKS_RPC, rpcCall } from "@trevonistrevon/pi-loop/api";
+
+const { id, task } = await rpcCall(pi.events, TASKS_RPC.create, {
+  subject: "Fix deploy polling",
+  description: "Replace polling with an event-driven loop",
+});
+```
+
+`rpcCall` rejects on failure or timeout. The native provider supports:
+
+| Channel | Request | Reply |
+|---|---|---|
+| `tasks:rpc:ping` | `{}` | `{ version, provider }` |
+| `tasks:rpc:pending` | `{}` | `{ pending }` |
+| `tasks:rpc:create` | `{ subject, description, metadata? }` | `{ id, task }` |
+| `tasks:rpc:clean` | `{}` | `{ pruned }` |
+| `tasks:rpc:update` | `{ id, status?, subject?, description? }` | `{ task }` |
+
+Requests include `requestId`; replies arrive on `<channel>:reply:<requestId>` as `{ success: true, data }` or `{ success: false, error }`.
+
+## Persistence and configuration
+
+| Variable | Effect | Default |
+|---|---|---|
+| `PI_LOOP` | Store path override; use `off` to disable persistence | derived from scope |
+| `PI_LOOP_SCOPE` | `memory`, `session`, or `project` | `session` |
+| `PI_LOOP_DEBUG` | Debug logging to stderr | unset |
+
+Scope behavior:
+
+- `session`: persists loops and tasks per session ID while isolating concurrent sessions and worktrees
+- `memory`: keeps all state ephemeral
+- `project`: shares persisted automation across sessions in the repository
+
+Session files live under `.pi/loops/` and `.pi/tasks/`. Keep `session` as the normal default; use `project` only when shared automation is intentional.
+
+## Status line and limits
+
+The TUI status line summarizes active loops, monitors, and native tasks. Use `LoopList`, `MonitorList`, and `/tasks` for detail. The status clears when no work is active.
+
+The runtime allows at most 25 active loops and 25 running monitors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevonistrevon/pi-loop",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "A pi extension for cron/event-based agent re-wake loops and background process monitoring.",
   "author": "trevonistrevon",
   "license": "MIT",
@@ -20,6 +20,7 @@
   "files": [
     "src/",
     "dist/",
+    "docs/USAGE_GUIDE.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -30,8 +31,8 @@
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.75.5",
-    "@earendil-works/pi-tui": "^0.75.5"
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10"
   },
   "dependencies": {
     "typebox": "^1.1.34"

package/src/commands/loop-command.ts

@@ -33,6 +33,7 @@ export interface LoopCommandOptions {
   getStore: () => LoopStoreLike;
   getTriggerSystem: () => TriggerSystemLike;
   updateWidget: () => void;
+  onDynamicLoopActivated?: (entry: LoopEntry) => void;
 }
 
 type LoopCommandRoute =
@@ -74,7 +75,7 @@ function parseLoopCommandRoute(input: string): LoopCommandRoute {
 }
 
 export function registerLoopCommand(options: LoopCommandOptions): void {
-  const { pi, getStore, getTriggerSystem, updateWidget } = options;
+  const { pi, getStore, getTriggerSystem, updateWidget, onDynamicLoopActivated } = options;
 
   function createCronLoop(ui: ExtensionUIContext, interval: string, prompt: string, notifyEvery: boolean) {
     let entry: LoopEntry | undefined;
@@ -130,6 +131,7 @@ export function registerLoopCommand(options: LoopCommandOptions): void {
     getTriggerSystem().add(entry);
     updateWidget();
     ui.notify(`Dynamic loop #${entry.id} created — ${goal.slice(0, 50)}`, "info");
+    onDynamicLoopActivated?.(entry);
   }
 
   async function viewLoops(ui: ExtensionUIContext) {
@@ -178,6 +180,7 @@ export function registerLoopCommand(options: LoopCommandOptions): void {
           getTriggerSystem().add(resumed);
           updateWidget();
           ui.notify(`Loop #${entry.id} resumed`, "info");
+          if (resumed.trigger.type === "dynamic") onDynamicLoopActivated?.(resumed);
         }
       }
     }

package/src/index.ts

@@ -200,7 +200,9 @@ export default function (pi: ExtensionAPI) {
       timestamp: Date.now(),
       readOnly: entry.readOnly,
       recurring: false,
+      persistent: entry.recurring,
       autoTask: true,
+      taskBacklog: entry.taskBacklog,
     });
     return true;
   }
@@ -276,7 +278,9 @@ export default function (pi: ExtensionAPI) {
       timestamp: firedAt,
       readOnly: firedEntry.readOnly,
       recurring: firedEntry.recurring,
+      persistent: firedEntry.recurring,
       autoTask: firedEntry.autoTask,
+      taskBacklog: firedEntry.taskBacklog,
       dynamic: firedEntry.dynamic,
     });
   }
@@ -368,6 +372,9 @@ export default function (pi: ExtensionAPI) {
     updateWidget: () => {
       widget.update();
     },
+    onDynamicLoopActivated: (entry) => {
+      onLoopFire(entry);
+    },
   });
 
   // ── Native task tools (only when pi-tasks is absent) ──

package/src/monitor-manager.ts

@@ -211,7 +211,7 @@ export class MonitorManager {
     if (timeout > 0) {
       setTimeout(() => {
         if (bp.entry.status === "running") {
-          this.stop(id);
+          void this.stop(id, "timeout");
         }
       }, timeout);
     }
@@ -231,7 +231,7 @@ export class MonitorManager {
       .sort((a, b) => Number(a.id) - Number(b.id));
   }
 
-  async stop(id: string): Promise<boolean> {
+  async stop(id: string, reason: "manual" | "timeout" = "manual"): Promise<boolean> {
     const bp = this.processes.get(id);
     if (!bp || bp.entry.status !== "running") return false;
 
@@ -243,7 +243,7 @@ export class MonitorManager {
       entityId: id,
       payload: {
         id,
-        reason: "manual",
+        reason,
       },
     });
     this.schedulePrune(id);
@@ -261,6 +261,14 @@ export class MonitorManager {
       });
     });
 
+    if (reason === "timeout") {
+      this.pi.events.emit("monitor:error", {
+        monitorId: id,
+        error: `Timed out after ${bp.entry.timeout}ms`,
+        outputLines: bp.entry.outputLines,
+      });
+      for (const callback of bp.completionCallbacks) callback();
+    }
     bp.completionCallbacks = [];
     for (const resolve of bp.waiters) resolve();
     bp.waiters = [];

package/src/notification-reducer.ts

@@ -9,7 +9,9 @@ export interface ReducerNotification {
   timestamp: number;
   trigger: unknown;
   recurring?: boolean;
+  persistent?: boolean;
   autoTask?: boolean;
+  taskBacklog?: boolean;
   readOnly?: boolean;
   dynamic?: DynamicLoopState;
 }

package/src/runtime/notification-runtime.ts

@@ -21,7 +21,9 @@ export interface LoopFireEvent {
   timestamp: number;
   readOnly?: boolean;
   recurring?: boolean;
+  persistent?: boolean;
   autoTask?: boolean;
+  taskBacklog?: boolean;
   dynamic?: DynamicLoopState;
 }
 
@@ -115,14 +117,22 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
       if (dynamic?.metrics) lines.push(`Metrics: ${dynamic.metrics}`);
       if (dynamic?.doneCriteria) lines.push(`Done criteria: ${dynamic.doneCriteria}`);
       lines.push(
-        "Continue toward the goal. When done call LoopUpdate with status=\"completed\". If more work remains, call LoopUpdate with status=\"continue\" plus state/metrics. Omit nextInterval for idle-driven rewake; include nextInterval for a timed wake. If blocked, use status=\"paused\".",
+        `Loop lifecycle: Loop #${loopId} is the persistent controller for the overall goal. Do not call LoopDelete after this iteration.`,
+        "Before ending this turn, call LoopUpdate exactly once: use status=\"completed\" only when the overall goal and done criteria are satisfied; use status=\"continue\" when any work remains, with state/metrics and optional nextInterval; use status=\"paused\" only when genuinely blocked. Omit nextInterval for an idle-driven rewake.",
       );
       return lines.join("\n");
     }
 
+    const lifecycle = data.taskBacklog
+      ? `Backlog lifecycle: Loop #${loopId} is managed automatically. Do not call LoopDelete; when no pending tasks remain, report that and end this iteration.`
+      : (data.persistent ?? data.recurring)
+        ? `Loop lifecycle: Loop #${loopId} is recurring and remains active after this iteration. Do not call LoopDelete or pause it merely because this run finished, found no changes, or has no immediate work. Stop it only when the user or the loop prompt explicitly requires cancellation.`
+        : `Loop lifecycle: Loop #${loopId} is a one-shot wake and cleanup is automatic. Do not call LoopDelete.`;
+
     return [
       `[pi-loop] Loop #${loopId} fired (${triggerInfo}).${constraint}`,
       prompt,
+      lifecycle,
     ].join("\n");
   }
 
@@ -154,8 +164,10 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
         loopId: notification.loopId,
         trigger: notification.trigger,
         recurring: notification.recurring,
+        persistent: notification.persistent,
         readOnly: notification.readOnly,
         autoTask: notification.autoTask,
+        taskBacklog: notification.taskBacklog,
         dynamic: notification.dynamic,
         timestamp: notification.timestamp,
       },

package/src/runtime/session-runtime.ts

@@ -62,8 +62,11 @@ export function registerSessionRuntimeHooks(options: SessionRuntimeOptions): voi
     if (heartbeatTimer) return;
     heartbeatTimer = setInterval(() => {
       // Swallow pump failures so a transient error never surfaces as an
-      // unhandled rejection; the next tick retries.
-      void pumpLoops().catch(() => {});
+      // unhandled rejection; repaint still runs so cleared harness UI heals.
+      void pumpLoops()
+        .catch(() => {})
+        .then(() => widget.update())
+        .catch(() => {});
     }, HEARTBEAT_MS);
     heartbeatTimer.unref?.();
   }
@@ -92,7 +95,6 @@ export function registerSessionRuntimeHooks(options: SessionRuntimeOptions): voi
       getStore().expireEventLoops(sessionStartedAt);
       getTriggerSystem().start();
       ensureHeartbeat();
-      widget.update();
     }
   }
 
@@ -110,6 +112,16 @@ export function registerSessionRuntimeHooks(options: SessionRuntimeOptions): voi
     getScheduler().pump(Date.now(), (entry) => !pendingTasks.has(entry.id));
   }
 
+  pi.on("session_start", async (_event, ctx) => {
+    setLatestCtx(ctx);
+    setSessionId(ctx.sessionManager.getSessionId());
+    widget.setUICtx(ctx.ui);
+    upgradeStoreIfNeeded(ctx);
+    ensureHeartbeat();
+    showPersistedLoops();
+    widget.update();
+  });
+
   pi.on("turn_start", async (_event, ctx) => {
     setLatestCtx(ctx);
     setSessionId(ctx.sessionManager.getSessionId());

package/src/runtime/task-backlog-runtime.ts

@@ -17,7 +17,7 @@ import {
 } from "./loop-events.js";
 
 export const AUTO_TASK_WORKER_THRESHOLD = 5;
-export const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, complete it. If no pending tasks remain, call LoopDelete on your own loop ID.";
+export const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, and complete it. If no pending tasks remain, report that and end this iteration; pi-loop manages the worker lifecycle automatically.";
 
 export interface TaskBacklogRuntimeOptions {
   getLoops: () => LoopEntry[];

package/src/tools/loop-tools.ts

@@ -214,7 +214,11 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **autoTask**: when pi-tasks is loaded or native task fallback is active, auto-create a task on each fire
 - **taskBacklog**: mark this as a task-backlog worker loop so it auto-deletes when pending tasks reach zero
 - **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`,
+- **maxFires**: auto-stop after N fires — prevents infinite token burn on polling loops
+
+## Loop Lifecycle
+
+Recurring loops persist across fires. A completed iteration, unchanged result, or temporarily empty check is not a reason to delete the loop. Delete only when the user explicitly cancels it or its stated stop condition is satisfied. Dynamic loops must be advanced with LoopUpdate, not LoopDelete.`,
     promptGuidelines: [
       "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",
@@ -226,14 +230,14 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       "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.",
+      "Recurring loops are persistent controllers. Do not call LoopDelete after a normal fire, an unchanged check, or one completed iteration; only delete when the user explicitly asks to cancel or the loop's stated stop condition is satisfied.",
       "## readOnly mode",
       "Set readOnly: true for loops that only observe and report (checks, status polls). This prevents unintended changes.",
       "## Task-driven workflows",
       "Do not rely on a past 'tasks:created' event to replay. If tasks already exist, bootstrap the first pass in the current turn or use a hybrid/event loop that can catch future task creation and a cron safety-net.",
       "Use autoTask only when you want the loop itself to create a task on each fire. For processing an existing task backlog, leave autoTask off and have the loop run TaskList to pick the next pending task.",
       "Set taskBacklog: true for backlog worker loops that process the existing pending queue. Backlog worker loops bootstrap against existing pending tasks and auto-delete when the queue reaches zero.",
-      "When no tasks are pending, the loop should stop itself or skip the wake entirely — no tokens burned on empty polls.",
+      "For taskBacklog loops, do not instruct the agent to delete the loop; pi-loop auto-deletes it when the pending count reaches zero.",
       "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
     ],
     parameters: Type.Object({
@@ -312,7 +316,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
         (entry.taskBacklog ? "Backlog worker: enabled\n" : "") +
         (bootstrapped ? "Backlog: initial wake queued for existing pending tasks\n" : "") +
         (isTaskSystemReady() ? "" : "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)`
+        `ID: ${entry.id} (persists until explicitly canceled or a configured stop condition is met)`
       ));
     },
   });
@@ -354,7 +358,7 @@ Use this before creating new loops to avoid duplicates, or to find IDs for LoopD
     label: "LoopUpdate",
     description: `Update progress for a dynamic loop.
 
-Use this after a dynamic loop wake. Mark status as "continue" with updated state/metrics and optional nextInterval, "completed" when the goal is done, or "paused" to stop temporarily.`,
+Use this exactly once after each dynamic loop wake. Mark status as "continue" with updated state/metrics and optional nextInterval whenever any work remains, "completed" only when the overall goal and done criteria are satisfied, or "paused" when genuinely blocked. Do not use LoopDelete to finish an iteration.`,
     parameters: Type.Object({
       id: Type.String({ description: "Dynamic loop ID to update" }),
       status: Type.String({ description: "continue, completed, or paused", enum: ["continue", "completed", "paused"] }),
@@ -386,7 +390,9 @@ Use this after a dynamic loop wake. Mark status as "continue" with updated state
     label: "LoopDelete",
     description: `Delete or pause a loop by its ID.
 
-Use "pause" to temporarily stop a loop without removing it. Use "delete" to permanently remove it.`,
+Use "pause" to temporarily stop a loop without removing it. Use "delete" to permanently remove it.
+
+Do not use this after a normal loop fire, an unchanged check, an empty iteration, or one step of a dynamic goal. Recurring loops remain active across iterations; dynamic loops use LoopUpdate. Delete only when the user explicitly asks to cancel the loop or its stated stop condition is satisfied.`,
     parameters: Type.Object({
       id: Type.String({ description: "Loop ID to delete or pause" }),
       action: Type.Optional(Type.String({ description: "delete or pause (default: delete)", enum: ["delete", "pause"], default: "delete" })),

package/src/tools/monitor-tools.ts

@@ -57,7 +57,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 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"`,
+Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits, fails, or times out. The completion wake lets the agent inspect the final status and buffered output.\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.",