@llblab/pi-actors 0.56.1 → 0.57.0

package/lib/registry.ts

@@ -172,6 +172,26 @@ function registrationNextActions(
   ];
 }
 
+const REGISTRY_METADATA_BUDGET = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+
+type RegistryMetadata = Record<string, unknown>;
+
+/** Bare block-YAML registry document; builders own whole-value/omission policy and the byte budget. */
+function registryMetadataText(value: RegistryMetadata): string {
+  return (ToolsResponse.renderYamlMetadata(value, REGISTRY_METADATA_BUDGET) as
+    Extract<ToolsResponse.YamlMetadataRendering, { state: "available" }>).text;
+}
+
+/** One opaque selected scalar as a whole value or an explicit whole-field omission, never a clip. */
+function registrySelected(key: string, value: string): ToolsResponse.YamlPart {
+  return ToolsResponse.selectYamlField(key, value, REGISTRY_METADATA_BUDGET);
+}
+
+/** Grow whole selected fields in priority order while the complete document still fits. */
+function growRegistryDocument(render: () => RegistryMetadata, order: readonly ToolsResponse.YamlPart[]): string {
+  return ToolsResponse.growYamlDocument(render, order, REGISTRY_METADATA_BUDGET);
+}
+
 /** Read-time text only: callers supply the original post-activation selections, not live ports. */
 function registrationReceiptText(data: {
   tool: string; result: "registered" | "updated" | "persisted"; source: string; callable: boolean;
@@ -235,74 +255,35 @@ function registryNoticeText(kind: "activated" | "promoted" | "deleted", name: st
 }
 
 function registrationTransactionFailureText(stage: string, generation: string, summary: string, error: string): string {
-  const field = ToolsResponse.formatMarkdownField;
-  const part = (key: string, value: string) => {
-    const wellFormed = value.isWellFormed();
-    const omitted = `- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
-    const full = wellFormed ? field(key, value) : omitted;
-    return { full, selected: Buffer.byteLength(full) <= Buffer.byteLength(omitted) ? full : omitted };
-  };
-  const selectedGeneration = part("resolution_generation", generation);
-  const selectedSummary = part("active_skills_summary", summary);
-  const selectedError = part("error", error);
-  const render = () => [field("result", "Tool registration transaction failed."), field("stage", stage),
-    selectedGeneration.selected, selectedSummary.selected, selectedError.selected].join("\n");
+  const selectedGeneration = registrySelected("resolution_generation", generation);
+  const selectedSummary = registrySelected("active_skills_summary", summary);
+  const selectedError = registrySelected("error", error);
+  const render = (): RegistryMetadata => ({ result: "Tool registration transaction failed.", stage,
+    ...selectedGeneration.selected, ...selectedSummary.selected, ...selectedError.selected });
   // Keep a fitting surfaced error before large optional resolution metadata.
-  for (const current of [selectedError, selectedGeneration, selectedSummary]) {
-    if (current.selected === current.full) continue;
-    const previous = current.selected;
-    current.selected = current.full;
-    if (Buffer.byteLength(render()) > Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) current.selected = previous;
-  }
-  return render();
+  return growRegistryDocument(render, [selectedError, selectedGeneration, selectedSummary]);
 }
 
 function candidateAdmissionFailureText(data: { kind: "source"; source: string; diagnostics: string; summary: string; instruction: string } | { kind: "recipe"; diagnostics: string }): string {
-  const field = ToolsResponse.formatMarkdownField;
-  const part = (key: string, value: string, literal = false) => {
-    const wellFormed = value.isWellFormed();
-    const omitted = `- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
-    const full = wellFormed ? field(key, literal ? ToolsResponse.formatLiteralBlock(value) : value) : omitted;
-    return { full, selected: Buffer.byteLength(full) <= Buffer.byteLength(omitted) ? full : omitted };
-  };
-  const diagnostics = part("diagnostics_summary", data.diagnostics);
-  const source = data.kind === "source" ? part("source", data.source, true) : undefined;
-  const summary = data.kind === "source" ? part("active_skills_summary", data.summary) : undefined;
-  const instruction = data.kind === "source" ? part("instruction", data.instruction) : undefined;
-  const render = () => [field("field", "recipe"), ...(source ? [source.selected] : []),
-    field("result", data.kind === "source" ? "Recipe source validation failed." : "Tool recipe validation failed."),
-    diagnostics.selected, ...(summary ? [summary.selected] : []), ...(instruction ? [instruction.selected] : [])].join("\n");
+  const diagnostics = registrySelected("diagnostics_summary", data.diagnostics);
+  const source = data.kind === "source" ? registrySelected("source", data.source) : undefined;
+  const summary = data.kind === "source" ? registrySelected("active_skills_summary", data.summary) : undefined;
+  const instruction = data.kind === "source" ? registrySelected("instruction", data.instruction) : undefined;
+  const render = (): RegistryMetadata => ({ field: "recipe", ...(source ? source.selected : {}),
+    result: data.kind === "source" ? "Recipe source validation failed." : "Tool recipe validation failed.",
+    ...diagnostics.selected, ...(summary ? summary.selected : {}), ...(instruction ? instruction.selected : {}) });
   // Preserve fitting diagnostics before large optional source/context/advice fields.
-  for (const current of [diagnostics, source, summary, instruction]) {
-    if (!current || current.selected === current.full) continue;
-    const previous = current.selected;
-    current.selected = current.full;
-    if (Buffer.byteLength(render()) > Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) current.selected = previous;
-  }
-  return render();
+  return growRegistryDocument(render, [diagnostics, ...(source ? [source] : []), ...(summary ? [summary] : []), ...(instruction ? [instruction] : [])]);
 }
 
 function sourceNormalizationFailureText(source: string, reason: string, summary: string, instruction: string): string {
-  const field = ToolsResponse.formatMarkdownField;
-  const part = (key: string, value: string, literal = false) => {
-    const wellFormed = value.isWellFormed();
-    const omitted = `- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
-    const full = wellFormed ? field(key, literal ? ToolsResponse.formatLiteralBlock(value) : value) : omitted;
-    return { full, selected: Buffer.byteLength(full) <= Buffer.byteLength(omitted) ? full : omitted };
-  };
-  const selectedSource = part("source", source, true);
-  const selectedReason = part("reason", reason);
-  const selectedSummary = part("active_skills_summary", summary);
-  const selectedInstruction = part("instruction", instruction);
-  const render = () => [field("field", "from"), selectedSource.selected, field("result", "Recipe source is invalid."),
-    selectedReason.selected, selectedSummary.selected, selectedInstruction.selected].join("\n");
-  for (const current of [selectedSource, selectedReason, selectedSummary, selectedInstruction]) {
-    if (current.selected === current.full) continue;
-    const previous = current.selected;
-    current.selected = current.full;
-    if (Buffer.byteLength(render()) > Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) current.selected = previous;
-  }
-  return render();
+  const selectedSource = registrySelected("source", source);
+  const selectedReason = registrySelected("reason", reason);
+  const selectedSummary = registrySelected("active_skills_summary", summary);
+  const selectedInstruction = registrySelected("instruction", instruction);
+  const render = (): RegistryMetadata => ({ field: "from", ...selectedSource.selected, result: "Recipe source is invalid.",
+    ...selectedReason.selected, ...selectedSummary.selected, ...selectedInstruction.selected });
+  return growRegistryDocument(render, [selectedSource, selectedReason, selectedSummary, selectedInstruction]);
 }
 
 function activeSkillSummary(
@@ -319,16 +300,11 @@ function activeSkillSummary(
 }
 
 function draftPathFailureText(kind: "root" | "missing", reference: string): string {
-  const key = kind === "root" ? "allowed_root" : "path";
-  const render = (selected: string) => "- field: draft\n" + selected + (kind === "root"
-    ? "\n- result: Draft must be under the allowed root.\n- instruction: Use inspect target=recipes view=summary to list drafts."
-    : "\n- result: Draft not found.");
-  const wellFormed = reference.isWellFormed();
-  if (wellFormed) {
-    const complete = render(ToolsResponse.formatMarkdownField(key, ToolsResponse.formatLiteralBlock(reference)));
-    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) return complete;
-  }
-  return render(`- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`);
+  const selected = registrySelected(kind === "root" ? "allowed_root" : "path", reference);
+  const render = (): RegistryMetadata => ({ field: "draft", ...selected.selected,
+    result: kind === "root" ? "Draft must be under the allowed root." : "Draft not found.",
+    ...(kind === "root" ? { instruction: "Use inspect target=recipes view=summary to list drafts." } : {}) });
+  return growRegistryDocument(render, [selected]);
 }
 
 function assertDraftPath<TContext>(
@@ -382,24 +358,16 @@ function draftReceiptText(result: "updated" | "registered", tool: string, callab
 }
 
 function duplicateRegistrationText(value: string): string {
-  const render = (selected: string) => "- field: name\n" + selected + "\n- result: Tool already registered.\n- instruction: Use update=true to overwrite.";
-  const wellFormed = value.isWellFormed();
-  if (wellFormed) {
-    const complete = render(ToolsResponse.formatMarkdownField("value", value));
-    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) return complete;
-  }
-  return render(`- value: [${wellFormed ? "omitted" : "unavailable"}]\n- value_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`);
+  const selected = registrySelected("value", value);
+  const render = (): RegistryMetadata => ({ field: "name", ...selected.selected,
+    result: "Tool already registered.", instruction: "Use update=true to overwrite." });
+  return growRegistryDocument(render, [selected]);
 }
 
 function draftRecipeFailureText(key: "reason" | "diagnostics_summary", value?: string): string {
-  const header = "- field: draft\n- result: Draft recipe is invalid.";
-  if (value === undefined) return header;
-  const wellFormed = value.isWellFormed();
-  if (wellFormed) {
-    const complete = header + "\n" + ToolsResponse.formatMarkdownField(key, value);
-    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) return complete;
-  }
-  return header + `\n- ${key}: [${wellFormed ? "omitted" : "unavailable"}]\n- ${key}_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`;
+  const selected = value === undefined ? undefined : registrySelected(key, value);
+  const render = (): RegistryMetadata => ({ field: "draft", result: "Draft recipe is invalid.", ...(selected ? selected.selected : {}) });
+  return growRegistryDocument(render, selected ? [selected] : []);
 }
 
 function promoteDraftRecipe<TContext>(
@@ -607,9 +575,9 @@ function assertTemplateIsNotNestedRecipe(value: unknown): void {
       ))
   ) {
     throw new Error(
-      ExecutionOutput.formatToolText(
-        "- field: template\n- result: Nested Recipe-shaped templates are not a register_tool source mode.\n- instruction: retry with from=<skill>/<recipe> and defaults={...}.",
-      ),
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "template",
+        result: "Nested Recipe-shaped templates are not a register_tool source mode.",
+        instruction: "retry with from=<skill>/<recipe> and defaults={...}." })),
     );
   }
 }
@@ -626,7 +594,7 @@ function getInputTemplate(
     });
     if (steps.length === 0)
       throw new Error(
-        ExecutionOutput.formatToolText("- field: template\n- result: Tool template sequence is empty."),
+        ExecutionOutput.formatToolText(registryMetadataText({ field: "template", result: "Tool template sequence is empty." })),
       );
     return value;
   }
@@ -637,9 +605,8 @@ function getInputTemplate(
     return value as CommandTemplates.CommandTemplateConfig;
   }
   throw new Error(
-    ExecutionOutput.formatToolText(
-      "- field: template\n- result: unsupported template type\n- supported_types:\n  - string\n  - object\n  - sequence",
-    ),
+    ExecutionOutput.formatToolText(registryMetadataText({ field: "template", result: "unsupported template type",
+      supported_types: ["string", "object", "sequence"] })),
   );
 }
 
@@ -665,7 +632,7 @@ function normalizeDefaults(value: unknown): Record<string, unknown> | undefined
   if (value === undefined) return undefined;
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(
-      ExecutionOutput.formatToolText("- field: defaults\n- result: Tool defaults must be an object."),
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "defaults", result: "Tool defaults must be an object." })),
     );
   }
   return { ...(value as Record<string, unknown>) };
@@ -725,9 +692,8 @@ function buildAuthoredRecipe(
   const description = (input.description ?? existing?.description ?? "").trim();
   if (!description && !from) {
     throw new Error(
-      ExecutionOutput.formatToolText(
-        "- field: description\n- result: Tool description is required for command-template registration.",
-      ),
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "description",
+        result: "Tool description is required for command-template registration." })),
     );
   }
   const inputDefaults = normalizeDefaults(input.defaults);
@@ -737,9 +703,10 @@ function buildAuthoredRecipe(
     );
     if (runtimeOwnedDefault) {
       throw new Error(
-        ExecutionOutput.formatToolText(
-          `- field: defaults\n- key: ${runtimeOwnedDefault}\n- result: Tool defaults cannot set runtime-owned input.\n- instruction: remove that default and retry register_tool; the runtime supplies it.`,
-        ),
+        ExecutionOutput.formatToolText(registryMetadataText({ field: "defaults",
+          ...registrySelected("key", runtimeOwnedDefault).selected,
+          result: "Tool defaults cannot set runtime-owned input.",
+          instruction: "remove that default and retry register_tool; the runtime supplies it." })),
       );
     }
     const authored: Record<string, unknown> = {
@@ -758,7 +725,7 @@ function buildAuthoredRecipe(
   const template = getInputTemplate(input.template);
   if (template === null) {
     throw new Error(
-      ExecutionOutput.formatToolText("- field: template\n- result: Tool template cannot be null here."),
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "template", result: "Tool template cannot be null here." })),
     );
   }
   const finalTemplate =
@@ -767,7 +734,7 @@ function buildAuthoredRecipe(
       : template;
   if (!finalTemplate) {
     throw new Error(
-      ExecutionOutput.formatToolText("- field: template\n- result: Tool template is required."),
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "template", result: "Tool template is required." })),
     );
   }
   const authored: Record<string, unknown> = {
@@ -792,9 +759,9 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
   const record = input as RegisterToolInput & Record<string, unknown>;
   if (Object.hasOwn(record, "values")) {
     throw new Error(
-      ExecutionOutput.formatToolText(
-        "- field: values\n- result: register_tool values was removed.\n- replacement_fields:\n  - defaults\n  - from\n- instruction: retry register_tool with defaults for caller inputs, or use from=<skill>/<recipe> for maintained composition.",
-      ),
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "values", result: "register_tool values was removed.",
+        replacement_fields: ["defaults", "from"],
+        instruction: "retry register_tool with defaults for caller inputs, or use from=<skill>/<recipe> for maintained composition." })),
     );
   }
   const fromProvided = Object.hasOwn(record, "from");
@@ -803,9 +770,10 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
     (typeof input.from !== "string" || input.from.trim().length === 0)
   ) {
     throw new Error(
-      ExecutionOutput.formatToolText(
-        "- field: from\n- result: Tool from must be a non-empty Recipe reference.\n- reference_forms:\n  - <skill>/<recipe>\n  - explicit .json path\n  - explicit .md path\n- instruction: retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path.",
-      ),
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "from",
+        result: "Tool from must be a non-empty Recipe reference.",
+        reference_forms: ["<skill>/<recipe>", "explicit .json path", "explicit .md path"],
+        instruction: "retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path." })),
     );
   }
   const draftProvided =
@@ -815,9 +783,9 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
     Number(fromProvided) + Number(draftProvided) + Number(templateProvided);
   if (modeCount > 1) {
     throw new Error(
-      ExecutionOutput.formatToolText(
-        "- result: Use exactly one register_tool source mode.\n- source_modes:\n  - from\n  - template\n  - draft\n- instruction: remove the extra source fields and retry register_tool.",
-      ),
+      ExecutionOutput.formatToolText(registryMetadataText({ result: "Use exactly one register_tool source mode.",
+        source_modes: ["from", "template", "draft"],
+        instruction: "remove the extra source fields and retry register_tool." })),
     );
   }
   if (
@@ -825,21 +793,18 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
     (Object.hasOwn(record, "args") || Object.hasOwn(record, "async"))
   ) {
     throw new Error(
-      ExecutionOutput.formatToolText(
-        "- field: from\n- result: register_tool from inherits args and async behavior.\n- inherited_fields:\n  - args\n  - async\n- instruction: retry register_tool with from and optional defaults only; omit args and async.",
-      ),
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "from",
+        result: "register_tool from inherits args and async behavior.",
+        inherited_fields: ["args", "async"],
+        instruction: "retry register_tool with from and optional defaults only; omit args and async." })),
     );
   }
 }
 
 function reservedRegistrationNameText(value: string): string {
-  const render = (selected: string) => "- field: name\n" + selected + "\n- result: Reserved tool name.";
-  const wellFormed = value.isWellFormed();
-  if (wellFormed) {
-    const complete = render(ToolsResponse.formatMarkdownField("value", value));
-    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1) return complete;
-  }
-  return render(`- value: [${wellFormed ? "omitted" : "unavailable"}]\n- value_omission:\n  - reason: ${wellFormed ? "response_too_large" : "malformed_selected_text"}\n  - shown: 0\n  - omitted: 1\n  - total: 1`);
+  const selected = registrySelected("value", value);
+  const render = (): RegistryMetadata => ({ field: "name", ...selected.selected, result: "Reserved tool name." });
+  return growRegistryDocument(render, [selected]);
 }
 
 function executeRegisterToolUnlocked<TContext>(
@@ -856,7 +821,7 @@ function executeRegisterToolUnlocked<TContext>(
   if (!input.name) return listTools(deps);
   const name = Identity.normalizeToolName(input.name);
   if (!name)
-    throw new Error(ExecutionOutput.formatToolText("- field: name\n- result: Invalid tool name."));
+    throw new Error(ExecutionOutput.formatToolText(registryMetadataText({ field: "name", result: "Invalid tool name." })));
   if (deps.reservedToolNames.has(name)) {
     throw new Error(
       ExecutionOutput.formatToolText(reservedRegistrationNameText(`${name}`)),
@@ -904,9 +869,9 @@ function executeRegisterToolUnlocked<TContext>(
   }
   if (template === undefined && !input.from && !existing) {
     throw new Error(
-      ExecutionOutput.formatToolText(
-        "- result: New registration requires exactly one source mode.\n- source_modes:\n  - from\n  - template\n  - draft\n- instruction: retry register_tool with one source field.",
-      ),
+      ExecutionOutput.formatToolText(registryMetadataText({ result: "New registration requires exactly one source mode.",
+        source_modes: ["from", "template", "draft"],
+        instruction: "retry register_tool with one source field." })),
     );
   }
   const recipePath = getToolRecipePath(deps, name);

package/lib/run-ui-runtime.ts

@@ -14,7 +14,7 @@ import * as Pi from "./pi.ts";
 import * as RunDelivery from "./run-delivery.ts";
 import * as RunDeliveryLineage from "./run-delivery-lineage.ts";
 import * as RunIndex from "./runs-index.ts";
-import { formatLiteralBlock, formatMarkdownField } from "./tools-response.ts";
+import { formatLiteralBlock, formatYamlNotice } from "./tools-response.ts";
 
 export interface RunUiRuntime {
   close(): void;
@@ -48,21 +48,18 @@ export interface RunUiRuntimeDeps {
 }
 
 function formatSteerDiagnosticMessage(eventId: string, stage: "admission" | "delivery", message: string): string {
-  const fields = [formatMarkdownField("event", eventId), formatMarkdownField("attention", "steer"),
-    formatMarkdownField("stage", stage), formatMarkdownField("result", stage === "admission" ? "remains retryable" : "request failed")];
-  if (stage === "delivery") fields.push(formatMarkdownField("delivery", "unconfirmed"), formatMarkdownField("presentation", "unconfirmed"));
   let end = Math.min(message.length, 240);
   const last = message.charCodeAt(end - 1), next = message.charCodeAt(end);
   if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) end -= 1;
   const preview = message.slice(0, end), clipped = end < message.length;
-  if (Buffer.from(preview).toString("utf8") !== preview) {
-    fields.push(formatMarkdownField("diagnostic", "unavailable"), formatMarkdownField("diagnostic_reason", "malformed legacy preview"),
-      formatMarkdownField("diagnostic_omission", "[omitted: unknown]"));
-  } else {
-    fields.push(formatMarkdownField("diagnostic", preview + (clipped ? "…" : "")));
-    if (clipped) fields.push(formatMarkdownField("diagnostic_omission", "[omitted: unknown]"));
-  }
-  return fields.join("\n");
+  // The 240-pair-aligned preview and its explicit unknown-loss marker are unchanged; only metadata is YAML.
+  const diagnostic: Record<string, string> = Buffer.from(preview).toString("utf8") !== preview
+    ? { diagnostic: "unavailable", diagnostic_reason: "malformed legacy preview", diagnostic_omission: "[omitted: unknown]" }
+    : { diagnostic: preview + (clipped ? "…" : ""), ...(clipped ? { diagnostic_omission: "[omitted: unknown]" } : {}) };
+  return formatYamlNotice({ event: eventId, attention: "steer", stage,
+    result: stage === "admission" ? "remains retryable" : "request failed",
+    ...(stage === "delivery" ? { delivery: "unconfirmed", presentation: "unconfirmed" } : {}),
+    ...diagnostic });
 }
 
 /** Transcript-only view of the exact delivered content; never re-read a Run or infer body labels. */
@@ -184,8 +181,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     }
     const message = error instanceof Error ? error.message : String(error);
     try {
-      expectedContext.ui.notify([formatMarkdownField("callback", label), formatMarkdownField("result", "failed"),
-        formatMarkdownField("diagnostic", message)].join("\n"), "error");
+      expectedContext.ui.notify(formatYamlNotice({ callback: label, result: "failed", diagnostic: message }), "error");
     } catch {
       /* stale context or unavailable UI */
     }
@@ -369,12 +365,8 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
         const key = `${batch.batch_id}:${evidence.status}:${evidence.reason ?? ""}`;
         if (!completionDiagnostics.has(key)) {
           completionDiagnostics.add(key);
-          ctx.ui.notify(
-            "\n" + [formatMarkdownField("batch", batch.batch_id), formatMarkdownField("stage", "completion recovery"),
-                formatMarkdownField("evidence", evidence.status), formatMarkdownField("phase", "pending"),
-                formatMarkdownField("reason", evidence.reason ?? "conflicting session evidence")].join("\n"),
-            "warning",
-          );
+          ctx.ui.notify("\n" + formatYamlNotice({ batch: batch.batch_id, stage: "completion recovery",
+            evidence: evidence.status, phase: "pending", reason: evidence.reason ?? "conflicting session evidence" }), "warning");
         }
         return true;
       }
@@ -440,12 +432,8 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
           const key = `${steer.steer_id}:${evidence.status}:${evidence.reason ?? ""}`;
           if (!steerDiagnostics.has(key)) {
             steerDiagnostics.add(key);
-            ctx.ui.notify(
-              [formatMarkdownField("event", steer.event_id), formatMarkdownField("attention", "steer"),
-                formatMarkdownField("stage", "recovery"), formatMarkdownField("evidence", evidence.status),
-                formatMarkdownField("phase", "queued"), formatMarkdownField("reason", evidence.reason ?? "conflicting session evidence")].join("\n"),
-              "warning",
-            );
+            ctx.ui.notify(formatYamlNotice({ event: steer.event_id, attention: "steer", stage: "recovery",
+              evidence: evidence.status, phase: "queued", reason: evidence.reason ?? "conflicting session evidence" }), "warning");
           }
           continue;
         }
@@ -714,14 +702,10 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       );
       if (teardown.failed === 0 || !ctx) return;
       try {
-        ctx.ui.notify(
-          [formatMarkdownField("stage", "shutdown teardown"), formatMarkdownField("killed", String(teardown.killed)),
-            formatMarkdownField("failed", String(teardown.failed)), formatMarkdownField("skipped", String(teardown.skipped)),
-            formatMarkdownField("discovery_failed", String(teardown.discoveryFailed)),
-            formatMarkdownField("summary", teardown.summaryPath == null ? "unavailable" : formatLiteralBlock(teardown.summaryPath)),
-            formatMarkdownField("basis", "teardown report; not scope closure")].join("\n"),
-          "warning",
-        );
+        ctx.ui.notify(formatYamlNotice({ stage: "shutdown teardown", killed: teardown.killed,
+          failed: teardown.failed, skipped: teardown.skipped, discovery_failed: teardown.discoveryFailed,
+          summary: teardown.summaryPath ?? "unavailable",
+          basis: "teardown report; not scope closure" }), "warning");
       } catch {
         /* stale shutdown context */
       }

package/lib/runs-process-windows-mi.ts

@@ -1,6 +1,15 @@
-// Owns: Bounded raw MI wire decoding, query inputs and unadmitted provenance fragments, subordinate to process acquisition.
-// Excludes: Identity construction/digest/comparison, status/liveness/lifecycle/publication/admission,
-// fallback, native invocation and asset loading. Decoded data never admits a representation profile.
+// Owns: Bounded raw MI wire decoding, query inputs, unadmitted provenance fragments, and unrouted
+// helper manifest/asset verification plus a shell-free invocation spec, subordinate to process acquisition.
+// Excludes: Identity construction/digest/comparison, status/liveness/lifecycle/publication/admission, fallback,
+// process spawning and package inventory. No production reader imports this owner; decoded data, verified
+// asset bytes and the invocation spec never admit a representation profile, architecture or activation.
+
+import { createHash } from 'node:crypto';
+
+const MANIFEST_MAX_BYTES = 32 * 1024;
+const EXECUTABLE_MAX_BYTES = 8 * 1024 * 1024;
+const HELPER_VERSION = /^(?:0|[1-9][0-9]{0,5})\.(?:0|[1-9][0-9]{0,5})\.(?:0|[1-9][0-9]{0,5})$/u;
+const MODULE_FILE = /\/lib\/runs-process-windows-mi\.(?:ts|js)$/u;
 
 type NativeStage = 'application' | 'session' | 'input' | 'retrieval' | 'operation' | 'representation' | 'cleanup';
 type RawTimestamp = {
@@ -111,3 +120,158 @@ export function decodeResponse(bytes: Uint8Array, profile: unknown, pids: unknow
   if (optionalNull) return { kind: 'unusable', reason: 'unsupported_optional_fields' };
   return { kind: 'decoded_unadmitted', rows };
 }
+
+/**
+ * Complete-helper manifest claim. Bounded reading, exact-key schema and closed lexemes only; a valid
+ * manifest is integrity/provenance input, never executable authenticity, an approved asset or activation.
+ */
+type HelperManifest = {
+  readonly helper_version: string;
+  readonly architecture: 'windows-x64';
+  readonly protocol: 'native-mi-v1';
+  readonly profiles: readonly ['scalar', 'shared'];
+  readonly native_source_sha256: string;
+  readonly executable_bytes: number;
+  readonly executable_sha256: string;
+  readonly toolchain: { readonly compiler: string; readonly sdk: string; readonly build_arguments: readonly string[] };
+  readonly dependencies: readonly string[];
+  readonly originating_source_commit: string;
+  readonly originating_build_job: string;
+};
+
+type ManifestUnusable =
+  | { readonly kind: 'unusable'; readonly reason: 'oversize_manifest' | 'invalid_manifest' | 'unsupported_manifest' };
+
+function boundedText(bytes: Uint8Array, maximumBytes: number): string | undefined {
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength > maximumBytes) return undefined;
+  if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return undefined;
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); }
+  catch { return undefined; }
+}
+
+function boundedLexemes(value: unknown, maximum: number): string[] | undefined {
+  if (!Array.isArray(value) || value.length > maximum) return undefined;
+  const selected: string[] = [];
+  for (const item of value) {
+    if (typeof item !== 'string' || item.length === 0 || item.length > 128 || !/^[\x20-\x7e]+$/.test(item) || selected.includes(item)) return undefined;
+    selected.push(item);
+  }
+  return selected;
+}
+
+/** Bounded complete-manifest reader: one strict UTF-8 JSON document with an exact reviewed shape. */
+export function readHelperManifest(bytes: Uint8Array):
+  | { readonly kind: 'manifest_unadmitted'; readonly manifest: HelperManifest }
+  | ManifestUnusable {
+  const invalid: ManifestUnusable = { kind: 'unusable', reason: 'invalid_manifest' };
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength > MANIFEST_MAX_BYTES) return { kind: 'unusable', reason: 'oversize_manifest' };
+  const text = boundedText(bytes, MANIFEST_MAX_BYTES);
+  if (text === undefined) return invalid;
+  let value: unknown;
+  try { value = JSON.parse(text); }
+  catch { return invalid; }
+  if (!exactKeys(value, ['helper_version', 'architecture', 'protocol', 'profiles', 'native_source_sha256',
+    'executable_bytes', 'executable_sha256', 'toolchain', 'dependencies', 'originating_source_commit', 'originating_build_job']))
+    return invalid;
+  const { helper_version, architecture, protocol, profiles, native_source_sha256, executable_bytes,
+    executable_sha256, toolchain, dependencies, originating_source_commit, originating_build_job } = value;
+  if (typeof helper_version !== 'string' || !HELPER_VERSION.test(helper_version) ||
+    architecture !== 'windows-x64' || protocol !== 'native-mi-v1' ||
+    !Array.isArray(profiles) || profiles.length !== 2 || profiles[0] !== 'scalar' || profiles[1] !== 'shared')
+    return { kind: 'unusable', reason: 'unsupported_manifest' };
+  if (typeof native_source_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(native_source_sha256) ||
+    typeof executable_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(executable_sha256) ||
+    typeof originating_source_commit !== 'string' || !/^[0-9a-f]{40}$/.test(originating_source_commit) ||
+    typeof originating_build_job !== 'string' || !/^[1-9][0-9]*$/.test(originating_build_job) ||
+    typeof executable_bytes !== 'number' || !Number.isSafeInteger(executable_bytes) || executable_bytes <= 0)
+    return invalid;
+  if (executable_bytes > EXECUTABLE_MAX_BYTES) return { kind: 'unusable', reason: 'unsupported_manifest' };
+  if (!exactKeys(toolchain, ['compiler', 'sdk', 'build_arguments'])) return invalid;
+  const compiler = boundedLexemes([toolchain.compiler], 1)?.[0];
+  const sdk = boundedLexemes([toolchain.sdk], 1)?.[0];
+  const buildArguments = boundedLexemes(toolchain.build_arguments, 32);
+  const dependencyNames = boundedLexemes(dependencies, 32);
+  if (compiler === undefined || sdk === undefined || buildArguments === undefined || dependencyNames === undefined) return invalid;
+  // Fresh primitive claims only; the caller still owns target/version/source-digest policy.
+  return {
+    kind: 'manifest_unadmitted',
+    manifest: {
+      helper_version, architecture: 'windows-x64', protocol: 'native-mi-v1', profiles: ['scalar', 'shared'],
+      native_source_sha256, executable_bytes, executable_sha256,
+      toolchain: { compiler, sdk, build_arguments: buildArguments }, dependencies: dependencyNames,
+      originating_source_commit, originating_build_job,
+    },
+  };
+}
+
+type HelperAssetLocation = {
+  readonly kind: 'located';
+  readonly helper_version: string;
+  readonly manifest_url: URL;
+  readonly executable_url: URL;
+};
+
+/**
+ * Fixed versioned package-relative lookup. Never searches cwd, PATH or caller locations: the only base is
+ * the sibling `native/` directory of this module's own `lib/` (source) or `dist/lib/` (compiled) home.
+ */
+export function resolveHelperAsset(moduleUrl: unknown, runtime: unknown, helperVersion: unknown):
+  | HelperAssetLocation
+  | { readonly kind: 'unusable'; readonly reason: 'unsupported_location' | 'unsupported_target' | 'unsupported_version' } {
+  let url: URL;
+  try { url = new URL(String(moduleUrl)); }
+  catch { return { kind: 'unusable', reason: 'unsupported_location' }; }
+  if (url.protocol !== 'file:' || !MODULE_FILE.test(url.pathname)) return { kind: 'unusable', reason: 'unsupported_location' };
+  const target = runtime as { platform?: unknown; arch?: unknown } | null | undefined;
+  if (target?.platform !== 'win32' || target?.arch !== 'x64') return { kind: 'unusable', reason: 'unsupported_target' };
+  if (typeof helperVersion !== 'string' || !HELPER_VERSION.test(helperVersion)) return { kind: 'unusable', reason: 'unsupported_version' };
+  const directory = `../native/windows-mi/win32-x64/${helperVersion}/`;
+  return {
+    kind: 'located', helper_version: helperVersion,
+    manifest_url: new URL(`${directory}manifest.json`, url),
+    executable_url: new URL(`${directory}helper.exe`, url),
+  };
+}
+
+/** Injected bounded reader: exact bytes for one fixed URL or nothing. Never a path, cwd or PATH lookup. */
+export type HelperAssetReader = (url: URL, maximumBytes: number) => Uint8Array | undefined;
+
+type HelperAssetOutcome =
+  | { readonly kind: 'asset_verified_unadmitted'; readonly manifest: HelperManifest; readonly executable_sha256: string; readonly executable_bytes: number }
+  | { readonly kind: 'unusable'; readonly reason:
+    'missing_manifest' | 'oversize_manifest' | 'invalid_manifest' | 'unsupported_manifest' | 'version_mismatch' |
+    'missing_asset' | 'oversize_asset' | 'size_mismatch' | 'digest_mismatch' };
+
+/** Trusted exact-byte selection: bounded manifest read, exact declared size, then exact SHA-256 match. */
+export function loadHelperAsset(location: HelperAssetLocation, read: HelperAssetReader): HelperAssetOutcome {
+  const manifestBytes = read(location.manifest_url, MANIFEST_MAX_BYTES + 1);
+  if (manifestBytes === undefined) return { kind: 'unusable', reason: 'missing_manifest' };
+  if (manifestBytes.byteLength > MANIFEST_MAX_BYTES) return { kind: 'unusable', reason: 'oversize_manifest' };
+  const reading = readHelperManifest(manifestBytes);
+  if (reading.kind === 'unusable') return { kind: 'unusable', reason: reading.reason };
+  const { manifest } = reading;
+  if (manifest.helper_version !== location.helper_version) return { kind: 'unusable', reason: 'version_mismatch' };
+  // One extra byte detects growth; a shorter read can never satisfy the declared size.
+  const executableBytes = read(location.executable_url, manifest.executable_bytes + 1);
+  if (executableBytes === undefined) return { kind: 'unusable', reason: 'missing_asset' };
+  if (executableBytes.byteLength > manifest.executable_bytes) return { kind: 'unusable', reason: 'oversize_asset' };
+  if (executableBytes.byteLength !== manifest.executable_bytes) return { kind: 'unusable', reason: 'size_mismatch' };
+  const digest = createHash('sha256').update(executableBytes).digest('hex');
+  if (digest !== manifest.executable_sha256) return { kind: 'unusable', reason: 'digest_mismatch' };
+  return { kind: 'asset_verified_unadmitted', manifest, executable_sha256: digest, executable_bytes: executableBytes.byteLength };
+}
+
+type HelperInvocation =
+  | { readonly kind: 'invocation_unadmitted'; readonly command: string; readonly args: readonly string[];
+      readonly options: { readonly shell: false; readonly windowsHide: true } }
+  | { readonly kind: 'unusable'; readonly reason: 'unsupported_executable' | 'invalid_query' };
+
+/** Shell-free invocation spec only: no spawn, retry, fallback or execution-policy bypass. */
+export function helperInvocation(executablePath: unknown, profile: unknown, pids: unknown): HelperInvocation {
+  if (typeof executablePath !== 'string' || executablePath.length === 0 || executablePath.length > 4096 ||
+    !/^[A-Za-z]:[\\/][^\x00\r\n"]*\.exe$/.test(executablePath)) return { kind: 'unusable', reason: 'unsupported_executable' };
+  const query = queryArguments(profile, pids);
+  if (!query) return { kind: 'unusable', reason: 'invalid_query' };
+  return { kind: 'invocation_unadmitted', command: executablePath, args: query,
+    options: { shell: false, windowsHide: true } };
+}