@llblab/pi-actors 0.58.1 → 0.58.2

package/lib/tool-review-scheduler.ts

@@ -404,7 +404,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
         ...state,
         failedStage: "approval_state",
         lastError: "approved review path is unavailable",
-        nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+        nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
         phase: "processing_failed" as const,
         updatedAt: (options.now ?? (() => new Date()))().toISOString(),
       };
@@ -427,7 +427,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
           ...state,
           failedStage: "transaction",
           lastError: `tool review transaction remained ${transaction.phase}`,
-          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+          nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: "processing_failed" as const,
           updatedAt: (options.now ?? (() => new Date()))().toISOString(),
         };
@@ -458,7 +458,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
           ...pending,
           failedStage: "lineage",
           lastError: error instanceof Error ? error.message : String(error),
-          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+          nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
         };
         writeJsonAtomic(statePath, failedPending);
         return { outcome: "lineage_pending", state: failedPending };
@@ -478,7 +478,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
         ...state,
         failedStage: "transaction",
         lastError: error instanceof Error ? error.message : String(error),
-        nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+        nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
         phase: "processing_failed" as const,
         updatedAt: (options.now ?? (() => new Date()))().toISOString(),
       };
@@ -541,7 +541,7 @@ export function createToolReviewScheduler(
           ...existing,
           failedStage: processed.stage ?? "review_result",
           lastError: processed.error ?? "automatic tool reviewer failed",
-          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+          nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: processed.outcome === "processing_failed"
             ? "processing_failed"
             : "failed",
@@ -577,7 +577,7 @@ export function createToolReviewScheduler(
             attempts: existing.attempts + 1,
             failedStage: "review_launch",
             lastError: error instanceof Error ? error.message : String(error),
-            nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+            nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
             phase: "failed",
             updatedAt: now().toISOString(),
           } satisfies ToolReviewAdmissionState);
