@llblab/pi-actors 0.53.2 → 0.55.0

package/AGENTS.md

@@ -26,6 +26,8 @@ Public Run verbs remain `spawn`, `message`, and `inspect`.
 
 ## Core Structure
 
+Require Pi ≥1.0.0 for all declared Pi peers. Keep source and packed lifecycle tests aligned with that baseline; do not restore an older host floor independently of those checks. Validation fixtures must use temporary agent directories, never write into the operator's live Recipe registry.
+
 ```text
 Pi host
   -> index.ts                         composition root
@@ -138,7 +140,9 @@ Tool result/error text contributes exactly one leading line break. Keep model-fa
 
 File watchers accelerate reconciliation; a bounded interval recovers missed terminal and retained-attention events. Canonical attention observation uses stable retained ids and bounds seen memory to the current suffix across compaction; only allowlisted legacy outbox fallback uses line offsets. Ordinary `notify` and `followup` hints prime at startup without replay and require durable state or artifacts for recovery. Explicit `steer` instead re-enters through the owner journal until exact presentation records its newer generation-fenced Trace marker.
 
-Ordinary terminals retain inherited delivery lineage from each nested Actor process to the top-level coordinator. Only that root coordinator may schedule completion follow-ups; descendant sessions stay quiet, descendants wait for their containing top-level Run to terminate, and the complete ready forest is flattened into one immutable settled/idle batch with parent-child rows and bounded semantic outputs. The same batch renders as one visible operator card and one model prompt. Batch delivery is generation-fenced and bounded at 256 durable members, 64 model-facing rows, 16 KiB of context, and a 1 MiB journal. Successful `sendMessage()` acceptance durably finalizes the completion batch and authorizes exact-generation handled markers, so a missed context callback cannot block later completion epochs. Send failure retains the pending batch for retry; queued recovery remains only for the narrow crash boundary between transport acceptance and finalization. Restart recovery walks the bounded active Pi session parent chain: exact queued evidence waits without resend, proven absence returns the envelope to pending, and incomplete or conflicting evidence remains queued with diagnostics. Retry duplicates collapse before presentation, malformed envelopes fail closed, and automatic review waits behind an active completion batch.
+Ordinary terminals retain inherited delivery lineage from each nested Actor process to the top-level coordinator. Only that root coordinator schedules completion delivery; descendant sessions stay quiet and wait for their complete containing top-level tree. A completed active `turn_end` snapshots the ready forest into one immutable batch, preserves earlier boundary entries, and returns one visible custom-message entry plus one continuation, never a native steering/follow-up enqueue. Aborted/error boundaries and pending native input defer projection. Already-idle Pi retains debounced follow-up delivery. The same batch renders as one operator card and one model prompt, fenced by owner and generation and bounded at 256 durable members, 64 model-facing rows, 16 KiB of context, and a 1 MiB journal.
+
+Returning a boundary draft is not acceptance: keep it pending until exact model context or bounded active-session parent-chain evidence proves the committed entry. Successful idle `sendMessage()` acceptance finalizes immediately; durable queued phase also proves acceptance. Only proven absence permits retry; incomplete or conflicting pending evidence stays pending with diagnostics. Exact acceptance authorizes generation-fenced terminal handled markers and releases later epochs without depending on one context callback. Retry duplicates collapse before presentation, malformed envelopes fail closed, and automatic review waits behind an active completion batch.
 
 When deferred Run results gate the next step, wait for their completion batch. Inspect early only for operator request, meaningful attention, or diagnosis of an overdue Run.
 

package/CHANGELOG.md

@@ -2,7 +2,14 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
-## Unreleased
+## 0.55.0: Active Completion Overlays
+
+- `Active Completion Overlays`: Batches ready Actor trees at the next completed model-step boundary, after the full tool batch, so the running coordinator receives fresh results before idle without native steering. Preserves prior boundary entries, exact owner/generation fences, and debounced idle wakeups. Proposed entries remain pending until exact context or bounded session evidence proves acceptance; dropped proposals retry without premature handled markers or duplicate accepted reports.
+
+## 0.54.0: Pi 1.0 Baseline and Package Licensing
+
+- `Licensing`: Includes the MIT LICENSE in source checkouts and npm packages, preserving existing author attribution.
+- `Pi Baseline`: Requires Pi 1.0.0 or newer for both coding-agent and TUI peers. Source and installed-package lifecycle checks use the same baseline; runtime ownership, Recipe/Run semantics and persistent registries are unchanged. Stored-tool normalization tests now use a temporary agent registry rather than writing fixtures into the operator's home.
 
 ## 0.53.2: Stable Inspector Trace Sequences
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llblab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,11 +15,11 @@ An **actor** is any runnable local capability: a script, tool, service, pipeline
 
 Multi-instance systems commonly put instance creation and routing in an external gateway. pi-actors supports a different topology: the current Pi instance remains the coordinator, companion extensions such as Telegram provide presence, and explicit Runs perform bounded delegated work. The coordinator receives high-level outcomes, decomposes them, stays available for decisions, and owns integration plus final validation instead of becoming another undifferentiated worker.
 
-This topology does not require every task to become a subagent. Short work with one natural validation boundary stays inline; delegation pays when clean context, asynchronous execution, independent judgement, parallel ownership, or coordinator availability exceeds its coordination cost. Bounded implementation can run with reasoning off while the coordinator selectively launches clean-context reasoning-enabled reviewers; several independent reviews can provide broader evidence than one author self-review. Settled completion batches, durable Trace, and declared artifacts replace tight polling loops.
+This topology does not require every task to become a subagent. Short work with one natural validation boundary stays inline; delegation pays when clean context, asynchronous execution, independent judgement, parallel ownership, or coordinator availability exceeds its coordination cost. Bounded implementation can run with reasoning off while the coordinator selectively launches clean-context reasoning-enabled reviewers; several independent reviews can provide broader evidence than one author self-review. Boundary-delivered completion batches, durable Trace, and declared artifacts replace tight polling loops.
 
 ## Install
 
-Requires Node.js 22.19.0 or newer and Pi 0.84.4 or newer.
+Requires Node.js 22.19.0 or newer and Pi 1.0.0 or newer.
 
 ```bash
 pi install npm:@llblab/pi-actors
