@llblab/pi-actors 0.42.2 → 0.43.0

package/docs/actor-inspector.md

@@ -1,86 +1,48 @@
 # Actor Inspector
 
-The actor inspector is a manually opened TUI navigator for owned actor runs. Evidence remains read-only; its one explicit lifecycle action can send canonical `control.kill` to the selected running run after confirmation. It keeps recipe/launch identity, communication evidence, and persisted subagent execution evidence in one hierarchy without merging their meanings.
+Open the live owner-filtered Run browser with:
 
 ```text
-owned run
-  → recipe
-  → messages | turns
-    → filtered timeline
-      → one bounded detail level
+/actor-inspector
 ```
 
-## Navigation
+The Inspector follows the kernel directly. It shows Runs owned by the current Pi session and offers exactly three tabs.
 
-`/actors-inspector` opens one centered overlay and remains the only command to remember. The latest run owned by the current Pi session becomes active automatically; an empty session still exposes functional tabs and filters.
+## Recipe
 
-The overlay exposes an explicit focus hierarchy:
+Shows captured execution provenance:
 
-```text
-Run       ←/→ chooses the previous/next owned run, Enter opens runs, K asks to Kill a running run, ↓ enters tabs
-Tabs      ←/→ chooses Recipe, Messages, or Turns
-Recipe    ↑/↓ scroll; PageUp/PageDown jumps by viewport; ↑ at top, Escape, or ← returns to tabs
-Filters   Enter on Messages/Turns opens Channel/State or Subagent; Enter opens values
-Values    ↑/↓ hovers, Enter applies, Escape returns one menu level
-List      ↑/↓ chooses, PageUp/PageDown jumps by viewport, Enter/→ opens detail, ← returns to tabs
-Detail    ↑/↓ scroll, PageUp/PageDown jumps by viewport, Escape/← returns to the list
-Escape    Close (or cancel the active options popup)
-```
-
-Navigation stays bounded by available actions. `↑` on Run does nothing because no higher control exists. `↓` on Tabs enters the timeline only when it contains rows. Empty timelines therefore never receive focus.
-
-`K` appears only while Run is focused and the selected owned run reports `running`. It replaces the Inspector with a dedicated responsive `Confirm Actor Kill` overlay that names the exact `run:<id>`, shows its current status, and states that canonical `control.kill` is destructive and irreversible. Cancel owns initial focus; ←/→/Tab moves between Cancel and Kill actor, Enter activates the focused choice, `Y` confirms directly, and `N`/Escape cancels. Confirmation captures the immutable run generation and routes expected owner/generation through canonical `control.kill`; control compares owner, generation, and running status while serialized against same-directory restart, so terminal, ownership, or replacement-generation races reject without signaling. After the dialog closes, success, cancellation, rejection, and failure remain bounded in the Inspector content area; terminal runs expose no Kill hint and reject a stale keypress.
-
-Selection and focus remain separate visual states. Accent-blue text marks the current tab, active filter popup, and applied option. The Run control uses `← … →` markers plus a light neutral background to show both focus and horizontal cycling; menus and timeline rows retain the single `▶` focus marker, while selected tabs retain brackets. Opening a popup keeps its parent filter blue so the relationship remains visible. Key hints live directly in the bottom overlay border rather than a dedicated body row: border-accent `─` connectors run through and between them instead of bullet glyphs, while key names and arrows retain blue accent color and descriptions use the border accent.
-
-The top Run control aligns vertically with the tab labels, names the selected owned run, and colors its textual lifecycle status semantically. ←/→ cycles owned runs directly with wraparound, while Enter opens the complete owned-run list immediately beneath the control. That run list starts one cell farther left than the filter menus so its border aligns with the Run control rather than the tab/filter grid. It still overlays the tab row rather than leaving a detached gap. The timeline no longer renders run metadata as a data row.
-
-Filters live behind their tab rather than occupying a permanent row. Non-default filters remain visible as compact parenthesized suffixes in the tab label, so hidden state never silently changes the timeline. Enter on Messages opens `Channel: <current>`, `State: <current>`, and `From: <current>`; `From` draws its values from the selected run's roster and limits rows to one actor. Enter on Turns opens `Subagent: <current>`. Enter on a parameter opens its alternative values as a second menu to the right while the parent and current value remain visible. Parent and child share their touching border rather than leaving or doubling a spacer column. Escape returns one level at a time. Moving focus never applies a value.
-
-Nested menus overlay rather than replace the timeline. Only rows and columns containing menu borders or values occlude underlying cells. When adjacent menus have different heights, the unused corner remains transparent and preserves the separator, striped background, and timeline data beneath it. Every run, filter, and nested value menu is viewport-bounded: ↑/↓ moves through the complete option set, the visible window follows focus, and `↑`/`↓` border markers disclose hidden options above or below without growing past the available inspector rows.
-
-The overlay uses most of the available terminal width and height and reduces its content/menu viewport on shorter terminals. Its border-embedded key rail replaces the former three-row footer, returning two rows to a viewport that now caps at 24 rows. The bordered header keeps all three tabs visible, while the body shows the selected run and its current status above the active document or evidence rows. Run, Message, and Turn lists place the newest retained item directly below their control; a newly opened Inspector therefore selects the latest owned run, and ↓ moves backward in time toward older entries. Run options, Messages, and Turns all use compact descending `#N` labels, providing one timestamp-free time axis without repeating type words on every row. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. Unused viewport padding stays on the plain overlay background instead of drawing fake striped rows beneath the last item. The bottom frame exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
+- Recipe name and source path;
+- resolved template and values;
+- imports/context records;
+- declared artifacts and actor-local actions;
+- model/thinking policy and launch source.
 
