@llblab/pi-actors 0.41.1 → 0.42.0

package/AGENTS.md

@@ -40,11 +40,12 @@ Pi host
   - `identity.ts`, `paths.ts`, `config.ts`: names, paths, and persistence.
   - `registry.ts`, `runtime.ts`: register/update/delete, load/conflict/registration coordination.
   - `execution.ts`, `execution-output.ts`, `limits.ts`: registered-tool execution and bounded output.
-  - `recipes-references.ts`, `recipes-discovery.ts`, `recipes-usage.ts`: recipe graph, discovery, and usage metadata.
+  - `recipes-references.ts`, `recipes-discovery.ts`, `recipes-usage.ts`, `draft-review.ts`, `draft-sleep.ts`, `tool-review.ts`, `tool-review-scheduler.ts`, `tool-review-transaction.ts`, `tool-review-lineage.ts`, `tool-review-lineage-transaction.ts`, `review-projection.ts`, `review-diagnostics.ts`, `review-control.ts`, `draft-consolidation.ts`, `draft-consolidation-transaction.ts`: recipe graph/discovery, automatic review admission, journaled filesystem and lineage execution/recovery, and bounded diagnostics.
   - `async-runs.ts`: detached run lifecycle facade; `runs-*` subdomains own artifacts, start guards, status, indexes, inbox/outbox, delivery, process control, and retention internals.
   - `runtime-notifier.ts`, `mailbox-loop.ts`: wake notifications and reusable run/branch mailbox worker loops.
   - `messages.ts`, `rooms.ts`, `recipes-context.ts`, `session-evidence.ts`, `inspector.ts`, `inspector-overlay.ts`, `observability.ts`: addressed message protocol, rooms, recipe prompt context, bounded/redacted child-session turns, inspector evidence/navigation, keyboard-driven overlay UI, and ambient run status.
   - `prompts.ts`, `temp.ts`: LLM-facing copy and temp cleanup.
+  - `automatic-review-runtime.ts`, `run-ui-runtime.ts`, `inspector-command.ts`: session-bound review composition, ambient run-observability lifecycle, and Inspector host-command adapters kept outside the entrypoint.
   - `tools.ts`: public tool family composition and reserved tool names.
   - `tools-message.ts`: public `message` tool behavior, including run controls, branch/room routing, tool actor invocation, and delivery feedback.
   - `tools-inspect.ts`: public `inspect` tool behavior, including recipe registry, room/session/tool/run views, and observation formatting.
@@ -68,7 +69,7 @@ Pi host
 
 ## Operating Principles
 
-- Prefer explicit operator action over silent user-config rewrites.
+- Automatic recipe evolution remains silent but mechanically fenced: no-tools reviewers select lifecycle/name operations from value-free structural projections without receiving recipe bodies, template/default values, authored prose, canonical names, draft basenames, raw content hashes, or filesystem paths; batch-local opaque occurrence IDs and equality-only content groups preserve decision correlation and deduplication, while sensitive active recipes stay outside model review as defense in depth, deterministic executors derive unchanged recipes from separate trusted captures, and safe-session activation separates approval from live registry mutation. `PI_ACTORS_AUTOMATIC_REVIEW=off` is the explicit startup opt-out and must disable both scheduling and safe-boundary activation while remaining visible in runtime status. Automatic portfolio review may keep, demote, rename, or deduplicate canonically identical recipes; replacement, split, and executable contract changes require explicit operator authoring. Transactions must hold canonical source/target locks, enforce compare-and-swap preconditions, preserve complete recipes, quarantine before commit, journal process-crash recovery phases, validate recovery CAS/hashes, and derive evidence from runtime outcomes. Prefer `register_tool draft=...` for a fenced manual single-draft override; deliberate filesystem promotion remains valid but may invalidate and defer an already captured batch.
 - Keep published documentation portable: use `~`, `<repo>`, or relative paths instead of machine-local absolute paths.
 - Preserve runtime output discipline because tool output flows directly into agent context. Tool result/error text contributes exactly one leading line break; Pi's renderer contributes the other break after the call header, producing one empty separator row without doubled gaps.
 - Optimize every actor-facing surface for signal over volume: prefer compact state-backed hints and fewer concepts over broad explanatory prose or speculative guidance.
@@ -102,7 +103,7 @@ Pi host
 ## Runtime Contract
 
 - Register trusted command templates with placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary fallback, and split-first command argv construction.
-- Serialize extension-authored recipe mutations with the canonical-path file lock across the complete check/read/write/runtime-update window; keep usage telemetry in locked `.usage/<recipe-filename>.json` sidecars so metadata cannot overwrite authored recipes, and do not replace keyed locking with a broad registry lock.
+- Serialize extension-authored recipe mutations with canonical-path locks across each complete check/read/write/runtime-update window; keep usage and lineage evidence in the locked `.usage/recipes/<recipe-name>.json` ledger plus path index so metadata cannot overwrite authored recipes, and do not replace keyed recipe locking with a broad registry lock. Launch accounting is the narrow exception: it briefly shares the portfolio transaction’s canonical recipe-root fence before taking index/ledger locks, so quarantine cannot make an already-authorized launch disappear; a source that changed before that fence rejects the stale launch and asks for reload.
 - Keep command templates synchronous and portable; `async: true` is the detached run switch.
 - Preserve node controls: `when`, positive `timeout`, `delay`, bounded `retry`, `failure`, and `recover` cleanup.
 - Persist every async command's complete byte-exact stdout/stderr under command- and retry-specific run-state paths while keeping returned tails bounded and pipeline stdin complete.