@@ -153,7 +153,7 @@ Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `lev
 
 Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve completion and execution evidence but never request or project attention, including malformed legacy records carrying `steer`. There is no Recipe-level command-completion delivery switch. Semantic attention is explicit: `notify` shows visible status without a model turn, `followup` supplies ordinary checkpoint context, and `steer` requests urgent delivery at Pi's next safe assistant/tool boundary. `notify` and `followup` remain retained wake hints that may compact away, so persist recovery state or an artifact first. `steer` is admitted to the bounded owner delivery journal before `deliverAs: "steer"`, acknowledged only in exact model-bound context, and never suppresses the eventual root-terminal batch. Store large evidence in artifacts or bounded execution captures.
 
-Ordinary finite Runs project terminal results through one root-coordinator completion scheduler. Nested actors inherit durable parent-generation lineage: their own Pi sessions never emit completion turns, their results wait until the containing top-level Run terminates, and the ready trees join other top-level completions accumulated during the same active/idle epoch. One immutable bounded forest causes one automatic agent turn after the root Pi settles. The operator sees one gray completion card, while the agent receives the same parent-child tree with bounded actor outputs as one prompt; terminal generations are acknowledged after Pi durably accepts the exact batch, preventing one missed context callback from blocking later completion epochs. Sequence, parallel, repeat, and imported branches remain internal, while separately launched Runs retain exact independent generations. Silent Runs and synchronous stop acknowledgments remain non-projecting.
+Ordinary finite Runs project terminal results through one root-coordinator completion scheduler. Nested actors inherit durable parent-generation lineage: their own Pi sessions never emit completion turns, and their results wait for the complete containing top-level tree. While the root Pi is active, the next completed `turn_end` boundary snapshots all ready trees into one immutable bounded batch, appends one visible custom message after the full tool batch, and requests one next model step. This overlay uses boundary entries, not Pi's native steering or follow-up queue, so the model can integrate fresh results before its current run settles. Already-idle Pi retains a short debounce and one automatic follow-up wake. The operator and model receive the same parent-child tree with bounded actor outputs. Proposed boundary entries stay pending until exact model context or bounded active-session evidence proves acceptance; an idle send finalizes on successful Pi acceptance without requiring a later context callback. Sequence, parallel, repeat, and imported branches remain internal, while separately launched Runs retain exact independent generations. Silent Runs and synchronous stop acknowledgments remain non-projecting.
 
 ## Control
 

package/dist/index.js

@@ -12,6 +12,7 @@ export default function toolRegistryExtension(pi) {
         pi.on("resources_discover", async () => runtime.discoverResources(import.meta.url));
     }
     pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
+    pi.on("turn_end", (event, ctx) => runtime.onTurnEnd(event, ctx));
     pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
     pi.on("context", async (event, ctx) => ({
         messages: runtime.onContext(event.messages, ctx),

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

@@ -14,6 +14,7 @@ export interface ActorExtensionRuntime {
     } | undefined;
     getRunOwnerId(ctx: Pi.ExtensionContext): string;
     onAgentSettled(ctx: Pi.ExtensionContext): void;
+    onTurnEnd(event: Pi.TurnEndEvent, ctx: Pi.ExtensionContext): Pi.TurnEndEventResult | undefined;
     onContext(messages: unknown[], ctx: Pi.ExtensionContext): unknown[];
     onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
     onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;

package/dist/lib/extension-runtime.js

@@ -118,6 +118,9 @@ export function createActorExtensionRuntime(pi) {
             if (!runUiRuntime.flushCompletionBatch(ctx))
                 automaticReview.schedule();
         },
+        onTurnEnd(event, ctx) {
+            return runUiRuntime.onTurnEnd(event, ctx);
+        },
         onContext(messages, ctx) {
             return runUiRuntime.projectContext(messages, ctx);
         },

package/dist/lib/pi.d.ts

@@ -3,9 +3,9 @@
  * Zones: pi agent sdk boundary, extension host adapters
  * Owns direct pi SDK imports and exposes narrow pi-actors-facing helpers/types for the composition root.
  */
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, CustomMessageEntryDraft, TurnEndEvent, TurnEndEventResult } from "@earendil-works/pi-coding-agent";
 import * as SessionEvidence from "./session-evidence.ts";
-export type { ExtensionAPI, ExtensionContext };
+export type { ExtensionAPI, ExtensionContext, TurnEndEvent, TurnEndEventResult };
 export declare const RUN_COMPLETION_BATCH_CUSTOM_TYPE = "pi-actors-run-batch";
 export declare const RUN_STEER_CUSTOM_TYPE = "pi-actors-run-steer";
 export interface PiNotificationSink {
@@ -19,6 +19,7 @@ export interface PiNotificationSink {
 }
 export declare function getSessionId(ctx: ExtensionContext): string;
 export declare function createNotificationSink(pi: ExtensionAPI, ctx: ExtensionContext): PiNotificationSink;
+export declare function createRunCompletionBatchEntry(batchId: string, content: string): CustomMessageEntryDraft;
 export declare function sendRunCompletionBatch(pi: ExtensionAPI, batchId: string, content: string): void;
 export declare function sendRunSteer(pi: ExtensionAPI, input: {
     content: string;
@@ -41,6 +42,10 @@ export declare function dedupeRunSteerContext(messages: unknown[]): {
     }>;
 };
 export declare function removeRunSteerFromContext(messages: unknown[], steerId: string): unknown[];
+export declare function inspectRunCompletionBatchSessionEvidence(ctx: ExtensionContext, input: {
+    batchId: string;
+    content: string;
+}): SessionEvidence.ActiveSessionEntryEvidence;
 export declare function inspectRunSteerSessionEvidence(ctx: ExtensionContext, input: {
     content: string;
     eventId: string;

package/dist/lib/pi.js

@@ -18,8 +18,9 @@ export function createNotificationSink(pi, ctx) {
         }),
     };
 }
-export function sendRunCompletionBatch(pi, batchId, content) {
-    pi.sendMessage({
+export function createRunCompletionBatchEntry(batchId, content) {
+    return {
+        type: "custom_message",
         customType: RUN_COMPLETION_BATCH_CUSTOM_TYPE,
         content,
         display: true,
@@ -29,10 +30,11 @@ export function sendRunCompletionBatch(pi, batchId, content) {
                 kind: "completion_batch",
             },
         },
-    }, {
-        deliverAs: "followUp",
-        triggerTurn: true,
-    });
+    };
+}
+export function sendRunCompletionBatch(pi, batchId, content) {
+    const { type: _type, ...message } = createRunCompletionBatchEntry(batchId, content);
+    pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 }
 export function sendRunSteer(pi, input) {
     pi.sendMessage({
@@ -172,6 +174,18 @@ export function dedupeRunSteerContext(messages) {
 export function removeRunSteerFromContext(messages, steerId) {
     return messages.filter((message) => steerMessage(message)?.steerId !== steerId);
 }
+export function inspectRunCompletionBatchSessionEvidence(ctx, input) {
+    return SessionEvidence.inspectBoundedActiveSessionEntries({
+        getEntry: (id) => ctx.sessionManager.getEntry(id),
+        leaf: ctx.sessionManager.getLeafEntry(),
+        match: (entry) => {
+            const batch = completionBatchMessage(entry);
+            if (!batch || batch.batchId !== input.batchId)
+                return undefined;
+            return batch.content === input.content ? "present" : "conflict";
+        },
+    });
+}
 export function inspectRunSteerSessionEvidence(ctx, input) {
     return SessionEvidence.inspectBoundedActiveSessionEntries({
         getEntry: (id) => ctx.sessionManager.getEntry(id),

package/dist/lib/run-ui-runtime.d.ts

@@ -9,6 +9,7 @@ import * as Pi from "./pi.ts";
 export interface RunUiRuntime {
     close(): void;
     flushCompletionBatch(ctx: Pi.ExtensionContext): boolean;
+    onTurnEnd(event: Pi.TurnEndEvent, ctx: Pi.ExtensionContext): Pi.TurnEndEventResult | undefined;
     projectContext(messages: unknown[], ctx: Pi.ExtensionContext): unknown[];
     shutdown(eventReason: string, ownerId: string | undefined, ctx?: Pi.ExtensionContext): void;
     start(ctx: Pi.ExtensionContext, ownerId: string): void;

package/dist/lib/run-ui-runtime.js

@@ -23,6 +23,7 @@ export function createRunUiRuntime(deps) {
     const deliveryObservation = Observability.createRunUiObservationState();
     const retirementAttempts = new Set();
     const steerDiagnostics = new Set();
+    const completionDiagnostics = new Set();
     const close = () => {
         running = false;
         activeContext = undefined;
@@ -47,6 +48,7 @@ export function createRunUiRuntime(deps) {
         deliveryTimeout = undefined;
         recoverQueuedSteers = false;
         steerDiagnostics.clear();
+        completionDiagnostics.clear();
         if (animationInterval)
             clearInterval(animationInterval);
         animationInterval = undefined;
@@ -185,6 +187,57 @@ export function createRunUiRuntime(deps) {
         });
         return true;
     };
+    const acceptCompletionBatch = (ownerId, batchId) => {
+        const input = { batchId, ownerId, tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir };
+        if (!RunDelivery.markRunCompletionBatchQueued(input))
+            return false;
+        if (!RunDelivery.markRunCompletionBatchPresented(input))
+            return false;
+        const accepted = journal(ownerId).completion_batch;
+        return accepted ? finishPresentedBatch(ownerId, accepted) : false;
+    };
+    const reconcileCompletionBatch = (ctx, ownerId) => {
+        const batch = journal(ownerId).completion_batch;
+        if (!batch)
+            return false;
+        if (batch.phase === "pending") {
+            // Returning boundary drafts is not acceptance: prove the exact entry before acknowledging it.
+            const evidence = Pi.inspectRunCompletionBatchSessionEvidence(ctx, {
+                batchId: batch.batch_id,
+                content: RunDelivery.formatRunCompletionBatchMessage(batch),
+            });
+            if (evidence.status === "absent")
+                return false;
+            if (evidence.status !== "present") {
+                const key = `${batch.batch_id}:${evidence.status}:${evidence.reason ?? ""}`;
+                if (!completionDiagnostics.has(key)) {
+                    completionDiagnostics.add(key);
+                    ctx.ui.notify(`Actor completion recovery is ${evidence.status}: ${evidence.reason ?? "conflicting session evidence"}. Batch ${batch.batch_id} remains pending.`, "warning");
+                }
+                return true;
+            }
+        }
+        return !acceptCompletionBatch(ownerId, batch.batch_id);
+    };
+    const pendingCompletionBatch = (ownerId) => {
+        const existing = journal(ownerId).completion_batch;
+        if (existing)
+            return existing;
+        const snapshot = Observability.readRunDeliverySnapshot(deliveryObservation, ownerId);
+        admitCompletionTransitions(ownerId, snapshot);
+        Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
+        return journal(ownerId).completion_batch;
+    };
+    const isCurrentOwner = (ctx) => {
+        if (!running || !activeOwnerId)
+            return false;
+        try {
+            return Pi.getSessionId(ctx) === activeOwnerId;
+        }
+        catch {
+            return false;
+        }
+    };
     const isIdle = (ctx) => typeof ctx.isIdle !== "function" || ctx.isIdle();
     const isDeliveryRoot = (ownerId) => {
         const inheritedOwner = RunDeliveryLineage.getProcessDeliveryOwnerId();
@@ -344,52 +397,20 @@ export function createRunUiRuntime(deps) {
     });
     flushCompletionBatch = (ctx) => {
         const ownerId = activeOwnerId;
-        if (!running || !ownerId)
+        if (!ownerId || !isCurrentOwner(ctx))
             return false;
-        try {
-            if (Pi.getSessionId(ctx) !== ownerId)
-                return false;
-        }
-        catch {
-            return false;
-        }
         if (flushSteers(ctx, ownerId))
             return true;
         if (!isDeliveryRoot(ownerId))
             return false;
-        let batch = journal(ownerId).completion_batch;
-        if (!batch) {
-            const snapshot = Observability.readRunDeliverySnapshot(deliveryObservation, ownerId);
-            admitCompletionTransitions(ownerId, snapshot);
-            Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
-            batch = journal(ownerId).completion_batch;
-        }
+        if (reconcileCompletionBatch(ctx, ownerId))
+            return true;
+        const batch = pendingCompletionBatch(ownerId);
         if (!batch)
             return false;
-        if (batch.phase === "presented") {
-            finishPresentedBatch(ownerId, batch);
-            const snapshot = Observability.readRunDeliverySnapshot(deliveryObservation, ownerId);
-            admitCompletionTransitions(ownerId, snapshot);
-            Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
-            batch = journal(ownerId).completion_batch;
-            if (!batch)
-                return false;
-        }
         if (!isIdle(ctx))
             return true;
         const content = RunDelivery.formatRunCompletionBatchMessage(batch);
-        if (batch.phase === "queued") {
-            if (!RunDelivery.markRunCompletionBatchPresented({
-                batchId: batch.batch_id,
-                ownerId,
-                tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-            }))
-                return true;
-            const accepted = journal(ownerId).completion_batch;
-            if (accepted)
-                finishPresentedBatch(ownerId, accepted);
-            return flushCompletionBatch(ctx);
-        }
         if (!isIdle(ctx))
             return true;
         try {
@@ -404,40 +425,33 @@ export function createRunUiRuntime(deps) {
             });
             throw error;
         }
-        if (!RunDelivery.markRunCompletionBatchQueued({
-            batchId: batch.batch_id,
-            ownerId,
-            tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-        })) {
-            throw new Error("Completion batch changed before queue acknowledgment");
-        }
-        if (!RunDelivery.markRunCompletionBatchPresented({
-            batchId: batch.batch_id,
-            ownerId,
-            tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-        })) {
+        if (!acceptCompletionBatch(ownerId, batch.batch_id)) {
             throw new Error("Completion batch changed before durable acceptance");
         }
-        const accepted = journal(ownerId).completion_batch;
-        if (accepted)
-            finishPresentedBatch(ownerId, accepted);
         ctx.ui.notify(`Actor completions ready: ${batch.members.length}`, "info");
         return true;
     };
     return {
         close,
         flushCompletionBatch,
+        onTurnEnd(event, ctx) {
+            const ownerId = activeOwnerId;
+            if (!ownerId || !isCurrentOwner(ctx) || !isDeliveryRoot(ownerId) ||
+                event.outcome !== "completed" || isIdle(ctx) || ctx.signal?.aborted ||
+                ctx.hasPendingMessages?.() || event.context.pendingMessages.length > 0)
+                return undefined;
+            if (flushSteers(ctx, ownerId) || reconcileCompletionBatch(ctx, ownerId))
+                return undefined;
+            const batch = pendingCompletionBatch(ownerId);
+            if (!batch)
+                return undefined;
+            const entry = Pi.createRunCompletionBatchEntry(batch.batch_id, RunDelivery.formatRunCompletionBatchMessage(batch));
+            return { entries: [...event.entries, entry], continue: true };
+        },
         projectContext(messages, ctx) {
             const ownerId = activeOwnerId;
-            if (!running || !ownerId)
-                return messages;
-            try {
-                if (Pi.getSessionId(ctx) !== ownerId)
-                    return messages;
-            }
-            catch {
+            if (!ownerId || !isCurrentOwner(ctx))
                 return messages;
-            }
             const steerContext = Pi.dedupeRunSteerContext(messages);
             let contextMessages = steerContext.messages;
             for (const steer of journal(ownerId).steers) {
@@ -472,21 +486,7 @@ export function createRunUiRuntime(deps) {
             if (content !== RunDelivery.formatRunCompletionBatchMessage(batch)) {
                 return Pi.removeRunCompletionBatchFromContext(projected.messages, batch.batch_id);
             }
-            if (!RunDelivery.markRunCompletionBatchQueued({
-                batchId: batch.batch_id,
-                ownerId,
-                tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-            }))
-                return projected.messages;
-            if (!RunDelivery.markRunCompletionBatchPresented({
-                batchId: batch.batch_id,
-                ownerId,
-                tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-            }))
-                return projected.messages;
-            const presented = journal(ownerId).completion_batch;
-            if (presented)
-                finishPresentedBatch(ownerId, presented);
+            acceptCompletionBatch(ownerId, batch.batch_id);
             return projected.messages;
         },
         shutdown(eventReason, ownerId, ctx) {

package/dist/skills/actors/SKILL.md

@@ -107,7 +107,7 @@ Run = Recipe + Trace + Control
 ```
 
 1. Spawn with the exact logical Recipe identity and caller-owned values.
