@llblab/pi-kit 0.38.3 → 0.39.0

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

@@ -1,9 +1,167 @@
 /**
- * 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.js";
+function yamlMetadataText(value) {
+    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, byteBudget) {
+    // 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";
+    const active = new Set();
+    const charge = (bytes) => {
+        remaining -= bytes;
+        if (remaining >= 0)
+            return true;
+        reason = "metadata_too_large";
+        return false;
+    };
+    const string = (text) => {
+        if (text.length > remaining) {
+            reason = "metadata_too_large";
+            return false;
+        }
+        return text.isWellFormed() && charge(Buffer.byteLength(text, "utf8"));
+    };
+    const copy = (input, depth) => {
+        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 = 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, value, depth = 0) {
+    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, view, verbose) {
+    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) {
+    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}`;
+}
+/** Pure formatting of already-admitted snapshots. DTO/schema validity is NOT source, timing, visibility or lifecycle authority. */
+export function renderRunSnapshot(value, format = "text") {
+    const unavailable = (reason) => 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 = 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) => typeof text === "string" && text.length > 0 && Buffer.from(text).toString("utf8") === text;
+    const reference = (text) => 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 = Object.freeze({ kind, run, run_instance_id, captured_at, elapsed_ms, status,
+        ...(phase === "stopping" ? { phase } : {}), cwd, evidence,
+        ...(evidence === null ? { evidence_error: "index_unavailable" } : {}) });
+    // 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) {
     return `\n${text.replace(/^\n+/, "")}`;
 }
