@llblab/pi-actors 0.58.1 → 0.58.3

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,24 +289,44 @@ 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,
   ];
 }
 
+/** Read-free projection of already selected location facts; never a complete inventory or body certificate. */
+function compactRunFileNavigation(value: unknown, terminal: boolean): unknown {
+  const navigation = asRecord(value);
+  if (navigation.state !== "available") return value;
+  if (!Array.isArray(navigation.files)) return value;
+  const paths: Record<string, unknown> = {};
+  const unavailable: string[] = [];
+  const selected = ["context_index", "result", "execution", "metadata"];
+  for (const file of navigation.files) {
+    const item = asRecord(file);
+    if (item.state === "unavailable") unavailable.push(String(item.role));
+    if (item.state === "present" && selected.includes(String(item.role))) paths[String(item.role)] = item.path;
+  }
+  const facts = [
+    ...(unavailable.length ? [`Unavailable locations: ${unavailable.join(", ")}`] : []),
+    ...(terminal && navigation.files.some(file => asRecord(file).role === "result" && asRecord(file).state === "missing") ? ["Recorded result location missing"] : []),
+  ];
+  return { directory: navigation.directory, ...paths, ...(facts.length ? { status: facts.join("; ") } : {}) };
+}
+
 export function compactAsyncRunStatus(value: unknown): string {
   const status = asRecord(value), progress = asRecord(status.progress), result = asRecord(status.result);
   const run = String(status.run ?? "<unknown>"), displayRun = run.startsWith("run:") ? run.slice(4) : run;
@@ -329,7 +349,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) {
@@ -358,8 +378,7 @@ export function compactAsyncRunStatus(value: unknown): string {
   const navigationRendering = hasNavigation ? renderYamlMetadata({ run_files: navigation }, budget) : undefined;
   const invalidNavigation = navigationRendering?.state === "unavailable" && navigationRendering.reason === "metadata_invalid";
   const locations = !hasNavigation ? {} : { run_files: invalidNavigation
-    ? { state: "unavailable", reason: "metadata_invalid" } : navigation,
-    run_files_observation: "Observed locations; mutable." };
+    ? { state: "unavailable", reason: "metadata_invalid" } : compactRunFileNavigation(navigation, ["done", "failed", "killed", "exited"].includes(String(core.state))) };
   const full = render({ ...fields, ...locations, ...(direct && !invalidNavigation ? {} : hint) });
   if (full !== undefined) return full;
   const omitted = !hasNavigation ? {} : { run_files: { state: "omitted", reason: "response_too_large", shown: 0, omitted: 1, total: 1 } };
@@ -509,25 +528,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 +558,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 +568,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 +578,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.3",
   "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.
+Compact launch receipts include `run_files` as bare nested YAML with useful exact observed context-index/result/execution/metadata paths and any unavailable-location status, only after current-session/physical identity admission. Routine absent optional files and repeated format/size/mutable/generation metadata stay out of compact content; unavailable or over-budget rows remain explicit. 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 useful source/artifact and observed context-index/result/execution paths (metadata fallback) under literal roots with relative entries, role/name, concise admitted status and a read_first group/entry pointer; no cwd guess, source refresh or automatic read follows. Unknown bases stay explicit. Source status preserves admission privacy, Actor-response/exported-text and diagnostic-metadata-only distinctions; declarations remain unverified. Unavailable locations and missing terminal-result locations stay visible. Full generation/hash/location facts stay in machine detail/saved snapshots, not repeated per file. 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/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/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/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.