-2. Retain the returned `run:<id>` and normally wait for the root coordinator's settled completion batch instead of polling. Nested actor completions accumulate under their containing top-level Run and arrive in that one tree-compressed batch; descendant sessions do not need notification options.
+2. Retain the returned `run:<id>` and normally wait for the root coordinator's completion batch instead of polling. While Pi is active, ready results arrive together at the next safe model-step boundary after the full tool batch; already-idle Pi wakes through a debounced follow-up. Nested actor completions wait for their complete containing top-level tree and arrive in that one compressed batch; descendant sessions do not need notification options.
 3. Inspect `view=trace` when retained observations or attention matter.
 4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
 5. Send `message` only for an action declared and consumed by that controlled Recipe.

package/dist/skills/actors/references/runs.md

@@ -14,7 +14,7 @@ A rare Skill Recipe may declare `singleton: true`. Do not pass `as`: the runtime
 
 ## Observe
 
-Normally wait for the settled completion batch. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
+Normally wait for the completion batch: ready trees reach an active root coordinator at the next safe model-step boundary after the full tool batch, or wake an already-idle coordinator through a debounced follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
 
 ```text
 inspect target=run:<id> view=recipe

package/docs/README.md

@@ -7,7 +7,7 @@ Living index of all documentation in the `/docs` directory.
 - [command-templates.md](./command-templates.md) — Portable synchronous command execution standard
 - [template-recipes.md](./template-recipes.md) — Saved JSON/Markdown recipe standard, imports, and reusable command-template graph composition
 - [async-runs.md](./async-runs.md) — Run lifecycle, state, Control, Trace, cancellation, and terminal reconciliation
-- [coordinator-delivery.md](./coordinator-delivery.md) — Accepted next-minor design for durable terminal batching and explicit urgent Pi steering
+- [coordinator-delivery.md](./coordinator-delivery.md) — Active model-step completion overlays, idle batching, durable acceptance, and explicit urgent Pi steering
 - [actor-inspector.md](./actor-inspector.md) — Owner-filtered actor-instance navigation through Recipe, Trace, and Control
 - [inspection.md](./inspection.md) — Complete `inspect` target/view matrix, authorization boundaries, and diagnostic routes
 - [tool-registry.md](./tool-registry.md) — Local `pi-actors` registry storage and `register_tool` adaptation

package/docs/async-runs.md

@@ -110,7 +110,9 @@ Statuses include `running`, `done`, `failed`, `exited`, `cancelled`, and `killed
 
 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.
 
