@trevonistrevon/pi-loop 0.6.3 → 0.6.4

package/dist/tools/native-task-tools.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { createTask, deleteTask, updateTask, } from "../runtime/task-mutations.js";
-import { textResult } from "./tool-result.js";
+import { renderToolCall, renderToolResult, toolArg } from "../ui/tool-renderer.js";
+import { displayRows, textResult } from "./tool-result.js";
 function backlogSuffix(backlog) {
     return backlog.created && backlog.entry
         ? `\nBacklog worker loop #${backlog.entry.id} created`
@@ -12,6 +13,8 @@ export function registerNativeTaskTools(options) {
     pi.registerTool({
         name: "TaskCreate",
         label: "TaskCreate",
+        renderCall: renderToolCall("Task", (args) => `create · ${String(toolArg(args, "subject") ?? "task").slice(0, 56)}`),
+        renderResult: renderToolResult,
         description: `Create a task for tracking work across turns. Use when you need to track progress on complex multi-step tasks or turn a broad user goal into a concrete backlog.
 
 Fields:
@@ -38,18 +41,32 @@ Fields:
                 subject: params.subject,
                 description: params.description,
             });
-            return textResult(`Task #${entry.id} created: ${entry.subject}${backlogSuffix(backlog)}`);
+            return textResult(`Task #${entry.id} created: ${entry.subject}${backlogSuffix(backlog)}`, {
+                kind: "task",
+                action: "create",
+                tone: "success",
+                summary: `Task #${entry.id} pending · ${entry.subject.slice(0, 56)}`,
+                expanded: [
+                    `Description: ${entry.description}`,
+                    backlog.created && backlog.entry ? `Backlog worker: loop #${backlog.entry.id} created` : "Backlog worker: unchanged",
+                ],
+            });
         },
     });
     pi.registerTool({
         name: "TaskList",
         label: "TaskList",
+        renderCall: renderToolCall("Task", () => "status"),
+        renderResult: renderToolResult,
         description: "List all tasks with status. Use to check progress and find available work.",
         parameters: Type.Object({}),
         execute() {
             const tasks = taskStore.list();
-            if (tasks.length === 0)
-                return Promise.resolve(textResult("No tasks."));
+            if (tasks.length === 0) {
+                return Promise.resolve(textResult("No tasks.", {
+                    kind: "task", action: "list", tone: "info", summary: "No tasks", expanded: ["Use TaskCreate for work that spans turns."],
+                }));
+            }
             const lines = [];
             const statuses = {
                 pending: 0,
@@ -62,12 +79,20 @@ Fields:
                 lines.push(`${icon} #${t.id} [${t.status}] ${t.subject.slice(0, 80)}`);
             }
             lines.unshift(`${tasks.length} tasks (${statuses.pending} pending, ${statuses.in_progress} in progress, ${statuses.completed} done)`);
-            return Promise.resolve(textResult(lines.join("\n")));
+            return Promise.resolve(textResult(lines.join("\n"), {
+                kind: "task",
+                action: "list",
+                tone: "info",
+                summary: `${tasks.length} task${tasks.length === 1 ? "" : "s"} · ${statuses.pending} pending · ${statuses.in_progress} active`,
+                expanded: displayRows(lines.slice(1)),
+            }));
         },
     });
     pi.registerTool({
         name: "TaskUpdate",
         label: "TaskUpdate",
+        renderCall: renderToolCall("Task", (args) => `update · #${String(toolArg(args, "id") ?? "?")}`),
+        renderResult: renderToolResult,
         description: `Update task status or details. Set status to "in_progress" before starting work, "completed" when done.
 
 Statuses: pending → in_progress → completed
@@ -91,24 +116,44 @@ Parameters: id (required), status, subject, description`,
                 subject,
                 description,
             });
-            if (!result)
-                return textResult(`Task #${id} not found`);
+            if (!result) {
+                return textResult(`Task #${id} not found`, {
+                    kind: "task", action: "update", tone: "error", summary: `Task #${id} not found`, expanded: ["Use TaskList to find valid task IDs."],
+                });
+            }
             const statusMsg = status ? ` → ${status}` : "";
-            return textResult(`Task #${id} updated${statusMsg}${backlogSuffix(result.backlog)}`);
+            return textResult(`Task #${id} updated${statusMsg}${backlogSuffix(result.backlog)}`, {
+                kind: "task",
+                action: "update",
+                tone: "success",
+                summary: `Task #${id}${status ? ` → ${status}` : " updated"}`,
+                expanded: [
+                    `Subject: ${result.entry.subject}`,
+                    `Status: ${result.entry.status}`,
+                    result.backlog.created && result.backlog.entry ? `Backlog worker: loop #${result.backlog.entry.id} created` : "Backlog worker: unchanged",
+                ],
+            });
         },
     });
     pi.registerTool({
         name: "TaskDelete",
         label: "TaskDelete",
+        renderCall: renderToolCall("Task", (args) => `delete · #${String(toolArg(args, "id") ?? "?")}`),
+        renderResult: renderToolResult,
         description: "Delete a task by ID. Use for cleaning up completed or irrelevant tasks.",
         parameters: Type.Object({
             id: Type.String({ description: "Task ID to delete" }),
         }),
         async execute(_toolCallId, params) {
             const result = await deleteTask(mutationCtx, params.id);
-            if (!result)
-                return textResult(`Task #${params.id} not found`);
-            return textResult(`Task #${params.id} deleted`);
+            if (!result) {
+                return textResult(`Task #${params.id} not found`, {
+                    kind: "task", action: "delete", tone: "error", summary: `Task #${params.id} not found`, expanded: ["Use TaskList to find valid task IDs."],
+                });
+            }
+            return textResult(`Task #${params.id} deleted`, {
+                kind: "task", action: "delete", tone: "success", summary: `Task #${params.id} deleted`, expanded: [],
+            });
         },
     });
 }

