@llblab/pi-actors 0.49.2 → 0.51.0

package/AGENTS.md

@@ -84,7 +84,7 @@ Canonical event:
 {"id":"…","ts":"…","kind":"…","summary":"…","data":{},"level":"info","attention":"notify"}
 ```
 
-Trace is a bounded retained suffix, not an audit archive. Every first-party writer must call `appendRunTraceEvent`; under the canonical token-owned lock it appends within both fixed bounds or atomically retains the newest suffix plus one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; terminal/result/execution/artifact files remain authoritative independently. Reads are newline-safe and order equal timestamps by same-source ordinal, fixed source rank, then stable id without exposing ordering metadata. Never write `trace.jsonl` directly. Persist durable state or an artifact before attention; `attention: "followup"` remains rare.
+Trace is a bounded retained suffix, not an audit archive. Every first-party writer must call `appendRunTraceEvent`; under the canonical token-owned lock it appends within both fixed bounds or atomically retains the newest suffix plus one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; terminal/result/execution/artifact files remain authoritative independently. Reads are newline-safe and order equal timestamps by same-source ordinal, fixed source rank, then stable id without exposing ordering metadata. Never write `trace.jsonl` directly. Generic command lifecycle is Trace-only: `command.done` preserves complete bounded execution evidence but never requests or projects attention, and Recipe grammar has no command-completion delivery switch. Attention is an explicit semantic wake hint: persist durable state or an artifact first; `attention: "followup"` remains rare. Reconcile root terminal transitions before attention. One normal finite Run defaults to one automatic agent turn from its root terminal result; sequence, parallel, repeat, and import branches remain internal, while each separately launched Run owns a separate generation.
 
 ### Control
 

package/BACKLOG.md

@@ -1,16 +1,6 @@
 # Project Backlog
 
-- [ ] `0.50.0 hardening`: Close the confirmed authorization, bounded-inspection, and operator-truth gaps from the v0.49.1 production-readiness review.
-  - [ ] `Run boundary checkpoint`: Public Run operations remain owner-safe and bounded under missing identity and adversarial evidence sizes.
-    - [ ] Make Run-specific `inspect` and `message` operations fail closed when the caller session identity is unavailable, keep runtime inventory owner-filtered, and add missing-context plus cross-owner regressions.
-    - [ ] Bound session-evidence and artifact-manifest inspection before full-file materialization; use capped/streaming reads or hashing as appropriate and add adversarial-size regressions.
-  - [ ] `Operator truth checkpoint`: Public status and recovery guidance exactly match supported runtime behavior.
-    - [ ] Route automatic-review status through the canonical policy parser so `0`, `false`, and `off` are reported consistently without case sensitivity.
-    - [ ] Replace the removed `session:<id>` and `session:all` recovery hints with supported inspection guidance.
-    - [ ] Document exact `message target=run:<id>` examples for runtime-owned `kill`, `archive`, and `prune`, including their state and artifact-preservation constraints.
-  - [ ] Pass focused boundary and operator-contract regressions plus full package validation before release.
-
-- [ ] `Future minor — Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority; keep this feature outside the 0.49.2 and 0.50.0 cohorts.
+- [ ] `Future minor — Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority.
   - [ ] Publish `PlaybackStatus`, track metadata, duration, read-time position, volume, and supported capabilities under one stable session-scoped bus identity; disappear cleanly when the Run stops or its generation is replaced, and fail soft when the user D-Bus session is unavailable.
   - [ ] Map `Play`, `Pause`, `PlayPause`, `Next`, `Previous`, `Stop`, `Seek`, `SetPosition`, and `Volume` back into the existing generation-fenced music-player Control/helper contract rather than signaling the backend or editing Run state directly.
   - [ ] Validate deterministic D-Bus contract behavior plus a live GNOME smoke showing the media surface, metadata, progress, volume, and controls while preserving backend independence and exact Actor ownership.

package/CHANGELOG.md

@@ -2,7 +2,23 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
-## Unreleased
+## 0.51.0: Monotonic Run Follow-Ups
+
+- `Root-Owned Follow-Up`: A normal finite Run now produces one automatic agent turn from its root terminal result. Sequence, parallel, repeat, and imported branches remain internal execution topology; each separately launched Run still owns a separate generation and terminal lifecycle.
+- `Trace-Only Command Lifecycle`: Consolidates each command completion into one complete bounded `command.done` observation with level, captures, session provenance, artifacts, and execution evidence, but no attention. Legacy `command.done` attention remains non-projectable, and the removed Recipe-level delivery grammar stays removed.
+- `Monotonic Reconciliation`: Delivers terminal transitions before explicit semantic attention, preserves silent Runs, synchronous stop behavior, generation fencing, terminal retry evidence, and semantic checkpoints, and removes branch exit-code heuristics that could wake the coordinator from stale process-level events.
+- `Settled Pi Baseline`: Requires Pi and Pi TUI 0.84.4 or newer and schedules automatic Recipe review on `agent_settled`, after queued follow-ups, retries, and compaction complete. Source and packed-package regressions pin the lifecycle and minimum peer contract.
+
+## 0.50.0: Hardened Actor Baseline
+
+- `Template Recipe Standard`: Rebuilt the Recipe authoring guide around one current-state contract: formats, identity, uniformly detailed file-level and command-node field tables, resolution precedence, imports, async/singleton lifecycle, Control, artifacts, runtime origins, provenance, authoring workflow, and validation. Removed migration history and legacy-reference narration from the normative document.
+- `Documentation Contract Reconciliation`: Audited every human-facing document against package metadata, public schemas, implementation, maintained Skills, and tests. Added the canonical Inspect target/view matrix and exact-owner authorization boundary; completed installation, runtime triage, registered-tool lifecycle/schema, detached-build, and bounded-evidence guidance; corrected lifecycle ownership, command-template shapes, Inspector zero-based navigation/focus behavior, and remaining historical or ambiguous prose.
+- `Owner-Safe Public Runs`: Run-specific Inspect and Control now require a live coordinator identity, reject ownerless and cross-owner state, and keep runtime Run inventory exact-owner filtered. Missing-session and mismatch failures provide supported runtime inspection guidance instead of removed session targets.
+- `Bounded Evidence Inspection`: Session evidence rejects oversized JSONL before materialization with explicit truncation diagnostics, while artifact manifests compute exact size and SHA-256 through fixed-size chunks instead of loading complete artifacts into memory.
+- `Operator Truth`: Runtime status now uses the canonical automatic-review policy for `0`, `false`, and case-insensitive `off`. Maintained guidance documents exact runtime-owned `kill`, `archive`, and artifact-preserving `prune` calls with their running/terminal state constraints.
+- `Consistent Inspector Indexing`: Actor Inspector now uses zero-based numbering for Runs, Trace rows, and complex array items. Structured items render as accent keys such as `#0: {` on one line, removing list bullets and redundant opening-brace rows while preserving nested indentation, commas, wrapping, and object-label grammar.
+- `Inspector Focus Semantics`: Alternating content stripes retain `customMessageBg`, while focused Run controls, tabs, Trace rows, selector options, and confirmation choices use `selectedBg`. Trace focus gains symmetric trailing padding and composes its selected span beside—rather than around—the independent full-row stripe, avoiding nested ANSI background resets.
+- `Layered Inspector Selectors`: Run choices open directly below the focused Run control, and Trace-source choices below the focused tabs. Each menu is ANSI-aware composited over only its bounded rectangle while the underlying tabs, separator, documents, Trace rows, stripes, overlay height, and footer remain rendered and restore unchanged on close. The parent Run control or Trace tab retains `selectedBg` while its child selector is active. Trace-source choices use the compact `Trace: <source>` label, begin twelve cells into the base layer beneath the tab region, and preserve distinct label/value colors under selection. A non-`all` source projects onto the parent tab with the same colon grammar and value color while `Trace:`, including the colon, and its focus brackets retain their established tab accent. Run choices use aligned zero-based sequence, name, and status columns without a redundant `run:` prefix, preserve the same semantic status colors as the parent control, and begin four cells inside the outer frame. Both insets preserve—rather than blank—the underlying base-layer prefix before the composited menu rectangle.
 
 ## 0.49.2: Stale-Context Lifecycle Hotfix
 