-Ordinary finite Runs project terminal results through one root-coordinator completion scheduler. Every detached runner passes its delivery-root owner and exact parent Run generation to nested actor processes. A descendant terminal remains authoritative but ineligible until its containing top-level Run is terminal; descendant Pi sessions never schedule completion follow-ups. After `agent_settled`, session recovery, or an idle debounce, the root scheduler snapshots the ready trees plus concurrently completed top-level Runs into one owner-fenced immutable batch of at most 256 exact generations. One batch causes one automatic agent turn, renders one visible gray operator card, exposes at most 64 bounded parent-child rows with semantic outputs to the model, and marks member terminals handled after Pi durably accepts the exact batch. Pending send failures retain bounded retry evidence. The narrow crash boundary between acceptance and finalization remains recoverable from bounded active-session evidence, but normal hot delivery never waits on a later context callback and therefore cannot block subsequent epochs. Duplicate exact context envelopes collapse before presentation.
+Ordinary finite Runs project terminal results through one root-coordinator completion scheduler. Every detached runner passes its delivery-root owner and exact parent Run generation to nested actor processes. A descendant terminal remains authoritative but ineligible until its complete containing top-level tree is terminal; descendant Pi sessions never schedule completion delivery. At an active completed `turn_end`, the root scheduler snapshots all ready trees into one owner-fenced immutable batch of at most 256 exact generations, preserves preceding boundary entries, and returns one visible `custom_message` plus `continue: true`. The full tool batch finishes before insertion, and the next model request receives fresh results within the same agent run without using native steering or follow-up queues. Aborted/error boundaries and pending native input defer insertion. Already-idle Pi still wakes through `agent_settled`, session recovery, or a short idle debounce. One batch renders one gray operator card and exposes at most 64 bounded parent-child rows with semantic outputs.
+
+Boundary proposals remain pending until exact model context or bounded active-session evidence proves the entry was committed; returning a draft never marks member terminals handled. An idle send finalizes immediately on Pi acceptance, and durable queued phase also proves acceptance. Recovery retries a pending batch only after proving absence from the bounded active session chain; incomplete or conflicting evidence stays pending with diagnostics. Exact acceptance marks the member generations handled and releases the next epoch without depending on one later context callback. Pending send failures retain bounded retry evidence. Duplicate exact context envelopes collapse before presentation. See [Coordinator Delivery](./coordinator-delivery.md) for scheduling and recovery details.
 
 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 and synchronously acknowledged stop outcomes suppress automatic projection. Large semantic results stay outside compact completion rows and remain available in structured details, execution captures, or artifacts.
 

