@llblab/pi-kit 0.35.5 → 0.36.1

package/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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,12 +182,12 @@ 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.
@@ -192,11 +195,10 @@ Implementation is complete only when source and packed-extension tests prove:
 11. Overflow, corruption, journal backpressure, archive/prune races, and stale contexts fail safely.
 12. Completion flushing precedes automatic Recipe review.
 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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-state-flow/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.26.5: Telegram Mode Receipt Hotfix
+
+- `Telegram mode controls`: Passive now refreshes the selected button on the first accepted click after Off, including existing-memory restoration and write-fence recovery during an active run. Accepted controls retain their renewed presentation receipt instead of being mistaken for canceled work; later mode choices, branch changes and shutdown still suppress obsolete updates. Memory storage and mode semantics are unchanged; no migration is required.
+
 ## 0.26.4: Passive Compaction Continuity
 
 - `Passive continuation`: After idle Stop, native compaction can replace the later user anchor with a summary. Passive now retains that summary, the available tool calls/results and later refinements instead of reducing requests to a frozen handoff. Reload/resume preserve the same continuation; discarded raw history is not reconstructed. Native compaction, memory scopes and stored state are unchanged; no migration or configuration change is required.

package/node_modules/@llblab/pi-state-flow/dist/lib/extension.js

@@ -1214,11 +1214,11 @@ export default function stateFlowExtension(pi, options = {}) {
                 });
             if (!modePersistenceError) {
                 appendCheckpoint();
-                return { ok: true, message: `State Flow ${selectedMode}` };
+                return { ok: true, message: `State Flow ${selectedMode}`, signal: sharedInspectionLifetime.signal };
             }
             const message = conciseDiagnostic(`State Flow ${selectedMode}; memory writes paused: ${modePersistenceError}`);
             notifyProblem(ctx, message, "warning");
-            return { ok: true, message };
+            return { ok: true, message, signal: sharedInspectionLifetime.signal };
         };
         let accepted = false;
         try {
@@ -1291,10 +1291,11 @@ export default function stateFlowExtension(pi, options = {}) {
                 const operation = selectMode(activeContext, mode);
                 if (mode === "active")
                     return operation;
-                // Inactive choices revoke older presentation at once; the receipt belongs to the new lifetime.
+                // Native-only outcomes use the selected lifetime; async acceptance may renew and return its own receipt.
                 const signal = sharedInspectionLifetime.signal;
                 try {
-                    return { ...await operation, signal };
+                    const result = await operation;
+                    return { ...result, signal: result.signal ?? signal };
                 }
                 catch (error) {
                     return { ok: false, message: diagnosticText(error), signal };

package/node_modules/@llblab/pi-state-flow/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.26.4",
+  "version": "0.26.5",
   "license": "MIT",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",

package/node_modules/@llblab/pi-state-flow/docs/compatibility.md

@@ -138,7 +138,7 @@ The optional adapter presents one Off | Passive | Active row and uses the same m
 - Inspection returns coherent state plus matching revisions, without publication.
 - Controls and inspections acknowledge callbacks before waiting, suppress revoked results and escape late failures in the current menu.
 - Synchronous mode-selection ports are supported.
-- A first Passive selection may install a read-only shared cache without invalidating its own success receipt. Later controls, branch changes and cancellation still revoke obsolete presentation.
+- Passive acceptance returns its current presentation receipt after any internal restoration or lifetime renewal, including existing-memory reacquisition after Off and write-fence recovery. The adapter preserves that accepted receipt, so the first click refreshes the button in both busy and idle sessions. Pre-runtime shared-cache loading also retains its receipt. Later controls, branch changes and shutdown still revoke obsolete presentation, including a change away and back to the same mode while callback acknowledgement waits.
 
 Adapter tests establish these contracts with isolated transport fixtures; they are not a live Telegram smoke test. Missing or unready transport remains fail-open and cannot change core memory behavior.
 

package/node_modules/@llblab/pi-state-flow/docs/usage.md

@@ -211,6 +211,7 @@ When `pi-telegram` is available, its main-menu section shows `State Flow: active
 
 - A horizontal radio row presents `Off | Passive | Active`. The selected option uses 🟣, 🟡 or 🟢 respectively; each inactive option uses ⚫️.
 - Telegram Active requested during a run waits for settlement; Passive and Off apply immediately.
+- The first accepted Passive click refreshes the selected button after memory restoration or write-fence recovery, including while the agent is busy. A later mode or branch selection still suppresses an obsolete menu update.
 - Ordinary successful controls add no redundant mode receipt; diagnostic outcomes stay visible.
 - Off exposes neither tool nor State Flow model context.
 

package/node_modules/@llblab/pi-state-flow/lib/extension.ts

@@ -1200,11 +1200,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			});
 			if (!modePersistenceError) {
 				appendCheckpoint();
-				return { ok: true, message: `State Flow ${selectedMode}` };
+				return { ok: true, message: `State Flow ${selectedMode}`, signal: sharedInspectionLifetime.signal };
 			}
 			const message = conciseDiagnostic(`State Flow ${selectedMode}; memory writes paused: ${modePersistenceError}`);
 			notifyProblem(ctx, message, "warning");
-			return { ok: true, message };
+			return { ok: true, message, signal: sharedInspectionLifetime.signal };
 		};
 		let accepted = false;
 		try {
@@ -1272,10 +1272,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
 				const operation = selectMode(activeContext, mode);
 				if (mode === "active") return operation;
-				// Inactive choices revoke older presentation at once; the receipt belongs to the new lifetime.
+				// Native-only outcomes use the selected lifetime; async acceptance may renew and return its own receipt.
 				const signal = sharedInspectionLifetime.signal;
 				try {
-					return { ...await operation, signal };
+					const result = await operation;
+					return { ...result, signal: result.signal ?? signal };
 				} catch (error) {
 					return { ok: false, message: diagnosticText(error), signal };
 				}

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.26.4",
+  "version": "0.26.5",
   "license": "MIT",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.35.5",
+  "version": "0.36.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -44,12 +44,12 @@
     "banner.jpg"
   ],
   "dependencies": {
-    "@llblab/pi-actors": "0.54.0",
+    "@llblab/pi-actors": "0.55.0",
     "@llblab/pi-claude-usage": "0.2.2",
     "@llblab/pi-clean-room": "0.3.0",
     "@llblab/pi-codex-usage": "0.13.1",
     "@llblab/pi-grow-loop": "0.9.0",
-    "@llblab/pi-state-flow": "0.26.4",
+    "@llblab/pi-state-flow": "0.26.5",
     "@llblab/pi-telegram": "0.57.3",
     "@llblab/skills": "1.15.0"
   },