@llblab/pi-actors 0.49.2 → 0.50.0

package/dist/lib/tools-inspect.js

@@ -27,14 +27,14 @@ const asRecord = ToolsResponse.asRecord;
 const maybeJsonText = ToolsResponse.maybeJsonText;
 function runtimeStatus() {
     return {
-        automatic_review: process.env.PI_ACTORS_AUTOMATIC_REVIEW !== "off",
+        automatic_review: Paths.isAutomaticRecipeReviewEnabled(),
         run_root: Paths.getRunStateRoot(),
         state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
         version: RuntimeIdentity.getPackageVersion(),
     };
 }
 function runtimeRuns(ctx, deps, status) {
-    const session = ToolsAccess.getContextSessionId(ctx);
+    const session = ToolsAccess.requireContextSessionId(ctx, "runtime Run inventory");
     const listed = deps.listRuns
         ? deps.listRuns()
         : AsyncRuns.listRuns(undefined, status);
@@ -49,8 +49,8 @@ function runtimeRuns(ctx, deps, status) {
             return run;
         }
     })
-        .filter((run) => !session || !run.ownerId || run.ownerId === session);
-    return { ...(session ? { owner_session: session } : {}), runs };
+        .filter((run) => run.ownerId === session);
+    return { owner_session: session, runs };
 }
 function runtimeTriage(ctx, deps) {
     const inventory = runtimeRuns(ctx, deps, undefined);
@@ -354,7 +354,7 @@ function inspectRun(run, view, input, ctx, deps) {
         throw new Error("inspect run:<id> supports view=recipe, view=trace, or view=control.");
     }
     const status = deps.getRunStatus
-        ? deps.getRunStatus(run)
+        ? ToolsAccess.assertRunStatusAccessibleToContext(run, deps.getRunStatus(run), ctx)
         : ToolsAccess.assertRunAccessibleToContext(run, ctx);
     const stateDir = String(status.state_dir);
     if (view === "recipe") {

package/dist/lib/tools-message.d.ts

@@ -4,6 +4,7 @@
  * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */
 export interface ControlToolDeps {
+    getRunStatus?: (run: string) => Record<string, unknown>;
     handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;
 }
 export declare function createControlToolDefinition<TContext = unknown>(deps?: ControlToolDeps): any;

package/dist/lib/tools-message.js

@@ -67,7 +67,9 @@ export function createControlToolDefinition(deps = {}) {
             }
             else {
                 const run = request.target.slice(4);
-                const status = ToolsAccess.assertRunAccessibleToContext(run, ctx);
+                const status = deps.getRunStatus
+                    ? ToolsAccess.assertRunStatusAccessibleToContext(run, deps.getRunStatus(run), ctx)
+                    : ToolsAccess.assertRunAccessibleToContext(run, ctx);
                 const runInstanceId = typeof status.run_instance_id === "string"
                     ? status.run_instance_id
                     : undefined;

package/docs/README.md

@@ -8,6 +8,7 @@ Living index of all documentation in the `/docs` directory.
 - [template-recipes.md](./template-recipes.md) — Saved JSON/Markdown recipe standard, imports, and reusable command-template graph composition
 - [async-runs.md](./async-runs.md) — Run lifecycle, state, Control, Trace, cancellation, and terminal reconciliation
 - [actor-inspector.md](./actor-inspector.md) — Owner-filtered actor-instance navigation through Recipe, Trace, and Control
+- [inspection.md](./inspection.md) — Complete `inspect` target/view matrix, authorization boundaries, and diagnostic routes
 - [tool-registry.md](./tool-registry.md) — Local `pi-actors` registry storage and `register_tool` adaptation
 - [recipe-library.md](./recipe-library.md) — Packaged standard recipe library such as async subagents, coordinator pipelines, utilities, and music playback
 - [releasing.md](./releasing.md) — Guarded tag validation, npm Trusted Publisher setup, registry verification, and GitHub Release convergence

package/docs/actor-inspector.md

@@ -19,13 +19,13 @@ Shows captured execution provenance:
 - declared artifacts and actor-local actions;
 - model/thinking policy and launch source.
 
-Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes. Skill components display logical identities such as `artifacts/report`; private physical `source_file`, `skill_dir`, and `recipe_dir` stay out of Inspector and model-facing views. Non-empty object values render as indented brace-delimited property lists rather than flattened inline strings.
+Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes. Skill components display logical identities such as `artifacts/report`; private physical `source_file`, `skill_dir`, and `recipe_dir` stay out of Inspector and model-facing views. Non-empty objects render as indented brace-delimited property lists. Complex arrays use compact zero-based entries such as `#0: {` rather than Markdown list markers.
 
 ## Trace
 
-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.
+Shows the unified bounded Trace projection. Sources include lifecycle/runtime observations, Controls, owned Pi turns, command-log tails, results, artifacts, and diagnostics. The source selector displays only `all` plus sources present in the current projection from `lifecycle`, `control`, `process`, `agent`, `artifact`, and `runtime`. Select a row to open structured detail.
 
-Trace ordering stays deterministic and newest-first: timestamp descending, same-source physical ordinal descending, fixed internal source rank, then stable id. Internal ordinals are never displayed or interpreted as cross-source causality. Row numbers still read chronologically from bottom to top: the oldest visible event is `#1` and the newest carries the highest number. The summary states whether retained history is complete; `runtime.trace_compacted` means older history was discarded and shows bounded cumulative drop evidence. Terminal/result/execution/artifact evidence keeps its own authority. The projection applies path containment and redaction before rendering.
+Trace ordering stays deterministic and newest-first: timestamp descending, same-source physical ordinal descending, fixed internal source rank, then stable id. Internal ordinals are never displayed or interpreted as cross-source causality. Row numbers are zero-based chronological identities even though display is newest-first: the oldest visible event is `#0` and the newest carries the highest number. The summary states whether retained history is complete; `runtime.trace_compacted` means older history was discarded and shows bounded cumulative drop evidence. Terminal/result/execution/artifact evidence keeps its own authority. The projection applies path containment and redaction before rendering.
 
 ## Control
 
@@ -39,12 +39,28 @@ Shows:
 
 A service endpoint counts as ready only when `control-endpoint.json` matches the Run's immutable `run_instance_id`. Capacity reaches zero at 64 pending Controls; further requests are rejected before admission, while admitted nonterminal Controls never expire automatically. Runtime-owned kill remains available for a stuck saturated Run. Recent Control input and errors use the same bounded structured redaction as tool inspection. The durable `controls.jsonl` journal remains raw and local; rendering never mutates it or attaches an unredacted copy.
 
+## Focus and Selectors
+
+`selectedBg` marks the current focus or selection; `customMessageBg` remains reserved for alternating content stripes. Opening the Run or Trace-source selector preserves `selectedBg` on its parent control, so focus reads as parent → child menu → selected option. Menus are composited over only their bounded rectangle; base content before, beside, and below that rectangle remains rendered.
+
+The Run selector uses aligned zero-based sequence, Run name, and semantic status columns. The Trace selector uses `Trace: <source>`; when a non-`all` source is active, the tab projects the same colon grammar and value color.
+
 ## Keys
 
-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 footer is authoritative for the current focus. The stable navigation contract is:
+
+| Focus | Keys |
+| --- | --- |
+| Run control | `←`/`→` change Run, `↓` enters tabs, `Enter` opens the Run selector, `k` requests kill when available |
+| Tabs | `←`/`→` or `Tab` changes tab, `↑` returns to Run, `↓` enters content, `Enter` opens content or the Trace-source selector |
+| Trace tab | `f` cycles present sources without opening the selector |
+| List/document/detail | `↑`/`↓` and `PgUp`/`PgDn` navigate; `→`/`Enter` opens a Trace row; `←` or `Esc` moves back |
+| Selector | `↑`/`↓` chooses, `Enter`/`→` applies, `←`/`Esc` cancels |
+| Kill confirmation | `←`/`→` or `Tab` chooses, `Enter`/`y` confirms, `Esc`/`n` cancels |
+| Overlay | `Esc` closes from the top level; `Ctrl-C` closes immediately |
 
 Run kill revalidates owner and generation through the canonical lifecycle path. After success, the Run status header is the sole confirmation; the content area does not duplicate it. The Inspector never edits state directly and never derives authority from displayed data.
 
 ## Scope
 
-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 view=status`, `inspect target=recipes view=status`, and `inspect target=tool:<name> view=status` for non-Run management targets.
+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 view=status|runs|triage`, `inspect target=recipes view=status|summary|doctor|imports|reviews`, and `inspect target=tool:<name> view=status|schema` for non-Run management targets. See [Management Inspection](./inspection.md) for exact applicability and authorization boundaries.

package/docs/async-runs.md

@@ -25,7 +25,7 @@ Each Run persists:
 - captured Recipe/template/values;
 - model and thinking policy provenance.
 
-Inspection, Control, cancellation, kill, retirement, and teardown filter by owner. Lifecycle mutations revalidate generation, state, and process identity under the canonical lock.
+Inspection, Control, cancellation, kill, retirement, and teardown filter by owner. Public Run-specific `inspect` and `message` also require a current coordinator session whose id exactly matches the persisted non-empty owner; possession of `run:<id>` alone grants no access. Missing coordinator identity, ownerless state, and cross-owner state fail closed. `inspect target=runtime view=runs` returns only the current session's exact-owner inventory and is the supported diagnostic when a remembered Run is inaccessible. Lifecycle mutations additionally revalidate generation, state, and process identity under the canonical lock.
 
 ## State Files
 
@@ -86,11 +86,19 @@ Unix services may publish a FIFO; native Windows services publish a Windows name
 
 A service exact-id claims queued or transport-delivered Controls and records handled/failed outcomes through the canonical Control journal authority. Admission performs one locked read, integrity/generation check, terminal-tail compaction, capacity decision, and atomic write. The 65th pending Control and a rewrite exceeding 1 MiB fail as bounded `control_backpressure` before admission; malformed, unreadable, oversized, or stale-generation journals fail with an integrity reason and no rejected record. `inspect view=control` reports pending capacity, saturation, stale work, journal bytes, and diagnostics. Every transition uses the same lock, expected-state fence, 128-terminal compaction, and atomic bounded rewrite; persisted errors truncate inside the string at 4 KiB. Admitted nonterminal Controls never expire automatically. Delivery failure evidence cannot regress a Control already claimed or completed by a fast consumer. Services capture their startup generation, so stale-generation Controls never execute.
 
-Runtime lifecycle `kill`, retention actions, and review retry/reset remain runtime-owned rather than Recipe-declared. Kill is the recovery path for a stuck saturated Run: it bypasses actor-local Control capacity and creates no synthetic Control. Same-directory restart clears all generation-local evidence before the new `run_instance_id`; archive moves the exact bounded terminal tree, while prune removes kernel state and preserves only explicitly requested artifacts.
+Runtime lifecycle `kill`, retention actions, and review retry/reset remain runtime-owned rather than Recipe-declared. Invoke Run actions through the public tool exactly as follows:
+
+```text
+message target=run:<id> action=kill
+message target=run:<id> action=archive
+message target=run:<id> action=prune input={"preserve_artifacts":true}
+```
+
+Kill accepts only a running owned generation and is the recovery path for a stuck saturated Run: it bypasses actor-local Control capacity and creates no synthetic Control. Archive and prune accept only terminal owned Runs. Archive moves the entire Run state directory and leaves a tombstone at the original path. Prune removes kernel state and preserves declared existing artifacts only when `preserve_artifacts` is explicitly true, copying them to retained artifact storage first. Same-directory restart clears all generation-local evidence before the new `run_instance_id`.
 
 ## Execution Evidence
 
-`execution.json` stores general command/session provenance. The async runner keeps bounded stdout/stderr logs plus complete capture artifacts when semantic validation requires untruncated evidence. Pi command execution also records owned session provenance for later Trace projection and review checks. Trace and Control quotas do not constrain declared user artifacts, repositories or media sources, complete execution captures, or actor-owned queue/workload state; each remains governed by its own lifecycle and policy.
+`execution.json` stores general command/session provenance. The async runner keeps bounded stdout/stderr logs plus complete capture artifacts when semantic validation requires untruncated evidence. Pi command execution also records owned session provenance for later Trace projection and review checks. Session evidence files larger than 4 MiB are rejected before JSONL materialization and surface explicit truncation diagnostics instead of being loaded unboundedly. Artifact manifests compute size and SHA-256 incrementally in 64 KiB chunks. Trace and Control quotas do not constrain declared user artifacts, repositories or media sources, complete execution captures, or actor-owned queue/workload state; each remains governed by its own lifecycle and policy.
 
 Review acceptance remains a command-stage concern. General execution evidence does not imply review approval.
 
@@ -126,7 +134,7 @@ Packaged controlled services demonstrate the endpoint protocol:
 - `music-player/playback` consumes playback Controls and emits playback Trace;
 - `actors/resource-locker` consumes queue/lease actions, emits lock Trace, and atomically retains at most 512 valid journal records within 1 MiB.
 
-Shared archive/prune evidence similarly retains at most 256 valid records within 1 MiB under its canonical lock. The obsolete advisory `wake.jsonl` notifier was removed; filesystem watchers and bounded reconciliation observe authoritative state directly.
+Shared archive/prune evidence similarly retains at most 256 valid records within 1 MiB under its canonical lock. Filesystem watchers and bounded reconciliation observe authoritative state directly.
 
 One-shot pipelines omit Control and terminate through their command graph.
 
@@ -136,6 +144,10 @@ One-shot pipelines omit Control and terminate through their command graph.
 inspect target=run:<id> view=recipe
 inspect target=run:<id> view=trace source=lifecycle lines=40
 inspect target=run:<id> view=control
+inspect target=runtime view=runs
+inspect target=runtime view=triage
 ```
 
+Runtime `runs` is the exact-owner inventory; `triage` aggregates failed Runs, Control pressure, incomplete Trace evidence, and attention for that inventory. See [Management Inspection](./inspection.md) for every target/view combination and applicable inputs.
+
 Use `/actor-inspector` to inspect Runs as concrete actor instances in the live TUI. Runtime, Recipe registry, and tool definitions remain separate management targets. No public noun, tool, target, or view is added by bounded retention.

package/docs/command-templates.md

@@ -30,7 +30,7 @@ Command-template standard does not own:
 
 ## Shape
 
-A command template is either a command-line string or an ordered array of command-template leaves:
+A command template is a command-line string, an ordered array of command-template nodes, or an object that applies execution fields to a nested `template`:
 
 ```json
 {
@@ -62,7 +62,8 @@ Common object fields:
 - `retry`: Optional max attempts including the first. Default is `1`.
 - `failure`: Optional failure propagation scope: `continue`, `branch`, or `root`. Default is `continue`.
 - `recover`: Optional command template run between failed retry attempts. Recovery output is ignored; recovery failure stops retries.
-- `template`: Required command string or ordered composition array.
+- `repeat`: Optional non-negative expansion count or supported length expression. Repeated nodes receive generated zero-based index placeholders.
+- `template`: Required nested command string, ordered composition array, or command-template object.
 
 For object form, write `template` last. Read the node flags first, then the executable content. Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
 
@@ -83,7 +84,7 @@ Implementations may expand `~` in command position and may resolve relative comm
 Supported forms:
 
 | Form               | Meaning                                          |
-| ------------------ | ------------------------------------------------ |
+| --- | --- |
 | `{name}`           | Required value from runtime values or `defaults` |
 | `{name=default}`   | Inline default when no value is provided         |
 | `{name??fallback}` | Fallback when value is missing, null, or empty   |
@@ -206,7 +207,7 @@ Repeat expressions support only integers, `index`, `prev`, `next`, `repeat`, par
 
 Repeat placeholders are local generated values. Call-time args should not use these reserved names to override the repeat index.
 
-Parallel children use the same object shape: flags come first and `template` stays last. A join remains usable when at least one branch succeeds and reports each branch label/status. Some local schemas may accept `pipe`, but the portable standard is `template: [...]`.
+Parallel children use the same object shape: flags come first and `template` stays last. A join remains usable when at least one branch succeeds and reports each branch label/status. The portable composition field is always `template`.
 
 ## Failure Propagation
 

package/docs/inspection.md

@@ -0,0 +1,83 @@
+# Management Inspection
+
+The public `inspect` tool exposes four exact target families. Targets are management projections, not interchangeable aliases.
+
+## Target and View Matrix
+
+| Target | Views | Purpose |
+| --- | --- | --- |
+| `run:<id>` | `recipe`, `trace`, `control` | Inspect one accessible Run generation |
+| `runtime` | `status`, `runs`, `triage` | Inspect package policy, owned Run inventory, or aggregate operational pressure |
+| `recipes` | `status`, `summary`, `doctor`, `imports`, `reviews` | Inspect user Recipe discovery, active Skill components, exact resolution, imports, and automatic-review recovery |
+| `tool:<name>` | `status`, `schema` | Inspect persistent-tool activation/usage or its current callable schema |
+
+`verbose=false` normally returns compact text and `verbose=true` returns structured details. `tool:<name> view=schema` is always structured because its callable parameter schema has no useful compact equivalent.
+
+## Run Targets
+
+```text
+inspect target=run:demo view=recipe
+inspect target=run:demo view=trace source=lifecycle lines=40
+inspect target=run:demo view=control lines=20
+```
+
+Run views require a current coordinator session and an exact, non-empty match between that session id and the Run's persisted owner. Possessing a `run:<id>` is not authorization. Missing coordinator identity, ownerless state, and cross-owner state fail closed.
+
+- `recipe` returns captured generation-local Recipe, launch, policy, and artifact declarations.
+- `trace` returns the bounded unified projection plus retained-history completeness. `source` accepts `all`, `lifecycle`, `control`, `process`, `agent`, `artifact`, or `runtime`; `lines` bounds returned rows.
+- `control` returns endpoint readiness, declared and runtime-owned actions, pending capacity, saturation, stale work, diagnostics, and recent redacted records; `lines` bounds recent records.
+
+Use the runtime inventory when a remembered Run id is inaccessible from the current session:
+
+```text
+inspect target=runtime view=runs
+```
+
+## Runtime Targets
+
+```text
+inspect target=runtime view=status
+inspect target=runtime view=runs
+inspect target=runtime view=runs status=failed
+inspect target=runtime view=triage
+```
+
+- `status` reports immutable package/runtime identity, state schema, and current automatic-review policy.
+- `runs` returns the complete inventory owned by the current coordinator session; it is not paginated or capped by `lines`. Optional `status` filters that exact-owner inventory.
+- `triage` aggregates the same exact-owner inventory into failed Runs, pending/stale Controls, backpressure, incomplete Trace diagnostics, and retained attention evidence.
+
+Runtime inventory never broadens authorization and never returns ownerless or foreign Run state.
+
+## Recipe Targets
+
+```text
+inspect target=recipes view=status
+inspect target=recipes view=summary
+inspect target=recipes view=doctor identity=music-player/playback
+inspect target=recipes view=imports verbose=true
+inspect target=recipes view=reviews verbose=true
+```
+
+- `status` reports registry/watch state, active/shadowed/invalid/disabled user Recipes, active Skill components, drafts, usage, and diagnostics.
+- `summary` returns the compact discovery-oriented projection of the same current context.
+- `doctor` diagnoses one canonical `<skill>/<recipe>` identity when `identity` is provided; without an identity it reports registry remediation evidence.
+- `imports` exposes active Skill namespaces and component import inventory for resolution diagnosis.
+- `reviews` exposes bounded automatic draft/tool review state and recovery guidance.
+
+`identity` is accepted only with `view=doctor`. Skill inventory is fail-soft diagnostic evidence; exact launch and registration still resolve against the immutable active-session context.
+
+## Tool Targets
+
+```text
+inspect target=tool:music_player view=status
+inspect target=tool:music_player view=schema
+```
+
+- `status` separates persistence, registry admission, host registration, `callable_now`, activation boundary, source identity, and `tool_calls` versus `spawn_calls`.
+- `schema` returns the currently callable description, parameter schema, and prompt snippet. It fails clearly when a definition is persisted but its live callable schema is unavailable.
+
+A registered tool is a capability definition, not a Run. Tool status cannot substitute for Run inspection, and Recipe spawning cannot prove registered-tool invocation.
+
+## Boundaries
+
+Inspection is read-only, owner-filtered where Run state is involved, and redacted. Evidence-heavy Run, review, diagnostic, and text projections apply their documented bounds; `runtime view=runs` deliberately returns the complete matching exact-owner inventory. Inspection does not mutate journals, infer authority from displayed data, expose private active-Skill installation paths, or turn retained Trace into an audit archive. Use `message` for admitted runtime or actor-local actions.

package/docs/recipe-library.md

@@ -80,7 +80,7 @@ Do not bulk-copy bundled Recipes into the user Recipe root. Internal `recipe-mem
 npm run recipes:qa
 ```
 
-Recipe QA recursively inventories direct Skill components and validates filesystem identity, syntax, imports, Control declarations, origin ownership, portable artifact paths, and `{skill_dir}` helper references. Nested files and JSON/Markdown stem collisions fail precisely. Recipe descriptions remain optional; QA requires zero capability diagnostics and zero warnings without enforcing style, documentation quotas, or architecture policy. Removed mailbox declarations fail with the migration diagnostic rather than receiving automatic conversion.
+Recipe QA recursively inventories direct Skill components and validates filesystem identity, syntax, imports, Control declarations, origin ownership, portable artifact paths, and `{skill_dir}` helper references. Nested files and JSON/Markdown stem collisions fail precisely. Recipe descriptions remain optional; QA requires zero capability diagnostics and zero warnings without enforcing style, documentation quotas, or architecture policy. `mailbox` is not part of the current Recipe contract and fails validation.
 
 ## Related