-## Recipe Document
+Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes.
 
-`Recipe` is the first and initially selected tab. It reads only persisted owned-run evidence from `run.json`: recipe identity and source, the authored recipe context captured at launch, the resolved executable template and runtime values, composition records, model policy, mailbox, artifacts, notification/retirement policy, and bounded read diagnostics. It never follows a mutable external recipe path while the Inspector is open.
+## Trace
 
-The document renders as labeled, indented terminal text rather than raw JSON and scrolls as one level. Secret-bearing values receive the same redaction as turn evidence. Recipe context lives here rather than repeating inside every Turn.
-
-## Communication Timeline
-
-The communication timeline reads run-local room, direct, branch-inbox, and coordinator/session message evidence. Rows display their stable `#N` sequence in newest-first order. It preserves channel/sender filters, unread state, attention markers, roster-derived sender options, and bounded body previews. Unread remains filterable but does not consume a row column with a separate dot marker.
-
-Communication evidence describes messages between actors. It does not prove model execution.
-
-## Turns Timeline
-
-Detached child `pi -p` commands receive isolated session storage under their owned run state:
-
-```text
-<run-state>/sessions/command-NNN/*.jsonl
-```
+Shows the unified bounded Trace projection. Sources include lifecycle/runtime observations, Controls, owned Pi turns, command-log tails, results, artifacts, and diagnostics. Filter by source and open a row for structured detail.
 
-The runner records direct command-template session files in `review-evidence.json`. Coordinator-managed room/swarm participants also persist role/phase-scoped directories under the same `sessions/` root; the inspector discovers those owned files even though the coordinator, rather than the command-template runner, launched them. Explicit caller session policy (`--no-session`, `--session`, `--session-id`, `--session-dir`, or `--fork`) remains authoritative and is not replaced. A command may therefore have no inspector-visible session.
+Trace ordering stays deterministic and newest-first. The projection applies path containment and redaction before rendering.
 
-The turns timeline follows the latest persisted entry branch in each recorded Pi session and displays numbered turns newest-first. Each list row begins with compact `#N`, then a humanized `Subagent N` derived from the internal `command-NNN` session owner, followed by an optional parenthesized semantic stage such as `(reviewer)`. The internal command id remains available in evidence detail for provenance but no longer acts as the unexplained primary list label. The visible model column shows only the model id, not its provider. Tool activity appears as a compact parenthesized action summary such as `(read)`, `(read, bash)`, or `(3 tools)`; `(error)` appears only when the turn or a tool result failed.
+## Control
 
-Each turn groups:
+Shows:
 
-- User input associated with the response;
-- Assistant text and host-persisted thinking blocks;
-- Model, stop reason, usage, and error metadata;
-- Tool calls in assistant source order;
-- Tool results correlated by `toolCallId`, regardless of completion order.
+- Recipe-declared actor-local actions;
+- runtime-owned lifecycle actions;
+- generation-fenced endpoint readiness;
+- recent durable Control records and outcomes.
 