package/dist/tools/tool-result.d.ts

@@ -1,8 +1,18 @@
 /** Plain-text tool result in the shape pi's registerTool expects. */
-export declare function textResult(msg: string): {
+export type ToolDisplayKind = "loop" | "workflow" | "task" | "monitor";
+export type ToolDisplayTone = "success" | "warning" | "error" | "info";
+export interface ToolDisplayDetails {
+    kind: ToolDisplayKind;
+    action: string;
+    tone: ToolDisplayTone;
+    summary: string;
+    expanded?: string[];
+}
+export declare function displayRows(rows: string[], limit?: number): string[];
+export declare function textResult(msg: string, details?: ToolDisplayDetails): {
     content: {
         type: "text";
         text: string;
     }[];
-    details: undefined;
+    details: ToolDisplayDetails | undefined;
 };

package/dist/tools/tool-result.js

@@ -1,4 +1,8 @@
-/** Plain-text tool result in the shape pi's registerTool expects. */
-export function textResult(msg) {
-    return { content: [{ type: "text", text: msg }], details: undefined };
+export function displayRows(rows, limit = 8) {
+    if (rows.length <= limit)
+        return rows;
+    return [...rows.slice(0, limit), `… ${rows.length - limit} more`];
+}
+export function textResult(msg, details) {
+    return { content: [{ type: "text", text: msg }], details };
 }

package/dist/types.d.ts

@@ -40,6 +40,40 @@ export interface DynamicLoopState {
     awaitingUpdate?: boolean;
     lastUpdatedAt?: number;
 }
+export type WorkflowTerminalStatus = "completed" | "paused";
+export interface WorkflowTaskDefinition {
+    subject: string;
+    description: string;
+}
+export interface WorkflowStateDefinition {
+    prompt: string;
+    task?: WorkflowTaskDefinition;
+    on?: Record<string, string>;
+    terminal?: WorkflowTerminalStatus;
+    maxAttempts?: number;
+}
+export interface WorkflowDefinition {
+    version: 1;
+    initialState: string;
+    states: Record<string, WorkflowStateDefinition>;
+}
+export interface WorkflowTransitionRecord {
+    from: string;
+    to: string;
+    outcome: string;
+    evidence?: string;
+    at: number;
+    sequence: number;
+}
+export interface WorkflowRunState {
+    definition: WorkflowDefinition;
+    currentState: string;
+    transitionSeq: number;
+    stateEnteredAt: number;
+    attemptsByState: Record<string, number>;
+    activeTaskId?: string;
+    lastTransition?: WorkflowTransitionRecord;
+}
 export interface LoopEntry {
     id: string;
     prompt: string;
@@ -55,6 +89,7 @@ export interface LoopEntry {
     maxFires?: number;
     fireCount?: number;
     dynamic?: DynamicLoopState;
+    workflow?: WorkflowRunState;
 }
 export interface LoopStoreData {
     nextId: number;

package/dist/ui/tool-renderer.d.ts

@@ -0,0 +1,7 @@
+import type { AgentToolResult, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+type ToolCallArgs = object;
+export declare function renderToolCall(label: string, summarize: (args: ToolCallArgs) => string): (args: ToolCallArgs, theme: Theme) => Text;
+export declare function toolArg(args: ToolCallArgs, name: string): unknown;
+export declare function renderToolResult(result: AgentToolResult<unknown>, { expanded, isPartial }: ToolRenderResultOptions, theme: Theme): Text;
+export {};

package/dist/ui/tool-renderer.js

@@ -0,0 +1,34 @@
+import { Text } from "@earendil-works/pi-tui";
+export function renderToolCall(label, summarize) {
+    return (args, theme) => {
+        const summary = summarize(args);
+        const text = theme.fg("toolTitle", theme.bold(`${label} `)) + theme.fg("muted", summary);
+        return new Text(text, 0, 0);
+    };
+}
+export function toolArg(args, name) {
+    return args[name];
+}
+export function renderToolResult(result, { expanded, isPartial }, theme) {
+    if (isPartial)
+        return new Text(theme.fg("warning", "Working…"), 0, 0);
+    const details = result.details;
+    if (!details) {
+        const content = result.content[0];
+        return new Text(content?.type === "text" ? content.text : "No result", 0, 0);
+    }
+    const color = details.tone === "success"
+        ? "success"
+        : details.tone === "warning"
+            ? "warning"
+            : details.tone === "error"
+                ? "error"
+                : "muted";
+    const icon = details.tone === "success" ? "✓" : details.tone === "error" ? "✕" : details.tone === "warning" ? "!" : "•";
+    let text = theme.fg(color, `${icon} ${details.summary}`);
+    if (expanded && details.expanded?.length) {
+        for (const line of details.expanded)
+            text += `\n${theme.fg("dim", line)}`;
+    }
+    return new Text(text, 0, 0);
+}

package/dist/ui/widget.js

@@ -23,18 +23,18 @@ export class LoopWidget {
     }
     computeStatus() {
         const loops = this.store.list().filter(isStatusVisibleLoop);
-        const monitors = this.monitorManager.list();
+        const monitors = this.monitorManager.list().filter((monitor) => monitor.status === "running");
         const taskSummary = this.taskSummaryProvider?.() ?? { count: 0 };
         if (loops.length === 0 && monitors.length === 0 && taskSummary.count === 0) {
             return undefined;
         }
         const parts = [];
         if (loops.length > 0)
-            parts.push(formatCount(loops.length, "loop"));
+            parts.push(`↻ ${formatCount(loops.length, "loop")}`);
         if (monitors.length > 0)
-            parts.push(formatCount(monitors.length, "monitor"));
+            parts.push(`▶ ${formatCount(monitors.length, "monitor")}`);
         if (taskSummary.count > 0)
-            parts.push(formatCount(taskSummary.count, "task"));
+            parts.push(`□ ${formatCount(taskSummary.count, "task")}`);
         let line = parts.join(" · ");
         if (taskSummary.focusText)
             line += ` | ${taskSummary.focusText}`;

package/dist/workflow-reducer.d.ts

@@ -0,0 +1,18 @@
+import type { WorkflowDefinition, WorkflowRunState, WorkflowTerminalStatus } from "./types.js";
+export type { WorkflowDefinition, WorkflowRunState, WorkflowStateDefinition, WorkflowTerminalStatus, WorkflowTransitionRecord, } from "./types.js";
+export interface WorkflowTransitionInput {
+    outcome: string;
+    evidence?: string;
+    activeTaskId?: string;
+}
+export type WorkflowTransitionResult = {
+    applied: true;
+    run: WorkflowRunState;
+    terminal?: WorkflowTerminalStatus;
+} | {
+    applied: false;
+    error: string;
+};
+export declare function validateWorkflowDefinition(definition: WorkflowDefinition): string | undefined;
+export declare function createWorkflowRun(definition: WorkflowDefinition, at: number): WorkflowRunState;
+export declare function transitionWorkflowRun(run: WorkflowRunState, input: WorkflowTransitionInput, at: number): WorkflowTransitionResult;

package/dist/workflow-reducer.js

@@ -0,0 +1,82 @@
+export function validateWorkflowDefinition(definition) {
+    if (!definition || definition.version !== 1)
+        return "Workflow version must be 1";
+    if (!definition.states || typeof definition.states !== "object")
+        return "Workflow states must be an object";
+    if (!definition.initialState || !definition.states[definition.initialState]) {
+        return `Initial state "${definition.initialState}" is not defined`;
+    }
+    for (const [stateId, state] of Object.entries(definition.states)) {
+        if (!stateId)
+            return "Workflow state IDs must be non-empty";
+        if (!state || typeof state !== "object")
+            return `State "${stateId}" must be an object`;
+        if (typeof state.prompt !== "string")
+            return `State "${stateId}" requires a prompt`;
+        if (!state.prompt.trim())
+            return `State "${stateId}" requires a prompt`;
+        if (state.on !== undefined && (typeof state.on !== "object" || Array.isArray(state.on))) {
+            return `State "${stateId}" transitions must be an object`;
+        }
+        if (state.terminal && state.on && Object.keys(state.on).length > 0) {
+            return `Terminal state "${stateId}" cannot declare transitions`;
+        }
+        if (state.maxAttempts !== undefined && (!Number.isInteger(state.maxAttempts) || state.maxAttempts < 1)) {
+            return `State "${stateId}" maxAttempts must be a positive integer`;
+        }
+        for (const [outcome, target] of Object.entries(state.on ?? {})) {
+            if (!outcome)
+                return `State "${stateId}" has an empty outcome name`;
+            if (typeof target !== "string")
+                return `Transition "${stateId}.${outcome}" target must be a state ID`;
+            if (!definition.states[target])
+                return `Transition "${stateId}.${outcome}" targets unknown state "${target}"`;
+        }
+    }
+    return undefined;
+}
+export function createWorkflowRun(definition, at) {
+    return {
+        definition,
+        currentState: definition.initialState,
+        transitionSeq: 0,
+        stateEnteredAt: at,
+        attemptsByState: { [definition.initialState]: 1 },
+    };
+}
+export function transitionWorkflowRun(run, input, at) {
+    const current = run.definition.states[run.currentState];
+    if (!current)
+        return { applied: false, error: `Current state "${run.currentState}" is not defined` };
+    if (current.terminal)
+        return { applied: false, error: `Workflow is already ${current.terminal}` };
+    const target = current.on?.[input.outcome];
+    if (!target)
+        return { applied: false, error: `Outcome "${input.outcome}" is not allowed from state "${run.currentState}"` };
+    const targetState = run.definition.states[target];
+    if (!targetState)
+        return { applied: false, error: `Transition target "${target}" is not defined` };
+    const nextAttempt = (run.attemptsByState[target] ?? 0) + 1;
+    if (targetState.maxAttempts !== undefined && nextAttempt > targetState.maxAttempts) {
+        return { applied: false, error: `State "${target}" has exhausted its ${targetState.maxAttempts} attempt limit` };
+    }
+    const sequence = run.transitionSeq + 1;
+    const lastTransition = {
+        from: run.currentState,
+        to: target,
+        outcome: input.outcome,
+        evidence: input.evidence,
+        at,
+        sequence,
+    };
+    const nextRun = {
+        ...run,
+        currentState: target,
+        transitionSeq: sequence,
+        stateEnteredAt: at,
+        attemptsByState: { ...run.attemptsByState, [target]: nextAttempt },
+        activeTaskId: input.activeTaskId,
+        lastTransition,
+    };
+    return { applied: true, run: nextRun, terminal: targetState.terminal };
+}

package/docs/USAGE_GUIDE.md

@@ -60,6 +60,47 @@ LoopUpdate id="1" status="completed"
 
 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.
 
+### Opt-in workflow loops
+
+Use a workflow only when work has stable named phases and outcomes. Ordinary reminders, polling, event hooks, and flat task backlogs should continue to use `LoopCreate` or the task tools.
+
+```text
+WorkflowCreate goal="Fix the regression" definition='{
+  "version": 1,
+  "initialState": "investigate",
+  "states": {
+    "investigate": {
+      "prompt": "Find and verify the root cause.",
+      "task": { "subject": "Investigate regression", "description": "Find the root cause and reproduce it." },
+      "on": { "root_cause_found": "fix", "blocked": "blocked" }
+    },
+    "fix": {
+      "prompt": "Implement and validate the fix.",
+      "task": { "subject": "Implement fix", "description": "Make the smallest fix and run targeted validation." },
+      "on": { "tests_pass": "done", "regression_found": "investigate" },
+      "maxAttempts": 2
+    },
+    "done": { "prompt": "Report completion.", "terminal": "completed" },
+    "blocked": { "prompt": "Report the blocker.", "terminal": "paused" }
+  }
+}'
+```
+
+Each wake presents the current state, state instructions, active task, and allowed outcomes. The agent finishes the state by selecting one declared outcome:
+
+```text
+WorkflowTransition id="1" outcome="root_cause_found" evidence="A null config reaches the parser."
+WorkflowTransition id="1" outcome="tests_pass" evidence="Targeted and full test suites pass."
+```
+
+`WorkflowTransition` validates the branch, records evidence, creates the next state's optional task, and queues the next wake. Reaching a `completed` terminal state deletes the workflow loop; reaching a `paused` terminal state preserves it in paused state. Task completion does not guess an outcome—the model selects one explicitly.
+
+```text
+WorkflowList
+```
+
+Lists only workflow loops, including their active state, active task, and valid outcomes.
+
 ### Inspecting and stopping loops
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevonistrevon/pi-loop",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "A pi extension for cron/event-based agent re-wake loops and background process monitoring.",
   "author": "trevonistrevon",
   "license": "MIT",
@@ -31,8 +31,8 @@
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.10",
-    "@earendil-works/pi-tui": "^0.80.10"
+    "@earendil-works/pi-coding-agent": "^0.81.1",
+    "@earendil-works/pi-tui": "^0.81.1"
   },
   "dependencies": {
     "typebox": "^1.1.34"

package/src/api.ts

@@ -33,4 +33,12 @@ export {
 export { NATIVE_TASKS_PROVIDER } from "./runtime/native-task-rpc.js";
 export { resolveLoopStorePath, resolveTaskStorePath } from "./runtime/scope.js";
 export { TaskStore } from "./task-store.js";
-export type { TaskEntry, TaskStatus, TaskStoreData } from "./task-types.js";
+export type { TaskEntry, TaskStatus, TaskStoreData, TaskWorkflowLink } from "./task-types.js";
+export type {
+  WorkflowDefinition,
+  WorkflowRunState,
+  WorkflowStateDefinition,
+  WorkflowTaskDefinition,
+  WorkflowTerminalStatus,
+  WorkflowTransitionRecord,
+} from "./types.js";

package/src/index.ts

@@ -128,6 +128,10 @@ export default function (pi: ExtensionAPI) {
     onDetectionSettled: () => {
       tasksDetectionSettled = true;
     },
+    isDetectionSettled: () => tasksDetectionSettled,
+    onNativeTaskCompleted: () => {
+      widget.update();
+    },
     debug,
   });
 
@@ -282,6 +286,7 @@ export default function (pi: ExtensionAPI) {
       autoTask: firedEntry.autoTask,
       taskBacklog: firedEntry.taskBacklog,
       dynamic: firedEntry.dynamic,
+      workflow: firedEntry.workflow,
     });
   }
 
@@ -349,6 +354,11 @@ export default function (pi: ExtensionAPI) {
     },
     maybeBootstrapTaskLoop,
     isTaskSystemReady: () => tasksAvailable || nativeTasksRegistered,
+    onDynamicLoopActivated: (entry) => {
+      onLoopFire(entry);
+    },
+    createWorkflowTask: (entry) => taskRuntime.createWorkflowTask(entry),
+    completeWorkflowTask: (taskId) => taskRuntime.completeWorkflowTask(taskId),
   });
 
   function handleMonitorDoneLoop(doneLoop: LoopEntry, monitorId: string): void {

package/src/loop-reducer.ts

@@ -1,4 +1,5 @@
-import type { DynamicLoopState, LoopEntry, Trigger } from "./types.js";
+import type { DynamicLoopState, LoopEntry, Trigger, WorkflowDefinition } from "./types.js";
+import { createWorkflowRun, transitionWorkflowRun } from "./workflow-reducer.js";
 
 export const MAX_LOOP_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -35,6 +36,7 @@ export type LoopReducerEvent =
       readOnly?: boolean;
       maxFires?: number;
       dynamic?: Partial<DynamicLoopState>;
+      workflow?: WorkflowDefinition;
     };
   }
   | {
@@ -73,6 +75,27 @@ export type LoopReducerEvent =
       prompt?: string;
       dynamic: Partial<DynamicLoopState>;
     };
+  }
+  | {
+    type: "LOOP_WORKFLOW_TRANSITION";
+    at: number;
+    source: ReducerSource;
+    entityType?: "loop";
+    entityId?: string;
+    payload: {
+      id: string;
+      outcome: string;
+      evidence?: string;
+      activeTaskId?: string;
+    };
+  }
+  | {
+    type: "LOOP_WORKFLOW_TASK_SET";
+    at: number;
+    source: ReducerSource;
+    entityType?: "loop";
+    entityId?: string;
+    payload: { id: string; taskId?: string };
   };
 
 export type LoopReducerEffect =