@@ -114,8 +115,8 @@ Pi host
 ## Recipes And Registry
 
 - `~/.pi/agent/recipes/*.json` is executable muscle memory: recipes there become persistent tools by location.
-- Preserve filename identity, atomic writes, explicit operator-gated changes, and local transportability.
-- Recipe live reload must watch the parent when the user recipe root is absent, switch to the root watcher when it appears, and rearm after deletion/rename without polling or duplicate watcher ownership.
+- Preserve filename identity, atomic writes, explicit operator-gated changes, and local transportability. Extension-authored draft creation must take the same canonical per-path mutation lock used by consolidation so source compare-and-swap and quarantine cannot race a writer.
+- Recipe live reload must watch the parent when the user recipe root is absent, switch to the root watcher when it appears, and rearm after deletion/rename without polling or duplicate watcher ownership. Every callback must compare its exact watcher instance before closing, replacing, notifying, or scheduling so delayed callbacks from closed generations cannot affect the current watcher.
 - Packaged/ad hoc recipes outside the agent root are components, not user tools.
 - Register existing recipes by importing them from the user-root wrapper and using a `{ "name": "alias" }` template node; do not duplicate a ready recipe's script command, defaults, mailbox, or artifact contract in the wrapper.
 - Skill-owned scripts must be exposed through skill-owned recipes first. If a local tool needs that capability, import the skill recipe via `{agent}/skills/<skill>/recipes/<recipe>.json` instead of calling `{agent}/skills/<skill>/scripts/*` directly.
@@ -141,9 +142,13 @@ Pi host
 - Keep tail truncation, full-output temp files, failure formatting, and centralized limits intact.
 - Published docs must not include machine-local absolute paths.
 - Any view scanning run directories must apply coordinator/session ownership filters before exposing summaries or previews.
+- Actor Inspector remains evidence-first; its `Kill` action is available only for a focused owned running run, requires in-overlay confirmation, revalidates exact ownership/status at action time, routes through canonical `control.kill`, and renders bounded success/failure feedback without direct process signaling.
 - Direct branch messages are active inbox queues; guard branch-local append/status rewrites with the branch inbox lock and keep claim/handled/failed transitions tested.
 - Run-state launch and destructive retention require the runtime ownership marker bound to the canonical directory and run id; reject non-run directories, missing/mismatched markers, and symlink aliases rather than trusting `run.json`.
-- Runner lifecycle and destructive process controls require the persisted cross-platform process identity proof (start time, command, and cwd where available); dead, mismatched, or unsupported proofs stay distinct and fail closed rather than degrading to pid liveness.
+- Runner lifecycle and destructive process controls require the persisted cross-platform process identity proof (start time, command, and cwd where available), revalidated at authorization and immediately before signaling; dead, mismatched, or unsupported proofs stay distinct and fail closed rather than degrading to pid liveness. On Unix, only process-group `ESRCH` followed by another matching identity proof permits exact-pid fallback. Keep the residual post-read OS PID/PGID reuse window explicit because Node lacks one portable identity-stable group handle.
+- Automatic draft review may schedule one silent review after ordinary `agent_end` only when twelve drafts exist and no actor is running; it must snapshot an exact batch, leave newer drafts for later, suppress routine terminal/outbox delivery, and never mutate recipes from the reviewer process.
+- Automatic tool review seeds zero-call lineage without fabricating launches, admits only current non-sensitive revisions lacking a review fingerprint, captures exactly thirty-six oldest eligible active user tools, and uses the same silent post-turn/active-actor boundary. Completed output becomes a size-bounded immutable approval only after result validation plus source and target CAS; approval must not mutate the live registry. Approved filesystem mutation uses intent-before-mutation journaling and source quarantine, composition invokes it only during `session_start` before runtime tool loading, persists `lineage_pending`, and must finalize lineage before quarantine cleanup. Failed cycles persist bounded stage/error/remediation evidence; explicit `review.retry`/`review.reset` messages to `tool:pi-actors` may reset counters or disposable state, but reset must reject approved/transaction/lineage evidence that requires roll-forward recovery. Draft retry must preserve the original reviewer run once a transaction journal exists and derive lineage/evidence from that authenticated journal plan, never from later reviewer output.
+- Parent-session teardown runs on every Pi `session_shutdown`, never ordinary `agent_end`: select discovered readable persisted `running` runs with the exact retiring session `ownerId`, carry immutable `run_instance_id` through canonical `control.kill`, serialize control against same-directory restart, fence teardown evidence to that generation, continue across partial failures, and leave terminal, ambiguous, changed-generation, or other-session runs untouched. Use unbounded teardown discovery, count unreadable/corrupt state as failures, and persist one bounded shutdown summary outside individual runs. Descendant Pi sessions remain separate exact owners and rely on their own shutdown hooks; hard termination keeps OS/manual orphan recovery as an honest boundary.
 - Room/branch provenance checks should validate that accepted `from` addresses belong to the addressed run.
 
 ## Coordination And Lifecycle