-Enter/→ opens the selected turn as one structured, scrollable detail document inside the overlay. A compact `Subagent N` heading with an optional meaningful role leads into meaning-first sections: User, persisted Thinking, Assistant, Tools, Execution, and Diagnostics. A final Provenance section retains session/prompt paths and truncation state without duplicating recipe context from the Recipe tab. Generic internal stages such as `command` and `subagent` stay hidden; technical `command-NNN` provenance remains available through the session and prompt paths without producing a redundant `Command / command-NNN (command)` block. Secondary qualifiers use parentheses rather than centered-dot separators. Long text, paths, and structured values wrap to subsequent terminal rows instead of receiving visual ellipsis; lines that already fit the available inner width remain intact, leading indentation is reserved before wrapping long unbroken paths so it cannot become a whitespace-only row, and every section plus all of its explicit or wrapped continuations keeps one background stripe. Blank-only source lines and trailing line breaks are omitted from both evidence and readable rendering. Section boundaries change the stripe without inserting separator rows, so the next heading follows the previous value immediately. ↑/↓ scrolls the resulting visual-row document while the footer remains visible. Source evidence remains bounded by the persisted session reader, but the detail view no longer truncates that retained evidence to one terminal row per field.
+A service endpoint counts as ready only when `control-endpoint.json` matches the Run's immutable `run_instance_id`.
 
-The detail view removes a single enclosing `<file name="…">…</file>` prompt transport wrapper and renders structured values as indented key/value text rather than one-line JSON. It has no nested transcript mode: Escape/← returns directly to the Turns list.
+## Keys
 
-## Evidence And Privacy Boundary
+The footer displays current bindings. Use tab navigation to switch Recipe/Trace/Control, movement keys to select rows, detail navigation to inspect evidence, refresh to reconcile disk state, and the documented kill key for lifecycle termination.
 
-The inspector reads file-backed evidence; it does not reconstruct hidden provider reasoning or claim access to data Pi did not persist. When no explicit thinking block exists, Execution reports `thinking: not persisted`.
+Run kill revalidates owner and generation through the canonical lifecycle path. The Inspector never edits state directly and never derives authority from displayed data.
 
-Session text, communication bodies, and structured values remain bounded. Common secret-bearing keys, camelCase/private-key credentials, serialized JSON credentials, and inline credential patterns are redacted before rendering. Malformed JSONL lines, missing parents, cycles, missing sessions, and incomplete tool correlation remain diagnostic states rather than inferred data.
+## Scope
 
-Ownership filtering happens before run summaries, communication previews, roster data, or session evidence become visible. Selection and read state reset across Pi sessions. Manifest session paths must resolve canonically beneath the selected owned run's `sessions/` directory; absolute paths, traversal, and symlink escapes remain invisible. The inspector never scans another coordinator session's run state into the current view.
+The Actor Inspector treats each Run as a concrete actor instance. It does not expose group conversations, peer addresses, routing, or communication topology. Use `inspect target=runtime`, `inspect target=recipes`, and `inspect target=tool:<name>` for non-Run management targets.

package/docs/actors-deep-reference.md

@@ -1,66 +1,108 @@
 # Actors Deep Reference
 
-Use this document after `skills/actors/SKILL.md` when quick-start actor mechanics are not enough.
+## Kernel
 
-## Recipe Navigator
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
 
-Use packaged recipes by name with `spawn file=<name>` for async actors, or register/call them as tools when repeated use deserves a stable shortcut. Start with the curated list below; use [`recipe-library.md`](recipe-library.md) for the full shipped inventory.
+- Recipe owns executable definition and declared actor-local actions.
+- Run owns one generation of execution and evidence.
+- Trace owns observations.
+- Control owns actor-local inputs.
 
-### Top Recipes
+`register_tool` persists capabilities but does not participate in running Control.
 
-- [`pipeline-room-swarm`](../recipes/pipeline-room-swarm.json): room-visible swarm coordination with roles, rounds, optional locker, artifact synthesis, and `subagent_ttl_ms` for hard participant budgets.
-- [`pipeline-repo-health`](../recipes/pipeline-repo-health.json): git/doc/validation evidence to normalized repository health report.
-- [`pipeline-release-readiness`](../recipes/pipeline-release-readiness.json): changelog/package/skill/validation evidence to release review and artifact report.
-- [`actor-worker`](../recipes/actor-worker.json): canonical mailbox-backed branch worker reference for claim/handle/status/artifact patterns.
-- [`coordinator-locker`](../recipes/coordinator-locker.json): queue, lease locks, and journaled coordinator messages for multi-actor ownership.
+## Choosing Execution
 
