@llblab/pi-actors 0.47.0 → 0.48.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+> Each release keeps at most 8 outcome records of at most 512 characters.
+
+## 0.48.1: Persistent Skill Composition
+
+- `Persistent Skill Composition`: Made `register_tool from=<skill>/<recipe>` use Pi's authoritative active-session Skill snapshot across every admitted Skill location and activate synchronous or asynchronous tools from the resolved effective contract. Compact user Recipes retain logical delegation without copied contracts, absolute helper paths, symlinks, or ambient runtime re-resolution.
+
+## 0.48.0: Host-Coordinated Swarms
+
+- `Coordinator And Swarm Methodology`: Defined gatewayless host coordination with companion transports as presence only; the coordinator accepts declarative outcomes, creates explicit Runs, stays available, and owns integration/final validation. Reasoning is role-allocated: bounded authors default off, independent reviewers/integrators use medium, and the coordinator selects evidence-worthy fanout. Swarm retains overhead admission, disjoint ownership, isolation, mutation freeze, and event/timer observation.
+
 ## 0.47.0: Agent-Native Actor UX
 
 - `Skill-First Operation`: Replaced the injected product manual with a compact Skill-routing meta-protocol. `actors` is now the decision-first authority for generic Recipe/tool/Run mechanics, capability Skills own capability choice, and `swarm` owns only multi-actor methodology.
@@ -7,7 +17,6 @@
 - `Registration Truth UX`: Registration now reports logical source, effective required/optional args, persistence, registry/host/active-tool state, callability, activation boundary, and bounded next actions without raw config or executable template payloads. Failed activation retains rollback guarantees.
 - `Focused Diagnosis`: Added `inspect target=recipes view=doctor identity=<skill>/<recipe>` with active ownership, exact resolvability, partial-catalog state, portable source, generation, rejection, and next actions. Tool status now includes source, effective args, activation boundary, and separate spawn/tool usage.
 - `Capability Protocols`: Rewrote all six Skill descriptions as routing triggers and made Media, Artifacts, Project Work, and Recipe Memory compact agent operating guides. Human installation, product, catalog, development, and release guidance remains independently owned by README/docs.
-- `Swarm Methodology`: Reduced Swarm to overhead admission, decomposition, disjoint ownership, lenses, quorum, conflict evidence, integration, and stop rules; moved deep review/development methods to Skill-local references and delegated all generic Run/Recipe mechanics to `actors`.
 - `Safe Recovery`: Inactive, missing, duplicate, removed, malformed, rejected, partial-catalog, and inactive-tool failures now preserve logical identity, redact physical Skill paths, and teach bounded public diagnosis/retry actions without copied contracts, helper paths, shell evaluation, backgrounding, or spawn substitution.
 - `Journey and Package Evidence`: Added deterministic Journeys A-G, reviewed fresh-agent Journey B evidence, and packed first-session parity for final Skills/prompt/references, `from` registration, source-equivalent schema, same-session activation, focused doctor, actual tool invocation, and unshipped `.agents/` evidence.
 

package/README.md

@@ -11,6 +11,12 @@ Run = Recipe + Trace + Control
 
 An **actor** is any runnable local capability: a script, tool, service, pipeline, or subagent. A **Recipe** is its reusable executable definition. `spawn` creates a **Run**—one concrete actor instance—which captures its Recipe, appends observable **Trace**, and may consume actor-local **Control**.
 