package/BACKLOG.md

@@ -1,67 +1,7 @@
 # Project Backlog
 
-## Implementation Boundary
-
-Work only inside `pi-actors`: strengthen the current Pi extension and local actor kernel. Do not split work into an external transportable standard, do not design `mcp-actors`, and do not change public positioning.
-
-Current carrying contour:
-
-- `spawn`, `message`, and `inspect` stay the durable public verbs.
-- Async run state stays file-backed and inspectable.
-- Tool exposure stays recipe-based and location-derived from `~/.pi/agent/recipes`.
-- Durable inbox and outbox files remain canonical intent and message state.
-- Rooms, rosters, and branch inboxes remain local coordination memory.
-- Wake notifications remain advisory acceleration, not the queue.
-- Operator-facing observability stays explicit and bounded.
-
-Core invariant:
-
-```text
-Recipe = portable executable capability.
-Run = addressable lifecycle instance.
-Message = typed semantic envelope.
-Mailbox = durable intent queue.
-Wake = advisory acceleration.
-Room = shared local coordination memory.
-Inspect = intentional observation.
-Artifact = durable result.
-```
-
-Non-goals:
-
-- Distributed workers.
-- Generic scheduler DSL.
-- Cloud sync.
-- External transport standard.
-- MCP implementation.
-- Arbitrary subrooms.
-- Heavy broker abstraction.
-
 ## Open Work
 
-### Manual draft-memory consolidation
-
-- [ ] Add a manually invoked command that launches an agent-led consolidation cycle over `~/.pi/agent/recipes/drafts`. The cycle must inventory and classify every draft, propose a complete `promote`, `merge`, or `discard` plan, require explicit operator confirmation before mutations, normalize approved reusable capabilities into active recipe-backed tools under `~/.pi/agent/recipes`, and remove every handled source so the drafts directory finishes empty. It must never run automatically or promote tools silently; preserve evidence for each decision and add regressions for plan-only, confirmation, promotion, merge, discard, failure recovery, and empty-directory completion.
-
-## Backlog Curation Rules
-
-- Completed work belongs in `CHANGELOG.md`, not in `BACKLOG.md`.
-- File length alone is not a domain-split trigger: ~1000-line cohesive domain files are acceptable when ownership is clear.
-- Consider splitting only when a file crosses roughly 2000 lines, mixes real ownership zones, or hides a clearer domain boundary.
-- Prefer semantic compression before file splitting: fewer public nouns, consistent outcomes, compact diagnostics, and domain-owned constants/helpers.
-- Preserve signal/noise balance: feedback should be state-backed, compact, and action-shaped; do not add advisory prose just because a surface exists.
-
-The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
-
-## Explicitly Deferred
-
-These are valid ideas but not current focus. Reintroduce only with concrete evidence from real actor workflows.
+### Windows filesystem fencing verification
 
