@llblab/pi-actors 0.31.0 → 0.32.0

package/AGENTS.md

@@ -61,6 +61,7 @@ Pi host
 - Prefer explicit operator action over silent user-config rewrites.
 - Keep published documentation portable: use `~`, `<repo>`, or relative paths instead of machine-local absolute paths.
 - Preserve runtime output discipline because tool output flows directly into agent context.
+- Optimize every actor-facing surface for signal over volume: prefer compact state-backed hints and fewer concepts over broad explanatory prose or speculative guidance.
 - Keep the project lens local-first and cybernetic: agents wrap durable local capabilities as actors, then use semantic tools and messages instead of repeatedly reconstructing shell commands.
 - Design recipes as agent-callable tools: make prompts, scopes, paths, models, and policy knobs public args/defaults when the caller should decide them at invocation time.
 - Decompose oversized bullets into sublists or hierarchy; long flat list items are a context-smell.
@@ -80,6 +81,7 @@ Pi host
 ## Public Actor Model
 
 - Preserve the public verbs: `spawn`, `message`, `inspect`.
+- Keep the model-facing concept ladder minimal: core is run actors, typed messages, intentional inspection, artifacts, and recipe/tool memory; group messaging, roster, branches, sessions, and diagnostics are advanced surfaces.
 - Prefer one typed actor-message envelope for upward, downward, lateral, parent/branch, and branch/parent messages.
 - Prefer actor addresses and inspect views over exposing FIFO, outbox, or status mechanics as public concepts.
 - Keep route and semantic type separate: delivery behavior comes from `to`, while `type` describes intent.
@@ -116,6 +118,7 @@ Pi host
 ## State, IO, And Safety
 
 - Tool stdout and temp state must stay bounded and local.
+- Feedback hints must be evidence-backed, bounded, and action-shaped; prefer `next_actions` pointing to existing verbs over prose, and avoid hints when no concrete next step is justified.
 - Keep tail truncation, full-output temp files, failure formatting, and centralized limits intact.
 - Published docs must not include machine-local absolute paths.
 - Any view scanning run directories must apply coordinator/session ownership filters before exposing summaries or previews.

package/BACKLOG.md

@@ -47,25 +47,12 @@ No open hotfix items.
 - File length alone is not a domain-split trigger: ~1000-line cohesive domain files are acceptable when ownership is clear.
 - Consider splitting only when a file crosses roughly 2000 lines, mixes real ownership zones, or hides a clearer domain boundary.
 - Prefer semantic compression before file splitting: fewer public nouns, consistent outcomes, compact diagnostics, and domain-owned constants/helpers.
+- Preserve signal/noise balance: feedback should be state-backed, compact, and action-shaped; do not add advisory prose just because a surface exists.
 
 ## Minor Backlog
 
 The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
-### M-14 Session Mismatch Follow-through
-
-- Priority: Medium.
-- Status: Planned.
-- Goal: Extend 0.27 structured session diagnostics consistently across room, branch, run, coordinator, and session workflows.
-- Why now: M-12 established the shape; dogfood should now make every ownership denial equally actionable without relaxing ownership gates.
-- Direction:
-  - Audit all session mismatch errors for consistent `reason`, owner/current session fields, and inspect-session hints.
-  - Keep read/write ownership policy unchanged.
-  - Update docs with session mismatch examples and recovery inspection paths.
-- Acceptance:
-  - Room, branch, run, coordinator, and session denials share the same compact/verbose shape.
-  - Tests cover representative inspect and message paths.
-
 ### M-15 Worker Stale-Claim Dogfood
 
 - Priority: Medium.
@@ -111,23 +98,23 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Room messages distinguish timeline append success from forwarded branch-targeted copies.
   - Tests cover at least run, branch, room, coordinator, and ownership-denied outcomes.
 
-### M-18 Candidate Recipe Promotion UX
+### M-18 Draft Recipe Promotion UX
 
 - Priority: High.
 - Status: Planned.
-- Goal: Make successful ad hoc actor patterns easy to promote manually from candidate memory into active user recipe memory.
-- Why now: Candidate recipes under `~/.pi/agent/recipes/candidates` are replayable but intentionally not active tools; the two-stage memory model now needs an explicit operator-gated promotion path.
+- Goal: Make successful ad hoc actor patterns easy to promote manually from draft memory into active user recipe memory.
+- Why now: Draft recipes under `~/.pi/agent/recipes/candidates` are replayable but intentionally not active tools; the directory name is retained for compatibility, and the two-stage memory model now needs an explicit operator-gated promotion path.
 - Direction:
-  - List candidate recipes with source run, timestamp, fingerprint, description/template preview, and validation status.
-  - Promote a selected candidate to `~/.pi/agent/recipes/<name>.json` only through an explicit action or explicit tool argument.
+  - List draft recipes with source run, timestamp, fingerprint, description/template preview, and validation status.
+  - Promote a selected draft to `~/.pi/agent/recipes/<name>.json` only through an explicit action or explicit tool argument.
   - Run recipe validation/doctor before writing and expose collision/shadowing diagnostics.
-  - Preserve candidate files unless deletion is explicitly requested.
+  - Preserve draft files unless deletion is explicitly requested.
   - Prefer extending existing registry/tool surfaces over adding a new public noun.
 - Acceptance:
-  - Candidate recipes remain non-tools until promotion.
+  - Draft recipes remain non-tools until promotion.
   - Promotion writes atomically and never auto-promotes.
-  - Tests cover valid promotion, invalid candidate, name collision, and packaged-recipe shadowing.
-  - Docs explain candidate memory vs active tool memory in one compact section.
+  - Tests cover valid promotion, invalid draft, name collision, and packaged-recipe shadowing.
+  - Docs explain draft memory vs active tool memory in one compact section.
 
 ### M-24 Registry Path Naming Cleanup
 
@@ -166,10 +153,10 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 - Priority: Medium.
 - Status: Planned.
 - Goal: Add one compact operator triage view that answers what needs attention right now without performing repairs.
-- Why now: Runtime status, recipe doctor, candidates, stale claims, session mismatches, failed runs, and other-session counts are currently separate bounded surfaces.
+- Why now: Runtime status, recipe doctor, drafts, stale claims, session mismatches, failed runs, and other-session counts are currently separate bounded surfaces.
 - Direction:
   - Add `inspect target=tool:pi-actors view=triage` or an equivalent existing inspect surface.
-  - Summarize runtime version/mode, active runs, other-session runs, invalid or blocking recipes, high-risk recipes, candidate recipes, stale worker claims, recent failed runs, attention messages, and suggested next inspect actions.
+  - Summarize runtime version/mode, active runs, other-session runs, invalid or blocking recipes, high-risk recipes, draft recipes, stale worker claims, recent failed runs, attention messages, and suggested next inspect actions.
   - Keep every warning tied to a next inspect/action hint.
   - Do not auto-repair, auto-prune, relax ownership, or hide detailed source-of-truth views.
 - Acceptance:
@@ -226,7 +213,7 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-Next milestone: M-14 Session Mismatch Follow-through.
-Then: M-15 Worker Stale-Claim Dogfood → M-17 Message Delivery Outcome Contract → M-18 Candidate Recipe Promotion UX.
+Next milestone: M-15 Worker Stale-Claim Dogfood.
+Then: M-17 Message Delivery Outcome Contract → M-18 Draft Recipe Promotion UX.
 Small cleanup lane: M-23 Tool Boundary Type Tightening → M-24 Registry Path Naming Cleanup.
 ```

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.32.0: Actor Surface Minimization
+
+- `[Context]` Added durable signal/noise guidance for actor-facing surfaces: keep the model-facing concept ladder minimal, make feedback hints state-backed and action-shaped, and avoid speculative advisory prose.
+- `[Backlog]` Added critical concept-surface compression and actor feedback-loop strengthening tracks to guide the next minimization-focused development cycle.
+- `[Concepts]` Compressed model-facing language by presenting captured inline-spawn recipes as drafts, treating `room:<run>` as advanced group messaging plus roster, demoting coordinator/session/debug views from golden-path guidance, and keeping compatibility names/paths as storage details rather than core onboarding nouns.
+- `[Feedback]` Added bounded next-action hints to recipe registry/doctor inspection, artifact inspection, delivery-fallback message results, and terminal run follow-ups so state-backed surfaces point back to `inspect`, `message`, `spawn`, or draft promotion without polling or auto-repair.
+- `[Sessions]` Normalized session-directed message ownership failures onto the same structured `reason=session_mismatch`, owner/current session, and inspect-session hint shape used by run, branch, room, and coordinator ownership denials.
+
 ## 0.31.0: Agent Adoption Ergonomics
 
 - `[Adoption]` Added a compact actor-mode trigger rule to the injected prompt, actors skill, README, and async-run docs so models prefer `spawn → message → inspect` for long-lived, stateful, follow-up, artifact, service, fanout, and resumable work while keeping short foreground checks as ordinary tools.

package/README.md

@@ -66,16 +66,21 @@ The npm package is dist-first for JavaScript-only runtimes: default Pi metadata
 
 ## Address Surface
 
-Actors and coordination endpoints are addressed with compact route strings:
+Core actor addresses stay small:
 
 ```text
-run:<id>               one detached actor run
-branch:<run>/<branch>  branch-local actor endpoint
-room:<run>             shared run-local task room
-coordinator            launching coordinator attention path
+run:<id>      one detached actor run
+tool:<name>   executable registered tool actor
+```
+
+Advanced coordination/debug addresses are available when a recipe or workflow needs them:
+
+```text
+branch:<run>/<branch>  branch-local worker endpoint
+room:<run>             group-message timeline plus roster for one run
+coordinator            compatibility alias for the current session coordination path
 session:               current session actor surface
-session:all            cross-session inventory surface
-tool:<name>            executable registered tool
+session:all            cross-session inventory surface for diagnostics
 ```
 
 Actor messages use one envelope shape:
@@ -140,9 +145,9 @@ message to=run:docs_review type=control.continue body=continue
 message to=run:docs_review type=control.kill body=stop
 ```
 
-## Actor Rooms
+## Group Messaging And Roster
 
-Every spawned run can have a shared room at `room:<run>`. A room is not a broker and not a chat app. It is a run-local coordination surface: append-only timeline, compact roster, member discovery, and previews.
+Every spawned run can have advanced group messaging at `room:<run>`. Treat this as a run-local timeline plus roster for coordinated actors, not as a core chat/broker concept.
 
 Actors can join, post, leave, and discover peers:
 
@@ -155,7 +160,7 @@ message \
   body='{"role":"reviewer","caps":["security-review"],"claim":"Review auth boundary risks"}'
 ```
 
-Inspect the room intentionally:
+Inspect group messages and roster intentionally:
 
 ```text
 inspect target=room:review view=status
@@ -165,7 +170,7 @@ inspect target=room:review view=contacts
 inspect target=room:review view=messages
 ```
 
-Room posts require a same-run sender, so unrelated runs do not pollute the roster. Direct messages and room messages use the same envelope; only the address changes. Direct `branch:<run>/<branch>` messages are private: they are forwarded through the parent run mailbox and recorded in the recipient branch inbox for worker protocols that consume queued branch work. For selected-recipient multicast, send to `room:<run>` with `metadata.recipients` set to same-run `branch:<run>/<branch>` addresses; this keeps one room transcript entry while forwarding branch-targeted copies.
+Group posts require a same-run sender, so unrelated runs do not pollute the roster. Direct messages and group messages use the same envelope; only the address changes. Direct `branch:<run>/<branch>` messages are private: they are forwarded through the parent run mailbox and recorded in the recipient branch inbox for worker protocols that consume queued branch work. For selected-recipient multicast, send to `room:<run>` with `metadata.recipients` set to same-run `branch:<run>/<branch>` addresses; this keeps one visible transcript entry while forwarding branch-targeted copies.
 
 ## Actor Inspector
 

package/dist/lib/observability.js

@@ -721,19 +721,30 @@ function formatRecipePersistenceSuggestion(transition) {
     }
     return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern fits this machine's recurring workflow, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
 }
+function formatTransitionNextActions(transition) {
+    const actions = [
+        `inspect target=run:${transition.run} view=status`,
+        transition.to === "done" && Object.keys(transition.artifacts ?? {}).length > 0
+            ? `inspect target=run:${transition.run} view=artifacts`
+            : `inspect target=run:${transition.run} view=tail`,
+        `inspect target=run:${transition.run} view=messages`,
+    ].filter(Boolean);
+    return `\nNext actions: ${actions.join(" | ")}`;
+}
 export function formatRunTransitionMessage(transition) {
     const artifacts = formatNamedArtifacts(transition.artifacts);
     const runFiles = formatRunFileList(getRunArtifacts(transition));
     const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
+    const nextActions = formatTransitionNextActions(transition);
     if (transition.to === "done")
-        return `Run ${transition.run} completed successfully.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail if the result needs inspection.${persistenceSuggestion}`;
+        return `Run ${transition.run} completed successfully.${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
     if (transition.to === "failed")
-        return `Run ${transition.run} failed.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail for details.`;
+        return `Run ${transition.run} failed.${artifacts}${runFiles}${nextActions}`;
     if (transition.to === "cancelled")
-        return `Run ${transition.run} was cancelled. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+        return `Run ${transition.run} was cancelled.${nextActions}`;
     if (transition.to === "killed")
-        return `Run ${transition.run} was force-killed. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+        return `Run ${transition.run} was force-killed.${nextActions}`;
     if (transition.to === "exited")
-        return `Run ${transition.run} exited before writing a result. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
-    return `Run ${transition.run} finished with status ${transition.to}. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+        return `Run ${transition.run} exited before writing a result.${nextActions}`;
+    return `Run ${transition.run} finished with status ${transition.to}.${nextActions}`;
 }

