@llblab/pi-kit 0.38.3 → 0.39.0

package/node_modules/@llblab/pi-actors/lib/session-evidence.ts

@@ -27,7 +27,18 @@ export interface SessionEvidenceToolCall {
   resultError?: boolean;
 }
 
+// Non-JSON provenance data. The enumerable Symbol survives turn copies; it grants no source/lifecycle authority.
+export const SESSION_TURN_IDENTITY = Symbol("session-turn-identity");
+interface SessionTurnIdentity {
+  basis: "entry" | "record";
+  entryId?: string;
+  sessionId?: string;
+  role: "assistant" | "user";
+  ordinal?: number;
+}
+
 export interface SessionEvidenceTurn {
+  [SESSION_TURN_IDENTITY]?: Readonly<SessionTurnIdentity>;
   assistantEntryId?: string;
   assistantText?: string;
   error?: string;
@@ -44,7 +55,20 @@ export interface SessionEvidenceTurn {
   userText?: string;
 }
 
+export const SESSION_EVIDENCE_CHRONOLOGY = Symbol("session-evidence-chronology");
+export interface SessionChronologyEntry {
+  ordinal: number;
+  timestamp: string;
+  identity: Readonly<SessionTurnIdentity>;
+}
+export type SessionChronologyReason = "source_unavailable" | "identity_unavailable" | "timestamp_unavailable" | "metadata_too_large";
+export type SessionChronology = Readonly<{
+  basis: "recorded_branch_metadata";
+  entries: readonly Readonly<SessionChronologyEntry>[];
+} & ({ state: "available" } | { state: "unavailable"; reason: SessionChronologyReason })>;
+
 export interface SessionEvidence {
+  [SESSION_EVIDENCE_CHRONOLOGY]?: SessionChronology;
   activeLeafId?: string;
   diagnostics: StateReadDiagnostic[];
   path: string;
@@ -289,7 +313,8 @@ function contentText(
   return boundedText(text, maxChars);
 }
 
-function activeBranch(
+/** Physical last-leaf ancestry, not current model context or a claim about a live SessionManager leaf. */
+export function selectLastRecordedSessionBranch(
   entries: SessionEntry[],
   path: string,
   diagnostics: StateReadDiagnostic[],
@@ -345,6 +370,28 @@ function toolCalls(
     }));
 }
 
+function sessionChronology(turns: readonly SessionEvidenceTurn[], sourceAvailable: boolean): SessionChronology {
+  const basis = "recorded_branch_metadata" as const;
+  const unavailable = (reason: SessionChronologyReason): SessionChronology => Object.freeze({
+    state: "unavailable", basis, reason, entries: Object.freeze([]),
+  });
+  if (!sourceAvailable) return unavailable("source_unavailable");
+  const entries: Readonly<SessionChronologyEntry>[] = [];
+  let bytes = Buffer.byteLength(JSON.stringify({ state: "available", basis, entries: [] }));
+  for (const turn of turns) {
+    const identity = turn[SESSION_TURN_IDENTITY];
+    if (identity?.basis !== "entry") return unavailable("identity_unavailable");
+    const timestamp = turn.timestamp;
+    if (typeof timestamp !== "string" || timestamp.length !== 24 || !Number.isFinite(Date.parse(timestamp)) ||
+      new Date(timestamp).toISOString() !== timestamp || redactSessionEvidenceValue(timestamp) !== timestamp) return unavailable("timestamp_unavailable");
+    const entry = Object.freeze({ ordinal: turn.index, timestamp, identity });
+    bytes += Buffer.byteLength(JSON.stringify(entry)) + Number(entries.length > 0);
+    if (bytes > Limits.SESSION_EVIDENCE_MAX_BYTES) return unavailable("metadata_too_large");
+    entries.push(entry);
+  }
+  return Object.freeze({ state: "available", basis, entries: Object.freeze(entries) });
+}
+
 export function readSessionEvidence(
   path: string,
   options: SessionEvidenceReadOptions = {},
@@ -368,9 +415,27 @@ export function readSessionEvidence(
   const read = readJsonlFileResilient<SessionEntry>(path, { maxBytes });
   const diagnostics = [...read.diagnostics];
   const header = read.records.find((entry) => entry.type === "session");
-  const branch = activeBranch(read.records, path, diagnostics);
+  const branch = selectLastRecordedSessionBranch(read.records, path, diagnostics);
+  const ordinals = new Map<SessionEntry, number>(branch.map(entry => [entry, 0]));
+  const idCounts = new Map(branch.map(entry => [String(entry.id), 0]));
+  let sessionHeaders = 0;
+  for (const [index, entry] of read.records.entries()) {
+    if (entry.type === "session") sessionHeaders++;
+    if (ordinals.has(entry)) ordinals.set(entry, index + 1);
+    if (entry.type !== "session" && typeof entry.id === "string" && idCounts.has(entry.id)) {
+      idCounts.set(entry.id, idCounts.get(entry.id)! + 1);
+    }
+  }
+  const sessionId = sessionHeaders === 1 && typeof header?.id === "string" && header.id &&
+    redactSessionEvidenceValue(header.id, maxTextChars) === header.id ? header.id : undefined;
+  const identity = (entry: SessionEntry, role: "assistant" | "user"): Readonly<SessionTurnIdentity> => {
+    const entryId = typeof entry.id === "string" ? entry.id : "";
+    const basis = sessionId && entryId && idCounts.get(entryId) === 1 && diagnostics.length === 0 &&
+      redactSessionEvidenceValue(entryId, maxTextChars) === entryId ? "entry" : "record";
+    return Object.freeze({ basis, role, ...(basis === "entry" ? { sessionId, entryId } : { ordinal: ordinals.get(entry)! }) });
+  };
   const turns: SessionEvidenceTurn[] = [];
-  let pendingUser: { id: string; text?: string } | undefined;
+  let pendingUser: { id: string; text?: string; identity: Readonly<SessionTurnIdentity> } | undefined;
   let currentTurn: SessionEvidenceTurn | undefined;
   for (const entry of branch) {
     if (entry.type !== "message") continue;
@@ -379,6 +444,7 @@ export function readSessionEvidence(
     if (role === "user") {
       pendingUser = {
         id: String(entry.id),
+        identity: identity(entry, "user"),
         text: contentText(message, "text", maxTextChars),
       };
       currentTurn = undefined;
@@ -386,6 +452,7 @@ export function readSessionEvidence(
     }
     if (role === "assistant") {
       currentTurn = {
+        [SESSION_TURN_IDENTITY]: identity(entry, "assistant"),
         ...(typeof entry.id === "string" ? { assistantEntryId: entry.id } : {}),
         ...(contentText(message, "text", maxTextChars)
           ? { assistantText: contentText(message, "text", maxTextChars) }
@@ -440,6 +507,7 @@ export function readSessionEvidence(
       toolCalls: [],
       unmatchedToolResults: 0,
       userEntryId: pendingUser.id,
+      [SESSION_TURN_IDENTITY]: pendingUser.identity,
       ...(pendingUser.text ? { userText: pendingUser.text } : {}),
     });
   }
@@ -448,7 +516,7 @@ export function readSessionEvidence(
     ...turn,
     index: firstVisibleIndex + index + 1,
   }));
-  return {
+  const evidence: SessionEvidence = {
     ...(branch.at(-1)?.id ? { activeLeafId: String(branch.at(-1)?.id) } : {}),
     diagnostics,
     path,
@@ -457,4 +525,8 @@ export function readSessionEvidence(
     truncated: read.truncated === true || turns.length > visibleTurns.length,
     turns: visibleTurns,
   };
+  Object.defineProperty(evidence, SESSION_EVIDENCE_CHRONOLOGY, {
+    value: sessionChronology(turns, sessionId !== undefined && read.truncated !== true && diagnostics.length === 0),
+  });
+  return evidence;
 }

package/node_modules/@llblab/pi-actors/lib/state-readers.ts

@@ -6,6 +6,7 @@
 
 import {
   closeSync,
+  constants,
   fstatSync,
   openSync,
   readFileSync,
@@ -41,12 +42,14 @@ function diagnosticMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function readTextFileCapped(path: string, maxBytes: number | undefined): string {
-  if (maxBytes === undefined) return readFileSync(path, "utf8");
+function readTextFileCapped(path: string, maxBytes: number | undefined, strictUtf8 = false): string {
+  if (maxBytes === undefined) return strictUtf8 ? new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path)) : readFileSync(path, "utf8");
   const limit = Math.max(0, Math.floor(maxBytes));
-  const fd = openSync(path, "r");
+  const fd = openSync(path, strictUtf8 ? constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0) : "r");
   try {
-    const size = fstatSync(fd).size;
+    const opened = fstatSync(fd);
+    if (strictUtf8 && !opened.isFile()) throw new Error("bounded strict read requires a regular file");
+    const size = opened.size;
     if (size > limit) {
       throw Object.assign(
         new Error(`file exceeds bounded read limit (${size} > ${limit} bytes)`),
@@ -60,17 +63,23 @@ function readTextFileCapped(path: string, maxBytes: number | undefined): string
       if (bytesRead === 0) break;
       offset += bytesRead;
     }
-    return content.subarray(0, offset).toString("utf8");
+    if (strictUtf8 && offset !== size) throw new Error("file ended before its bounded strict read completed");
+    const observed = content.subarray(0, offset);
+    return strictUtf8 ? new TextDecoder("utf-8", { fatal: true }).decode(observed) : observed.toString("utf8");
   } finally {
     closeSync(fd);
   }
 }
 
-export function readJsonFileResilient<T>(path: string, fallback: T): JsonReadResult<T> {
+export function readJsonFileResilient<T>(
+  path: string,
+  fallback: T,
+  options: { maxBytes?: number; strictUtf8?: boolean } = {},
+): JsonReadResult<T> {
   try {
     return {
       diagnostics: [],
-      value: JSON.parse(readFileSync(path, "utf8")) as T,
+      value: JSON.parse(readTextFileCapped(path, options.maxBytes, options.strictUtf8)) as T,
     };
   } catch (error) {
     if (isEnoent(error)) return { diagnostics: [], value: fallback };

package/node_modules/@llblab/pi-actors/lib/temp.ts

@@ -1,14 +1,13 @@
 /**
  * Extension temp-directory helpers
  * Zones: temp directory, cleanup, runtime files
- * Owns pi-agent tmp directory preparation and stale-entry cleanup
+ * Owns ordinary pi-agent tmp directory preparation and stale-entry cleanup; Run retirement is separate.
  */
 
-import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 
 export const DEFAULT_TEMP_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-export const DEFAULT_RUN_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 
 export async function cleanupStaleTempEntries(
   tempDir: string,
@@ -38,62 +37,10 @@ export async function cleanupStaleTempEntries(
   return removed;
 }
 
-function isPidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function isRunEntryAlive(path: string): Promise<boolean> {
-  try {
-    const raw = await readFile(join(path, "run.json"), "utf8");
-    const meta = JSON.parse(raw) as Record<string, unknown>;
-    const pid = Number(meta.pid || 0);
-    return pid > 0 && isPidAlive(pid);
-  } catch {
-    return false;
-  }
-}
-
-export async function cleanupStaleRunEntries(
-  runsDir: string,
-  maxAgeMs = DEFAULT_RUN_MAX_AGE_MS,
-  now = Date.now(),
-): Promise<number> {
-  let entries: Array<{ name: string; isDirectory(): boolean }>;
-  let removed = 0;
-  try {
-    entries = await readdir(runsDir, { withFileTypes: true });
-  } catch {
-    return 0;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const path = join(runsDir, entry.name);
-    try {
-      const info = await stat(path);
-      const timestamp = Math.min(info.birthtimeMs || info.mtimeMs, info.mtimeMs);
-      if (now - timestamp <= maxAgeMs) continue;
-      if (await isRunEntryAlive(path)) continue;
-      await rm(path, { force: true, recursive: true });
-      removed += 1;
-    } catch {
-      // Ignore temp cleanup races.
-    }
-  }
-  return removed;
-}
-
 export async function prepareExtensionTempDir(
   tempDir: string,
   maxAgeMs = DEFAULT_TEMP_MAX_AGE_MS,
-  runMaxAgeMs = DEFAULT_RUN_MAX_AGE_MS,
 ): Promise<number> {
   await mkdir(tempDir, { recursive: true });
-  const removedTemp = await cleanupStaleTempEntries(tempDir, maxAgeMs);
-  const removedRuns = await cleanupStaleRunEntries(join(tempDir, "runs"), runMaxAgeMs);
-  return removedTemp + removedRuns;
+  return cleanupStaleTempEntries(tempDir, maxAgeMs);
 }

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

@@ -5,6 +5,7 @@
  */
 
 import * as AsyncRuns from "./async-runs.ts";
+import * as RunIndex from "./runs-index.ts";
 
 export interface SessionContext {
   sessionManager?: { getSessionId?: () => string };
@@ -14,6 +15,18 @@ export function getContextSessionId(ctx: unknown): string | undefined {
   return (ctx as SessionContext | undefined)?.sessionManager?.getSessionId?.();
 }
 
+/** Optional post-launch navigation never fails or rolls back work already admitted by the launch owner. */
+export function readRunFileNavigationForContext(status: object, ctx: unknown): Readonly<RunIndex.RunDirectoryNavigation> {
+  try {
+    const sessionId = getContextSessionId(ctx);
+    const directory = Object.getOwnPropertyDescriptor(status, "state_dir");
+    const navigation = RunIndex.readRunDirectoryNavigation(typeof directory?.value === "string" ? directory.value : "", status, sessionId);
+    return getContextSessionId(ctx) === sessionId ? navigation : Object.freeze({ state: "unavailable", reason: "session_changed" });
+  } catch {
+    return Object.freeze({ state: "unavailable", reason: "navigation_unavailable" });
+  }
+}
+
 export function requireContextSessionId(ctx: unknown, actor: string): string {
   const sessionId = getContextSessionId(ctx);
   if (!sessionId) {

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

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