-- Spawn preflight mode: useful later, but lower value than resilient inspect and mailbox-loop consolidation.
-- Run restart/reattach policy: risky for isolation; defer until corruption recovery and protocol fixtures are stronger.
-- Cross-session force kill or attach/adopt/reparent: useful later, but ownership policy should not change until observability makes current boundaries clear.
-- Actor address helper CLI: keep diagnostics improving opportunistically inside existing parser/tests.
-- Golden flow docs and flow conformance runner: useful after the diagnostic and promotion surfaces are stable.
-- Host-level tool unregistration: blocked on host API support.
-- Branch-local checkpoint semantics: wait for real collaborative branch-runner experiments.
-- Actor recipe feedback loop: keep advisory and operator-gated after real runs produce evidence.
+- [ ] Add Windows CI and native NTFS regressions for consolidation root identity, directory junction/reparse-point substitution, lifecycle locks, and recovery without requiring privileged symbolic-link creation. Keep bigint device/inode capture, document filesystems that report weak or zero file identity, and evaluate a native handle-relative mutation layer only if real Windows evidence justifies expanding beyond Node’s portable process-crash and trusted-state-tree contract.

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.42.0: Automatic Recipe Evolution and Recipe-first Inspector
+
+- `Recipe-first Inspector`: The Inspector now opens on a bounded, redacted `Recipe` document for the selected owned run, showing authored identity, resolved launch template and values, composition, policy, mailbox, and artifacts without following mutable external recipe paths. `Messages` and `Turns` remain adjacent tabs; Turns use one scrollable detail level without duplicated recipe context, and documents/timelines/details support arrows plus PageUp/PageDown. Nested values render as compact indented text with label-first, separator-aware wrapping and consistent lowercase hints. Recipe documents retain ↑-at-top/← navigation to tabs, and ← now also returns a scrolled Messages or Turns list directly to its tabs without resetting the selected row. Turns retain one cached evidence snapshot while list/detail navigation remains active, eliminating repeated full session-file parsing on every arrow key while preserving periodic refresh when focus returns to higher-level controls.
+- `Pre-release Surface Compression`: Automatic-review persistence remains intentionally unversioned until a public compatibility boundary exists; transitional UUID-ledger and filename-sidecar migrations are removed. Canonical recipe names own lineage identity, hashes own content/CAS identity, revisions describe executable history, and operation-local UIDs remain confined to fencing and correlation.
+- `Automatic Draft Evolution`: Twelve eligible inline-spawn drafts trigger one silent no-tools review of a value-free structural projection after the foreground turn and active actors finish; canonical names, draft basenames, raw hashes, recipe bodies, template/default values, authored prose, and filesystem paths remain in the separate trusted capture; batch-local opaque occurrence IDs and equality-only content groups preserve decision correlation without cross-batch identity disclosure. Every captured draft receives one quota-free `promote` or `discard` decision without recipe content; the deterministic executor derives promotions from exact immutable sources, rejects incomplete, stale, unsafe, secret-bearing, temporary-path, duplicate, or colliding outcomes, atomically applies the batch, preserves newer drafts, and records bounded garbage-collection evidence. `register_tool draft=...` remains the preferred fenced single-draft override, while deliberate filesystem promotion stays valid and may defer a captured batch.
+- `Automatic Tool Portfolio Evolution`: Thirty-six eligible non-sensitive active recipe revisions trigger a separate no-tools review of the same value-free structural projection; `PI_ACTORS_AUTOMATIC_REVIEW=off` explicitly disables reviewer scheduling and safe-boundary activation, with the effective policy visible in runtime status. Usage, adaptability, duplication, safety, contract quality, and likely future value inform quota-free `keep`, unchanged-source rename (`evolve`), unchanged-source `demote`, or identical-source `merge` decisions; reviewers cannot return recipe content, while `replace`, `split`, and executable contract changes require explicit operator authoring. Mechanically validated immutable approval plans remain non-mutating until the next safe `session_start` activation boundary.
+- `Deterministic Transactions And Recovery`: Draft and portfolio mutations use exact source/target CAS, authenticated plan-derived operation graphs, root identity and symlink/path containment, intent-before-mutation journals, source quarantine, complete recipe validation, and idempotent rollback/roll-forward recovery. Cross-session admission and activation serialize through canonical state locks; launch accounting shares the portfolio mutation fence so quarantine cannot lose usage evidence, while already-stale loaded sources reject and request reload. Malformed/missing reviewer state and processing failures stop after bounded retries, and hard crashes at every transaction/lineage transition converge without overwriting concurrent edits.
+- `Recipe Lineage, Revisions, And Rollback`: Canonical name-and-priority ledgers preserve lifetime usage, launch-kind counters, former names/paths, review epochs, and transition history across rename, revision, promotion, demotion, merge, and split; replacement starts new meaning. Revision-local counters restart on executable fingerprint changes, unchanged automatic demotions remain in cooldown, and evolve/replace retain a bounded 32-slot snapshot ring. The internal rollback recovery primitive now journals exact recipe and lineage writes before mutation, CAS-validates both, and rolls post-write failures forward idempotently without resetting lifetime usage; 0.42 does not expose a public operator rollback action.
+- `Review Diagnostics And Recovery`: `inspect target=recipes view=reviews` exposes bounded read-only draft/tool phases, action counts, garbage collection, lineage/revision usage, demotion and rollback provenance, transaction state, retained snapshots, and actionable failed stage/error/next-action evidence without starting reviewers or generating foreground turns. Explicit `review.retry` and safe `review.reset` messages to `tool:pi-actors` recover bounded failures while preserving approved transaction/lineage evidence that must roll forward. Draft retry with an existing journal resumes the original reviewer run and authenticated transaction decisions, preventing later reviewer output from splitting committed recipes and lineage.
+- `Generation-fenced Run Control`: Every async start receives an immutable run generation. Inspector `k kill`, parent-session teardown, cancellation, and replacement-sensitive controls compare exact owner/generation inside the canonical lifecycle lock before signaling; stale, terminal, ambiguous, unsupported-proof, or replacement runs fail closed. Session shutdown discovers all readable exact-owner running actors, continues across partial failures, and persists a bounded survivor summary while descendant Pi sessions remain separately owned.
+- `Lock, Watcher, And Signal Safety`: Canonical-path mutation locks use token-owned reclaim/release boundaries with deterministic sibling-process contention and dead-owner recovery, preventing stale owners or concurrent reclaimers from deleting replacement locks. Recipe watchers fence callbacks to their exact generation, and process control revalidates stable identity immediately before group signaling and after `ESRCH`; the remaining host-level PID/PGID reuse window and native Windows NTFS junction verification remain explicit platform boundaries.
+- `Composition Root Compression`: Reduced `index.ts` from 389 to 118 lines by moving automatic-review scheduler/launch/control wiring, ambient run watcher/reconciliation/teardown lifecycle, and Inspector command adaptation into focused domains. The entrypoint now retains host event registration, dependency wiring, tool wrapping, and session context while low-level actor/review operations remain behind named runtime contracts.
+- `Selective Recipe Installation`: Replaced bulk library-copy guidance with explicit selected-recipe or thin-wrapper installation. Internal `draft-review.json` and `tool-review.json` selectors remain runtime-owned components rather than user-installed callable tools.
+- `Validation`: Primary CI release validation now includes protocol conformance, high-severity dependency audit, strict source Domain DAG, an exact temporary-index diff/secret/public-path hygiene pass, and ABCd root/routing/link checks; the local peer test lock advances Pi from `0.75.3` to `0.80.10`, clearing the prior audit findings. Passed 631 tests, 171 conformance tests, 63 packaged-recipe QA checks, a clean `npm audit`, TypeScript, extension import, package build/dry-run for `0.42.0`, and the reproducible supplemental release gates.
+
 ## 0.41.1: Actor Inspector and Delivery Hotfix
 
 - `Terminal Delivery`: Added bounded ten-second terminal reconciliation and watcher rearm so owned terminal follow-ups converge without reload when file watching misses or fails. Delivery still uses Pi follow-ups with owner filtering, `triggerTurn`, no historical outbox replay, and the existing at-least-once handled-marker contract; routine run-directory removal stays quiet while real watcher degradation remains diagnostic.