-### Common Cells
+Use a foreground tool for short work with one natural response. Use a Run when execution may outlive the turn, needs later inspection or steering, produces artifacts, runs as a service, or coordinates repeated/parallel command-template cells.
 
-- Subagents: [`subagent-prompt`](../recipes/subagent-prompt.json), [`subagent-review-coordinator`](../recipes/subagent-review-coordinator.json), [`subagent-quorum`](../recipes/subagent-quorum.json), [`lens-swarm`](../recipes/lens-swarm.json).
-- Artifacts/messages: [`utility-artifact-manifest`](../recipes/utility-artifact-manifest.json), [`utility-artifact-write`](../recipes/utility-artifact-write.json), [`utility-actor-message`](../recipes/utility-actor-message.json).
-- Validation/state: [`utility-validation-wrapper`](../recipes/utility-validation-wrapper.json), [`utility-validate-recipe`](../recipes/utility-validate-recipe.json), [`utility-run-summary`](../recipes/utility-run-summary.json), [`utility-run-state-files`](../recipes/utility-run-state-files.json), [`utility-jsonl-tail`](../recipes/utility-jsonl-tail.json).
+Do not background shell processes outside the Run lifecycle.
 
-## Operating Patterns
+## Recipe Resolution
+
+Active user Recipes shadow packaged Recipes by name. Invalid active shadowing fails with both active and blocked fallback paths instead of silently executing another definition. Imports resolve under Recipe-root priority, enforce a 1 MiB file limit and depth limit 32, reject cycles, and act as local definitions inside one Run.
+
+Current model/thinking placeholders resolve from Pi context before launch and persist provenance in `run.json`.
+
+## Command Templates
+
+String leaves execute without shell parsing. Arrays sequence commands. Objects add `parallel`, `concurrency`, `min_successful`, `when`, `timeout`, `delay`, `retry`, `failure`, `recover`, `repeat`, `accept_output`, and `output` behavior.
+
+Placeholders support typed args, defaults, fallback, and conditional expansion. Prefer explicit scripts when shell semantics or a maintained service loop matters.
+
+## Control Discipline
 
-- **Short deterministic command**: call a foreground registered tool or command template.
-- **Long job/service/fanout**: `spawn` an async recipe, then inspect messages and artifacts.
-- **One-off experiment**: use inline `template`; promote only useful repeats.
-- **Reusable workflow**: package a user or bundled recipe with public knobs, mailbox, artifacts, and docs.
-- **Subagent/swarm execution**: compose packaged recipes/pipelines from smaller recipe cells; add missing generic cells to the extension rather than creating one-off external orchestration scripts.
-- **Consensus-first build**: when many lenses should shape one artifact, have proposer subagents post room messages, then one named implementer writes, one QA reviewer checks, and one finalizer emits `run.done`.
-- **Coordinated workers**: spawn `coordinator-locker` when several actors need a shared queue, acquire/renew/release resource leases, or a journaled coordination point.
-- **Release/review pipeline**: pi-actors can prepare evidence, summaries, and artifacts; external actions such as commit, PR, merge, tag, and publish require the appropriate gated release workflow.
+Public shape:
 
-## Complementary Methodology Engines
+```json
+{"target":"run:<id>","action":"action","input":{},"verbose":false}
+```
 
-pi-actors is the local execution engine for methodology skills. A methodology skill can define abstract patterns such as lens swarm, quorum, task cards, lock discipline, consensus-first build, or clean-context merge; pi-actors turns those patterns into concrete local actors, recipes, queues, leases, artifacts, and messages.
+Recipe actions use lowercase stable names. Do not declare runtime-reserved lifecycle actions. Inputs must remain bounded JSON. A controlled service publishes readiness only after its consumer can read the endpoint and includes its immutable generation id.
 
