@trevonistrevon/pi-loop 0.3.1 → 0.4.1

package/DIFFERENTIAL_REVIEW_REPORT.md

@@ -0,0 +1,81 @@
+# Differential Review Report
+
+## Update — 2026-06-02
+
+### Resolved audit finding
+- **Resolved:** recurring `event` / `hybrid` loops now clean themselves up immediately when `maxFires` is reached on the final allowed fire.
+- **Implementation:** `src/trigger-system.ts` now removes and deletes recurring event/hybrid loops as soon as `fireCount >= maxFires` after `onFire(...)` completes.
+- **Why this mattered:** the previous behavior left one stale active loop behind until the next matching event arrived, which was a real runtime cleanup bug.
+
+### Regression coverage added
+- `test/trigger-system.test.ts`
+  - recurring `event` loop is deleted immediately at final `maxFires`
+  - recurring `hybrid` loop is deleted immediately at final `maxFires`
+  - hybrid cleanup also clears scheduled cron state
+- `test/index.test.ts`
+  - extension-level `LoopCreate`/`LoopList` path confirms the loop is gone immediately after the final allowed event fire
+
+### Validation status
+- `npm run lint` ✅
+- `npm run typecheck` ✅
+- `npm run test` ✅
+- `npm run build` ✅
+- Current suite: **112 passing tests**
+
+## Scope
+Reviewed recent uncommitted changes in:
+- `src/index.ts`
+- `src/ui/widget.ts`
+- `test/index.test.ts`
+- `test/widget.test.ts`
+- `README.md`
+
+## Risk Summary
+- **Overall risk:** Medium
+- **Primary areas affected:** runtime task fallback routing, UI/widget behavior, interactive command registration
+- **Security impact:** Low direct security impact; main risks are state-management regressions and missing coverage around command behavior
+
+## Findings
+
+### 🟡 Warning
+`src/index.ts` - Native task fallback is covered for registration and file persistence, but not for interactive `/tasks` flows or loop-driven task lifecycle integration.
+
+**Why it matters:**
+The new `/tasks` command and interactive actions (`Start`, `Complete`, `Reopen`, `Delete`) are stateful and user-facing. Regressions here would not be caught by current tests. Similarly, native fallback behavior for `autoTask`, `hasPendingTasks()`, and `cleanDoneTasks()` is only indirectly covered.
+
+**Recommended follow-up:**
+Add tests for:
+- `/tasks` command registration and quick-create path
+- native `autoTask` creation path
+- `hasPendingTasks()` using native fallback
+- completed-task sweep behavior for native tasks
+
+### 🟢 Suggestion
+`src/ui/widget.ts` - Compact widget behavior is appropriately simplified and focus-oriented.
+
+**Good pattern:**
+The single-line status approach reduces noise and matches the intended UX. Showing only active/next task focus text is a good constraint.
+
+## Test Coverage Review
+
+### Covered well
+- Native tool registration when `pi-tasks` is absent/present
+- Native task persistence path (`.pi/tasks/tasks.json`)
+- Compact widget states:
+  - `none`
+  - monitor-only count
+  - loop + monitor count
+  - active task focus text
+  - next task focus text
+  - retained widget rendering after content clears
+
+### Coverage gaps
+- No tests for `/tasks` command behavior beyond registration
+- No direct tests for native `TaskUpdate` → widget focus transitions
+- No direct tests for native `cleanDoneTasks()` sweep behavior
+- No end-to-end tests for `LoopCreate(autoTask: true)` using native fallback
+
+## Review Verdict
+- **No merge-blocking issues found**
+- Safe to release after version bump and validation
+- Recommended follow-up: add native task lifecycle command/integration tests in a later pass

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
 <h1 align="center">@trevonistrevon/pi-loop</h1>
-<h6 align="center">Cron and event loops for the pi coding agent. Background monitors, scheduled re-wakes, pi-tasks integration.</h6>
+<h6 align="center">Cron and event loops for the pi coding agent. Background monitors, scheduled re-wakes, pi-tasks integration, and native task fallback.</h6>
 </p>
 
 ## Install
@@ -11,29 +11,45 @@ pi install @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"
 ```
 
-```
+```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"
 ```
 
+When `pi-tasks` is not installed, `pi-loop` also exposes native task tools after startup detection:
+
+```text
+TaskCreate subject="Fix deploy polling" description="Switch deploy check to event-driven loop"
+TaskList
+TaskUpdate id="1" status="in_progress"
+TaskDelete id="1"
+```
+
 ## Commands
 
 `/loop [interval] [prompt]` — interactive loop creation.
 
-```
+```text
 /loop                         # menu
 /loop 5m check the deploy     # 5-minute cron loop
 ```
 
+`/tasks` — interactive native task viewer/manager, only registered when `pi-tasks` is absent.
+
+```text
+/tasks                        # open native task viewer
+/tasks Write README updates   # quick-create native task
+```
+
 ## Tools
 
 | Tool | What it does |
@@ -44,16 +60,44 @@ MonitorStop monitorId="1"
 | `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), or `hybrid` (both, debounced).
 
-## pi-tasks
+## 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:
+
+- persistent store at `.pi/tasks/tasks.json`
+- `TaskCreate`, `TaskList`, `TaskUpdate`, `TaskDelete`
+- `/tasks` interactive viewer
+- compact widget task tracking
+
+This fallback is session-sticky: `pi-loop` decides once at startup whether `pi-tasks` or native tasks own task management for that session.
+
 ## Widget
 
-Active loops and monitors show in a persistent TUI widget above the editor.
+`pi-loop` keeps a compact persistent TUI widget above the editor.
+
+It now shows a single focus-friendly status line such as:
+
+```text
+none
+1 loop · 1 monitor
+2 tasks | active: Fix deploy polling
+1 loop · 2 monitors · 3 tasks | next: Update README
+```
+
+Only task counts and the single active/next task are shown in the widget so attention stays on what is currently happening. Use `LoopList`, `MonitorList`, and `/tasks` for detail.
 
 ## Configuration