package/dist/lib/tools.js

@@ -168,8 +168,9 @@ function compactAsyncRunStatus(value) {
         tokens.push(`code=${String(result.code)}`);
     if (result.killed === true)
         tokens.push("killed=true");
-    if (status.candidate_recipe)
-        tokens.push(`candidate_recipe=${String(status.candidate_recipe)}`);
+    const draftRecipe = status.draft_recipe ?? status.candidate_recipe;
+    if (draftRecipe)
+        tokens.push(`draft_recipe=${String(draftRecipe)}`);
     const nextActions = actorRunNextActions(run);
     if (nextActions.length > 0)
         tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
@@ -357,6 +358,15 @@ function compactArtifactPath(value) {
     const record = asRecord(value);
     return String(record.path ?? "<missing>");
 }
+function artifactNextActions(run, artifacts) {
+    const id = String(run ?? "").trim();
+    if (!id || Object.keys(artifacts).length === 0)
+        return [];
+    return [
+        `inspect target=run:${id} view=artifacts verbose=true`,
+        `inspect target=run:${id} view=messages`,
+    ];
+}
 function compactActorFiles(status) {
     const run = String(status.run ?? "<unknown>");
     const artifacts = asRecord(status.artifacts);
@@ -375,7 +385,11 @@ function compactActorFiles(status) {
             .map(([key, value]) => `${key}:${compactArtifactPath(value)}`)
             .join(",")}`
         : "";
-    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
+    const nextActions = artifactNextActions(run, artifacts);
+    const nextText = nextActions.length
+        ? ` next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+        : "";
+    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}${nextText}`;
 }
 function summarizeOtherSessions(currentSession, allRuns) {
     const otherRuns = allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession);
@@ -495,8 +509,42 @@ function compactRecipeDoctor(summary) {
             : "";
         lines.push(`${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`);
     }
+    const nextActions = Array.isArray(summary.next_actions)
+        ? summary.next_actions
+        : [];
+    if (nextActions.length > 0)
+        lines[0] = `${lines[0]}${compactNextActions(nextActions)}`;
     return `\n${lines.join("\n")}`;
 }
+function recipeRegistryNextActions(summary, view) {
+    const actions = [];
+    const drafts = Array.isArray(summary.drafts)
+        ? summary.drafts
+        : [];
+    const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
+    const diagnostics = Array.isArray(summary.diagnostics)
+        ? summary.diagnostics.length
+        : 0;
+    const topAction = asRecord(summary.top_action);
+    if (view !== "doctor" && (invalid > 0 || diagnostics > 0)) {
+        actions.push("inspect target=recipes view=doctor");
+    }
+    if (view === "doctor" && typeof topAction.action === "string") {
+        actions.push(String(topAction.action));
+    }
+    if (drafts.length > 0) {
+        actions.push("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}`);
+    }
+    return [...new Set(actions)].slice(0, 4);
+}
+function compactNextActions(actions) {
+    return actions.length
+        ? ` next=${actions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+        : "";
+}
 function compactRecipeRegistry(summary) {
     const active = Array.isArray(summary.active) ? summary.active.length : 0;
     const shadowed = Array.isArray(summary.shadowed)
@@ -509,13 +557,41 @@ function compactRecipeRegistry(summary) {
     const diagnostics = Array.isArray(summary.diagnostics)
         ? summary.diagnostics.length
         : 0;
-    const candidates = Array.isArray(summary.candidates)
-        ? summary.candidates.length
-        : 0;
+    const drafts = Array.isArray(summary.drafts)
+        ? summary.drafts.length
+        : Array.isArray(summary.candidates)
+            ? summary.candidates.length
+            : 0;
     const recommendations = Array.isArray(summary.recommendations)
         ? summary.recommendations.length
         : 0;
-    return `\nrecipes active=${active} candidates=${candidates} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
+    const nextActions = Array.isArray(summary.next_actions)
+        ? summary.next_actions
+        : [];
+    return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
+}
+function actorMessageNextActions(message, result) {
+    const actions = [];
+    const address = ActorMessages.parseActorAddress(message.to);
+    if (result.delivery_error || result.sent === false) {
+        if (address.kind === "run" && address.value) {
+            actions.push(`inspect target=run:${address.value} view=status`);
+            actions.push(`inspect target=run:${address.value} view=mailbox`);
+        }
+        else if (address.kind === "branch" && address.value) {
+            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+            actions.push(`inspect target=run:${address.value} view=status`);
+        }
+    }
+    if (result.queued === true) {
+        if (address.kind === "branch" && address.value) {
+            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+        }
+        else if (address.kind === "run" && address.value) {
+            actions.push(`inspect target=run:${address.value} view=mailbox`);
+        }
+    }
+    return [...new Set(actions)].slice(0, 3);
 }
 function compactActorMessageResult(message, result) {
     const tokens = [
@@ -548,6 +624,11 @@ function compactActorMessageResult(message, result) {
     if (result.delivery_error) {
         tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
     }
+    const nextActions = Array.isArray(result.next_actions)
+        ? result.next_actions
+        : actorMessageNextActions(message, result);
+    if (nextActions.length > 0)
+        tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
     return `\n${tokens.join(" ")}`;
 }
 function maybeJsonText(value, verbose, compact) {
@@ -649,7 +730,7 @@ function writeSpawnCandidateRecipe(input, meta) {
     const defaults = candidateRecipeDefaults(meta.values);
     const recipe = {
         async: true,
-        description: `Candidate recipe captured from spawn run ${String(meta.run)}`,
+        description: `Draft recipe captured from spawn run ${String(meta.run)}`,
         ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
         ...(defaults ? { defaults } : {}),
         template: input.template,
@@ -787,7 +868,9 @@ export function createSpawnToolDefinition() {
             const nextActions = actorRunNextActions(meta.run);
             const details = {
                 ...meta,
-                ...(candidateRecipe ? { candidate_recipe: candidateRecipe } : {}),
+                ...(candidateRecipe
+                    ? { candidate_recipe: candidateRecipe, draft_recipe: candidateRecipe }
+                    : {}),
                 next_actions: nextActions,
             };
             ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
@@ -814,15 +897,29 @@ function requireContextSessionId(ctx, actor) {
     }
     return sessionId;
 }
+function sessionMismatchError(input) {
+    const ownerSession = input.expectedSession ?? "none";
+    const currentSession = input.currentSession ?? "none";
+    const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
+    const hintTarget = input.expectedSession
+        ? `session:${input.expectedSession}`
+        : "session:all";
+    return Object.assign(new Error(`${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`), {
+        current_session: input.currentSession,
+        hint: `inspect target=${hintTarget} view=status`,
+        owner_session: input.expectedSession,
+        reason: "session_mismatch",
+        run: input.run,
+        target: input.target,
+    });
+}
 function assertRunAccessibleToContext(runId, ctx) {
     const status = AsyncRuns.getRunStatus(runId);
     const sessionId = getContextSessionId(ctx);
     if (sessionId && status.ownerId && status.ownerId !== sessionId) {
-        throw Object.assign(new Error(`run:${runId} reason=session_mismatch owner_session=${status.ownerId} current_session=${sessionId} hint=inspect_session:${status.ownerId}`), {
-            current_session: sessionId,
-            hint: `inspect target=session:${status.ownerId} view=status`,
-            owner_session: status.ownerId,
-            reason: "session_mismatch",
+        throw sessionMismatchError({
+            currentSession: sessionId,
+            expectedSession: String(status.ownerId),
             run: runId,
         });
     }
@@ -835,13 +932,13 @@ export function createInspectToolDefinition(deps = {}) {
     return {
         name: "inspect",
         label: "Inspect",
-        description: "Intentionally inspect an actor at decision points, after follow-ups, or during diagnosis instead of polling. Supports run:<id> views: status, tail, messages, artifacts, files, mailbox, communication; room:<run> status/messages/previews/roster/contacts; coordinator/session status; and tool:<name> status/schema.",
+        description: "Intentionally inspect actors at decision points, after follow-ups, or during diagnosis instead of polling. Core targets are run:<id> and tool:<name>; advanced targets include branch:<run>/<branch>, room:<run>, coordinator, session:<id>, and session:all.",
         parameters: objectSchema({
             lines: stringSchema("Line count for tail/messages views. Default 40."),
             status: stringSchema("Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited."),
-            target: stringSchema("Actor address to inspect, e.g. run:<id>, room:<run>, coordinator, session:<id>, session:all, or tool:<name>."),
+            target: stringSchema("Actor address to inspect, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>, session:all."),
             verbose: booleanSchema("Return full JSON instead of compact text where available."),
-            view: stringSchema("Inspection view: status, tail, messages, artifacts, files, mailbox, communication, roster, or contacts."),
+            view: stringSchema("Inspection view. Core run views: status, tail, messages, artifacts, files, mailbox. Advanced views include communication, roster, and contacts."),
         }, ["target", "view"]),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const input = asRecord(params);
@@ -863,10 +960,15 @@ export function createInspectToolDefinition(deps = {}) {
                     { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
                 ]);
                 const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
-                const summary = {
+                const summaryBase = {
                     ...RecipeDiscovery.summarizeDiscovery(discovered),
+                    drafts: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
                     candidates: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
                 };
+                const summary = {
+                    ...summaryBase,
+                    next_actions: recipeRegistryNextActions(summaryBase, view),
+                };
                 return {
                     content: [
                         {
@@ -1084,7 +1186,11 @@ export function createInspectToolDefinition(deps = {}) {
                     const status = assertRunAccessibleToContext(runId, ctx);
                     const artifactManifest = AsyncRuns.resolveArtifactManifest(status.artifacts);
                     const details = artifactManifest
-                        ? { ...status, artifact_manifest: artifactManifest }
+                        ? {
+                            ...status,
+                            artifact_manifest: artifactManifest,
+                            next_actions: artifactNextActions(status.run ?? runId, asRecord(status.artifacts)),
+                        }
                         : status;
                     return {
                         content: [
@@ -1139,7 +1245,7 @@ export function createActorMessageToolDefinition(deps = {}) {
     return {
         name: "message",
         label: "Message",
-        description: "Send one typed addressed message to steer an existing actor instead of restarting it. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, room:<run> timelines/rosters, tool:<name> calls, and coordinator/session-bound run messages.",
+        description: "Send one typed addressed message to steer an existing actor instead of restarting it. Core routes are run:<id> and tool:<name>; advanced routes include branch:<run>/<branch>, room:<run> group timelines, coordinator, and session:<id>.",
         parameters: objectSchema({
             body: unionSchema([
                 stringSchema("Message body. For run:<id>, this is the run-local command line."),
@@ -1151,7 +1257,7 @@ export function createActorMessageToolDefinition(deps = {}) {
             metadata: looseObjectSchema("Optional structured metadata for routing or domain hints."),
             reply_to: stringSchema("Optional message id this message replies to."),
             summary: stringSchema("Optional short human-facing summary."),
-            to: stringSchema("Destination actor address, e.g. run:<id>, branch:<run>/<branch>, room:<run>, coordinator, session:<id>, or tool:<name>."),
+            to: stringSchema("Destination actor address, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>."),
             type: stringSchema("Semantic message type, e.g. control.approve or checkpoint.needs_scope."),
             verbose: booleanSchema("Return full JSON instead of compact text."),
         }, ["to", "type"]),
@@ -1266,10 +1372,20 @@ export function createActorMessageToolDefinition(deps = {}) {
                 const senderStatus = assertRunAccessibleToContext(sender.value, ctx);
                 if (address.kind === "session") {
                     if (!senderStatus.ownerId) {
-                        throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got no owner.`);
+                        throw sessionMismatchError({
+                            currentSession: undefined,
+                            expectedSession: address.value,
+                            run: sender.value,
+                            target: `session:${address.value}`,
+                        });
                     }
                     if (senderStatus.ownerId !== address.value) {
-                        throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got ${senderStatus.ownerId}.`);
+                        throw sessionMismatchError({
+                            currentSession: String(senderStatus.ownerId),
+                            expectedSession: address.value,
+                            run: sender.value,
+                            target: `session:${address.value}`,
+                        });
                     }
                 }
                 result = AsyncRuns.appendRunOutboxEvent(sender.value, {
@@ -1291,14 +1407,18 @@ export function createActorMessageToolDefinition(deps = {}) {
             else {
                 throw new Error(`message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`);
             }
+            const nextActions = actorMessageNextActions(message, result);
+            const resultWithNext = nextActions.length
+                ? { ...result, next_actions: nextActions }
+                : result;
             return {
                 content: [
                     {
                         type: "text",
-                        text: maybeJsonText({ message, result }, input.verbose === true, compactActorMessageResult(message, result)),
+                        text: maybeJsonText({ message, result: resultWithNext }, input.verbose === true, compactActorMessageResult(message, resultWithNext)),
                     },
                 ],
-                details: { message, result },
+                details: { message, result: resultWithNext },
             };
         },
     };

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.31.0
+  version: 0.32.0
 ---
 
 # Actors (pi-actors)
@@ -39,12 +39,11 @@ Trusted local capability
 
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
-- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, communication snapshot, and artifacts.
-- **Room actor**: shared timeline + roster endpoint addressable as `room:<run>`; every spawned run gets `room:<run>`.
+- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
 - **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime/status inspection.
-- **Coordinator/session**: the current pi session endpoint that receives bounded actor follow-ups.
-- **Mailbox**: public interaction contract: message types the actor accepts/emits.
 - **Artifact**: named durable output path declared by a recipe/run.
+- **Mailbox**: interaction contract: message types the actor accepts/emits.
+- **Advanced group/coordination surfaces**: `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:<id>`, and communication snapshots exist for multi-actor workflows and diagnostics; do not make them the default mental model.
 
 ## Three Verbs
 
@@ -86,8 +85,9 @@ Envelope fields:
 
 - Required: `to`, `type`.
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
-- Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
-- Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
+- Core addresses: `run:<id>`, `tool:<name>`.
+- Advanced addresses: `branch:<run>/<branch>`, `room:<run>` for group timeline/roster, `coordinator`, `session:<id>`.
+- Group posts to `room:<run>` require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
 - Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 - Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
 
@@ -99,12 +99,7 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "run:repo-health", "view": "status" }
 { "target": "run:repo-health", "view": "tail", "lines": "80" }
 { "target": "run:repo-health", "view": "messages" }
-{ "target": "run:repo-health", "view": "communication" }
 { "target": "run:repo-health", "view": "artifacts" }
-{ "target": "room:repo-health", "view": "status" }
-{ "target": "room:repo-health", "view": "roster" }
-{ "target": "room:repo-health", "view": "contacts" }
-{ "target": "room:repo-health", "view": "previews" }
 { "target": "tool:pi-actors", "view": "status" }
 { "target": "tool:music_player", "view": "status" }
 { "target": "recipes", "view": "status" }
@@ -116,10 +111,10 @@ Views:
 - `status`: lifecycle, pid, values, progress, result, compact summary.
 - `tail`: recent stdout/stderr/log tail.
 - `messages`: actor messages emitted by the run, or room timeline entries for `room:*`.
-- `communication`: run/branch communication snapshot with self/root/default-room/member/contact hints.
-- `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
-- `contacts`: roster-derived direct-message targets without full roster metadata.
-- `previews`: TUI-ready bounded room message previews with timestamp/from/to/type/summary/body_preview.
+- Advanced `communication`: run/branch group-coordination snapshot with self/root/default-room/member/contact hints.
+- Advanced `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
+- Advanced `contacts`: roster-derived direct-message targets without full roster metadata.
+- Advanced `previews`: TUI-ready bounded group-message previews with timestamp/from/to/type/summary/body_preview.
 - `mailbox`: declared accepts/emits contract for runs; queued direct branch inbox messages for `branch:<run>/<branch>` with `id`, status, route/type, and queue/handling timestamps.
 - `files`: run state directory file list.
 - `artifacts`: declared artifact paths/status.
@@ -218,13 +213,13 @@ Only matching filename ids compete. Higher priority shadows lower priority; with
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
 1. `~/.pi/agent/recipes/*.json` and `*.md` are the agent's active capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Descriptions matter here because they become the tool's operator-facing title/context.
-2. `~/.pi/agent/recipes/candidates/*.json` is candidate memory captured from successful inline `spawn template=...` runs. Candidates are not registered tools and do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/candidates/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
+2. `~/.pi/agent/recipes/candidates/*.json` is draft memory captured from successful inline `spawn template=...` runs. The directory name is retained for compatibility; treat these as drafts, not active tools. Drafts do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/candidates/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
 
-Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow candidate memory by trying ad hoc actors successfully. Treat both as executable habits: candidates are the workbench/proving ground; root recipes are promoted muscle memory.
+Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow draft memory by trying ad hoc actors successfully. Treat both as executable habits: drafts are the workbench/proving ground; root recipes are promoted muscle memory.
 
 Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
 
-Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave candidate recipes as replayable evidence, not active tools. If a candidate is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
+Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave draft recipes as replayable evidence, not active tools. If a draft is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
 
 Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
 

package/dist/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.31.0
+  version: 0.32.0
 ---
 
 # Swarm
@@ -30,8 +30,8 @@ Maintain this skill as a living orchestration standard. When real swarm work exp
 - `Async Run`: A local lifecycle envelope around a command-template swarm composer or utility. It owns state, logs, status, cancellation, and observability, not swarm semantics.
 - `Lens`: A deliberately narrow cognitive role assigned to one subagent, such as security, tests, architecture, economics, or operator UX.
 - `Task Card`: A bounded implementation assignment with goal, allowed files, avoided files, expected output, and validation gates.
-- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, candidate recipes, command templates, async runs, or services.
-- `Candidate Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood.
+- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, draft recipes, command templates, async runs, or services.
+- `Draft Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood. Its compatibility storage path may still include `recipes/candidates`.
 - `Coordinator Checkpoint`: A deliberate subagent pause where the subagent preserves its working context, sends a bounded question or status to the orchestrator, receives a coordinator reply, and continues in the same subagent context.
 - `Evidence Checkpoint`: A deliberate stop where a subagent records sources, assumptions, confidence, contradictions, or blocking evidence gaps before synthesis.
 - `Integrator`: The human or agent that merges isolated branches/worktrees into the shared target and owns conflict resolution.

package/docs/actor-messages.md

@@ -199,7 +199,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Run mailbox inspection shows recipe-declared mailbox metadata plus recent durable run inbox entries; branch mailbox inspection shows branch-local queued/claimed/handled records. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
+The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Run mailbox inspection shows recipe-declared mailbox metadata plus recent durable run inbox entries; branch mailbox inspection shows branch-local queued/claimed/handled records. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. Ownership denials use `reason=session_mismatch owner_session=<id> current_session=<id> hint=inspect_session:<id>`; recover by inspecting the hinted `session:<id>` instead of forcing cross-session control. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
 
 ## Runtime Direction
 

package/docs/tool-registry.md

@@ -10,7 +10,7 @@ The registry source is location-discovered recipes, not a live tool-only JSON fi
 
 - `~/.pi/agent/recipes/*.json` and `*.md` are the highest-priority user recipe root and the operator-managed tool set.
 - Recipes in that root are tools by location.
-- `~/.pi/agent/recipes/candidates/*.json` are captured inline-spawn candidates, not registered tools; promote one by moving or copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths/descriptions for explicit replay by file path.
+- `~/.pi/agent/recipes/candidates/*.json` stores captured inline-spawn draft recipes, not registered tools. The directory name is retained for compatibility; model-facing output calls them drafts. Promote one by moving or copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths/descriptions for explicit replay by file path.
 - Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components, not automatically registered tools.
 - Ad hoc recipe files outside the user recipe root are components unless explicitly registered/copied into `~/.pi/agent/recipes`.
 - Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.

package/lib/observability.ts

@@ -1021,19 +1021,31 @@ function formatRecipePersistenceSuggestion(transition: RunTransition): string {
   return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern fits this machine's recurring workflow, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
 }
 
+function formatTransitionNextActions(transition: RunTransition): string {
+  const actions = [
+    `inspect target=run:${transition.run} view=status`,
+    transition.to === "done" && Object.keys(transition.artifacts ?? {}).length > 0
+      ? `inspect target=run:${transition.run} view=artifacts`
+      : `inspect target=run:${transition.run} view=tail`,
+    `inspect target=run:${transition.run} view=messages`,
+  ].filter(Boolean);
+  return `\nNext actions: ${actions.join(" | ")}`;
+}
+
 export function formatRunTransitionMessage(transition: RunTransition): string {
   const artifacts = formatNamedArtifacts(transition.artifacts);
   const runFiles = formatRunFileList(getRunArtifacts(transition));
   const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
+  const nextActions = formatTransitionNextActions(transition);
   if (transition.to === "done")
-    return `Run ${transition.run} completed successfully.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail if the result needs inspection.${persistenceSuggestion}`;
+    return `Run ${transition.run} completed successfully.${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
   if (transition.to === "failed")
-    return `Run ${transition.run} failed.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail for details.`;
+    return `Run ${transition.run} failed.${artifacts}${runFiles}${nextActions}`;
   if (transition.to === "cancelled")
-    return `Run ${transition.run} was cancelled. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} was cancelled.${nextActions}`;
   if (transition.to === "killed")
-    return `Run ${transition.run} was force-killed. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} was force-killed.${nextActions}`;
   if (transition.to === "exited")
-    return `Run ${transition.run} exited before writing a result. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
-  return `Run ${transition.run} finished with status ${transition.to}. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} exited before writing a result.${nextActions}`;
+  return `Run ${transition.run} finished with status ${transition.to}.${nextActions}`;
 }

package/lib/tools.ts

@@ -222,8 +222,8 @@ function compactAsyncRunStatus(value: unknown): string {
     tokens.push(`failures=${failures}`);
   if (result.code !== undefined) tokens.push(`code=${String(result.code)}`);
   if (result.killed === true) tokens.push("killed=true");
-  if (status.candidate_recipe)
-    tokens.push(`candidate_recipe=${String(status.candidate_recipe)}`);
+  const draftRecipe = status.draft_recipe ?? status.candidate_recipe;
+  if (draftRecipe) tokens.push(`draft_recipe=${String(draftRecipe)}`);
   const nextActions = actorRunNextActions(run);
   if (nextActions.length > 0)
     tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
@@ -451,6 +451,15 @@ function compactArtifactPath(value: unknown): string {
   return String(record.path ?? "<missing>");
 }
 
+function artifactNextActions(run: unknown, artifacts: Record<string, unknown>): string[] {
+  const id = String(run ?? "").trim();
+  if (!id || Object.keys(artifacts).length === 0) return [];
+  return [
+    `inspect target=run:${id} view=artifacts verbose=true`,
+    `inspect target=run:${id} view=messages`,
+  ];
+}
+
 function compactActorFiles(status: Record<string, unknown>): string {
   const run = String(status.run ?? "<unknown>");
   const artifacts = asRecord(status.artifacts);
@@ -469,7 +478,11 @@ function compactActorFiles(status: Record<string, unknown>): string {
         .map(([key, value]) => `${key}:${compactArtifactPath(value)}`)
         .join(",")}`
     : "";
-  return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
+  const nextActions = artifactNextActions(run, artifacts);
+  const nextText = nextActions.length
+    ? ` next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+    : "";
+  return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}${nextText}`;
 }
 
 function summarizeOtherSessions(
@@ -621,9 +634,43 @@ function compactRecipeDoctor(summary: Record<string, unknown>): string {
       `${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`,
     );
   }
+  const nextActions = Array.isArray(summary.next_actions)
+    ? (summary.next_actions as string[])
+    : [];
+  if (nextActions.length > 0) lines[0] = `${lines[0]}${compactNextActions(nextActions)}`;
   return `\n${lines.join("\n")}`;
 }
 
+function recipeRegistryNextActions(summary: Record<string, unknown>, view: string): string[] {
+  const actions: string[] = [];
+  const drafts = Array.isArray(summary.drafts)
+    ? (summary.drafts as Array<Record<string, unknown>>)
+    : [];
+  const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
+  const diagnostics = Array.isArray(summary.diagnostics)
+    ? summary.diagnostics.length
+    : 0;
+  const topAction = asRecord(summary.top_action);
+  if (view !== "doctor" && (invalid > 0 || diagnostics > 0)) {
+    actions.push("inspect target=recipes view=doctor");
+  }
+  if (view === "doctor" && typeof topAction.action === "string") {
+    actions.push(String(topAction.action));
+  }
+  if (drafts.length > 0) {
+    actions.push("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}`);
+  }
+  return [...new Set(actions)].slice(0, 4);
+}
+
+function compactNextActions(actions: string[]): string {
+  return actions.length
+    ? ` next=${actions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+    : "";
+}
+
 function compactRecipeRegistry(summary: Record<string, unknown>): string {
   const active = Array.isArray(summary.active) ? summary.active.length : 0;
   const shadowed = Array.isArray(summary.shadowed)
@@ -636,13 +683,43 @@ function compactRecipeRegistry(summary: Record<string, unknown>): string {
   const diagnostics = Array.isArray(summary.diagnostics)
     ? summary.diagnostics.length
     : 0;
-  const candidates = Array.isArray(summary.candidates)
-    ? summary.candidates.length
-    : 0;
+  const drafts = Array.isArray(summary.drafts)
+    ? summary.drafts.length
+    : Array.isArray(summary.candidates)
+      ? summary.candidates.length
+      : 0;
   const recommendations = Array.isArray(summary.recommendations)
     ? summary.recommendations.length
     : 0;
-  return `\nrecipes active=${active} candidates=${candidates} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
+  const nextActions = Array.isArray(summary.next_actions)
+    ? (summary.next_actions as string[])
+    : [];
+  return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
+}
+
+function actorMessageNextActions(
+  message: ActorMessages.ActorMessage,
+  result: Record<string, unknown>,
+): string[] {
+  const actions: string[] = [];
+  const address = ActorMessages.parseActorAddress(message.to);
+  if (result.delivery_error || result.sent === false) {
+    if (address.kind === "run" && address.value) {
+      actions.push(`inspect target=run:${address.value} view=status`);
+      actions.push(`inspect target=run:${address.value} view=mailbox`);
+    } else if (address.kind === "branch" && address.value) {
+      actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+      actions.push(`inspect target=run:${address.value} view=status`);
+    }
+  }
+  if (result.queued === true) {
+    if (address.kind === "branch" && address.value) {
+      actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+    } else if (address.kind === "run" && address.value) {
+      actions.push(`inspect target=run:${address.value} view=mailbox`);
+    }
+  }
+  return [...new Set(actions)].slice(0, 3);
 }
 
 function compactActorMessageResult(
@@ -670,6 +747,11 @@ function compactActorMessageResult(
   if (result.delivery_error) {
     tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
   }
+  const nextActions = Array.isArray(result.next_actions)
+    ? (result.next_actions as string[])
+    : actorMessageNextActions(message, result);
+  if (nextActions.length > 0)
+    tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
   return `\n${tokens.join(" ")}`;
 }
 
@@ -832,7 +914,7 @@ function writeSpawnCandidateRecipe(
   const defaults = candidateRecipeDefaults(meta.values);
   const recipe = {
     async: true,
-    description: `Candidate recipe captured from spawn run ${String(meta.run)}`,
+    description: `Draft recipe captured from spawn run ${String(meta.run)}`,
     ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
     ...(defaults ? { defaults } : {}),
     template: input.template,
@@ -1040,7 +1122,9 @@ export function createSpawnToolDefinition<
       const nextActions = actorRunNextActions(meta.run);
       const details = {
         ...meta,
-        ...(candidateRecipe ? { candidate_recipe: candidateRecipe } : {}),
+        ...(candidateRecipe
+          ? { candidate_recipe: candidateRecipe, draft_recipe: candidateRecipe }
+          : {}),
         next_actions: nextActions,
       };
       ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
@@ -1084,6 +1168,33 @@ function requireContextSessionId(ctx: unknown, actor: string): string {
   return sessionId;
 }
 
+function sessionMismatchError(input: {
+  currentSession?: string;
+  expectedSession?: string;
+  run?: string;
+  target?: string;
+}): Error {
+  const ownerSession = input.expectedSession ?? "none";
+  const currentSession = input.currentSession ?? "none";
+  const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
+  const hintTarget = input.expectedSession
+    ? `session:${input.expectedSession}`
+    : "session:all";
+  return Object.assign(
+    new Error(
+      `${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`,
+    ),
+    {
+      current_session: input.currentSession,
+      hint: `inspect target=${hintTarget} view=status`,
+      owner_session: input.expectedSession,
+      reason: "session_mismatch",
+      run: input.run,
+      target: input.target,
+    },
+  );
+}
+
 function assertRunAccessibleToContext(
   runId: string,
   ctx: unknown,
@@ -1091,18 +1202,11 @@ function assertRunAccessibleToContext(
   const status = AsyncRuns.getRunStatus(runId);
   const sessionId = getContextSessionId(ctx);
   if (sessionId && status.ownerId && status.ownerId !== sessionId) {
-    throw Object.assign(
-      new Error(
-        `run:${runId} reason=session_mismatch owner_session=${status.ownerId} current_session=${sessionId} hint=inspect_session:${status.ownerId}`,
-      ),
-      {
-        current_session: sessionId,
-        hint: `inspect target=session:${status.ownerId} view=status`,
-        owner_session: status.ownerId,
-        reason: "session_mismatch",
-        run: runId,
-      },
-    );
+    throw sessionMismatchError({
+      currentSession: sessionId,
+      expectedSession: String(status.ownerId),
+      run: runId,
+    });
   }
   return status;
 }
@@ -1120,7 +1224,7 @@ export function createInspectToolDefinition<TContext = unknown>(
     name: "inspect",
     label: "Inspect",
     description:
-      "Intentionally inspect an actor at decision points, after follow-ups, or during diagnosis instead of polling. Supports run:<id> views: status, tail, messages, artifacts, files, mailbox, communication; room:<run> status/messages/previews/roster/contacts; coordinator/session status; and tool:<name> status/schema.",
+      "Intentionally inspect actors at decision points, after follow-ups, or during diagnosis instead of polling. Core targets are run:<id> and tool:<name>; advanced targets include branch:<run>/<branch>, room:<run>, coordinator, session:<id>, and session:all.",
     parameters: objectSchema(
       {
         lines: stringSchema("Line count for tail/messages views. Default 40."),
@@ -1128,13 +1232,13 @@ export function createInspectToolDefinition<TContext = unknown>(
           "Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited.",
         ),
         target: stringSchema(
-          "Actor address to inspect, e.g. run:<id>, room:<run>, coordinator, session:<id>, session:all, or tool:<name>.",
+          "Actor address to inspect, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>, session:all.",
         ),
         verbose: booleanSchema(
           "Return full JSON instead of compact text where available.",
         ),
         view: stringSchema(
-          "Inspection view: status, tail, messages, artifacts, files, mailbox, communication, roster, or contacts.",
+          "Inspection view. Core run views: status, tail, messages, artifacts, files, mailbox. Advanced views include communication, roster, and contacts.",
         ),
       },
       ["target", "view"],
@@ -1169,12 +1273,19 @@ export function createInspectToolDefinition<TContext = unknown>(
           { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
         ]);
         const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
-        const summary = {
+        const summaryBase = {
           ...RecipeDiscovery.summarizeDiscovery(discovered),
+          drafts: RecipeDiscovery.listCandidateRecipes(
+            join(recipeRoot, "candidates"),
+          ),
           candidates: RecipeDiscovery.listCandidateRecipes(
             join(recipeRoot, "candidates"),
           ),
         };
+        const summary = {
+          ...summaryBase,
+          next_actions: recipeRegistryNextActions(summaryBase, view),
+        };
         return {
           content: [
             {
@@ -1488,7 +1599,14 @@ export function createInspectToolDefinition<TContext = unknown>(
               | undefined,
           );
           const details = artifactManifest
-            ? { ...status, artifact_manifest: artifactManifest }
+            ? {
+                ...status,
+                artifact_manifest: artifactManifest,
+                next_actions: artifactNextActions(
+                  status.run ?? runId,
+                  asRecord(status.artifacts),
+                ),
+              }
             : status;
           return {
             content: [
@@ -1574,7 +1692,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
     name: "message",
     label: "Message",
     description:
-      "Send one typed addressed message to steer an existing actor instead of restarting it. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, room:<run> timelines/rosters, tool:<name> calls, and coordinator/session-bound run messages.",
+      "Send one typed addressed message to steer an existing actor instead of restarting it. Core routes are run:<id> and tool:<name>; advanced routes include branch:<run>/<branch>, room:<run> group timelines, coordinator, and session:<id>.",
     parameters: objectSchema(
       {
         body: unionSchema([
@@ -1596,7 +1714,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         reply_to: stringSchema("Optional message id this message replies to."),
         summary: stringSchema("Optional short human-facing summary."),
         to: stringSchema(
-          "Destination actor address, e.g. run:<id>, branch:<run>/<branch>, room:<run>, coordinator, session:<id>, or tool:<name>.",
+          "Destination actor address, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>.",
         ),
         type: stringSchema(
           "Semantic message type, e.g. control.approve or checkpoint.needs_scope.",
@@ -1765,14 +1883,20 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         const senderStatus = assertRunAccessibleToContext(sender.value, ctx);
         if (address.kind === "session") {
           if (!senderStatus.ownerId) {
-            throw new Error(
-              `message to session:${address.value} requires sender run owner ${address.value}; got no owner.`,
-            );
+            throw sessionMismatchError({
+              currentSession: undefined,
+              expectedSession: address.value,
+              run: sender.value,
+              target: `session:${address.value}`,
+            });
           }
           if (senderStatus.ownerId !== address.value) {
-            throw new Error(
-              `message to session:${address.value} requires sender run owner ${address.value}; got ${senderStatus.ownerId}.`,
-            );
+            throw sessionMismatchError({
+              currentSession: String(senderStatus.ownerId),
+              expectedSession: address.value,
+              run: sender.value,
+              target: `session:${address.value}`,
+            });
           }
         }
         result = AsyncRuns.appendRunOutboxEvent(sender.value, {
@@ -1796,18 +1920,22 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           `message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`,
         );
       }
+      const nextActions = actorMessageNextActions(message, result);
+      const resultWithNext = nextActions.length
+        ? { ...result, next_actions: nextActions }
+        : result;
       return {
         content: [
           {
             type: "text" as const,
             text: maybeJsonText(
-              { message, result },
+              { message, result: resultWithNext },
               input.verbose === true,
-              compactActorMessageResult(message, result),
+              compactActorMessageResult(message, resultWithNext),
             ),
           },
         ],
-        details: { message, result },
+        details: { message, result: resultWithNext },
       };
     },
   };

package/package.json

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

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.31.0
+  version: 0.32.0
 ---
 
 # Actors (pi-actors)
@@ -39,12 +39,11 @@ Trusted local capability
 
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
-- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, communication snapshot, and artifacts.
-- **Room actor**: shared timeline + roster endpoint addressable as `room:<run>`; every spawned run gets `room:<run>`.
+- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
 - **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime/status inspection.
-- **Coordinator/session**: the current pi session endpoint that receives bounded actor follow-ups.
-- **Mailbox**: public interaction contract: message types the actor accepts/emits.
 - **Artifact**: named durable output path declared by a recipe/run.
+- **Mailbox**: interaction contract: message types the actor accepts/emits.
+- **Advanced group/coordination surfaces**: `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:<id>`, and communication snapshots exist for multi-actor workflows and diagnostics; do not make them the default mental model.
 
 ## Three Verbs
 
@@ -86,8 +85,9 @@ Envelope fields:
 
 - Required: `to`, `type`.
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
-- Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
-- Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
+- Core addresses: `run:<id>`, `tool:<name>`.
+- Advanced addresses: `branch:<run>/<branch>`, `room:<run>` for group timeline/roster, `coordinator`, `session:<id>`.
+- Group posts to `room:<run>` require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
 - Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 - Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
 
@@ -99,12 +99,7 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "run:repo-health", "view": "status" }
 { "target": "run:repo-health", "view": "tail", "lines": "80" }
 { "target": "run:repo-health", "view": "messages" }
-{ "target": "run:repo-health", "view": "communication" }
 { "target": "run:repo-health", "view": "artifacts" }
-{ "target": "room:repo-health", "view": "status" }
-{ "target": "room:repo-health", "view": "roster" }
-{ "target": "room:repo-health", "view": "contacts" }
-{ "target": "room:repo-health", "view": "previews" }
 { "target": "tool:pi-actors", "view": "status" }
 { "target": "tool:music_player", "view": "status" }
 { "target": "recipes", "view": "status" }
@@ -116,10 +111,10 @@ Views:
 - `status`: lifecycle, pid, values, progress, result, compact summary.
 - `tail`: recent stdout/stderr/log tail.
 - `messages`: actor messages emitted by the run, or room timeline entries for `room:*`.
-- `communication`: run/branch communication snapshot with self/root/default-room/member/contact hints.
-- `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
-- `contacts`: roster-derived direct-message targets without full roster metadata.
-- `previews`: TUI-ready bounded room message previews with timestamp/from/to/type/summary/body_preview.
+- Advanced `communication`: run/branch group-coordination snapshot with self/root/default-room/member/contact hints.
+- Advanced `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
+- Advanced `contacts`: roster-derived direct-message targets without full roster metadata.
+- Advanced `previews`: TUI-ready bounded group-message previews with timestamp/from/to/type/summary/body_preview.
 - `mailbox`: declared accepts/emits contract for runs; queued direct branch inbox messages for `branch:<run>/<branch>` with `id`, status, route/type, and queue/handling timestamps.
 - `files`: run state directory file list.
 - `artifacts`: declared artifact paths/status.
@@ -218,13 +213,13 @@ Only matching filename ids compete. Higher priority shadows lower priority; with
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
 1. `~/.pi/agent/recipes/*.json` and `*.md` are the agent's active capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Descriptions matter here because they become the tool's operator-facing title/context.
-2. `~/.pi/agent/recipes/candidates/*.json` is candidate memory captured from successful inline `spawn template=...` runs. Candidates are not registered tools and do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/candidates/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
+2. `~/.pi/agent/recipes/candidates/*.json` is draft memory captured from successful inline `spawn template=...` runs. The directory name is retained for compatibility; treat these as drafts, not active tools. Drafts do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/candidates/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
 
-Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow candidate memory by trying ad hoc actors successfully. Treat both as executable habits: candidates are the workbench/proving ground; root recipes are promoted muscle memory.
+Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow draft memory by trying ad hoc actors successfully. Treat both as executable habits: drafts are the workbench/proving ground; root recipes are promoted muscle memory.
 
 Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
 
-Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave candidate recipes as replayable evidence, not active tools. If a candidate is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
+Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave draft recipes as replayable evidence, not active tools. If a draft is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
 
 Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
 

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.31.0
+  version: 0.32.0
 ---
 
 # Swarm
@@ -30,8 +30,8 @@ Maintain this skill as a living orchestration standard. When real swarm work exp
 - `Async Run`: A local lifecycle envelope around a command-template swarm composer or utility. It owns state, logs, status, cancellation, and observability, not swarm semantics.
 - `Lens`: A deliberately narrow cognitive role assigned to one subagent, such as security, tests, architecture, economics, or operator UX.
 - `Task Card`: A bounded implementation assignment with goal, allowed files, avoided files, expected output, and validation gates.
-- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, candidate recipes, command templates, async runs, or services.
-- `Candidate Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood.
+- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, draft recipes, command templates, async runs, or services.
+- `Draft Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood. Its compatibility storage path may still include `recipes/candidates`.
 - `Coordinator Checkpoint`: A deliberate subagent pause where the subagent preserves its working context, sends a bounded question or status to the orchestrator, receives a coordinator reply, and continues in the same subagent context.
 - `Evidence Checkpoint`: A deliberate stop where a subagent records sources, assumptions, confidence, contradictions, or blocking evidence gaps before synthesis.
 - `Integrator`: The human or agent that merges isolated branches/worktrees into the shared target and owns conflict resolution.