@llblab/pi-kit 0.38.3 → 0.39.0

package/node_modules/@llblab/pi-actors/dist/lib/tools-inspect.js

@@ -15,6 +15,7 @@ import * as RecipesDiscovery from "./recipes-discovery.js";
 import * as RecipesReferences from "./recipes-references.js";
 import * as ReviewDiagnostics from "./review-diagnostics.js";
 import * as RunsControls from "./runs-controls.js";
+import { readRunSessionNavigation } from "./runs-index.js";
 import * as RunControlDelivery from "./runs-control-delivery.js";
 import * as RunsTrace from "./runs-trace.js";
 import * as RuntimeIdentity from "./runtime-identity.js";
@@ -33,24 +34,37 @@ function runtimeStatus() {
         version: RuntimeIdentity.getPackageVersion(),
     };
 }
-function runtimeRuns(ctx, deps, status) {
+function runtimeRuns(ctx, deps, status, includeNavigation = false) {
     const session = ToolsAccess.requireContextSessionId(ctx, "runtime Run inventory");
     const listed = deps.listRuns
         ? deps.listRuns()
         : AsyncRuns.listRuns(undefined, status);
+    const observedFailures = [];
     const runs = listed
         .map((run) => {
         try {
-            return deps.getRunStatus
+            const observed = deps.getRunStatus
                 ? deps.getRunStatus(String(run.state_dir ?? run.run))
                 : AsyncRuns.getRunStatus(String(run.state_dir ?? run.run));
+            if (includeNavigation && observed.status === "failed" && typeof observed.run === "string" && typeof observed.run_instance_id === "string" &&
+                typeof observed.state_dir === "string" && observed.ownerId === session) {
+                observedFailures.push({ run: observed.run, run_instance_id: observed.run_instance_id, state_dir: observed.state_dir, ownerId: session });
+            }
+            return observed;
         }
         catch {
             return run;
         }
     })
         .filter((run) => run.ownerId === session);
-    return { owner_session: session, runs };
+    const navigation = includeNavigation ? readRunSessionNavigation(deps.runStateRoot ?? Paths.getRunStateRoot(), session, {
+        root_order: status === "failed" ? "failed_subtrees_first" : "latest_registration",
+        failed: observedFailures,
+    }) : undefined;
+    const current = ToolsAccess.requireContextSessionId(ctx, "runtime Run inventory");
+    if (current !== session)
+        throw ToolsAccess.sessionMismatchError({ currentSession: current, expectedSession: session, target: "runtime" });
+    return { owner_session: session, runs, ...(navigation ? { navigation } : {}) };
 }
 function runtimeTriage(ctx, deps) {
     const inventory = runtimeRuns(ctx, deps, undefined);
@@ -141,23 +155,55 @@ function runtimeTriage(ctx, deps) {
     };
 }
 function compactRuntime(view, details) {
-    if (view === "runs") {
-        return `\nruntime runs=${details.runs?.length ?? 0}`;
-    }
-    if (view === "triage") {
-        return `\nruntime failed=${details.failed_runs?.length ?? 0} pending_controls=${Number(details.pending_control_count ?? 0)} stale_controls=${Number(details.stale_control_count ?? 0)} backpressured=${Number(details.backpressured_run_count ?? 0)} incomplete_trace=${Number(details.trace_diagnostic_count ?? 0)} attention=${details.attention_events?.length ?? 0}`;
-    }
-    return `\nruntime version=${String(details.version)} state_schema=${String(details.state_schema)} automatic_review=${String(details.automatic_review)}`;
+    const fields = view === "runs" ? { runs: details.runs?.length ?? 0 }
+        : view === "triage" ? {
+            failed: details.failed_runs?.length ?? 0,
+            pending_controls: Number(details.pending_control_count ?? 0), stale_controls: Number(details.stale_control_count ?? 0),
+            backpressured: Number(details.backpressured_run_count ?? 0), incomplete_trace: Number(details.trace_diagnostic_count ?? 0),
+            attention: details.attention_events?.length ?? 0,
+        } : { version: String(details.version), state_schema: String(details.state_schema), automatic_review: String(details.automatic_review) };
+    return "\n" + [ToolsResponse.formatMarkdownField("runtime", view),
+        ...Object.entries(fields).map(([key, value]) => ToolsResponse.formatMarkdownField(key, String(value)))].join("\n");
+}
+// Projects local refusals only; does not intercept other throws or change existing catches.
+function formatInspectFailure(fields, next) {
+    // The unchanged public adapter adds exactly one leading LF to these Error messages.
+    const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+    const omitted = (key) => `- ${key}:\n  - state: omitted\n  - reason: response_too_large\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
+    const field = ([key, value]) => typeof value === "string"
+        ? ToolsResponse.formatMarkdownField(key, value)
+        : `- ${key}:\n${value.map(item => `  - ${item}`).join("\n")}`;
+    // Unmarked fields are bounded compiler literals/lists. Short values seed full so admission only grows.
+    const formatted = fields.map(field);
+    const projected = fields.map((item, index) => {
+        const full = formatted[index], fallback = omitted(item[0]);
+        return item[2] && Buffer.byteLength(full, "utf8") > Buffer.byteLength(fallback, "utf8") ? fallback : full;
+    });
+    let action = next ? ToolsResponse.formatInspectNextAction(next[0], next[1]) : "";
+    const text = () => [...projected, ...(action ? [action] : [])].join("\n");
+    if (next && Buffer.byteLength(text(), "utf8") > budget)
+        action = omitted("next_action");
+    fields.forEach((item, index) => {
+        if (!item[2])
+            return;
+        const fallback = projected[index];
+        projected[index] = formatted[index];
+        if (Buffer.byteLength(text(), "utf8") > budget)
+            projected[index] = fallback;
+    });
+    return text();
 }
 function inspectRuntime(view, input, ctx, deps) {
     if (view === "status")
         return runtimeStatus();
     if (view === "runs") {
-        return runtimeRuns(ctx, deps, typeof input.status === "string" ? input.status : undefined);
+        return runtimeRuns(ctx, deps, typeof input.status === "string" ? input.status : undefined, input.verbose === true);
     }
     if (view === "triage")
         return runtimeTriage(ctx, deps);
-    throw new Error("inspect runtime supports view=status, view=runs, or view=triage.");
+    throw new Error(formatInspectFailure([
+        ["target_kind", "runtime"], ["result", "unsupported view"], ["supported_views", ["status", "runs", "triage"]],
+    ]));
 }
 function portableSkillRecipePath(file, skill, namespaces) {
     const root = namespaces[skill]?.[0];
@@ -272,7 +318,10 @@ function inspectRecipes(view, input, deps, context) {
         view !== "doctor" &&
         view !== "imports" &&
         view !== "reviews") {
-        throw new Error("inspect recipes supports view=status, view=summary, view=doctor, view=imports, or view=reviews.");
+        throw new Error(formatInspectFailure([
+            ["target_kind", "recipes"], ["result", "unsupported view"],
+            ["supported_views", ["status", "summary", "doctor", "imports", "reviews"]],
+        ]));
     }
     const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
     if (view === "reviews") {
@@ -291,7 +340,7 @@ function inspectRecipes(view, input, deps, context) {
     const registryStatus = deps.registryStatus?.();
     const identity = typeof input.identity === "string" ? input.identity.trim() : "";
     if (identity && view !== "doctor") {
-        throw new Error("inspect recipes identity is supported only with view=doctor.");
+        throw new Error(formatInspectFailure([["target_kind", "recipes"], ["result", "identity requires view=doctor"]]));
     }
     if (view === "doctor" && identity) {
         return inspectRecipeIdentity(identity, resolutionContext, skillRecipeNamespaces, skillInventory, registryStatus);
@@ -353,7 +402,9 @@ function parseRunTarget(target) {
 }
 function inspectRun(run, view, input, ctx, deps) {
     if (view !== "recipe" && view !== "trace" && view !== "control") {
-        throw new Error("inspect run:<id> supports view=recipe, view=trace, or view=control.");
+        throw new Error(formatInspectFailure([
+            ["target_kind", "run"], ["result", "unsupported view"], ["supported_views", ["recipe", "trace", "control"]],
+        ]));
     }
     const status = deps.getRunStatus
         ? ToolsAccess.assertRunStatusAccessibleToContext(run, deps.getRunStatus(run), ctx)
@@ -371,7 +422,10 @@ function inspectRun(run, view, input, ctx, deps) {
             source !== "agent" &&
             source !== "artifact" &&
             source !== "runtime") {
-            throw new Error(`unsupported Trace source: ${source}`);
+            throw new Error(formatInspectFailure([
+                ["target_kind", "run"], ["source", source, true], ["result", "unsupported Trace source"],
+                ["supported_sources", ["all", "lifecycle", "control", "process", "agent", "artifact", "runtime"]],
+            ]));
         }
         return {
             run, source,
@@ -424,18 +478,26 @@ function inspectRun(run, view, input, ctx, deps) {
 }
 function inspectTool(name, view, deps) {
     if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
-        throw new Error(`invalid tool target: tool:${name}`);
+        throw new Error(formatInspectFailure([["target", `tool:${name}`, true], ["result", "invalid tool target"]]));
     }
     if (view !== "status" && view !== "schema") {
-        throw new Error("inspect tool:<name> supports view=status or view=schema.");
+        throw new Error(formatInspectFailure([
+            ["target_kind", "tool"], ["result", "unsupported view"], ["supported_views", ["status", "schema"]],
+        ]));
     }
     const tool = deps.getTool?.(name);
     const status = deps.getToolStatus?.(name);
     if (!tool && !status) {
-        throw new Error(`Registered tool not found: ${name}. Next: inspect target=recipes view=doctor; do not substitute spawn for tool invocation.`);
+        throw new Error(formatInspectFailure([
+            ["tool", name, true], ["result", "registered tool not found"], ["safety", "Do not substitute spawn for tool invocation."],
+        ], ["recipes", "doctor"]));
     }
     if (view === "schema" && !tool) {
-        throw new Error(`Tool "${name}" is registered but its callable schema is unavailable; callable_now=${String(status?.callable_now ?? false)}, activation_boundary=${String(status?.activation_boundary ?? "host_registration")}. Next: inspect target=tool:${name} view=status.`);
+        throw new Error(formatInspectFailure([
+            ["tool", name, true], ["result", "registered; callable schema unavailable"],
+            ["callable_now", String(status?.callable_now ?? false), true],
+            ["activation_boundary", String(status?.activation_boundary ?? "host_registration"), true],
+        ], [`tool:${name}`, "status"]));
     }
     return {
         name,
@@ -453,38 +515,40 @@ function compactResult(target, view, details) {
     if (target === "runtime")
         return compactRuntime(view, details);
     if (target === "recipes" && typeof details.identity === "string") {
-        const lines = [
-            `recipes doctor identity=${details.identity} skill_active=${String(details.skill_active)} resolvable=${String(details.resolvable)} catalog_partial=${String(details.catalog_partial)} component_status=${String(details.component_status)}`,
-            ...(details.source_location
-                ? [`source=${String(details.source_location)}`]
-                : []),
-            `resolution_generation=${String(details.resolution_generation)}`,
-            ...(details.rejected_reason
-                ? [`rejected_reason=${String(details.rejected_reason)}`]
-                : []),
-            ...(details.next_actions ?? []).map((action) => `next=${String(action)}`),
-        ];
-        return `\n${lines.join("\n")}`;
+        const fields = [ToolsResponse.formatMarkdownField("recipes", "doctor"),
+            ...["identity", "skill_active", "resolvable", "catalog_partial", "component_status"]
+                .map(key => ToolsResponse.formatMarkdownField(key, String(details[key]))),
+            ...(details.source_location ? [ToolsResponse.formatMarkdownField("source_location", ToolsResponse.formatLiteralBlock(String(details.source_location)))] : []),
+            ToolsResponse.formatMarkdownField("resolution_generation", String(details.resolution_generation)),
+            ...(details.rejected_reason ? [ToolsResponse.formatMarkdownField("rejected_reason", String(details.rejected_reason))] : [])];
+        const actions = details.next_actions;
+        if (actions?.length)
+            fields.push(ToolsResponse.formatInspectionHint(String(actions[0])));
+        return "\n" + fields.join("\n");
     }
     if (target === "recipes")
         return ToolsResponse.compactRecipeRegistry(details);
     if (target.startsWith("tool:") && view === "status") {
-        const required = Array.isArray(details.required_args)
-            ? details.required_args.map(String).join(",") || "none"
-            : "unknown";
-        const optional = Array.isArray(details.optional_args)
-            ? details.optional_args.map(String).join(",") || "none"
-            : "unknown";
+        const argumentsField = (key, value) => Array.isArray(value) && value.length
+            ? "- " + key + ":\n" + value.map(item => "  - " + String(item).replace(/\r\n|\r|\n/gu, match => match + "    ")).join("\n")
+            : ToolsResponse.formatMarkdownField(key, Array.isArray(value) ? "none" : "unknown");
         const next = Array.isArray(details.next_actions) && details.next_actions.length > 0
             ? String(details.next_actions[0])
             : details.callable_now === true
                 ? `call tool ${target.slice(5)}`
                 : `register_tool name=${target.slice(5)} update=true`;
-        return `\ntool=${target.slice(5)} source=${String(details.source ?? "unknown")} callable_now=${String(details.callable_now ?? false)} activation_boundary=${String(details.activation_boundary ?? "unknown")} required=${required} optional=${optional} launch_kind=${String(details.launch_kind ?? "none")} spawn_calls=${Number(details.spawn_calls ?? 0)} tool_calls=${Number(details.tool_calls ?? 0)} next=${next}`;
+        return "\n" + [ToolsResponse.formatMarkdownField("tool", target.slice(5)),
+            ToolsResponse.formatMarkdownField("source", String(details.source ?? "unknown")),
+            ToolsResponse.formatMarkdownField("callable_now", String(details.callable_now ?? false)),
+            ToolsResponse.formatMarkdownField("activation_boundary", String(details.activation_boundary ?? "unknown")),
+            argumentsField("required_args", details.required_args), argumentsField("optional_args", details.optional_args),
+            ToolsResponse.formatMarkdownField("launch_kind", String(details.launch_kind ?? "none")),
+            ToolsResponse.formatMarkdownField("spawn_calls", String(Number(details.spawn_calls ?? 0))),
+            ToolsResponse.formatMarkdownField("tool_calls", String(Number(details.tool_calls ?? 0))), ToolsResponse.formatInspectionHint(next)].join("\n");
     }
     if (target.startsWith("tool:"))
-        return `\ntool=${target.slice(5)} view=${view}`;
-    return `\nrun=${target.slice(4)} view=${view}`;
+        return "\n" + ToolsResponse.formatMarkdownField("tool", target.slice(5)) + "\n" + ToolsResponse.formatMarkdownField("view", view);
+    return "\n" + ToolsResponse.formatMarkdownField("run", target.slice(4)) + "\n" + ToolsResponse.formatMarkdownField("view", view);
 }
 export function createInspectToolDefinition(deps = {}) {
     return {
@@ -495,7 +559,7 @@ export function createInspectToolDefinition(deps = {}) {
             identity: Schema.stringSchema("Optional canonical <skill>/<recipe> identity for focused Recipe doctor diagnosis."),
             lines: Schema.stringSchema("Bounded item count for Trace or recent Controls."),
             source: Schema.stringSchema("Optional Trace source: all, lifecycle, control, process, agent, artifact, or runtime."),
-            status: Schema.stringSchema("Optional runtime Run status filter."),
+            status: Schema.stringSchema("Optional runtime Run status filter. With verbose runs, failed prioritizes observed failed subtrees without filtering the navigation map."),
             target: Schema.stringSchema("Target: run:<id>, runtime, recipes, or tool:<name>."),
             verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
             view: Schema.stringSchema("Run view recipe|trace|control, or target-specific management view."),
@@ -519,7 +583,10 @@ export function createInspectToolDefinition(deps = {}) {
                     details = inspectTool(target.slice(5), view, deps);
                 }
                 else {
-                    throw new Error(`unsupported inspect target: ${target}; use run:<id>, runtime, recipes, or tool:<name>`);
+                    throw new Error(formatInspectFailure([
+                        ["target", target, true], ["result", "unsupported inspect target"],
+                        ["supported_targets", ["run:<id>", "runtime", "recipes", "tool:<name>"]],
+                    ]));
                 }
             }
             return {

package/node_modules/@llblab/pi-actors/dist/lib/tools-local.d.ts

@@ -3,6 +3,7 @@
  * Zones: user recipe tools, generated schemas, async recipe launch
  * Owns wrapping saved local capabilities as executable pi tools
  */
+import * as AsyncRuns from "./async-runs.ts";
 import * as ModelContext from "./model-context.ts";
 import type { RegisteredTool } from "./config.ts";
 import * as Execution from "./execution.ts";
@@ -10,6 +11,8 @@ import type * as RecipeResolution from "./recipes-context.ts";
 export interface RuntimeToolContext extends ModelContext.CurrentModelContext {
     recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
     cwd: string;
+    /** Kernel-injected only; never sourced from tool input/actor values. */
+    onSupervisionClockCaptured?: AsyncRuns.AsyncRunStartOptions["onSupervisionClockCaptured"];
     sessionManager?: {
         getSessionId?: () => string;
     };

package/node_modules/@llblab/pi-actors/dist/lib/tools-local.js

@@ -11,6 +11,7 @@ import * as RecipesReferences from "./recipes-references.js";
 import * as RecipesUsage from "./recipes-usage.js";
 import * as Schema from "./schema.js";
 import * as ToolsResponse from "./tools-response.js";
+import { readRunFileNavigationForContext } from "./tools-access.js";
 function getRunOwnerId(ctx) {
     return ctx.sessionManager?.getSessionId?.();
 }
@@ -138,6 +139,11 @@ export function createRuntimeToolDefinition(cfg, exec) {
             ? Prompts.formatRecipeToolPromptSnippet(cfg.recipe?.name ?? String(cfg.template), isAsyncRecipe)
             : Prompts.formatRegisteredToolPromptSnippet(cfg.template),
         async execute(toolCallId, params, signal, _onUpdate, ctx) {
+            let dispatchEntered = false;
+            const execute = (...args) => {
+                dispatchEntered = true;
+                return exec(...args);
+            };
             try {
                 if (cfg.sourcePath &&
                     !RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool")) {
@@ -152,7 +158,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
                         : typeof run_id === "string" && run_id.trim()
                             ? run_id.trim()
                             : `${cfg.name}-${Date.now()}`;
-                    const meta = AsyncRuns.startRun({
+                    const startParams = {
                         ...base,
                         launch_source: "tool",
                         launch_correlation: { tool_call_id: toolCallId },
@@ -167,23 +173,29 @@ export function createRuntimeToolDefinition(cfg, exec) {
                         tool: cfg.name,
                         policy_values: ModelContext.withCurrentModelValues({ ...(cfg.recipe?.values ?? {}), ...values }, ctx),
                         values: resolveRecipeToolValues(cfg, values, ctx),
-                    }, ctx.cwd, { skillContext: ctx.recipeResolutionContext?.activeSkills });
+                    };
+                    dispatchEntered = true;
+                    const meta = AsyncRuns.startRun(startParams, ctx.cwd, { skillContext: ctx.recipeResolutionContext?.activeSkills, onSupervisionClockCaptured: ctx.onSupervisionClockCaptured });
+                    const details = { ...meta, file_navigation: readRunFileNavigationForContext(meta, ctx) };
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: ToolsResponse.compactAsyncRunStatus(meta),
+                                text: ToolsResponse.compactAsyncRunStatus(details),
                             },
                         ],
-                        details: meta,
+                        details,
                     };
                 }
                 if (isRecipe && recipeTemplate) {
-                    return await Execution.executeRegisteredTool({ ...cfg, template: recipeTemplate }, resolveRecipeToolValues(cfg, params, ctx), exec, ctx.cwd, signal);
+                    return await Execution.executeRegisteredTool({ ...cfg, template: recipeTemplate }, resolveRecipeToolValues(cfg, params, ctx), execute, ctx.cwd, signal);
                 }
-                return await Execution.executeRegisteredTool(cfg, Schema.normalizeRuntimeValues(ModelContext.withCurrentModelValues(params, ctx), cfg.argTypes), exec, ctx.cwd, signal);
+                return await Execution.executeRegisteredTool(cfg, Schema.normalizeRuntimeValues(ModelContext.withCurrentModelValues(params, ctx), cfg.argTypes), execute, ctx.cwd, signal);
             }
             catch (error) {
+                // Dispatch entry is not effect/closure proof; matching error text cannot justify argument repair or retry.
+                if (dispatchEntered)
+                    throw error;
                 throw formatRuntimeToolArgumentError(cfg, error, required, isAsyncRecipe && !isSingletonRecipe);
             }
         },

package/node_modules/@llblab/pi-actors/dist/lib/tools-message.d.ts

@@ -1,8 +1,11 @@
 /**
  * Public Control facade under the stable `message` tool name.
- * Zones: Control request validation, Run/runtime dispatch, compact receipts
+ * Zones: Control request validation, Run/runtime dispatch, recipient-scoped receipts
  * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */
+import * as Control from "./control.ts";
+/** Pure first-layer copy; legacy stopped/killed flags are not scope-closure proof. */
+export declare function compactControlResult(request: Control.ControlRequest, result: Record<string, unknown>): string;
 export interface ControlToolDeps {
     getRunStatus?: (run: string) => Record<string, unknown>;
     handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;

package/node_modules/@llblab/pi-actors/dist/lib/tools-message.js

@@ -1,41 +1,109 @@
 /**
  * Public Control facade under the stable `message` tool name.
- * Zones: Control request validation, Run/runtime dispatch, compact receipts
+ * Zones: Control request validation, Run/runtime dispatch, recipient-scoped receipts
  * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */
 import * as AsyncRuns from "./async-runs.js";
 import * as Control from "./control.js";
 import * as Schema from "./schema.js";
 import * as ToolsAccess from "./tools-access.js";
+import * as Limits from "./limits.js";
 import * as ToolsResponse from "./tools-response.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
         : {};
 }
-function compactControlResult(request, result) {
-    const tokens = [
-        `target=${request.target}`,
-        `action=${request.action}`,
-        `status=${String(result.delivery ?? result.status ?? (result.stopped === true ? "handled" : "accepted"))}`,
-    ];
-    if (result.control_id)
-        tokens.push(`control=${String(result.control_id)}`);
-    if (result.reason)
-        tokens.push(`reason=${String(result.reason).replaceAll(/\s+/g, "_")}`);
-    if (Array.isArray(result.next_actions) && result.next_actions.length > 0) {
-        tokens.push(`next=${result.next_actions
-            .map((action) => action.replaceAll(/\s+/g, "_"))
-            .join("|")}`);
+const controlField = ToolsResponse.formatMarkdownField;
+/** Only the four compiler-owned guard sites below; never wraps dispatch/dependency errors. */
+function controlGuardText(request, result, options) {
+    const key = request.target === "runtime" ? "target" : "run";
+    const identity = controlField(key, request.target === "runtime" ? request.target : request.target.slice(4));
+    const omittedIdentity = `- ${key}: [omitted]\n- ${key}_omission:\n  - reason: response_too_large\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
+    const fixed = [controlField("action", request.action), controlField("result", result)];
+    let fullOptions = "", omittedOptions = "";
+    if (options) {
+        const rows = [];
+        let malformed = false;
+        // Values were selected by the original string filter, not by a new action grammar.
+        for (let index = 0; index < options.values.length; index++) {
+            const value = options.values[index];
+            if (!value.isWellFormed()) {
+                malformed = true;
+                break;
+            }
+            rows.push("  - " + value.replaceAll(/\r\n|\r|\n/gu, newline => newline + "    "));
+        }
+        omittedOptions = `- ${options.key}: [${malformed ? "unavailable" : "omitted"}]\n- ${options.key}_omission:\n  - reason: ${malformed ? "malformed_selected_text" : "response_too_large"}\n  - shown: 0\n  - omitted: ${options.values.length}\n  - total: ${options.values.length}`;
+        fullOptions = malformed ? omittedOptions : rows.length ? `- ${options.key}:\n${rows.join("\n")}` : controlField(options.key, "none");
     }
-    return `\n${tokens.join(" ")}`;
+    // Start with the shorter complete-or-omitted rendering: adding an omission scaffold must
+    // never manufacture overflow when the complete small field would fit. Then grow only.
+    let selectedIdentity = Buffer.byteLength(identity) <= Buffer.byteLength(omittedIdentity) ? identity : omittedIdentity;
+    let selectedOptions = Buffer.byteLength(fullOptions) <= Buffer.byteLength(omittedOptions) ? fullOptions : omittedOptions;
+    const render = (target, choices) => ToolsResponse.withLeadingLineBreak([target, ...fixed, ...(options ? [choices] : [])].join("\n"));
+    if (Buffer.byteLength(render(identity, selectedOptions)) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES)
+        selectedIdentity = identity;
+    if (options && Buffer.byteLength(render(selectedIdentity, fullOptions)) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES)
+        selectedOptions = fullOptions;
+    return render(selectedIdentity, selectedOptions);
+}
+function controlNext(action) {
+    const inspect = /^inspect target=([^\s]+) view=([^\s]+)$/u.exec(action);
+    return inspect ? ToolsResponse.formatInspectNextAction(inspect[1], inspect[2])
+        : "- next:\n" + controlField("instruction", action, 1);
+}
+/** Pure first-layer copy; legacy stopped/killed flags are not scope-closure proof. */
+export function compactControlResult(request, result) {
+    const fields = [request.target.startsWith("run:") ? controlField("run", request.target.slice(4)) : controlField("target", request.target),
+        controlField("action", request.action)];
+    if (result.stopped === false || result.archived === false || result.pruned === false) {
+        fields.push(controlField("result", "not applied"));
+        if (typeof result.reason === "string")
+            fields.push(controlField("reason", result.reason));
+        const observed = asRecord(result.status);
+        if (result.reason === "not running" && typeof observed.status === "string")
+            fields.push(controlField("state", observed.status));
+    }
+    else if (request.action === "kill" && result.stopped === true) {
+        fields.push(controlField("result", "kill attempted"), controlField("termination", "unconfirmed"));
+    }
+    else if (result.archived === true) {
+        fields.push(controlField("result", "archived"));
+    }
+    else if (result.pruned === true) {
+        fields.push(controlField("result", "pruned"));
+    }
+    else if (result.delivery === "queued" || result.delivery === "delivered") {
+        fields.push(controlField("delivery", result.delivery), controlField("handling", "unconfirmed"));
+    }
+    else {
+        fields.push(controlField(typeof result.delivery === "string" ? "delivery" : "result", typeof result.delivery === "string" ? result.delivery : typeof result.status === "string" ? result.status : "accepted"));
+        if (typeof result.reason === "string")
+            fields.push(controlField("reason", result.reason));
+    }
+    if (typeof result.control_id === "string")
+        fields.push(controlField("control_id", result.control_id));
+    const actions = Array.isArray(result.next_actions) ? result.next_actions
+        : request.target.startsWith("run:") ? runNextActions(request.target.slice(4), result) : [];
+    const next = actions.find((action) => typeof action === "string" && action.length > 0);
+    if (next)
+        fields.push(controlNext(next));
+    return ToolsResponse.withLeadingLineBreak(fields.join("\n"));
 }
 function runNextActions(run, result) {
+    if (result.stopped === true)
+        return [`inspect target=run:${run} view=trace`];
+    if (result.stopped === false || result.archived === false || result.pruned === false) {
+        if (result.reason === "ownership changed" || result.reason === "run generation changed") {
+            return ["inspect target=runtime view=runs"];
+        }
+        if (result.stopped === false && result.reason !== "not running")
+            return [`inspect target=run:${run} view=trace`];
+    }
     if (result.delivery === "queued" || result.delivery === "delivered") {
         return [`inspect target=run:${run} view=control`];
     }
-    if (result.stopped === true)
-        return [`inspect target=run:${run} view=control`];
     return [];
 }
 export function createControlToolDefinition(deps = {}) {
@@ -58,10 +126,12 @@ export function createControlToolDefinition(deps = {}) {
             let result;
             if (request.target === "runtime") {
                 if (request.action !== "review.retry" && request.action !== "review.reset") {
-                    throw new Error(`unsupported runtime Control action: ${request.action}; use review.retry or review.reset`);
+                    throw new Error(controlGuardText(request, "unsupported runtime Control action", {
+                        key: "supported_actions", values: ["review.retry", "review.reset"],
+                    }));
                 }
                 if (!deps.handleRuntimeControl) {
-                    throw new Error("runtime Control is unavailable");
+                    throw new Error(controlGuardText(request, "runtime Control is unavailable"));
                 }
                 result = deps.handleRuntimeControl(request.action, request.input);
             }
@@ -74,7 +144,7 @@ export function createControlToolDefinition(deps = {}) {
                     ? status.run_instance_id
                     : undefined;
                 if (!runInstanceId)
-                    throw new Error(`Run generation unavailable: ${run}`);
+                    throw new Error(controlGuardText(request, "Run generation unavailable"));
                 if (request.action === "kill") {
                     result = AsyncRuns.killRun(run, {
                         ...(typeof status.ownerId === "string"
@@ -108,17 +178,42 @@ export function createControlToolDefinition(deps = {}) {
                         ? status.control.filter((action) => typeof action === "string")
                         : [];
                     if (!declared.includes(request.action)) {
-                        throw new Error(`undeclared Run Control action: ${request.action}; available=${declared.join(",") || "none"}`);
+                        // The old join/template evaluation may itself throw or have observable hooks.
+                        // Preserve it before the new presentation; it is not an action-list parser.
+                        void `${declared.join(",") || "none"}`;
+                        throw new Error(controlGuardText(request, "undeclared Run Control action", {
+                            key: "available_actions", values: declared,
+                        }));
                     }
-                    result = await AsyncRuns.sendRunControl(run, {
-                        action: request.action,
-                        ...(request.input !== undefined ? { input: request.input } : {}),
-                        run_instance_id: runInstanceId,
-                    }, {
-                        ...(typeof status.ownerId === "string"
-                            ? { ownerId: status.ownerId }
-                            : {}),
-                    });
+                    try {
+                        result = await AsyncRuns.sendRunControl(run, {
+                            action: request.action,
+                            ...(request.input !== undefined ? { input: request.input } : {}),
+                            run_instance_id: runInstanceId,
+                        }, {
+                            ...(typeof status.ownerId === "string"
+                                ? { ownerId: status.ownerId }
+                                : {}),
+                        });
+                    }
+                    catch (cause) {
+                        // Admission-era correlation is not current reply-scope proof after an awaited dispatch.
+                        const summary = [controlField("action", request.action), controlField("result", "request failed"),
+                            controlField("delivery", "unconfirmed"), controlField("handling", "unconfirmed"),
+                            controlField("warning", "Effects may already exist.\nDo not repeat automatically."),
+                            controlNext("inspect target=runtime view=runs")].join("\n");
+                        // Reserve both line breaks; display one whole caller-owned id or explicit whole-id omission.
+                        const identity = controlField("run", run);
+                        const target = Buffer.byteLength(identity) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - Buffer.byteLength(summary) - 2
+                            ? identity
+                            : "- run: [omitted]\n- run_omission:\n  - reason: response_too_large\n  - shown: 0\n  - omitted: 1\n  - total: 1";
+                        throw new Error(ToolsResponse.withLeadingLineBreak(target + "\n" + summary), { cause });
+                    }
+                }
+                // A refused identity change must not publish the replacement's status, even in verbose/details.
+                if (result.reason === "ownership changed" || result.reason === "run generation changed") {
+                    result = { ...result };
+                    delete result.status;
                 }
                 const nextActions = runNextActions(run, result);
                 if (nextActions.length > 0)

package/node_modules/@llblab/pi-actors/dist/lib/tools-response.d.ts

@@ -1,8 +1,30 @@
 /**
- * Public tool response formatting
- * Zones: compact text summaries, verbose JSON switching, next-action rendering
- * Owns model-facing response helpers shared by public tool execution paths
+ * Shared response formatting.
+ * Zones: compact text summaries, snapshot/literal rendering, JSON switching, next-action rendering.
+ * Owns model-facing formatting shared by tool and coordinator delivery paths.
+ * Excludes: evidence reads/admission, source visibility, clock measurement and lifecycle/delivery authority.
  */
+export type YamlMetadataRendering = {
+    readonly state: "available";
+    readonly text: string;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "budget_invalid" | "metadata_invalid" | "metadata_too_large";
+};
+/** Pure selected-metadata formatting, not admission or authority. */
+export declare function renderYamlMetadata(value: unknown, byteBudget: number): YamlMetadataRendering;
+export declare function formatMarkdownField(key: string, value: string, depth?: number): string;
+export declare function formatInspectNextAction(target: string, view: string, verbose?: boolean): string;
+export declare function formatLiteralBlock(value: string): string;
+export type RunSnapshotRendering = {
+    readonly state: "available";
+    readonly text: string;
+} | {
+    readonly state: "unavailable";
+    readonly reason: "snapshot_invalid" | "snapshot_too_large" | "format_invalid" | "render_too_large";
+};
+/** Pure formatting of already-admitted snapshots. DTO/schema validity is NOT source, timing, visibility or lifecycle authority. */
+export declare function renderRunSnapshot(value: unknown, format?: "text" | "json"): Readonly<RunSnapshotRendering>;
 export declare function withLeadingLineBreak(text: string): string;
 export declare function spaceToolResult<T>(result: T): T;
 export declare function spaceToolError(error: unknown): unknown;
@@ -10,11 +32,17 @@ export declare function asRecord(value: unknown): Record<string, unknown>;
 export declare function jsonText(value: unknown): string;
 export declare function compactPreview(value: unknown, maxLength?: number): string | undefined;
 export declare function compactNextActions(actions: string[]): string;
+/** Frozen older completion-format text: new launch layout must not change this shared packet helper. */
+export declare function formatRunFileNavigationHandoff(): string;
 export declare function runNextActions(run: unknown): string[];
 export declare function compactAsyncRunStatus(value: unknown): string;
 export declare function maybeJsonText(value: unknown, verbose: boolean | undefined, compact: string): string;
+/** Full spawn metadata retains legacy JSON selection; projection is not launch or source authority. */
+export declare function spawnMetadataText(value: unknown, verbose: boolean | undefined, compact: string): string;
 export declare function compactRecipeImports(summary: Record<string, unknown>): string;
 export declare function compactRecipeDoctor(summary: Record<string, unknown>): string;
 export declare function recipeRegistryNextActions(summary: Record<string, unknown>, view: string): string[];
+/** Only these existing read-only inspection hints become action nodes; other advice stays content. */
+export declare function formatInspectionHint(action: string): string;
 export declare function compactRecipeRegistry(summary: Record<string, unknown>): string;
 export declare const DEFAULT_INSPECT_LINES = 40;