+## Local Coordinator Model
+
+Multi-instance systems commonly put instance creation and routing in an external gateway. pi-actors supports a different topology: the current Pi instance remains the coordinator, companion extensions such as Telegram provide presence, and explicit Runs perform bounded delegated work. The coordinator receives high-level outcomes, decomposes them, stays available for decisions, and owns integration plus final validation instead of becoming another undifferentiated worker.
+
+This topology does not require every task to become a subagent. Short work with one natural validation boundary stays inline; delegation pays when clean context, asynchronous execution, independent judgement, parallel ownership, or coordinator availability exceeds its coordination cost. Bounded implementation can run with reasoning off while the coordinator selectively launches clean-context reasoning-enabled reviewers; several independent reviews can provide broader evidence than one author self-review. Terminal follow-ups, durable Trace, and declared artifacts replace tight polling loops.
+
 ## Install
 
 ```bash

package/dist/lib/extension-runtime.js

@@ -127,6 +127,9 @@ export function createActorExtensionRuntime(pi) {
             Pi.registerToolDefinitions(pi, Tools.createCoreActorToolDefinitions({
                 configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
                 getActiveTools: () => pi.getActiveTools(),
+                getRecipeResolutionContext: () => activeRunContext
+                    ? getRecipeResolutionContext(activeRunContext)
+                    : undefined,
                 getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
                 getRuntimeToolStatus: runtime.getToolStatus,
                 handleRuntimeControl: automaticReview.handleControl,

package/dist/lib/registry.d.ts

@@ -5,6 +5,7 @@
  */
 import * as CommandTemplates from "./command-templates.ts";
 import * as Config from "./config.ts";
+import * as RecipesContext from "./recipes-context.ts";
 export interface RegisterToolInput {
     name?: string;
     description?: string;
@@ -55,6 +56,7 @@ export interface RegisterToolRuntimeDeps<TContext> {
     recipeRoot?: string;
     getToolNameBlocker: (name: string) => string | undefined;
     getTools: () => Map<string, Config.RegisteredTool>;
+    getRecipeResolutionContext?: () => RecipesContext.RecipeResolutionContext | undefined;
     getActiveTools: () => string[];
     notify: (ctx: TContext, message: string, type: "info" | "warning" | "error") => void;
     registerRuntimeTool: (cfg: Config.RegisteredTool) => RuntimeActivation | void;

package/dist/lib/registry.js

@@ -233,9 +233,10 @@ function getInputTemplate(value) {
     throw new Error(ExecutionOutput.formatToolText("Tool template must be a string, object, or sequence."));
 }
 function getRegistrationResolutionContext(ctx, deps) {
-    if (ctx &&
-        typeof ctx === "object" &&
-        "recipeResolutionContext" in ctx) {
+    const runtimeContext = deps.getRecipeResolutionContext?.();
+    if (runtimeContext)
+        return runtimeContext;
+    if (ctx && typeof ctx === "object" && "recipeResolutionContext" in ctx) {
         const resolutionContext = ctx.recipeResolutionContext;
         if (resolutionContext)
             return resolutionContext;
@@ -415,15 +416,18 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
     let persisted = false;
     let activation;
     let cfg;
+    let transactionStage = "persist";
     try {
         persistToolRecipe(deps, name, authoredRecipe);
         persisted = true;
+        transactionStage = "persisted_admission";
         const admitted = RecipesDiscovery.admitUserRecipe(recipePath, resolutionContext);
         if (!admitted.validated || !admitted.tool) {
             throw new Error(`Persisted tool recipe admission failed: ${admitted.diagnostics.join("; ")}`);
         }
         cfg = admitted.tool;
         tools.set(name, cfg);
+        transactionStage = "runtime_activation";
         activation = deps.registerRuntimeTool(cfg) ?? undefined;
         if (activation &&
             (!activation.host_registered ||
@@ -447,7 +451,7 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
             tools.delete(name);
         }
         deps.setActiveTools(activeBefore);
-        throw new Error(ExecutionOutput.formatToolText(`Tool registration transaction failed: ${error instanceof Error ? error.message : String(error)}`));
+        throw new Error(ExecutionOutput.formatToolText(`Tool registration transaction failed at ${transactionStage} (${resolutionContext.generation}; active Skills: ${activeSkillSummary(resolutionContext)}): ${error instanceof Error ? error.message : String(error)}`));
     }
     deps.notify(ctx, `Tool activated: ${name}`, "info");
     const templateWarnings = CommandTemplates.getCommandTemplateWarnings(typeof cfg.recipe?.template === "object" && !Array.isArray(cfg.recipe.template)

package/dist/lib/tools-local.js

@@ -93,8 +93,9 @@ export function createRuntimeToolDefinition(cfg, exec) {
     const paramSchema = {};
     const required = [];
     const isRecipe = RecipesReferences.isRecipeTool(cfg.template, cfg.recipe);
-    const isAsyncRecipe = cfg.recipe?.async === true ||
-        RecipesReferences.isAsyncRecipeReference(cfg.template);
+    const isAsyncRecipe = cfg.recipe
+        ? cfg.recipe.async === true
+        : RecipesReferences.isAsyncRecipeReference(cfg.template);
     const recipeTemplate = cfg.recipe?.template ?? RecipesReferences.getRecipeTemplate(cfg.template);
     const requiredTemplate = recipeTemplate ?? cfg.template;
     const requiredTemplateConfig = typeof requiredTemplate === "object" && !Array.isArray(requiredTemplate)
@@ -112,7 +113,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
     const requiredArgs = isRecipe && cfg.storedArgs !== undefined
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg) &&
             !Object.hasOwn(recipeInlineDefaults, arg)))
-        : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
+        : !cfg.recipe && RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
             ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
             : Schema.getRequiredToolArgNames(requiredTemplateConfig);
     for (const arg of cfg.args) {

package/dist/lib/tools.d.ts

@@ -14,6 +14,7 @@ export interface ActorToolDefinition {
 export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext> {
     configPath: string;
     getActiveTools: () => string[];
+    getRecipeResolutionContext: () => import("./recipes-context.ts").RecipeResolutionContext | undefined;
     getRuntimeTool: (name: string) => unknown;
     getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
     handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;

package/dist/lib/tools.js

@@ -30,6 +30,7 @@ export function createCoreActorToolDefinitions(deps) {
             getActiveTools: deps.getActiveTools,
             getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
             getTools: deps.registryRuntime.getTools,
+            getRecipeResolutionContext: deps.getRecipeResolutionContext,
             notify: deps.registryRuntime.notify,
             registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,
             reservedToolNames: RESERVED_TOOL_NAMES,

package/dist/skills/actors/SKILL.md

@@ -52,7 +52,7 @@ 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` creates or updates a persistent user tool. 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>`. `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`.
 
 `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.
 
