@llblab/pi-actors 0.58.1 → 0.58.2

package/dist/skills/actors/SKILL.md

@@ -5,31 +5,39 @@ description: Use for any non-trivial pi-actors operation, diagnosis, or developm
 
 # Actors
 
+## Public tool names and migration
+
+Use only `actors_tool_register`, `actors_run_spawn`, `actors_control_apply`, and `actors_inspect` for new calls. The old `register_tool`, `spawn`, `message`, and `inspect` names are explicit compatibility dispatch to the same schemas and executors, not a second advertised API. Saved calls and logical Recipe identities stay unchanged; do not migrate the live registry or reload the host implicitly. Compatibility entries are deferred, active dispatch names with model declarations hidden by the host loadout hook; explicit inspection/search or the host's active/registered inventory can still reveal them. They remain subject to the same host permissions and session fences.
+
+Name new configurable Recipe tools under their functional owner's namespace, such as `audio_transcribe`, `music_player`, or `repo_check`, not generic host verbs. This is a caller naming contract, not a new Recipe identity field or an automatic prefix. Preserve existing persisted names and calls. Registration and discovery reject normalized collisions with foreign host tools, even inactive ones; `update=true` cannot authorize replacing another owner's tool. A rejected exposure does not make a foreign tool callable as a Recipe. Within the same runtime, observed name/source-path provenance survives Recipe deactivation so an owned retained host declaration does not block recreation or restoration. A different-source or normalized foreign declaration still blocks exposure; identical host name/source metadata cannot distinguish a replacement. This is not complete host unregister or activation proof: require fresh `callable_now` evidence.
+
+`actors_control_apply` applies Run/runtime actions, never chat or peer messages. The rename changes no Control envelope, ownership, generation, delivery/handling distinction or Run semantics.
+
 ## Choose the operation
 
 Start from the intended outcome:
 
 ```text
 Run a maintained capability once
-→ use spawn recipe=<skill>/<recipe>
+→ use actors_run_spawn recipe=<skill>/<recipe>
 
 Make a maintained capability a persistent agent-callable tool
-→ use register_tool from=<skill>/<recipe>
+→ use actors_tool_register from=<skill>/<recipe>
 
 Keep the same capability but narrow caller defaults
-→ use register_tool from=<skill>/<recipe> defaults={...}
+→ use actors_tool_register from=<skill>/<recipe> defaults={...}
 
 Retain a new named capability without exposing a tool
-→ use register_tool expose=false with from or template
+→ use actors_tool_register expose=false with from or template
 
 Register a trusted command directly
-→ use register_tool template="..."
+→ use actors_tool_register template="..."
 
 Build a reusable multi-node execution graph
 → author a Recipe with named imports
 
 Run a long-lived controlled process
-→ spawn its async Recipe, then use message and inspect
+→ use actors_run_spawn for its async Recipe, then actors_control_apply and actors_inspect
 
 Coordinate several independent actors or subagents
 → also read the swarm Skill
@@ -55,13 +63,13 @@ direct delegation ≠ named import composition
 Run Control ≠ actor chat
 ```
 
-A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool from=<skill>/<recipe>` persists compact logical delegation and activates from the resolved effective contract without copying, symlinking, or ambient re-resolution. A tool is callable in the current session only when activation evidence says `callable_now: true`.
+A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `actors_run_spawn` creates a Run from a Recipe. `actors_tool_register from=<skill>/<recipe>` persists compact logical delegation and activates from the resolved effective contract without copying, symlinking, or ambient re-resolution. A tool is callable in the current session only when activation evidence says `callable_now: true`.
 
-Sync/async is an execution contract, not a usefulness or tool-exposure rule. A sync tool awaits its result; an async tool returns a Run launch receipt, with the eventual result delivered separately. A subagent-backed tool is a capability launcher, not a persisted live subagent. Register a stable, meaningfully parameterized capability when its name and contract save repeated planning; prefer one-off `spawn` over a redundant generic launcher or a new tool for every mission.
+Sync/async is an execution contract, not a usefulness or tool-exposure rule. A sync tool awaits its result; an async tool returns a Run launch receipt, with the eventual result delivered separately. A subagent-backed tool is a capability launcher, not a persisted live subagent. Register a stable, meaningfully parameterized capability when its name and contract save repeated planning; prefer one-off `actors_run_spawn` over a redundant generic launcher or a new tool for every mission.
 
-Use `register_tool expose=false` with a new name and one `template` or `from` source to retain a capability without requesting tool activation. Its `kind: retained_recipe`, `activation: not_requested` receipt is deliberate retention, not failed registration; it omits global callability flags because a same-named tool may already exist. Reuse the exact returned Recipe path through `spawn`, or deliberately expose it later with ordinary `register_tool from=<exact path>`. Retained update, delete and draft promotion are unsupported; do not hand-edit the live registry to bypass those guards.
+Use `actors_tool_register expose=false` with a new name and one `template` or `from` source to retain a capability without requesting tool activation. Its `kind: retained_recipe`, `activation: not_requested` receipt is deliberate retention, not failed registration; it omits global callability flags because a same-named tool may already exist. Reuse the exact returned Recipe path through `actors_run_spawn`, or deliberately expose it later with ordinary `actors_tool_register from=<exact path>`. Retained update, delete and draft promotion are unsupported; do not hand-edit the live registry to bypass those guards.
 
-Automatic retained lifecycle is not implemented. Current user-root tool discovery and automatic review actions are unchanged. `inspect target=recipes view=summary` distinguishes retained definitions under `recipes/library` from root tool candidates; verbose detail gives exact paths, resolved mode and invalid/disabled diagnostics. Storage is not proof of review, callability or a running Actor. `expose` is registration input, not a Recipe field or automatic-review action; do not invent retain/defer review commands. See [persistent tools](./references/persistent-tools.md) for current selection and activation proof.
+Automatic retained lifecycle is not implemented. Current user-root tool discovery and automatic review actions are unchanged. `actors_inspect target=recipes view=summary` distinguishes retained definitions under `recipes/library` from root tool candidates; verbose detail gives exact paths, resolved mode and invalid/disabled diagnostics. Storage is not proof of review, callability or a running Actor. `expose` is registration input, not a Recipe field or automatic-review action; do not invent retain/defer review commands. See [persistent tools](./references/persistent-tools.md) for current selection and activation proof.
 
 `actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
 
@@ -87,15 +95,15 @@ Four locally authored Control guard errors use caller target/action/result recor
 
 Local spawn guards identify unsupported state_dir or invalid as with field/result and the selected caller value, not an admitted Run. Whole values fit16KiB or show field omission; malformed text is unavailable, not repaired. The host may reject unsupported state_dir by its own schema before the facade, so not every SDK validation error has AX text. This adds no launch, no-effects receipt, retry permission, generated identity or change to Recipe/session/post-launch failures.
 