@@ -612,7 +612,7 @@ export function createToolReviewScheduler(
           failedStage: "review_launch",
           inputPath: batch.inputPath,
           lastError: error instanceof Error ? error.message : String(error),
-          nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+          nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
           phase: "failed",
           reviewerInputPath: batch.reviewerInputPath,
           reviewId: batch.reviewId,

package/lib/tools-access.ts

@@ -55,7 +55,7 @@ export function sessionMismatchError(input: {
     ),
     {
       current_session: input.currentSession,
-      hint: "inspect target=runtime view=runs",
+      hint: "actors_inspect target=runtime view=runs",
       owner_session: input.expectedSession,
       reason: "session_mismatch",
       run: input.run,

package/lib/tools-inspect.ts

@@ -171,13 +171,13 @@ function runtimeTriage(
     trace_diagnostic_count: traceDiagnostics.length, trace_diagnostics: traceDiagnostics.slice(0, 40),
     attention_events: attentionEvents.slice(-40).reverse(),
     next_actions: [
-      ...(failed.length ? ["inspect target=runtime view=runs status=failed"] : []),
+      ...(failed.length ? ["actors_inspect target=runtime view=runs status=failed"] : []),
       ...new Set([...staleControls, ...backpressuredRuns].slice(0, 3).map((entry) =>
-        `inspect target=run:${entry.run} view=control`,
+        `actors_inspect target=run:${entry.run} view=control`,
       )),
       ...(attentionEvents.length
         ? attentionEvents.slice(-3).map((entry) =>
-            `inspect target=run:${String(entry.run)} view=trace source=runtime`,
+            `actors_inspect target=run:${String(entry.run)} view=trace source=runtime`,
           )
         : []),
     ],
@@ -247,7 +247,7 @@ function formatInspectFailure(
     return { omittable, full, selected };
   });
   // Only producer-known read-only inspect literals become a typed next, never a parsed action.
-  const typedNext = next ? { next: { tool: "inspect", target: next[0], view: next[1] } } : undefined;
+  const typedNext = next ? { next: { tool: "actors_inspect", target: next[0], view: next[1] } } : undefined;
   const nextFallback = { next_action: omitted };
   const document = () => ({ ...Object.assign({}, ...parts.map((part) => part.selected)),
     ...(typedNext ?? nextFallback) });
@@ -412,15 +412,15 @@ function inspectRecipeIdentity(
     ...(rejectedReason ? { rejected_reason: rejectedReason } : {}),
     next_actions: resolvable
       ? [
-          `spawn recipe=${identity}`,
-          `register_tool name=<tool-name> from=${identity}`,
+          `actors_run_spawn recipe=${identity}`,
+          `actors_tool_register name=<tool-name> from=${identity}`,
         ]
       : roots.length === 0 && skill
         ? [
             `activate Skill ${skill}`,
-            `inspect target=recipes view=doctor identity=${identity}`,
+            `actors_inspect target=recipes view=doctor identity=${identity}`,
           ]
-        : ["inspect target=recipes view=imports verbose=true"],
+        : ["actors_inspect target=recipes view=imports verbose=true"],
   };
 }
 
@@ -707,7 +707,7 @@ function compactResult(target: string, view: string, details: Record<string, unk
       ? String(details.next_actions[0])
       : details.callable_now === true
         ? `call tool ${name}`
-        : `register_tool name=${name} update=true`;
+        : `actors_tool_register name=${name} update=true`;
     const hint = ToolsResponse.nextActionMetadata(next, Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
     const required = compactArguments("required_args", details.required_args);
     const optional = compactArguments("optional_args", details.optional_args);
@@ -727,7 +727,7 @@ export function createInspectToolDefinition<TContext = unknown>(
   deps: InspectToolDeps<TContext> = {},
 ): any {
   return {
-    name: "inspect",
+    name: "actors_inspect",
     label: "Inspect",
     description:
       "Inspect a Run's Recipe, Trace, or Control evidence, or runtime/recipe/tool diagnostics.",

package/lib/tools-message.ts

@@ -1,5 +1,5 @@
 /**
- * Public Control facade under the stable `message` tool name.
+ * Public Control facade under the stable `actors_control_apply` tool name.
  * Zones: Control request validation, Run/runtime dispatch, recipient-scoped receipts
  * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */
@@ -52,9 +52,9 @@ function controlDocument(render: () => ControlDocument, order: readonly ControlP
 
 /** Only producer-known read-only inspect literals become typed next; other advice stays opaque content. */
 function controlNextPart(action: string): ControlPart {
-  const inspect = /^inspect target=([^\s]+) view=([^\s]+)$/u.exec(action);
+  const inspect = /^actors_inspect target=([^\s]+) view=([^\s]+)$/u.exec(action);
   if (inspect) {
-    return ToolsResponse.selectYamlNode("next", { tool: "inspect", target: inspect[1], view: inspect[2] }, CONTROL_BUDGET);
+    return ToolsResponse.selectYamlNode("next", { tool: "actors_inspect", target: inspect[1], view: inspect[2] }, CONTROL_BUDGET);
   }
   const wellFormed = action.isWellFormed();
   const omitted: ControlDocument = { next: { instruction: wellFormed ? "[omitted]" : "[unavailable]",
@@ -123,15 +123,15 @@ export function compactControlResult(
 }
 
 function runNextActions(run: string, result: Record<string, unknown>): string[] {
-  if (result.stopped === true) return [`inspect target=run:${run} view=trace`];
+  if (result.stopped === true) return [`actors_inspect target=run:${run} view=trace`];
   if (result.stopped === false || result.archived === false || result.pruned === false) {
     if (result.reason === "ownership changed" || result.reason === "run generation changed") {
-      return ["inspect target=runtime view=runs"];
+      return ["actors_inspect target=runtime view=runs"];
     }
-    if (result.stopped === false && result.reason !== "not running") return [`inspect target=run:${run} view=trace`];
+    if (result.stopped === false && result.reason !== "not running") return [`actors_inspect target=run:${run} view=trace`];
   }
   if (result.delivery === "queued" || result.delivery === "delivered") {
-    return [`inspect target=run:${run} view=control`];
+    return [`actors_inspect target=run:${run} view=control`];
   }
   return [];
 }
@@ -148,10 +148,10 @@ export function createControlToolDefinition<TContext = unknown>(
   deps: ControlToolDeps = {},
 ): any {
   return {
-    name: "message",
+    name: "actors_control_apply",
     label: "Control",
     description:
-      "Apply one Control action to an existing Run or the pi-actors runtime.",
+      "Apply one Run/runtime Control action. This is not chat or peer messaging.",
     parameters: Schema.objectSchema(
       {
         target: Schema.stringSchema("Run target run:<id>, or literal runtime."),
@@ -260,7 +260,7 @@ export function createControlToolDefinition<TContext = unknown>(
             // Admission-era correlation is not current reply-scope proof after an awaited dispatch.
             // Display one whole caller-owned id or an explicit whole-id omission; the warning stays literal.
             const identity = controlSelected("run", run);
-            const next = controlNextPart("inspect target=runtime view=runs");
+            const next = controlNextPart("actors_inspect target=runtime view=runs");
             const render = (): ControlDocument => ({ ...identity.selected, action: request.action,
               result: "request failed", delivery: "unconfirmed", handling: "unconfirmed",
               warning: "Effects may already exist.\nDo not repeat automatically.", ...next.selected });

package/lib/tools-register.ts

@@ -1,7 +1,7 @@
 /**
- * Public register_tool behavior
- * Zones: runtime tool registration, tool registry mutation, register_tool schema
- * Owns the public register_tool definition that persists local agent capabilities
+ * Public actors_tool_register behavior
+ * Zones: runtime tool registration, tool registry mutation, actors_tool_register schema
+ * Owns the public actors_tool_register definition that persists local agent capabilities
  */
 
 import * as Prompts from "./prompts.ts";
@@ -24,7 +24,7 @@ export function createRegisterToolDefinition<TContext>(
   deps: RegisterToolRuntimeDeps<TContext>,
 ) {
   return {
-    name: "register_tool",
+    name: "actors_tool_register",
     label: "Register Tool",
     description: Prompts.REGISTER_TOOL_DESCRIPTION,
     promptSnippet: Prompts.REGISTER_TOOL_PROMPT_SNIPPET,

package/lib/tools-response.ts

@@ -154,8 +154,8 @@ export function formatMarkdownField(key: string, value: string, depth = 0): stri
     : `${indent}- ${key}: ${value}`;
 }
 
-export function formatInspectNextAction(target: string, view: string, verbose?: boolean): string {
-  return ["- next:", formatMarkdownField("tool", "inspect", 1), formatMarkdownField("target", target, 1),
+export function formatInspectNextAction(target: string, view: string, verbose?: boolean, tool = "inspect"): string {
+  return ["- next:", formatMarkdownField("tool", tool, 1), formatMarkdownField("target", target, 1),
     formatMarkdownField("view", view, 1), ...(verbose === undefined ? [] : [formatMarkdownField("verbose", String(verbose), 1)])].join("\n");
 }
 
@@ -289,20 +289,20 @@ function launchModelPolicy(value: unknown): Record<string, unknown> {
   return fields;
 }
 
-const RUN_FILE_INVESTIGATION_COMMAND = "inspect target=runtime view=runs verbose=true";
+const RUN_FILE_INVESTIGATION_COMMAND = "actors_inspect target=runtime view=runs verbose=true";
 
 /** Frozen older completion-format text: new launch layout must not change this shared packet helper. */
 export function formatRunFileNavigationHandoff(): string {
-  return `Files (optional; current session):\n\`${RUN_FILE_INVESTIGATION_COMMAND}\``;
+  return "Files (optional; current session):\n`inspect target=runtime view=runs verbose=true`";
 }
 
 export function runNextActions(run: unknown): string[] {
   const id = String(run ?? "").trim();
   if (!id) return [];
   return [
-    `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`,
     RUN_FILE_INVESTIGATION_COMMAND,
   ];
 }
@@ -329,7 +329,7 @@ export function compactAsyncRunStatus(value: unknown): string {
   }
   if (result.killed === true) fields.killed = true;
   if (status.draft_recipe) fields.draft_recipe = String(status.draft_recipe);
-  const hint = { file_investigation: "optional; current session", next: { tool: "inspect", target: "runtime", view: "runs", verbose: true } };
+  const hint = { file_investigation: "optional; current session", next: { tool: "actors_inspect", target: "runtime", view: "runs", verbose: true } };
   const hasNavigation = Object.hasOwn(status, "file_navigation");
   let navigation: unknown;
   if (hasNavigation) {
@@ -509,25 +509,25 @@ export function recipeRegistryNextActions(
     : 0;
   const topAction = asRecord(summary.top_action);
   if (view !== "doctor" && (invalid > 0 || diagnostics > 0)) {
-    actions.push("inspect target=recipes view=doctor");
+    actions.push("actors_inspect target=recipes view=doctor");
   }
   if (view === "doctor" && typeof topAction.action === "string") {
     actions.push(String(topAction.action));
   }
   if (summary.skill_recipe_catalog_partial === true) {
-    actions.push("inspect target=recipes view=imports verbose=true");
+    actions.push("actors_inspect target=recipes view=imports verbose=true");
   }
   if (
     (Array.isArray(summary.retained) && summary.retained.length > 0) ||
     (Array.isArray(summary.retained_diagnostics) && summary.retained_diagnostics.length > 0)
   ) {
-    actions.push("inspect target=recipes view=summary verbose=true");
+    actions.push("actors_inspect target=recipes view=summary verbose=true");
   }
   if (drafts.length > 0) {
-    actions.push("inspect target=recipes view=summary verbose=true");
+    actions.push("actors_inspect target=recipes view=summary verbose=true");
     const firstPath =
       typeof drafts[0]?.path === "string" ? drafts[0].path : undefined;
-    if (firstPath) actions.push(`spawn file=${firstPath}`);
+    if (firstPath) actions.push(`actors_run_spawn file=${firstPath}`);
   }
   return [...new Set(actions)].slice(0, 4);
 }
@@ -539,9 +539,9 @@ export function compactYamlDocument(value: Record<string, unknown>): string {
 }
 
 function recipeInspectionHint(action: string): { view: "doctor" | "imports" | "summary"; verbose?: true } | undefined {
-  if (action === "inspect target=recipes view=doctor") return { view: "doctor" };
-  if (action === "inspect target=recipes view=imports verbose=true") return { view: "imports", verbose: true };
-  if (action === "inspect target=recipes view=summary verbose=true") return { view: "summary", verbose: true };
+  if (action === "actors_inspect target=recipes view=doctor") return { view: "doctor" };
+  if (action === "actors_inspect target=recipes view=imports verbose=true") return { view: "imports", verbose: true };
+  if (action === "actors_inspect target=recipes view=summary verbose=true") return { view: "summary", verbose: true };
   return undefined;
 }
 
@@ -549,7 +549,7 @@ function recipeInspectionHint(action: string): { view: "doctor" | "imports" | "s
 export function nextActionMetadata(action: string, byteBudget: number): YamlPart {
   const hint = recipeInspectionHint(action);
   if (hint) {
-    const typed = { next: { tool: "inspect", target: "recipes", ...hint } };
+    const typed = { next: { tool: "actors_inspect", target: "recipes", ...hint } };
     return { full: typed, selected: typed };
   }
   const instruction = selectYamlField("instruction", action, byteBudget);
@@ -559,7 +559,7 @@ export function nextActionMetadata(action: string, byteBudget: number): YamlPart
 /** Only these existing read-only inspection hints become action nodes; other advice stays content. */
 export function formatInspectionHint(action: string): string {
   const hint = recipeInspectionHint(action);
-  return hint ? formatInspectNextAction("recipes", hint.view, hint.verbose) : formatMarkdownField("instruction", action);
+  return hint ? formatInspectNextAction("recipes", hint.view, hint.verbose, "actors_inspect") : formatMarkdownField("instruction", action);
 }
 
 export function compactRecipeRegistry(

package/lib/tools-spawn.ts

@@ -124,7 +124,7 @@ export function createSpawnToolDefinition<
   TContext extends SpawnToolContext,
 >(): any {
   return {
-    name: "spawn",
+    name: "actors_run_spawn",
     label: "Spawn",
     description:
       "Create one controllable Run from a Recipe file or inline command template.",

package/lib/tools.ts

@@ -54,12 +54,40 @@ export const RESERVED_TOOL_NAMES = new Set([
   "find",
   "grep",
   "ls",
+  "actors_tool_register",
+  "actors_run_spawn",
+  "actors_control_apply",
+  "actors_inspect",
   "register_tool",
   "message",
   "spawn",
   "inspect",
 ]);
 
+// Compatibility dispatch is registered but omitted from model declarations and normal
+// callable listings. Active legacy names still execute saved native tool calls.
+export const LEGACY_TOOL_NAMES = {
+  register_tool: "actors_tool_register",
+  spawn: "actors_run_spawn",
+  message: "actors_control_apply",
+  inspect: "actors_inspect",
+} as const;
+
+export function createLegacyActorToolDefinitions(
+  definitions: ActorToolDefinition[],
+): ActorToolDefinition[] {
+  return Object.entries(LEGACY_TOOL_NAMES).map(([name, canonical]) => {
+    const definition = definitions.find((tool) => tool.name === canonical);
+    if (!definition) throw new Error(`Missing canonical actor tool: ${canonical}`);
+    return {
+      ...definition, name, exposure: "deferred",
+      description: `Compatibility dispatch for ${canonical}; use the canonical tool for new calls.`,
+      promptSnippet: undefined, promptGuidelines: undefined,
+      prepareLoadout: () => ({ hiddenDeclarations: Object.keys(LEGACY_TOOL_NAMES) }),
+    };
+  });
+}
+
 export function createCoreActorToolDefinitions<
   TContext extends RuntimeToolContext,
 >(deps: CoreActorToolDefinitionDeps<TContext>): ActorToolDefinition[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.58.1",
+  "version": "0.58.2",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/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