@@ -76,6 +76,17 @@ Then:
 
 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).
 
+## Local coordinator topology
+
+There are two distinct multi-instance shapes:
+
+- A gateway-centric system owns ingress, agent-instance creation, routing, and lifecycle outside the agents.
+- A host-coordinator system keeps the current Pi instance as the control plane; companion extensions such as Telegram provide presence, while pi-actors creates explicit local Runs for delegated work.
+
+In host-coordinator mode, the top-level agent receives declarative outcomes, preserves user authority and global context, delegates bounded concrete execution, and owns integration plus final validation. It is not merely another worker after delegation begins. One bounded implementation worker normally runs with reasoning off; consequential output receives a separate reasoning-enabled review. Several independent participants or reviewers additionally use `swarm`.
+
+Delegation is not mandatory for every prompt. Work inline when one short bounded act has one natural validation boundary and spawning would add more coordination than isolation, latency hiding, clean context, or continued coordinator availability can repay. For admitted delegation, prefer terminal follow-up and durable Trace/artifacts; inspect on meaningful attention, operator request, or an evidence-based overdue timer rather than busy polling.
+
 ## Run workflow
 
 A Run is one concrete execution of a Recipe:

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

@@ -28,6 +28,8 @@ register_tool
 
 `from` means logical direct delegation. The source remains authoritative for async behavior, caller args and types, source defaults, artifacts, Control, and runtime-owned origins. The persistent user Recipe stores only the compact specialization; do not copy inherited fields.
 
+Resolution uses Pi's authoritative active-session Skill snapshot across every Skill location Pi admits. Registration resolves and validates the maintained source, persists only its logical `<skill>/<recipe>` reference plus caller specialization, and projects the already-resolved effective contract into the runtime tool. Never replace this composition with a copied Recipe, absolute helper path, symlink, or ambient runtime re-resolution.
+
 Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
 
 ## Prove registration

package/dist/skills/swarm/SKILL.md

@@ -9,6 +9,25 @@ Use multi-actor execution only when at least two scopes or evidence lenses are m
 
 Read `actors` first for generic Recipe, spawn, Run, Trace, Control, artifact, and lifecycle operation. This Skill owns only multi-actor methodology: decomposition, scope ownership, independence, synthesis, integration, and completion proof.
 
+## Coordinator topology
+
+A swarm can be coordinated without an external gateway. In this model the current host agent is the declarative control plane, the actor kernel creates explicit participant Runs, and companion transports provide ingress or presence without owning hidden agent creation. The coordinator retains user authority, global context, decomposition, shared-surface ownership, integration, and final validation; participants own bounded concrete tasks and report evidence.
+
+This resembles gateway orchestration in dependency direction but not in ownership: the coordinator is itself an agent instance with inspectable Runs, not an infrastructure service that implicitly creates sessions. Preserve that distinction in prompts, docs, recovery, and target routing.
+
+Once work is delegated, keep the coordinator available for decisions and integration instead of duplicating participant implementation. Wait for terminal follow-up by default; use meaningful attention or evidence-based timers for overdue work rather than a tight inspection loop.
+
+## Reasoning allocation
+
+Allocate reasoning by role instead of making one long thread implement and judge itself:
+
+- Bounded implementation/authorship participants default to reasoning off when the task card fixes scope, invariants, checks, and escalation. Enable reasoning only when unresolved diagnosis or local design judgement is part of their assignment.
+- Reviewers default to independent medium reasoning and clean context. For consequential work, several reviewers with distinct lenses or repeated independent judgement usually provide better error discovery than increasing one author's reasoning and relying on self-review.
+- Synthesizers and integrators use medium reasoning because they reconcile evidence, conflicts, shared contracts, and retained state.
+- The coordinator decides whether review fanout is worth its cost, preserves dissent, and never treats reviewer count as evidence quality by itself.
+
+Do not change a running participant's profile merely because policy changed. Replace or add a later independent review only when fresh evidence is still needed.
+
 ## Choose the shape
 
 | Need | Shape | Primary Recipe |
@@ -29,18 +48,22 @@ The coordinator owns the whole result even when participants choose local implem
 1. State the goal, non-goals, evidence standard, integration owner, and stop condition.
 2. Partition work into disjoint read or write scopes. Give shared contracts one owner.
 3. Give each participant a bounded task card with allowed scope, avoided scope, expected artifact, checks, and escalation rule.