-Keep the split clean: methodology chooses coordination shape; pi-actors supplies addressable local machinery.
+Controls persist before transport and keep durable outcome evidence. Never infer owner identity from caller-provided input.
+
+## Trace Discipline
+
+Trace events use stable `kind` names and concise summaries. Put structured bounded evidence in `data`; put large evidence in artifacts. Use attention sparingly:
+
+- omitted/`log`: inspectable only;
+- `notify`: visible status;
+- `followup`: semantic coordinator follow-up.
+
+Trace has no address or response semantics.
 
 ## Lifecycle Discipline
 
-1. Choose an existing recipe/tool when available.
-2. Spawn with a stable actor id for observable work.
-3. Inspect `status` after launch.
-4. Use notifications and `inspect`; do not busy-poll.
-5. Read `messages` and `artifacts`, not only stdout.
-6. Use `message` for explicit control or domain commands; inspect `mailbox` before domain-specific messages.
-7. Promote repeated inline forms to recipes.
-8. Keep recipes small and shallow: files over 1 MiB or import chains deeper than 32 are rejected.
-9. Update docs/context when changing public behavior; if the change affects how agents operate this extension, update the bundled skill and prompt guidance too.
-
-## Common Pitfalls
-
-- Treating actor mechanics as multi-agent methodology.
-- Repeating inline templates instead of promoting recipes.
-- Creating task-specific external orchestration scripts when the scenario belongs in pi-actors as a reusable recipe/pipeline.
-- Embedding complex shell loops or Bash `${...}` parameter expansion directly in command templates; braces are pi-actors placeholders too.
-- Omitting stable run ids for work that needs follow-up.
-- Sending domain messages without checking `mailbox`.
-- Expecting current room messages to wake prompt-only subagents; use direct branch messages or a runner protocol for initiating work.
-- Reading only stdout and missing actor messages/artifacts.
-- Assuming every packaged message-controlled script is native-Windows-ready; core run control is platform-adapted, but Unix-tool scripts must be migrated recipe by recipe.
-- Baking local absolute paths into published docs or reusable recipes.
-- Creating recipes that perform external side effects without explicit operator gates.
-- Letting project insights live only in chat instead of updating BACKLOG/CHANGELOG/docs and, when agent behavior changes, the packaged skill or prompt guidance.
-- Preserving old runtime/event/FIFO vocabulary instead of `spawn`/`message`/`inspect` and actor messages.
+Retain these invariants:
+
+- owner filtering;
+- immutable generation fencing;
+- process identity verification;
+- canonical lifecycle locks;
+- shutdown and parent-teardown kill;
+- terminal notification reconciliation;
+- bounded logs and complete captures;
+- owned Pi session provenance;
+- path containment and redaction;
+- review retry/reset safety.
+
+A lifecycle operation that cannot prove identity or ownership fails closed.
+
+## Operating Patterns
+
+### One-shot pipeline
+
+Spawn the Recipe, wait for terminal follow-up when needed, inspect Trace/result/artifacts, and validate outputs. Do not send Controls the process does not implement.
+
+### Controlled service
+
+Spawn, inspect `view=control` for endpoint readiness, send only declared actions, inspect Trace for outcomes, then use the declared actor-local stop action or runtime lifecycle termination as appropriate.
+
+### Parallel review
+
+Use maintained review Recipes with explicit model/thinking and bounded concurrency. Preflight provider/model policy before fanout. Keep reviewer artifacts immutable and run merge/judge stages only after required evidence succeeds.
+
+### Resource locking
+
+Use `resource-locker` only when methodology needs lease-backed resource exclusion. Include owner/resource identity in Control input and treat lock Trace as coordination evidence, not kernel authority.
+
+## Diagnostics
+
+- `inspect target=runtime` for failed Runs, stale Controls, and attention Trace.
+- `inspect target=recipes` for active/shadowed/invalid Recipe state.
+- `inspect target=tool:<name>` for registered capability schema.
+- `inspect target=run:<id> view=recipe|trace|control` for generation evidence.
+- `/actor-inspector` for owner-filtered actor-instance navigation.
+
+Avoid repeated polling. Deferred terminal results arrive as Pi follow-ups.
+
+## Related
+
+- [Runs](./async-runs.md)
+- [Recipe library](./recipe-library.md)
+- [Command templates](./command-templates.md)
+- [Template Recipes](./template-recipes.md)
+- [Actor Inspector](./actor-inspector.md)