@llblab/pi-actors 0.50.0 → 0.51.0

package/AGENTS.md

@@ -84,7 +84,7 @@ Canonical event:
 {"id":"…","ts":"…","kind":"…","summary":"…","data":{},"level":"info","attention":"notify"}
 ```
 
-Trace is a bounded retained suffix, not an audit archive. Every first-party writer must call `appendRunTraceEvent`; under the canonical token-owned lock it appends within both fixed bounds or atomically retains the newest suffix plus one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; terminal/result/execution/artifact files remain authoritative independently. Reads are newline-safe and order equal timestamps by same-source ordinal, fixed source rank, then stable id without exposing ordering metadata. Never write `trace.jsonl` directly. Persist durable state or an artifact before attention; `attention: "followup"` remains rare.
+Trace is a bounded retained suffix, not an audit archive. Every first-party writer must call `appendRunTraceEvent`; under the canonical token-owned lock it appends within both fixed bounds or atomically retains the newest suffix plus one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; terminal/result/execution/artifact files remain authoritative independently. Reads are newline-safe and order equal timestamps by same-source ordinal, fixed source rank, then stable id without exposing ordering metadata. Never write `trace.jsonl` directly. Generic command lifecycle is Trace-only: `command.done` preserves complete bounded execution evidence but never requests or projects attention, and Recipe grammar has no command-completion delivery switch. Attention is an explicit semantic wake hint: persist durable state or an artifact first; `attention: "followup"` remains rare. Reconcile root terminal transitions before attention. One normal finite Run defaults to one automatic agent turn from its root terminal result; sequence, parallel, repeat, and import branches remain internal, while each separately launched Run owns a separate generation.
 
 ### Control
 

package/BACKLOG.md

@@ -1,6 +1,6 @@
 # Project Backlog
 
-- [ ] `Future minor — Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority; keep this feature outside the 0.49.2 and 0.50.0 cohorts.
+- [ ] `Future minor — Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority.
   - [ ] Publish `PlaybackStatus`, track metadata, duration, read-time position, volume, and supported capabilities under one stable session-scoped bus identity; disappear cleanly when the Run stops or its generation is replaced, and fail soft when the user D-Bus session is unavailable.
   - [ ] Map `Play`, `Pause`, `PlayPause`, `Next`, `Previous`, `Stop`, `Seek`, `SetPosition`, and `Volume` back into the existing generation-fenced music-player Control/helper contract rather than signaling the backend or editing Run state directly.
   - [ ] Validate deterministic D-Bus contract behavior plus a live GNOME smoke showing the media surface, metadata, progress, volume, and controls while preserving backend independence and exact Actor ownership.

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.51.0: Monotonic Run Follow-Ups
+
+- `Root-Owned Follow-Up`: A normal finite Run now produces one automatic agent turn from its root terminal result. Sequence, parallel, repeat, and imported branches remain internal execution topology; each separately launched Run still owns a separate generation and terminal lifecycle.
+- `Trace-Only Command Lifecycle`: Consolidates each command completion into one complete bounded `command.done` observation with level, captures, session provenance, artifacts, and execution evidence, but no attention. Legacy `command.done` attention remains non-projectable, and the removed Recipe-level delivery grammar stays removed.
+- `Monotonic Reconciliation`: Delivers terminal transitions before explicit semantic attention, preserves silent Runs, synchronous stop behavior, generation fencing, terminal retry evidence, and semantic checkpoints, and removes branch exit-code heuristics that could wake the coordinator from stale process-level events.
+- `Settled Pi Baseline`: Requires Pi and Pi TUI 0.84.4 or newer and schedules automatic Recipe review on `agent_settled`, after queued follow-ups, retries, and compaction complete. Source and packed-package regressions pin the lifecycle and minimum peer contract.
+
 ## 0.50.0: Hardened Actor Baseline
 
 - `Template Recipe Standard`: Rebuilt the Recipe authoring guide around one current-state contract: formats, identity, uniformly detailed file-level and command-node field tables, resolution precedence, imports, async/singleton lifecycle, Control, artifacts, runtime origins, provenance, authoring workflow, and validation. Removed migration history and legacy-reference narration from the normative document.

package/README.md

@@ -19,7 +19,7 @@ This topology does not require every task to become a subagent. Short work with
 
 ## Install
 
-Requires Node.js 22.19.0 or newer.
+Requires Node.js 22.19.0 or newer and Pi 0.84.4 or newer.
 
 ```bash
 pi install npm:@llblab/pi-actors
