@trevonistrevon/pi-loop 0.6.0 → 0.6.2

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

@@ -8,7 +8,7 @@ import {
   type TaskBacklogEvent,
 } from "../task-backlog-coordinator.js";
 import type { TaskStore } from "../task-store.js";
-import type { LoopEntry, Trigger } from "../types.js";
+import type { LoopDeletionTombstoneInput, LoopEntry, Trigger } from "../types.js";
 import {
   buildLoopAutodeletedPayload,
   buildTaskBacklogEmptyPayload,
@@ -27,6 +27,7 @@ export interface TaskBacklogRuntimeOptions {
     maxFires?: number;
   }) => LoopEntry;
   deleteLoop: (id: string) => void;
+  recordDeletionTombstone?: (id: string, tombstone: LoopDeletionTombstoneInput) => void;
   addTrigger: (entry: LoopEntry) => void;
   removeTrigger: (id: string) => void;
   updateWidget: () => void;
@@ -52,6 +53,7 @@ export function createTaskBacklogRuntime(options: TaskBacklogRuntimeOptions): Ta
     getLoops,
     createLoop,
     deleteLoop,
+    recordDeletionTombstone,
     addTrigger,
     removeTrigger,
     updateWidget,
@@ -79,6 +81,14 @@ export function createTaskBacklogRuntime(options: TaskBacklogRuntimeOptions): Ta
     return getLoops().find(isAutoTaskWorkerLoop);
   }
 
+  function deleteTaskBacklogLoop(entry: LoopEntry, pendingCount: number): void {
+    debug?.(`task backlog loop #${entry.id} — no pending tasks remain, deleting`);
+    removeTrigger(entry.id);
+    recordDeletionTombstone?.(entry.id, { reason: "task_backlog_empty", pendingCount });
+    deleteLoop(entry.id);
+    emitLoopAutodeleted?.(buildLoopAutodeletedPayload(entry, pendingCount));
+  }
+
   async function cleanupTaskBacklogLoops(): Promise<number> {
     const backlogLoops = getLoops().filter(isTaskBacklogLoop);
     if (backlogLoops.length === 0) return 0;
@@ -86,15 +96,9 @@ export function createTaskBacklogRuntime(options: TaskBacklogRuntimeOptions): Ta
     const pending = await hasPendingTasks();
     if (pending < 0 || pending > 0) return 0;
 
-    emitTaskBacklogEmpty?.(
-      buildTaskBacklogEmptyPayload(backlogLoops.map((entry) => entry.id)),
-    );
-    for (const entry of backlogLoops) {
-      debug?.(`task backlog loop #${entry.id} — no pending tasks remain, deleting`);
-      removeTrigger(entry.id);
-      deleteLoop(entry.id);
-      emitLoopAutodeleted?.(buildLoopAutodeletedPayload(entry, pending));
-    }
+    const deletedLoopIds = backlogLoops.map((entry) => entry.id);
+    emitTaskBacklogEmpty?.(buildTaskBacklogEmptyPayload(deletedLoopIds));
+    for (const entry of backlogLoops) deleteTaskBacklogLoop(entry, pending);
     updateWidget();
     return backlogLoops.length;
   }
@@ -107,7 +111,7 @@ export function createTaskBacklogRuntime(options: TaskBacklogRuntimeOptions): Ta
 
     const trigger: Trigger = {
       type: "hybrid",
-      cron: "*/5 * * * *",
+      cron: "*/3 * * * *",
       event: { source: "tasks:created" },
       debounceMs: 30000,
     };

package/src/scheduler.ts

@@ -8,6 +8,9 @@ function computeNextFire(entry: LoopEntry): Date {
   if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid") {
     return cronToNextFire(entry.trigger.type === "hybrid" ? entry.trigger.cron : entry.trigger.schedule);
   }
+  if (entry.trigger.type === "dynamic") {
+    return new Date(entry.dynamic?.nextWakeAt ?? Date.now());
+  }
   return new Date(Date.now() + 60000);
 }
 