package/docs/coordinator-delivery.md

@@ -8,10 +8,10 @@ Separate durable Run completion truth from the scheduling of model turns:
 
 ```text
 one Run generation -> one terminal record with inherited tree lineage
-one ready completion forest per bounded epoch -> one root-coordinator turn
+one ready completion forest per bounded epoch -> one root-coordinator model step
 ```
 
-Ordinary terminals accumulate across nested actor sessions while Pi is active. Descendants wait for their containing top-level Run, then all ready trees and concurrently completed top-level Runs reach only the root coordinator in one bounded batch after Pi settles. Only an explicitly actor-authored urgent semantic checkpoint may steer an active agent loop.
+Ordinary terminals accumulate across nested actor sessions. Descendants wait for their complete containing top-level tree, then all ready trees and concurrently completed top-level Runs reach only the root coordinator in one bounded batch. During active work, a public `turn_end` overlay supplies fresh results to the next model request after the full tool batch, without waiting for idle or using native steering. Already-idle Pi retains debounced follow-up wakeups. Explicit actor-authored urgent semantic checkpoints remain a separate native-steer delivery class.
 
 ## Non-Goals
 
@@ -27,7 +27,7 @@ Ordinary terminals accumulate across nested actor sessions while Pi is active. D
 - `attention: "notify"` remains visible UI status without a model turn.
 - `attention: "followup"` retains its existing explicit semantic follow-up behavior.
 - New `attention: "steer"` requests urgent semantic delivery at Pi's next safe assistant/tool boundary.
-- Terminal transitions inherit exact parent-generation and root-owner lineage; only the root session batches ready completion trees instead of sending one follow-up per Run or descendant session.
+- Terminal transitions inherit exact parent-generation and root-owner lineage; only the root session batches ready completion trees into a model-step overlay or an already-idle follow-up, never one turn per Run or descendant session.
 
 `command.done` remains non-projectable even if malformed or legacy Trace attaches any attention value.
 
@@ -37,7 +37,7 @@ Ordinary terminals accumulate across nested actor sessions while Pi is active. D
 - `runs-trace.ts` owns admission of the new `steer` attention value.
 - `observability.ts` discovers terminal candidates and explicit semantic attention without deciding Pi delivery timing.
 - A new `run-delivery.ts` domain owns the owner-scoped delivery journal, batch construction, bounds, phases, formatting, recovery, and acknowledgments.
-- `run-ui-runtime.ts` owns idle detection, debounce, reconciliation, flushing, and stale-context containment.
+- `run-ui-runtime.ts` owns active model-step boundaries, idle detection, debounce, reconciliation, flushing, and stale-context containment.
 - `extension-runtime.ts` orders completion flushes before automatic Recipe review.
 - `index.ts` remains a thin registration root and adds only the required Pi lifecycle adapter.
 - `pi.ts` exposes narrow ports for batched follow-up and urgent steer delivery.
@@ -75,13 +75,13 @@ Completion batch shape:
 
 Phases are monotonic:
 
-1. `pending`: The exact member snapshot is durable but no Pi message has been accepted.
+1. `pending`: The exact member snapshot is durable but Pi acceptance is unproven. Returning a boundary draft does not advance this phase.
 2. `queued`: Pi accepted a custom message carrying the exact batch or steer ID.
-3. `presented`: A Pi `context` event observed that ID in messages being supplied to an LLM call.
+3. `presented`: Exact completion acceptance is proven, or a Pi `context` event observed the urgent-steer ID in messages being supplied to an LLM call.
 
 Every journal mutation uses the canonical token-owned lock, expected-phase fencing, owner and generation validation, and atomic replacement. Repeated transitions are idempotent. Corrupt, oversized, foreign-owner, or stale-generation state fails closed with bounded diagnostics.
 
-Completion and steer acknowledgments intentionally differ. Successful `sendMessage()` acceptance finalizes an ordinary completion batch immediately and marks its members through the existing terminal-handled authority; this prevents a missed context callback from blocking every later epoch. Urgent steer still requires exact model-context presentation. If a completion member was synchronously archived or pruned after queueing, the bounded delivery snapshot remains sufficient and the missing state write becomes a diagnostic rather than invalidating acceptance.
+Completion and steer acknowledgments intentionally differ. An active completion overlay remains pending until exact model context or bounded active-session evidence proves its committed entry. Successful idle `sendMessage()` acceptance finalizes an ordinary completion batch immediately; durable queued phase also proves acceptance. Both paths mark members through the existing terminal-handled authority, so a missed context callback cannot block every later epoch. Urgent steer still requires exact model-context presentation. If a completion member was synchronously archived or pruned after acceptance, the bounded delivery snapshot remains sufficient and the missing state write becomes a diagnostic rather than invalidating acceptance.
 
 ## Completion Collection
 
@@ -97,17 +97,20 @@ It excludes:
 
 Candidates sort by terminal timestamp, then stable Run identity, then `run_instance_id`. Replacement generations with the same logical Run id remain distinct internal members.
 
-While `ctx.isIdle()` is false, candidates remain durable in their Run state and no terminal follow-up is sent. A flush snapshots eligible candidates into one immutable batch. While transport acceptance is pending, newer terminals stay unhandled for the next bounded completion epoch.
+While Pi is active, candidates remain durable until the next completed `turn_end`; watchers do not enqueue ordinary terminal follow-ups into the native message queue. The boundary itself reads current Run state, so a missed watcher cannot make the next step stale. A flush snapshots eligible candidates into one immutable batch. While acceptance is pending, newer terminals stay unhandled for the next bounded completion epoch.
 
 ## Batch Flush
 
 Flush one batch when:
 
-1. `agent_settled` fires for the still-active context and `ctx.isIdle()` remains true;
-2. terminals arrive while Pi is already idle and survive one short debounce window;
-3. session restoration discovers unhandled terminal generations or recoverable queued delivery state.
+1. A completed active `turn_end` reaches the exact root owner without an aborted signal or native pending input;
+2. `agent_settled` fires for the still-active owner and `ctx.isIdle()` remains true;
+3. Terminals arrive while Pi is already idle and survive the 100 ms default debounce window;
+4. Session restoration discovers unhandled terminal generations or recoverable delivery state.
 