@@ -151,7 +151,9 @@ String command-template leaves execute directly without shell interpretation. Us
 
 Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `level`, `attention`. Address, sender, recipient, reply, and routing fields fail validation. Trace is a bounded retained suffix, not an audit archive: the canonical authority appends within 2,048 events and 4 MiB or atomically keeps the newest suffix plus one warning-only `runtime.trace_compacted` marker. That marker means older history was discarded; `result.json`, `execution.json`, terminal state, and declared artifacts retain their own authority. `inspect view=trace` reports whether retained history is complete. Reads are newline-safe and deterministic; first-party scripts never write this file directly.
 
-Attention is a live wake hint, not a durable queue: persist recovery state or an artifact first. Use `attention: "notify"` for visible status and `attention: "followup"` only when the coordinator needs semantic follow-up context; compaction may discard older hints. Store large evidence in artifacts or bounded execution captures.
+Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve completion and execution evidence but never request or project attention. There is no Recipe-level command-completion delivery switch. Attention is an explicit semantic opt-in and a live wake hint, not a durable queue: persist recovery state or an artifact first, use `attention: "notify"` for visible status and `attention: "followup"` only when the coordinator needs semantic follow-up context, and expect compaction to discard older hints. Store large evidence in artifacts or bounded execution captures.
+
+By default, one normal finite Run produces one automatic agent turn from its root terminal result. Sequence, parallel, repeat, and imported branches remain internal to that Run and do not create branch-level turns; each separately launched Run owns its own generation and terminal follow-up.
 
 ## Control
 

package/dist/index.js

@@ -9,7 +9,7 @@ export default function toolRegistryExtension(pi) {
     const runtime = ExtensionRuntime.createActorExtensionRuntime(pi);
     pi.on("resources_discover", async () => runtime.discoverResources(import.meta.url));
     pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
-    pi.on("agent_end", async (_event, ctx) => runtime.onAgentEnd(ctx));
+    pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
     pi.on("session_shutdown", async (event, ctx) => runtime.onSessionShutdown(event.reason, ctx));
     pi.on("before_agent_start", async (event, ctx) => runtime.beforeAgentStart(event.systemPrompt, event.systemPromptOptions.skills ?? [], ctx));
     InspectorCommand.registerActorInspectorCommand(pi, runtime.getRunOwnerId);

package/dist/lib/extension-runtime.d.ts

@@ -13,7 +13,7 @@ export interface ActorExtensionRuntime {
         skillPaths: string[];
     } | undefined;
     getRunOwnerId(ctx: Pi.ExtensionContext): string;
-    onAgentEnd(ctx: Pi.ExtensionContext): void;
+    onAgentSettled(ctx: Pi.ExtensionContext): void;
     onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
     onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;
     registerCoreTools(): void;

package/dist/lib/extension-runtime.js

@@ -112,7 +112,7 @@ export function createActorExtensionRuntime(pi) {
             return skillPaths.length > 0 ? { skillPaths } : undefined;
         },
         getRunOwnerId,
-        onAgentEnd(ctx) {
+        onAgentSettled(ctx) {
             if (activeRunContext === ctx)
                 automaticReview.schedule();
         },

package/dist/lib/observability.js

@@ -75,9 +75,9 @@ export function reconcileRunTerminalNotifications(input) {
         includeAttention: input.includeAttention,
         stateRoot: input.stateRoot,
     });
+    deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
     if (input.includeAttention)
         deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
-    deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
     pruneRunUiObservationState(input.state, snapshot);
     return snapshot;
 }
@@ -838,6 +838,8 @@ export function getRunAttentionNotificationType(event) {
     return event.level;
 }
 export function shouldNotifyRunAttentionEvent(event) {
+    if (event.kind === "command.done")
+        return false;
     return event.attention === "notify" || event.attention === "followup";
 }
 export function shouldSendRunAttentionFollowUp(event) {

package/dist/scripts/async-runner.mjs

@@ -284,9 +284,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       complete_allowed: missing.length === 0,
     };
   }
