@llblab/pi-actors 0.56.1 → 0.57.1

package/lib/run-delivery.ts

@@ -69,7 +69,7 @@ export interface RunCompletionBatch {
   /** Retained singleton capture; absence preserves older indexed bytes. Never a new-capture selector. */
   readonly single_result?: true;
   /** Captured record-list shape; no public format/version choice or source authority. */
-  readonly result_layout?: "records" | "run_headers" | "headings" | "headings_flat_omissions" | "headings_outcomes" | "headings_shared_results" | "headings_shared_kinds" | "frontmatter_v1" | "frontmatter_v2" | "completion_yaml_core_v1";
+  readonly result_layout?: "records" | "run_headers" | "headings" | "headings_flat_omissions" | "headings_outcomes" | "headings_shared_results" | "headings_shared_kinds" | "frontmatter_v1" | "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1";
   /** Immutable scope/order/range data, not a caller-selected format or allocation authority. */
   readonly numbering?: RunCompletionNumbering;
   /** Formatting version/data only; no recipient ownership, read or publication capability. */
@@ -467,8 +467,12 @@ function isFrontmatterCompletionLayout(layout: unknown): boolean {
   return layout === "frontmatter_v1" || layout === "frontmatter_v2";
 }
 
+function isYamlCompletionLayout(layout: unknown): boolean {
+  return layout === "completion_yaml_core_v1" || layout === "completion_yaml_files_v1";
+}
+
 function isSharedCompletionLayout(layout: unknown): boolean {
-  return layout === "headings_shared_results" || layout === "headings_shared_kinds" || layout === "completion_yaml_core_v1" || isFrontmatterCompletionLayout(layout);
+  return layout === "headings_shared_results" || layout === "headings_shared_kinds" || isYamlCompletionLayout(layout) || isFrontmatterCompletionLayout(layout);
 }
 
 function parseBatch(value: unknown): RunCompletionBatch {
@@ -512,7 +516,7 @@ function parseBatch(value: unknown): RunCompletionBatch {
     throw new Error("Completion shared text budget is invalid");
   }
   const numberingDescriptor = Object.getOwnPropertyDescriptor(record, "numbering");
-  if (numberingDescriptor && (resultLayout === "completion_yaml_core_v1" || !Object.hasOwn(numberingDescriptor, "value") || presentationFormat !== "ax_records" || (resultLayout !== "headings" && resultLayout !== "headings_flat_omissions" && resultLayout !== "headings_outcomes" && !isSharedCompletionLayout(resultLayout)))) {
+  if (numberingDescriptor && (isYamlCompletionLayout(resultLayout) || !Object.hasOwn(numberingDescriptor, "value") || presentationFormat !== "ax_records" || (resultLayout !== "headings" && resultLayout !== "headings_flat_omissions" && resultLayout !== "headings_outcomes" && !isSharedCompletionLayout(resultLayout)))) {
     throw new Error("Completion numbering requires a canonical captured heading layout");
   }
   const numbering = numberingDescriptor ? parseCompletionNumbering(numberingDescriptor.value, members.length) : undefined;
@@ -891,7 +895,7 @@ export function requestRunCompletionStream(input: { tempDir: string; ownerId: st
 }
 
 export function admitRunCompletionBatch(input: AdmitRunCompletionBatchInput): RunCompletionBatch {
-  return captureCompletionBatch(input, false, "completion_yaml_core_v1");
+  return captureCompletionBatch(input, false, "completion_yaml_files_v1");
 }
 
 /** Kernel-only opt-in; ordinary Pi capture stays fenced until session/lifecycle integration is admitted. */
@@ -901,10 +905,10 @@ export function captureRunCompletionStreamBatch(input: AdmitRunCompletionBatchIn
 
 /** Private ordinary candidate composition; stream capture retains its separately gated codec. */
 export function captureRunCompletionYamlCandidateBatch(input: AdmitRunCompletionBatchInput): RunCompletionBatch {
-  return captureCompletionBatch(input, false, "completion_yaml_core_v1");
+  return captureCompletionBatch(input, false, "completion_yaml_files_v1");
 }
 
-function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: boolean, layout: "frontmatter_v2" | "completion_yaml_core_v1" = "frontmatter_v2"): RunCompletionBatch {
+function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: boolean, layout: "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1" = "frontmatter_v2"): RunCompletionBatch {
   const now = (input.now ?? new Date()).toISOString();
   if (Object.hasOwn(input, "presentationFormat")) throw new Error("Completion presentation selection is not supported; new batches use AX.");
   if (Object.hasOwn(input, "numbering")) throw new Error("Completion numbering is assigned only by journal capture");
@@ -917,7 +921,7 @@ function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: b
     members: input.members,
     phase: "pending",
   });
-  const draft: RunCompletionBatch = layout === "completion_yaml_core_v1"
+  const draft: RunCompletionBatch = isYamlCompletionLayout(layout)
     ? parseBatch({ ...captured, result_layout: layout }) : { ...captured, result_layout: layout };
   return mutateJournal(input.tempDir, input.ownerId, (journal) => {
     let batch = draft;
@@ -946,9 +950,9 @@ function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: b
     } else if (journal.completion_stream) {
       throw new Error("Completion stream capture requires the numbered kernel path; stream state is retained");
     }
-    if (layout !== "completion_yaml_core_v1") batch = retainSharedCompletionTexts(batch);
+    if (!isYamlCompletionLayout(layout)) batch = retainSharedCompletionTexts(batch);
     if (projectCompletionBatchMessage(batch).membersShown === batch.members.length) {
-      if (layout === "completion_yaml_core_v1") batch = retainSharedCompletionTexts(batch);
+      if (isYamlCompletionLayout(layout)) batch = retainSharedCompletionTexts(batch);
       journal.completion_batch = batch;
       return batch;
     }
@@ -1515,7 +1519,7 @@ function isRoutineCompletionSummary(member: RunCompletionBatchMember): boolean {
 }
 
 function completionRecordRow(member: RunCompletionBatchMember, index: number, byIdentity: Map<string, RunCompletionBatchMember>, flat = false, layout?: RunCompletionBatch["result_layout"], textBudget?: number): CompletionRow {
-  const frontmatter = isFrontmatterCompletionLayout(layout) || layout === "completion_yaml_core_v1";
+  const frontmatter = isFrontmatterCompletionLayout(layout) || isYamlCompletionLayout(layout);
   const simpleKinds = frontmatter || layout === "headings_shared_kinds", shared = isSharedCompletionLayout(layout);
   const outcomes = shared || layout === "headings_outcomes", directOmission = outcomes || layout === "headings_flat_omissions";
   const run = member.run.startsWith("run:") ? member.run.slice(4) : member.run;
@@ -1780,6 +1784,83 @@ function completionYamlReferences(row: CompletionRow): Record<string, Completion
   return technical;
 }
 
+/** Split selected paths without normalize/resolve/relative: dot and symlink routes must not be rewritten. */
+function rootedCompletionPath(path: CompletionYamlData, runRoot?: string): { root: string; path: string } | undefined {
+  if (typeof path !== "string" || !path.isWellFormed()) return undefined;
+  const windows = /^(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+[\\/])/u.test(path);
+  const separator = windows ? /[\\/]/u : /\//u;
+  if (!windows && !path.startsWith("/")) return undefined;
+  if (path.split(separator).some(part => part === "." || part === "..")) return undefined;
+  if (runRoot && path.startsWith(runRoot)) {
+    const tail = path.slice(runRoot.length);
+    if (separator.test(runRoot.slice(-1)) ? tail.length > 0 : separator.test(tail[0] ?? "")) {
+      const relative = separator.test(runRoot.slice(-1)) ? tail : tail.slice(1);
+      if (relative && !separator.test(relative[0]!)) return { root: runRoot, path: relative };
+    }
+  }
+  let split = -1;
+  for (let i = 0; i < path.length; i++) if (separator.test(path[i]!)) split = i;
+  if (split < 0 || split === path.length - 1) return undefined;
+  const end = split === 0 || (windows && split === 2 && path[1] === ":") ? split + 1 : split;
+  return { root: path.slice(0, end), path: path.slice(split + 1) };
+}
+
+/** Body-free, read-free navigation over already selected references. Roots are presentation bases, not containment proof. */
+function completionRootedFiles(row: CompletionRow, member: RunCompletionBatchMember, locations?: RunDirectoryNavigation): Record<string, CompletionYamlData> {
+  const technical = completionYamlReferences(row), files: Record<string, CompletionYamlData> = {};
+  const groups: Array<{ root: CompletionYamlData; entries: Record<string, CompletionYamlData>[] }> = [];
+  const runRoot = locations?.state === "available" ? locations.directory : undefined;
+  const group = (root: CompletionYamlData): number => {
+    const found = groups.findIndex(item => item.root === root);
+    if (found >= 0) return found;
+    groups.push({ root, entries: [] }); return groups.length - 1;
+  };
+  let priority = Infinity;
+  const add = (path: CompletionYamlData, entry: Record<string, CompletionYamlData>, rank = Infinity, base?: string): void => {
+    const selected = rootedCompletionPath(path, runRoot);
+    const index = group(selected?.root ?? (base === undefined ? null : completionYamlString(base)));
+    const selectedPath = selected?.path ?? path;
+    groups[index]!.entries.push({ ...entry, path: selectedPath,
+      ...(!selected && base === undefined ? { path_basis: "as_recorded", base_unavailable: true } : {}) });
+    if (selected && rank < priority) {
+      priority = rank; files.read_first = { group: index, entry: groups[index]!.entries.length - 1 };
+    }
+  };
+  for (const [role, purpose, rank] of [
+    ["primary", "Full result text", 0], ["diagnostic_metadata", "Recorded error and command metadata", 1],
+    ["artifact_inventory", "Declared artifact inventory; target availability unproven", 2],
+  ] as const) {
+    const detail = technical[role] as Record<string, CompletionYamlData> | undefined;
+    if (!detail) continue;
+    const { source: rawSource, ...facts } = detail;
+    const { path, ...binding } = rawSource as Record<string, CompletionYamlData>;
+    add(path!, { role, purpose, ...facts, source: binding }, rank);
+    delete technical[role];
+  }
+  const artifacts = technical.artifacts as { scope: string; declarations: { name: CompletionYamlData; path: CompletionYamlData }[] } | undefined;
+  if (artifacts) {
+    for (const item of artifacts.declarations)
+      add(item.path, { role: "artifact", purpose: "Declared artifact", name: item.name, scope: artifacts.scope, state: "declared" });
+    delete technical.artifacts;
+  }
+  if (locations?.state === "available") {
+    const { directory, files: selectedFiles, ...observation } = locations;
+    files.observation = { ...observation, run: completionYamlString(locations.run), run_instance_id: completionYamlString(locations.run_instance_id),
+      group: group(completionYamlString(directory)) };
+    for (const item of selectedFiles) {
+      const { path, ...facts } = item;
+      const purpose = item.role === "result" ? "Recorded result metadata" : item.role === "execution" ? "Recorded execution and capture locations" : "Recorded Run file";
+      add(typeof path === "string" ? completionYamlString(path) : null, { ...facts, purpose },
+        item.state === "present" && item.role === "result" ? 3 : item.state === "present" && item.role === "execution" ? 4 : Infinity, directory);
+    }
+  } else if (locations) files.observation = { ...locations, run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id) };
+  if (groups.length) {
+    files.groups = groups;
+  }
+  if (Object.keys(technical).length) files.notes = technical;
+  return files;
+}
+
 type PreparedCompletionYamlProjection =
   | { state: "unsupported" }
   | { state: "overbudget" }
@@ -1788,6 +1869,7 @@ type PreparedCompletionYamlProjection =
 function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: readonly { row: CompletionRow; location?: CompletionPiece }[],
   references: ReadonlySet<number>, ordered: readonly RunCompletionBatchMember[]): PreparedCompletionYamlProjection {
   const packet: CompletionYamlPacket = { batchId: safe.batch_id, records: [] };
+  const rooted = safe.result_layout === "completion_yaml_files_v1";
   if (!safe.batch_id.isWellFormed()) return { state: "unsupported" };
   for (const [index, { row, location }] of candidates.entries()) {
     const member = ordered[index]!;
@@ -1804,28 +1886,38 @@ function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: r
       else if (key === "artifact_declarations") metadata[key] = member.artifact_inventory?.declarations_total ?? Object.keys(member.artifacts ?? {}).length;
       else metadata[key] = completionYamlString(value);
     }
-    const technical = completionYamlReferences(row);
-    if (Object.keys(technical).length) metadata.references = technical;
-    if (references.has(index) && location) {
-      const navigation = safe.file_navigation!.find(item => safe.members[item.member_index] === member)!;
-      // Navigation is already decoded native data, not the JSON display field.
-      const locations = navigation.locations;
-      metadata.run_files = { run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id),
-        locations: locations.state === "available" ? { ...locations, run: completionYamlString(locations.run),
-          run_instance_id: completionYamlString(locations.run_instance_id), directory: completionYamlString(locations.directory),
-          files: locations.files.map(file => ({ ...file, ...(typeof file.path === "string" ? { path: completionYamlString(file.path) } : {}) })) } as CompletionYamlData
-          : { ...locations } };
+    const navigation = references.has(index) && location
+      ? safe.file_navigation!.find(item => safe.members[item.member_index] === member)!.locations : undefined;
+    if (rooted) {
+      const files = completionRootedFiles(row, member, navigation);
+      if (Object.keys(files).length) metadata.files = files;
+    } else {
+      const technical = completionYamlReferences(row);
+      if (Object.keys(technical).length) metadata.references = technical;
+      if (navigation) {
+        metadata.run_files = { run: completionYamlString(member.run), run_instance_id: completionYamlString(member.run_instance_id),
+          locations: navigation.state === "available" ? { ...navigation, run: completionYamlString(navigation.run),
+            run_instance_id: completionYamlString(navigation.run_instance_id), directory: completionYamlString(navigation.directory),
+            files: navigation.files.map(file => ({ ...file, ...(typeof file.path === "string" ? { path: completionYamlString(file.path) } : {}) })) } as CompletionYamlData
+              : { ...navigation } };
+      }
     }
     const parts: CompletionYamlPart[] = [];
     const add = (part: CompletionYamlPart) => { if (parts.length) parts.push({ marker: "\n" }); parts.push(part); };
     for (const piece of row.pieces) if (piece.block) {
       if (!piece.text.isWellFormed()) return { state: "unsupported" };
-      add(piece.block === "body" ? { body: piece.text } : { marker: piece.text });
+      if (rooted && piece.block === "marker" && !/^\[[0-9]+ characters omitted\]$/u.test(piece.text)) {
+        metadata.text_warnings ??= [];
+        (metadata.text_warnings as CompletionYamlData[]).push(piece.text);
+      } else add(piece.block === "body" ? { body: piece.text } : { marker: piece.text });
+    }
+    if (safe.file_navigation !== undefined && !references.has(index)) {
+      if (rooted) metadata.run_files_omission = { reason: "packet_byte_limit", shown: 0, omitted: 1, total: 1 };
+      else add({ marker: "Run-file reference omitted (packet byte limit)." });
     }
-    if (safe.file_navigation !== undefined && !references.has(index)) add({ marker: "Run-file reference omitted (packet byte limit)." });
     packet.records.push({ metadata, parts });
   }
-  const service: Record<string, CompletionYamlData> = {};
+  const service: Record<string, CompletionYamlData> = rooted ? { header_layout: "rooted_files_v1" } : {};
   const omitted = safe.members.length - candidates.length;
   if (omitted) {
     service.omitted_results = omitted;
@@ -1841,7 +1933,11 @@ function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: r
     service.numbering = { ...safe.numbering, session_id: completionYamlString(safe.numbering.session_id), member_order: [...safe.numbering.member_order] };
     if (safe.numbering.kind === "unavailable") service.numbering_unavailable = safe.numbering.reason;
   }
-  if (safe.inventory_source) service.result_inventory = { ...safe.inventory_source, path: completionYamlString(safe.inventory_source.path) };
+  if (safe.inventory_source) {
+    const path = rooted ? rootedCompletionPath(safe.inventory_source.path) : undefined;
+    service.result_inventory = { ...safe.inventory_source,
+      ...(path ? { root: path.root, path: path.path } : { path: completionYamlString(safe.inventory_source.path) }) };
+  }
   if (Object.keys(service).length) packet.service = service;
   const chunks: string[] = [];
   let bytes = 0;
@@ -1890,7 +1986,7 @@ export function projectRunCompletionYamlPrototype(batch: unknown):
   }
 }
 