-4. Preflight required model/tool access before expensive fanout.
-5. Launch independent work without cross-contaminating lenses. Do not let participants silently expand scope.
-6. Preserve every terminal result, including failures, disagreements, and partial evidence.
-7. Merge through one named synthesizer or integrator. Resolve conflicts from explicit intent and invariants, not textual convenience.
-8. Run fresh integrated validation and, for consequential outputs, an independent post-merge review.
-9. Report complete, degraded, or insufficient-data status honestly; name residual owners and next actions.
+4. Assign each participant an explicit execution profile and isolation mode under the reasoning-allocation contract.
+5. Preflight required model/tool access before expensive fanout.
+6. Launch independent work without cross-contaminating lenses. Do not let participants silently expand scope.
+7. Preserve every terminal result, including failures, disagreements, and partial evidence; avoid doing participant work in the coordinator while a valid owner remains active.
+8. Merge through one named synthesizer or integrator. Resolve conflicts from explicit intent and invariants, not textual convenience.
+9. Run fresh integrated validation and, for consequential outputs, an independent post-merge review.
+10. Report complete, degraded, or insufficient-data status honestly; name residual owners and next actions.
 
 ## Scope and coordination rules
 
 - One writable scope has one owner. Parallel readers may share a stable target.
 - Public contracts, schemas, central configuration, and integration surfaces require exclusive ownership.
-- Participants record out-of-scope needs instead of opportunistically editing them.
+- Concurrent writers use disjoint paths, isolated worktrees, or declared patch/artifact outputs.
+- Shared ledgers, lockfiles, generated contracts, metadata, schemas, release surfaces, and cross-domain configuration belong to one named integrator unless a task card transfers one surface to another exclusive owner.
+- Participants record shared-surface and other out-of-scope needs in handoff instead of editing them opportunistically.
+- Reasoning and model profiles are task-card inputs, not implicit properties of the whole swarm.
 - Coordinator checkpoints are bounded decision requests, not free-form actor chat.
 - Locks support scope ownership but do not replace coordinator judgement. Every lock must be bounded and releasable.
 - One integrator owns merge order, conflict resolution, and final validation.

package/dist/skills/swarm/references/development-swarm.md

@@ -14,6 +14,39 @@ Use a development swarm only when all are true:
 
 Do not parallelize implementation when tasks need the same central files, semantic ordering dominates wall-clock time, or the likely conflicts would invalidate the decomposition. Use planning or review first.
 
+## Coordinator role separation
+
+In a host-coordinator topology, the current Pi instance owns the declarative outcome and participant graph rather than acting as the default implementation worker. It may receive intent through Telegram or another companion extension, but transport does not become a gateway or gain hidden instance-creation authority; participant creation remains an explicit actor-kernel Run.
+
+The coordinator should:
+
+- Translate high-level intent into bounded task cards and dependency edges.
+- Keep user authority, shared contracts, integration order, and final validation local.
+- Remain available for checkpoints, permissions, conflicts, and changing evidence.
+- Consume terminal handoffs, durable artifacts, and Trace attention instead of mirroring participant work.
+- Check overdue work on an evidence-based timer; never replace event-driven completion with a rapid polling loop.
+
+A participant should:
+
+- Own one concrete execution or evidence boundary.
+- Avoid global orchestration and undeclared participant creation.
+- Return a bounded handoff that lets the coordinator decide without replaying the entire task.
+
+Use one ordinary Run under `actors` when only one worker is delegated. Activate this development-swarm protocol when two or more participants, parallel ownership, or explicit integration edges exist. Keep trivial single-boundary work inline when delegation overhead has no compensating value.
+
+## Reasoning profiles
+
+| Role | Default | Raise or fan out when |
+| --- | --- | --- |
+| Bounded implementation author | Reasoning off | The card explicitly owns unresolved diagnosis or design judgement |
+| Reviewer | Medium reasoning, clean context | Stakes require independent lenses or repeated judges |
+| Synthesizer / integrator | Medium reasoning | Evidence conflicts, shared contracts move, or merge order is semantic |
+| Coordinator | Sufficient for decomposition and decisions | Scope, authority, or architecture remains unresolved |
+
+Prefer independent review after implementation over asking one author thread to implement, retain all local assumptions, and then certify itself. When risk justifies the cost, use multiple independent reviewers: different lenses increase breadth, while repeated judges increase confidence. Preserve minority high-impact findings and merge only evidence-backed conclusions.
+
+More reviewers are not automatically better. Do not fan out when they would inspect unstable code, share contaminated context, repeat one unsupported claim, or exceed the value of the decision. Never change an already-running participant solely to enforce a newer profile; add a fresh review boundary if evidence remains open.
+
 ## Decompose by ownership
 
 Prefer mutation-zone ownership over broad feature labels.
@@ -38,6 +71,9 @@ Goal:
 Non-goals:
 Allowed files or logical scope:
 Avoided files or shared contracts:
+Execution profile:
+Isolation mode: exclusive paths | isolated worktree | artifact-only
+Shared surfaces reserved for integrator:
 Expected artifact or patch:
 Required evidence:
 Checks:
@@ -60,6 +96,14 @@ A useful task card names the smallest scope that can independently reach a valid
 
 If a participant discovers that another scope must change, it emits a dependency or conflict report and stops that edge. The coordinator either transfers ownership, serializes the work, or replans.
 
+## Isolation modes
+
+- `Exclusive paths`: Writers share one worktree only when their complete writable path sets are disjoint and the shared baseline remains stable.
+- `Isolated worktree`: Use when compilation, generated files, imports, or likely dependencies can touch shared repository state.
+- `Artifact-only`: Use for reports, inventories, proposed patches, fixtures, or reviews that the integrator applies later.
+
+The integrator exclusively owns `BACKLOG.md`, `CHANGELOG.md`, lockfiles, generated metadata, public schemas, release manifests, and cross-domain configuration by default. A task card may transfer one of these surfaces to another participant, but never create concurrent ownership. Authors report required shared-surface changes in handoff instead of applying them outside scope.
+
 ## Coordinator checkpoints
 
 A checkpoint preserves useful local context while requesting one decision:
@@ -129,13 +173,14 @@ The integrator resolves from both reports. Architecture conflicts stop affected
 
 The named integrator:
 
-1. reads task cards, handoffs, dependency edges, and conflict reports;
-2. verifies each result stayed within scope;
-3. integrates in dependency order, one ownership edge at a time;
-4. resolves conflicts while preserving stated invariants;
-5. runs checks after risky edges and the full agreed validation at the end;
-6. obtains fresh review for conflict-resolved or shared-contract changes;
-7. reports integrated tasks, rejected or deferred work, checks, and residual risks.
+1. freezes new author mutations and preserves every terminal handoff before integration;
+2. reads task cards, handoffs, dependency edges, and conflict reports;
+3. verifies each result stayed within scope;
+4. integrates in dependency order, one ownership edge at a time;
+5. resolves conflicts while preserving stated invariants;
+6. runs checks after risky edges and the full agreed validation at the end;
+7. obtains fresh review for conflict-resolved or shared-contract changes;
+8. reports integrated tasks, rejected or deferred work, checks, and residual risks.
 
 Do not treat a clean merge, participant-local tests, or a collection of terminal Runs as integrated completion. Completion requires retained shared state plus coordinator-owned validation evidence.
 

package/docs/tool-registry.md

@@ -73,7 +73,7 @@ Usage and lineage live in locked metadata ledgers rather than authored Recipe fi
 
 ## Specializing Existing Recipes
 