-  function getCommandDoneDelivery(result) {
-    return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
-  }
   function progressRunning() {
     progress("running", {
       activeSubagents,
@@ -433,21 +430,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
         ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
       });
     }
-    event("command.done", {
-      activeSubagents,
-      command_id: commandId,
-      code: result.code,
-      command: commandDetail,
-      killed: result.killed,
-      ...captureDetails(result),
-      ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
-      ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
-      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
-      ...(commandSessionFiles(session.sessionDir).length > 0
-        ? { session_files: commandSessionFiles(session.sessionDir) }
-        : {}),
-      ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
-    });
     observation(
       "command.done",
       `Command ${summarizeCommandDetail(commandDetail)} completed with code ${result.code}`,
@@ -462,9 +444,13 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
         ...captureDetails(result),
         ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
         ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+        ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
+        ...(commandSessionFiles(session.sessionDir).length > 0
+          ? { session_files: commandSessionFiles(session.sessionDir) }
+          : {}),
         ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
       },
-      getCommandDoneDelivery(result),
+      "log",
       result.code === 0 ? "info" : "error",
     );
     progressRunning();

package/docs/async-runs.md

@@ -52,12 +52,13 @@ diagnostics.jsonl
 Trace records strict bounded events:
 
 ```json
-{"id":"…","ts":"…","kind":"command.done","summary":"Command completed","data":{"code":0},"level":"info","attention":"followup"}
+{"id":"…","ts":"…","kind":"command.done","summary":"Command completed","data":{"code":0},"level":"info"}
+{"id":"…","ts":"…","kind":"checkpoint.ready","summary":"Review needs a decision","level":"info","attention":"followup"}
 ```
 
 Required fields: `id`, `ts`, `kind`. Optional fields: `summary`, `data`, `level`, `attention`. Trace rejects addressed-envelope fields and malformed or oversized data. It retains a recent suffix within 2,048 events and 4 MiB. When either bound would be exceeded, the canonical lock atomically keeps a newest suffix near the lower targets, the new event, and one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; it reports cumulative drop evidence and never requests attention.
 
-Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. Bounded reads preserve complete UTF-8 lines and disclose omitted legacy prefixes. `inspect view=trace` reports retained-history completeness and projects events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics newest-first. Equal timestamps use same-source physical order, then fixed source rank and stable id without claiming cross-source causality. Terminal state, `result.json`, `execution.json`, and artifacts remain authoritative even when old Trace has compacted.
+Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve level, captures, session provenance, and execution evidence but never request or project attention. No Recipe field configures command-completion delivery. Semantic checkpoints opt in explicitly with `attention: "notify"` or `attention: "followup"`; they must not infer coordinator intent from a leaf exit code. Bounded reads preserve complete UTF-8 lines and disclose omitted legacy prefixes. `inspect view=trace` reports retained-history completeness and projects events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics newest-first. Equal timestamps use same-source physical order, then fixed source rank and stable id without claiming cross-source causality. Terminal state, `result.json`, `execution.json`, and artifacts remain authoritative even when old Trace has compacted.
 
 ## Control
 
@@ -106,7 +107,9 @@ Review acceptance remains a command-stage concern. General execution evidence do
 
 Statuses include `running`, `done`, `failed`, `exited`, `cancelled`, and `killed`. Status resolution combines persisted metadata, result/terminal evidence, and verified process state.
 
