@llblab/pi-kit 0.1.5 → 0.1.7

package/node_modules/@llblab/pi-actors/dist/lib/run-ui-runtime.js

@@ -8,22 +8,78 @@ import * as Observability from "./observability.js";
 import * as Paths from "./paths.js";
 import * as Pi from "./pi.js";
 export function createRunUiRuntime(deps) {
+    let activeContext;
+    let activeOwnerId;
     let animationInterval;
     let notifyTimeout;
+    let running = false;
     let lastWatcherDiagnosticId = 0;
     const observation = Observability.createRunUiObservationState();
     const retirementAttempts = new Set();
     const terminalNotificationsInFlight = new Set();
+    const close = () => {
+        running = false;
+        activeContext = undefined;
+        activeOwnerId = undefined;
+        try {
+            watcher.close();
+        }
+        catch {
+            /* cleanup must not escape a host callback */
+        }
+        try {
+            reconciliation.close();
+        }
+        catch {
+            /* cleanup must not escape a host callback */
+        }
+        if (notifyTimeout)
+            clearTimeout(notifyTimeout);
+        notifyTimeout = undefined;
+        if (animationInterval)
+            clearInterval(animationInterval);
+        animationInterval = undefined;
+    };
+    const stopAfterCallbackFailure = (label, error, expectedContext) => {
+        if (activeContext !== expectedContext)
+            return;
+        close();
+        try {
+            deps.onCallbackError?.(error);
+        }
+        catch {
+            /* host callback containment must remain no-throw */
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+            expectedContext.ui.notify(`Actor ${label} failed: ${message}`, "error");
+        }
+        catch {
+            /* stale context or unavailable UI */
+        }
+    };
+    const runActiveCallback = (label, callback) => {
+        if (!running || !activeContext || !activeOwnerId)
+            return;
+        const ctx = activeContext;
+        try {
+            if (deps.getActiveContext() !== ctx)
+                return;
+            callback(ctx, activeOwnerId);
+        }
+        catch (error) {
+            stopAfterCallbackFailure(label, error, ctx);
+        }
+    };
     const retireCandidateRuns = (ctx, summary) => {
         void Observability.executeRunRetirements(summary, {
             attempted: retirementAttempts,
             cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
             notify: (message, level) => ctx.ui.notify(message, level),
             sendStop: async (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
-        });
+        }).catch((error) => stopAfterCallbackFailure("Run retirement callback", error, ctx));
     };
-    const update = (ctx, notify = false, terminalOnly = false) => {
-        const ownerId = deps.getRunOwnerId(ctx);
+    const update = (ctx, ownerId, notify = false, terminalOnly = false) => {
         const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
         ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
         if (!notify)
@@ -45,62 +101,55 @@ export function createRunUiRuntime(deps) {
         }
     };
     const scheduleUpdate = () => {
+        if (!running)
+            return;
         if (notifyTimeout)
             clearTimeout(notifyTimeout);
         notifyTimeout = setTimeout(() => {
-            const ctx = deps.getActiveContext();
-            if (!ctx)
-                return;
-            watcher.refresh();
-            update(ctx, true);
-            deps.onRunEvent();
-            reportDiagnostics(ctx);
-        }, 50);
+            runActiveCallback("Run watcher callback", (ctx, ownerId) => {
+                watcher.refresh();
+                update(ctx, ownerId, true);
+                deps.onRunEvent();
+                reportDiagnostics(ctx);
+            });
+        }, deps.notificationDelayMs ?? 50);
         notifyTimeout.unref?.();
     };