-Use `register_tool from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. The stored user Recipe remains compact direct delegation; it does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Use `register_tool from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. Pi supplies one authoritative active-session Skill snapshot across global, project, package, settings, CLI, and extension-contributed locations. Registration resolves the source from that snapshot, stores only the logical direct-delegation reference plus caller specialization, and activates the tool from the already-resolved effective contract without ambient re-resolution. It does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`; symlinks and absolute helper paths are not substitutes. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety
 

package/lib/extension-runtime.ts

@@ -160,6 +160,10 @@ export function createActorExtensionRuntime(
         Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({
           configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
           getActiveTools: () => pi.getActiveTools(),
+          getRecipeResolutionContext: () =>
+            activeRunContext
+              ? getRecipeResolutionContext(activeRunContext)
+              : undefined,
           getRuntimeTool: (name) =>
             Tools.resolveActiveRuntimeTool(
               name,

package/lib/registry.ts

@@ -73,6 +73,7 @@ export interface RegisterToolRuntimeDeps<TContext> {
   recipeRoot?: string;
   getToolNameBlocker: (name: string) => string | undefined;
   getTools: () => Map<string, Config.RegisteredTool>;
+  getRecipeResolutionContext?: () => RecipesContext.RecipeResolutionContext | undefined;
   getActiveTools: () => string[];
   notify: (
     ctx: TContext,
@@ -422,11 +423,9 @@ function getRegistrationResolutionContext<TContext>(
   ctx: TContext,
   deps: RegisterToolRuntimeDeps<TContext>,
 ): RecipesContext.RecipeResolutionContext {
-  if (
-    ctx &&
-    typeof ctx === "object" &&
-    "recipeResolutionContext" in ctx
-  ) {
+  const runtimeContext = deps.getRecipeResolutionContext?.();
+  if (runtimeContext) return runtimeContext;
+  if (ctx && typeof ctx === "object" && "recipeResolutionContext" in ctx) {
     const resolutionContext = (ctx as {
       recipeResolutionContext?: RecipesContext.RecipeResolutionContext;
     }).recipeResolutionContext;
@@ -697,9 +696,11 @@ function executeRegisterToolUnlocked<TContext>(
   let persisted = false;
   let activation: RuntimeActivation | undefined;
   let cfg: Config.RegisteredTool;
+  let transactionStage = "persist";
   try {
     persistToolRecipe(deps, name, authoredRecipe);
     persisted = true;
+    transactionStage = "persisted_admission";
     const admitted = RecipesDiscovery.admitUserRecipe(
       recipePath,
       resolutionContext,
@@ -711,6 +712,7 @@ function executeRegisterToolUnlocked<TContext>(
     }
     cfg = admitted.tool;
     tools.set(name, cfg);
+    transactionStage = "runtime_activation";
     activation = deps.registerRuntimeTool(cfg) ?? undefined;
     if (
       activation &&
@@ -737,7 +739,7 @@ function executeRegisterToolUnlocked<TContext>(
     deps.setActiveTools(activeBefore);
     throw new Error(
       ExecutionOutput.formatToolText(
-        `Tool registration transaction failed: ${error instanceof Error ? error.message : String(error)}`,
+        `Tool registration transaction failed at ${transactionStage} (${resolutionContext.generation}; active Skills: ${activeSkillSummary(resolutionContext)}): ${error instanceof Error ? error.message : String(error)}`,
       ),
     );
   }

package/lib/tools-local.ts

@@ -147,9 +147,9 @@ export function createRuntimeToolDefinition(
   const paramSchema: Record<string, JsonSchema> = {};
   const required: string[] = [];
   const isRecipe = RecipesReferences.isRecipeTool(cfg.template, cfg.recipe);
-  const isAsyncRecipe =
-    cfg.recipe?.async === true ||
-    RecipesReferences.isAsyncRecipeReference(cfg.template);
+  const isAsyncRecipe = cfg.recipe
+    ? cfg.recipe.async === true
+    : RecipesReferences.isAsyncRecipeReference(cfg.template);
   const recipeTemplate =
     cfg.recipe?.template ?? RecipesReferences.getRecipeTemplate(cfg.template);
   const requiredTemplate = recipeTemplate ?? cfg.template!;
@@ -177,7 +177,7 @@ export function createRuntimeToolDefinition(
               !Object.hasOwn(recipeInlineDefaults, arg),
           ),
         )
-      : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
+      : !cfg.recipe && RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
         : Schema.getRequiredToolArgNames(requiredTemplateConfig);
   for (const arg of cfg.args) {

package/lib/tools.ts

@@ -24,6 +24,7 @@ export interface CoreActorToolDefinitionDeps<
 > {
   configPath: string;
   getActiveTools: () => string[];
+  getRecipeResolutionContext: () => import("./recipes-context.ts").RecipeResolutionContext | undefined;
   getRuntimeTool: (name: string) => unknown;
   getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
   handleRuntimeControl?: (
@@ -68,6 +69,7 @@ export function createCoreActorToolDefinitions<
       getActiveTools: deps.getActiveTools,
       getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
       getTools: deps.registryRuntime.getTools,
+      getRecipeResolutionContext: deps.getRecipeResolutionContext,
       notify: deps.registryRuntime.notify,
       registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,
       reservedToolNames: RESERVED_TOOL_NAMES,

package/package.json

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

package/skills/actors/SKILL.md

@@ -52,7 +52,7 @@ 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` creates or updates a persistent user tool. 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>`. `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`.
 
 `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.
 
@@ -76,6 +76,17 @@ Then:
 
 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).
 
+## Local coordinator topology
+
+There are two distinct multi-instance shapes:
+
+- A gateway-centric system owns ingress, agent-instance creation, routing, and lifecycle outside the agents.
+- A host-coordinator system keeps the current Pi instance as the control plane; companion extensions such as Telegram provide presence, while pi-actors creates explicit local Runs for delegated work.
+
+In host-coordinator mode, the top-level agent receives declarative outcomes, preserves user authority and global context, delegates bounded concrete execution, and owns integration plus final validation. It is not merely another worker after delegation begins. One bounded implementation worker normally runs with reasoning off; consequential output receives a separate reasoning-enabled review. Several independent participants or reviewers additionally use `swarm`.
+
+Delegation is not mandatory for every prompt. Work inline when one short bounded act has one natural validation boundary and spawning would add more coordination than isolation, latency hiding, clean context, or continued coordinator availability can repay. For admitted delegation, prefer terminal follow-up and durable Trace/artifacts; inspect on meaningful attention, operator request, or an evidence-based overdue timer rather than busy polling.
+
 ## Run workflow
 
 A Run is one concrete execution of a Recipe:

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

@@ -28,6 +28,8 @@ register_tool
 
 `from` means logical direct delegation. The source remains authoritative for async behavior, caller args and types, source defaults, artifacts, Control, and runtime-owned origins. The persistent user Recipe stores only the compact specialization; do not copy inherited fields.
 
+Resolution uses Pi's authoritative active-session Skill snapshot across every Skill location Pi admits. Registration resolves and validates the maintained source, persists only its logical `<skill>/<recipe>` reference plus caller specialization, and projects the already-resolved effective contract into the runtime tool. Never replace this composition with a copied Recipe, absolute helper path, symlink, or ambient runtime re-resolution.
+
 Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
 
 ## Prove registration