@@ -20,9 +23,19 @@ export class CronScheduler {
   ) {}
 
   start(): void {
-    for (const entry of this.store.list()) {
+    for (const storedEntry of this.store.list()) {
+      let entry = storedEntry;
       if (entry.status !== "active") continue;
-      if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid") {
+      if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid" || entry.trigger.type === "dynamic") {
+        if (entry.trigger.type === "dynamic" && entry.dynamic?.awaitingUpdate && !this.fireTimes.has(entry.id)) {
+          entry = this.store.updateDynamic(entry.id, {
+            dynamic: {
+              awaitingUpdate: false,
+              nextWakeAt: undefined,
+              lastUpdatedAt: Date.now(),
+            },
+          }) ?? entry;
+        }
         this.armTimer(entry);
       }
     }
@@ -33,7 +46,7 @@ export class CronScheduler {
   }
 
   add(entry: LoopEntry): void {
-    if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid") {
+    if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid" || entry.trigger.type === "dynamic") {
       this.armTimer(entry);
     }
   }
@@ -47,12 +60,14 @@ export class CronScheduler {
   }
 
   private armTimer(entry: LoopEntry): void {
-    const _scheduleExpr = entry.trigger.type === "hybrid" ? entry.trigger.cron : (entry.trigger as { schedule: string }).schedule;
-
     const nextFire = computeNextFire(entry);
-    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);
+    let jitter = 0;
+    if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid") {
+      const scheduleExpr = entry.trigger.type === "hybrid" ? entry.trigger.cron : entry.trigger.schedule;
+      const minuteField = scheduleExpr.trim().split(/\s+/)[0] ?? "";
+      const minuteStep = minuteField.startsWith("*/") ? parseInt(minuteField.slice(2), 10) || 30 : 30;
+      jitter = computeJitter(entry.id, entry.recurring, minuteStep);
+    }
     const fireTime = nextFire.getTime() + jitter;
 
     if (fireTime > entry.expiresAt) {
@@ -73,6 +88,8 @@ export class CronScheduler {
         continue;
       }
 
+      if (entry.trigger.type === "dynamic" && entry.dynamic?.awaitingUpdate) continue;
+
       if (filter && !filter(entry)) continue;
 
       if (now >= entry.expiresAt) {

package/src/store.ts

@@ -2,12 +2,15 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { type LoopReducerEvent, type LoopReducerState, reduceLoopState } from "./loop-reducer.js";
 import { ReducerBackedStore } from "./reducer-backed-store.js";
-import type { LoopEntry, LoopStoreData, Trigger } from "./types.js";
+import type { DynamicLoopState, LoopDeletionTombstone, LoopDeletionTombstoneInput, LoopEntry, LoopStoreData, Trigger } from "./types.js";
 
 const LOOPS_DIR = join(homedir(), ".pi", "loops");
 const MAX_LOOPS = 25;
+const TOMBSTONE_TTL_MS = 10 * 60 * 1000;
 
 export class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, LoopReducerEvent, LoopStoreData> {
+  private tombstones = new Map<string, LoopDeletionTombstone>();
+
   constructor(listIdOrPath?: string) {
     super(
       {
@@ -22,7 +25,7 @@ export class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, L
     );
   }
 
-  create(trigger: Trigger, prompt: string, opts: { recurring: boolean; autoTask?: boolean; taskBacklog?: boolean; readOnly?: boolean; maxFires?: number }): LoopEntry {
+  create(trigger: Trigger, prompt: string, opts: { recurring: boolean; autoTask?: boolean; taskBacklog?: boolean; readOnly?: boolean; maxFires?: number; dynamic?: Partial<DynamicLoopState> }): LoopEntry {
     return this.withLock(() => {
       if (this.entries.size >= MAX_LOOPS) {
         throw new Error(`Maximum of ${MAX_LOOPS} loops reached. Delete some before creating new ones.`);
@@ -41,6 +44,7 @@ export class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, L
           taskBacklog: opts.taskBacklog,
           readOnly: opts.readOnly,
           maxFires: opts.maxFires,
+          dynamic: opts.dynamic,
         },
       });
       return this.entries.get(String(this.nextId - 1))!;
@@ -75,6 +79,22 @@ export class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, L
         entityId: id,
         payload: { id },
       });
+      if (entry.trigger.type === "dynamic" && entry.dynamic?.awaitingUpdate) {
+        this.applyReducerEvent({
+          type: "LOOP_DYNAMIC_UPDATED",
+          at: Date.now(),
+          source: "tool",
+          entityType: "loop",
+          entityId: id,
+          payload: {
+            id,
+            dynamic: {
+              awaitingUpdate: false,
+              lastUpdatedAt: Date.now(),
+            },
+          },
+        });
+      }
       return this.entries.get(id);
     });
   }
@@ -119,6 +139,43 @@ export class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, L
     });
   }
 