package/README.md

@@ -19,6 +19,8 @@ This topology does not require every task to become a subagent. Short work with
 
 ## Install
 
+Requires Node.js 22.19.0 or newer and Pi 0.84.4 or newer.
+
 ```bash
 pi install npm:@llblab/pi-actors
 ```
@@ -59,7 +61,7 @@ Send one exact Control:
 }
 ```
 
-Run targets accept only actions declared by the captured Recipe. Runtime targets accept only reserved review actions:
+Run targets accept Recipe-declared actor-local actions plus runtime-owned `kill`, `archive`, and `prune`, subject to Run state. Runtime targets accept only reserved review actions:
 
 ```text
 message target=runtime action=review.retry input={"scope":"draft"}
@@ -79,12 +81,14 @@ inspect target=run:test view=recipe
 inspect target=run:test view=trace source=lifecycle lines=40
 inspect target=run:test view=control
 inspect target=runtime view=status
+inspect target=runtime view=runs status=failed
+inspect target=runtime view=triage
 inspect target=recipes view=status
 inspect target=recipes view=doctor identity=music-player/playback
 inspect target=tool:my_tool view=status
 ```
 
-A Run exposes exactly `recipe`, `trace`, and `control` views.
+A Run exposes exactly `recipe`, `trace`, and `control` views. Run-specific `inspect` and `message` require a current coordinator session whose id exactly matches the persisted non-empty Run owner; possessing `run:<id>` alone is not authorization. Missing-session, ownerless, and cross-owner access fails closed. Use `inspect target=runtime view=runs` for the current session's exact-owner inventory. See the complete [management inspection matrix](./docs/inspection.md).
 
 ### `register_tool`
 
@@ -147,11 +151,23 @@ String command-template leaves execute directly without shell interpretation. Us
 
 Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `level`, `attention`. Address, sender, recipient, reply, and routing fields fail validation. Trace is a bounded retained suffix, not an audit archive: the canonical authority appends within 2,048 events and 4 MiB or atomically keeps the newest suffix plus one warning-only `runtime.trace_compacted` marker. That marker means older history was discarded; `result.json`, `execution.json`, terminal state, and declared artifacts retain their own authority. `inspect view=trace` reports whether retained history is complete. Reads are newline-safe and deterministic; first-party scripts never write this file directly.
 
-Attention is a live wake hint, not a durable queue: persist recovery state or an artifact first. Use `attention: "notify"` for visible status and `attention: "followup"` only when the coordinator needs semantic follow-up context; compaction may discard older hints. Store large evidence in artifacts or bounded execution captures.
+Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve completion and execution evidence but never request or project attention. There is no Recipe-level command-completion delivery switch. Attention is an explicit semantic opt-in and a live wake hint, not a durable queue: persist recovery state or an artifact first, use `attention: "notify"` for visible status and `attention: "followup"` only when the coordinator needs semantic follow-up context, and expect compaction to discard older hints. Store large evidence in artifacts or bounded execution captures.
+
+By default, one normal finite Run produces one automatic agent turn from its root terminal result. Sequence, parallel, repeat, and imported branches remain internal to that Run and do not create branch-level turns; each separately launched Run owns its own generation and terminal follow-up.
 
 ## Control
 
-Controls persist to `controls.jsonl` before transport. One token-owned lock rejects a 65th pending Control or 1 MiB rewrite before admission, fails closed on malformed or stale-generation evidence, and atomically admits one record. Canonical transitions retain a 128-terminal tail, expected-state fencing, and 4 KiB errors. Admitted nonterminal Controls never expire automatically. Every record carries immutable `run_instance_id`. `inspect view=control` reports pending capacity, saturation, stale work, journal bytes, and bounded diagnostics. If a stuck Run is saturated, use runtime-owned `kill`; it bypasses actor-local capacity and creates no synthetic Control.
+Controls persist to `controls.jsonl` before transport. One token-owned lock rejects a 65th pending Control or 1 MiB rewrite before admission, fails closed on malformed or stale-generation evidence, and atomically admits one record. Canonical transitions retain a 128-terminal tail, expected-state fencing, and 4 KiB errors. Admitted nonterminal Controls never expire automatically. Every record carries immutable `run_instance_id`. `inspect view=control` reports pending capacity, saturation, stale work, journal bytes, and bounded diagnostics.
+
+Runtime-owned lifecycle and retention actions use the same `message` tool:
+
+```text
+message target=run:<id> action=kill
+message target=run:<id> action=archive
+message target=run:<id> action=prune input={"preserve_artifacts":true}
+```
+
+`kill` accepts only a currently running owned generation, bypasses actor-local capacity, and creates no synthetic Control. `archive` and `prune` accept only terminal owned Runs. Archive moves the entire Run state directory and leaves a tombstone. Prune removes Run state; declared existing artifacts survive only when `preserve_artifacts` is explicitly true, in which case they are copied to retained artifact storage before removal.
 
 Long-lived services publish `control-endpoint.json` only when ready:
 
@@ -222,6 +238,8 @@ npm run validate
 npm run test:preservation
 ```
 
