@trevonistrevon/pi-loop 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [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

@@ -331,6 +331,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/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.2",
   "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

@@ -368,6 +368,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/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.",