@llblab/pi-kit 0.35.4 → 0.36.0

package/AGENTS.md

@@ -27,6 +27,8 @@
 - Do not copy extension source, Skills, or documentation into this repository.
 - Preserve package independence: a kit release may advance any subset of included extensions without forcing lockstep extension releases.
 - Adding packages or newly exposed capabilities requires a kit minor bump. For updates to the existing composition, derive the kit version bump from the highest dependency bump in the synchronized release cohort: dependency patch-only updates require a kit patch bump, while any dependency minor update requires a kit minor bump. Do not let lower-level dependency bumps force a larger kit bump.
+- Stable patch/minor updates within the current major of existing direct packages are explicitly authorized to commit coherent exact pins and a visible kit bump directly to main, without PRs or manual approval. Major/prerelease releases and composition/resource changes remain manual.
+- Keep dependency preparation read-only and secret-free; isolate main writes on a fresh runner and accept only declared data artifacts without executing them. Never force or rebase over concurrent main work. Explicitly dispatch the OIDC publisher for the expected commit, validate again before publication, and never overwrite release tags.
 - Use English for public and repository-facing text.
 - Do not commit, publish, tag, create a remote repository, or mutate Pi settings without explicit authorization.
 

package/BACKLOG.md

@@ -2,6 +2,10 @@
 
 Package pins, resource order and bundled runtime ownership remain authoritative in `package.json`. Release outcomes belong in [CHANGELOG.md](./CHANGELOG.md).
 
+## Automatic-update operations
+
+- **First changed-cohort smoke:** After the first live automatic pin update, confirm the four-file main commit, explicit `workflow_dispatch` to `publish-pi-kit.yml`, matching expected commit, and final npm/tag/GitHub Release identities. No-update runs and local bare-repository tests do not prove this hosted changed-cohort path. Do not fabricate an update or weaken branch protection for a smoke test; inspect the real run or disable the updater on failure.
+
 ## Carried checks
 
 - **Installed 0.35.4 Telegram smoke (operator-owned):** After separately authorized kit installation/reload of every Pi process together, run `/telegram-new` in one follower instance and confirm the same Thread is reused with a new letter slot and title, with no second tab and no orphan left behind. Then restart that instance, open a new session in the same folder, and confirm it adopts the retained Thread instead of provisioning another. Do not erase accepted work or replay uncertain input. Packed validation does not certify installed clients.

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.36.0: Bundled Package Updates (2026-10-21)
+
+- `Automatic updates`: Replaces the dependency PR/approval step with validated direct-to-main adoption of stable same-major patch/minor releases. Exact pins, bundle aliases, lockfile, README and kit version remain synchronized; preparation stays read-only and a fresh data-only writer rejects unsafe payloads and concurrent main changes.
+- `Release handoff`: Explicitly dispatches the OIDC publisher with the committed SHA because GITHUB_TOKEN pushes do not trigger ordinary push workflows. The publisher rejects a different commit before tagging. No updates means no fabricated commit or release; existing untagged versions can retry a missed handoff. Major/prerelease and composition changes remain manual; packaging checks do not establish extension safety.
+- `Exact pins`: `@llblab/pi-actors` 0.54.0 → 0.55.0.
+- `Packaging`: Synchronizes the lockfile, bundle aliases and README inventory. Package membership and resource order remain unchanged; packed validation does not certify extension safety or installed-client behavior.
+
+## 0.35.5: Reviewed Updates and OIDC Releases
+
+- `Update preparation`: Adds daily/manual npm discovery and one human-reviewed update PR containing exact pins, both bundle aliases, regenerated lockfile, README inventory, kit version and changelog. Preparation is read-only without secrets or dependency hooks/bin links; a fresh write runner accepts only four checked data files. Major/prerelease updates and resource changes remain manual; failed validation prevents PR creation, and no auto-merge is enabled.
+- `Publication`: Replaces tag-triggered publication with a main-only npm Trusted Publisher using short-lived OIDC, without a persistent npm token. It reads the reviewed version, skips an unchanged latest tag, validates before a non-forced tag push, and publishes npm before the GitHub Release. Existing-version recovery requires matching tag/npm commit identity; public packed inventory remains verified. Stage-only permission is rejected, not silently substituted.
+- `Review and evidence`: Adds automation regression tests, executable lock/bundle/tarball coherence checks, CODEOWNERS and maintainer setup/recovery guidance. The npm trust binding and enforced main-branch review protection remain administrator-owned activation steps.
+- `Compatibility`: Keeps all eight dependency pins, bundled resource order and runtime entrypoints unchanged. This patch changes update/release tooling and documentation; it does not install or reload Pi clients.
+
 ## 0.35.4: Telegram Session Thread Continuity
 
 - `Telegram pin`: Advances only the exact Telegram pin from `0.57.2` to `0.57.3`. A session replaced inside one Pi process now reuses its preserved Thread on every registration path instead of provisioning a second tab, and a new session registering in a folder whose previous session is provably gone adopts that binding's exact target and slot while the predecessor binding is re-keyed. A live predecessor or an ambiguous candidate set keeps ordinary provisioning.