+  updateDynamic(id: string, fields: { prompt?: string; dynamic: Partial<DynamicLoopState> }): LoopEntry | undefined {
+    return this.withLock(() => {
+      if (!this.entries.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "LOOP_DYNAMIC_UPDATED",
+        at: Date.now(),
+        source: "tool",
+        entityType: "loop",
+        entityId: id,
+        payload: { id, prompt: fields.prompt, dynamic: fields.dynamic },
+      });
+      return this.entries.get(id);
+    });
+  }
+
+  getDeletionTombstone(id: string): LoopDeletionTombstone | undefined {
+    const tombstone = this.tombstones.get(id);
+    if (!tombstone) return undefined;
+    if (Date.now() - tombstone.deletedAt <= TOMBSTONE_TTL_MS) return tombstone;
+    this.tombstones.delete(id);
+    return undefined;
+  }
+
+  recordDeletionTombstone(id: string, input: LoopDeletionTombstoneInput): LoopDeletionTombstone | undefined {
+    const entry = this.entries.get(id);
+    if (!entry) return undefined;
+    const tombstone: LoopDeletionTombstone = {
+      id,
+      reason: input.reason,
+      pendingCount: input.pendingCount,
+      deletedAt: Date.now(),
+      prompt: entry.prompt,
+    };
+    this.tombstones.set(id, tombstone);
+    return tombstone;
+  }
+
   delete(id: string): boolean {
     return this.withLock(() => {
       if (!this.entries.has(id)) return false;

package/src/tools/loop-tools.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { formatTrigger } from "../loop-format.js";
 import { parseInterval } from "../loop-parse.js";
 import type { LoopEntry, Trigger } from "../types.js";
 import { textResult } from "./tool-result.js";
@@ -15,6 +16,8 @@ interface LoopStoreLike {
     maxFires?: number;
   }): LoopEntry;
   pause(id: string): LoopEntry | undefined;
+  updateDynamic(id: string, fields: { prompt?: string; dynamic: Partial<NonNullable<LoopEntry["dynamic"]>> }): LoopEntry | undefined;
+  getDeletionTombstone(id: string): { reason: string; pendingCount?: number } | undefined;
   delete(id: string): boolean;
 }
 
@@ -82,6 +85,89 @@ function formatRemaining(ms: number): string {
   return `${Math.round(ms / 3600000)}h`;
 }
 
+function parseDelayMs(input: string): number | undefined {
+  const match = input.trim().match(/^(\d+)\s*(s|m|h|d)$/i);
+  if (!match) return undefined;
+  const value = Number.parseInt(match[1] ?? "", 10);
+  const unit = (match[2] ?? "").toLowerCase();
+  const multiplier = unit === "s" ? 1000 : unit === "m" ? 60000 : unit === "h" ? 3600000 : 86400000;
+  return value * multiplier;
+}
+
+interface LoopUpdateParams {
+  id: string;
+  status: "continue" | "completed" | "paused";
+  state?: string;
+  metrics?: string;
+  doneCriteria?: string;
+  nextInterval?: string;
+  prompt?: string;
+}
+
+function resolveNextWakeAt(nextInterval?: string): { nextWakeAt?: number; error?: string } {
+  if (!nextInterval) return { nextWakeAt: undefined };
+  const parsedDelayMs = parseDelayMs(nextInterval);
+  if (!parsedDelayMs) return { error: `Invalid nextInterval "${nextInterval}". Use formats like 3m, 30s, or 1h.` };
+  return { nextWakeAt: Date.now() + parsedDelayMs };
+}
+
+function formatDynamicUpdateResult(id: string, iteration: number | undefined, nextWakeAt: number | undefined): string {
+  const mode = nextWakeAt === undefined
+    ? "Next wake: when idle"
+    : `Next wake: ${formatRemaining(Math.max(0, nextWakeAt - Date.now()))}`;
+  return `Dynamic loop #${id} updated\n` +
+    `Iteration: ${iteration ?? "?"}` +
+    `\n${mode}`;
+}
+
+function formatDeletionTombstone(id: string, tombstone: { reason: string; pendingCount?: number }): string {
+  const detail = tombstone.pendingCount === undefined ? "" : ` (pending: ${tombstone.pendingCount})`;
+  return `Loop #${id} already auto-deleted: ${tombstone.reason}${detail}`;
+}
+
+function continueDynamicLoop(
+  params: LoopUpdateParams,
+  entry: LoopEntry & { dynamic: NonNullable<LoopEntry["dynamic"]> },
+  store: LoopStoreLike,
+  triggerSystem: TriggerSystemLike,
+): string {
+  const { nextWakeAt, error } = resolveNextWakeAt(params.nextInterval);
+  if (error) return error;
+
+  const updated = store.updateDynamic(params.id, {
+    prompt: params.prompt,
+    dynamic: {
+      goal: params.prompt ?? entry.dynamic.goal,
+      state: params.state,
+      metrics: params.metrics,
+      doneCriteria: params.doneCriteria,
+      iteration: (entry.dynamic.iteration ?? 0) + 1,
+      nextWakeAt,
+      awaitingUpdate: false,
+      lastUpdatedAt: Date.now(),
+    },
+  });
+  if (updated) {
+    triggerSystem.remove(params.id);
+    triggerSystem.add(updated);
+  }
+  return formatDynamicUpdateResult(params.id, updated?.dynamic?.iteration, nextWakeAt);
+}
+
+function stopDynamicLoop(
+  params: LoopUpdateParams,
+  store: LoopStoreLike,
+  triggerSystem: TriggerSystemLike,
+): string {
+  triggerSystem.remove(params.id);
+  if (params.status === "completed") {
+    store.delete(params.id);
+    return `Dynamic loop #${params.id} completed and deleted`;
+  }
+  store.pause(params.id);
+  return `Dynamic loop #${params.id} paused`;
+}
+
 export function registerLoopTools(options: LoopToolsOptions): void {
   const {
     pi,
@@ -216,11 +302,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       const bootstrapped = await maybeBootstrapTaskLoop(entry);
       updateWidget();
 
-      const triggerDesc = trigger.type === "cron"
-        ? `schedule: ${trigger.schedule}`
-        : trigger.type === "event"
-          ? `event: ${trigger.source}`
-          : `hybrid: cron ${trigger.cron} + event ${trigger.event.source}`;
+      const triggerDesc = formatTrigger(trigger, "create");
 
       return Promise.resolve(textResult(
         `Loop #${entry.id} created: ${entry.prompt.slice(0, 60)}\n` +
@@ -248,13 +330,9 @@ Use this before creating new loops to avoid duplicates, or to find IDs for LoopD
 
       const lines: string[] = [];
       for (const entry of loops) {
-        const triggerDesc = entry.trigger.type === "cron"
-          ? `cron: ${entry.trigger.schedule}`
-          : entry.trigger.type === "event"
-            ? `event: ${entry.trigger.source}`
-            : `hybrid: ${entry.trigger.cron} + ${entry.trigger.event.source}`;
+        const triggerDesc = formatTrigger(entry.trigger, "list");
 
-        const nextFire = entry.trigger.type !== "event" ? getScheduler().nextFire(entry.id) : undefined;
+        const nextFire = entry.trigger.type === "cron" || entry.trigger.type === "hybrid" || entry.dynamic?.nextWakeAt !== undefined ? getScheduler().nextFire(entry.id) : undefined;
         const statusIcon = entry.status === "active" ? "*" : entry.status === "paused" ? "-" : "x";
         let line = `${statusIcon} #${entry.id} [${entry.status}] ${entry.prompt.slice(0, 60)}`;
         line += ` (${triggerDesc})`;
@@ -271,6 +349,38 @@ Use this before creating new loops to avoid duplicates, or to find IDs for LoopD
     },
   });
 
+  pi.registerTool({
+    name: "LoopUpdate",
+    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.`,
+    parameters: Type.Object({
+      id: Type.String({ description: "Dynamic loop ID to update" }),
+      status: Type.String({ description: "continue, completed, or paused", enum: ["continue", "completed", "paused"] }),
+      state: Type.Optional(Type.String({ description: "Current progress/state summary" })),
+      metrics: Type.Optional(Type.String({ description: "Current metrics/check results" })),
+      doneCriteria: Type.Optional(Type.String({ description: "Definition of done for the dynamic loop" })),
+      nextInterval: Type.Optional(Type.String({ description: "When to wake next, e.g. 3m, 30s, 1h" })),
+      prompt: Type.Optional(Type.String({ description: "Optional updated goal/prompt text" })),
+    }),
+    execute(_toolCallId, params: LoopUpdateParams) {
+      const store = getStore();
+      const triggerSystem = getTriggerSystem();
+      const entry = store.get(params.id);
+      if (!entry) return Promise.resolve(textResult(`Loop #${params.id} not found`));
+      if (entry.trigger.type !== "dynamic" || !entry.dynamic) {
+        return Promise.resolve(textResult(`Loop #${params.id} is not a dynamic loop`));
+      }
+
+      const message = params.status === "continue"
+        ? continueDynamicLoop(params, entry as LoopEntry & { dynamic: NonNullable<LoopEntry["dynamic"]> }, store, triggerSystem)
+        : stopDynamicLoop(params, store, triggerSystem);
+      updateWidget();
+      return Promise.resolve(textResult(message));
+    },
+  });
+
   pi.registerTool({
     name: "LoopDelete",
     label: "LoopDelete",
@@ -286,7 +396,11 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
 
       if (action === "pause") {
         const entry = getStore().pause(id);
-        if (!entry) return Promise.resolve(textResult(`Loop #${id} not found`));
+        if (!entry) {
+          const tombstone = getStore().getDeletionTombstone(id);
+          if (tombstone) return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone)));
+          return Promise.resolve(textResult(`Loop #${id} not found`));
+        }
         getTriggerSystem().remove(id);
         updateWidget();
         return Promise.resolve(textResult(`Loop #${id} paused`));
@@ -296,6 +410,8 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
       const deleted = getStore().delete(id);
       updateWidget();
       if (deleted) return Promise.resolve(textResult(`Loop #${id} deleted`));
+      const tombstone = getStore().getDeletionTombstone(id);
+      if (tombstone) return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone)));
       return Promise.resolve(textResult(`Loop #${id} not found`));
     },
   });

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.",

