@llblab/pi-actors 0.42.1 → 0.42.2

package/AGENTS.md

@@ -108,7 +108,7 @@ Pi host
 - Preserve node controls: `when`, positive `timeout`, `delay`, bounded `retry`, `failure`, and `recover` cleanup.
 - Persist every async command's complete byte-exact stdout/stderr under command- and retry-specific run-state paths while keeping returned tails bounded and pipeline stdin complete.
 - Keep async run state under `~/.pi/agent/tmp/pi-actors/runs` with injected `{run_id}` and `{state_dir}` values.
-- Preserve event-driven observability with bounded reconciliation: file watchers accelerate durable retrying terminal follow-up notifications, while a conservative terminal-only interval recovers missed watcher activity, rearms degraded watchers, and never replays outbox traffic. Queue coordinator context through Pi follow-up delivery rather than steering so current work finishes before async results arrive and host follow-up batching policy can combine concurrent completions. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window; watch-triggered and periodic delivery share one live-runtime in-flight guard.
+- Preserve event-driven observability with bounded reconciliation: file watchers accelerate durable retrying terminal follow-up notifications, while a conservative terminal-only interval recovers missed watcher activity, rearms degraded watchers, and never replays outbox traffic. Queue compact terminal coordinator notices through Pi follow-up delivery rather than steering so current work finishes before async results arrive and host follow-up batching policy can combine concurrent completions; LLM content contains only run id, status, one base path, and relative artifact names, while semantic output/error/correlation stays in non-LLM details and run state. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window; watch-triggered and periodic delivery share one live-runtime in-flight guard.
 - When a deferred actor result gates the next step, wait for its terminal follow-up. Do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs; inspect early only on operator request, meaningful actor event, or diagnosis of an overdue/stuck run.
 - Do not restore busy-polling examples, duplicate terminal notifications, or duplicate notifications for handled `cancel`, `kill`, or control-stop actions.
 
@@ -142,7 +142,7 @@ Pi host
 - 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.
-- Actor Inspector remains evidence-first; its `Kill` action is available only for a focused owned running run, requires in-overlay confirmation, revalidates exact ownership/status at action time, routes through canonical `control.kill`, and renders bounded success/failure feedback without direct process signaling.
+- Actor Inspector remains evidence-first; its `Kill` action is available only for a focused owned running run, requires in-overlay confirmation, revalidates exact ownership/status at action time, routes through canonical `control.kill`, and renders bounded success/failure feedback without direct process signaling. Keep active key hints in the bottom border as one blue-key/border-accent-description rail joined by border-accent `─`, never as a dedicated body row or bullet-separated footer.
 - Direct branch messages are active inbox queues; guard branch-local append/status rewrites with the branch inbox lock and keep claim/handled/failed transitions tested.
 - Run-state launch and destructive retention require the runtime ownership marker bound to the canonical directory and run id; reject non-run directories, missing/mismatched markers, and symlink aliases rather than trusting `run.json`.
 - Runner lifecycle and destructive process controls require the persisted cross-platform process identity proof (start time, command, and cwd where available), revalidated at authorization and immediately before signaling; dead, mismatched, or unsupported proofs stay distinct and fail closed rather than degrading to pid liveness. On Unix, only process-group `ESRCH` followed by another matching identity proof permits exact-pid fallback. Keep the residual post-read OS PID/PGID reuse window explicit because Node lacks one portable identity-stable group handle.

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.42.2: Inspector Key Rail and Terminal Follow-up Context
+
+- `[Inspector Key Rail]` Moved every Inspector hotkey hint onto the bottom border, replacing the dedicated two-row footer with a border-connected rail. Blue key labels remain, while descriptions and `─` connectors use the border accent instead of bullet separators; the main viewport cap rises from 16 to 24 rows. Impact: the Inspector gains two content rows without losing keyboard discoverability, and the kill confirmation dialog now shares the same visual grammar.
+- `[Terminal Follow-up Context]` Kept terminal delivery on Pi's `followUp` queue but reduced LLM content to run id, status, one base path, and relative artifact names. Bounded semantic stdout/error payloads, correlation, and adapter transport metadata remain available only in non-LLM details and run state; the launcher writes initial progress before spawning its runner, and runners write terminal progress and review evidence before the `result.json` completion marker. Impact: completed background actors no longer inject raw output or unsolicited workflow prompts into coordinator context, and result readers never see an incomplete terminal state.
+
 ## 0.42.1: Terminal Delivery and Cross-platform Validation
 
 - `[Terminal Delivery]` Added one bounded semantic terminal result with durable launch/tool-call correlation and bounded adapter-provided transport context. Explicit advertised semantic envelopes win; successful accepted reviews that advertise `review.completed` deterministically synthesize it when absent, while failed runs include their terminal error. Watcher and reconciliation delivery share the existing live in-flight dedupe guard, failed sends persist bounded retry evidence without writing the handled marker, and status exposes the latest failure. Impact: coordinators and Telegram-style chat/thread adapters can retain the exact launch/result relationship across detached completion instead of receiving only run-file metadata.

package/README.md

@@ -293,9 +293,7 @@ Packaged recipes are building blocks. Use `spawn file=<recipe>` for maintained p
 | A useful output that should survive context compression | Artifacts |
 | A repeated local workflow | Recipe/tool memory |
 
-When a directly spawned inline/ad hoc actor or a recipe outside the user recipe root completes successfully, `pi-actors` may include a promotion suggestion in its terminal follow-up notification. The agent should ask first and never auto-save.
-
-Terminal completion returns one bounded semantic result to the originating coordinator, not only run-state paths. `spawn` and saved async tools preserve their tool-call correlation automatically; callers may add `correlation_id` plus bounded `transport_context` when an adapter must retain an exact detached route, including Telegram `chat_id`/`thread_id`. Recipes that advertise `review.completed` either emit that envelope explicitly or receive one synthesized from successfully accepted review output. Watcher and periodic reconciliation share one in-flight guard, while failed sends remain retryable and visible in run status.
+Terminal completion queues a minimal follow-up with run id, status, one base path, and relative artifact names only. Bounded semantic output, launch/tool-call correlation, and optional transport context remain in non-LLM follow-up details and run state, so adapters retain the exact launch/result relationship without injecting actor output into coordinator context. Inspect the run before deciding whether a successful pattern deserves recipe persistence; never auto-save without the operator's confirmation.
 
 ## Platform support
 

package/dist/lib/async-runs.js

@@ -321,6 +321,13 @@ export function startRun(params, cwd) {
                 ? { transport_context: transportContext } : {}),
         };
         writeJsonAtomic(join(stateDir, "run.json"), meta);