-The custom message uses `customType: "pi-actors-run-batch"`, `display: true`, `deliverAs: "followUp"`, and `triggerTurn: true`. It restores the visible gray completion card for the operator while supplying the same single tree-compressed prompt to the model. The bounded content retains the exact batch identity for session evidence and deduplication even though Pi omits private message details from model context. It includes:
+Active delivery returns `{ entries: [...event.entries, entry], continue: true }`, where `entry` is one `custom_message` with `customType: "pi-actors-run-batch"` and `display: true`. It preserves previous extensions' boundary entries and requests one next model step in the same agent run after the entire tool batch. Aborted/error boundaries, queued native input, and outstanding urgent steer defer the overlay. It never uses `sendMessage(..., { deliverAs: "steer" })` or a native follow-up queue for active completion delivery.
+
+Already-idle delivery uses the same custom message with `deliverAs: "followUp"` and `triggerTurn: true` to wake Pi. Both paths render one gray operator card and supply the same tree-compressed prompt to the model. The bounded content retains the exact batch identity for session evidence and deduplication even though Pi omits private message details from model context. It includes:
 
 - batch ID and completion window;
 - counts by terminal status;
@@ -120,14 +123,14 @@ Completion member details remain redacted through existing terminal projection r
 
 ## Acceptance, Presentation, And Recovery
 
-Ordinary completion delivery atomically advances through queued acceptance to finalization immediately after `sendMessage()` returns, marks every still-present member generation terminal-handled, and retains a bounded owner receipt. A `context` lifecycle adapter remains for exact urgent-steer presentation and harmless completion deduplication; presented steer writes `delivery.steer_presented` in the exact Run generation.
+Returning boundary drafts is a proposal, not an SDK receipt. An active completion batch advances through queued acceptance to finalization only when exact model-bound `context` or a bounded active-session parent-chain read proves the committed entry. If another extension replaces or invalidates the proposed draft chain, the absent batch remains pending and can retry with the same identity. Idle delivery advances immediately after `sendMessage()` returns. Acceptance marks every still-present member generation terminal-handled and retains a bounded owner receipt. The `context` lifecycle adapter also deduplicates completion envelopes and handles exact urgent-steer presentation; presented steer writes `delivery.steer_presented` in the exact Run generation.
 
 The generation-fenced Trace marker prevents a retained historical steer from replaying after bounded owner receipts rotate: suffix compaction cannot retain the older steer while discarding its newer presentation marker. Missing, archived, pruned, or replaced Run state needs no marker because it can no longer replay that original generation.
 
 Recovery rules:
 
 - Send failure: keep `pending`, record failure evidence, and retry.
-- Crash after queueing: inspect existing owned Pi session evidence for the exact custom message ID.
+- Pending batch after a boundary attempt or restart: inspect the bounded active Pi session chain for the exact batch ID and content. Proven presence finalizes; proven absence permits retry; incomplete or conflicting evidence stays pending with a diagnostic.
 - Completion send accepted: finalize immediately and release the next epoch.
 - Crash leaves a queued completion: queued itself proves `sendMessage()` acceptance, so finalize without resend or content reformatting.
 - Presented urgent steer: never resend.
@@ -179,24 +182,23 @@ Another extension may start work during `agent_settled`; recheck `ctx.isIdle()`
 
 Implementation is complete only when source and packed-extension tests prove:
 
-1. Multiple Runs finishing during one agent run cause no immediate terminal turns and one settled batch.
+1. Multiple Runs finishing during active work produce one boundary entry and one next model request before idle, after all tools in the current batch finish; no native steering/follow-up enqueue occurs.
 2. Idle completions inside the debounce window form one batch.
 3. Completion/settled races project every generation exactly once.
 4. Send failure and restart before queueing retry without a handled marker.
 5. Restart in the narrow queue-acceptance/finalization boundary neither loses nor duplicates the batch.
-6. Successful completion acceptance acknowledges members atomically and idempotently; urgent steer still requires exact `context` presentation.
+6. Boundary proposals do not acknowledge terminals early. Exact committed-entry evidence or idle send acceptance acknowledges members atomically and idempotently; urgent steer still requires exact `context` presentation.
 7. Replacement generations sharing a Run id remain distinct.
 8. Silent, stopped, cancelled, handled, and foreign-owner Runs remain excluded.
 9. Legacy or malformed `command.done` attention, including `steer`, remains non-projectable.
 10. Explicit steer reaches the next safe Pi boundary once and root terminal still batches later.
 11. Overflow, corruption, journal backpressure, archive/prune races, and stale contexts fail safely.
 12. Completion flushing precedes automatic Recipe review.
-13. Pi 0.84.4 remains the exact minimum source and packed lifecycle baseline.
+13. Pi 1.0.0 is the minimum source and packed lifecycle baseline; coding-agent and TUI peers share that floor.
+14. The packed extension runs through the public SDK with a synthetic provider, proving one batch reaches the next request before settlement for both a full tool batch and a tool-free final answer, while preserving preceding boundary entries.
 
 Focused observability and delivery tests precede TypeScript/build/import checks. The acceptance checkpoint then runs full product validation, dependency audit, package dry-run, and ABCd context validation.
 
-## Rollout
-
-This is one minor release because durable batching, acceptance acknowledgment, lifecycle ordering, and explicit steer share one model-delivery invariant. Completion acceptance must release later epochs without depending on a context callback; steer must not ship before its durable presentation-deduplication path exists.
+## Product Boundaries
 
-Update README and Run documentation only when implementation establishes the new public behavior. Move the accepted outcome from BACKLOG to CHANGELOG only after complete validation.
+Active overlays and idle follow-ups share the same batch identity, bounds, lineage, terminal authority, and acceptance journal. They differ only in the Pi scheduling port and its acceptance evidence. Urgent semantic steer remains independent; completion status never implies urgency. The extension has no dependency on Telegram and does not modify Telegram reply or preview ownership.

package/index.ts

@@ -17,6 +17,7 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     );
   }
   pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