+The build produces the JavaScript runtime used by detached Actor processes in npm installations. Pi can load a TypeScript extension entrypoint, but standalone Node processes cannot type-strip modules under `node_modules`; keeping compiled Run modules preserves process isolation without a runtime TypeScript loader.
+
 See the [documentation index](./docs/README.md), [Run lifecycle](./docs/async-runs.md), and [Recipe library](./docs/recipe-library.md).
 
 Project context: [AGENTS.md](./AGENTS.md) · [BACKLOG.md](./BACKLOG.md) · [CHANGELOG.md](./CHANGELOG.md).

package/dist/index.js

@@ -9,7 +9,7 @@ export default function toolRegistryExtension(pi) {
     const runtime = ExtensionRuntime.createActorExtensionRuntime(pi);
     pi.on("resources_discover", async () => runtime.discoverResources(import.meta.url));
     pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
-    pi.on("agent_end", async (_event, ctx) => runtime.onAgentEnd(ctx));
+    pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
     pi.on("session_shutdown", async (event, ctx) => runtime.onSessionShutdown(event.reason, ctx));
     pi.on("before_agent_start", async (event, ctx) => runtime.beforeAgentStart(event.systemPrompt, event.systemPromptOptions.skills ?? [], ctx));
     InspectorCommand.registerActorInspectorCommand(pi, runtime.getRunOwnerId);

package/dist/lib/extension-runtime.d.ts

@@ -13,7 +13,7 @@ export interface ActorExtensionRuntime {
         skillPaths: string[];
     } | undefined;
     getRunOwnerId(ctx: Pi.ExtensionContext): string;
-    onAgentEnd(ctx: Pi.ExtensionContext): void;
+    onAgentSettled(ctx: Pi.ExtensionContext): void;
     onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
     onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;
     registerCoreTools(): void;

package/dist/lib/extension-runtime.js

@@ -112,7 +112,7 @@ export function createActorExtensionRuntime(pi) {
             return skillPaths.length > 0 ? { skillPaths } : undefined;
         },
         getRunOwnerId,
-        onAgentEnd(ctx) {
+        onAgentSettled(ctx) {
             if (activeRunContext === ctx)
                 automaticReview.schedule();
         },

package/dist/lib/inspector-overlay.d.ts

@@ -32,6 +32,7 @@ export declare class ActorInspectorOverlay {
     private readonly theme;
     private readonly tui;
     private readonly refreshTimer;
+    private contentSelectedRows;
     private contentStripeIndices;
     private documentScroll;
     private detailScroll;
@@ -71,6 +72,7 @@ export declare class ActorInspectorOverlay {
     private renderTabs;
     private renderContent;
     private renderSelector;
+    private runSelectorOptions;
     private renderMenuBox;
     private renderTraceList;
     private renderTraceDetail;
@@ -91,6 +93,7 @@ export declare class ActorInspectorOverlay {
     private renderKeyHints;
     private statusColor;
     private footerBorder;
+    private compositeMenuLine;
     private stripeBackground;
     private stripedRow;
     private row;

package/dist/lib/inspector-overlay.js

@@ -5,7 +5,7 @@
  */
 import { readFileSync, statSync } from "node:fs";
 import * as path from "node:path";
-import { matchesKey, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+import { matchesKey, sliceByColumn, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
 import * as ActorInspector from "./inspector.js";
 import * as ControlProjection from "./control-projection.js";
 import * as RunsControls from "./runs-controls.js";
@@ -35,6 +35,7 @@ export class ActorInspectorOverlay {
     theme;
     tui;
     refreshTimer;
+    contentSelectedRows = new Set();
     contentStripeIndices = [];
     documentScroll = 0;
     detailScroll = 0;
@@ -219,9 +220,10 @@ export class ActorInspectorOverlay {
         if (this.killConfirmation)
             return this.renderKillDialog(innerWidth);
         const lines = [this.border("╭", " Actor Inspector ", "╮", innerWidth)];
-        lines.push(this.row(this.renderRunControl(run, runs.length - this.runIndex), innerWidth));
+        lines.push(this.row(this.renderRunControl(run, runs.length - this.runIndex - 1), innerWidth));
         lines.push(this.row(this.renderTabs(run), innerWidth));
         lines.push(this.border("├", "", "┤", innerWidth));
+        this.contentSelectedRows.clear();
         this.contentStripeIndices = [];
         let content = this.renderContent(run, innerWidth);
         if (this.feedback) {
@@ -231,14 +233,28 @@ export class ActorInspectorOverlay {
                     ? "error"
                     : "warning";
             content = [this.theme.fg(color, ` ${this.feedback.message}`), ...content];
+            this.contentSelectedRows = new Set([...this.contentSelectedRows].map((index) => index + 1));
             this.contentStripeIndices = [0, ...this.contentStripeIndices];
         }
         const viewportRows = this.contentViewportRows();
         content = content.slice(0, viewportRows);
         for (let index = 0; index < viewportRows; index += 1) {
-            lines.push(this.stripedRow(content[index] ?? "", innerWidth, this.contentStripeIndices[index] ?? index));
+            lines.push(this.stripedRow(content[index] ?? "", innerWidth, this.contentStripeIndices[index] ?? index, this.contentSelectedRows.has(index)));
         }
         lines.push(this.footerBorder(this.renderKeyHints(), innerWidth));
+        if (this.focus === "select") {
+            const runSelector = this.selectorMode === "run";
+            const startRow = runSelector ? 2 : 3;
+            const horizontalOffset = runSelector ? 4 : 12;
+            const availableRows = Math.max(3, lines.length - startRow - 1);
+            const menu = this.renderSelector(run, availableRows);
+            for (const [offset, menuLine] of menu.entries()) {
+                const target = startRow + offset;
+                if (target >= lines.length - 1)
+                    break;
+                lines[target] = this.compositeMenuLine(lines[target], menuLine, innerWidth, horizontalOffset);
+            }
+        }
         return lines;
     }
     get tab() {
@@ -399,10 +415,10 @@ export class ActorInspectorOverlay {
     renderKillDialog(innerWidth) {
         const confirmation = this.killConfirmation;
         const cancel = this.killDialogChoice === "cancel"
-            ? this.theme.bg("customMessageBg", this.theme.fg("accent", "  Cancel  "))
+            ? this.theme.bg("selectedBg", this.theme.fg("accent", "  Cancel  "))
             : this.theme.fg("muted", "  Cancel  ");
         const kill = this.killDialogChoice === "kill"
-            ? this.theme.bg("customMessageBg", this.theme.fg("error", "  Kill actor  "))
+            ? this.theme.bg("selectedBg", this.theme.fg("error", "  Kill actor  "))
             : this.theme.fg("error", "  Kill actor  ");
         const body = [
             "",
@@ -433,30 +449,36 @@ export class ActorInspectorOverlay {
         const suffix = active ? this.theme.fg("accent", " → ") : "   ";
         if (!run) {
             const empty = this.theme.fg("muted", `${prefix}Run: none${suffix}`);
-            return this.focus === "runs" ? this.theme.bg("customMessageBg", empty) : empty;
+            return active ? this.theme.bg("selectedBg", empty) : empty;
         }
         const value = `${prefix}${this.theme.fg("muted", "Run: ")}${this.theme.fg("text", `#${sequence}`)}  ${this.theme.fg("accent", run.run)}  ${this.theme.fg(this.statusColor(run.status), run.status)}${suffix}`;
-        return this.focus === "runs" ? this.theme.bg("customMessageBg", value) : value;
+        return active ? this.theme.bg("selectedBg", value) : value;
     }
     renderTabs(run) {
         const source = this.traceSource(run);
         return TABS.map((tab, index) => {
             const base = `${tab[0].toUpperCase()}${tab.slice(1)}`;
-            const label = tab === "trace" && source !== "all" ? `${base} (${source})` : base;
+            const label = tab === "trace" && source !== "all" ? `${base}: ${source}` : base;
             const selected = index === this.tabIndex;
-            const display = selected && this.focus !== "runs" ? `[ ${label} ]` : `  ${label}  `;
-            const value = ` ${display} `;
-            if (!selected)
-                return this.theme.fg("muted", value);
-            const colored = this.theme.fg("accent", value);
-            return this.focus === "tabs" ? this.theme.bg("customMessageBg", colored) : colored;
+            const bracketed = selected && this.focus !== "runs";
+            if (!selected) {
+                const display = bracketed ? `[ ${label} ]` : `  ${label}  `;
+                return this.theme.fg("muted", ` ${display} `);
+            }
+            const coloredLabel = tab === "trace" && source !== "all"
+                ? `${this.theme.fg("accent", `${base}:`)} ${this.theme.fg("text", source)}`
+                : this.theme.fg("accent", label);
+            const colored = bracketed
+                ? ` ${this.theme.fg("accent", "[ ")}${coloredLabel}${this.theme.fg("accent", " ]")} `
+                : `   ${coloredLabel}   `;
+            const active = this.focus === "tabs"
+                || (this.focus === "select" && this.selectorMode === "source");
+            return active ? this.theme.bg("selectedBg", colored) : colored;
         }).join(" ");
     }
     renderContent(run, width) {
         if (!run)
             return [this.theme.fg("muted", " No owned actor runs")];
-        if (this.focus === "select")
-            return this.renderSelector(run);
         if (this.focus === "detail")
             return this.renderTraceDetail(width);
         if (this.tab === "trace")
@@ -471,30 +493,49 @@ export class ActorInspectorOverlay {
         this.contentStripeIndices = projection.stripes.slice(this.documentScroll, this.documentScroll + this.contentViewportRows());
         return projection.lines.slice(this.documentScroll, this.documentScroll + this.contentViewportRows());
     }
-    renderSelector(run) {
+    renderSelector(run, availableRows) {
         const options = this.selectorMode === "run"
-            ? this.runs().map((item) => `run:${item.run}  ${item.status}`)
-            : this.traceSources(run).map((source) => `Trace source: ${source}`);
-        const lines = this.renderMenuBox(options, this.selectorIndex);
-        this.contentStripeIndices = lines.map(() => 0);
-        return lines;
-    }
-    renderMenuBox(options, focusedIndex) {
+            ? this.runSelectorOptions()
+            : this.traceSources(run).map((source) => ({
+                content: `${this.theme.fg("accent", "Trace:")} ${this.theme.fg("text", source)}`,
+                preserveColors: true,
+            }));
+        return this.renderMenuBox(options, this.selectorIndex, availableRows);
+    }
+    runSelectorOptions() {
+        const runs = this.runs();
+        const sequenceWidth = Math.max(2, ...runs.map((_item, index) => `#${runs.length - index - 1}`.length));
+        const runWidth = Math.max(1, ...runs.map((item) => visibleWidth(item.run)));
+        return runs.map((item, index) => ({
+            content: [
+                this.theme.fg("text", this.fit(`#${runs.length - index - 1}`, sequenceWidth)),
+                this.theme.fg("accent", this.fit(item.run, runWidth)),
+                this.theme.fg(this.statusColor(item.status), item.status),
+            ].join("  "),
+            preserveColors: true,
+        }));
+    }
+    renderMenuBox(options, focusedIndex, availableRows) {
         if (options.length === 0)
             return [this.theme.fg("muted", " No options")];
-        const visibleLimit = Math.max(1, Math.min(this.contentViewportRows(), options.length));
+        const visibleLimit = Math.max(1, Math.min(availableRows - 2, options.length));
         const maxStart = Math.max(0, options.length - visibleLimit);
         const start = Math.max(0, Math.min(focusedIndex - Math.floor(visibleLimit / 2), maxStart));
         const visible = options.slice(start, start + visibleLimit);
-        const width = Math.max(8, ...options.map((option) => visibleWidth(option) + 4));
+        const width = Math.max(8, ...options.map((option) => visibleWidth(option.content) + 4));
         const border = (left, right, marker = "") => this.theme.fg("borderAccent", `${left}${marker}${"─".repeat(Math.max(0, width - visibleWidth(marker)))}${right}`);
         return [
             border("╭", "╮", start > 0 ? "↑" : ""),
             ...visible.map((option, offset) => {
                 const index = start + offset;
-                const row = this.fit(`${index === focusedIndex ? " ▶ " : "   "}${option}`, width);
-                const colored = index === focusedIndex ? this.theme.fg("accent", row) : row;
-                const styled = index === focusedIndex ? this.theme.bg("customMessageBg", colored) : colored;
+                const marker = index === focusedIndex
+                    ? this.theme.fg("accent", " ▶ ")
+                    : "   ";
+                const row = this.fit(`${marker}${option.content}`, width);
+                const colored = index === focusedIndex && !option.preserveColors
+                    ? this.theme.fg("accent", row)
+                    : row;
+                const styled = index === focusedIndex ? this.theme.bg("selectedBg", colored) : colored;
                 return `${this.theme.fg("borderAccent", "│")}${styled}${this.theme.fg("borderAccent", "│")}`;
             }),
             border("╰", "╯", start + visible.length < options.length ? "↓" : ""),
@@ -523,6 +564,12 @@ export class ActorInspectorOverlay {
         this.contentStripeIndices = items
             .slice(start, start + viewportRows)
             .map((_item, offset) => start + offset);
+        const selectedViewportRow = banner.length + this.rowIndex - start;
+        if (this.focus === "list" &&
+            selectedViewportRow >= banner.length &&
+            selectedViewportRow < viewportRows) {
+            this.contentSelectedRows.add(selectedViewportRow);
+        }
         return [...banner, ...items.slice(start, start + viewportRows - banner.length).map((item, offset) => {
                 const index = start + offset;
                 const detail = item.detail && typeof item.detail === "object"
@@ -536,7 +583,7 @@ export class ActorInspectorOverlay {
                 const prefix = this.focus === "list" && index === this.rowIndex
                     ? this.theme.fg("accent", " ▶ ")
                     : "   ";
-                const row = `${prefix}${this.theme.fg("text", `#${items.length - index}`)} ${marker} ${this.theme.fg("muted", item.source)}/${this.theme.fg(item.level === "error" ? "error" : "accent", item.kind)}  ${this.theme.fg("text", item.summary)}`;
+                const row = `${prefix}${this.theme.fg("text", `#${items.length - index - 1}`)} ${marker} ${this.theme.fg("muted", item.source)}/${this.theme.fg(item.level === "error" ? "error" : "accent", item.kind)}  ${this.theme.fg("text", item.summary)}`;
                 return this.focus === "list" && index === this.rowIndex
                     ? this.theme.fg("accent", row)
                     : row;
@@ -676,11 +723,27 @@ export class ActorInspectorOverlay {
             return [
                 `${indent}[`,
                 ...value.flatMap((item, index) => {
-                    const marker = `${indent}  - #${index + 1}`;
+                    const itemDepth = depth + 1;
+                    const itemIndent = "  ".repeat(itemDepth);
+                    const marker = `#${index}`;
                     const itemInline = this.inlineDocumentValue(item);
-                    return itemInline !== undefined
-                        ? [`${marker}: ${itemInline}`]
-                        : [marker, ...this.document(item, depth + 2)];
+                    let lines;
+                    if (itemInline !== undefined) {
+                        lines = [`${itemIndent}${marker}: ${itemInline}`];
+                    }
+                    else if (item && typeof item === "object") {
+                        const nested = this.document(item, itemDepth);
+                        lines = [
+                            `${itemIndent}${marker}: ${nested[0].slice(itemIndent.length)}`,
+                            ...nested.slice(1),
+                        ];
+                    }
+                    else {
+                        lines = this.labeledScalarLines(marker, item, itemDepth);
+                    }
+                    if (index < value.length - 1)
+                        lines[lines.length - 1] += ",";
+                    return lines;
                 }),
                 `${indent}]`,
             ];
@@ -731,9 +794,13 @@ export class ActorInspectorOverlay {
     styleDocumentLine(line) {
         const indent = line.match(/^ */u)?.[0] ?? "";
         const content = line.slice(indent.length);
-        if (/^- #\d+$/u.test(content) || content.endsWith(":")) {
+        if (content.endsWith(":")) {
             return `${indent}${this.theme.fg("accent", content)}`;
         }
+        const indexed = /^(#\d+:)(.*)$/u.exec(content);
+        if (indexed) {
+            return `${indent}${this.theme.fg("accent", indexed[1])}${this.theme.fg("text", indexed[2])}`;
+        }
         const labeled = /^([^:]+:)(.*)$/u.exec(content);
         if (labeled) {
             return `${indent}${this.theme.fg("muted", labeled[1])}${this.theme.fg("text", labeled[2])}`;
@@ -799,12 +866,27 @@ export class ActorInspectorOverlay {
         const fill = "─".repeat(Math.max(0, width - visibleWidth(prefix) - visibleWidth(suffix) - visibleWidth(content)));
         return `${this.theme.fg("borderAccent", `╰${prefix}`)}${content}${this.theme.fg("borderAccent", `${suffix}${fill}╯`)}`;
     }
+    compositeMenuLine(baseLine, menuLine, innerWidth, horizontalOffset) {
+        const offset = Math.max(0, Math.min(horizontalOffset, innerWidth));
+        const menuWidth = Math.min(innerWidth - offset, visibleWidth(menuLine));
+        const baseInner = sliceByColumn(baseLine, 1, innerWidth, true);
+        const prefix = sliceByColumn(baseInner, 0, offset, true);
+        const suffixStart = offset + menuWidth;
+        const suffix = sliceByColumn(baseInner, suffixStart, Math.max(0, innerWidth - suffixStart), true);
+        const remainder = this.fit(suffix, innerWidth - suffixStart);
+        return `${this.theme.fg("borderAccent", "│")}${this.fit(prefix, offset)}${truncateToWidth(menuLine, menuWidth, "")}${remainder}${this.theme.fg("borderAccent", "│")}`;
+    }
     stripeBackground(content, index) {
         return index % 2 === 0 ? content : this.theme.bg("customMessageBg", content);
     }
-    stripedRow(content, width, index) {
-        const fitted = this.fit(content, width);
-        return `${this.theme.fg("borderAccent", "│")}${this.stripeBackground(fitted, index)}${this.theme.fg("borderAccent", "│")}`;
+    stripedRow(content, width, index, selected) {
+        if (!selected) {
+            const fitted = this.fit(content, width);
+            return `${this.theme.fg("borderAccent", "│")}${this.stripeBackground(fitted, index)}${this.theme.fg("borderAccent", "│")}`;
+        }
+        const selectedContent = truncateToWidth(`${content} `, width, "");
+        const remainder = " ".repeat(Math.max(0, width - visibleWidth(selectedContent)));
+        return `${this.theme.fg("borderAccent", "│")}${this.theme.bg("selectedBg", selectedContent)}${this.stripeBackground(remainder, index)}${this.theme.fg("borderAccent", "│")}`;
     }
     row(content, width) {
         return `${this.theme.fg("borderAccent", "│")}${this.fit(content, width)}${this.theme.fg("borderAccent", "│")}`;

package/dist/lib/limits.d.ts

@@ -11,6 +11,7 @@ export declare const CONTROL_INPUT_MAX_BYTES = 380;
 export declare const CONTROL_WIRE_MAX_BYTES = 512;
 export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export declare const SESSION_EVIDENCE_MAX_BYTES: number;
 export declare const SESSION_EVIDENCE_MAX_TURNS = 100;
 export declare const SESSION_EVIDENCE_TEXT_CHARS = 4000;
 export declare const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/dist/lib/limits.js

@@ -11,6 +11,7 @@ export const CONTROL_INPUT_MAX_BYTES = 380;
 export const CONTROL_WIRE_MAX_BYTES = 512;
 export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export const SESSION_EVIDENCE_MAX_BYTES = 4 * 1024 * 1024;
 export const SESSION_EVIDENCE_MAX_TURNS = 100;
 export const SESSION_EVIDENCE_TEXT_CHARS = 4_000;
 export const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/dist/lib/observability.js

@@ -75,9 +75,9 @@ export function reconcileRunTerminalNotifications(input) {
         includeAttention: input.includeAttention,
         stateRoot: input.stateRoot,
     });
+    deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
     if (input.includeAttention)
         deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
-    deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
     pruneRunUiObservationState(input.state, snapshot);
     return snapshot;
 }
@@ -838,6 +838,8 @@ export function getRunAttentionNotificationType(event) {
     return event.level;
 }
 export function shouldNotifyRunAttentionEvent(event) {
+    if (event.kind === "command.done")
+        return false;
     return event.attention === "notify" || event.attention === "followup";
 }
 export function shouldSendRunAttentionFollowUp(event) {

package/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/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/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/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[];