-Fresh source normal register_tool receipts use bare block-YAML tool/result/source/callable_now fields and native argument/warning sequences, including empty argument lists. Normal callability remains Boolean and a non-template source stays one exact safely quoted scalar; complete warnings take priority under16KiB, and whole-field/list omissions count only selected metadata, not hidden chars. Call advice remains opaque instruction, not automatic invocation; an unverified registration keeps its existing read-only tool-status next. Persistence is not callability: rely on the existing activation evidence, never substitute spawn or infer fresh host readiness from this layout. Transaction/errors/list/delete/draft and saved messages are not restyled by this slice.
+Fresh source normal actors_tool_register receipts use bare block-YAML tool/result/source/callable_now fields and native argument/warning sequences, including empty argument lists. Normal callability remains Boolean and a non-template source stays one exact safely quoted scalar; complete warnings take priority under16KiB, and whole-field/list omissions count only selected metadata, not hidden chars. Call advice remains opaque instruction, not automatic invocation; an unverified registration keeps its existing read-only tool-status next. Persistence is not callability: rely on the existing activation evidence, never substitute spawn or infer fresh host readiness from this layout. Transaction/errors/list/delete/draft and saved messages are not restyled by this slice.
 
 Fresh source registry listings and deletion receipts use bare block YAML. Listings preserve the same selected sorted names as a native sequence with coverage; empty selection is `[]`, an overlarge whole group is explicitly omitted rather than mislabeled empty, and malformed text is unavailable without repair. Counts describe selected names, not active/callable or the complete loaded-host registry. Deletion returns tool/result and preserves the manual reload note as opaque instruction: neither a current-map miss nor returned deletion proves full host removal or authorizes automatic reload/retry. Existing partial-effect exceptions and machine details remain unchanged. Combined compiled/package acceptance and loaded-host observation remain separate; an older runtime can still return the prior flat-list text.
 
 Fresh source draft-promotion success uses bare block YAML only for its original selected name/new-update/source=draft/callable display and one prior hint. The selected callable display remains a string, including quoted "false", "true" or "0", not reconstructed Boolean readiness. It adds no default/body/argument/path or activation facts and does not become an ordinary registration transaction. A zero, opaque legacy display or unavailable field is not permission to infer readiness or repair callability. Whole scalar/action omissions stay explicit; invocation advice is content and only the existing read-only status hint may be typed. Promotion callbacks/display can still fail after writes with original errors; no automatic rollback/retry/reload follows.
 
-Local register_tool source-mode refusals now identify field/result and actual replacement/reference/source-mode/inherited-field choices. Existing correction advice is instruction content, not automatic retry/update or a no-effects receipt. Supplied values are not echoed. The host owns clone/coercion/schema behavior before the facade, so use the actual outcome rather than assuming every wrong-typed request reaches a local AX guard. Other registry errors and all existing activation/transaction contracts remain unchanged.
+Local actors_tool_register source-mode refusals now identify field/result and actual replacement/reference/source-mode/inherited-field choices. Existing correction advice is instruction content, not automatic retry/update or a no-effects receipt. Supplied values are not echoed. The host owns clone/coercion/schema behavior before the facade, so use the actual outcome rather than assuming every wrong-typed request reaches a local AX guard. Other registry errors and all existing activation/transaction contracts remain unchanged.
 
-Ordinary invalid/reserved-name and new-registration missing-source errors now use AX fields. Reserved-name display is only the old selected value, not ownership or tool-invocation permission; an unfit/malformed value is wholly omitted/unavailable, not repaired. Missing-source choices and prior correction advice do not impose a new source rule on listing or existing-tool updates. Dependency/normalizer/blocker errors keep their own behavior; no retry, overwrite or no-effects authority follows from these records. Ordinary/draft already-registered refusals likewise identify only the original selected name and preserve Use update=true to overwrite as opaque instruction. This layout neither merges their admission policies nor authorizes overwriting, automatic retry or invocation; unfit/malformed name display stays explicitly omitted/unavailable under16KiB. Local template-shape errors now identify nested Recipe-shaped template, empty sequence or unsupported type, with actual string/object/sequence choices and old repair advice as opaque instruction. Supplied values are not echoed; this adds no source mode, global null/undefined rule, retry permission or change to host validation/coercion and dependency errors. Four later authored-Recipe validation errors now likewise identify defaults, description or template with fixed field/result. Their original stages remain: front null can delete, existing source can be inherited, and host schema/earlier source checks may reject or route a request before these local errors. No new value echo, automatic correction, activation or no-effects authority follows. A delegated-source runtime-owned-default refusal now names only its existing first selected key under defaults/key/result with prior advice as opaque instruction. It neither displays supplied values/all reserved keys nor authorizes retry or changes command-template/default admission behavior; original copy faults can still precede the refusal. Draft-path refusals now identify the allowed-root or resolved-path reference as a whole literal, or explicit omission/unavailability when unfit/malformed. Old summary-inspection advice remains opaque instruction, not automatic action or a new guarantee that a summary lists every draft. Existing root/exists checks and unowned faults keep their semantics; this is not filesystem absence, no-effects or native proof. Public from-normalization failures now show the prior displayed source, reason, legacy active-skill summary and doctor advice as AX. Source stays a whole literal or explicit field omission/unavailability; reason/summary/body labels are opaque, and advice remains instruction rather than an automatic call. The legacy summary is not a complete Skill inventory, display is not freshly normalized ownership, and a failure does not grant retry, broader source/cause access or host readiness. Normal candidate-admission refusals now likewise report selected joined diagnostics and, only on the existing source branch, prior displayed source/legacy summary/doctor advice. Diagnostics/summary are opaque values, not complete lists or raw causes; upstream diagnostic clipping remains legacy/unproven. Full fields fit16KiB or have explicit omission/unavailability without repair. This does not alter admission, make failures effect-free/transactional, or authorize automatic correction, retry or invocation. Draft invalid-Recipe refusals now similarly show only the previously selected optional reason or joined diagnostics with draft/result. They add no path/body, source permission, raw cause or rollback guarantee; read/diagnose/admission behavior and legacy upstream limits remain. Whole values fit16KiB or show omission/unavailability without repair, and absent reason is not synthesized. Outer registration transaction failure now also separates old stage, resolution_generation, legacy summary and surfaced error as AX after the original cleanup path. That generation identifies resolution context, not fresh Run identity/epoch. Inner rollback/advice wording remains opaque error content, not proof of complete host rollback/removal or permission to repeat. Original cleanup/formatting faults and partial effects remain; no new cause/source access or transaction guarantee. Registry activation/promotion/deletion UI notices now use report/tool fields with only old selected display. A report is not callable or complete-host-removal proof; original hasUI/callback/post-effect failures remain. Whole well-formed notifier values are not subject to the model16KiB cap, malformed selected name is unavailable without repair, and RPC forwarding is not client handling/visibility proof. Recipe registry watcher warning/refresh reports use AX fields too; their old default-root wording is not a freshly verified actual path, and restart/register_tool advice is only opaque instruction, never automatic action. Startup registry warnings use category sequences with whole opaque selected diagnostics; authored next/tool labels are content, malformed selected text unavailable and old doctor advice only opaque instruction. The reports do not establish callability, full upstream diagnostics or new source permission.
+Ordinary invalid/reserved-name and new-registration missing-source errors now use AX fields. Reserved-name display is only the old selected value, not ownership or tool-invocation permission; an unfit/malformed value is wholly omitted/unavailable, not repaired. Missing-source choices and prior correction advice do not impose a new source rule on listing or existing-tool updates. Dependency/normalizer/blocker errors keep their own behavior; no retry, overwrite or no-effects authority follows from these records. Ordinary/draft already-registered refusals likewise identify only the original selected name and preserve Use update=true to overwrite as opaque instruction. This layout neither merges their admission policies nor authorizes overwriting, automatic retry or invocation; unfit/malformed name display stays explicitly omitted/unavailable under16KiB. Local template-shape errors now identify nested Recipe-shaped template, empty sequence or unsupported type, with actual string/object/sequence choices and old repair advice as opaque instruction. Supplied values are not echoed; this adds no source mode, global null/undefined rule, retry permission or change to host validation/coercion and dependency errors. Four later authored-Recipe validation errors now likewise identify defaults, description or template with fixed field/result. Their original stages remain: front null can delete, existing source can be inherited, and host schema/earlier source checks may reject or route a request before these local errors. No new value echo, automatic correction, activation or no-effects authority follows. A delegated-source runtime-owned-default refusal now names only its existing first selected key under defaults/key/result with prior advice as opaque instruction. It neither displays supplied values/all reserved keys nor authorizes retry or changes command-template/default admission behavior; original copy faults can still precede the refusal. Draft-path refusals now identify the allowed-root or resolved-path reference as a whole literal, or explicit omission/unavailability when unfit/malformed. Old summary-inspection advice remains opaque instruction, not automatic action or a new guarantee that a summary lists every draft. Existing root/exists checks and unowned faults keep their semantics; this is not filesystem absence, no-effects or native proof. Public from-normalization failures now show the prior displayed source, reason, legacy active-skill summary and doctor advice as AX. Source stays a whole literal or explicit field omission/unavailability; reason/summary/body labels are opaque, and advice remains instruction rather than an automatic call. The legacy summary is not a complete Skill inventory, display is not freshly normalized ownership, and a failure does not grant retry, broader source/cause access or host readiness. Normal candidate-admission refusals now likewise report selected joined diagnostics and, only on the existing source branch, prior displayed source/legacy summary/doctor advice. Diagnostics/summary are opaque values, not complete lists or raw causes; upstream diagnostic clipping remains legacy/unproven. Full fields fit16KiB or have explicit omission/unavailability without repair. This does not alter admission, make failures effect-free/transactional, or authorize automatic correction, retry or invocation. Draft invalid-Recipe refusals now similarly show only the previously selected optional reason or joined diagnostics with draft/result. They add no path/body, source permission, raw cause or rollback guarantee; read/diagnose/admission behavior and legacy upstream limits remain. Whole values fit16KiB or show omission/unavailability without repair, and absent reason is not synthesized. Outer registration transaction failure now also separates old stage, resolution_generation, legacy summary and surfaced error as AX after the original cleanup path. That generation identifies resolution context, not fresh Run identity/epoch. Inner rollback/advice wording remains opaque error content, not proof of complete host rollback/removal or permission to repeat. Original cleanup/formatting faults and partial effects remain; no new cause/source access or transaction guarantee. Registry activation/promotion/deletion UI notices now use report/tool fields with only old selected display. A report is not callable or complete-host-removal proof; original hasUI/callback/post-effect failures remain. Whole well-formed notifier values are not subject to the model16KiB cap, malformed selected name is unavailable without repair, and RPC forwarding is not client handling/visibility proof. Recipe registry watcher warning/refresh reports use AX fields too; their old default-root wording is not a freshly verified actual path, and restart/actors_tool_register advice is only opaque instruction, never automatic action. Startup registry warnings use category sequences with whole opaque selected diagnostics; authored next/tool labels are content, malformed selected text unavailable and old doctor advice only opaque instruction. The reports do not establish callability, full upstream diagnostics or new source permission.
 
 Compact Control receipts now use flat Markdown-list key/value records: run names have no duplicated namespace, action/result/delivery/handling remain distinct, and an optional next node names the inspect tool and its target/view. Multiline values retain their internal Markdown under an outer indentation; they are not extra status fields. This is a presentation of existing facts, not a raw dump or proof of completion. Delivery is not handling; a legacy kill attempt is not full termination. Changed-owner/generation refusals withhold replacement status even in verbose/detail output. Kernel delivery exceptions retain original/later causes and genuinely admitted correlation, but raw cause chains are not a new public message schema or proof that handling failed. Actor-local dispatch exceptions stay errors and report delivery/handling/effects uncertainty with a fresh-owned-inventory hint; they intentionally withhold saved correlation, including verbose, because an admission-era context does not prove current reply scope. Do not interpret this as a handling receipt or no-effect refusal. Do not repeat destructive actions to obtain verbose detail or follow a changed owner/generation blindly. See the Runs reference for this boundary.
 