package/skills/swarm/SKILL.md

@@ -9,6 +9,25 @@ Use multi-actor execution only when at least two scopes or evidence lenses are m
 
 Read `actors` first for generic Recipe, spawn, Run, Trace, Control, artifact, and lifecycle operation. This Skill owns only multi-actor methodology: decomposition, scope ownership, independence, synthesis, integration, and completion proof.
 
+## Coordinator topology
+
+A swarm can be coordinated without an external gateway. In this model the current host agent is the declarative control plane, the actor kernel creates explicit participant Runs, and companion transports provide ingress or presence without owning hidden agent creation. The coordinator retains user authority, global context, decomposition, shared-surface ownership, integration, and final validation; participants own bounded concrete tasks and report evidence.
+
+This resembles gateway orchestration in dependency direction but not in ownership: the coordinator is itself an agent instance with inspectable Runs, not an infrastructure service that implicitly creates sessions. Preserve that distinction in prompts, docs, recovery, and target routing.
+
+Once work is delegated, keep the coordinator available for decisions and integration instead of duplicating participant implementation. Wait for terminal follow-up by default; use meaningful attention or evidence-based timers for overdue work rather than a tight inspection loop.
+
+## Reasoning allocation
+
+Allocate reasoning by role instead of making one long thread implement and judge itself:
+
+- Bounded implementation/authorship participants default to reasoning off when the task card fixes scope, invariants, checks, and escalation. Enable reasoning only when unresolved diagnosis or local design judgement is part of their assignment.
+- Reviewers default to independent medium reasoning and clean context. For consequential work, several reviewers with distinct lenses or repeated independent judgement usually provide better error discovery than increasing one author's reasoning and relying on self-review.
+- Synthesizers and integrators use medium reasoning because they reconcile evidence, conflicts, shared contracts, and retained state.
+- The coordinator decides whether review fanout is worth its cost, preserves dissent, and never treats reviewer count as evidence quality by itself.
+
+Do not change a running participant's profile merely because policy changed. Replace or add a later independent review only when fresh evidence is still needed.
+
 ## Choose the shape
 
 | Need | Shape | Primary Recipe |
@@ -29,18 +48,22 @@ The coordinator owns the whole result even when participants choose local implem
 1. State the goal, non-goals, evidence standard, integration owner, and stop condition.
 2. Partition work into disjoint read or write scopes. Give shared contracts one owner.
 3. Give each participant a bounded task card with allowed scope, avoided scope, expected artifact, checks, and escalation rule.
-4. Preflight required model/tool access before expensive fanout.
-5. Launch independent work without cross-contaminating lenses. Do not let participants silently expand scope.
-6. Preserve every terminal result, including failures, disagreements, and partial evidence.
-7. Merge through one named synthesizer or integrator. Resolve conflicts from explicit intent and invariants, not textual convenience.
-8. Run fresh integrated validation and, for consequential outputs, an independent post-merge review.
-9. Report complete, degraded, or insufficient-data status honestly; name residual owners and next actions.
+4. Assign each participant an explicit execution profile and isolation mode under the reasoning-allocation contract.
+5. Preflight required model/tool access before expensive fanout.
+6. Launch independent work without cross-contaminating lenses. Do not let participants silently expand scope.
+7. Preserve every terminal result, including failures, disagreements, and partial evidence; avoid doing participant work in the coordinator while a valid owner remains active.
+8. Merge through one named synthesizer or integrator. Resolve conflicts from explicit intent and invariants, not textual convenience.
+9. Run fresh integrated validation and, for consequential outputs, an independent post-merge review.
+10. Report complete, degraded, or insufficient-data status honestly; name residual owners and next actions.
 
 ## Scope and coordination rules
 
 - One writable scope has one owner. Parallel readers may share a stable target.
 - Public contracts, schemas, central configuration, and integration surfaces require exclusive ownership.
-- Participants record out-of-scope needs instead of opportunistically editing them.
+- Concurrent writers use disjoint paths, isolated worktrees, or declared patch/artifact outputs.
+- Shared ledgers, lockfiles, generated contracts, metadata, schemas, release surfaces, and cross-domain configuration belong to one named integrator unless a task card transfers one surface to another exclusive owner.
+- Participants record shared-surface and other out-of-scope needs in handoff instead of editing them opportunistically.
+- Reasoning and model profiles are task-card inputs, not implicit properties of the whole swarm.
 - Coordinator checkpoints are bounded decision requests, not free-form actor chat.
 - Locks support scope ownership but do not replace coordinator judgement. Every lock must be bounded and releasable.
 - One integrator owns merge order, conflict resolution, and final validation.

package/skills/swarm/references/development-swarm.md

@@ -14,6 +14,39 @@ Use a development swarm only when all are true:
 
 Do not parallelize implementation when tasks need the same central files, semantic ordering dominates wall-clock time, or the likely conflicts would invalidate the decomposition. Use planning or review first.
 
