@llblab/pi-kit 0.1.12 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.2.0 - 2026-08-31
+
+- `Actors Minor Releases`: Advances `@llblab/pi-actors` to `0.52.0`, bringing root-owned follow-ups, durable completion epochs, presentation acknowledgment, recovery-safe scheduling, explicit urgent steering, and settled packed-package parity into the bundled kit.
+- `Telegram Minor Release`: Advances `@llblab/pi-telegram` to `0.41.0`, keeping typing active through settled work and compaction, making connected companion projection always-on, and updating generated controls, connection notices, token telemetry, and voice setup guidance.
+
+## 0.1.13 - 2026-08-30
+
+- `Telegram Minor Release`: Advances `@llblab/pi-telegram` to `0.40.0`, requiring Pi 0.84.4 and adopting native compaction-failure, mid-run compaction, terminal-message, and local UI-prompt lifecycle contracts while increasing bounded inbound text output to 24,000 characters.
+
 ## 0.1.12 - 2026-08-28
 
 - `Codex Usage Release`: Advances `@llblab/pi-codex-usage` to `0.9.4`, reducing automatic OpenAI quota polling by increasing the refresh interval from 30 to 60 seconds while preserving the local countdown responsiveness.

package/README.md

@@ -6,10 +6,10 @@
 
 | Package | Version | Resources |
 | --- | ---: | --- |
-| `@llblab/pi-actors` | `0.50.0` | Extension and Skills |
+| `@llblab/pi-actors` | `0.52.0` | Extension and Skills |
 | `@llblab/pi-codex-usage` | `0.9.4` | Extension |
 | `@llblab/pi-grow-loop` | `0.7.3` | Extension and Skills |
-| `@llblab/pi-telegram` | `0.39.5` | Extension and Skills |
+| `@llblab/pi-telegram` | `0.41.0` | Extension and Skills |
 
 Versions are exact by design. Updating an extension does not change an installed kit until this repository explicitly advances that dependency and publishes a new kit version.
 

package/node_modules/@llblab/pi-actors/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 any attention value, and Recipe grammar has no command-completion delivery switch. Semantic attention is explicit: `notify` is visible status, `followup` is an ordinary checkpoint hint, and actor-authored `steer` is durable urgent delivery at Pi's next safe boundary. Never infer attention from status or exit code. Admit steer by exact event and Run generation before `deliverAs: "steer"`; acknowledge only its exact model-bound context envelope, and preserve the later root-terminal completion batch. Sequence, parallel, repeat, and import branches remain internal, while each separately launched Run owns a separate generation.
 
 ### Control
 
@@ -134,9 +134,11 @@ Automatic review receives value-free structural projections, not executable cont
 
 Tool result/error text contributes exactly one leading line break. Keep model-facing responses compact and state-backed. Preserve complete byte-exact command streams in bounded spill files while returning bounded tails; never feed truncated tails into pipeline stdin.
 
-File watchers accelerate reconciliation; a bounded interval recovers missed terminal and retained-attention events. Canonical attention observation uses stable retained ids, primes them at startup without replay, and bounds seen memory to the current suffix across compaction; only allowlisted legacy outbox fallback uses line offsets. Attention is a wake hint, so persist durable recovery state before emitting it. Terminal follow-ups contain only Run id, status, one base path, and relative artifact names in visible content; semantic details remain structured. Delivery remains honestly at-least-once across the send/handled-marker crash window.
+File watchers accelerate reconciliation; a bounded interval recovers missed terminal and retained-attention events. Canonical attention observation uses stable retained ids and bounds seen memory to the current suffix across compaction; only allowlisted legacy outbox fallback uses line offsets. Ordinary `notify` and `followup` hints prime at startup without replay and require durable state or artifacts for recovery. Explicit `steer` instead re-enters through the owner journal until exact presentation records its newer generation-fenced Trace marker.
 