package/README.md

@@ -12,7 +12,7 @@ Package links lead to the owning repositories for usage, documentation, issues,
 
 | Package | Version | Purpose |
 | --- | ---: | --- |
-| [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.54.0` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
+| [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.55.0` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
 | [`@llblab/pi-claude-usage`](https://github.com/llblab/pi-claude-usage) | `0.2.2` | Claude subscription quota status and shared per-model Fast toggle for Opus, mirrored in Telegram |
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.3.0` | Isolated nested Pi TUI with named npm extensions and compatible model selection |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.13.1` | OpenAI/legacy Codex subscription quota and Business credit status, with persistent priority Fast toggle mirrored in Telegram |
@@ -58,6 +58,55 @@ npm run validate
 
 The repository-local `.npmrc` keeps Pi-provided peer packages out of the kit's lockfile; Pi supplies those peers at runtime. To advance an included package, update its exact version in `dependencies`, run `npm install`, synchronize bundled dependencies, each declared extension pointer and its target, declared Skill paths, tests, the table above, and the changelog, then validate the packed artifact. Keep every pointer target identical to the entrypoint its pin declares. A bundled package must resolve auxiliary files, workers and sibling packages from its own module URL rather than from the declared entry path, because a pointer redirects only that entry. Expose only resources declared by the published owning package; do not use version ranges or unpublished local paths.
 
+## Update automation
+
+Updates are **fully automatic for newer stable patch/minor releases within each existing package's current major**. The updater validates and commits the coherent update directly to `main`, then requests publication. There is no dependency PR, merge step or manual approval. This is an explicit maintainer policy accepting the risk of upstream code; exact versions and successful packaging checks do not establish extension safety.
+
+### Daily update
+
+[Update pi-kit dependencies](./.github/workflows/update-pi-kit-deps.yml) runs daily at **03:00 UTC** and supports `workflow_dispatch` on `main`. Manual dispatch defaults to `dry_run: true`: prepare and validate the complete diff, show the report and retain the data artifact, but do not commit or publish. Select `false` for the live automatic path.
+
+The dependency-free [updater](./scripts/check-updates.mjs) reads npm's `latest` metadata for existing direct dependencies. A custom updater, rather than Dependabot, keeps one coherent update cohort:
+
+- Exact dependency pins, both `bundledDependencies`/`bundleDependencies` aliases, and `package-lock.json` regenerated by `npm install --ignore-scripts --bin-links=false`.
+- The README package/version inventory, versioned upstream documentation links, and [changelog](./CHANGELOG.md).
+- The kit version: patch-only direct updates produce a kit patch; any direct minor update produces a kit minor. Transitive bumps do not determine the kit bump. Pending `Unreleased` outcomes move into the new release within the changelog budget.
+- Existing package membership, extension pointers and resource order. Major updates, non-stable `latest` versions and changed resource declarations remain manual; automation does not guess a new composition.
+
+Preparation runs in a **read-only job without repository secrets**. Both installation and clean `npm ci --ignore-scripts --bin-links=false` disable dependency lifecycle hooks and executable links, then `npm run validate` checks the package and bundled inventory. Failure stops before any main write.
+
+A **separate fresh writer runner** receives only `package.json`, `package-lock.json`, `README.md` and `CHANGELOG.md` from that run's artifact. The trusted updater rejects extra paths, symlinks, script/resource/package-set changes, hidden rollbacks, incorrect kit bumps and unexpected prose edits. It does not install dependencies or execute transferred scripts. The writer requires a clean tracked checkout at the same main baseline, commits only those four files, and uses a normal push to `main`. A concurrent main change rejects the update; it never force-pushes, rebases or bypasses protection.
+
+The report lists exact `old → new` pins and upstream release/compare links for audit. A read-only local discovery plan is available through `node scripts/check-updates.mjs --plan`; `npm run deps:check` prepares and validates local changes but does not push them. Internal `--apply-prepared` is the privileged clean-runner commit/push path, not a normal local update command.
+
+### Automatic publication
+
+Pushes made with `GITHUB_TOKEN` do not trigger another workflow's ordinary `push` event. The writer therefore explicitly dispatches [Publish pi-kit](./.github/workflows/publish-pi-kit.yml) using `workflow_dispatch` and an `expected_commit` SHA. GitHub permits this dispatch exception with `GITHUB_TOKEN`; no PAT is needed. The publisher rejects a different main commit before tag creation, even if the version would otherwise no-op.
+
+On a live run with no new pins, the fresh job still checks for an untagged main version awaiting publication. This can retry a failed handoff before any tag exists; an unchanged already-tagged version does not manufacture a commit or release. The updater reports that publication was requested, not that it succeeded: inspect the separate publisher run for the final result.
+
+The publisher also supports ordinary human pushes to `main` changing `package.json` and manual dispatch on `main`. It **reads, never bumps**, the kit version. If `v<version>` equals the latest `v*` tag in version-sort order, it exits successfully without republishing. Older versions and existing non-latest tags are rejected, not overwritten.
+
+For a new version the order is: verify the hosted main-workflow OIDC environment and npm >= 11.5.1 → clean `npm ci --ignore-scripts --bin-links=false` → `npm run validate` → create and push `vX.Y.Z` → `npm publish --access public` through Trusted Publishing → verify public npm identity and packed inventory → `gh release create --generate-notes`. Publication is serialized. An npm version-conflict is accepted only when the tag and npm `gitHead` both match HEAD; authentication, staging-only permission and contradictory identities remain errors.
+
+A tag may remain if npm or GitHub fails **after** successful validation and tag push. A same-version rerun intentionally no-ops and does not automatically repair this partial state. Recovery requires a separate maintainer decision: verify the existing remote tag and npm state, preserve the exact tagged commit, and repeat clean validation before any missing publication. Use an explicitly reviewed OIDC recovery or interactive maintainer publication with 2FA; never silently fall back to a persistent token or staging. Verify the public package before creating any missing GitHub Release. Never move/delete a published tag or reuse a version for different content.
+
+### Manual changes and operations
+
+Major/prerelease adoption, adding packages, changing resources and editing automation remain manual engineering work. [Release / validate](./.github/workflows/release.yml) still checks normal PRs; [CODEOWNERS](./.github/CODEOWNERS) requests owner review for workflows, manifests and scripts. CODEOWNERS does not gate the expressly authorized direct dependency updates.
+
+Inspect failed workflow logs and upstream source/changelogs when validation fails or runtime behavior is suspect. Pre-1.0 minor versions can break compatibility. Check supported Pi/Node versions, transitive dependencies, executable hooks, pointer targets and auxiliary-file resolution from the owning package's `import.meta.url` when preparing manual changes. Packed validation does not certify installed-client rendering or runtime safety.
+
+Disable the updater workflow before manually holding or rolling back a problematic pin, otherwise a later automatic run may advance it again. Publish corrective content at a new kit version; never retag or replace an npm version. Pi installation and live-client reload remain separate operator actions.
+
+### Repository setup and secrets
+
+- **npm Trusted Publishing (required; no `NPM_TOKEN`):** Configure the npm package for GitHub user/organization `llblab`, repository `pi-kit`, workflow filename `publish-pi-kit.yml` (without `.github/workflows/`), and no environment name. Explicitly allow **`npm publish`**, not only staging. A new binding must complete its first successful publication within two days or be recreated. Preflight checks runtime prerequisites, not registry authorization. See [npm's Trusted Publishing documentation](https://docs.npmjs.com/trusted-publishers/).
+- **Actions permissions:** Preparation and PR validation are read-only. Only the fresh updater writer requests `contents: write` and `actions: write` for the main push and explicit publisher dispatch; it does not request PR permissions. Repository-wide default token permissions may remain read-only because jobs declare their needs. The publisher requests `contents: write` for the tag/GitHub Release and `id-token: write` for short-lived OIDC.
+- **Main protection:** The repository must permit the updater's authorized main push. Required-PR or signing rules can reject it; automation fails rather than weakening rules, adding bypasses or force-pushing. Any compatibility decision about those protections is administrator-owned. The former Actions create-PR checkbox is no longer required by this updater.
+- **`PI_KIT_PAT` (optional, publisher tag only):** Only needed if tag pushes must trigger other downstream workflows. The updater always uses `GITHUB_TOKEN` plus explicit dispatch, not a PAT. No token is committed to source or git configuration.
+- **Do not substitute stage-only tokens:** Granular-token direct publication is being removed in January 2027. Stage-only publication requires separate maintainer promotion with 2FA; this pipeline instead uses explicitly permitted direct OIDC publication and never silently stages.
+
 ## Security
 
-Pi extensions execute with the user's system permissions, and Skills can guide executable actions. Review each included package and release before advancing its pin. Private Knowledge, credentials, and personal Pi configuration are not bundled.
+Pi extensions execute with the user's system permissions, and Skills can guide executable actions. This repository explicitly opts into adopting supported upstream releases **without human review before publication**. Validation and npm audit are packaging signals, not a security decision; reproducible exact pins do not make new code trustworthy. Disable automatic updates if human source review is required. Private Knowledge, credentials and personal Pi configuration are not bundled.

package/node_modules/@llblab/pi-actors/AGENTS.md

@@ -140,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/node_modules/@llblab/pi-actors/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 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.

package/node_modules/@llblab/pi-actors/README.md

@@ -15,7 +15,7 @@ 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
 
@@ -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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/node_modules/@llblab/pi-actors/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.35.4",
+  "version": "0.36.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -29,8 +29,10 @@
   "scripts": {
     "test": "node --test test/*.test.mjs",
     "audit": "npm audit --omit=dev",
-    "pack:check": "npm pack --dry-run",
-    "validate": "npm test && npm run audit && npm run pack:check"
+    "deps:check": "node scripts/check-updates.mjs",
+    "check:coherence": "node scripts/validate.mjs",
+    "pack:check": "node scripts/validate.mjs --pack",
+    "validate": "npm run check:coherence && npm test && npm run audit && npm run pack:check"
   },
   "files": [
     "extensions/",
@@ -42,7 +44,7 @@
     "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",