@llblab/pi-kit 0.35.5 → 0.36.1

package/AGENTS.md

@@ -27,7 +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.
-- Automated dependency updates must remain reviewable PRs with a visible kit version bump; never auto-merge. Keep unreviewed preparation read-only and secret-free, isolate PR writes on a fresh runner, and accept only declared data artifacts without executing them. Publish only the reviewed main commit after clean validation, and never overwrite release tags.
+- 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,11 +2,6 @@
 
 Package pins, resource order and bundled runtime ownership remain authoritative in `package.json`. Release outcomes belong in [CHANGELOG.md](./CHANGELOG.md).
 
-## Automation activation (administrator-owned)
-
-- Before relying on automated updates/publication, configure the repository settings described in [Update automation](./README.md#repository-setup-and-secrets): required human Code Owner approval, stale-approval dismissal, the `validate` PR check, no bypass/auto-merge and Actions PR creation permission. Add an automation-account `PI_KIT_PAT` only if downstream checks must trigger automatically. Local validation does not establish these remote settings.
-- **First OIDC publication:** The operator created the `publish-pi-kit.yml` npm trusted publisher on October 21, 2026. Confirm direct `npm publish` is permitted and complete the first successful workflow publication before **October 23, 2026 at 18:13 UTC** to validate that binding; otherwise recreate it. Keep the existing `release.yml` connection until success. No `NPM_TOKEN` is required.
-
 ## 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,18 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.36.1: Bundled Package Updates (2026-10-22)
+
+- `Exact pins`: `@llblab/pi-state-flow` 0.26.4 → 0.26.5.
+- `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.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.

package/README.md

@@ -12,12 +12,12 @@ 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 |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.9.0` | Visible continuation scheduling and bounded worker Skills through compiled, manifest-owned resources |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.26.4` | Scoped context/memory compiler with step-independent current memory, stable Passive/Active modes and visible blocked-state status |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.26.5` | Scoped context/memory compiler with step-independent current memory, stable Passive/Active modes and visible blocked-state status |
 | [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.57.3` | Telegram companion with per-prompt Steer, queued controls, Reroute/Restore, recoverable connections, previews, follower Threads, files, and voice |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
@@ -25,7 +25,7 @@ Versions are exact by design. An upstream release does not change an installed k
 
 ## Install
 
-Requires **Pi 1.0.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.26.4/docs/usage.md#moving-a-store-and-supported-formats) before changing installations.
+Requires **Pi 1.0.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.26.5/docs/usage.md#moving-a-store-and-supported-formats) before changing installations.
 
 From npm:
 
@@ -60,51 +60,53 @@ The repository-local `.npmrc` keeps Pi-provided peer packages out of the kit's l
 
 ## Update automation
 
-Two independent workflows prepare updates and publish **human-reviewed** kit versions. Automation reduces synchronization work; it does not decide whether an extension is safe and never enables auto-merge.
+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.
 
-### Prepare an update PR
+### 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`: it prepares and validates the complete working-tree diff and prints it in the run log/summary, but does not push a branch or create/update a PR. Select `false` to open or refresh the single `chore/pi-kit-deps` PR, labelled `dependencies` and `automated`.
+[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 the existing direct dependencies. A custom updater is used instead of Dependabot because one coherent PR must synchronize kit-owned artifacts, not just npm pins:
+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 versions, both `bundledDependencies`/`bundleDependencies` aliases, and `package-lock.json` regenerated by `npm install --ignore-scripts --bin-links=false`.
-- The README package/version inventory and versioned upstream documentation links.
-- The kit version and [changelog](./CHANGELOG.md): 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 are carried into the new release within the changelog budget.
-- Existing package membership, extension pointers and resource order are preserved. Tests reject changed upstream resource declarations; prepare those composition changes manually rather than guessing new entrypoints.
+- 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.
 
-Major updates and non-stable `latest` versions are reported for manual preparation, never silently accepted. Pre-1.0 minor releases can still break compatibility and require particular care. After synchronization, the updater runs **`npm ci --ignore-scripts --bin-links=false` and `npm run validate`**. Failure stops the run before any PR write; inspect the failed run's log. Both installs disable dependency lifecycle hooks and executable links, so a dependency-provided `node`/`npm` bin cannot shadow validation commands. This is not a security verdict about the bundled code. For a read-only local discovery plan, run `node scripts/check-updates.mjs --plan`; `npm run deps:check` instead prepares and validates changes locally and should be used on a disposable working branch.
+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.
 
-Preparation runs in a **read-only job without repository secrets**. A separate fresh runner receives only `package.json`, `package-lock.json`, `README.md` and `CHANGELOG.md` from that run's artifact. Before any PR write, the trusted updater rejects extra paths, symlinks, package-set/resource/script changes, incorrect version bumps and unexpected prose edits; it regenerates the PR report itself. The write job never installs dependencies or executes artifact-provided scripts. Read-only preparation cannot poison the later write runner's command path.
+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.
 
-### Maintainer review
+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.
 
-For every bot PR, use the [Security](#security) guidance and its generated checklist:
+### Automatic publication
 
-1. Read the linked upstream releases, changelogs and source comparisons. Investigate breaking changes and compatibility with the supported Pi/Node versions.
-2. Review new transitive dependencies, registry integrity changes, executable hooks and auxiliary workers/scripts. Confirm pointer-loaded extensions resolve auxiliary files from their own `import.meta.url`, not the redirected entry path.
-3. Inspect the entire diff: exact pins with no ranges, both bundle aliases matching the package set, lockfile, README inventory, kit version and changelog. No new package, capability or resource should enter through an automatic pin-only update.
-4. Inspect successful `validate` output, including the dry-run tarball's bundled manifests, extension targets and Skills. Run necessary isolated runtime/client smoke checks; package checks and a clean audit do not establish extension safety.
-5. Obtain human approval, then **merge manually**. Do not enable auto-merge. If the updater refreshes the PR, review the new diff again before approval.
+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.
 
-The existing [Release / validate](./.github/workflows/release.yml) PR check is retained, without a tag-triggered publisher. PRs created with `GITHUB_TOKEN` normally do **not** trigger another workflow. The updater already validates before creating them; to obtain the separate PR check, a maintainer can close/reopen the PR or push a reviewed change with their own credentials. `workflow_dispatch` on the PR branch can also provide separate validation evidence, but it does not replace a required PR check. Use an automation-account `PI_KIT_PAT` when automatic downstream PR checks are needed; do not use the sole reviewer's PAT, since authors cannot approve their own PRs.
+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.
 
-### Publish after merge
+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.
 
-[Publish pi-kit](./.github/workflows/publish-pi-kit.yml) runs on `main` pushes changing `package.json`, or by manual dispatch on `main`. It **reads**, never bumps, the reviewed kit version. If `v<version>` equals the latest `v*` tag in version-sort order, the run exits successfully without publishing. 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.
 
-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`. Validation must succeed before a tag is created. The tag push is non-forced, concurrent publications are serialized, and an npm version-conflict error is accepted only when the tag and npm `gitHead` both match the current HEAD. Authentication, registry failures and contradictory identities remain errors. The workflow never commits to `main`.
+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.
 
-A tag may remain if npm or GitHub fails **after** successful validation and tag push. An ordinary rerun intentionally no-ops once that version is the latest tag; it does not republish. Recovery requires a separate maintainer decision: verify the existing remote tag and npm state, preserve the exact tagged commit, and rerun `npm ci --ignore-scripts --bin-links=false` and `npm run validate` before any missing publication. Use an explicitly reviewed OIDC recovery or an interactive maintainer publication with 2FA; never silently fall back to a persistent token or staging. Run `node scripts/publish-pi-kit.mjs verify` before creating a missing GitHub Release with `gh release create vX.Y.Z --verify-tag --generate-notes`. 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`):** In the npm settings for `@llblab/pi-kit`, add a GitHub Actions trusted publisher for 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 `npm stage publish`. Keep an existing `release.yml` trust connection until the new publisher succeeds. A new configuration must complete its first successful publication within two days or be recreated. The preflight verifies runtime prerequisites, not npm authorization; only the successful publish validates the binding. See [npm's Trusted Publishing documentation](https://docs.npmjs.com/trusted-publishers/).
-- **`PI_KIT_PAT` (optional):** A repository-scoped automation-account token with contents and pull-request write access. Without it, PR writes and tag pushes use `GITHUB_TOKEN`; those events do not trigger downstream workflows. Use the PAT only if those downstream events are required. No token is stored in source or committed git configuration.
-- **Actions permissions:** Permit Actions to create pull requests in the repository settings. Only the updater's fresh PR-write job requests `contents: write` and `pull-requests: write`; dependency preparation and PR validation are read-only. The publisher requests `contents: write` for the validated tag/GitHub Release and `id-token: write` for short-lived npm OIDC authentication on a GitHub-hosted runner. No long-lived npm credential is needed.
-- **Do not substitute stage-only tokens:** npm is removing granular-token direct publication in January 2027. A stage-only token returns `E_STAGE_REQUIRED` for `npm publish` and requires separate maintainer approval with 2FA after `npm stage publish`. That is a different release process; this workflow keeps automatic post-merge publication through explicitly permitted OIDC and never silently stages instead.
-- **Required human review:** [CODEOWNERS](./.github/CODEOWNERS) assigns `@llblab` to workflows, manifests and automation scripts. An administrator must separately protect `main` with a pull-request requirement, required Code Owner approval, stale-approval dismissal after new commits, and the `validate` status check; disallow bypasses and auto-merge. CODEOWNERS alone does **not** enforce approval. Configure these settings before relying on the pipeline as a mandatory review gate.
+- **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; the [maintainer checklist](#maintainer-review) makes that review explicit for automated PRs. Automated validation and npm audit are packaging signals, not approval to trust an update. 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