-When a deferred Run result gates the next step, wait for its terminal follow-up. Inspect early only for operator request, meaningful attention, or diagnosis of an overdue Run.
+Ordinary root terminals remain authoritative in Run state until the owner-scoped completion scheduler snapshots an immutable batch at a settled or idle boundary. Batch delivery is generation-fenced and bounded at 256 durable members, 64 model-facing rows, 16 KiB of context, and a 1 MiB journal. `sendMessage()` acceptance advances only to queued; only the exact batch id and content appearing in model-bound `context` advances to presented and authorizes exact-generation handled markers. Restart recovery walks the bounded active Pi session parent chain: exact queued evidence waits without resend, proven absence returns the envelope to pending, and incomplete or conflicting evidence remains queued with diagnostics. Retry duplicates collapse before presentation, malformed envelopes fail closed, and automatic review waits behind an active completion batch.
+
+When deferred Run results gate the next step, wait for their completion batch. Inspect early only for operator request, meaningful attention, or diagnosis of an overdue Run.
 
 ## Documentation and Release Discipline
 

package/node_modules/@llblab/pi-actors/BACKLOG.md

@@ -1,6 +1,6 @@
 # Project Backlog
 
-- [ ] `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.
+- [ ] `Next 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/node_modules/@llblab/pi-actors/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.52.0: Durable Coordinator Delivery
+
+- `Completion Epochs`: Replaces per-Run terminal turns with one immutable owner-fenced completion batch per idle/settled epoch. Batches retain exact Run generations and terminal timestamps, bound durable and model-facing members, preserve silent and synchronous-stop semantics, and remain eligible after urgent steering.
+- `Presentation Acknowledgment`: Persists completion delivery through `pending`, `queued`, and `presented`; Pi transport acceptance advances only to `queued`, while exact model-bound `context` presentation authorizes generation-fenced terminal handled markers. Duplicate envelopes collapse and altered or conflicting content fails closed.
+- `Recovery-Safe Scheduling`: Stores owner-hashed atomic delivery journals with bounded receipts, attempts, and errors. Restart recovery inspects only the bounded active Pi session chain, retries proven-absent envelopes, preserves uncertain queued evidence, rejects malformed, oversized, duplicate, and symlinked state, and keeps the scheduler directory through stale-temp cleanup.
+- `Explicit Urgent Steering`: Adds durable actor-authored Trace `attention: "steer"` envelopes delivered only through Pi's safe steer boundary. Exact presentation writes generation-fenced `delivery.steer_presented` evidence, suppresses historical replay, and never suppresses the later root-terminal completion batch; `command.done` remains Trace-only regardless of legacy attention fields.
+- `Settled Packed Parity`: Exercises the compiled package against the Pi 0.84.4 lifecycle contract, proving urgent steer presentation precedes its exact completion epoch, with `agent_settled`, follow-up/steer delivery modes, model-bound context acknowledgment, terminal fencing, and durable steer evidence.
+
+## 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.

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

@@ -15,11 +15,11 @@ An **actor** is any runnable local capability: a script, tool, service, pipeline
 
 Multi-instance systems commonly put instance creation and routing in an external gateway. pi-actors supports a different topology: the current Pi instance remains the coordinator, companion extensions such as Telegram provide presence, and explicit Runs perform bounded delegated work. The coordinator receives high-level outcomes, decomposes them, stays available for decisions, and owns integration plus final validation instead of becoming another undifferentiated worker.
 
-This topology does not require every task to become a subagent. Short work with one natural validation boundary stays inline; delegation pays when clean context, asynchronous execution, independent judgement, parallel ownership, or coordinator availability exceeds its coordination cost. Bounded implementation can run with reasoning off while the coordinator selectively launches clean-context reasoning-enabled reviewers; several independent reviews can provide broader evidence than one author self-review. Terminal follow-ups, durable Trace, and declared artifacts replace tight polling loops.
+This topology does not require every task to become a subagent. Short work with one natural validation boundary stays inline; delegation pays when clean context, asynchronous execution, independent judgement, parallel ownership, or coordinator availability exceeds its coordination cost. Bounded implementation can run with reasoning off while the coordinator selectively launches clean-context reasoning-enabled reviewers; several independent reviews can provide broader evidence than one author self-review. Settled completion batches, durable Trace, and declared artifacts replace tight polling loops.
 
 ## Install
 