@@ -58,22 +216,30 @@ export function compactNextActions(actions) {
 function formatFailureCount(value) {
     return Array.isArray(value) ? value.length : undefined;
 }
-function compactPolicyAxis(label, value) {
-    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) {
+    const policy = asRecord(value), fields = {};
+    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, 1);
+        const selected = { 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) {
-    const policy = asRecord(value);
-    return [
-        compactPolicyAxis("model", policy.model),
-        compactPolicyAxis("thinking", policy.thinking),
-    ].filter((token) => 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() {
+    return `Files (optional; current session):\n\`${RUN_FILE_INVESTIGATION_COMMAND}\``;
 }
 export function runNextActions(run) {
     const id = String(run ?? "").trim();
@@ -83,49 +249,132 @@ export function runNextActions(run) {
         `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) {
-    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")}`];
+    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 = { run: displayRun, state: 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)}`);
+        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 = { ...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)
-        tokens.push(`pid=${Number(status.pid)}`);
+        fields.pid = Number(status.pid);
     if (progress.phase && progress.phase !== status.status)
-        tokens.push(`phase=${String(progress.phase)}`);
+        fields.phase = String(progress.phase);
     if (Number(progress.activeSubagents) > 0)
-        tokens.push(`active=${Number(progress.activeSubagents)}`);
+        fields.active_subagents = Number(progress.activeSubagents);
     if (Number(progress.completed) > 0)
-        tokens.push(`completed=${Number(progress.completed)}`);
+        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)}`);
+        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)
-        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(" ")}`;
+        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;
+    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) => {
+        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);
+        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(value, verbose, compact) {
     return verbose ? jsonText(value) : compact;
 }
+function unavailableSpawnProjection(reason) {
+    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, verbose, compact) {
+    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 = JSON.parse(selected), pending = [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) {
     const active = Array.isArray(summary.active)
         ? summary.active
@@ -215,6 +464,16 @@ export function recipeRegistryNextActions(summary, view) {
     }
     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) {
+    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) {
     const active = Array.isArray(summary.active) ? summary.active.length : 0;
     const shadowed = Array.isArray(summary.shadowed)
@@ -238,6 +497,11 @@ export function compactRecipeRegistry(summary) {
     const nextActions = Array.isArray(summary.next_actions)
         ? summary.next_actions
         : [];
-    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/dist/lib/tools-spawn.d.ts

@@ -3,11 +3,14 @@
  * Zones: actor launch, draft recipe capture, launch diagnostics
  * Owns the public spawn execution path for run-backed actors
  */
+import * as AsyncRuns from "./async-runs.ts";
 import * as ModelContext from "./model-context.ts";
 import type * as RecipeResolution from "./recipes-context.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;
     };

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

@@ -7,13 +7,15 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import { withFileMutationLock } from "./file-state.js";
+import * as Limits from "./limits.js";
 import * as ModelContext from "./model-context.js";
 import * as Paths from "./paths.js";
 import * as RecipesUsage from "./recipes-usage.js";
 import * as Schema from "./schema.js";
 import * as ToolsResponse from "./tools-response.js";
+import { readRunFileNavigationForContext } from "./tools-access.js";
 const asRecord = ToolsResponse.asRecord;
-const maybeJsonText = ToolsResponse.maybeJsonText;
+const spawnMetadataText = ToolsResponse.spawnMetadataText;
 function getRunOwnerId(ctx) {
     return ctx.sessionManager?.getSessionId?.();
 }
@@ -48,15 +50,34 @@ function writeSpawnDraftRecipe(input, meta) {
     RecipesUsage.recordRecipeLaunch(path, new Date(), "spawn", Paths.getRecipeRoot());
     return path;
 }
+/** Compiler-owned pre-launch diagnostics only; selected caller values are not admitted Run ids. */
+function spawnGuardText(kind, value) {
+    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) => 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) {
     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;
 }
@@ -77,12 +98,12 @@ export function createSpawnToolDefinition() {
             ]),
             values: Schema.looseObjectSchema("Runtime placeholder values passed to the actor."),
             transport_context: Schema.looseObjectSchema("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."),
+            verbose: Schema.booleanSchema("Return full YAML instead of compact text."),
         }, []),
         async execute(toolCallId, params, _signal, _onUpdate, ctx) {
             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);
             const recipe = typeof input.file === "string"
@@ -111,11 +132,12 @@ export function createSpawnToolDefinition() {
                         artifacts: input.artifacts,
                     }
                     : {}),
-            }, ctx.cwd, { skillContext: ctx.recipeResolutionContext?.activeSkills });
+            }, ctx.cwd, { 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,
             };
@@ -123,7 +145,7 @@ export function createSpawnToolDefinition() {
                 content: [
                     {
                         type: "text",
-                        text: maybeJsonText(details, input.verbose === true, ToolsResponse.compactAsyncRunStatus(details)),
+                        text: spawnMetadataText(details, input.verbose === true, ToolsResponse.compactAsyncRunStatus(details)),
                     },
                 ],
                 details,

package/node_modules/@llblab/pi-actors/dist/lib/trace-projection.d.ts

@@ -4,19 +4,39 @@
  * Owns public Trace items; source journals and session parsing remain in their domains.
  */
 import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
+import * as RunsTrace from "./runs-trace.ts";
 export type TraceSource = "lifecycle" | "control" | "process" | "agent" | "artifact" | "runtime";
 export type TraceSourceFilter = TraceSource | "all";
 export declare const TRACE_ITEM_SEQUENCE: unique symbol;
+export declare const TRACE_ITEM_CHRONOLOGY: unique symbol;
+export type TraceChronologyReason = "history_incomplete" | "control_history_unproven" | "metadata_unavailable" | "metadata_private" | "metadata_too_large" | "metadata_ambiguous" | "timestamp_unavailable";
+export type TraceChronology = Readonly<{
+    basis: "recorded_observations";
+} & ({
+    state: "available";
+    ordinal: number;
+    total: number;
+} | {
+    state: "unavailable";
+    reason: TraceChronologyReason;
+})>;
 export interface TraceItem {
     id: string;
     ts: string;
     [TRACE_ITEM_SEQUENCE]?: number;
+    [TRACE_ITEM_CHRONOLOGY]?: TraceChronology;
     source: TraceSource;
     kind: string;
     summary: string;
     level?: "info" | "warning" | "error";
     detail: unknown;
 }
+/** Data-only canonical-journal projection; captured Recipe context supplies privacy, never lifecycle/work authority. */
+export declare function projectRunTraceJournal(read: RunsTrace.RunTraceJournalRead, options?: {
+    limit?: number;
+    recipe?: Record<string, unknown>;
+    redactEvidence?: (value: unknown) => unknown;
+}): TraceItem[];
 export declare function projectRunTrace(stateDir: string, options?: {
     artifacts?: Record<string, RunArtifactDeclaration>;
     limit?: number;