+        writeJsonAtomic(join(stateDir, "progress.json"), {
+            completed: 0,
+            failures: [],
+            model_policy: modelPolicy,
+            phase: "starting",
+            updatedAt: new Date().toISOString(),
+        });
         const child = spawn(process.execPath, argv, {
             cwd,
             detached: true,
@@ -333,13 +340,6 @@ export function startRun(params, cwd) {
         if (processIdentity)
             meta.process_identity = processIdentity;
         writeJsonAtomic(join(stateDir, "run.json"), meta);
-        writeJsonAtomic(join(stateDir, "progress.json"), {
-            completed: 0,
-            failures: [],
-            model_policy: modelPolicy,
-            phase: "starting",
-            updatedAt: new Date().toISOString(),
-        });
         writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event: "run.start", run, run_instance_id: meta.run_instance_id, pid: meta.pid, ts: new Date().toISOString() })}\n`, { flag: "a" });
         child.unref();
         return meta;

package/dist/lib/inspector-overlay.d.ts

@@ -104,6 +104,7 @@ export declare class ActorInspectorOverlay {
     private openDetail;
     private backDetail;
     private closeDetail;
+    private footerBorder;
     private border;
     private stripeBackground;
     private stripedRow;

package/dist/lib/inspector-overlay.js

@@ -239,7 +239,7 @@ export class ActorInspectorOverlay {
         if (selectorTop) {
             const leadingBorder = "─".repeat(selectorAnchor);
             const remainingBorder = "─".repeat(Math.max(0, innerWidth - visibleWidth(selectorTop) - selectorAnchor));
-            lines.push(`${this.theme.fg("border", `├${leadingBorder}`)}${selectorTop}${this.theme.fg("border", `${remainingBorder}┤`)}`);
+            lines.push(`${this.theme.fg("borderAccent", `├${leadingBorder}`)}${selectorTop}${this.theme.fg("borderAccent", `${remainingBorder}┤`)}`);
         }
         else
             lines.push(this.border("├", "", "┤", innerWidth));
@@ -280,9 +280,7 @@ export class ActorInspectorOverlay {
             const preservedBase = this.stripeBackground(this.fit(this.dropVisiblePrefix(base, popupWidth + popupAnchor), baseWidth), stripeIndex);
             lines.push(this.row(`${leadingBase}${visiblePopup}${preservedBase}`, innerWidth, true));
         }
-        lines.push(this.border("├", "", "┤", innerWidth));
-        lines.push(this.row(this.renderKeyHints(), innerWidth));
-        lines.push(this.border("╰", "", "╯", innerWidth));
+        lines.push(this.footerBorder(this.renderKeyHints(), innerWidth));
         return lines;
     }
     invalidate() { }
@@ -298,7 +296,7 @@ export class ActorInspectorOverlay {
     }
     contentViewportRows() {
         const overlayRows = Math.floor(this.tui.terminal.rows * 0.94);
-        return Math.max(4, Math.min(16, overlayRows - 7));
+        return Math.max(4, Math.min(24, overlayRows - 5));
     }
     selectRun(run, index) {
         this.selectedRun = run;
@@ -380,7 +378,7 @@ export class ActorInspectorOverlay {
     }
     renderKillDialog(_width, innerWidth) {
         const confirmation = this.killConfirmation;
-        const totalRows = this.contentViewportRows() + 7;
+        const totalRows = this.contentViewportRows() + 5;
         const cancel = this.killDialogChoice === "cancel"
             ? this.theme.bg("selectedBg", this.theme.fg("accent", "  Cancel  "))
             : this.theme.fg("muted", "  Cancel  ");
@@ -411,7 +409,7 @@ export class ActorInspectorOverlay {
             dialogRows.push("");
         for (const line of dialogRows)
             lines.push(this.row(this.center(line, innerWidth), innerWidth));
-        lines.push(this.border("╰", " ←→/tab choose · enter activate · esc cancel ", "╯", innerWidth));
+        lines.push(this.footerBorder(this.renderKeyHints(), innerWidth));
         return lines;
     }
     listItemCount() {
@@ -435,27 +433,34 @@ export class ActorInspectorOverlay {
         return Math.max(0, tabs.indexOf(label) - 2);
     }
     renderKeyHints() {
-        const hint = (keys, description) => `${this.theme.fg("accent", keys)}${this.theme.fg("dim", ` ${description}`)}`;
+        const hint = (keys, description) => `${this.theme.fg("accent", keys)}${this.theme.fg("borderAccent", ` ${description}`)}`;
+        const divider = this.theme.fg("borderAccent", " ─ ");
+        const hints = (...items) => items.map(([keys, description]) => hint(keys, description)).join(divider);
         if (this.killConfirmation)
-            return ` ${hint("y/enter", "confirm kill")}  ${hint("n/esc", "cancel")}`;
+            return hints(["←→/tab", "choose"], ["enter/y", "confirm"], ["esc/n", "cancel"]);
         if (this.focus === "select")
             return this.menuLevel === "value"
-                ? ` ${hint("↑↓", "option")}  ${hint("enter", "apply")}  ${hint("←/esc", "back")}`
-                : ` ${hint("↑↓", "option")}  ${hint("→/enter", "open")}  ${hint("←/esc", "back")}`;
+                ? hints(["↑↓", "option"], ["enter", "apply"], ["←/esc", "back"])
+                : hints(["↑↓", "option"], ["→/enter", "open"], ["←/esc", "back"]);
         if (this.focus === "recipe")
-            return ` ${hint("↑↓/pgup/pgdn", "scroll")}  ${hint("↑ at top", "tabs")}  ${hint("←/esc", "tabs")}`;
+            return hints(["↑↓/pgup/pgdn", "scroll"], ["↑ at top", "tabs"], ["←/esc", "tabs"]);
         if (this.focus === "detail")
-            return ` ${hint("↑↓/pgup/pgdn", "scroll")}  ${hint("←/esc", "back")}`;
+            return hints(["↑↓/pgup/pgdn", "scroll"], ["←/esc", "back"]);
         if (this.focus === "list")
-            return ` ${hint("↑↓/pgup/pgdn", "row")}  ${hint("→/enter", "open")}  ${hint("←", "tabs")}  ${hint("esc", "close")}`;
+            return hints(["↑↓/pgup/pgdn", "row"], ["→/enter", "open"], ["←", "tabs"], ["esc", "close"]);
         if (this.focus === "runs") {
+            const items = [
+                ["←→", "run"],
+                ["↓", "tabs"],
+                ["enter", "list"],
+            ];
             const run = this.runs().find((item) => item.run === this.selectedRun);
-            const killHint = this.killRun && run?.status === "running" && run.runInstanceId
-                ? `  ${hint("k", "kill")}`
-                : "";
-            return ` ${hint("←→", "run")}  ${hint("↓", "tabs")}  ${hint("enter", "list")}${killHint}  ${hint("esc", "close")}`;
+            if (this.killRun && run?.status === "running" && run.runInstanceId)
+                items.push(["k", "kill"]);
+            items.push(["esc", "close"]);
+            return hints(...items);
         }
-        return ` ${hint("←→", "navigate")}  ${hint("↑↓", "change row")}  ${hint("enter", "select")}  ${hint("esc", "close")}`;
+        return hints(["←→", "navigate"], ["↑↓", "change row"], ["enter", "select"], ["esc", "close"]);
     }
     renderRunControl() {
         const runs = this.runs();
@@ -1013,7 +1018,7 @@ export class ActorInspectorOverlay {
         const hiddenAbove = start > 0;
         const hiddenBelow = start + visibleOptions.length < options.length;
         const contentWidth = Math.max(4, ...options.map((option) => visibleWidth(option) + 4));
-        const border = (left, right, marker = "") => this.theme.fg("border", `${omitLeftBorder ? "" : left}${marker}${"─".repeat(Math.max(0, contentWidth - visibleWidth(marker)))}${omitRightBorder ? "" : right}`);
+        const border = (left, right, marker = "") => this.theme.fg("borderAccent", `${omitLeftBorder ? "" : left}${marker}${"─".repeat(Math.max(0, contentWidth - visibleWidth(marker)))}${omitRightBorder ? "" : right}`);
         return [
             border("╭", "╮", hiddenAbove ? "↑" : ""),
             ...visibleOptions.map((option, localIndex) => {
@@ -1026,7 +1031,7 @@ export class ActorInspectorOverlay {
                 const styled = focused || index === parentIndex
                     ? this.theme.bg("selectedBg", colored)
                     : colored;
-                return `${omitLeftBorder ? "" : this.theme.fg("border", "│")}${styled}${omitRightBorder ? "" : this.theme.fg("border", "│")}`;
+                return `${omitLeftBorder ? "" : this.theme.fg("borderAccent", "│")}${styled}${omitRightBorder ? "" : this.theme.fg("borderAccent", "│")}`;
             }),
             border("╰", "╯", hiddenBelow ? "↓" : ""),
         ];
@@ -1068,10 +1073,17 @@ export class ActorInspectorOverlay {
         this.detailScroll = 0;
         this.focus = "list";
     }
+    footerBorder(hints, width) {
+        const prefix = " ";
+        const suffix = " ─";
+        const content = truncateToWidth(hints, Math.max(0, width - visibleWidth(prefix) - visibleWidth(suffix)), "");
+        const fill = "─".repeat(Math.max(0, width - visibleWidth(prefix) - visibleWidth(suffix) - visibleWidth(content)));
+        return `${this.theme.fg("borderAccent", `╰${prefix}`)}${content}${this.theme.fg("borderAccent", `${suffix}${fill}╯`)}`;
+    }
     border(left, title, right, width) {
         const titleText = truncateToWidth(title, width, "");
         const fill = "─".repeat(Math.max(0, width - visibleWidth(titleText)));
-        return this.theme.fg("border", `${left}${titleText}${fill}${right}`);
+        return this.theme.fg("borderAccent", `${left}${titleText}${fill}${right}`);
     }
     stripeBackground(content, index) {
         if (index % 2 === 0)
@@ -1086,7 +1098,7 @@ export class ActorInspectorOverlay {
     }
     row(content, width, fitted = false) {
         const body = fitted ? content : this.fit(content, width);
-        return `${this.theme.fg("border", "│")}${body}${this.theme.fg("border", "│")}`;
+        return `${this.theme.fg("borderAccent", "│")}${body}${this.theme.fg("borderAccent", "│")}`;
     }
     takeVisiblePrefix(content, width) {
         const plain = stripVTControlCharacters(content);

package/dist/lib/observability.d.ts

@@ -181,5 +181,4 @@ export declare function formatRunOutboxMessage(event: RunOutboxEvent): string;
 export declare function getRunTransitionNotificationType(transition: RunTransition): RunTransitionNotificationType;
 export declare function shouldNotifyRunTransition(transition: RunTransition): boolean;
 export declare function shouldSendRunTransitionFollowUp(transition: RunTransition): boolean;
-export declare function shouldSuggestRecipePersistence(transition: RunTransition): boolean;
 export declare function formatRunTransitionMessage(transition: RunTransition): string;

package/dist/lib/observability.js

@@ -4,7 +4,7 @@
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
 import { closeSync, existsSync, fstatSync, openSync, readdirSync, readFileSync, readSync, watch, } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
 import { readJsonlFileResilient } from "./state-readers.js";
@@ -958,94 +958,29 @@ export function shouldNotifyRunTransition(transition) {
 export function shouldSendRunTransitionFollowUp(transition) {
     return shouldNotifyRunTransition(transition);
 }
-function getRunArtifacts(transition) {
-    if (!transition.stateDir)
-        return [];
-    return [
-        join(transition.stateDir, "stdout.log"),
-        join(transition.stateDir, "stderr.log"),
-        join(transition.stateDir, "result.json"),
-        join(transition.stateDir, "events.jsonl"),
-        join(transition.stateDir, "outbox.jsonl"),
-    ];
-}
-function isUserRecipeFile(file) {
-    if (!file)
-        return false;
-    const recipeRoot = resolve(Paths.getRecipeRoot());
-    const path = resolve(file);
-    const relation = relative(recipeRoot, path);
-    return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
-}
-export function shouldSuggestRecipePersistence(transition) {
-    if (transition.to !== "done")
-        return false;
-    if (isUserRecipeFile(transition.recipeFile))
-        return false;
-    return Boolean(transition.recipeFile) || transition.launchSource === "spawn";
-}
-function formatRecipePersistenceSuggestion(transition) {
-    if (!shouldSuggestRecipePersistence(transition))
-        return "";
-    if (transition.recipeFile) {
-        return `\nAgent note: this actor completed successfully from recipe ${transition.recipeFile}. If this recipe fits this machine's recurring workflow, ask the operator whether to copy or register it as a durable tool recipe under ~/.pi/agent/recipes. Do not auto-save without confirmation.`;
-    }
-    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 formatTransitionPolicy(transition) {
-    if (!transition.modelPolicy)
-        return "";
-    const axis = (key, label) => {
-        const value = transition.modelPolicy?.[key];
-        if (!value || typeof value !== "object" || Array.isArray(value))
-            return undefined;
-        const record = value;
-        const source = typeof record.source === "string" ? record.source : "unused";
-        if (source === "unused")
-            return undefined;
-        const renderedValue = typeof record.value === "string" && record.value.trim()
-            ? ` (${record.value.trim()})`
-            : "";
-        return `${label}: ${source}${renderedValue}`;
-    };
-    const lines = [axis("model", "Model"), axis("thinking", "Thinking")].filter((line) => Boolean(line));
-    return lines.length ? `\nPolicy:\n- ${lines.join("\n- ")}` : "";
-}
-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(" | ")}`;
-}
-function formatTransitionSemanticResult(transition) {
-    const result = transition.semanticResult;
-    if (!result)
-        return "";
-    const correlation = result.correlationId
-        ? `\nCorrelation: ${result.correlationId}` : "";
-    const body = result.body ? `\nResult:\n${result.body}` : "";
-    return `\nSemantic result: ${result.type} — ${result.summary}${correlation}${body}`;
+const TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT = 4;
+const TERMINAL_FOLLOW_UP_IDENTIFIER_CHARS = 120;
+const TERMINAL_FOLLOW_UP_PATH_CHARS = 320;
+function compactTerminalText(value, limit) {
+    const compact = value.replaceAll(/\s+/g, " ").trim();
+    return compact.length > limit ? `${compact.slice(0, limit - 1)}…` : compact;
+}
+function formatTerminalPath(path) {
+    return `\`${compactTerminalText(path, TERMINAL_FOLLOW_UP_PATH_CHARS)}\``;
+}
+function formatTerminalResultLocations(transition) {
+    const artifactPaths = [...new Set(Object.values(transition.artifacts ?? {}).filter((path) => typeof path === "string" && path.length > 0))];
+    if (artifactPaths.length === 0)
+        return transition.stateDir ? `\nBase: ${formatTerminalPath(transition.stateDir)}` : "";
+    const base = commonDirectory(artifactPaths);
+    const artifactPreview = artifactPaths
+        .slice(0, TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT)
+        .map((path) => formatTerminalPath(base ? relativeName(base, path) : path));
+    const omitted = artifactPaths.length - artifactPreview.length;
+    const artifacts = `${artifactPreview.join(", ")}${omitted > 0 ? ` (+${omitted} more)` : ""}`;
+    return `${base ? `\nBase: ${formatTerminalPath(base)}` : ""}\nArtifacts: ${artifacts}`;
 }
 export function formatRunTransitionMessage(transition) {
-    const artifacts = formatNamedArtifacts(transition.artifacts);
-    const runFiles = formatRunFileList(getRunArtifacts(transition));
-    const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
-    const policy = formatTransitionPolicy(transition);
-    const nextActions = formatTransitionNextActions(transition);
-    const semanticResult = formatTransitionSemanticResult(transition);
-    if (transition.to === "done")
-        return `Run ${transition.run} completed successfully.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
-    if (transition.to === "failed")
-        return `Run ${transition.run} failed.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}`;
-    if (transition.to === "cancelled")
-        return `Run ${transition.run} was cancelled.${policy}${nextActions}`;
-    if (transition.to === "killed")
-        return `Run ${transition.run} was force-killed.${policy}${nextActions}`;
-    if (transition.to === "exited")
-        return `Run ${transition.run} exited before writing a result.${policy}${nextActions}`;
-    return `Run ${transition.run} finished with status ${transition.to}.${policy}${nextActions}`;
+    const run = compactTerminalText(transition.run, TERMINAL_FOLLOW_UP_IDENTIFIER_CHARS);
+    return `Run: \`${run}\`\nStatus: \`${transition.to}\`${formatTerminalResultLocations(transition)}`;
 }