@@ -108,7 +116,7 @@ Manual archive/prune exceptions can follow moved/copied/removed data. A single s
 To make `music-player/playback` callable as `music_player` with a default source:
 
 ```text
-register_tool
+actors_tool_register
   name=music_player
   from=music-player/playback
   defaults={"source":"~/Music/1MIX"}
@@ -117,8 +125,8 @@ register_tool
 Then:
 
 1. Require registration to report successful resolution, validation, persistence, registry admission, host registration, activation, and `callable_now: true`.
-2. Call the actual `music_player` tool. Do not call `spawn` and describe that as tool invocation.
-3. Verify agent-facing evidence reports `launch_kind: "tool"`; use `inspect target=tool:music_player view=status` when usage or activation needs confirmation.
+2. Call the actual `music_player` tool. Do not call `actors_run_spawn` and describe that as tool invocation.
+3. Verify agent-facing evidence reports `launch_kind: "tool"`; use `actors_inspect target=tool:music_player view=status` when usage or activation needs confirmation.
 4. If callability is false, stop at the reported activation boundary. Preserve the logical source and diagnose it; do not substitute a Recipe spawn as proof.
 
 Use direct delegation for the same maintained capability under a persistent name or narrower defaults. Use named imports only when one Recipe graph contains reusable child nodes. See [persistent tools](./references/persistent-tools.md) and [Recipes](./references/recipes.md).
@@ -136,7 +144,7 @@ Recipes remain with the Skill that owns their behavior. Load that Skill for sele
 | `music-player` | The controlled `playback` singleton |
 | `recipe-memory` | Internal automatic reviewers; use its Skill only for diagnosis/recovery |
 
-Use the `actors/*` helpers only for their narrow requested result or intentional composition. Prefer public `inspect` for ordinary runtime diagnosis and the capability's primary workflow for a complete outcome.
+Use the `actors/*` helpers only for their narrow requested result or intentional composition. Prefer public `actors_inspect` for ordinary runtime diagnosis and the capability's primary workflow for a complete outcome.
 
 ## Delegation boundary
 
@@ -157,12 +165,12 @@ Run = Recipe + Trace + Control
 2. Retain the returned `run:<id>` and normally wait for the root coordinator's completion batch instead of polling. While Pi is active, ready results arrive together at the next safe model-step boundary after the full tool batch; already-idle Pi wakes through a debounced follow-up. Nested actor completions wait for their complete containing top-level tree and arrive in that one compressed batch; descendant sessions do not need notification options.
 3. Inspect `view=trace` when retained observations or attention matter.
 4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
-5. Send `message` only for an action declared and consumed by that controlled Recipe.
+5. Send `actors_control_apply` only for an action declared and consumed by that controlled Recipe.
 6. Use terminal state, result, declared artifacts, and execution evidence to prove completion. When an outcome includes a retained primary-source, declaration-inventory or diagnostic-metadata reference, use that exact reference for further reading, not guessed captures or sibling files. Literal previews may be clipped; their field/range/counts describe what was shown. Diagnostic sources contain recorded command/error/failure-reason metadata only, not complete primary output; other recorded fields may be referenced without being shown. Artifact inventories list declarations only: they do not assert that target files exist or were produced, or grant body-read permission. Explicit unavailability has no guessed legacy body/path fallback.
 
 Compact launch receipts include `run_files` as nested block YAML containing the exact selected observed location values, labeled observed locations/mutable for the exact launched Run generation when the current session and physical identity agree; otherwise they report unavailability or whole-row omission. Machine `file_navigation` details stay JSON-compatible; saved terminal messages retain their own original encodings. Selectively ordinary-read those starting locations when needed; layout/size hints are not body, privacy, terminal or native proof. No evidence bodies or session-wide catalog map are read to build this row. New terminal packets also freeze bounded location rows for captured completion members at fresh current-session admission. Fresh rooted completion headers group paths under literal roots with relative entries, English purposes and a read_first group/entry pointer; no cwd guess, source refresh or automatic read follows. Unknown bases stay explicit. Runtime navigation/omission/inventory facts remain above the Actor Markdown, not in a footer; retained packets keep their original projection. Each shown result keeps its whole Run-file row or explicit per-record omission; wholly omitted results stay covered by result omission/inventory. This describes Run-row coverage, not a complete file/tree inventory. Older captured formats retain their original shown/omitted/total counters; unavailability remains explicit. Ordinary-read selected paths only when needed. Packet reload/render never refreshes sources, and old absent/request-only formats keep their text. Source/npm SDK verifies an explicitly requested ordinary read from a delivered terminal result path; this is research, never routine completion polling or new primary/privacy/clock/native authority. Use the request only for file investigation, not routine completion/status polling. Copied locations/hints remain data, never transferred scope; older batches keep their original text.
 
-For selective investigation of already cataloged files, use `inspect target=runtime view=runs verbose=true`, then ordinary file tools on its current-session root-first navigation. Ordinary maps keep latest-registration order between roots and prioritize known failed subtrees within each root. For a failed investigation add status=failed: inventory is filtered, while the full owned map prioritizes observed failed subtrees across roots, always ancestors first. Priority uses only exact-generation matched inventory observations, not complete terminal truth. Launches and compatible singleton attachments populate the catalog; reads do not backfill missing locations. A `catalog: unavailable` launch warning is not workload failure: do not spawn again merely to repair navigation. The starting map's format hints do not certify syntax, encoding or complete output. See [Runs](./references/runs.md) for selective recorded-capture research and resume boundaries.
+For selective investigation of already cataloged files, use `actors_inspect target=runtime view=runs verbose=true`, then ordinary file tools on its current-session root-first navigation. Ordinary maps keep latest-registration order between roots and prioritize known failed subtrees within each root. For a failed investigation add status=failed: inventory is filtered, while the full owned map prioritizes observed failed subtrees across roots, always ancestors first. Priority uses only exact-generation matched inventory observations, not complete terminal truth. Launches and compatible singleton attachments populate the catalog; reads do not backfill missing locations. A `catalog: unavailable` launch warning is not workload failure: do not spawn again merely to repair navigation. The starting map's format hints do not certify syntax, encoding or complete output. See [Runs](./references/runs.md) for selective recorded-capture research and resume boundaries.
 
 Trusted parent-session shutdown keeps the existing Kill attempts for quit/reload/new/resume/fork; a Run is not promised to survive session replacement. This is logical-session ownership, not independent PID-bound ownership for parallel hosts with the same ID. A teardown report is not scope closure or crash/hung-host cleanup, and bare AgentSession.dispose alone emits no shutdown. See the Runs reference for the boundary.
 
@@ -179,7 +187,7 @@ When a pi-actors operation fails:
 
 Stop if spawn and registry resolve the same Recipe differently. When tool exposure was requested, stop if registration persists but is not callable. A `retained_recipe` receipt with `activation: not_requested` instead permits ordinary Recipe reuse, not a claim of tool invocation. Stop if an operation cannot be proven through pi-actors surfaces.
 
-Never recover by copying maintained Recipe args, defaults, Control, artifacts, or helper commands. Never hard-code a `{skill_dir}` replacement path. Never introduce `bash -lc`, `eval`, direct bundled-helper execution, or shell backgrounding to bypass resolution. Never call `spawn` and claim a tool call. Use [diagnostics](./references/diagnostics.md) for the safe next action.
+Never recover by copying maintained Recipe args, defaults, Control, artifacts, or helper commands. Never hard-code a `{skill_dir}` replacement path. Never introduce `bash -lc`, `eval`, direct bundled-helper execution, or shell backgrounding to bypass resolution. Never call `actors_run_spawn` and claim a tool call. Use [diagnostics](./references/diagnostics.md) for the safe next action.
 
 ## When to read another Skill
 

package/dist/skills/actors/references/diagnostics.md

@@ -5,9 +5,9 @@ Preserve the intended logical identity and diagnose through public pi-actors sur
 ## Recipe resolution or catalog failure
 
 ```text
-inspect target=recipes view=status
-inspect target=recipes view=summary
-inspect target=recipes view=doctor identity=<skill>/<recipe>
+actors_inspect target=recipes view=status
+actors_inspect target=recipes view=summary
+actors_inspect target=recipes view=doctor identity=<skill>/<recipe>
 ```
 
 `summary` and `registry` name the same inspection path: identical facts, details and rendering for identical `verbose` input, so only `verbose` selects compact text versus structured output. The compact label still reports `recipes: registry`, and that label is not a separate view to request. Unsupported-view refusals list the actual accepted view names.
@@ -37,8 +37,8 @@ The actual host clones/validates public arguments first. Its unchanged schema re
 ## Persistent tool failure
 
 ```text
-inspect target=tool:<name> view=status
-inspect target=tool:<name> view=schema
+actors_inspect target=tool:<name> view=status
+actors_inspect target=tool:<name> view=schema
 ```
 
 Successful normal register/update-or-persisted text now separates tool/result/source/callable_now, lists required/optional args and warnings, and keeps one prior hint. Non-template source references are whole literals; safety warnings take budget priority. Whole selected fields/groups/actions fit16KiB or carry omission counts; malformed selections are unavailable without repair or hidden character counts. Invocation advice is opaque instruction rather than an automatic call. The unverified branch retains one typed read-only tool-status next; all existing next_actions/details remain. Post-persistence callbacks/formatting can still fail with their original values, so text does not add rollback, fresh activation or retry guarantees. List/delete/draft/transaction errors and notices remain separate.
@@ -51,19 +51,19 @@ Four local source-mode refusals now show field/result plus replacement fields, a
 
 The host first clones/coerces/validates args. It rejects unsupported values/object-valued from before execute, but numeric from can normalize to a string; an unnamed valid request can still return the existing name list. Direct getter/descriptor/trim probes are not SDK-cloned DTOs. Do not override schema or force a public error solely to obtain AX text, and do not infer the caller's original type from post-validation data.
 
-Ordinary invalid-name, reserved-name and new-registration missing-source errors now use field/value/result or a real source-mode sequence with prior opaque repair advice. No raw caller name/source/body is newly exposed. Reserved selected display fits whole16KiB including spacing or has scalar omission/unavailability; this is not hidden character loss or ownership/invocation proof. Empty-name listing and existing-tool update reusing source remain unchanged. Normalizer/reserved-set/resolution/authoritative/blocker exceptions retain original behavior; a dependency blocker is not reformatted as an owned refusal. SDK numeric name coercion may reach a different local guard than the direct request, while object-type schema rejection stays outside execute. Both ordinary and draft already-registered errors now use field/value/result with exact Use update=true to overwrite instruction content. Distinct Map/authoritative-file/exists/blocker/update checks remain; the selected display does not disclose source/recipe bytes or certify no effects, rollback, fresh host membership or overwrite permission. Whole scalar omission/unavailability and raw observation/coercion failures remain explicit and unchanged, respectively. Nested Recipe-shaped template, empty sequence and unsupported template type now have fixed template/result AX errors and real supported-type choices, retaining prior correction as opaque instruction without supplied body/source echo. External expansion/getter failures stay raw. Front null/empty deletion, undefined/inherited source and later authoring errors are not reclassified; a numeric SDK template may be coerced to a command string rather than reaching the direct unsupported-type refusal. Later non-object defaults, missing command description, authoring-stage null and missing final template now use fixed field/result without supplied values. Preserve the error's actual stage rather than treating null globally invalid or every missing source as a late template failure: host defaults schema rejection, front deletion and earlier missing-source refusal still precede or bypass these guards. Schema argument/description/default/retained-template observation faults keep their original owner and values. The delegated-source runtime-owned-default-key refusal now names the old first selected key only with fixed defaults/result and opaque remove-default/retry advice. Key order and complete prior default copy remain; do not infer a complete key listing, supplied values, early effect-free rejection, global command-template ban or permission to repeat. Host SDK preserves selected-key error normalization without granting readiness or overwrite authority. Draft outside-root/current-not-found diagnostics now identify field draft and only the original allowed-root/resolved-path literal; root refusal does not add the refused caller path. Whole references fit16KiB or are explicitly omitted/unavailable without repair/private counts. Old summary hint stays instruction content, not an automatic call/listing guarantee. Getter/resolve/relative/dot-prefix/exists behavior and raw faults remain; not-found text is not stronger absence/native/host proof. Public from-normalization wrapper now reports only original displayed source/reason/legacy active_skills_summary and opaque doctor instruction, with whole-field omissions/unavailability under16KiB. Inner normalizer errors, Error.message.trim/String and old display/summary/doctor observation order remain. Do not parse comma summary/body Next labels, infer discarded counts/private causes, fix undefined/source-hint disagreement or automatically execute advice; other validation/transaction errors stay separate. Normal candidate-admission refusal now uses field recipe/result and opaque diagnostics_summary, plus old displayed source/legacy summary/instruction only when the old requestedSource branch is truthy. Preserve pre-Error diagnostic join/String ordering and original bounded upstream diagnostic text, including explicit unavailability for malformed selected clipping; do not reconstruct a full list/body/cause or infer no effects, rollback, current readiness or retry permission. Draft invalid-Recipe raw/candidate refusals now likewise use fixed draft/result plus old optional reason or joined diagnostics only, not new paths/bodies/causes. Separate raw read/diagnose calls, reason truthiness, original draft Error-before-join timing and upstream4096UTF16 candidate cap stay unchanged; malformed selected text is unavailable without repair. This neither merges normal/draft policy nor proves no effects/rollback or authorizes retry. Outer registration transaction-failure text now identifies old stage/resolution_generation/legacy summary/error only after existing cleanup. That generation is resolution-context display, not Run scope/current host epoch. Error.message/String behavior and all restoration/unlink/Map/reactivation/setActive faults remain exact; a formatting error can follow cleanup, and legacy inner rollback/advice text is not authoritative rollback/readiness or retry permission. Whole selected fields fit16KiB or show omission/unavailability without repairing private data. Inner activation/persisted-admission errors and receipts stay separate. Registry activation/promotion/deletion notifier text now uses old report identity/tool display only, not new readiness/removal evidence. Original info type/positions/hasUI gate/callback exceptions remain; ordinary UI has no borrowed model16KiB limit. Multiline text stays literal/native-wrapped, malformed selected name is explicitly unavailable, and RPC message forwarding does not certify display or handling. Loaded terminal/phone remains separately gated. Recipe registry watcher warning/refresh notices now use AX report plus original opaque repair instruction, without changing direct ctx.ui.notify, pending/dedup/load/callback failures. The old ~/.pi/agent/recipes report is not freshly verified root metadata; it does not authorize restart, register_tool replay or reload. Startup registry warnings now expose category sequences including singletons, preserving original selected diagnostics and existing shadow/bash suppression. Authored labels stay inside values; malformed selected text is unavailable, no borrowed model cap or recovered private tail. Doctor advice stays opaque instruction, not automatic inspection. Formatting still precedes runtime.notify/hasUI; a report/fault does not undo prior scan/registry effects.
+Ordinary invalid-name, reserved-name and new-registration missing-source errors now use field/value/result or a real source-mode sequence with prior opaque repair advice. No raw caller name/source/body is newly exposed. Reserved selected display fits whole16KiB including spacing or has scalar omission/unavailability; this is not hidden character loss or ownership/invocation proof. Empty-name listing and existing-tool update reusing source remain unchanged. Normalizer/reserved-set/resolution/authoritative/blocker exceptions retain original behavior; a dependency blocker is not reformatted as an owned refusal. SDK numeric name coercion may reach a different local guard than the direct request, while object-type schema rejection stays outside execute. Both ordinary and draft already-registered errors now use field/value/result with exact Use update=true to overwrite instruction content. Distinct Map/authoritative-file/exists/blocker/update checks remain; the selected display does not disclose source/recipe bytes or certify no effects, rollback, fresh host membership or overwrite permission. Whole scalar omission/unavailability and raw observation/coercion failures remain explicit and unchanged, respectively. Nested Recipe-shaped template, empty sequence and unsupported template type now have fixed template/result AX errors and real supported-type choices, retaining prior correction as opaque instruction without supplied body/source echo. External expansion/getter failures stay raw. Front null/empty deletion, undefined/inherited source and later authoring errors are not reclassified; a numeric SDK template may be coerced to a command string rather than reaching the direct unsupported-type refusal. Later non-object defaults, missing command description, authoring-stage null and missing final template now use fixed field/result without supplied values. Preserve the error's actual stage rather than treating null globally invalid or every missing source as a late template failure: host defaults schema rejection, front deletion and earlier missing-source refusal still precede or bypass these guards. Schema argument/description/default/retained-template observation faults keep their original owner and values. The delegated-source runtime-owned-default-key refusal now names the old first selected key only with fixed defaults/result and opaque remove-default/retry advice. Key order and complete prior default copy remain; do not infer a complete key listing, supplied values, early effect-free rejection, global command-template ban or permission to repeat. Host SDK preserves selected-key error normalization without granting readiness or overwrite authority. Draft outside-root/current-not-found diagnostics now identify field draft and only the original allowed-root/resolved-path literal; root refusal does not add the refused caller path. Whole references fit16KiB or are explicitly omitted/unavailable without repair/private counts. Old summary hint stays instruction content, not an automatic call/listing guarantee. Getter/resolve/relative/dot-prefix/exists behavior and raw faults remain; not-found text is not stronger absence/native/host proof. Public from-normalization wrapper now reports only original displayed source/reason/legacy active_skills_summary and opaque doctor instruction, with whole-field omissions/unavailability under16KiB. Inner normalizer errors, Error.message.trim/String and old display/summary/doctor observation order remain. Do not parse comma summary/body Next labels, infer discarded counts/private causes, fix undefined/source-hint disagreement or automatically execute advice; other validation/transaction errors stay separate. Normal candidate-admission refusal now uses field recipe/result and opaque diagnostics_summary, plus old displayed source/legacy summary/instruction only when the old requestedSource branch is truthy. Preserve pre-Error diagnostic join/String ordering and original bounded upstream diagnostic text, including explicit unavailability for malformed selected clipping; do not reconstruct a full list/body/cause or infer no effects, rollback, current readiness or retry permission. Draft invalid-Recipe raw/candidate refusals now likewise use fixed draft/result plus old optional reason or joined diagnostics only, not new paths/bodies/causes. Separate raw read/diagnose calls, reason truthiness, original draft Error-before-join timing and upstream4096UTF16 candidate cap stay unchanged; malformed selected text is unavailable without repair. This neither merges normal/draft policy nor proves no effects/rollback or authorizes retry. Outer registration transaction-failure text now identifies old stage/resolution_generation/legacy summary/error only after existing cleanup. That generation is resolution-context display, not Run scope/current host epoch. Error.message/String behavior and all restoration/unlink/Map/reactivation/setActive faults remain exact; a formatting error can follow cleanup, and legacy inner rollback/advice text is not authoritative rollback/readiness or retry permission. Whole selected fields fit16KiB or show omission/unavailability without repairing private data. Inner activation/persisted-admission errors and receipts stay separate. Registry activation/promotion/deletion notifier text now uses old report identity/tool display only, not new readiness/removal evidence. Original info type/positions/hasUI gate/callback exceptions remain; ordinary UI has no borrowed model16KiB limit. Multiline text stays literal/native-wrapped, malformed selected name is explicitly unavailable, and RPC message forwarding does not certify display or handling. Loaded terminal/phone remains separately gated. Recipe registry watcher warning/refresh notices now use AX report plus original opaque repair instruction, without changing direct ctx.ui.notify, pending/dedup/load/callback failures. The old ~/.pi/agent/recipes report is not freshly verified root metadata; it does not authorize restart, actors_tool_register replay or reload. Startup registry warnings now expose category sequences including singletons, preserving original selected diagnostics and existing shadow/bash suppression. Authored labels stay inside values; malformed selected text is unavailable, no borrowed model cap or recovered private tail. Doctor advice stays opaque instruction, not automatic inspection. Formatting still precedes runtime.notify/hasUI; a report/fault does not undo prior scan/registry effects.
 
 Distinguish persistence, registry admission, host registration, active-tool membership, and `callable_now`. Confirm the source identity, effective caller schema, separate tool/spawn usage, and last launch kind when exposed.
 
-If persistence succeeded but callability is false, do not use `spawn` and claim the tool worked. Follow the reported activation boundary or stop.
+If persistence succeeded but callability is false, do not use `actors_run_spawn` and claim the tool worked. Follow the reported activation boundary or stop.
 
 ## Run failure
 
 ```text
-inspect target=run:<id> view=recipe
-inspect target=run:<id> view=trace
-inspect target=run:<id> view=control
-inspect target=runtime view=status
+actors_inspect target=run:<id> view=recipe
+actors_inspect target=run:<id> view=trace
+actors_inspect target=run:<id> view=control
+actors_inspect target=runtime view=status
 ```
 
 Use Recipe view for captured identity/launch evidence, Trace for bounded observations, Control for readiness/capacity/stale work, and runtime status for kernel-level health. Treat retained-history completeness honestly.

package/dist/skills/actors/references/persistent-tools.md

@@ -1,26 +1,30 @@
 # Persistent Tools
 
-Use a persistent tool when the agent should call a trusted capability by name across turns or sessions. Use `spawn` instead for one-off Recipe execution.
+Use a persistent tool when the agent should call a trusted capability by name across turns or sessions. Use `actors_run_spawn` instead for one-off Recipe execution.
 
 ## Select the capability, not the execution mode
 
 Both sync and async Recipes can be tools. Sync invocation awaits the result; async invocation returns a launch receipt and the eventual result arrives separately. Neither synchrony nor a model-backed implementation establishes usefulness. A subagent-backed tool launches a capability, not a saved live subagent. Synchronous tools execute inline; non-singleton async calls launch Run executions, while singleton attachment follows its existing compatibility contract.
 
-Prefer a stable purpose/name, caller-owned parameterized inputs, a clear result/acceptance boundary, understood effects and failure/cancellation limits, and meaningful leverage over existing tools or one-off `spawn`. Do not register every transient mission or a generic arbitrary-prompt alias merely to add a name. A successful registration is not permission for new effects, and a launch receipt is not successful task completion.
+Prefer a stable purpose/name, caller-owned parameterized inputs, a clear result/acceptance boundary, understood effects and failure/cancellation limits, and meaningful leverage over existing tools or one-off `actors_run_spawn`. Do not register every transient mission or a generic arbitrary-prompt alias merely to add a name. A successful registration is not permission for new effects, and a launch receipt is not successful task completion.
 
-Current user-root Recipes are tool candidates by location; Skill components do not become tools automatically. Explicit create-only retention is supported through `register_tool expose=false`; it is separate from tool exposure. Automatic retained lifecycle is not implemented. Read-only `inspect target=recipes view=summary` reports retained counts for `recipes/library`; use `verbose=true` for exact `retained` paths, resolved mode, invalid/disabled state and diagnostics. Reuse a valid enabled entry through `spawn recipe=<exact path>` with required caller values, or deliberately register it with `from=<exact path>`. A stored definition is not review, activation or Run evidence; use `tool:<name>` for activation and `runtime view=runs` for running instances. A `library/<stem>` usage-lineage label is private accounting identity, not a callable name or Skill Recipe reference; reuse the exact file path from inspection. Do not populate or migrate the live registry manually. `expose` is a registration input, not a Recipe field; do not invent review actions or bypass unsupported retained mutations. Existing explicit `register_tool` works for both modes; automatic review remains under its existing policy. Launch counts and value-free structural review alone do not establish semantic purpose, a good name, or accepted useful reuse.
+Current user-root Recipes are tool candidates by location; Skill components do not become tools automatically. Explicit create-only retention is supported through `actors_tool_register expose=false`; it is separate from tool exposure. Automatic retained lifecycle is not implemented. Read-only `actors_inspect target=recipes view=summary` reports retained counts for `recipes/library`; use `verbose=true` for exact `retained` paths, resolved mode, invalid/disabled state and diagnostics. Reuse a valid enabled entry through `actors_run_spawn recipe=<exact path>` with required caller values, or deliberately register it with `from=<exact path>`. A stored definition is not review, activation or Run evidence; use `tool:<name>` for activation and `runtime view=runs` for running instances. A `library/<stem>` usage-lineage label is private accounting identity, not a callable name or Skill Recipe reference; reuse the exact file path from inspection. Do not populate or migrate the live registry manually. `expose` is a registration input, not a Recipe field; do not invent review actions or bypass unsupported retained mutations. Existing explicit `actors_tool_register` works for both modes; automatic review remains under its existing policy. Launch counts and value-free structural review alone do not establish semantic purpose, a good name, or accepted useful reuse.
+
+## Names and ownership
+
+Use `actors_tool_register` for new calls; explicit legacy `register_tool` calls share its dispatch contract. Name new exposed tools under the functional owner, for example `audio_transcribe` or `repo_check`. Preserve already persisted names instead of silently prefixing them. The namespace is a caller naming rule, not a Recipe field or identity migration. A normalized collision against any foreign host tool, even an inactive one, refuses exposure/update; `update=true` never authorizes a foreign overwrite. Inspect the original logical capability and stop rather than choosing a misleading generic alias to bypass that refusal. Retention without exposure remains separate.
 
 ## Choose one source mode
 
 ```text
 Maintained or explicit-file Recipe
-→ register_tool from=<skill>/<recipe|path.json|path.md>
+→ actors_tool_register from=<skill>/<recipe|path.json|path.md>
 
 Trusted command template
-→ register_tool template="..."
+→ actors_tool_register template="..."
 
 Reviewed captured draft
-→ register_tool draft=<draft-path>
+→ actors_tool_register draft=<draft-path>
 ```
 
 Do not mix source modes.
@@ -28,7 +32,7 @@ Do not mix source modes.
 ## Specialize a maintained Recipe
 
 ```text
-register_tool
+actors_tool_register
   name=music_player
   from=music-player/playback
   defaults={"source":"~/Music/1MIX"}
@@ -42,11 +46,11 @@ Use `description` to narrow agent-facing intent when useful. Every supplied defa
 
 ## Retain without exposing a tool
 
-Use `register_tool name=<name> expose=false from=<skill>/<recipe>` or a trusted `template` source to create `recipes/library/<name>.json`. A description is still required for authored command templates; source defaults/args/origins still belong to the maintained Recipe. This is create-only: retained `update=true`, null/empty deletion, `draft` mode and direct Recipe dependencies on managed disposable drafts are rejected, including Recipe-valued template leaves. A duplicate retained JSON/Markdown stem is a conflict; no older file is overwritten.
+Use `actors_tool_register name=<name> expose=false from=<skill>/<recipe>` or a trusted `template` source to create `recipes/library/<name>.json`. A description is still required for authored command templates; source defaults/args/origins still belong to the maintained Recipe. This is create-only: retained `update=true`, null/empty deletion, `draft` mode and direct Recipe dependencies on managed disposable drafts are rejected, including Recipe-valued template leaves. A duplicate retained JSON/Markdown stem is a conflict; no older file is overwritten.
 
-The `kind: retained_recipe`, `activation: not_requested` receipt confirms persistence/admission, not host activation or review. It returns the exact Recipe path and required/optional argument names, without global callability flags or default values. A same-named tool is left untouched. Use the exact returned path with `spawn`; if compact output omits the whole path, follow its read-only verbose Recipe inspection hint rather than guessing it. Retention records no launch and makes no self-contained-backup promise for referenced sources.
+The `kind: retained_recipe`, `activation: not_requested` receipt confirms persistence/admission, not host activation or review. It returns the exact Recipe path and required/optional argument names, without global callability flags or default values. A same-named tool is left untouched. Use the exact returned path with `actors_run_spawn`; if compact output omits the whole path, follow its read-only verbose Recipe inspection hint rather than guessing it. Retention records no launch and makes no self-contained-backup promise for referenced sources.
 
-To expose a retained capability deliberately, call ordinary `register_tool name=<tool> from=<exact retained path>`, prove activation below, then call the actual tool. Deleting that admitted wrapper through the ordinary deletion path leaves the retained source; it does not stop active Runs. This is not a migration or safe-retention rule for old standalone tools.
+To expose a retained capability deliberately, call ordinary `actors_tool_register name=<tool> from=<exact retained path>`, prove activation below, then call the actual tool. Deleting that admitted wrapper through the ordinary deletion path leaves the retained source; it does not stop active Runs. This is not a migration or safe-retention rule for old standalone tools.
 
 Publication uses a complete atomic no-overwrite file link; unsupported filesystems refuse without an overwrite fallback. A storage, admission or lock-release failure can follow committed bytes. Inspect the retained inventory and preserve the original cause; do not blindly repeat the request or delete an uncertain file.
 
@@ -69,9 +73,9 @@ For tool exposure, when `callable_now` is true, call the actual generated tool a
 Use:
 
 ```text
-inspect target=tool:<name> view=status
-inspect target=tool:<name> view=schema
-inspect target=recipes view=doctor
+actors_inspect target=tool:<name> view=status
+actors_inspect target=tool:<name> view=schema
+actors_inspect target=recipes view=doctor
 ```
 
 ## Command templates
@@ -80,7 +84,7 @@ Use `template` only for a trusted command definition, not to make the agent gues
 
 ## Updates and deletion
 
-Use `update=true` only for an intentional replacement. Preserve the existing capability when candidate resolution, validation, persistence, or activation fails. Use the compact deletion form documented by the live `register_tool` schema; do not create a second deletion mechanism.
+Use `update=true` only for an intentional replacement. Preserve the existing capability when candidate resolution, validation, persistence, or activation fails. Use the compact deletion form documented by the live `actors_tool_register` schema; do not create a second deletion mechanism.
 
 ## Stop rules
 
@@ -88,7 +92,7 @@ Stop rather than:
 
 - copying source Recipe args, defaults, artifacts, Control, or helper command;
 - invoking a Skill helper by installation path;
-- using `spawn` and claiming the tool was called;
+- using `actors_run_spawn` and claiming the tool was called;
 - treating persistence as callability;
 - adding shell evaluation or backgrounding to bypass registration;
 - editing an unrelated rejected Skill component unless that repair is explicitly requested.

package/dist/skills/actors/references/recipes.md

@@ -14,7 +14,7 @@ music-player/playback
 For agent-facing persistent specialization, use:
 
 ```text
-register_tool from=music-player/playback defaults={"source":"~/Music/1MIX"}
+actors_tool_register from=music-player/playback defaults={"source":"~/Music/1MIX"}
 ```
 
 The delegated root inherits async behavior, args and types, defaults, artifacts, Control, and runtime-owned origins. Do not copy those fields into the wrapper.

package/dist/skills/actors/references/runs.md

@@ -5,7 +5,7 @@ Use a Run when execution may outlive the current turn, needs declared Control, p
 ## Launch
 
 ```text
-spawn recipe=<skill>/<recipe> values={...} as=run:<id>
+actors_run_spawn recipe=<skill>/<recipe> values={...} as=run:<id>
 ```
 
 Use the owning capability Skill to choose the Recipe and capability-specific values. Retain the returned Run id. A spawn result reports `launch_kind: "spawn"`; it is never evidence of registered-tool invocation.
@@ -19,9 +19,9 @@ Compact spawn/async-tool receipts use flat Markdown-list fields: run, state, lau
 Normally wait for the completion batch: ready trees reach an active root coordinator at the next safe model-step boundary after the full tool batch, or wake an already-idle coordinator through a debounced follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
 
 ```text
-inspect target=run:<id> view=recipe
-inspect target=run:<id> view=trace
-inspect target=run:<id> view=control
+actors_inspect target=run:<id> view=recipe
+actors_inspect target=run:<id> view=trace
+actors_inspect target=run:<id> view=control
 ```
 
 Fresh root completions use YAML frontmatter (run, state, admitted kind), followed by raw left-edge Markdown. Prepend the packet-local index only when two or more results are shown. Exactly one shown result omits its index even with omitted results; preserve omission/inventory metadata, internal member/generation/correlation and every saved message. This rule does not apply to numbered streams. New source captures put all runtime metadata above that body, with no service/file footer. files.groups gives one literal root plus relative entry paths; files.read_first names zero-based group/entry indices for the first useful source, not an automatic read. role/purpose guidance is English; Actor Markdown and path/name bytes are unchanged. External paths use separate roots; unknown bases remain explicit rather than guessed from cwd or Run id. Known cut counts alone may follow the cut body; unknown-loss warnings and packet omission/inventory facts stay in the header. Retained captures preserve their old bytes and presentation. No external #N heading, result:/preview: wrapper, list nesting, whole-body fence, Batch caption, members wrapper or routine outer counter is added. Primary/final Actor response uses kind:primary; explicit error/failure diagnostic text uses kind:diagnostic, never a launch command. Untracked fallback has no kind and keeps unknown original completeness/privacy explicit outside YAML. Known cut loss is [N characters omitted] at the cut, with no extra ellipsis or body clipping counters/flags in metadata. Unknown upstream loss remains separately unknown and does not assert a known positive omission. Exact source/generation/parent/location references remain in complete model content, with whole references or explicit omission, captured inventory recovery and non-done omitted states. The compact TUI independently renders literal headers/markers and native Markdown bodies from validated content-bound blocks; only whole header reference/location rows and framing are hidden. Expansion and invalid/missing hints reveal original text. Hashes/layout/markers establish consistency/correlation only, never authentication, read/action permission, acceptance or native truth. Authored YAML/next/tool/batch/omission lookalikes stay body content. Fresh packets share48KiB UTF-8 including service data, equally between up to64candidate rows, with256captured members and no redistribution of unused shares or fixed16KiB/2KiB text cap. Full admitted text fitting its share without upstream uncertainty has no cut marker; otherwise use the scalar/CRLF-safe prefix and exact retained-source loss. Allocation/text is frozen at admission; rendering/recovery does not reread sources or reallocate. Unsupported Pi event/control output is withheld. Source basis stays in reference metadata; retained structured coverage facts are not exposed as YAML clipping fields. Pending/queued/presented older formats—including #N records and the first frontmatter draft—keep exact bytes, hints and budgets. Encoding names are storage replay data, not public product choices, source permissions or work authority. No standing full-map instruction or automatic research/read follows; use selective same-session investigation when needed.
@@ -49,12 +49,12 @@ Compact spawn/async-tool receipts now carry `file_navigation`: observed canonica
 For an explicit file investigation, request the existing management route:
 
 ```text
-inspect target=runtime view=runs verbose=true
+actors_inspect target=runtime view=runs verbose=true
 ```
 
 Its `navigation` selects only the actual current logical session's already cataloged, generation-checked directories. Start at the root's context index/result, then follow selected locations with ordinary file tools; no original producer key is needed. Resuming the same saved session after restart retains this research scope; a new/forked/cloned session does not inherit it through copied history or paths.
 
-The ordinary map keeps independent roots latest-registration-first and puts known failed child subtrees before other siblings without moving a descendant ahead of its ancestors. For an explicit failed investigation use inspect target=runtime view=runs status=failed verbose=true. This filters inventory, not navigation: the full owned map then puts observed failed root subtrees first, with recency as the stable peer tie-break. Its priority.root_order is latest_registration or failed_subtrees_first and priority.basis=observed_failed_rows; missing/unmatched observations remain unranked, not proof of success. Ordering grants no ownership/terminal/native authority and does not read extra evidence or rewrite the catalog.
+The ordinary map keeps independent roots latest-registration-first and puts known failed child subtrees before other siblings without moving a descendant ahead of its ancestors. For an explicit failed investigation use actors_inspect target=runtime view=runs status=failed verbose=true. This filters inventory, not navigation: the full owned map then puts observed failed root subtrees first, with recency as the stable peer tie-break. Its priority.root_order is latest_registration or failed_subtrees_first and priority.basis=observed_failed_rows; missing/unmatched observations remain unranked, not proof of success. Ordering grants no ownership/terminal/native authority and does not read extra evidence or rewrite the catalog.
 
 This bounded map marks file_inventory_scope=canonical_starting_locations and reports file locations, observed sizes and format_hint (json/jsonl/text). Hints describe the expected layout, not validated syntax/UTF-8 or complete output; it is not a full file inventory, body, original privacy, terminal/clock/native truth or authority to change state. Missing/nonregular/stale locations stay unavailable, whole-row omission counts are explicit, and corrupt/missing catalogs report `catalog_unavailable` without repair or turning healthy Runs into failures. New launches and explicit compatible singleton attachments register their exact existing generation; reads never scan/backfill missing entries. A `catalog: unavailable` launch warning means that separate registration attempt did not complete, not that the work failed. Do not relaunch merely to repair the map; even failed publication can leave committed catalog bytes. Current ordering covers directly owned rows and their exact same-session parent links, not a complete cross-session descendant tree. Compact/default inspection still does not build a map. Launch text offers that request as a fallback when no complete direct row is shown; existing new-outcome formats retain their optional request. Neither embeds a session-wide map or file bodies.
 
@@ -73,7 +73,7 @@ Do not infer successful native closure from a teardown count, signal attempt or
 Send an actor-local action only when the root Recipe declares and implements it:
 
 ```text
-message target=run:<id> action=<declared-action> input={...}
+actors_control_apply target=run:<id> action=<declared-action> input={...}
 ```
 
 Inspect Control when readiness, capacity, stale work, or saturation matters. Put large data in an artifact and send only a bounded reference or instruction. Use runtime-owned termination for a stuck Run rather than inventing undeclared service actions.

package/dist/skills/music-player/SKILL.md

@@ -16,10 +16,10 @@ When a Telegram-originated turn or explicit Telegram-control question makes repe
 `music-player/playback` is a singleton async controlled service with the canonical address `run:music-player`. The Recipe is the sole lifecycle owner: it starts the service, supervises it, and stops playback when the Run closes. The service owns queue, backend, checkpoint, and playback state. `scripts/playback.mjs` owns both foreground playback and the bounded control CLI. Its `control <state-dir> <action> [percent]` entrypoint observes or controls an existing owner without starting, adopting, or supervising it. Explicit foreground `serve` supports a caller-owned standalone host without importing the Actor runtime; Actor and standalone ownership of one state directory are mutually exclusive.
 
 ```text
-spawn recipe=music-player/playback values={"source":"~/Music","player":"auto"}
-message target=run:music-player action=pause
-message target=run:music-player action=next
-inspect target=run:music-player view=control
+actors_run_spawn recipe=music-player/playback values={"source":"~/Music","player":"auto"}
+actors_control_apply target=run:music-player action=pause
+actors_control_apply target=run:music-player action=next
+actors_inspect target=run:music-player view=control
 ```
 
 A repeated compatible spawn returns the healthy active singleton instead of launching a second player. A terminal or dead singleton restarts under the same Run id with a fresh fenced generation and restores its validated playback checkpoint when the source and configuration still match.

package/dist/skills/music-player/scripts/playback.mjs

@@ -112,7 +112,7 @@ function usage() {
 Runs a foreground music player so pi-actors can own it as a controlled Run.
 Actor-owned controls use canonical records in <state-dir>/controls.jsonl.
 Standalone controls use the generation-fenced playback service endpoint.
-Prefer message target=run:<run> action=<command> for Actors; external adapters use control <state-dir> <action>.
+Prefer actors_control_apply target=run:<run> action=<command> for Actors; external adapters use control <state-dir> <action>.
 Supported players: auto, mpv, afplay, ffplay, cvlc, play, wmp.
 `);
 }

package/dist/skills/recipe-memory/SKILL.md

@@ -11,13 +11,13 @@ Use this Skill only when automatic draft-memory or active-tool review needs diag
 
 Automatic reviewers receive value-free contract shape, risk labels, usage counts, and batch-local equality groups, not executable content, descriptions, paths, or canonical names. Structural evidence and launch counts alone do not establish semantic purpose, good tool names, successful reuse, or accepted outcomes. Promotion preserves unchanged captured executable content; it does not generalize a one-off mission.
 
-Explicit create-only retention is owned by `actors` through `register_tool expose=false`, not by these internal reviewers. Automatic retained lifecycle is not implemented. Current draft promote/discard and tool-review behavior are unchanged. Missing evidence is unknown; this guidance adds no retain/defer action, retry permission, automatic rewrite, or live migration. Do not bypass confidentiality or edit review state to simulate the future policy.
+Explicit create-only retention is owned by `actors` through `actors_tool_register expose=false`, not by these internal reviewers. Automatic retained lifecycle is not implemented. Current draft promote/discard and tool-review behavior are unchanged. Missing evidence is unknown; this guidance adds no retain/defer action, retry permission, automatic rewrite, or live migration. Do not bypass confidentiality or edit review state to simulate the future policy.
 
 ## Diagnose first
 
 ```text
-inspect target=recipes view=reviews
-inspect target=runtime view=triage
+actors_inspect target=recipes view=reviews
+actors_inspect target=runtime view=triage
 ```
 
 Use the review view to distinguish `draft` and `tool` scope, current phase, failed stage, bounded error, preserved transaction evidence, and the recorded next action. Use runtime triage only when the reviewer Run itself needs Run-level diagnosis. Follow `actors` for generic Inspect, Run, and Control semantics.
@@ -27,10 +27,10 @@ Use the review view to distinguish `draft` and `tool` scope, current phase, fail
 Use runtime Controls only when the review evidence names the matching recovery action:
 
 ```text
-message target=runtime action=review.retry input={"scope":"draft"}
-message target=runtime action=review.retry input={"scope":"tool"}
-message target=runtime action=review.reset input={"scope":"draft"}
-message target=runtime action=review.reset input={"scope":"tool"}
+actors_control_apply target=runtime action=review.retry input={"scope":"draft"}
+actors_control_apply target=runtime action=review.retry input={"scope":"tool"}
+actors_control_apply target=runtime action=review.reset input={"scope":"draft"}
+actors_control_apply target=runtime action=review.reset input={"scope":"tool"}
 ```
 
 - `review.retry` resumes the selected failed review scope while preserving authenticated transaction recovery.

package/docs/README.md

@@ -11,8 +11,8 @@ Living index of all documentation in the `/docs` directory.
 - [async-runs.md](./async-runs.md) — Run lifecycle, state, Control, Trace, cancellation, and terminal reconciliation
 - [coordinator-delivery.md](./coordinator-delivery.md) — Active model-step completion overlays, idle batching, durable acceptance, explicit urgent Pi steering, and the adopted completion-stream contract under implementation (not enabled)
 - [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
+- [inspection.md](./inspection.md) — Complete `actors_inspect` target/view matrix, authorization boundaries, and diagnostic routes
+- [tool-registry.md](./tool-registry.md) — Local `pi-actors` registry storage and `actors_tool_register` 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

@@ -132,4 +132,4 @@ Run kill revalidates owner and generation through the canonical lifecycle path.
 
 ## 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|runs|triage`, `inspect target=recipes view=status|summary|doctor|imports|reviews` (`registry` is the same view as `summary`), and `inspect target=tool:<name> view=status|schema` for non-Run management targets. See [Management Inspection](./inspection.md) for exact applicability and authorization boundaries.
+The Actor Inspector treats each Run as a concrete actor instance. It does not expose group conversations, peer addresses, routing, or communication topology. Use `actors_inspect target=runtime view=status|runs|triage`, `actors_inspect target=recipes view=status|summary|doctor|imports|reviews` (`registry` is the same view as `summary`), and `actors_inspect target=tool:<name> view=status|schema` for non-Run management targets. See [Management Inspection](./inspection.md) for exact applicability and authorization boundaries.