-function projectCompletionRecords(safe: RunCompletionBatch, assembler: "legacy" | "yaml" = safe.result_layout === "completion_yaml_core_v1" ? "yaml" : "legacy"): { message: string; membersShown: number; compact_ranges: [number, number][]; textBudget?: number; blocks?: readonly CompletionBlock[] } {
+function projectCompletionRecords(safe: RunCompletionBatch, assembler: "legacy" | "yaml" = isYamlCompletionLayout(safe.result_layout) ? "yaml" : "legacy"): { message: string; membersShown: number; compact_ranges: [number, number][]; textBudget?: number; blocks?: readonly CompletionBlock[] } {
   const frontmatter = isFrontmatterCompletionLayout(safe.result_layout) || assembler === "yaml";
   const shared = isSharedCompletionLayout(safe.result_layout);
   const maxBytes = shared ? Limits.RUN_COMPLETION_MODEL_MAX_BYTES : Limits.RUN_DELIVERY_MODEL_MAX_BYTES;
@@ -2118,7 +2214,7 @@ export function projectRunCompletionBatchPresentation(batch: RunCompletionBatch)
   const safe = parseBatch(batch);
   if (safe.presentation_format !== "ax_records" && safe.presentation_format !== "ax_records_v3") return { content: projectCompletionBatchMessage(safe).message };
   const result = safe.result_layout !== undefined ? projectCompletionRecords(safe) : projectRetainedRecordCompletionBatch(safe);
-  if (safe.result_layout === "completion_yaml_core_v1") return { content: result.message, presentation: Object.freeze({
+  if (isYamlCompletionLayout(safe.result_layout)) return { content: result.message, presentation: Object.freeze({
     format: "completion_yaml_core_v1", content_sha256: createHash("sha256").update(result.message).digest("hex"),
   }) };
   return { content: result.message, presentation: Object.freeze({ format: isFrontmatterCompletionLayout(safe.result_layout) ? "completion_frontmatter_v1" : safe.presentation_format, content_sha256: createHash("sha256").update(result.message).digest("hex"),
@@ -2253,19 +2349,22 @@ export function readRunCompletionPresentation(content: string, value: unknown):
         !completionYamlKeys(hint, ["format", "content_sha256"]) || hint.format !== completionYamlCodec ||
         hint.content_sha256 !== createHash("sha256").update(content).digest("hex")) return full;
     const segments: NonNullable<RunCompletionPresentationView["segments"]>[number][] = [];
+    const rooted = core.packet.service?.header_layout === "rooted_files_v1";
+    const facts = Object.fromEntries(Object.entries(core.packet.service ?? {}).filter(([key]) => key !== "header_layout"));
     for (const [index, record] of core.packet.records.entries()) {
       if (index) segments.push({ kind: "separator", text: "\n" });
-      const metadata = Object.fromEntries(Object.entries(record.metadata).filter(([key]) => key !== "references" && key !== "run_files"));
+      const metadata = Object.fromEntries(Object.entries(record.metadata).filter(([key]) => rooted || (key !== "references" && key !== "run_files")));
+      if (rooted && index === 0 && Object.keys(facts).length) metadata.delivery = facts;
       const header = renderYamlMetadata(metadata, completionYamlMaxBytes);
       if (header.state !== "available") return full;
       segments.push({ kind: "header", text: record.parts.length ? `---\n${header.text}---` : header.text.replace(/\n$/u, "") });
       for (const part of record.parts) segments.push("body" in part ? { kind: "body", text: part.body } : { kind: "marker", text: part.marker });
     }
-    if (core.packet.service) {
-      const service = renderYamlMetadata(core.packet.service, completionYamlMaxBytes);
+    if (core.packet.service && (!rooted || !core.packet.records.length)) {
+      const service = renderYamlMetadata(rooted ? facts : core.packet.service, completionYamlMaxBytes);
       if (service.state !== "available") return full;
       if (segments.length) segments.push({ kind: "separator", text: "\n" });
-      segments.push({ kind: "service", text: service.text.replace(/\n$/u, "") });
+      segments.push({ kind: rooted ? "header" : "service", text: service.text.replace(/\n$/u, "") });
     }
     return { text: segments.map(segment => segment.text).join("\n"), compact: true, records: true, yaml: true,
       segments: Object.freeze(segments.map(segment => Object.freeze(segment))) };

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 } };
+}