-Requires Node.js 22.19.0 or newer.
+Requires Node.js 22.19.0 or newer and Pi 0.84.4 or newer.
 
 ```bash
 pi install npm:@llblab/pi-actors
@@ -151,7 +151,9 @@ 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, including malformed legacy records carrying `steer`. There is no Recipe-level command-completion delivery switch. Semantic attention is explicit: `notify` shows visible status without a model turn, `followup` supplies ordinary checkpoint context, and `steer` requests urgent delivery at Pi's next safe assistant/tool boundary. `notify` and `followup` remain retained wake hints that may compact away, so persist recovery state or an artifact first. `steer` is admitted to the bounded owner delivery journal before `deliverAs: "steer"`, acknowledged only in exact model-bound context, and never suppresses the eventual root-terminal batch. Store large evidence in artifacts or bounded execution captures.
+
+Ordinary finite Runs project root terminal results through one owner-fenced completion scheduler. Completions that accumulate while Pi is active or inside the idle debounce window enter one immutable bounded batch and cause one automatic agent turn after Pi settles; terminal generations are acknowledged only when that exact batch reaches model-bound context. Sequence, parallel, repeat, and imported branches remain internal and never create branch-level turns, while separately launched Runs retain exact independent generations. Silent Runs and synchronous stop acknowledgments remain non-projecting.
 
 ## Control
 

package/node_modules/@llblab/pi-actors/dist/index.js

@@ -9,7 +9,10 @@ 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("context", async (event, ctx) => ({
+        messages: runtime.onContext(event.messages, 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/node_modules/@llblab/pi-actors/dist/lib/async-runs.d.ts

@@ -136,8 +136,8 @@ export interface RunControlExpectation {
     ownerId?: string;
     runInstanceId?: string;
 }
-export declare function markRunTerminalNotificationHandled(stateDir: string, status: string): void;
-export declare function recordRunTerminalDeliveryFailure(stateDir: string, status: string, error: unknown): void;
+export declare function markRunTerminalNotificationHandled(stateDir: string, status: string, expectedRunInstanceId: string): boolean;
+export declare function markRunSteerPresentationHandled(stateDir: string, expectedRunInstanceId: string, eventId: string, steerId: string): boolean;
 export declare function cancelRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;
 export declare function archiveRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;
 export declare function pruneRun(runOrDir: string, options?: {

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

@@ -4,7 +4,7 @@
  */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, rmSync, statSync, } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
@@ -719,25 +719,48 @@ function stopRun(runOrDir, signal, event, expected = {}) {
         releaseControlLock();
     }
 }
-export function markRunTerminalNotificationHandled(stateDir, status) {
-    markTerminalHandled(stateDir, {
-        event: "run.notification",
-        status,
-    });
+export function markRunTerminalNotificationHandled(stateDir, status, expectedRunInstanceId) {
+    const releaseLock = RunsStart.acquireStateStartLock(stateDir);
+    try {
+        if (!existsSync(join(stateDir, "run.json")))
+            return false;
+        const current = getRunStatus(stateDir);
+        if (current.run_instance_id !== expectedRunInstanceId ||
+            current.status !== status)
+            return false;
+        markTerminalHandled(stateDir, {
+            event: "run.notification",
+            run_instance_id: expectedRunInstanceId,
+            status,
+        });
+        rmSync(join(stateDir, "terminal-delivery-failure.json"), { force: true });
+        return true;
+    }
+    finally {
+        releaseLock();
+    }
 }
-export function recordRunTerminalDeliveryFailure(stateDir, status, error) {
-    const path = join(stateDir, "terminal-delivery-failure.json");
-    const previous = readJson(path);
-    const message = (error instanceof Error ? error.message : String(error))
-        .replaceAll(/\s+/g, " ")
-        .trim()
-        .slice(0, 500);
-    writeJsonAtomic(path, {
-        attempts: Math.max(0, Number(previous?.attempts ?? 0)) + 1,
-        error: message || "unknown delivery failure",
-        status,
-        ts: new Date().toISOString(),
-    });
+export function markRunSteerPresentationHandled(stateDir, expectedRunInstanceId, eventId, steerId) {
+    const releaseLock = RunsStart.acquireStateStartLock(stateDir);
+    try {
+        if (!existsSync(join(stateDir, "run.json")))
+            return false;
+        const current = getRunStatus(stateDir);
+        if (current.run_instance_id !== expectedRunInstanceId)
+            return false;
+        appendRunTraceEvent(stateDir, {
+            data: {
+                event_id: eventId,
+                run_instance_id: expectedRunInstanceId,
+                steer_id: steerId,
+            },
+            kind: "delivery.steer_presented",
+        });
+        return true;
+    }
+    finally {
+        releaseLock();
+    }
 }
 export function cancelRun(runOrDir, expected = {}) {
     const result = stopRun(runOrDir, "SIGTERM", "run.cancel", expected);

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

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

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

@@ -112,10 +112,15 @@ export function createActorExtensionRuntime(pi) {
             return skillPaths.length > 0 ? { skillPaths } : undefined;
         },
         getRunOwnerId,
-        onAgentEnd(ctx) {
-            if (activeRunContext === ctx)
+        onAgentSettled(ctx) {
+            if (activeRunContext !== ctx)
+                return;
+            if (!runUiRuntime.flushCompletionBatch(ctx))
                 automaticReview.schedule();
         },
+        onContext(messages, ctx) {
+            return runUiRuntime.projectContext(messages, ctx);
+        },
         onSessionShutdown(reason, ctx) {
             const ownerId = runOwnerIdsByContext.get(ctx);
             runOwnerIdsByContext.delete(ctx);

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

@@ -27,3 +27,12 @@ export declare const RUN_CONTROL_ERROR_MAX_BYTES: number;
 export declare const RUN_CONTROL_JOURNAL_MAX_BYTES: number;
 export declare const RUN_RETENTION_MAX_RECORDS = 256;
 export declare const RUN_RETENTION_MAX_BYTES: number;
+export declare const RUN_DELIVERY_BATCH_MAX_MEMBERS = 256;
+export declare const RUN_DELIVERY_MODEL_MAX_MEMBERS = 64;
+export declare const RUN_DELIVERY_MODEL_MAX_BYTES: number;
+export declare const RUN_DELIVERY_RECEIPT_LIMIT = 128;
+export declare const RUN_DELIVERY_SESSION_MAX_ENTRIES = 256;
+export declare const RUN_DELIVERY_SESSION_MAX_BYTES: number;
+export declare const RUN_DELIVERY_STEER_MAX_ENVELOPES = 64;
+export declare const RUN_DELIVERY_STEER_MAX_BYTES: number;
+export declare const RUN_DELIVERY_JOURNAL_MAX_BYTES: number;

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

@@ -27,3 +27,12 @@ export const RUN_CONTROL_ERROR_MAX_BYTES = 4 * 1024;
 export const RUN_CONTROL_JOURNAL_MAX_BYTES = 1024 * 1024;
 export const RUN_RETENTION_MAX_RECORDS = 256;
 export const RUN_RETENTION_MAX_BYTES = 1024 * 1024;
+export const RUN_DELIVERY_BATCH_MAX_MEMBERS = 256;
+export const RUN_DELIVERY_MODEL_MAX_MEMBERS = 64;
+export const RUN_DELIVERY_MODEL_MAX_BYTES = 16 * 1024;
+export const RUN_DELIVERY_RECEIPT_LIMIT = 128;
+export const RUN_DELIVERY_SESSION_MAX_ENTRIES = 256;
+export const RUN_DELIVERY_SESSION_MAX_BYTES = 1024 * 1024;
+export const RUN_DELIVERY_STEER_MAX_ENVELOPES = 64;
+export const RUN_DELIVERY_STEER_MAX_BYTES = 16 * 1024;
+export const RUN_DELIVERY_JOURNAL_MAX_BYTES = 1024 * 1024;

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

@@ -5,8 +5,9 @@
  */
 import { type FSWatcher } from "node:fs";
 import * as AsyncRuns from "./async-runs.ts";
+import type { RunCompletionBatchMember } from "./run-delivery.ts";
 export type RunObservedStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
-export type RunTraceAttention = "log" | "notify" | "followup";
+export type RunTraceAttention = "log" | "notify" | "followup" | "steer";
 export type RunTraceLevel = "info" | "warning" | "error";
 export interface RunObservation {
     activeSubagents?: number;
@@ -23,6 +24,7 @@ export interface RunObservation {
     terminalHandled?: boolean;
     retireWhen?: string;
     run: string;
+    runInstanceId?: string;
     semanticResult?: RunTerminalSemanticResult;
     tool?: string;
     stateDir?: string;
@@ -68,15 +70,6 @@ export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId:
     stateRoot?: string;
 }): RunUiSnapshot;
 export declare function pruneRunUiObservationState(state: RunUiObservationState, snapshot: Pick<RunUiSnapshot, "summary" | "transitions">): void;
-export declare function deliverRunTransitionNotifications(transitions: RunTransition[], sink: RunUiNotificationSink, inFlight?: Set<string>): void;
-export declare function reconcileRunTerminalNotifications(input: {
-    inFlight?: Set<string>;
-    ownerId: string;
-    sink: RunUiNotificationSink;
-    state: RunUiObservationState;
-    stateRoot?: string;
-    includeAttention?: boolean;
-}): RunUiSnapshot;
 export declare function deliverRunAttentionNotifications(events: RunAttentionEvent[], sink: RunUiNotificationSink): void;
 export interface RunRetirementCandidate {
     activeSubagents: number;
@@ -133,7 +126,9 @@ export interface RunRetirementExecutorOptions {
 export interface RunTransition {
     from: RunObservedStatus;
     run: string;
+    runInstanceId?: string;
     stateDir?: string;
+    terminalAt?: string;
     artifacts?: Record<string, string>;
     launchCorrelation?: Record<string, string>;
     launchSource?: AsyncRuns.AsyncRunLaunchSource;
@@ -161,6 +156,7 @@ export interface RunAttentionEvent {
     level: RunTraceLevel;
     metadata?: Record<string, unknown>;
     run: string;
+    runInstanceId?: string;
     stateDir: string;
     summary: string;
     ts: string;
@@ -178,9 +174,12 @@ export declare function pruneRunObservationState(previousStatuses: Map<string, R
 export declare function detectRunAttentionEvents(legacyLineCounts: Map<string, number>, summary: RunSummary, seenEventIds?: Map<string, Set<string>>, prime?: boolean): RunAttentionEvent[];
 export declare function getRunAttentionNotificationType(event: RunAttentionEvent): RunTransitionNotificationType;
 export declare function shouldNotifyRunAttentionEvent(event: RunAttentionEvent): boolean;
+export declare function isRunSteerAttentionEvent(event: RunAttentionEvent): boolean;
+export declare function retryRunAttentionEvent(state: RunUiObservationState, event: Pick<RunAttentionEvent, "id" | "stateDir">): void;
 export declare function shouldSendRunAttentionFollowUp(event: RunAttentionEvent): boolean;
 export declare function formatRunAttentionMessage(event: RunAttentionEvent): string;
 export declare function getRunTransitionNotificationType(transition: RunTransition): RunTransitionNotificationType;
 export declare function shouldNotifyRunTransition(transition: RunTransition): boolean;
-export declare function shouldSendRunTransitionFollowUp(transition: RunTransition): boolean;
+/** Build exact immutable generation members for owner-journal admission. */
+export declare function collectRunCompletionBatchMembers(transitions: RunTransition[]): RunCompletionBatchMember[];
 export declare function formatRunTransitionMessage(transition: RunTransition): string;

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

@@ -35,52 +35,6 @@ export function readRunUiSnapshot(state, ownerId, options = {}) {
 export function pruneRunUiObservationState(state, snapshot) {
     pruneRunObservationState(state.observed, state.legacyEventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.attentionEventIds);
 }
-export function deliverRunTransitionNotifications(transitions, sink, inFlight = new Set()) {
-    for (const transition of transitions) {
-        if (!shouldNotifyRunTransition(transition))
-            continue;
-        const key = transition.stateDir ?? transition.run;
-        if (inFlight.has(key))
-            continue;
-        inFlight.add(key);
-        try {
-            const text = formatRunTransitionMessage(transition);
-            sink.notify(text, getRunTransitionNotificationType(transition));
-            if (!shouldSendRunTransitionFollowUp(transition))
-                continue;
-            sink.sendFollowUp({
-                customType: "pi-actors-run",
-                content: text,
-                display: false,
-                details: transition,
-            });
-            if (transition.stateDir) {
-                AsyncRuns.markRunTerminalNotificationHandled(transition.stateDir, transition.to);
-            }
-        }
-        catch (error) {
-            if (transition.stateDir) {
-                AsyncRuns.recordRunTerminalDeliveryFailure(transition.stateDir, transition.to, error);
-            }
-            const message = error instanceof Error ? error.message : String(error);
-            sink.notify(`Actor terminal delivery failed for run:${transition.run}: ${message.replaceAll(/\s+/g, " ").slice(0, 240)}`, "error");
-        }
-        finally {
-            inFlight.delete(key);
-        }
-    }
-}
-export function reconcileRunTerminalNotifications(input) {
-    const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
-        includeAttention: input.includeAttention,
-        stateRoot: input.stateRoot,
-    });
-    if (input.includeAttention)
-        deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
-    deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
-    pruneRunUiObservationState(input.state, snapshot);
-    return snapshot;
-}
 export function deliverRunAttentionNotifications(events, sink) {
     for (const event of events) {
         if (!shouldNotifyRunAttentionEvent(event))
@@ -271,11 +225,18 @@ function getProgress(status) {
 }
 function getUpdatedAt(status) {
     const progress = getProgress(status);
-    return typeof progress.updatedAt === "string"
-        ? progress.updatedAt
-        : typeof status.createdAt === "string"
-            ? status.createdAt
-            : undefined;
+    const result = status.result &&
+        typeof status.result === "object" &&
+        !Array.isArray(status.result)
+        ? status.result
+        : {};
+    return typeof result.completed_at === "string"
+        ? result.completed_at
+        : typeof progress.updatedAt === "string"
+            ? progress.updatedAt
+            : typeof status.createdAt === "string"
+                ? status.createdAt
+                : undefined;
 }
 function scanRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
     if (!existsSync(stateRoot) || seen.has(stateRoot))
@@ -409,6 +370,9 @@ function observeRun(stateDir) {
             ...(typeof status.recipe_file === "string"
                 ? { recipeFile: status.recipe_file }
                 : {}),
+            ...(typeof status.run_instance_id === "string"
+                ? { runInstanceId: status.run_instance_id }
+                : {}),
             ...(status.terminal_handled ? { terminalHandled: true } : {}),
             ...(typeof status.retire_when === "string"
                 ? { retireWhen: status.retire_when }
@@ -725,8 +689,10 @@ export function detectRunTransitions(previous, summary) {
                 ...(run.launchSource ? { launchSource: run.launchSource } : {}),
                 ...(run.modelPolicy ? { modelPolicy: run.modelPolicy } : {}),
                 ...(run.recipeFile ? { recipeFile: run.recipeFile } : {}),
+                ...(run.runInstanceId ? { runInstanceId: run.runInstanceId } : {}),
                 ...(run.semanticResult ? { semanticResult: run.semanticResult } : {}),
                 ...(run.terminalHandled ? { terminalHandled: true } : {}),
+                ...(run.updatedAt ? { terminalAt: run.updatedAt } : {}),
                 to: run.status,
                 ...(run.tool ? { tool: run.tool } : {}),
             });
@@ -761,7 +727,9 @@ function parseAttentionRecord(raw, run, index) {
     return {
         ...(raw.body !== undefined ? { body: raw.body } : {}),
         ...(raw.data !== undefined ? { data: raw.data } : {}),
-        attention: raw.attention === "notify" || raw.attention === "followup"
+        attention: raw.attention === "notify" ||
+            raw.attention === "followup" ||
+            raw.attention === "steer"
             ? raw.attention
             : normalizeTraceAttention(raw.delivery),
         id,
@@ -773,6 +741,7 @@ function parseAttentionRecord(raw, run, index) {
             ? { metadata: raw.metadata }
             : {}),
         run: run.run,
+        ...(run.runInstanceId ? { runInstanceId: run.runInstanceId } : {}),
         stateDir: run.stateDir,
         summary,
         ts,
@@ -811,6 +780,15 @@ export function detectRunAttentionEvents(legacyLineCounts, summary, seenEventIds
         const read = readTraceAttentionRecords(run);
         const retained = new Set();
         const seen = seenEventIds.get(key) ?? new Set();
+        const presentedSteerIds = new Set(read.records.flatMap((record) => {
+            if (record.kind !== "delivery.steer_presented" ||
+                !record.data ||
+                typeof record.data !== "object" ||
+                Array.isArray(record.data))
+                return [];
+            const eventId = record.data.event_id;
+            return typeof eventId === "string" && eventId ? [eventId] : [];
+        }));
         const start = read.canonical ? 0
             : Math.min(legacyLineCounts.get(key) ?? 0, read.records.length);
         for (const [index, record] of read.records.entries()) {
@@ -819,8 +797,16 @@ export function detectRunAttentionEvents(legacyLineCounts, summary, seenEventIds
                 event.kind === "runtime.trace_compacted")
                 continue;
             retained.add(event.id);
-            if (prime || run.notificationPolicy === "silent")
+            if (isRunSteerAttentionEvent(event) && presentedSteerIds.has(event.id)) {
                 seen.add(event.id);
+                continue;
+            }
+            if (run.notificationPolicy === "silent")
+                seen.add(event.id);
+            else if (prime) {
+                if (!isRunSteerAttentionEvent(event))
+                    seen.add(event.id);
+            }
             else if (index >= start && !seen.has(event.id)) {
                 events.push(event);
                 seen.add(event.id);
@@ -838,7 +824,17 @@ export function getRunAttentionNotificationType(event) {
     return event.level;
 }
 export function shouldNotifyRunAttentionEvent(event) {
-    return event.attention === "notify" || event.attention === "followup";
+    if (event.kind === "command.done")
+        return false;
+    return event.attention === "notify" ||
+        event.attention === "followup" ||
+        event.attention === "steer";
+}
+export function isRunSteerAttentionEvent(event) {
+    return event.kind !== "command.done" && event.attention === "steer";
+}
+export function retryRunAttentionEvent(state, event) {
+    state.attentionEventIds.get(event.stateDir)?.delete(event.id);
 }
 export function shouldSendRunAttentionFollowUp(event) {
     return event.attention === "followup";
@@ -925,8 +921,37 @@ export function shouldNotifyRunTransition(transition) {
         transition.to === "killed" ||
         transition.to === "exited");
 }
-export function shouldSendRunTransitionFollowUp(transition) {
-    return shouldNotifyRunTransition(transition);
+/** Build exact immutable generation members for owner-journal admission. */
+export function collectRunCompletionBatchMembers(transitions) {
+    return transitions.flatMap((transition) => {
+        if (!shouldNotifyRunTransition(transition) ||
+            !transition.stateDir ||
+            !transition.runInstanceId ||
+            !transition.terminalAt ||
+            Number.isNaN(Date.parse(transition.terminalAt)))
+            return [];
+        const artifactEntries = Object.entries(transition.artifacts ?? {})
+            .filter((entry) => typeof entry[1] === "string" && Boolean(entry[1]))
+            .slice(0, 4);
+        const rawSummary = transition.semanticResult?.summary.trim() ||
+            `Run ${transition.to}.`;
+        return [{
+                ...(artifactEntries.length > 0
+                    ? { artifacts: Object.fromEntries(artifactEntries) }
+                    : {}),
+                run: transition.run,
+                run_instance_id: transition.runInstanceId,
+                state_dir: transition.stateDir,
+                status: transition.to,
+                summary: rawSummary.length > 1_000
+                    ? `${rawSummary.slice(0, 999)}…`
+                    : rawSummary,
+                terminal_at: transition.terminalAt,
+            }];
+    }).sort((left, right) => left.terminal_at.localeCompare(right.terminal_at) ||
+        left.run.localeCompare(right.run) ||
+        left.run_instance_id.localeCompare(right.run_instance_id) ||
+        left.state_dir.localeCompare(right.state_dir));
 }
 const TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT = 4;
 const TERMINAL_FOLLOW_UP_IDENTIFIER_CHARS = 120;

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

@@ -4,7 +4,10 @@
  * Owns direct pi SDK imports and exposes narrow pi-actors-facing helpers/types for the composition root.
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import * as SessionEvidence from "./session-evidence.ts";
 export type { ExtensionAPI, ExtensionContext };
+export declare const RUN_COMPLETION_BATCH_CUSTOM_TYPE = "pi-actors-run-batch";
+export declare const RUN_STEER_CUSTOM_TYPE = "pi-actors-run-steer";
 export interface PiNotificationSink {
     notify(message: string, level: "info" | "warning" | "error"): void;
     sendFollowUp(message: {
@@ -16,4 +19,32 @@ export interface PiNotificationSink {
 }
 export declare function getSessionId(ctx: ExtensionContext): string;
 export declare function createNotificationSink(pi: ExtensionAPI, ctx: ExtensionContext): PiNotificationSink;
+export declare function sendRunCompletionBatch(pi: ExtensionAPI, batchId: string, content: string): void;
+export declare function sendRunSteer(pi: ExtensionAPI, input: {
+    content: string;
+    eventId: string;
+    steerId: string;
+}): void;
+/** Collapse exact retry duplicates and remove conflicting delivery envelopes. */
+export declare function dedupeRunCompletionBatchContext(messages: unknown[]): {
+    batches: Map<string, string>;
+    conflicts: Set<string>;
+    messages: unknown[];
+};
+export declare function removeRunCompletionBatchFromContext(messages: unknown[], batchId: string): unknown[];
+export declare function dedupeRunSteerContext(messages: unknown[]): {
+    conflicts: Set<string>;
+    messages: unknown[];
+    steers: Map<string, {
+        content: string;
+        eventId: string;
+    }>;
+};
+export declare function removeRunSteerFromContext(messages: unknown[], steerId: string): unknown[];
+export declare function inspectRunSteerSessionEvidence(ctx: ExtensionContext, input: {
+    content: string;
+    eventId: string;
+    steerId: string;
+}): SessionEvidence.ActiveSessionEntryEvidence;
+export declare function inspectRunCompletionBatchSessionEvidence(ctx: ExtensionContext, batchId: string, content: string): SessionEvidence.ActiveSessionEntryEvidence;
 export declare function registerToolDefinitions(pi: ExtensionAPI, definitions: Iterable<unknown>): void;