@@ -131,6 +154,7 @@ export function reduceLoopState(state: LoopReducerState, event: LoopReducerEvent
             lastUpdatedAt: event.payload.dynamic?.lastUpdatedAt ?? event.at,
           }
         : undefined,
+      workflow: event.payload.workflow ? createWorkflowRun(event.payload.workflow, event.at) : undefined,
     };
     next.loopsById[id] = loop;
     return {
@@ -190,6 +214,34 @@ export function reduceLoopState(state: LoopReducerState, event: LoopReducerEvent
     loop.updatedAt = event.at;
   }
 
+  if (event.type === "LOOP_WORKFLOW_TRANSITION") {
+    if (!loop.workflow) return { state, effects: [] };
+    const result = transitionWorkflowRun(loop.workflow, {
+      outcome: event.payload.outcome,
+      evidence: event.payload.evidence,
+      activeTaskId: event.payload.activeTaskId,
+    }, event.at);
+    if (!result.applied) return { state, effects: [] };
+    loop.workflow = result.run;
+    loop.dynamic = {
+      goal: loop.dynamic?.goal ?? loop.prompt,
+      state: result.run.currentState,
+      metrics: loop.dynamic?.metrics,
+      doneCriteria: loop.dynamic?.doneCriteria,
+      iteration: (loop.dynamic?.iteration ?? 0) + 1,
+      nextWakeAt: undefined,
+      awaitingUpdate: false,
+      lastUpdatedAt: event.at,
+    };
+    loop.updatedAt = event.at;
+  }
+
+  if (event.type === "LOOP_WORKFLOW_TASK_SET") {
+    if (!loop.workflow) return { state, effects: [] };
+    loop.workflow = { ...loop.workflow, activeTaskId: event.payload.taskId };
+    loop.updatedAt = event.at;
+  }
+
   next.loopsById[id] = loop;
   return {
     state: next,

package/src/notification-reducer.ts

@@ -1,4 +1,4 @@
-import type { DynamicLoopState } from "./types.js";
+import type { DynamicLoopState, WorkflowRunState } from "./types.js";
 
 type ReducerSource = "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
 
@@ -14,6 +14,7 @@ export interface ReducerNotification {
   taskBacklog?: boolean;
   readOnly?: boolean;
   dynamic?: DynamicLoopState;
+  workflow?: WorkflowRunState;
 }
 
 export interface NotificationReducerState {

package/src/runtime/notification-runtime.ts

@@ -12,7 +12,7 @@ import {
   type ReducerNotification,
   reduceNotificationState,
 } from "../notification-reducer.js";
-import type { DynamicLoopState, Trigger } from "../types.js";
+import type { DynamicLoopState, Trigger, WorkflowRunState } from "../types.js";
 
 export interface LoopFireEvent {
   loopId: string;
@@ -25,6 +25,7 @@ export interface LoopFireEvent {
   autoTask?: boolean;
   taskBacklog?: boolean;
   dynamic?: DynamicLoopState;
+  workflow?: WorkflowRunState;
 }
 
 export interface PendingNotification extends LoopFireEvent {
@@ -106,6 +107,24 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
       ? "\n\nREAD-ONLY MODE — use only read tools (Read, TaskList, LoopList, MonitorList, etc.). No file writes, shell execution, or destructive changes."
       : "";
 
+    if (data.workflow) {
+      const state = data.workflow.definition.states[data.workflow.currentState];
+      const outcomes = Object.keys(state?.on ?? {});
+      const lines = [
+        `[pi-loop] Loop #${loopId} fired (workflow).${constraint}`,
+        `Goal: ${data.prompt || data.workflow.definition.initialState}`,
+        `State: ${data.workflow.currentState}`,
+      ];
+      if (state?.prompt) lines.push(`State instructions: ${state.prompt}`);
+      if (data.workflow.activeTaskId) lines.push(`Active task: #${data.workflow.activeTaskId}`);
+      if (outcomes.length > 0) lines.push(`Allowed outcomes: ${outcomes.join(", ")}`);
+      lines.push(
+        `Workflow lifecycle: Loop #${loopId} is an opt-in state controller. Do not call LoopDelete after this state.`,
+        "Before ending this turn, call WorkflowTransition exactly once with this workflow id and one allowed outcome. Include evidence for the branch decision. Terminal outcomes complete or pause the workflow automatically.",
+      );
+      return lines.join("\n");
+    }
+
     if (data.dynamic || (typeof data.trigger !== "string" && data.trigger?.type === "dynamic")) {
       const dynamic = data.dynamic;
       const lines = [
@@ -169,6 +188,7 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
         autoTask: notification.autoTask,
         taskBacklog: notification.taskBacklog,
         dynamic: notification.dynamic,
+        workflow: notification.workflow,
         timestamp: notification.timestamp,
       },
     }, {

package/src/runtime/task-events.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { TaskEntry, TaskStatus } from "../task-types.js";
+import type { TaskEntry, TaskStatus, TaskWorkflowLink } from "../task-types.js";
 
 export type NativeTaskEventName =
   | "tasks:created"
@@ -19,6 +19,7 @@ export interface NativeTaskEventPayload {
   updatedAt: number;
   completedAt?: number;
   metadata?: Record<string, unknown>;
+  workflow?: TaskWorkflowLink;
 }
 
 export function emitNativeTaskEvent(
@@ -37,5 +38,6 @@ export function emitNativeTaskEvent(
     updatedAt: entry.updatedAt,
     completedAt: entry.completedAt,
     metadata: entry.metadata,
+    workflow: entry.workflow,
   } satisfies NativeTaskEventPayload);
 }