-Ambient observation detects terminal transitions and retained Trace attention. Canonical attention is an in-memory wake hint, not a durable queue: observers prime retained ids at startup, deliver each later retained unseen id once, and bound memory to the current retained set across compaction. Persist durable recovery state or an artifact before emitting attention; compaction may discard older hints and its marker makes that history loss explicit. Terminal follow-up delivery persists handled/failure evidence so reloads retry unhandled transitions without duplicating completed notifications.
+Ambient observation detects root terminal transitions and explicit retained Trace attention. Terminal transitions reconcile before semantic attention. Canonical attention is an in-memory wake hint, not a durable queue: observers prime retained ids at startup, deliver each later retained unseen id once, and bound memory to the current retained set across compaction. Persist durable recovery state or an artifact before emitting attention; compaction may discard older hints and its marker makes that history loss explicit. Terminal follow-up delivery persists handled/failure evidence so reloads retry unhandled transitions without duplicating completed notifications.
+
+By default, one normal finite Run produces exactly one automatic agent turn from its root terminal result. Sequence, parallel, repeat, and imported branches are internal execution topology and never own branch-level turns. Each separately launched Run owns its own generation and terminal lifecycle; compatible singleton reuse is not a new launch. Explicit semantic attention may intentionally add a checkpoint turn; Runs marked silent suppress automatic projection.
 
 Large semantic results stay outside compact visible follow-up text and remain available in structured details, execution captures, or artifacts.
 

package/index.ts

@@ -14,7 +14,7 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     runtime.discoverResources(import.meta.url),
   );
   pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
-  pi.on("agent_end", async (_event, ctx) => runtime.onAgentEnd(ctx));
+  pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
   pi.on("session_shutdown", async (event, ctx) =>
     runtime.onSessionShutdown(event.reason, ctx),
   );

package/lib/extension-runtime.ts

@@ -25,7 +25,7 @@ export interface ActorExtensionRuntime {
   ): { systemPrompt: string };
   discoverResources(metaUrl: string): { skillPaths: string[] } | undefined;
   getRunOwnerId(ctx: Pi.ExtensionContext): string;
-  onAgentEnd(ctx: Pi.ExtensionContext): void;
+  onAgentSettled(ctx: Pi.ExtensionContext): void;
   onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
   onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;
   registerCoreTools(): void;
@@ -141,7 +141,7 @@ export function createActorExtensionRuntime(
       return skillPaths.length > 0 ? { skillPaths } : undefined;
     },
     getRunOwnerId,
-    onAgentEnd(ctx) {
+    onAgentSettled(ctx) {
       if (activeRunContext === ctx) automaticReview.schedule();
     },
     onSessionShutdown(reason, ctx) {

package/lib/observability.ts

@@ -206,9 +206,9 @@ export function reconcileRunTerminalNotifications(input: {
     includeAttention: input.includeAttention,
     stateRoot: input.stateRoot,
   });
+  deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
   if (input.includeAttention)
     deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
-  deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
   pruneRunUiObservationState(input.state, snapshot);
   return snapshot;
 }
@@ -1193,6 +1193,7 @@ export function getRunAttentionNotificationType(
 }
 
 export function shouldNotifyRunAttentionEvent(event: RunAttentionEvent): boolean {
+  if (event.kind === "command.done") return false;
   return event.attention === "notify" || event.attention === "followup";
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -66,8 +66,8 @@
     "image": "https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
+    "@earendil-works/pi-tui": ">=0.84.4"
   },
   "devDependencies": {
     "@types/node": "latest",

package/scripts/async-runner.mjs

@@ -284,9 +284,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       complete_allowed: missing.length === 0,
     };
   }
-  function getCommandDoneDelivery(result) {
-    return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
-  }
   function progressRunning() {
     progress("running", {
       activeSubagents,
@@ -433,21 +430,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
         ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
       });
     }
-    event("command.done", {
-      activeSubagents,
-      command_id: commandId,
-      code: result.code,
-      command: commandDetail,
-      killed: result.killed,
-      ...captureDetails(result),
-      ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
-      ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
-      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
-      ...(commandSessionFiles(session.sessionDir).length > 0
-        ? { session_files: commandSessionFiles(session.sessionDir) }
-        : {}),
-      ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
-    });
     observation(
       "command.done",
       `Command ${summarizeCommandDetail(commandDetail)} completed with code ${result.code}`,
@@ -462,9 +444,13 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
         ...captureDetails(result),
         ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
         ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+        ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
+        ...(commandSessionFiles(session.sessionDir).length > 0
+          ? { session_files: commandSessionFiles(session.sessionDir) }
+          : {}),
         ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
       },
-      getCommandDoneDelivery(result),
+      "log",
       result.code === 0 ? "info" : "error",
     );
     progressRunning();