package/src/trigger-system.ts

@@ -31,7 +31,7 @@ export class TriggerSystem {
   }
 
   add(entry: LoopEntry): void {
-    if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid") {
+    if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid" || entry.trigger.type === "dynamic") {
       this.scheduler.add(entry);
     }
     if (entry.trigger.type === "event" || entry.trigger.type === "hybrid") {

package/src/types.ts

@@ -1,3 +1,15 @@
+export type LoopDeletionReason = "task_backlog_empty";
+
+export interface LoopDeletionTombstone {
+  id: string;
+  reason: LoopDeletionReason;
+  deletedAt: number;
+  prompt: string;
+  pendingCount?: number;
+}
+
+export type LoopDeletionTombstoneInput = Omit<LoopDeletionTombstone, "id" | "deletedAt" | "prompt">;
+
 export type LoopStatus = "active" | "paused";
 
 export interface CronTrigger {
@@ -18,7 +30,22 @@ export interface HybridTrigger {
   debounceMs: number;
 }
 
-export type Trigger = CronTrigger | EventTrigger | HybridTrigger;
+export interface DynamicTrigger {
+  type: "dynamic";
+}
+
+export type Trigger = CronTrigger | EventTrigger | HybridTrigger | DynamicTrigger;
+
+export interface DynamicLoopState {
+  goal: string;
+  state?: string;
+  metrics?: string;
+  doneCriteria?: string;
+  iteration: number;
+  nextWakeAt?: number;
+  awaitingUpdate?: boolean;
+  lastUpdatedAt?: number;
+}
 
 export interface LoopEntry {
   id: string;
@@ -34,6 +61,7 @@ export interface LoopEntry {
   readOnly?: boolean;
   maxFires?: number;
   fireCount?: number;
+  dynamic?: DynamicLoopState;
 }
 
 export interface LoopStoreData {

package/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.6.0"
-}

package/AGENTS.md

@@ -1,123 +0,0 @@
-# pi-loop Development Guidelines
-
-## Overview
-`pi-loop` is a pi extension providing cron/event-based agent re-wake loops and background process monitoring. Modeled after Claude Code's `/loop`, `CronCreate`, and `MonitorCreate` tools.
-
-## Stack
-- TypeScript 6.x (strict, ES2022 target, bundler module resolution)
-- `typebox` for tool parameter validation
-- `vitest` for tests
-- `biome` for linting (linter: on, formatter: off)
-- npm packaging as `@trevonistrevon/pi-loop`
-
-## Architecture
-```
-src/
-├── index.ts                          # Extension entry: tool/command registration, session wiring, native task fallback timer
-├── api.ts                            # Public subpath (@trevonistrevon/pi-loop/api): RPC channels/DTOs, TaskStore, scope resolvers
-├── types.ts                          # LoopKind, Trigger spec, LoopEntry, MonitorEntry, LoopConfig
-├── task-types.ts                     # TaskEntry, TaskStatus, TaskStoreData
-├── store.ts                          # File-backed CRUD (.pi/loops/loops.json) with file locking
-├── task-store.ts                     # File-backed CRUD for native fallback tasks (.pi/tasks/tasks.json)
-├── reducer-backed-store.ts           # Shared atomic-write + pid-lock persistence layer for reducer-driven stores
-├── coordinator.ts                    # ReducerSource/ReducerEvent/ReducerEffect plumbing shared by *-reducer/*-coordinator modules
-├── loop-reducer.ts                   # Pure loop state transitions, incl. maxFires/expiry checks
-├── monitor-reducer.ts                # Pure monitor state transitions
-├── notification-reducer.ts           # Pure pending-notification state transitions
-├── task-reducer.ts                   # Pure native task state transitions
-├── monitor-completion-coordinator.ts # Reduces monitor "onDone" completion into a fire effect
-├── task-backlog-coordinator.ts       # Reduces pending-task counts into auto-create/auto-clean effects
-├── scheduler.ts                      # Timer-based cron scheduler with jitter + 7-day expiry
-├── trigger-system.ts                 # Unified trigger engine: cron timers + pi event subscriptions + hybrid
-├── monitor-manager.ts                # ChildProcess tracking, output buffering, event emission, stop
-├── loop-parse.ts                     # Human interval → cron expression, next-fire computation, jitter
-├── rpc/                               # VENDORED — canonical copy shared verbatim with pi-orca; see "Cross-extension RPC" below
-│   ├── channels.ts                   # TASKS_RPC/SUBAGENTS_RPC/TASK_EVENTS channel constants + wire DTOs
-│   └── cross-extension-rpc.ts        # rpcCall (client), rpcProbe (detection), handleRpc (server), PROTOCOL_VERSION, RpcError
-├── runtime/                          # Extension-init-time wiring, one module per concern
-│   ├── loop-events.ts                # Auto-delete payload types for backlog-drained loops
-│   ├── monitor-ondone-runtime.ts     # Coordinator wiring for MonitorCreate's onDone → loop fire
-│   ├── native-task-rpc.ts            # tasks:rpc:* server: ping/pending/create/clean/update over the native TaskStore
-│   ├── notification-runtime.ts       # Pending-notification buffering + idle-driven delivery
-│   ├── scope.ts                      # PI_LOOP_SCOPE → loop/task store path resolution
-│   ├── session-runtime.ts            # Session-switch hooks, store (re)binding
-│   ├── task-backlog-runtime.ts       # Auto-create/auto-clean backlog worker evaluation
-│   ├── task-events.ts                # emitNativeTaskEvent: tasks:created/started/completed/reopened/updated/deleted
-│   ├── task-mutations.ts             # Shared mutation service: mutate → emit event → widget → backlog, used by RPC server and tools
-│   └── task-rpc.ts                   # Client bridge: probes pi-tasks, falls back to native TaskStore for autoTask/pending/clean
-├── tools/                            # Tool implementations
-│   ├── loop-tools.ts                 # LoopCreate/LoopList/LoopDelete
-│   ├── monitor-tools.ts              # MonitorCreate/MonitorList/MonitorStop
-│   ├── native-task-tools.ts          # TaskCreate/TaskList/TaskUpdate/TaskDelete (fallback only)
-│   └── tool-result.ts                # textResult() helper
-├── commands/
-│   ├── loop-command.ts               # /loop interactive loop creation
-│   └── tasks-command.ts              # /tasks native task viewer/manager
-└── ui/
-    └── widget.ts                     # Persistent widget: active loops + monitors + task summary
-```
-
-## Cross-extension RPC
-`src/rpc/` is a **vendored** module: the canonical copy is maintained here and copied verbatim into the sibling `pi-orca` repo. If you edit `channels.ts` or `cross-extension-rpc.ts`, copy the change to `pi-orca` and bump the `VENDOR_REV` comment at the top of both files in both repos — the two copies must never drift.
-
-The wire contract is request/reply over `pi.events`: a caller emits `{ requestId, ...params }` on a channel (e.g. `tasks:rpc:create`), the server replies on `<channel>:reply:<requestId>` with an envelope, `{success:true,data}` or `{success:false,error}`. `rpcCall` resolves/rejects that promise, `rpcProbe` swallows the rejection into `undefined` for presence detection, `handleRpc` is the server-side helper that turns a handler function into a channel subscription with automatic envelope wrapping. `PROTOCOL_VERSION` (currently `2`) is returned in ping replies so callers can gate on server capability.
-
-`pi-loop`'s native tasks RPC server (`src/runtime/native-task-rpc.ts`) registers at extension init — not behind the native-tool-registration fallback timer — so early cross-extension calls never race it. It stands down (silent no-op via `isEnabled`) once an external `pi-tasks` is detected.
-
-## Public API surface
-External consumers must import `@trevonistrevon/pi-loop/api` (`src/api.ts`), never a deep `src/...` path. The package `exports` map in `package.json` enforces this — deep imports fail to resolve. `src/api.ts` re-exports the RPC channel constants/DTOs, `rpcCall`/`rpcProbe`/`handleRpc`/`RpcError`/`PROTOCOL_VERSION`, `TaskStore`, `TaskEntry`/`TaskStatus`, `resolveLoopStorePath`/`resolveTaskStorePath`, and `NATIVE_TASKS_PROVIDER`. Anything not re-exported there is internal and may change without notice.
-
-## Conventions (mirror pi-tasks)
-- No comments unless answering "why", never "what"
-- `debug(...)` helper gated on `PI_LOOP_DEBUG` env var, logs to stderr
-- `textResult(msg)` helper for uniform tool output
-- All tool params use `Type.Object()` with description strings
-- Tool descriptions follow Claude Code format: `## When to Use`, `## When NOT to Use`
-- Cross-extension communication via `pi.events` with `requestId` + reply channels
-- File-backed stores use atomic write (write tmp → rename) + pid-based file locking
-- Runtime tracker UI uses `UICtx.setStatus()` for compact single-line state
-- Tests co-located in `test/`, named `<module>.test.ts`
-
-## Tool Schema Discipline
-- Tool calls must use the exact schema field names from the tool definition. Do not invent aliases.
-- Example: `TaskUpdate` uses `id`, not `taskId`.
-- When a tool validation error clearly indicates an immediately recoverable schema mismatch, correct it silently and retry. Do not emit user-facing chatter like "retrying with the correct shape" unless the recovery itself changes the user's understanding.
-- When adding or revising tool prompt guidance, include concrete parameter-name reminders for commonly miscalled tools.
-
-## File Locking Pattern
-Copy TaskStore from pi-tasks: `O_EXCL` lockfile, stale PID detection, `LOCK_RETRY_MS`/`LOCK_MAX_RETRIES`
-
-## Trigger Types
-Three trigger types, all stored as `LoopEntry.trigger`:
-- `{ type: "cron", schedule: "*/5 * * * *" }` — timer-based
-- `{ type: "event", source: "tool_execution_start", filter?: "regex:..." | '{"key":"value"}' }` — eventbus-based
-- `{ type: "hybrid", cron: "...", event: { source, filter? }, debounceMs: 30000 }` — both with debounce
-
-All cron/hybrid loops are dynamic: they track their next fire time but only deliver on agent idle (`agent_end`/`turn_start`) rather than wall-clock timers.
-
-## Re-wake via In-Memory Pending Notifications
-When a loop fires, the scheduler calls `onLoopFire()` which emits `pi.events("loop:fire", ...)`. The extension buffers a pending notification in memory, re-checks whether the wake is still relevant, and only then injects a `pi.sendMessage()` custom message to wake the agent. Do not rely on early queued follow-up user messages for loop delivery; those are not extension-cancelable once handed to pi's queue.
-
-All loops are idle-driven. Cron and hybrid loops track their next fire time but only deliver when the agent becomes idle (via `agent_end`/`turn_start`), resetting their timer from the actual delivery point.
-
-## Monitor Streaming via PI Events
-Monitor stdout/stderr lines are emitted as `pi.events("monitor:output", { monitorId, line, timestamp })`. Tool consumers subscribe to these events. Completion emits `"monitor:done"` / `"monitor:error"`.
-
-## pi-tasks Integration
-`pi-loop` probes for `@tintinweb/pi-tasks` at init via `tasks:rpc:ping` (see "Cross-extension RPC" above) and again on a `tasks:ready` listener for late binding. When an external provider answers, `LoopCreate` with `autoTask: true` calls `tasks:rpc:create` to create a tracked task on fire. When no external provider answers, `pi-loop`'s own native RPC server (`src/runtime/native-task-rpc.ts`) serves all five verbs — `ping`/`pending`/`create`/`clean`/`update` — against the native `TaskStore`, and `autoTask: true` creates a native task directly instead of over RPC.
-
-## /loop Self-Paced Mode
-When no interval is specified in `/loop prompt`, the loop runs in self-paced mode. The agent receives the prompt, acts on it, and uses `LoopCreate`/`LoopUpdate` to schedule the next iteration. The loop fires once, then the agent decides the next interval dynamically (matching Claude Code's dynamic interval behavior).
-
-## Testing
-- `vitest` with `describe`/`it` blocks
-- In-memory stores for unit tests, `tmpdir` for file-backed tests
-- Fake timers (`vi.useFakeTimers`) for scheduler tests
-- Mock pi eventbus for monitor-manager tests
-- `vitest run` in CI, `vitest` for watch mode
-
-## Limits
-- Maximum 25 active loops
-- Maximum 25 running monitors
-- 7-day expiry on recurring loops
-- 5-minute default cron interval for self-paced mode