package/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -23,7 +23,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;

package/dist/scripts/async-runner.mjs

@@ -517,6 +517,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       };
       throw error;
     }
+    writeEvidenceManifest("done");
+    progress("done", {
+      completed: 1,
+      failures: result.details.nonCriticalFailures || [],
+    });
     writeJsonAtomic(resultPath, {
       code: result.details.code,
       command: result.details.command,
@@ -525,26 +530,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       truncated: result.details.truncated,
       completedAt: new Date().toISOString(),
     });
-    writeEvidenceManifest("done");
-    progress("done", {
-      completed: 1,
-      failures: result.details.nonCriticalFailures || [],
-    });
     event("run.done", { code: result.details.code });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const details = error && typeof error === "object" ? error.details : undefined;
     appendFileSync(stderrPath, `${message}\n`);
-    writeJsonAtomic(resultPath, {
-      code: typeof details?.code === "number" ? details.code : 1,
-      error: message,
-      killed: Boolean(details?.killed),
-      ...(Array.isArray(details?.branches) ? { branches: details.branches } : {}),
-      ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),
-      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
-      ...(details?.softQuorum ? { soft_quorum: details.softQuorum } : {}),
-      completedAt: new Date().toISOString(),
-    });
     writeEvidenceManifest("failed");
     progress("failed", {
       completed: 0,
@@ -555,6 +545,16 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
           : [{ message }],
       ...(details?.failureReason ? { failureReason: details.failureReason } : {}),
     });
