@llblab/pi-kit 0.38.4 → 0.39.0

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

@@ -1,10 +1,145 @@
 /**
- * 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.
  */
 
+import { Document, isScalar, visit } from "yaml";
 import * as Limits from "./limits.ts";
+import type { RunSnapshot } from "./runs-snapshot.ts";
+
+export type YamlMetadataRendering =
+  | { readonly state: "available"; readonly text: string }
+  | { readonly state: "unavailable"; readonly reason: "budget_invalid" | "metadata_invalid" | "metadata_too_large" };
+
+function yamlMetadataText(value: unknown): string {
+  const document = new Document(value, { version: "1.2", schema: "core", aliasDuplicateObjects: false });
+  // yaml's plain-key preference otherwise treats a leading BOM as document whitespace.
+  visit(document, { Pair(_key, pair) {
+    if (isScalar(pair.key) && typeof pair.key.value === "string" && pair.key.value.includes("\uFEFF")) pair.key.type = "QUOTE_DOUBLE";
+  } });
+  return document.toString({ collectionStyle: "block", indent: 2, lineWidth: 0, directives: false,
+    defaultKeyType: "PLAIN", defaultStringType: "QUOTE_DOUBLE", doubleQuotedAsJSON: true });
+}
+
+/** Pure selected-metadata formatting, not admission or authority. */
+export function renderYamlMetadata(value: unknown, byteBudget: number): YamlMetadataRendering {
+  // Execution ceiling, not a caller allowance. The caller still owns its smaller policy budget.
+  if (!Number.isSafeInteger(byteBudget) || byteBudget <= 0 || byteBudget > 49152) return { state: "unavailable", reason: "budget_invalid" };
+  let remaining = byteBudget;
+  let reason: "metadata_invalid" | "metadata_too_large" = "metadata_invalid";
+  const active = new Set<object>();
+  const charge = (bytes: number): boolean => {
+    remaining -= bytes;
+    if (remaining >= 0) return true;
+    reason = "metadata_too_large";
+    return false;
+  };
+  const string = (text: string): boolean => {
+    if (text.length > remaining) { reason = "metadata_too_large"; return false; }
+    return text.isWellFormed() && charge(Buffer.byteLength(text, "utf8"));
+  };
+  const copy = (input: unknown, depth: number): { value: unknown } | undefined => {
+    if (!charge(1)) return undefined;
+    if (typeof input === "string") return string(input) ? { value: input } : undefined;
+    if (input === null || typeof input === "boolean") return { value: input };
+    // Refuse -0 explicitly: default YAML numeric serialization would erase its sign.
+    if (typeof input === "number") return Number.isFinite(input) && !Object.is(input, -0) ? { value: input } : undefined;
+    if (!input || typeof input !== "object") return undefined;
+    // Small explicit supported-input ceiling protects the library's recursive AST/stringifier.
+    if (depth > 64 || active.has(input)) return undefined;
+    const array = Array.isArray(input), prototype = Object.getPrototypeOf(input);
+    if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) return undefined;
+    active.add(input);
+    const result: unknown[] | Record<string, unknown> = array ? [] : Object.create(null);
+    const length = array ? Object.getOwnPropertyDescriptor(input, "length") : undefined;
+    if (array && (!length || !Object.hasOwn(length, "value") || !Number.isSafeInteger(length.value) || length.value < 0)) return undefined;
+    if (array && length!.value > remaining) { reason = "metadata_too_large"; return undefined; }
+    let count = 0;
+    // ownKeys is necessarily atomic reflection; descriptor/value walks stop at the budget.
+    for (const key of Reflect.ownKeys(input)) {
+      if (array && key === "length") continue;
+      if (typeof key !== "string" || (array && key !== String(count))) return undefined;
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor || !Object.hasOwn(descriptor, "value") || !descriptor.enumerable) return undefined;
+      if (!array && !string(key)) return undefined;
+      const child = copy(descriptor.value, depth + 1);
+      if (!child) return undefined;
+      Object.defineProperty(result, key, { value: child.value, enumerable: true, configurable: true, writable: true });
+      count++;
+    }
+    if (array && count !== length!.value) return undefined;
+    active.delete(input);
+    return { value: result };
+  };
+  try {
+    if (!value || typeof value !== "object") return { state: "unavailable", reason: "metadata_invalid" };
+    const copied = copy(value, 0);
+    if (!copied) return { state: "unavailable", reason };
+    const text = yamlMetadataText(copied.value);
+    return Buffer.byteLength(text, "utf8") <= byteBudget ? { state: "available", text } : { state: "unavailable", reason: "metadata_too_large" };
+  } catch {
+    return { state: "unavailable", reason: "metadata_invalid" };
+  }
+}
+
+export function formatMarkdownField(key: string, value: string, depth = 0): string {
+  const indent = "  ".repeat(depth);
+  return /[\r\n]/u.test(value)
+    ? `${indent}- ${key}:\n${indent}  ${value.replaceAll(/\r\n|\r|\n/gu, newline => `${newline}${indent}  `)}`
+    : `${indent}- ${key}: ${value}`;
+}
+
+export function formatInspectNextAction(target: string, view: string, verbose?: boolean): string {
+  return ["- next:", formatMarkdownField("tool", "inspect", 1), formatMarkdownField("target", target, 1),
+    formatMarkdownField("view", view, 1), ...(verbose === undefined ? [] : [formatMarkdownField("verbose", String(verbose), 1)])].join("\n");
+}
+
+export function formatLiteralBlock(value: string): string {
+  let length = 3;
+  for (const run of value.matchAll(/`+/gu)) length = Math.max(length, run[0].length + 1);
+  const fence = "`".repeat(length);
+  return `${fence}text\n${value}\n${fence}`;
+}
+
+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 function renderRunSnapshot(value: unknown, format: "text" | "json" = "text"): Readonly<RunSnapshotRendering> {
+  const unavailable = (reason: Extract<RunSnapshotRendering, { state: "unavailable" }>["reason"]): Readonly<RunSnapshotRendering> => Object.freeze({ state: "unavailable", reason });
+  if (format !== "text" && format !== "json") return unavailable("format_invalid");
+  if (!value || typeof value !== "object" || Array.isArray(value)) return unavailable("snapshot_invalid");
+  const fields: Record<string, unknown> = Object.create(null);
+  for (const key of ["kind", "run", "run_instance_id", "captured_at", "elapsed_ms", "status", "phase", "cwd", "evidence", "evidence_error"]) {
+    const field = Object.getOwnPropertyDescriptor(value, key);
+    if (!field) { if (key !== "phase" && key !== "evidence_error") return unavailable("snapshot_invalid"); continue; }
+    if (!Object.hasOwn(field, "value")) return unavailable("snapshot_invalid");
+    if (typeof field.value === "string" && field.value.length > Limits.RUN_DELIVERY_MODEL_MAX_BYTES) return unavailable("snapshot_too_large");
+    fields[key] = field.value;
+  }
+  const { kind, run, run_instance_id, captured_at, elapsed_ms, status, phase, cwd, evidence, evidence_error } = fields;
+  const scalar = (text: unknown): text is string => typeof text === "string" && text.length > 0 && Buffer.from(text).toString("utf8") === text;
+  const reference = (text: unknown): text is string => scalar(text) && !/[\u0000-\u001f\u007f]/u.test(text);
+  if (evidence !== null && !reference(evidence)) return unavailable("snapshot_invalid");
+  if (kind !== "run_snapshot" || !scalar(run) || /[^A-Za-z0-9_.-]/u.test(run) || !scalar(run_instance_id) || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(run_instance_id) ||
+    !scalar(captured_at) || !Number.isSafeInteger(Date.parse(captured_at)) || new Date(Date.parse(captured_at)).toISOString() !== captured_at ||
+    typeof elapsed_ms !== "number" || !Number.isSafeInteger(elapsed_ms) || elapsed_ms < 0 || (status !== "running" && status !== "done" && status !== "failed") ||
+    (phase !== undefined && (status !== "running" || phase !== "stopping")) || !reference(cwd) ||
+    (evidence === null ? evidence_error !== "index_unavailable" : evidence_error !== undefined)) return unavailable("snapshot_invalid");
+  const snapshot: Readonly<RunSnapshot> = Object.freeze({ kind, run, run_instance_id, captured_at, elapsed_ms, status,
+    ...(phase === "stopping" ? { phase } as const : {}), cwd, evidence,
+    ...(evidence === null ? { evidence_error: "index_unavailable" } as const : {}) });
+  // Compact JSON preserves the same bounded payload without a second pretty-print allowance or implicit fallback.
+  const json = JSON.stringify(snapshot);
+  if (Buffer.byteLength(json, "utf8") > Limits.RUN_DELIVERY_MODEL_MAX_BYTES) return unavailable("snapshot_too_large");
+  const text = format === "json" ? json
+    : `run:${snapshot.run} · ${snapshot.status}${snapshot.phase ? ` (${snapshot.phase})` : ""} · elapsed=${snapshot.elapsed_ms}ms\ngeneration:\n${formatLiteralBlock(snapshot.run_instance_id)}` +
+      `\ncaptured_at: ${snapshot.captured_at}\ncwd:\n${formatLiteralBlock(snapshot.cwd)}\nevidence:${snapshot.evidence === null ? " unavailable (index_unavailable)" : `\n${formatLiteralBlock(snapshot.evidence)}`}`;
+  return Buffer.byteLength(text, "utf8") > Limits.RUN_DELIVERY_MODEL_MAX_BYTES ? unavailable("render_too_large") : Object.freeze({ state: "available", text });
+}
 
 export function withLeadingLineBreak(text: string): string {
   return `\n${text.replace(/^\n+/, "")}`;
@@ -71,23 +206,31 @@ function formatFailureCount(value: unknown): number | undefined {
   return Array.isArray(value) ? value.length : undefined;
 }
 
-function compactPolicyAxis(label: string, value: unknown): string | undefined {
-  const axis = asRecord(value);
-  const source = typeof axis.source === "string" ? axis.source : undefined;
-  if (!source || source === "unused") return undefined;
-  const renderedValue =
-    typeof axis.value === "string" && axis.value.trim()
-      ? `:${axis.value.trim()}`
-      : "";
-  return `${label}=${source}${renderedValue}`;
+function launchModelPolicy(value: unknown): Record<string, unknown> {
+  const policy = asRecord(value), fields: Record<string, unknown> = {};
+  for (const key of ["model", "thinking"]) {
+    const axis = asRecord(policy[key]);
+    if (typeof axis.source !== "string" || !axis.source || axis.source === "unused") continue;
+    const source = axis.source;
+    // Retain legacy coercion/error behavior for unstable getter-produced values.
+    formatMarkdownField("source", source as string, 1);
+    const selected: Record<string, unknown> = { source };
+    if (typeof axis.value === "string" && axis.value.trim()) {
+      const text = axis.value.trim();
+      formatMarkdownField("value", text, 1);
+      selected.value = text;
+    }
+    fields[key] = Object.values(selected).every(field => typeof field === "string" && field.isWellFormed())
+      ? selected : { state: "unavailable", reason: "metadata_invalid" };
+  }
+  return fields;
 }
 
-function compactModelPolicy(value: unknown): string[] {
-  const policy = asRecord(value);
-  return [
-    compactPolicyAxis("model", policy.model),
-    compactPolicyAxis("thinking", policy.thinking),
-  ].filter((token): token is string => Boolean(token));
+const RUN_FILE_INVESTIGATION_COMMAND = "inspect target=runtime view=runs verbose=true";
+
+/** Frozen older completion-format text: new launch layout must not change this shared packet helper. */
+export function formatRunFileNavigationHandoff(): string {
+  return `Files (optional; current session):\n\`${RUN_FILE_INVESTIGATION_COMMAND}\``;
 }
 
 export function runNextActions(run: unknown): string[] {
@@ -97,42 +240,83 @@ export function runNextActions(run: unknown): string[] {
     `inspect target=run:${id} view=recipe`,
     `inspect target=run:${id} view=trace`,
     `inspect target=run:${id} view=control`,
+    RUN_FILE_INVESTIGATION_COMMAND,
   ];
 }
 
 export function compactAsyncRunStatus(value: unknown): string {
-  const status = asRecord(value);
-  const progress = asRecord(status.progress);
-  const result = asRecord(status.result);
-  const run = String(status.run ?? "<unknown>");
-  const tokens = [`run=${run}`, `status=${String(status.status ?? "unknown")}`];
-  if (status.launch_kind)
-    tokens.push(`launch_kind=${String(status.launch_kind)}`);
-  tokens.push(...compactModelPolicy(status.model_policy ?? progress.model_policy));
-  if (status.tool) tokens.push(`tool=${String(status.tool)}`);
-  if (status.recipe) tokens.push(`recipe=${String(status.recipe)}`);
-  if (status.retire_when)
-    tokens.push(`retire_when=${String(status.retire_when)}`);
-  if (Number(status.pid) > 0) tokens.push(`pid=${Number(status.pid)}`);
-  if (progress.phase && progress.phase !== status.status)
-    tokens.push(`phase=${String(progress.phase)}`);
-  if (Number(progress.activeSubagents) > 0)
-    tokens.push(`active=${Number(progress.activeSubagents)}`);
-  if (Number(progress.completed) > 0)
-    tokens.push(`completed=${Number(progress.completed)}`);
+  const status = asRecord(value), progress = asRecord(status.progress), result = asRecord(status.result);
+  const run = String(status.run ?? "<unknown>"), displayRun = run.startsWith("run:") ? run.slice(4) : run;
+  const core: Record<string, unknown> = { run: displayRun, state: String(status.status ?? "unknown") };
+  if (status.launch_kind) core.launch_kind = String(status.launch_kind);
+  if (status.reused === true) core.launch = "existing Run reused";
+  const catalog = asRecord(status.catalog_registration);
+  if (catalog.state === "unavailable" && catalog.reason === "catalog_registration_failed") core.catalog = "unavailable";
+  const fields: Record<string, unknown> = { ...core, ...launchModelPolicy(status.model_policy ?? progress.model_policy) };
+  for (const key of ["tool", "recipe", "retire_when"]) if (status[key]) fields[key] = String(status[key]);
+  if (Number(status.pid) > 0) fields.pid = Number(status.pid);
+  if (progress.phase && progress.phase !== status.status) fields.phase = String(progress.phase);
+  if (Number(progress.activeSubagents) > 0) fields.active_subagents = Number(progress.activeSubagents);
+  if (Number(progress.completed) > 0) fields.completed = Number(progress.completed);
   const failures = formatFailureCount(progress.failures);
-  if (failures !== undefined && failures > 0)
-    tokens.push(`failures=${failures}`);
-  if (result.code !== undefined) tokens.push(`code=${String(result.code)}`);
-  if (result.killed === true) tokens.push("killed=true");
-  const draftRecipe = status.draft_recipe;
-  if (draftRecipe) tokens.push(`draft_recipe=${String(draftRecipe)}`);
-  const nextActions = runNextActions(run);
-  if (nextActions.length > 0)
-    tokens.push(
-      `next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`,
-    );
-  return `\n${tokens.join(" ")}`;
+  if (failures !== undefined && failures > 0) fields.failures = failures;
+  if (result.code !== undefined) {
+    const code = result.code, text = String(code);
+    fields.code = typeof code === "number" || typeof code === "boolean" ? code : text;
+  }
+  if (result.killed === true) fields.killed = true;
+  if (status.draft_recipe) fields.draft_recipe = String(status.draft_recipe);
+  const hint = { file_investigation: "optional; current session", next: { tool: "inspect", target: "runtime", view: "runs", verbose: true } };
+  const hasNavigation = Object.hasOwn(status, "file_navigation");
+  let navigation: unknown;
+  if (hasNavigation) {
+    // Preserve the original JSON selection (including hooks and thrown errors), once only.
+    const json = JSON.stringify(status.file_navigation ?? { state: "unavailable", reason: "navigation_unavailable" });
+    if (json === undefined) formatLiteralBlock(json!);
+    navigation = JSON.parse(json!);
+  }
+  const direct = hasNavigation && asRecord(status.file_navigation).state === "available" && asRecord(navigation).state === "available";
+  const budget = Limits.RUN_DELIVERY_MODEL_MAX_BYTES - 1;
+  const render = (metadata: Record<string, unknown>): string | undefined => {
+    const rendered = renderYamlMetadata(metadata, budget);
+    return rendered.state === "available" ? withLeadingLineBreak(rendered.text) : undefined;
+  };
+  // Invalid selected scalars are unavailable whole values, never repaired strings/paths.
+  for (const group of [core, fields]) {
+    for (const key of Object.keys(group)) {
+      const field = group[key];
+      if ((typeof field === "string" && !field.isWellFormed()) ||
+        (typeof field === "number" && (!Number.isFinite(field) || Object.is(field, -0)))) {
+        group[key] = { state: "unavailable", reason: "metadata_invalid" };
+      }
+    }
+  }
+  // Validate only runtime-selected JSON facts, never walk the original navigation again.
+  const navigationRendering = hasNavigation ? renderYamlMetadata({ run_files: navigation }, budget) : undefined;
+  const invalidNavigation = navigationRendering?.state === "unavailable" && navigationRendering.reason === "metadata_invalid";
+  const locations = !hasNavigation ? {} : { run_files: invalidNavigation
+    ? { state: "unavailable", reason: "metadata_invalid" } : navigation,
+    run_files_observation: "Observed locations; mutable." };
+  const full = render({ ...fields, ...locations, ...(direct && !invalidNavigation ? {} : hint) });
+  if (full !== undefined) return full;
+  const omitted = !hasNavigation ? {} : { run_files: { state: "omitted", reason: "response_too_large", shown: 0, omitted: 1, total: 1 } };
+  const withoutRow = render({ ...fields, ...omitted, ...hint });
+  if (withoutRow !== undefined) return withoutRow;
+  // Keep the original fallback observation order; no rereads on successful full receipts.
+  const fallback = { ...core };
+  if (typeof status.run_instance_id === "string") {
+    const generation = status.run_instance_id;
+    formatMarkdownField("run_instance_id", generation as string);
+    fallback.run_instance_id = typeof generation === "string" && generation.isWellFormed()
+      ? generation : { state: "unavailable", reason: "metadata_invalid" };
+  }
+  if (Number(status.pid) > 0) {
+    const pid = Number(status.pid);
+    fallback.pid = Number.isFinite(pid) && !Object.is(pid, -0) ? pid : { state: "unavailable", reason: "metadata_invalid" };
+  }
+  const omission = { launch_fields: "omitted", launch_omission: "response_too_large" };
+  return render({ ...omission, ...fallback, ...omitted, ...hint }) ??
+    render({ ...omission, ...omitted, ...hint })!;
 }
 
 export function maybeJsonText(
@@ -143,6 +327,33 @@ export function maybeJsonText(
   return verbose ? jsonText(value) : compact;
 }
 
+function unavailableSpawnProjection(reason: "malformed_selected_text" | "yaml_projection_failed"): string {
+  return `projection: unavailable\nreason: ${reason}\nwarning: "Full metadata is not shown. Launch or attachment processing preceded this projection; this is not a workload-failure or no-effects receipt. Do not repeat automatically."\n`;
+}
+
+/** Full spawn metadata retains legacy JSON selection; projection is not launch or source authority. */
+export function spawnMetadataText(value: unknown, verbose: boolean | undefined, compact: string): string {
+  if (!verbose) return compact;
+  // Original selection faults remain exact, outside the recoverable projection boundary.
+  const selected = JSON.stringify(value, null, 2);
+  if (selected === undefined) return `\n${unavailableSpawnProjection("yaml_projection_failed")}`;
+  try {
+    const clone: unknown = JSON.parse(selected), pending: unknown[] = [clone];
+    // Only the JSON clone is walked; full metadata borrows no bounded emitter allowance.
+    while (pending.length) {
+      const current = pending.pop();
+      if (typeof current === "string" && !current.isWellFormed()) return `\n${unavailableSpawnProjection("malformed_selected_text")}`;
+      if (current && typeof current === "object") for (const [key, child] of Object.entries(current)) {
+        if (!key.isWellFormed()) return `\n${unavailableSpawnProjection("malformed_selected_text")}`;
+        pending.push(child);
+      }
+    }
+    return `\n${yamlMetadataText(clone)}`;
+  } catch {
+    return `\n${unavailableSpawnProjection("yaml_projection_failed")}`;
+  }
+}
+
 export function compactRecipeImports(summary: Record<string, unknown>): string {
   const active = Array.isArray(summary.active)
     ? (summary.active as Array<Record<string, unknown>>)
@@ -252,6 +463,14 @@ export function recipeRegistryNextActions(
   return [...new Set(actions)].slice(0, 4);
 }
 
+/** Only these existing read-only inspection hints become action nodes; other advice stays content. */
+export function formatInspectionHint(action: string): string {
+  if (action === "inspect target=recipes view=doctor") return formatInspectNextAction("recipes", "doctor");
+  if (action === "inspect target=recipes view=imports verbose=true") return formatInspectNextAction("recipes", "imports", true);
+  if (action === "inspect target=recipes view=summary verbose=true") return formatInspectNextAction("recipes", "summary", true);
+  return formatMarkdownField("instruction", action);
+}
+
 export function compactRecipeRegistry(
   summary: Record<string, unknown>,
 ): string {
@@ -279,7 +498,11 @@ export function compactRecipeRegistry(
   const nextActions = Array.isArray(summary.next_actions)
     ? (summary.next_actions as string[])
     : [];
-  return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} current_policy=${currentPolicy} skill_catalog_partial=${skillCatalogPartial} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
+  const fields = [formatMarkdownField("recipes", "registry"), ...Object.entries({ active, drafts, shadowed, invalid, disabled,
+    current_policy: currentPolicy, skill_catalog_partial: skillCatalogPartial, recommendations, diagnostics })
+    .map(([key, value]) => formatMarkdownField(key, String(value)))];
+  if (nextActions.length) fields.push(formatInspectionHint(nextActions[0]));
+  return "\n" + fields.join("\n");
 }
 
 export const DEFAULT_INSPECT_LINES = Limits.DEFAULT_INSPECT_LINES;

package/node_modules/@llblab/pi-actors/lib/tools-spawn.ts

@@ -9,22 +9,25 @@ import { join } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
 import { withFileMutationLock } from "./file-state.ts";
+import * as Limits from "./limits.ts";
 import * as ModelContext from "./model-context.ts";
 import * as Paths from "./paths.ts";
 import type * as RecipeResolution from "./recipes-context.ts";
-import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsResponse from "./tools-response.ts";
+import { readRunFileNavigationForContext } from "./tools-access.ts";
 
 export interface SpawnToolContext 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 };
 }
 
 const asRecord = ToolsResponse.asRecord;
-const maybeJsonText = ToolsResponse.maybeJsonText;
+const spawnMetadataText = ToolsResponse.spawnMetadataText;
 
 function getRunOwnerId(ctx: SpawnToolContext): string | undefined {
   return ctx.sessionManager?.getSessionId?.();
@@ -79,14 +82,33 @@ function writeSpawnDraftRecipe(
   return path;
 }
 
+/** Compiler-owned pre-launch diagnostics only; selected caller values are not admitted Run ids. */
+function spawnGuardText(kind: "state_dir" | "namespace" | "id", value?: string): string {
+  const field = ToolsResponse.formatMarkdownField;
+  const facts = kind === "state_dir"
+    ? [field("result", "unsupported field"), field("reason", "Run state is runtime-owned; run:<id> remains addressable and retention-safe.")]
+    : [field("result", kind === "namespace" ? "unsupported Run target" : "invalid Run target"), field("accepted_format", "run:<id>"),
+      ...(kind === "id" ? [field("id_rule", "nonempty ASCII letters, digits, underscore, dot or hyphen")] : [])];
+  const render = (selected?: string) => ToolsResponse.withLeadingLineBreak(
+    [field("field", kind === "state_dir" ? "state_dir" : "as"), ...(selected === undefined ? [] : [selected]), ...facts].join("\n"));
+  if (value === undefined) return render();
+  const wellFormed = value.isWellFormed();
+  if (wellFormed) {
+    const complete = render(field("value", value));
+    if (Buffer.byteLength(complete) <= Limits.RUN_DELIVERY_MODEL_MAX_BYTES) return complete;
+  }
+  const reason = wellFormed ? "response_too_large" : "malformed_selected_text";
+  return render(`- value: [${reason === "response_too_large" ? "omitted" : "unavailable"}]\n- value_omission:\n  - reason: ${reason}\n  - shown: 0\n  - omitted: 1\n  - total: 1`);
+}
+
 function runIdFromTarget(target: string | undefined): string | undefined {
   if (!target) return undefined;
   if (!target.startsWith("run:")) {
-    throw new Error(`spawn.as accepts only run:<id>; received: ${target}`);
+    throw new Error(spawnGuardText("namespace", `${target}`));
   }
   const run = target.slice(4);
   if (!run || !/^[A-Za-z0-9_.-]+$/.test(run)) {
-    throw new Error(`invalid spawn Run target: ${target}`);
+    throw new Error(spawnGuardText("id", `${target}`));
   }
   return run;
 }
@@ -127,7 +149,7 @@ export function createSpawnToolDefinition<
           "Optional originating transport route preserved for detached terminal follow-up, e.g. Telegram chat_id and thread_id.",
         ),
         verbose: Schema.booleanSchema(
-          "Return full JSON instead of compact text.",
+          "Return full YAML instead of compact text.",
         ),
       },
       [],
@@ -141,9 +163,7 @@ export function createSpawnToolDefinition<
     ) {
       const input = asRecord(params);
       if (input.state_dir !== undefined) {
-        throw new Error(
-          "spawn.state_dir is not supported; run state is runtime-owned so run:<id> remains addressable and retention-safe.",
-        );
+        throw new Error(spawnGuardText("state_dir"));
       }
       const runId = runIdFromTarget(
         typeof input.as === "string" ? input.as : undefined,
@@ -185,12 +205,13 @@ export function createSpawnToolDefinition<
             : {}),
         },
         ctx.cwd,
-        { skillContext: ctx.recipeResolutionContext?.activeSkills },
+        { skillContext: ctx.recipeResolutionContext?.activeSkills, onSupervisionClockCaptured: ctx.onSupervisionClockCaptured },
       );
       const draftRecipe = writeSpawnDraftRecipe(input, meta);
       const nextActions = ToolsResponse.runNextActions(meta.run);
       const details = {
         ...meta,
+        file_navigation: readRunFileNavigationForContext(meta, ctx),
         ...(draftRecipe ? { draft_recipe: draftRecipe } : {}),
         next_actions: nextActions,
       };
@@ -198,7 +219,7 @@ export function createSpawnToolDefinition<
         content: [
           {
             type: "text" as const,
-            text: maybeJsonText(
+            text: spawnMetadataText(
               details,
               input.verbose === true,
               ToolsResponse.compactAsyncRunStatus(details),