-    const watcher = Observability.createRunStateWatcher({
+    const watcher = (deps.createRunStateWatcher ?? Observability.createRunStateWatcher)({
         stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
         onChange: scheduleUpdate,
     });
-    const reconciliation = Observability.createRunTerminalReconciliationLoop({
+    const reconciliation = (deps.createRunTerminalReconciliationLoop ??
+        Observability.createRunTerminalReconciliationLoop)({
         onError: (error) => {
-            const ctx = deps.getActiveContext();
-            if (!ctx)
+            if (!running || !activeContext)
                 return;
-            const message = error instanceof Error ? error.message : String(error);
-            ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+            stopAfterCallbackFailure("terminal reconciliation callback", error, activeContext);
         },
         reconcile: () => {
-            const ctx = deps.getActiveContext();
-            if (!ctx)
-                return;
-            Observability.reconcileRunTerminalNotifications({
-                inFlight: terminalNotificationsInFlight,
-                ownerId: deps.getRunOwnerId(ctx),
-                sink: Pi.createNotificationSink(deps.pi, ctx),
-                state: observation,
-                includeAttention: true,
+            runActiveCallback("terminal reconciliation callback", (ctx, ownerId) => {
+                Observability.reconcileRunTerminalNotifications({
+                    inFlight: terminalNotificationsInFlight,
+                    ownerId,
+                    sink: Pi.createNotificationSink(deps.pi, ctx),
+                    state: observation,
+                    includeAttention: true,
+                });
+                reportDiagnostics(ctx);
             });
-            reportDiagnostics(ctx);
         },
-        refreshWatcher: () => watcher.refresh(),
+        refreshWatcher: () => {
+            if (running)
+                watcher.refresh();
+        },
     });
-    const close = () => {
-        watcher.close();
-        reconciliation.close();
-        if (notifyTimeout)
-            clearTimeout(notifyTimeout);
-        notifyTimeout = undefined;
-        if (animationInterval)
-            clearInterval(animationInterval);
-        animationInterval = undefined;
-    };
     return {
         close,
-        shutdown(eventReason, ctx) {
-            close();
-            const teardown = AsyncRuns.teardownRunsOwnedByParent(deps.getRunOwnerId(ctx), Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, { trigger: `session_shutdown:${eventReason}` });
-            if (teardown.failed === 0)
+        shutdown(eventReason, ownerId, ctx) {
+            if (!ownerId)
+                return;
+            const teardown = (deps.teardownRunsOwnedByParent ?? AsyncRuns.teardownRunsOwnedByParent)(ownerId, Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, { trigger: `session_shutdown:${eventReason}` });
+            if (teardown.failed === 0 || !ctx)
                 return;
             try {
                 ctx.ui.notify(`Actor shutdown teardown: killed=${teardown.killed} failed=${teardown.failed} skipped=${teardown.skipped} discovery_failed=${teardown.discoveryFailed}. Summary: ${teardown.summaryPath ?? "unavailable"}.`, "warning");
@@ -109,17 +158,25 @@ export function createRunUiRuntime(deps) {
                 /* stale shutdown context */
             }
         },
-        start(ctx) {
+        start(ctx, ownerId) {
             close();
-            Observability.primeRunAttentionState(observation, deps.getRunOwnerId(ctx));
-            update(ctx, true, true);
-            watcher.refresh();
-            reconciliation.start();
-            animationInterval = setInterval(() => {
-                if (deps.getActiveContext() === ctx)
-                    update(ctx);
-            }, 1000);
-            animationInterval.unref?.();
+            activeContext = ctx;
+            activeOwnerId = ownerId;
+            running = true;
+            try {
+                Observability.primeRunAttentionState(observation, ownerId);
+                update(ctx, ownerId, true, true);
+                watcher.refresh();
+                reconciliation.start();
+                animationInterval = setInterval(() => {
+                    runActiveCallback("status animation callback", (current, currentOwnerId) => update(current, currentOwnerId));
+                }, deps.animationIntervalMs ?? 1000);
+                animationInterval.unref?.();
+            }
+            catch (error) {
+                close();
+                throw error;
+            }
         },
     };
 }

package/node_modules/@llblab/pi-actors/dist/lib/runs-artifacts.js

@@ -3,8 +3,28 @@
  * Owns: artifact path template expansion and filesystem-backed artifact metadata.
  */
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { closeSync, fstatSync, openSync, readSync, } from "node:fs";
 import { substituteCommandTemplateToken } from "./command-templates.js";
+function hashArtifactFile(path) {
+    const fd = openSync(path, "r");
+    try {
+        const size = fstatSync(fd).size;
+        const hash = createHash("sha256");
+        const chunk = Buffer.allocUnsafe(64 * 1024);
+        let position = 0;
+        while (position < size) {
+            const bytesRead = readSync(fd, chunk, 0, Math.min(chunk.byteLength, size - position), position);
+            if (bytesRead === 0)
+                break;
+            hash.update(chunk.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+        return { sha256: hash.digest("hex"), size: position };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 export function resolveArtifactPaths(artifacts, values) {
     if (!artifacts)
         return undefined;
@@ -35,7 +55,7 @@ export function resolveArtifactManifest(artifacts) {
         if (!declaration?.path)
             continue;
         try {
-            const content = readFileSync(declaration.path);
+            const hashed = hashArtifactFile(declaration.path);
             manifest[name] = {
                 exists: true,
                 ...(declaration.kind ? { kind: declaration.kind } : {}),
@@ -46,8 +66,8 @@ export function resolveArtifactManifest(artifacts) {
                 ...(declaration.required !== undefined
                     ? { required: declaration.required }
                     : {}),
-                sha256: createHash("sha256").update(content).digest("hex"),
-                size: content.byteLength,
+                sha256: hashed.sha256,
+                size: hashed.size,
             };
         }
         catch {

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

@@ -63,7 +63,9 @@ export declare function createAutoToolsRuntime(deps: ToolRegistryRuntimeDeps): T
 export interface RecipeToolReloadWatcherDeps {
     exists?: (path: string) => boolean;
     getResolutionContext?: () => RecipeResolutionContext | undefined;
+    onCallbackError?: (error: unknown) => void;
     recipeRoot?: string;
+    reloadDelayMs?: number;
     watchPath?: typeof watch;
 }
 export declare function createRecipeToolReloadWatcher(runtime: Pick<ToolRegistryRuntime, "loadTools"> & Partial<Pick<ToolRegistryRuntime, "setWatchStatus">>, deps?: RecipeToolReloadWatcherDeps): RecipeToolReloadWatcher;

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

@@ -236,21 +236,41 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
         reloadTimeout = undefined;
         setWatchStatus("closed");
     };
+    const reportCallbackError = (error) => {
+        try {
+            deps.onCallbackError?.(error);
+        }
+        catch {
+            /* host callback containment must remain no-throw */
+        }
+    };
     const notifyFailure = (ctx) => {
         if (failureNotified)
             return;
         failureNotified = true;
         setWatchStatus("failed");
-        ctx.ui.notify("Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.", "warning");
+        try {
+            ctx.ui.notify("Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.", "warning");
+        }
+        catch (error) {
+            reportCallbackError(error);
+        }
     };
     const scheduleReload = (ctx) => {
         failureNotified = false;
         if (reloadTimeout)
             clearTimeout(reloadTimeout);
         reloadTimeout = setTimeout(() => {
-            runtime.loadTools(ctx, deps.getResolutionContext?.());
-            ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
-        }, 150);
+            reloadTimeout = undefined;
+            try {
+                runtime.loadTools(ctx, deps.getResolutionContext?.());
+                ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+            }
+            catch (error) {
+                notifyFailure(ctx);
+                reportCallbackError(error);
+            }
+        }, deps.reloadDelayMs ?? 150);
         reloadTimeout.unref?.();
     };
     const watchParent = (ctx, recipeRoot) => {

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

@@ -37,6 +37,7 @@ export interface SessionEvidence {
     turns: SessionEvidenceTurn[];
 }
 export interface SessionEvidenceReadOptions {
+    maxBytes?: number;
     maxTextChars?: number;
     maxToolCalls?: number;
     maxTurns?: number;

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

@@ -105,10 +105,11 @@ function toolCalls(message, maxTextChars, maxToolCalls) {
     }));
 }
 export function readSessionEvidence(path, options = {}) {
+    const maxBytes = Math.max(1, options.maxBytes ?? Limits.SESSION_EVIDENCE_MAX_BYTES);
     const maxTextChars = Math.max(1, options.maxTextChars ?? Limits.SESSION_EVIDENCE_TEXT_CHARS);
     const maxToolCalls = Math.max(1, options.maxToolCalls ?? Limits.SESSION_EVIDENCE_MAX_TOOL_CALLS);
     const maxTurns = Math.max(1, options.maxTurns ?? Limits.SESSION_EVIDENCE_MAX_TURNS);
-    const read = readJsonlFileResilient(path);
+    const read = readJsonlFileResilient(path, { maxBytes });
     const diagnostics = [...read.diagnostics];
     const header = read.records.find((entry) => entry.type === "session");
     const branch = activeBranch(read.records, path, diagnostics);
@@ -198,7 +199,7 @@ export function readSessionEvidence(path, options = {}) {
         path,
         ...(header ? { session: asRecord(header) } : {}),
         totalTurns: turns.length,
-        truncated: turns.length > visibleTurns.length,
+        truncated: read.truncated === true || turns.length > visibleTurns.length,
         turns: visibleTurns,
     };
 }

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

@@ -15,7 +15,11 @@ export interface JsonReadResult<T> {
 export interface JsonlReadResult<T> {
     diagnostics: StateReadDiagnostic[];
     records: T[];
+    truncated?: boolean;
+}
+export interface JsonlReadOptions {
+    maxBytes?: number;
 }
 export declare function readJsonFileResilient<T>(path: string, fallback: T): JsonReadResult<T>;
-export declare function readJsonlFileResilient<T>(path: string): JsonlReadResult<T>;
+export declare function readJsonlFileResilient<T>(path: string, options?: JsonlReadOptions): JsonlReadResult<T>;
 export declare function formatStateReadDiagnostics(diagnostics: StateReadDiagnostic[], limit?: number): string[];

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

@@ -3,13 +3,37 @@
  * Zones: file-backed actor state, JSON/JSONL diagnostics, inspect safety
  * Owns best-effort JSON and JSONL parsing helpers for operator-facing state reads.
  */
-import { readFileSync } from "node:fs";
+import { closeSync, fstatSync, openSync, readFileSync, readSync, } from "node:fs";
 function isEnoent(error) {
     return error.code === "ENOENT";
 }
 function diagnosticMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function readTextFileCapped(path, maxBytes) {
+    if (maxBytes === undefined)
+        return readFileSync(path, "utf8");
+    const limit = Math.max(0, Math.floor(maxBytes));
+    const fd = openSync(path, "r");
+    try {
+        const size = fstatSync(fd).size;
+        if (size > limit) {
+            throw Object.assign(new Error(`file exceeds bounded read limit (${size} > ${limit} bytes)`), { code: "EFBIG" });
+        }
+        const content = Buffer.allocUnsafe(size);
+        let offset = 0;
+        while (offset < size) {
+            const bytesRead = readSync(fd, content, offset, size - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        return content.subarray(0, offset).toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 export function readJsonFileResilient(path, fallback) {
     try {
         return {
@@ -31,11 +55,11 @@ export function readJsonFileResilient(path, fallback) {
         };
     }
 }
-export function readJsonlFileResilient(path) {
+export function readJsonlFileResilient(path, options = {}) {
     try {
         const records = [];
         const diagnostics = [];
-        const lines = readFileSync(path, "utf8").split("\n");
+        const lines = readTextFileCapped(path, options.maxBytes).split("\n");
         for (const [index, line] of lines.entries()) {
             if (!line.trim())
                 continue;
@@ -63,6 +87,9 @@ export function readJsonlFileResilient(path) {
                 },
             ],
             records: [],
+            ...(error.code === "EFBIG"
+                ? { truncated: true }
+                : {}),
         };
     }
 }

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

@@ -16,4 +16,5 @@ export declare function sessionMismatchError(input: {
     run?: string;
     target?: string;
 }): Error;
+export declare function assertRunStatusAccessibleToContext(runId: string, status: Record<string, unknown>, ctx: unknown): Record<string, unknown>;
 export declare function assertRunAccessibleToContext(runId: string, ctx: unknown): Record<string, unknown>;

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

@@ -10,7 +10,7 @@ export function getContextSessionId(ctx) {
 export function requireContextSessionId(ctx, actor) {
     const sessionId = getContextSessionId(ctx);
     if (!sessionId) {
-        throw new Error(`${actor} requires a current coordinator session; use session:<id> or session:all for explicit session inventory.`);
+        throw Object.assign(new Error(`${actor} reason=session_unavailable requires a current coordinator session; retry from an active coordinator session.`), { reason: "session_unavailable" });
     }
     return sessionId;
 }
@@ -18,27 +18,29 @@ export function sessionMismatchError(input) {
     const ownerSession = input.expectedSession ?? "none";
     const currentSession = input.currentSession ?? "none";
     const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
-    const hintTarget = input.expectedSession
-        ? `session:${input.expectedSession}`
-        : "session:all";
-    return Object.assign(new Error(`${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`), {
+    return Object.assign(new Error(`${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_runtime_runs`), {
         current_session: input.currentSession,
-        hint: `inspect target=${hintTarget} view=status`,
+        hint: "inspect target=runtime view=runs",
         owner_session: input.expectedSession,
         reason: "session_mismatch",
         run: input.run,
         target: input.target,
     });
 }
-export function assertRunAccessibleToContext(runId, ctx) {
-    const status = AsyncRuns.getRunStatus(runId);
-    const sessionId = getContextSessionId(ctx);
-    if (sessionId && status.ownerId && status.ownerId !== sessionId) {
+export function assertRunStatusAccessibleToContext(runId, status, ctx) {
+    const sessionId = requireContextSessionId(ctx, `run:${runId}`);
+    const ownerId = typeof status.ownerId === "string" && status.ownerId
+        ? status.ownerId
+        : undefined;
+    if (ownerId !== sessionId) {
         throw sessionMismatchError({
             currentSession: sessionId,
-            expectedSession: String(status.ownerId),
+            expectedSession: ownerId,
             run: runId,
         });
     }
     return status;
 }
+export function assertRunAccessibleToContext(runId, ctx) {
+    return assertRunStatusAccessibleToContext(runId, AsyncRuns.getRunStatus(runId), ctx);
+}

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

@@ -27,14 +27,14 @@ const asRecord = ToolsResponse.asRecord;
 const maybeJsonText = ToolsResponse.maybeJsonText;
 function runtimeStatus() {
     return {
-        automatic_review: process.env.PI_ACTORS_AUTOMATIC_REVIEW !== "off",
+        automatic_review: Paths.isAutomaticRecipeReviewEnabled(),
         run_root: Paths.getRunStateRoot(),
         state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
         version: RuntimeIdentity.getPackageVersion(),
     };
 }
 function runtimeRuns(ctx, deps, status) {
-    const session = ToolsAccess.getContextSessionId(ctx);
+    const session = ToolsAccess.requireContextSessionId(ctx, "runtime Run inventory");
     const listed = deps.listRuns
         ? deps.listRuns()
         : AsyncRuns.listRuns(undefined, status);
@@ -49,8 +49,8 @@ function runtimeRuns(ctx, deps, status) {
             return run;
         }
     })
-        .filter((run) => !session || !run.ownerId || run.ownerId === session);
-    return { ...(session ? { owner_session: session } : {}), runs };
+        .filter((run) => run.ownerId === session);
+    return { owner_session: session, runs };
 }
 function runtimeTriage(ctx, deps) {
     const inventory = runtimeRuns(ctx, deps, undefined);
@@ -354,7 +354,7 @@ function inspectRun(run, view, input, ctx, deps) {
         throw new Error("inspect run:<id> supports view=recipe, view=trace, or view=control.");
     }
     const status = deps.getRunStatus
-        ? deps.getRunStatus(run)
+        ? ToolsAccess.assertRunStatusAccessibleToContext(run, deps.getRunStatus(run), ctx)
         : ToolsAccess.assertRunAccessibleToContext(run, ctx);
     const stateDir = String(status.state_dir);
     if (view === "recipe") {

package/node_modules/@llblab/pi-actors/dist/lib/tools-message.d.ts

@@ -4,6 +4,7 @@
  * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */
 export interface ControlToolDeps {
+    getRunStatus?: (run: string) => Record<string, unknown>;
     handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;
 }
 export declare function createControlToolDefinition<TContext = unknown>(deps?: ControlToolDeps): any;

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

@@ -67,7 +67,9 @@ export function createControlToolDefinition(deps = {}) {
             }
             else {
                 const run = request.target.slice(4);
-                const status = ToolsAccess.assertRunAccessibleToContext(run, ctx);
+                const status = deps.getRunStatus
+                    ? ToolsAccess.assertRunStatusAccessibleToContext(run, deps.getRunStatus(run), ctx)
+                    : ToolsAccess.assertRunAccessibleToContext(run, ctx);
                 const runInstanceId = typeof status.run_instance_id === "string"
                     ? status.run_instance_id
                     : undefined;

package/node_modules/@llblab/pi-actors/docs/README.md

@@ -8,6 +8,7 @@ Living index of all documentation in the `/docs` directory.
 - [template-recipes.md](./template-recipes.md) — Saved JSON/Markdown recipe standard, imports, and reusable command-template graph composition
 - [async-runs.md](./async-runs.md) — Run lifecycle, state, Control, Trace, cancellation, and terminal reconciliation
 - [actor-inspector.md](./actor-inspector.md) — Owner-filtered actor-instance navigation through Recipe, Trace, and Control
+- [inspection.md](./inspection.md) — Complete `inspect` target/view matrix, authorization boundaries, and diagnostic routes
 - [tool-registry.md](./tool-registry.md) — Local `pi-actors` registry storage and `register_tool` adaptation
 - [recipe-library.md](./recipe-library.md) — Packaged standard recipe library such as async subagents, coordinator pipelines, utilities, and music playback
 - [releasing.md](./releasing.md) — Guarded tag validation, npm Trusted Publisher setup, registry verification, and GitHub Release convergence

package/node_modules/@llblab/pi-actors/docs/actor-inspector.md

@@ -19,13 +19,13 @@ Shows captured execution provenance:
 - declared artifacts and actor-local actions;
 - model/thinking policy and launch source.
 
-Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes. Skill components display logical identities such as `artifacts/report`; private physical `source_file`, `skill_dir`, and `recipe_dir` stay out of Inspector and model-facing views. Non-empty object values render as indented brace-delimited property lists rather than flattened inline strings.
+Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes. Skill components display logical identities such as `artifacts/report`; private physical `source_file`, `skill_dir`, and `recipe_dir` stay out of Inspector and model-facing views. Non-empty objects render as indented brace-delimited property lists. Complex arrays use compact zero-based entries such as `#0: {` rather than Markdown list markers.
 
 ## Trace
 
-Shows the unified bounded Trace projection. Sources include lifecycle/runtime observations, Controls, owned Pi turns, command-log tails, results, artifacts, and diagnostics. Filter by source and open a row for structured detail.
+Shows the unified bounded Trace projection. Sources include lifecycle/runtime observations, Controls, owned Pi turns, command-log tails, results, artifacts, and diagnostics. The source selector displays only `all` plus sources present in the current projection from `lifecycle`, `control`, `process`, `agent`, `artifact`, and `runtime`. Select a row to open structured detail.
 
-Trace ordering stays deterministic and newest-first: timestamp descending, same-source physical ordinal descending, fixed internal source rank, then stable id. Internal ordinals are never displayed or interpreted as cross-source causality. Row numbers still read chronologically from bottom to top: the oldest visible event is `#1` and the newest carries the highest number. The summary states whether retained history is complete; `runtime.trace_compacted` means older history was discarded and shows bounded cumulative drop evidence. Terminal/result/execution/artifact evidence keeps its own authority. The projection applies path containment and redaction before rendering.
+Trace ordering stays deterministic and newest-first: timestamp descending, same-source physical ordinal descending, fixed internal source rank, then stable id. Internal ordinals are never displayed or interpreted as cross-source causality. Row numbers are zero-based chronological identities even though display is newest-first: the oldest visible event is `#0` and the newest carries the highest number. The summary states whether retained history is complete; `runtime.trace_compacted` means older history was discarded and shows bounded cumulative drop evidence. Terminal/result/execution/artifact evidence keeps its own authority. The projection applies path containment and redaction before rendering.
 
 ## Control
 
@@ -39,12 +39,28 @@ Shows:
 
 A service endpoint counts as ready only when `control-endpoint.json` matches the Run's immutable `run_instance_id`. Capacity reaches zero at 64 pending Controls; further requests are rejected before admission, while admitted nonterminal Controls never expire automatically. Runtime-owned kill remains available for a stuck saturated Run. Recent Control input and errors use the same bounded structured redaction as tool inspection. The durable `controls.jsonl` journal remains raw and local; rendering never mutates it or attaches an unredacted copy.
 
+## Focus and Selectors
+
+`selectedBg` marks the current focus or selection; `customMessageBg` remains reserved for alternating content stripes. Opening the Run or Trace-source selector preserves `selectedBg` on its parent control, so focus reads as parent → child menu → selected option. Menus are composited over only their bounded rectangle; base content before, beside, and below that rectangle remains rendered.
+
+The Run selector uses aligned zero-based sequence, Run name, and semantic status columns. The Trace selector uses `Trace: <source>`; when a non-`all` source is active, the tab projects the same colon grammar and value color.
+
 ## Keys
 
-The footer displays current bindings. Use tab navigation to switch Recipe/Trace/Control, movement keys to select rows, detail navigation to inspect evidence, refresh to reconcile disk state, and the documented kill key for lifecycle termination.
+The footer is authoritative for the current focus. The stable navigation contract is:
+
+| Focus | Keys |
+| --- | --- |
+| Run control | `←`/`→` change Run, `↓` enters tabs, `Enter` opens the Run selector, `k` requests kill when available |
+| Tabs | `←`/`→` or `Tab` changes tab, `↑` returns to Run, `↓` enters content, `Enter` opens content or the Trace-source selector |
+| Trace tab | `f` cycles present sources without opening the selector |
+| List/document/detail | `↑`/`↓` and `PgUp`/`PgDn` navigate; `→`/`Enter` opens a Trace row; `←` or `Esc` moves back |
+| Selector | `↑`/`↓` chooses, `Enter`/`→` applies, `←`/`Esc` cancels |
+| Kill confirmation | `←`/`→` or `Tab` chooses, `Enter`/`y` confirms, `Esc`/`n` cancels |
+| Overlay | `Esc` closes from the top level; `Ctrl-C` closes immediately |
 
 Run kill revalidates owner and generation through the canonical lifecycle path. After success, the Run status header is the sole confirmation; the content area does not duplicate it. The Inspector never edits state directly and never derives authority from displayed data.
 
 ## Scope
 
-The Actor Inspector treats each Run as a concrete actor instance. It does not expose group conversations, peer addresses, routing, or communication topology. Use `inspect target=runtime view=status`, `inspect target=recipes view=status`, and `inspect target=tool:<name> view=status` for non-Run management targets.
+The Actor Inspector treats each Run as a concrete actor instance. It does not expose group conversations, peer addresses, routing, or communication topology. Use `inspect target=runtime view=status|runs|triage`, `inspect target=recipes view=status|summary|doctor|imports|reviews`, and `inspect target=tool:<name> view=status|schema` for non-Run management targets. See [Management Inspection](./inspection.md) for exact applicability and authorization boundaries.