package/README.md

@@ -129,11 +129,13 @@ Routing comes from `to`, actor ownership, and runtime policy. `type` describes i
 | Message protocol | Typed envelopes across run, tool, branch, room, coordinator, and session targets | Continue, approve, kill, or route work without restarting actors |
 | Rooms and rosters | Run-local group timeline with actor join/leave, contacts, previews, and branch-aware delivery | Coordinate multiple subagents under one visible run |
 | Registry and recipe doctor | Discovered tools, overrides, drafts, invalid recipes, and advisory risk labels | Audit local capability memory before using or promoting it |
-| Draft promotion | Captured ad hoc spawn patterns can become explicit recipes after operator approval | Turn successful improvisation into durable local tools |
+| Draft promotion | Captured ad hoc spawn patterns can become explicit recipes through one operator-selected promotion or bounded automatic unchanged-source review | Turn successful improvisation into durable local tools without granting a reviewer executable-authoring authority |
 | Review/swarm recipes | Maintained packaged pipelines with preflight, marked semantic evidence, quorum knobs, model/thinking inheritance, one-turn prompt-file transport, and diagnostics | Delegate reviews without rebuilding fanout commands |
-| Actor inspector | One manual `Messages or Turns → filtered timeline → detail` overlay for owned actor messages and persisted subagent sessions, with bounded/redacted prompt, model, thinking, tool, result, usage, and provenance evidence | Follow actor traffic and every persisted subagent turn without exposing another session or inventing hidden reasoning |
+| Actor inspector | One manual `Recipe → Messages or Turns → timeline → one detail level` overlay for owned actor evidence, plus confirmed `K` → `control.kill` for the selected running run | Understand the selected recipe and launch, follow actor traffic and persisted subagent turns, or explicitly terminate one owned actor without exposing another session or signaling directly |
 | Packaged recipe QA | Installed-package-safe checks for helper paths, mailbox contracts, platform scope, artifacts, and recipe structure | Keep shipped actor components executable and diagnosable |
 
+Detached actors survive ordinary agent turns. When their owning Pi session quits, reloads, or is replaced, pi-actors scans run state without the ordinary index depth cap and attempts canonical `control.kill` for each readable still-running exact-owner run. Destructive control is fenced by immutable run generation and serialized against state-directory restart; terminal, ambiguous, changed-generation, and other-session runs remain untouched. Unreadable/corrupt state becomes an explicit failure and every shutdown writes a bounded summary under the run root; actors owned by descendant Pi sessions remain outside the exact-owner contract and require their own shutdown hook or manual OS recovery.
+
 ## Golden path: from local workflow to actor memory
 
 Create a reusable async actor recipe in the user recipe root:
@@ -198,7 +200,8 @@ Rules:
 - Same-id JSON recipes shadow Markdown recipes in the same priority layer.
 - Packaged recipes are standard-library components, not automatically installed operator policy.
 - Draft recipes in `~/.pi/agent/recipes/drafts/` are replayable memory, not active tools.
-- `register_tool` creates, updates, lists, deletes, or explicitly promotes draft recipe files through the normal agent interface.
+- `register_tool` creates, updates, lists, deletes, or explicitly promotes one draft recipe file through the normal agent interface.
+- Batch draft consolidation is automatic and silent. Prefer fenced `register_tool draft=...` for one early promotion; deliberate move/copy into the recipe root remains valid but may defer an already captured batch.
 
 Register a foreground tool:
 
@@ -223,14 +226,29 @@ Promote a captured draft only after explicit operator approval:
 register_tool name=docs_review draft=~/.pi/agent/recipes/drafts/spawned-run.json
 ```
 
+Successful inline spawns accumulate draft memory automatically. When twelve drafts exist, pi-actors waits for the foreground turn and active actors to finish, captures an exact immutable batch, and attaches a value-free structural projection to a silent reviewer with no tools. The projection replaces canonical names, draft basenames, and raw hashes with batch-local opaque occurrence IDs and equality-only content groups, and omits recipe bodies, template text, defaults, authored prose, and filesystem paths; the reviewer selects one quota-free `promote` or `discard` decision per source but cannot return recipe content. The executor derives every promotion from the exact captured source, applies the batch through its journaled transaction, garbage-collects discarded drafts, and leaves newer drafts for the next cycle.
+
+Automatic review and mutation remain separate trust boundaries: reviewers receive only value-free structural/usage evidence and have neither filesystem tools, raw recipe access, mutation tools, nor executable-authoring authority. Active-tool portfolio review excludes recipes detected as sensitive and can only select `keep`, unchanged-source rename (`evolve`), unchanged-source `demote`, or deduplication of canonically identical recipes (`merge`). `replace`, `split`, and any executable contract change require an explicit operator-authored recipe mutation through the existing recipe/register surface. Deterministic executors revalidate the exact batch, source and target hashes, complete captured recipes, quarantine state, and journals before committing or recovering internally. The runtime exposes no separate manual batch command.
+
 Inspect the registry:
 
 ```text
 inspect target=recipes view=status