+## Coordinator role separation
+
+In a host-coordinator topology, the current Pi instance owns the declarative outcome and participant graph rather than acting as the default implementation worker. It may receive intent through Telegram or another companion extension, but transport does not become a gateway or gain hidden instance-creation authority; participant creation remains an explicit actor-kernel Run.
+
+The coordinator should:
+
+- Translate high-level intent into bounded task cards and dependency edges.
+- Keep user authority, shared contracts, integration order, and final validation local.
+- Remain available for checkpoints, permissions, conflicts, and changing evidence.
+- Consume terminal handoffs, durable artifacts, and Trace attention instead of mirroring participant work.
+- Check overdue work on an evidence-based timer; never replace event-driven completion with a rapid polling loop.
+
+A participant should:
+
+- Own one concrete execution or evidence boundary.
+- Avoid global orchestration and undeclared participant creation.
+- Return a bounded handoff that lets the coordinator decide without replaying the entire task.
+
+Use one ordinary Run under `actors` when only one worker is delegated. Activate this development-swarm protocol when two or more participants, parallel ownership, or explicit integration edges exist. Keep trivial single-boundary work inline when delegation overhead has no compensating value.
+
+## Reasoning profiles
+
+| Role | Default | Raise or fan out when |
+| --- | --- | --- |
+| Bounded implementation author | Reasoning off | The card explicitly owns unresolved diagnosis or design judgement |
+| Reviewer | Medium reasoning, clean context | Stakes require independent lenses or repeated judges |
+| Synthesizer / integrator | Medium reasoning | Evidence conflicts, shared contracts move, or merge order is semantic |
+| Coordinator | Sufficient for decomposition and decisions | Scope, authority, or architecture remains unresolved |
+
+Prefer independent review after implementation over asking one author thread to implement, retain all local assumptions, and then certify itself. When risk justifies the cost, use multiple independent reviewers: different lenses increase breadth, while repeated judges increase confidence. Preserve minority high-impact findings and merge only evidence-backed conclusions.
+
+More reviewers are not automatically better. Do not fan out when they would inspect unstable code, share contaminated context, repeat one unsupported claim, or exceed the value of the decision. Never change an already-running participant solely to enforce a newer profile; add a fresh review boundary if evidence remains open.
+
 ## Decompose by ownership
 
 Prefer mutation-zone ownership over broad feature labels.
@@ -38,6 +71,9 @@ Goal:
 Non-goals:
 Allowed files or logical scope:
 Avoided files or shared contracts:
+Execution profile:
+Isolation mode: exclusive paths | isolated worktree | artifact-only
+Shared surfaces reserved for integrator:
 Expected artifact or patch:
 Required evidence:
 Checks:
@@ -60,6 +96,14 @@ A useful task card names the smallest scope that can independently reach a valid
 
 If a participant discovers that another scope must change, it emits a dependency or conflict report and stops that edge. The coordinator either transfers ownership, serializes the work, or replans.
 
+## Isolation modes
+
+- `Exclusive paths`: Writers share one worktree only when their complete writable path sets are disjoint and the shared baseline remains stable.
+- `Isolated worktree`: Use when compilation, generated files, imports, or likely dependencies can touch shared repository state.
+- `Artifact-only`: Use for reports, inventories, proposed patches, fixtures, or reviews that the integrator applies later.
+
+The integrator exclusively owns `BACKLOG.md`, `CHANGELOG.md`, lockfiles, generated metadata, public schemas, release manifests, and cross-domain configuration by default. A task card may transfer one of these surfaces to another participant, but never create concurrent ownership. Authors report required shared-surface changes in handoff instead of applying them outside scope.
+
 ## Coordinator checkpoints
 
 A checkpoint preserves useful local context while requesting one decision:
@@ -129,13 +173,14 @@ The integrator resolves from both reports. Architecture conflicts stop affected
 
 The named integrator:
 
-1. reads task cards, handoffs, dependency edges, and conflict reports;
-2. verifies each result stayed within scope;
-3. integrates in dependency order, one ownership edge at a time;
-4. resolves conflicts while preserving stated invariants;
-5. runs checks after risky edges and the full agreed validation at the end;
-6. obtains fresh review for conflict-resolved or shared-contract changes;
-7. reports integrated tasks, rejected or deferred work, checks, and residual risks.
+1. freezes new author mutations and preserves every terminal handoff before integration;
+2. reads task cards, handoffs, dependency edges, and conflict reports;
+3. verifies each result stayed within scope;
+4. integrates in dependency order, one ownership edge at a time;
+5. resolves conflicts while preserving stated invariants;
+6. runs checks after risky edges and the full agreed validation at the end;
+7. obtains fresh review for conflict-resolved or shared-contract changes;
+8. reports integrated tasks, rejected or deferred work, checks, and residual risks.
 
 Do not treat a clean merge, participant-local tests, or a collection of terminal Runs as integrated completion. Completion requires retained shared state plus coordinator-owned validation evidence.