+  pi.on("turn_end", (event, ctx) => runtime.onTurnEnd(event, ctx));
   pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
   pi.on("context", async (event, ctx) => ({
     messages: runtime.onContext(event.messages, ctx) as typeof event.messages,

package/lib/extension-runtime.ts

@@ -26,6 +26,7 @@ export interface ActorExtensionRuntime {
   discoverResources(metaUrl: string): { skillPaths: string[] } | undefined;
   getRunOwnerId(ctx: Pi.ExtensionContext): string;
   onAgentSettled(ctx: Pi.ExtensionContext): void;
+  onTurnEnd(event: Pi.TurnEndEvent, ctx: Pi.ExtensionContext): Pi.TurnEndEventResult | undefined;
   onContext(messages: unknown[], ctx: Pi.ExtensionContext): unknown[];
   onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
   onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;
@@ -146,6 +147,9 @@ export function createActorExtensionRuntime(
       if (!activeRunOwnerId || getRunOwnerId(ctx) !== activeRunOwnerId) return;
       if (!runUiRuntime.flushCompletionBatch(ctx)) automaticReview.schedule();
     },
+    onTurnEnd(event, ctx) {
+      return runUiRuntime.onTurnEnd(event, ctx);
+    },
     onContext(messages, ctx) {
       return runUiRuntime.projectContext(messages, ctx);
     },

package/lib/pi.ts

@@ -7,11 +7,14 @@
 import type {
   ExtensionAPI,
   ExtensionContext,
+  CustomMessageEntryDraft,
+  TurnEndEvent,
+  TurnEndEventResult,
 } from "@earendil-works/pi-coding-agent";
 
 import * as SessionEvidence from "./session-evidence.ts";
 
-export type { ExtensionAPI, ExtensionContext };
+export type { ExtensionAPI, ExtensionContext, TurnEndEvent, TurnEndEventResult };
 
 export const RUN_COMPLETION_BATCH_CUSTOM_TYPE = "pi-actors-run-batch";
 export const RUN_STEER_CUSTOM_TYPE = "pi-actors-run-steer";
@@ -44,12 +47,12 @@ export function createNotificationSink(
   };
 }
 
-export function sendRunCompletionBatch(
-  pi: ExtensionAPI,
+export function createRunCompletionBatchEntry(
   batchId: string,
   content: string,
-): void {
-  pi.sendMessage({
+): CustomMessageEntryDraft {
+  return {
+    type: "custom_message",
     customType: RUN_COMPLETION_BATCH_CUSTOM_TYPE,
     content,
     display: true,
@@ -59,10 +62,16 @@ export function sendRunCompletionBatch(
         kind: "completion_batch",
       },
     },
-  }, {
-    deliverAs: "followUp",
-    triggerTurn: true,
-  });
+  };
+}
+
+export function sendRunCompletionBatch(
+  pi: ExtensionAPI,
+  batchId: string,
+  content: string,
+): void {
+  const { type: _type, ...message } = createRunCompletionBatchEntry(batchId, content);
+  pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 }
 
 export function sendRunSteer(
@@ -219,6 +228,21 @@ export function removeRunSteerFromContext(
   return messages.filter((message) => steerMessage(message)?.steerId !== steerId);
 }
 
+export function inspectRunCompletionBatchSessionEvidence(
+  ctx: ExtensionContext,
+  input: { batchId: string; content: string },
+): SessionEvidence.ActiveSessionEntryEvidence {
+  return SessionEvidence.inspectBoundedActiveSessionEntries({
+    getEntry: (id) => ctx.sessionManager.getEntry(id),
+    leaf: ctx.sessionManager.getLeafEntry(),
+    match: (entry) => {
+      const batch = completionBatchMessage(entry);
+      if (!batch || batch.batchId !== input.batchId) return undefined;
+      return batch.content === input.content ? "present" : "conflict";
+    },
+  });
+}
+
 export function inspectRunSteerSessionEvidence(
   ctx: ExtensionContext,
   input: { content: string; eventId: string; steerId: string },

package/lib/run-ui-runtime.ts

@@ -15,6 +15,7 @@ import * as RunDeliveryLineage from "./run-delivery-lineage.ts";
 export interface RunUiRuntime {
   close(): void;
   flushCompletionBatch(ctx: Pi.ExtensionContext): boolean;
+  onTurnEnd(event: Pi.TurnEndEvent, ctx: Pi.ExtensionContext): Pi.TurnEndEventResult | undefined;
   projectContext(messages: unknown[], ctx: Pi.ExtensionContext): unknown[];
   shutdown(
     eventReason: string,
@@ -51,6 +52,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   const deliveryObservation = Observability.createRunUiObservationState();
   const retirementAttempts = new Set<string>();
   const steerDiagnostics = new Set<string>();
+  const completionDiagnostics = new Set<string>();
 
   const close = (): void => {
     running = false;
@@ -72,6 +74,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     deliveryTimeout = undefined;
     recoverQueuedSteers = false;
     steerDiagnostics.clear();
+    completionDiagnostics.clear();
     if (animationInterval) clearInterval(animationInterval);
     animationInterval = undefined;
   };
@@ -242,6 +245,53 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     });
     return true;
   };
+  const acceptCompletionBatch = (ownerId: string, batchId: string): boolean => {
+    const input = { batchId, ownerId, tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir };
+    if (!RunDelivery.markRunCompletionBatchQueued(input)) return false;
+    if (!RunDelivery.markRunCompletionBatchPresented(input)) return false;
+    const accepted = journal(ownerId).completion_batch;
+    return accepted ? finishPresentedBatch(ownerId, accepted) : false;
+  };
+  const reconcileCompletionBatch = (ctx: Pi.ExtensionContext, ownerId: string): boolean => {
+    const batch = journal(ownerId).completion_batch;
+    if (!batch) return false;
+    if (batch.phase === "pending") {
+      // Returning boundary drafts is not acceptance: prove the exact entry before acknowledging it.
+      const evidence = Pi.inspectRunCompletionBatchSessionEvidence(ctx, {
+        batchId: batch.batch_id,
+        content: RunDelivery.formatRunCompletionBatchMessage(batch),
+      });
+      if (evidence.status === "absent") return false;
+      if (evidence.status !== "present") {
+        const key = `${batch.batch_id}:${evidence.status}:${evidence.reason ?? ""}`;
+        if (!completionDiagnostics.has(key)) {
+          completionDiagnostics.add(key);
+          ctx.ui.notify(
+            `Actor completion recovery is ${evidence.status}: ${evidence.reason ?? "conflicting session evidence"}. Batch ${batch.batch_id} remains pending.`,
+            "warning",
+          );
+        }
+        return true;
+      }
+    }
+    return !acceptCompletionBatch(ownerId, batch.batch_id);
+  };
+  const pendingCompletionBatch = (ownerId: string): RunDelivery.RunCompletionBatch | undefined => {
+    const existing = journal(ownerId).completion_batch;
+    if (existing) return existing;
+    const snapshot = Observability.readRunDeliverySnapshot(deliveryObservation, ownerId);
+    admitCompletionTransitions(ownerId, snapshot);
+    Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
+    return journal(ownerId).completion_batch;
+  };
+  const isCurrentOwner = (ctx: Pi.ExtensionContext): boolean => {
+    if (!running || !activeOwnerId) return false;
+    try {
+      return Pi.getSessionId(ctx) === activeOwnerId;
+    } catch {
+      return false;
+    }
+  };
   const isIdle = (ctx: Pi.ExtensionContext): boolean =>
     typeof ctx.isIdle !== "function" || ctx.isIdle();
   const isDeliveryRoot = (ownerId: string): boolean => {
@@ -422,48 +472,14 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
 
   flushCompletionBatch = (ctx: Pi.ExtensionContext): boolean => {
     const ownerId = activeOwnerId;
-    if (!running || !ownerId) return false;
-    try {
-      if (Pi.getSessionId(ctx) !== ownerId) return false;
-    } catch {
-      return false;
-    }
+    if (!ownerId || !isCurrentOwner(ctx)) return false;
     if (flushSteers(ctx, ownerId)) return true;
     if (!isDeliveryRoot(ownerId)) return false;
-    let batch = journal(ownerId).completion_batch;
-    if (!batch) {
-      const snapshot = Observability.readRunDeliverySnapshot(
-        deliveryObservation,
-        ownerId,
-      );
-      admitCompletionTransitions(ownerId, snapshot);
-      Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
-      batch = journal(ownerId).completion_batch;
-    }
+    if (reconcileCompletionBatch(ctx, ownerId)) return true;
+    const batch = pendingCompletionBatch(ownerId);
     if (!batch) return false;
-    if (batch.phase === "presented") {
-      finishPresentedBatch(ownerId, batch);
-      const snapshot = Observability.readRunDeliverySnapshot(
-        deliveryObservation,
-        ownerId,
-      );
-      admitCompletionTransitions(ownerId, snapshot);
-      Observability.pruneRunUiObservationState(deliveryObservation, snapshot);
-      batch = journal(ownerId).completion_batch;
-      if (!batch) return false;
-    }
     if (!isIdle(ctx)) return true;
     const content = RunDelivery.formatRunCompletionBatchMessage(batch);
-    if (batch.phase === "queued") {
-      if (!RunDelivery.markRunCompletionBatchPresented({
-        batchId: batch.batch_id,
-        ownerId,
-        tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-      })) return true;
-      const accepted = journal(ownerId).completion_batch;
-      if (accepted) finishPresentedBatch(ownerId, accepted);
-      return flushCompletionBatch(ctx);
-    }
     if (!isIdle(ctx)) return true;
     try {
       Pi.sendRunCompletionBatch(deps.pi, batch.batch_id, content);
@@ -476,22 +492,9 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       });
       throw error;
     }
-    if (!RunDelivery.markRunCompletionBatchQueued({
-      batchId: batch.batch_id,
-      ownerId,
-      tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-    })) {
-      throw new Error("Completion batch changed before queue acknowledgment");
-    }
-    if (!RunDelivery.markRunCompletionBatchPresented({
-      batchId: batch.batch_id,
-      ownerId,
-      tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-    })) {
+    if (!acceptCompletionBatch(ownerId, batch.batch_id)) {
       throw new Error("Completion batch changed before durable acceptance");
     }
-    const accepted = journal(ownerId).completion_batch;
-    if (accepted) finishPresentedBatch(ownerId, accepted);
     ctx.ui.notify(
       `Actor completions ready: ${batch.members.length}`,
       "info",
@@ -502,14 +505,25 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   return {
     close,
     flushCompletionBatch,
+    onTurnEnd(event, ctx) {
+      const ownerId = activeOwnerId;
+      if (
+        !ownerId || !isCurrentOwner(ctx) || !isDeliveryRoot(ownerId) ||
+        event.outcome !== "completed" || isIdle(ctx) || ctx.signal?.aborted ||
+        ctx.hasPendingMessages?.() || event.context.pendingMessages.length > 0
+      ) return undefined;
+      if (flushSteers(ctx, ownerId) || reconcileCompletionBatch(ctx, ownerId)) return undefined;
+      const batch = pendingCompletionBatch(ownerId);
+      if (!batch) return undefined;
+      const entry = Pi.createRunCompletionBatchEntry(
+        batch.batch_id,
+        RunDelivery.formatRunCompletionBatchMessage(batch),
+      );
+      return { entries: [...event.entries, entry], continue: true };
+    },
     projectContext(messages, ctx) {
       const ownerId = activeOwnerId;
-      if (!running || !ownerId) return messages;
-      try {
-        if (Pi.getSessionId(ctx) !== ownerId) return messages;
-      } catch {
-        return messages;
-      }
+      if (!ownerId || !isCurrentOwner(ctx)) return messages;
       const steerContext = Pi.dedupeRunSteerContext(messages);
       let contextMessages = steerContext.messages;
       for (const steer of journal(ownerId).steers) {
@@ -549,18 +563,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
           batch.batch_id,
         );
       }
-      if (!RunDelivery.markRunCompletionBatchQueued({
-        batchId: batch.batch_id,
-        ownerId,
-        tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-      })) return projected.messages;
-      if (!RunDelivery.markRunCompletionBatchPresented({
-        batchId: batch.batch_id,
-        ownerId,
-        tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
-      })) return projected.messages;
-      const presented = journal(ownerId).completion_batch;
-      if (presented) finishPresentedBatch(ownerId, presented);
+      acceptCompletionBatch(ownerId, batch.batch_id);
       return projected.messages;
     },
     shutdown(eventReason, ownerId, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.53.2",
+  "version": "0.55.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -38,6 +38,7 @@
     "prepack": "npm run build"
   },
   "files": [
+    "LICENSE",
     "index.ts",
     "dist",
     "lib",
@@ -61,8 +62,8 @@
     "image": "https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.84.4",
-    "@earendil-works/pi-tui": ">=0.84.4"
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0"
   },
   "devDependencies": {
     "@types/node": "latest",

package/skills/actors/SKILL.md

@@ -107,7 +107,7 @@ Run = Recipe + Trace + Control
 ```
 
 1. Spawn with the exact logical Recipe identity and caller-owned values.
-2. Retain the returned `run:<id>` and normally wait for the root coordinator's settled completion batch instead of polling. Nested actor completions accumulate under their containing top-level Run and arrive in that one tree-compressed batch; descendant sessions do not need notification options.
+2. Retain the returned `run:<id>` and normally wait for the root coordinator's completion batch instead of polling. While Pi is active, ready results arrive together at the next safe model-step boundary after the full tool batch; already-idle Pi wakes through a debounced follow-up. Nested actor completions wait for their complete containing top-level tree and arrive in that one compressed batch; descendant sessions do not need notification options.
 3. Inspect `view=trace` when retained observations or attention matter.
 4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
 5. Send `message` only for an action declared and consumed by that controlled Recipe.

package/skills/actors/references/runs.md

@@ -14,7 +14,7 @@ A rare Skill Recipe may declare `singleton: true`. Do not pass `as`: the runtime
 
 ## Observe
 
-Normally wait for the settled completion batch. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
+Normally wait for the completion batch: ready trees reach an active root coordinator at the next safe model-step boundary after the full tool batch, or wake an already-idle coordinator through a debounced follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
 
 ```text
 inspect target=run:<id> view=recipe