+inspect target=recipes view=reviews
 inspect target=recipes view=summary verbose=true
 inspect target=tool:pi-actors view=triage
 ```
 
+Failed automatic cycles retain a bounded failed stage, error, retry count, and exact next action. Retry the same immutable scope through the reserved runtime actor; reset only disposable failed/completed admission state:
+
+```text
+message to=tool:pi-actors type=review.retry body={"scope":"draft"}
+message to=tool:pi-actors type=review.retry body={"scope":"tool"}
+message to=tool:pi-actors type=review.reset body={"scope":"draft"}
+```
+
+Draft retry with an existing transaction journal resumes the original reviewer run and uses the journal’s authenticated decisions for lineage/evidence; it never launches a second reviewer over already-committed filesystem state. Tool review recovery that already has approved/transaction evidence cannot be reset; retry preserves that evidence and may require `/reload` for the safe `session_start` activation boundary.
+
 ## Command templates
 
 A command template is the launch substrate. It can be a string, a sequence, or a composed graph.
@@ -298,7 +316,7 @@ Packaged recipes should prefer mailbox/wake behavior for portable control. Recip
 
 Commands execute directly without shell evaluation where possible, but trusted executables still run with the same system permissions as Pi. Only register commands, scripts, recipes, and paths you trust.
 
-High-risk templates such as shells, interpreter eval modes, network access, external side effects, and broad filesystem mutation may surface warnings, but the runtime is not a security boundary.
+High-risk templates such as shells, interpreter eval modes, network access, external side effects, and broad filesystem mutation may surface warnings, but the runtime is not a security boundary. Automatic reviewers cannot author or change executable contracts: they receive attached immutable evidence with no tools and may only select unchanged-source lifecycle/name operations. Disable all automatic draft/tool review and safe-boundary activation before starting Pi with `PI_ACTORS_AUTOMATIC_REVIEW=off`; `inspect target=tool:pi-actors view=status` reports `automatic_review=false`.
 
 Prefer:
 

package/dist/index.js

@@ -4,101 +4,30 @@
  *
  * Wraps command templates as callable pi tools, stores durable user tools as recipe files, and exposes actor orchestration across reloads and sessions.
  */
-import * as AsyncRuns from "./lib/async-runs.js";
+import * as AutomaticReviewRuntime from "./lib/automatic-review-runtime.js";
 import * as CommandTemplates from "./lib/command-templates.js";
-import * as InspectorOverlay from "./lib/inspector-overlay.js";
-import * as Observability from "./lib/observability.js";
+import * as InspectorCommand from "./lib/inspector-command.js";
 import * as Paths from "./lib/paths.js";
 import * as Pi from "./lib/pi.js";
 import * as Prompts from "./lib/prompts.js";
+import * as RunUiRuntime from "./lib/run-ui-runtime.js";
 import * as Runtime from "./lib/runtime.js";
 import * as Temp from "./lib/temp.js";
 import * as Tools from "./lib/tools.js";
 import * as ToolsResponse from "./lib/tools-response.js";
 export default function toolRegistryExtension(pi) {
-    let runsAnimationInterval;
-    let runsNotifyTimeout;
     let activeRunContext;
-    let lastRunWatcherDiagnosticId = 0;
-    const runUi = Observability.createRunUiObservationState();
-    const retirementAttempts = new Set();
-    const terminalNotificationsInFlight = new Set();
     const getRunOwnerId = Pi.getSessionId;
-    const retireCandidateRuns = (ctx, summary) => {
-        void Observability.executeRunRetirements(summary, {
-            attempted: retirementAttempts,
-            cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
-            notify: (message, level) => ctx.ui.notify(message, level),
-            sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
-        });
-    };
-    const updateRunUi = (ctx, notify = false, terminalOnly = false) => {
-        const ownerId = getRunOwnerId(ctx);
-        const snapshot = Observability.readRunUiSnapshot(runUi, ownerId);
-        ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
-        if (!notify)
-            return;
-        const notificationSink = Pi.createNotificationSink(pi, ctx);
-        retireCandidateRuns(ctx, snapshot.summary);
-        Observability.deliverRunTransitionNotifications(snapshot.transitions, notificationSink, terminalNotificationsInFlight);
-        Observability.pruneRunUiObservationState(runUi, snapshot);
-        if (!terminalOnly) {
-            Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, notificationSink);
-        }
-    };
-    const closeRunWatchers = () => {
-        runWatcher.close();
-        terminalReconciliation.close();
-        if (runsNotifyTimeout)
-            clearTimeout(runsNotifyTimeout);
-        runsNotifyTimeout = undefined;
-    };
-    const reportRunWatcherDiagnostics = (ctx) => {
-        for (const diagnostic of runWatcher.getDiagnostics()) {
-            if (diagnostic.id <= lastRunWatcherDiagnosticId)
-                continue;
-            lastRunWatcherDiagnosticId = diagnostic.id;
-            ctx.ui.notify(diagnostic.message, diagnostic.code === "rearmed" ? "info" : "warning");
-        }
-    };
-    const scheduleRunEventUpdate = () => {
-        if (runsNotifyTimeout)
-            clearTimeout(runsNotifyTimeout);
-        runsNotifyTimeout = setTimeout(() => {
-            const ctx = activeRunContext;
-            if (!ctx)
-                return;
-            runWatcher.refresh();
-            updateRunUi(ctx, true);
-            reportRunWatcherDiagnostics(ctx);
-        }, 50);
-        runsNotifyTimeout.unref?.();
-    };
-    const runWatcher = Observability.createRunStateWatcher({
-        stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
-        onChange: scheduleRunEventUpdate,
+    const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
+        getActiveContext: () => activeRunContext,
+        getRunOwnerId,
+        getThinkingLevel: () => pi.getThinkingLevel(),
     });
-    const terminalReconciliation = Observability.createRunTerminalReconciliationLoop({
-        onError: (error) => {
-            const ctx = activeRunContext;
-            if (!ctx)
-                return;
-            const message = error instanceof Error ? error.message : String(error);
-            ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
-        },
-        reconcile: () => {
-            const ctx = activeRunContext;
-            if (!ctx)
-                return;
-            Observability.reconcileRunTerminalNotifications({
-                inFlight: terminalNotificationsInFlight,
-                ownerId: getRunOwnerId(ctx),
-                sink: Pi.createNotificationSink(pi, ctx),
-                state: runUi,
-            });
-            reportRunWatcherDiagnostics(ctx);
-        },
-        refreshWatcher: () => runWatcher.refresh(),
+    const runUiRuntime = RunUiRuntime.createRunUiRuntime({
+        getActiveContext: () => activeRunContext,
+        getRunOwnerId,
+        onRunEvent: automaticReview.schedule,
+        pi,
     });
     const actorToolDefinitions = new Map();
     const withCurrentThinkingContext = (definition) => {
@@ -148,54 +77,28 @@ export default function toolRegistryExtension(pi) {
         // Clear the pre-overlay widget after hot reloads from older pi-actors builds.
         ctx.ui.setWidget("zz-pi-actors-comms", undefined);
         activeRunContext = ctx;
-        closeRunWatchers();
+        runUiRuntime.close();
+        automaticReview.close();
         recipeReload.close();
         await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
         if (activeRunContext !== ctx)
             return;
+        automaticReview.start(ctx);
         runtime.loadTools(ctx);
-        updateRunUi(ctx, true, true);
-        runWatcher.refresh();
-        terminalReconciliation.start();
+        runUiRuntime.start(ctx);
         recipeReload.watch(ctx);
-        if (runsAnimationInterval)
-            clearInterval(runsAnimationInterval);
-        runsAnimationInterval = setInterval(() => {
-            if (activeRunContext === ctx)
-                updateRunUi(ctx, false);
-        }, 1000);
-        runsAnimationInterval.unref?.();
     });
-    pi.on("session_shutdown", async () => {
-        if (runsAnimationInterval)
-            clearInterval(runsAnimationInterval);
-        runsAnimationInterval = undefined;
+    pi.on("agent_end", async (_event, ctx) => {
+        if (activeRunContext === ctx)
+            automaticReview.schedule();
+    });
+    pi.on("session_shutdown", async (event, ctx) => {
         activeRunContext = undefined;
-        closeRunWatchers();
+        automaticReview.close();
         recipeReload.close();
+        runUiRuntime.shutdown(event.reason, ctx);
     });
-    pi.registerCommand("actors-inspector", {
-        description: "Open the keyboard-driven actor inspector overlay",
-        handler: async (_args, ctx) => {
-            ctx.ui.setWidget("zz-pi-actors-comms", undefined);
-            await ctx.ui.custom((tui, theme, _keybindings, done) => new InspectorOverlay.ActorInspectorOverlay({
-                done,
-                ownerId: getRunOwnerId(ctx),
-                stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
-                theme,
-                tui,
-            }), {
-                overlay: true,
-                overlayOptions: {
-                    anchor: "center",
-                    width: "94%",
-                    minWidth: 72,
-                    maxHeight: "94%",
-                    margin: 1,
-                },
-            });
-        },
-    });
+    InspectorCommand.registerActorInspectorCommand(pi, getRunOwnerId);
     pi.on("before_agent_start", async (event) => ({
         systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
     }));
@@ -203,6 +106,7 @@ export default function toolRegistryExtension(pi) {
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         getActiveTools: () => pi.getActiveTools(),
         getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
+        handleRuntimeMessage: automaticReview.handleMessage,
         registryRuntime: runtime,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     }).map(withCurrentThinkingContext));

package/dist/lib/async-runs.d.ts

@@ -1,6 +1,6 @@
 /**
  * Command-template async run lifecycle facade.
- * Owns launch, state observation, listing, message/control facade methods, and retention while runs-* subdomains own narrower run internals.
+ * Owns: launch, state observation, listing, message/control facade methods, and retention while runs-* subdomains own narrower run internals.
  */
 import type { CommandTemplateFailureScope, CommandTemplateValue } from "./command-templates.ts";
 import { type CurrentPolicyProvenance } from "./model-context.ts";
@@ -9,8 +9,10 @@ import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
 import { type RunOutboxEvent } from "./runs-outbox.ts";
 import { type RunProcessIdentity } from "./runs-process.ts";
 import * as RunsIndex from "./runs-index.ts";
+import * as RunsParentTeardown from "./runs-parent-teardown.ts";
 import { type ProcessRunInboxResult, type RunInboxMessage, type RunInboxStatus } from "./runs-mailbox.ts";
 import { type SendRunMessageOptions } from "./runs-messages.ts";
+import { type AsyncRunStatus } from "./runs-status.ts";
 export type AsyncRunLaunchSource = "spawn" | "tool";
 export interface AsyncRunControlEndpoint {
     path: string;
@@ -21,6 +23,9 @@ export interface AsyncRunStartParams {
     control?: AsyncRunControlEndpoint;
     file?: string;
     launch_source?: AsyncRunLaunchSource;
+    lifecycleHooks?: {
+        onLockContention?(): void;
+    };
     name?: string;
     ownerId?: string;
     run_id?: string;
@@ -40,6 +45,7 @@ export interface AsyncRunStartParams {
     output?: string;
     artifacts?: Record<string, RunArtifactDeclaration>;
     mailbox?: RecipesReferences.TemplateRecipeMailbox;
+    notification_policy?: "normal" | "silent";
     retire_when?: "children_terminal";
     retry?: number | string;
     failure?: CommandTemplateFailureScope;
@@ -50,7 +56,7 @@ export interface AsyncRunStartParams {
     actor_context?: boolean | string;
     cwd?: string;
 }
-export type AsyncRunStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
+export type { AsyncRunStatus } from "./runs-status.ts";
 export interface AsyncRunMeta {
     argv: string[];
     createdAt: string;
@@ -61,6 +67,7 @@ export interface AsyncRunMeta {
     recipe?: string;
     recipe_file?: string;
     run: string;
+    run_instance_id: string;
     state_dir: string;
     status: AsyncRunStatus;
     tool?: string;
@@ -70,6 +77,7 @@ export interface AsyncRunMeta {
     control?: AsyncRunControlEndpoint;
     mailbox?: RecipesReferences.TemplateRecipeMailbox;
     model_policy?: CurrentPolicyProvenance;
+    notification_policy?: "normal" | "silent";
     process_identity?: RunProcessIdentity;
     recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
@@ -82,10 +90,17 @@ export { parseRunOutboxEventLine } from "./runs-outbox.ts";
 export type { RunOutboxDelivery, RunOutboxEvent, RunOutboxLevel, } from "./runs-outbox.ts";
 export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
 export type { RunStateIndexEntry } from "./runs-index.ts";
-export declare function listRunStateDirs(stateRoot?: string, depth?: number, seen?: Set<string>): string[];
+export declare function listRunStateDirs(stateRoot?: string): string[];
 export declare function rebuildRunStateIndex(stateRoot?: string): RunsIndex.RunStateIndexEntry[];
 export declare function readRunStateIndex(stateRoot?: string): RunsIndex.RunStateIndexEntry[] | undefined;
 export declare function listRuns(stateRoot?: string, statusFilter?: string): Array<Record<string, unknown>>;
+export type { ParentRunTeardownAttempt, ParentRunTeardownDiscoveryFailure, ParentRunTeardownResult, } from "./runs-parent-teardown.ts";
+export interface ParentRunsTeardownSummaryResult extends RunsParentTeardown.ParentRunTeardownResult {
+    summaryPath?: string;
+}
+export declare function teardownRunsOwnedByParent(ownerId: string | undefined, stateRoot?: string, options?: {
+    trigger?: string;
+}): ParentRunsTeardownSummaryResult;
 export declare function tailRun(runOrDir: string, lines?: number): string;
 export declare function readRunEvents(runOrDir: string, lines?: number): RunOutboxEvent[];
 export type { ProcessRunInboxResult, RunInboxMessage, RunInboxStatus, } from "./runs-mailbox.ts";
@@ -115,10 +130,15 @@ export type { SendRunMessageOptions } from "./runs-messages.ts";
 export declare function sendRunMessage(runOrDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;
 export { getRunProcessSignalPlan } from "./runs-control.ts";
 export type { RunProcessSignalPlan } from "./runs-control.ts";
+export interface RunControlExpectation {
+    onLocked?(): void;
+    ownerId?: string;
+    runInstanceId?: string;
+}
 export declare function markRunTerminalNotificationHandled(stateDir: string, status: string): void;
-export declare function cancelRun(runOrDir: string): Record<string, unknown>;
+export declare function cancelRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;
 export declare function archiveRun(runOrDir: string): Record<string, unknown>;
 export declare function pruneRun(runOrDir: string, options?: {
     preserveArtifacts?: boolean;
 }): Record<string, unknown>;
-export declare function killRun(runOrDir: string): Record<string, unknown>;
+export declare function killRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;