+    writeJsonAtomic(resultPath, {
+      code: typeof details?.code === "number" ? details.code : 1,
+      error: message,
+      killed: Boolean(details?.killed),
+      ...(Array.isArray(details?.branches) ? { branches: details.branches } : {}),
+      ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),
+      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
+      ...(details?.softQuorum ? { soft_quorum: details.softQuorum } : {}),
+      completedAt: new Date().toISOString(),
+    });
     event("run.failed", {
       error: message,
       ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use, including parallel actor launches, subagent fanout, and autonomous coordinator workflows. 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.42.1
+  version: 0.42.2
 ---
 
 # Actors (pi-actors)
@@ -69,7 +69,7 @@ Rules:
 - Command-template strings execute directly without a shell. Operators such as `&&`, `||`, pipes, redirects, and `cd` remain literal argv unless an explicit trusted shell is the executable. Prefer absolute paths or template arrays for sequencing; put non-trivial shell behavior in a reviewed script.
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
-- When a successful actor follow-up suggests persistence, decide whether the pattern deserves durable tool memory; call `register_tool` yourself only when the evidence is strong, and ask before writing the user recipe root.
+- Terminal follow-up context contains only run id, status, one base path, and relative artifact names. Inspect the run for contents; semantic output and correlation remain in non-LLM details and state. Decide whether a successful pattern deserves durable tool memory only after inspection, and ask before writing the user recipe root.
 - Use stable `as` names when you will inspect or message the actor later.
 - Public run state is runtime-owned; do not pass custom `state_dir` paths. This keeps `run:<id>` addressability and retention on one boundary.
 - `async: true` on the recipe is the detached run switch.
@@ -126,7 +126,7 @@ Views:
 - `artifacts`: declared artifact paths/status plus the same bounded owned review-evidence manifest when present.
 - `recipes` target: registry summary for active, shadowed, invalid, disabled, and diagnostic recipe entries.
 
-Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
+Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. Their LLM context content stays limited to run id, status, one base path, and relative artifact names; inspect state for raw output while correlation and semantic details remain outside LLM context. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
 
 ## Runtime Communication Rules
 

package/dist/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
 metadata:
-  version: 0.42.1
+  version: 0.42.2
 ---
 
 # Swarm

package/docs/actor-inspector.md

@@ -31,7 +31,7 @@ Navigation stays bounded by available actions. `↑` on Run does nothing because
 
 `K` appears only while Run is focused and the selected owned run reports `running`. It replaces the Inspector with a dedicated responsive `Confirm Actor Kill` overlay that names the exact `run:<id>`, shows its current status, and states that canonical `control.kill` is destructive and irreversible. Cancel owns initial focus; ←/→/Tab moves between Cancel and Kill actor, Enter activates the focused choice, `Y` confirms directly, and `N`/Escape cancels. Confirmation captures the immutable run generation and routes expected owner/generation through canonical `control.kill`; control compares owner, generation, and running status while serialized against same-directory restart, so terminal, ownership, or replacement-generation races reject without signaling. After the dialog closes, success, cancellation, rejection, and failure remain bounded in the Inspector content area; terminal runs expose no Kill hint and reject a stale keypress.
 
-Selection and focus remain separate visual states. Accent-blue text marks the current tab, active filter popup, and applied option. The Run control uses `← … →` markers plus a light neutral background to show both focus and horizontal cycling; menus and timeline rows retain the single `▶` focus marker, while selected tabs retain brackets. Opening a popup keeps its parent filter blue so the relationship remains visible. The footer uses accent color only for key names and arrows; descriptions remain muted.
+Selection and focus remain separate visual states. Accent-blue text marks the current tab, active filter popup, and applied option. The Run control uses `← … →` markers plus a light neutral background to show both focus and horizontal cycling; menus and timeline rows retain the single `▶` focus marker, while selected tabs retain brackets. Opening a popup keeps its parent filter blue so the relationship remains visible. Key hints live directly in the bottom overlay border rather than a dedicated body row: border-accent `─` connectors run through and between them instead of bullet glyphs, while key names and arrows retain blue accent color and descriptions use the border accent.
 
 The top Run control aligns vertically with the tab labels, names the selected owned run, and colors its textual lifecycle status semantically. ←/→ cycles owned runs directly with wraparound, while Enter opens the complete owned-run list immediately beneath the control. That run list starts one cell farther left than the filter menus so its border aligns with the Run control rather than the tab/filter grid. It still overlays the tab row rather than leaving a detached gap. The timeline no longer renders run metadata as a data row.
 
@@ -39,7 +39,7 @@ Filters live behind their tab rather than occupying a permanent row. Non-default
 
 Nested menus overlay rather than replace the timeline. Only rows and columns containing menu borders or values occlude underlying cells. When adjacent menus have different heights, the unused corner remains transparent and preserves the separator, striped background, and timeline data beneath it. Every run, filter, and nested value menu is viewport-bounded: ↑/↓ moves through the complete option set, the visible window follows focus, and `↑`/`↓` border markers disclose hidden options above or below without growing past the available inspector rows.
 
-The overlay uses most of the available terminal width and height and reduces its content/menu viewport on shorter terminals. The bordered header keeps all three tabs visible, while the body shows the selected run and its current status above the active document or evidence rows. Run, Message, and Turn lists place the newest retained item directly below their control; a newly opened Inspector therefore selects the latest owned run, and ↓ moves backward in time toward older entries. Run options, Messages, and Turns all use compact descending `#N` labels, providing one timestamp-free time axis without repeating type words on every row. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. Unused viewport padding stays on the plain overlay background instead of drawing fake striped rows beneath the last item. The footer exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
+The overlay uses most of the available terminal width and height and reduces its content/menu viewport on shorter terminals. Its border-embedded key rail replaces the former three-row footer, returning two rows to a viewport that now caps at 24 rows. The bordered header keeps all three tabs visible, while the body shows the selected run and its current status above the active document or evidence rows. Run, Message, and Turn lists place the newest retained item directly below their control; a newly opened Inspector therefore selects the latest owned run, and ↓ moves backward in time toward older entries. Run options, Messages, and Turns all use compact descending `#N` labels, providing one timestamp-free time axis without repeating type words on every row. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. Unused viewport padding stays on the plain overlay background instead of drawing fake striped rows beneath the last item. The bottom frame exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
 
 ## Recipe Document
 

package/docs/async-runs.md

@@ -83,7 +83,7 @@ Use `run_id` on async recipe tools or `as: "run:<id>"` on `spawn` when the calle
 
 Review commands that require semantic evidence apply marker acceptance before command completion accounting. Rejected code-zero output is reported consistently as a failed command in events, progress, evidence, and outbox delivery; it cannot emit a success-level completion notification. Evidence records are written before command launch and lifecycle cancellation or kill finalizes any running record with its interrupted state, effective exit code, and attempt capture paths. Async attempt stdout/stderr files exist from attempt start, so even small partial streams remain auditable when a command never returns.
 
-Terminal follow-ups carry one bounded semantic result in addition to run-file and artifact references. Direct `spawn` and saved async tools persist the originating tool-call correlation; callers may also provide `correlation_id` and a bounded scalar `transport_context`. A transport adapter can preserve an exact route such as `{ "transport": "telegram", "chat_id": 123456, "thread_id": 77 }`, and the same metadata is returned inside terminal follow-up details after detached completion. When a recipe advertises `review.completed`, an explicit matching outbox envelope wins; otherwise a successful accepted review result deterministically synthesizes one from the bounded beginning of `stdout.log`. Failed runs carry their bounded terminal error as `run.failed`.
+Terminal follow-up content stays deliberately minimal: run id, status, one base path, and relative artifact names only. With declared artifacts, `Base` names their common directory and `Artifacts` lists bounded relative names; without them, `Base` names the run state directory. It never embeds stdout, stderr, semantic body, terminal error, model policy, persistence advice, completion type, or an inspect command into LLM context. The follow-up's non-LLM details retain one bounded semantic result, launch/tool-call correlation, and optional bounded scalar `transport_context`; a transport adapter can preserve an exact route such as `{ "transport": "telegram", "chat_id": 123456, "thread_id": 77 }`. When a recipe advertises `review.completed`, an explicit matching outbox envelope wins; otherwise a successful accepted review result deterministically synthesizes one from the bounded beginning of `stdout.log`. Failed runs retain their bounded terminal error as `run.failed` details.
 
 Watcher acceleration and periodic reconciliation share one live in-flight guard. Delivery remains at-least-once across the send/handled-marker crash window, but reentrant watcher/reconciliation races do not create parallel sends. A send failure leaves the run unhandled for retry, notifies the active operator, and persists bounded attempts/error/status evidence in `terminal-delivery-failure.json`; `getRunStatus` exposes the latest record as `terminal_delivery_failure`.
 
@@ -96,12 +96,12 @@ Use ordinary files under the extension temp directory so status tools stay simpl
 - `communication.json`: compact actor communication snapshot with self/root/parent, default-room, member, and contact hints for room-aware scripts and agents.
 - `progress.json`: phase, active command count, completed count, failures, updated time, and optional `model_policy` provenance for inherited/explicit model and thinking values.
 - `events.jsonl`: append-only implementation lifecycle log.
-- `outbox.jsonl`: implementation storage for actor-message envelopes used by `inspect view=messages`, coordinator notifications, or follow-up context. Coordinator follow-ups preserve bounded `body` previews plus message metadata for decision points.
+- `outbox.jsonl`: implementation storage for actor-message envelopes used by `inspect view=messages`, coordinator notifications, or follow-up context. Script-authored decision-point follow-ups may preserve bounded `body` previews plus message metadata; automatic terminal follow-ups stay limited to run id, status, one base path, and relative artifact names.
 - `stdout.log` and `stderr.log`: detached process output.
 - `prompts/command-NNN.md`: state-owned prompt files that collapse child `pi -p` natural-language positional fragments and appended recipe context into one authoritative `@file` prompt while preserving intentional file/image arguments.
 - `captures/command-NNN/attempt-NNN/{stdout,stderr}.log`: complete byte-exact command streams, retained even below the bounded in-memory capture limit and separated across retries.
 - `review-evidence.json`: stable command/stage manifest linking prompts, repeated branches, capture attempts, byte counts, exit state, semantic marker acceptance, recipe context, and model/thinking policy; terminal status aligns with the run. Review pipelines inject prior-stage `ACTOR_EVIDENCE_REF` values into downstream prompts, record cited/missing report sources, and fail closed if a normalized report claims `complete` without every required reviewer, verifier, merger, and judge reference.
-- `result.json`: final code, killed flag, output selector, and optional full-output path.
+- `result.json`: final code, killed flag, output selector, and optional full-output path. It publishes only after terminal `progress.json` and `review-evidence.json`, so readers never observe a result before its terminal state.
 - `terminal-delivery-failure.json`: latest bounded failed follow-up attempt count, status, error, and timestamp; a later successful retry writes `terminal-handled.json`.
 - `terminal-handled.json`: durable proof that terminal follow-up delivery or an explicit terminal control completed; notification delivery writes it only after the follow-up send returns successfully.
 
@@ -143,7 +143,7 @@ The core loop is:
    { "recipe": "music-player.json", "as": "run:music" }
    ```
 
-2. Let terminal completion, `command.done`, and script-authored follow-up messages reach the launching coordinator automatically. When a directly spawned inline/ad hoc actor or a recipe outside `~/.pi/agent/recipes` completes successfully, the coordinator follow-up tells the agent to offer recipe persistence only as a question to the operator; it must not auto-save.
+2. Let terminal completion, `command.done`, and script-authored follow-up messages reach the launching coordinator automatically. Terminal completion gives the coordinator only run id, status, a base path, and relative artifact names; inspect the run when result content changes the next decision. Decide whether a successful pattern deserves recipe persistence only after inspection and operator confirmation.
 
 3. Respond with explicit run-local messages when needed:
 

package/docs/recipe-library.md

@@ -135,7 +135,7 @@ The repeatable smoke surface is the normal validation suite:
 npm test
 ```
 
-The scenario coverage is intentionally local-first and bounded: shared room coordination and roster snapshots (`rooms` / `tools` tests), direct branch delivery and claim/handle transitions (`tools` and coordinator tests), inspector navigation (`inspector` tests), recipe context injection (`recipes-context` / async-runs tests), recipe persistence suggestions (`observability` tests), and opt-in retirement candidate/execution smoke (`observability` / async-runs tests). These scenarios exercise public `spawn` / `message` / `inspect` behavior or the packaged script surfaces rather than relying on manual swarm demos.
+The scenario coverage is intentionally local-first and bounded: shared room coordination and roster snapshots (`rooms` / `tools` tests), direct branch delivery and claim/handle transitions (`tools` and coordinator tests), inspector navigation (`inspector` tests), recipe context injection (`recipes-context` / async-runs tests), compact terminal follow-up delivery (`observability` tests), and opt-in retirement candidate/execution smoke (`observability` / async-runs tests). These scenarios exercise public `spawn` / `message` / `inspect` behavior or the packaged script surfaces rather than relying on manual swarm demos.
 
 ## Music Player
 

package/lib/async-runs.ts

@@ -573,6 +573,13 @@ export function startRun(
         ? { transport_context: transportContext } : {}),
     };
     writeJsonAtomic(join(stateDir, "run.json"), meta);
+    writeJsonAtomic(join(stateDir, "progress.json"), {
+      completed: 0,
+      failures: [],
+      model_policy: modelPolicy,
+      phase: "starting",
+      updatedAt: new Date().toISOString(),
+    });
     const child = spawn(process.execPath, argv, {
       cwd,
       detached: true,
@@ -589,13 +596,6 @@ export function startRun(
     );
     if (processIdentity) meta.process_identity = processIdentity;
     writeJsonAtomic(join(stateDir, "run.json"), meta);
-    writeJsonAtomic(join(stateDir, "progress.json"), {
-      completed: 0,
-      failures: [],
-      model_policy: modelPolicy,
-      phase: "starting",
-      updatedAt: new Date().toISOString(),
-    });
     writeFileSync(
       join(stateDir, "events.jsonl"),
       `${JSON.stringify({ event: "run.start", run, run_instance_id: meta.run_instance_id, pid: meta.pid, ts: new Date().toISOString() })}\n`,

package/lib/inspector-overlay.ts

@@ -270,7 +270,7 @@ export class ActorInspectorOverlay {
         Math.max(0, innerWidth - visibleWidth(selectorTop) - selectorAnchor),
       );
       lines.push(
-        `${this.theme.fg("border", `├${leadingBorder}`)}${selectorTop}${this.theme.fg("border", `${remainingBorder}┤`)}`,
+        `${this.theme.fg("borderAccent", `├${leadingBorder}`)}${selectorTop}${this.theme.fg("borderAccent", `${remainingBorder}┤`)}`,
       );
     } else lines.push(this.border("├", "", "┤", innerWidth));
     this.contentStripeIndices = [];
@@ -322,9 +322,7 @@ export class ActorInspectorOverlay {
       );
       lines.push(this.row(`${leadingBase}${visiblePopup}${preservedBase}`, innerWidth, true));
     }
-    lines.push(this.border("├", "", "┤", innerWidth));
-    lines.push(this.row(this.renderKeyHints(), innerWidth));
-    lines.push(this.border("╰", "", "╯", innerWidth));
+    lines.push(this.footerBorder(this.renderKeyHints(), innerWidth));
     return lines;
   }
 
@@ -344,7 +342,7 @@ export class ActorInspectorOverlay {
 
   private contentViewportRows(): number {
     const overlayRows = Math.floor(this.tui.terminal.rows * 0.94);
-    return Math.max(4, Math.min(16, overlayRows - 7));
+    return Math.max(4, Math.min(24, overlayRows - 5));
   }
 
   private selectRun(run: string, index: number): void {
@@ -438,7 +436,7 @@ export class ActorInspectorOverlay {
 
   private renderKillDialog(_width: number, innerWidth: number): string[] {
     const confirmation = this.killConfirmation!;
-    const totalRows = this.contentViewportRows() + 7;
+    const totalRows = this.contentViewportRows() + 5;
     const cancel = this.killDialogChoice === "cancel"
       ? this.theme.bg("selectedBg", this.theme.fg("accent", "  Cancel  "))
       : this.theme.fg("muted", "  Cancel  ");
@@ -468,7 +466,7 @@ export class ActorInspectorOverlay {
     while (dialogRows.length < availableRows) dialogRows.push("");
     for (const line of dialogRows)
       lines.push(this.row(this.center(line, innerWidth), innerWidth));
-    lines.push(this.border("╰", " ←→/tab choose · enter activate · esc cancel ", "╯", innerWidth));
+    lines.push(this.footerBorder(this.renderKeyHints(), innerWidth));
     return lines;
   }
 
@@ -495,27 +493,53 @@ export class ActorInspectorOverlay {
 
   private renderKeyHints(): string {
     const hint = (keys: string, description: string) =>
-      `${this.theme.fg("accent", keys)}${this.theme.fg("dim", ` ${description}`)}`;
+      `${this.theme.fg("accent", keys)}${this.theme.fg("borderAccent", ` ${description}`)}`;
+    const divider = this.theme.fg("borderAccent", " ─ ");
+    const hints = (...items: Array<[string, string]>) =>
+      items.map(([keys, description]) => hint(keys, description)).join(divider);
     if (this.killConfirmation)
-      return ` ${hint("y/enter", "confirm kill")}  ${hint("n/esc", "cancel")}`;
+      return hints(
+        ["←→/tab", "choose"],
+        ["enter/y", "confirm"],
+        ["esc/n", "cancel"],
+      );
     if (this.focus === "select")
       return this.menuLevel === "value"
-        ? ` ${hint("↑↓", "option")}  ${hint("enter", "apply")}  ${hint("←/esc", "back")}`
-        : ` ${hint("↑↓", "option")}  ${hint("→/enter", "open")}  ${hint("←/esc", "back")}`;
+        ? hints(["↑↓", "option"], ["enter", "apply"], ["←/esc", "back"])
+        : hints(["↑↓", "option"], ["→/enter", "open"], ["←/esc", "back"]);
     if (this.focus === "recipe")
-      return ` ${hint("↑↓/pgup/pgdn", "scroll")}  ${hint("↑ at top", "tabs")}  ${hint("←/esc", "tabs")}`;
+      return hints(
+        ["↑↓/pgup/pgdn", "scroll"],
+        ["↑ at top", "tabs"],
+        ["←/esc", "tabs"],
+      );
     if (this.focus === "detail")
-      return ` ${hint("↑↓/pgup/pgdn", "scroll")}  ${hint("←/esc", "back")}`;
+      return hints(["↑↓/pgup/pgdn", "scroll"], ["←/esc", "back"]);
     if (this.focus === "list")
-      return ` ${hint("↑↓/pgup/pgdn", "row")}  ${hint("→/enter", "open")}  ${hint("←", "tabs")}  ${hint("esc", "close")}`;
+      return hints(
+        ["↑↓/pgup/pgdn", "row"],
+        ["→/enter", "open"],
+        ["←", "tabs"],
+        ["esc", "close"],
+      );
     if (this.focus === "runs") {
+      const items: Array<[string, string]> = [
+        ["←→", "run"],
+        ["↓", "tabs"],
+        ["enter", "list"],
+      ];
       const run = this.runs().find((item) => item.run === this.selectedRun);
-      const killHint = this.killRun && run?.status === "running" && run.runInstanceId
-        ? `  ${hint("k", "kill")}`
-        : "";
-      return ` ${hint("←→", "run")}  ${hint("↓", "tabs")}  ${hint("enter", "list")}${killHint}  ${hint("esc", "close")}`;
+      if (this.killRun && run?.status === "running" && run.runInstanceId)
+        items.push(["k", "kill"]);
+      items.push(["esc", "close"]);
+      return hints(...items);
     }
-    return ` ${hint("←→", "navigate")}  ${hint("↑↓", "change row")}  ${hint("enter", "select")}  ${hint("esc", "close")}`;
+    return hints(
+      ["←→", "navigate"],
+      ["↑↓", "change row"],
+      ["enter", "select"],
+      ["esc", "close"],
+    );
   }
 
   private renderRunControl(): string {
@@ -1200,7 +1224,7 @@ export class ActorInspectorOverlay {
     );
     const border = (left: string, right: string, marker = "") =>
       this.theme.fg(
-        "border",
+        "borderAccent",
         `${omitLeftBorder ? "" : left}${marker}${"─".repeat(Math.max(0, contentWidth - visibleWidth(marker)))}${omitRightBorder ? "" : right}`,
       );
     return [
@@ -1215,7 +1239,7 @@ export class ActorInspectorOverlay {
         const styled = focused || index === parentIndex
           ? this.theme.bg("selectedBg", colored)
           : colored;
-        return `${omitLeftBorder ? "" : this.theme.fg("border", "│")}${styled}${omitRightBorder ? "" : this.theme.fg("border", "│")}`;
+        return `${omitLeftBorder ? "" : this.theme.fg("borderAccent", "│")}${styled}${omitRightBorder ? "" : this.theme.fg("borderAccent", "│")}`;
       }),
       border("╰", "╯", hiddenBelow ? "↓" : ""),
     ];
@@ -1285,10 +1309,27 @@ export class ActorInspectorOverlay {
     this.focus = "list";
   }
 
+  private footerBorder(hints: string, width: number): string {
+    const prefix = " ";
+    const suffix = " ─";
+    const content = truncateToWidth(
+      hints,
+      Math.max(0, width - visibleWidth(prefix) - visibleWidth(suffix)),
+      "",
+    );
+    const fill = "─".repeat(
+      Math.max(
+        0,
+        width - visibleWidth(prefix) - visibleWidth(suffix) - visibleWidth(content),
+      ),
+    );
+    return `${this.theme.fg("borderAccent", `╰${prefix}`)}${content}${this.theme.fg("borderAccent", `${suffix}${fill}╯`)}`;
+  }
+
   private border(left: string, title: string, right: string, width: number): string {
     const titleText = truncateToWidth(title, width, "");
     const fill = "─".repeat(Math.max(0, width - visibleWidth(titleText)));
-    return this.theme.fg("border", `${left}${titleText}${fill}${right}`);
+    return this.theme.fg("borderAccent", `${left}${titleText}${fill}${right}`);
   }
 
   private stripeBackground(content: string, index: number): string {
@@ -1311,7 +1352,7 @@ export class ActorInspectorOverlay {
 
   private row(content: string, width: number, fitted = false): string {
     const body = fitted ? content : this.fit(content, width);
-    return `${this.theme.fg("border", "│")}${body}${this.theme.fg("border", "│")}`;
+    return `${this.theme.fg("borderAccent", "│")}${body}${this.theme.fg("borderAccent", "│")}`;
   }
 
   private takeVisiblePrefix(content: string, width: number): string {

package/lib/observability.ts

@@ -21,7 +21,6 @@ import {
   isAbsolute,
   join,
   relative,
-  resolve,
 } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
@@ -1345,97 +1344,40 @@ export function shouldSendRunTransitionFollowUp(
   return shouldNotifyRunTransition(transition);
 }
 
-function getRunArtifacts(transition: RunTransition): string[] {
-  if (!transition.stateDir) return [];
-  return [
-    join(transition.stateDir, "stdout.log"),
-    join(transition.stateDir, "stderr.log"),
-    join(transition.stateDir, "result.json"),
-    join(transition.stateDir, "events.jsonl"),
-    join(transition.stateDir, "outbox.jsonl"),
-  ];
-}
-
-function isUserRecipeFile(file: string | undefined): boolean {
-  if (!file) return false;
-  const recipeRoot = resolve(Paths.getRecipeRoot());
-  const path = resolve(file);
-  const relation = relative(recipeRoot, path);
-  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
-}
-
-export function shouldSuggestRecipePersistence(
-  transition: RunTransition,
-): boolean {
-  if (transition.to !== "done") return false;
-  if (isUserRecipeFile(transition.recipeFile)) return false;
-  return Boolean(transition.recipeFile) || transition.launchSource === "spawn";
-}
+const TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT = 4;
+const TERMINAL_FOLLOW_UP_IDENTIFIER_CHARS = 120;
+const TERMINAL_FOLLOW_UP_PATH_CHARS = 320;
 
-function formatRecipePersistenceSuggestion(transition: RunTransition): string {
-  if (!shouldSuggestRecipePersistence(transition)) return "";
-  if (transition.recipeFile) {
-    return `\nAgent note: this actor completed successfully from recipe ${transition.recipeFile}. If this recipe fits this machine's recurring workflow, ask the operator whether to copy or register it as a durable tool recipe under ~/.pi/agent/recipes. Do not auto-save without confirmation.`;
-  }
-  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 formatTransitionPolicy(transition: RunTransition): string {
-  if (!transition.modelPolicy) return "";
-  const axis = (key: "model" | "thinking", label: string): string | undefined => {
-    const value = transition.modelPolicy?.[key];
-    if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-    const record = value as Record<string, unknown>;
-    const source = typeof record.source === "string" ? record.source : "unused";
-    if (source === "unused") return undefined;
-    const renderedValue =
-      typeof record.value === "string" && record.value.trim()
-        ? ` (${record.value.trim()})`
-        : "";
-    return `${label}: ${source}${renderedValue}`;
-  };
-  const lines = [axis("model", "Model"), axis("thinking", "Thinking")].filter(
-    (line): line is string => Boolean(line),
-  );
-  return lines.length ? `\nPolicy:\n- ${lines.join("\n- ")}` : "";
+function compactTerminalText(value: string, limit: number): string {
+  const compact = value.replaceAll(/\s+/g, " ").trim();
+  return compact.length > limit ? `${compact.slice(0, limit - 1)}…` : compact;
 }
 
-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(" | ")}`;
+function formatTerminalPath(path: string): string {
+  return `\`${compactTerminalText(path, TERMINAL_FOLLOW_UP_PATH_CHARS)}\``;
 }
 
-function formatTransitionSemanticResult(transition: RunTransition): string {
-  const result = transition.semanticResult;
-  if (!result) return "";
-  const correlation = result.correlationId
-    ? `\nCorrelation: ${result.correlationId}` : "";
-  const body = result.body ? `\nResult:\n${result.body}` : "";
-  return `\nSemantic result: ${result.type} — ${result.summary}${correlation}${body}`;
+function formatTerminalResultLocations(transition: RunTransition): string {
+  const artifactPaths = [...new Set(
+    Object.values(transition.artifacts ?? {}).filter(
+      (path): path is string => typeof path === "string" && path.length > 0,
+    ),
+  )];
+  if (artifactPaths.length === 0)
+    return transition.stateDir ? `\nBase: ${formatTerminalPath(transition.stateDir)}` : "";
+  const base = commonDirectory(artifactPaths);
+  const artifactPreview = artifactPaths
+    .slice(0, TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT)
+    .map((path) => formatTerminalPath(base ? relativeName(base, path) : path));
+  const omitted = artifactPaths.length - artifactPreview.length;
+  const artifacts = `${artifactPreview.join(", ")}${omitted > 0 ? ` (+${omitted} more)` : ""}`;
+  return `${base ? `\nBase: ${formatTerminalPath(base)}` : ""}\nArtifacts: ${artifacts}`;
 }
 
 export function formatRunTransitionMessage(transition: RunTransition): string {
-  const artifacts = formatNamedArtifacts(transition.artifacts);
-  const runFiles = formatRunFileList(getRunArtifacts(transition));
-  const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
-  const policy = formatTransitionPolicy(transition);
-  const nextActions = formatTransitionNextActions(transition);
-  const semanticResult = formatTransitionSemanticResult(transition);
-  if (transition.to === "done")
-    return `Run ${transition.run} completed successfully.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
-  if (transition.to === "failed")
-    return `Run ${transition.run} failed.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}`;
-  if (transition.to === "cancelled")
-    return `Run ${transition.run} was cancelled.${policy}${nextActions}`;
-  if (transition.to === "killed")
-    return `Run ${transition.run} was force-killed.${policy}${nextActions}`;
-  if (transition.to === "exited")
-    return `Run ${transition.run} exited before writing a result.${policy}${nextActions}`;
-  return `Run ${transition.run} finished with status ${transition.to}.${policy}${nextActions}`;
+  const run = compactTerminalText(
+    transition.run,
+    TERMINAL_FOLLOW_UP_IDENTIFIER_CHARS,
+  );
+  return `Run: \`${run}\`\nStatus: \`${transition.to}\`${formatTerminalResultLocations(transition)}`;
 }

package/lib/prompts.ts

@@ -29,7 +29,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;

package/package.json

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

package/scripts/async-runner.mjs

@@ -517,6 +517,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       };
       throw error;
     }
+    writeEvidenceManifest("done");
+    progress("done", {
+      completed: 1,
+      failures: result.details.nonCriticalFailures || [],
+    });
     writeJsonAtomic(resultPath, {
       code: result.details.code,
       command: result.details.command,
@@ -525,26 +530,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       truncated: result.details.truncated,
       completedAt: new Date().toISOString(),
     });
-    writeEvidenceManifest("done");
-    progress("done", {
-      completed: 1,
-      failures: result.details.nonCriticalFailures || [],
-    });
     event("run.done", { code: result.details.code });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const details = error && typeof error === "object" ? error.details : undefined;
     appendFileSync(stderrPath, `${message}\n`);
-    writeJsonAtomic(resultPath, {
-      code: typeof details?.code === "number" ? details.code : 1,
-      error: message,
-      killed: Boolean(details?.killed),
-      ...(Array.isArray(details?.branches) ? { branches: details.branches } : {}),
-      ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),
-      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
-      ...(details?.softQuorum ? { soft_quorum: details.softQuorum } : {}),
-      completedAt: new Date().toISOString(),
-    });
     writeEvidenceManifest("failed");
     progress("failed", {
       completed: 0,
@@ -555,6 +545,16 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
           : [{ message }],
       ...(details?.failureReason ? { failureReason: details.failureReason } : {}),
     });
+    writeJsonAtomic(resultPath, {
+      code: typeof details?.code === "number" ? details.code : 1,
+      error: message,
+      killed: Boolean(details?.killed),
+      ...(Array.isArray(details?.branches) ? { branches: details.branches } : {}),
+      ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),
+      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
+      ...(details?.softQuorum ? { soft_quorum: details.softQuorum } : {}),
+      completedAt: new Date().toISOString(),
+    });
     event("run.failed", {
       error: message,
       ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use, including parallel actor launches, subagent fanout, and autonomous coordinator workflows. 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.42.1
+  version: 0.42.2
 ---
 
 # Actors (pi-actors)
@@ -69,7 +69,7 @@ Rules:
 - Command-template strings execute directly without a shell. Operators such as `&&`, `||`, pipes, redirects, and `cd` remain literal argv unless an explicit trusted shell is the executable. Prefer absolute paths or template arrays for sequencing; put non-trivial shell behavior in a reviewed script.
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
-- When a successful actor follow-up suggests persistence, decide whether the pattern deserves durable tool memory; call `register_tool` yourself only when the evidence is strong, and ask before writing the user recipe root.
+- Terminal follow-up context contains only run id, status, one base path, and relative artifact names. Inspect the run for contents; semantic output and correlation remain in non-LLM details and state. Decide whether a successful pattern deserves durable tool memory only after inspection, and ask before writing the user recipe root.
 - Use stable `as` names when you will inspect or message the actor later.
 - Public run state is runtime-owned; do not pass custom `state_dir` paths. This keeps `run:<id>` addressability and retention on one boundary.
 - `async: true` on the recipe is the detached run switch.
@@ -126,7 +126,7 @@ Views:
 - `artifacts`: declared artifact paths/status plus the same bounded owned review-evidence manifest when present.
 - `recipes` target: registry summary for active, shadowed, invalid, disabled, and diagnostic recipe entries.
 
-Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
+Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. Their LLM context content stays limited to run id, status, one base path, and relative artifact names; inspect state for raw output while correlation and semantic details remain outside LLM context. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
 
 ## Runtime Communication Rules
 

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
 metadata:
-  version: 0.42.1
+  version: 0.42.2
 ---
 
 # Swarm