@llblab/pi-actors 0.51.0 → 0.52.0

package/dist/skills/swarm/SKILL.md

@@ -15,7 +15,7 @@ A swarm can be coordinated without an external gateway. In this model the curren
 
 This resembles gateway orchestration in dependency direction but not in ownership: the coordinator is itself an agent instance with inspectable Runs, not an infrastructure service that implicitly creates sessions. Preserve that distinction in prompts, docs, recovery, and target routing.
 
-Once work is delegated, keep the coordinator available for decisions and integration instead of duplicating participant implementation. Wait for terminal follow-up by default; use meaningful attention or evidence-based timers for overdue work rather than a tight inspection loop.
+Once work is delegated, keep the coordinator available for decisions and integration instead of duplicating participant implementation. Wait for the settled completion batch by default; use meaningful attention or evidence-based timers for overdue work rather than a tight inspection loop.
 
 ## Reasoning allocation
 

package/docs/README.md

@@ -7,6 +7,7 @@ Living index of all documentation in the `/docs` directory.
 - [command-templates.md](./command-templates.md) — Portable synchronous command execution standard
 - [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
+- [coordinator-delivery.md](./coordinator-delivery.md) — Accepted next-minor design for durable terminal batching and explicit urgent Pi steering
 - [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

package/docs/async-runs.md

@@ -54,11 +54,12 @@ Trace records strict bounded events:
 ```json
 {"id":"…","ts":"…","kind":"command.done","summary":"Command completed","data":{"code":0},"level":"info"}
 {"id":"…","ts":"…","kind":"checkpoint.ready","summary":"Review needs a decision","level":"info","attention":"followup"}
+{"id":"…","ts":"…","kind":"checkpoint.blocked","summary":"Approval required before migration","level":"warning","attention":"steer"}
 ```
 
 Required fields: `id`, `ts`, `kind`. Optional fields: `summary`, `data`, `level`, `attention`. Trace rejects addressed-envelope fields and malformed or oversized data. It retains a recent suffix within 2,048 events and 4 MiB. When either bound would be exceeded, the canonical lock atomically keeps a newest suffix near the lower targets, the new event, and one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; it reports cumulative drop evidence and never requests attention.
 
-Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve level, captures, session provenance, and execution evidence but never request or project attention. No Recipe field configures command-completion delivery. Semantic checkpoints opt in explicitly with `attention: "notify"` or `attention: "followup"`; they must not infer coordinator intent from a leaf exit code. Bounded reads preserve complete UTF-8 lines and disclose omitted legacy prefixes. `inspect view=trace` reports retained-history completeness and projects events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics newest-first. Equal timestamps use same-source physical order, then fixed source rank and stable id without claiming cross-source causality. Terminal state, `result.json`, `execution.json`, and artifacts remain authoritative even when old Trace has compacted.
+Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve level, captures, session provenance, and execution evidence but never request or project attention, even if malformed legacy evidence carries `steer`. No Recipe field configures command-completion delivery. Semantic checkpoints opt in explicitly: `attention: "notify"` is visible status, `attention: "followup"` supplies ordinary checkpoint context, and `attention: "steer"` requests urgent delivery at Pi's next safe assistant/tool boundary. Steer is never inferred from exit status; its exact Run generation and event id enter the bounded owner journal before Pi delivery, recover through owned session evidence, and require exact model-bound context acknowledgment. Presentation appends a generation-fenced non-attention `delivery.steer_presented` Trace marker so historical retained steer events cannot replay after bounded owner receipts rotate. The eventual root terminal remains independently eligible for its completion batch. Bounded reads preserve complete UTF-8 lines and disclose omitted legacy prefixes. `inspect view=trace` reports retained-history completeness and projects events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics newest-first. Equal timestamps use same-source physical order, then fixed source rank and stable id without claiming cross-source causality. Terminal state, `result.json`, `execution.json`, and artifacts remain authoritative even when old Trace has compacted.
 
 ## Control
 
@@ -109,9 +110,9 @@ Statuses include `running`, `done`, `failed`, `exited`, `cancelled`, and `killed
 
 Ambient observation detects root terminal transitions and explicit retained Trace attention. Terminal transitions reconcile before semantic attention. Canonical attention is an in-memory wake hint, not a durable queue: observers prime retained ids at startup, deliver each later retained unseen id once, and bound memory to the current retained set across compaction. Persist durable recovery state or an artifact before emitting attention; compaction may discard older hints and its marker makes that history loss explicit. Terminal follow-up delivery persists handled/failure evidence so reloads retry unhandled transitions without duplicating completed notifications.
 
-By default, one normal finite Run produces exactly one automatic agent turn from its root terminal result. Sequence, parallel, repeat, and imported branches are internal execution topology and never own branch-level turns. Each separately launched Run owns its own generation and terminal lifecycle; compatible singleton reuse is not a new launch. Explicit semantic attention may intentionally add a checkpoint turn; Runs marked silent suppress automatic projection.
+Ordinary finite Runs project root terminal results through one completion scheduler. Eligible terminals remain authoritative in Run state while Pi is active; after `agent_settled`, session recovery, or an idle debounce, the scheduler snapshots at most 256 exact generations into one owner-fenced immutable batch. One batch causes one automatic agent turn, exposes at most 64 bounded model-facing rows, and marks member terminals handled only after the exact batch id and content appear in model-bound Pi context. Pending send failures retain bounded retry evidence. On restart, queued recovery inspects only a bounded active Pi session parent chain: exact message evidence waits for presentation without resend, proven absence returns the same batch to pending, and incomplete or conflicting evidence stays queued with a diagnostic. Duplicate exact context envelopes collapse before presentation.
 
-Large semantic results stay outside compact visible follow-up text and remain available in structured details, execution captures, or artifacts.
+Sequence, parallel, repeat, and imported branches are internal execution topology and never own branch-level turns. Each separately launched Run owns its own generation and terminal lifecycle; compatible singleton reuse is not a new launch. Explicit semantic attention may intentionally add a checkpoint turn; Runs marked silent and synchronously acknowledged stop outcomes suppress automatic projection. Large semantic results stay outside compact completion rows and remain available in structured details, execution captures, or artifacts.
 
 ## Cancellation and Kill
 

package/docs/coordinator-delivery.md

@@ -0,0 +1,207 @@
+# Coordinator Delivery Scheduler
+
+Status: Accepted next-minor design. Implementation is in progress; public delivery behavior remains unchanged until the complete acceptance boundary passes.
+
+## Goal
+
+Separate durable Run completion truth from the scheduling of model turns:
+
+```text
+one Run generation -> one root terminal record
+one bounded completion epoch -> one coordinator turn
+```
+
+Ordinary root terminals accumulate while Pi is active and reach the coordinator in one bounded batch after Pi settles. Only an explicitly actor-authored urgent semantic checkpoint may steer an active agent loop.
+
+## Non-Goals
+
+- Do not interrupt generation mid-token.
+- Do not stream generic progress or Command lifecycle into model context.
+- Do not infer urgency from exit codes, failure status, artifacts, branch position, or active subagent counts.
+- Do not change Run, Recipe, Trace, Control, artifact, generation, ownership, or Inspect authority.
+- Do not add transport-specific behavior or restore Recipe-level Command delivery grammar.
+
+## Delivery Classes
+
+- Generic Trace and runner-owned `command.done` remain Trace-only.
+- `attention: "notify"` remains visible UI status without a model turn.
+- `attention: "followup"` retains its existing explicit semantic follow-up behavior.
+- New `attention: "steer"` requests urgent semantic delivery at Pi's next safe assistant/tool boundary.
+- Root terminal transitions enter durable completion batching instead of sending one follow-up per Run.
+
+`command.done` remains non-projectable even if malformed or legacy Trace attaches any attention value.
+
+## Ownership
+
+- Run terminal state remains completion truth; the absence of `terminal-handled.json` makes that generation eligible for projection.
+- `runs-trace.ts` owns admission of the new `steer` attention value.
+- `observability.ts` discovers terminal candidates and explicit semantic attention without deciding Pi delivery timing.
+- A new `run-delivery.ts` domain owns the owner-scoped delivery journal, batch construction, bounds, phases, formatting, recovery, and acknowledgments.
+- `run-ui-runtime.ts` owns idle detection, debounce, reconciliation, flushing, and stale-context containment.
+- `extension-runtime.ts` orders completion flushes before automatic Recipe review.
+- `index.ts` remains a thin registration root and adds only the required Pi lifecycle adapter.
+- `pi.ts` exposes narrow ports for batched follow-up and urgent steer delivery.
+
+The local TypeScript dependency graph must remain acyclic. No public tool, target, view, Recipe field, or transport contract is added by default.
+
+## Durable Delivery State
+
+Store one journal per exact coordinator owner under an internal path derived from a safe owner hash:
+
+```text
+<extension-temp>/delivery/<owner-hash>/projection.json
+```
+
+The journal records the exact internal owner and contains at most one active completion batch plus a bounded set of unpresented urgent steer envelopes.
+
+Completion batch shape:
+
+```json
+{
+  "batch_id": "uuid",
+  "owner_id": "exact internal owner",
+  "phase": "pending",
+  "members": [
+    {
+      "run": "review-a",
+      "run_instance_id": "generation-id",
+      "status": "done",
+      "state_dir": "internal path"
+    }
+  ],
+  "created_at": "timestamp"
+}
+```
+
+Phases are monotonic:
+
+1. `pending`: The exact member snapshot is durable but no Pi message has been accepted.
+2. `queued`: Pi accepted a custom message carrying the exact batch or steer ID.
+3. `presented`: A Pi `context` event observed that ID in messages being supplied to an LLM call.
+
+Every journal mutation uses the canonical token-owned lock, expected-phase fencing, owner and generation validation, and atomic replacement. Repeated transitions are idempotent. Corrupt, oversized, foreign-owner, or stale-generation state fails closed with bounded diagnostics.
+
+A queued envelope is not treated as presented merely because `sendMessage()` returned. Only presentation marks completion members through their existing terminal-handled authority. If a member was synchronously archived or pruned after queueing, the bounded delivery snapshot remains sufficient and the missing state write becomes a diagnostic rather than invalidating the batch.
+
+## Completion Collection
+
+Reconciliation admits unhandled root terminal generations with status `done`, `failed`, `killed`, or `exited`.
+
+It excludes:
+
+- Runs with silent notification policy;
+- synchronous stop or cancel outcomes already acknowledged by their caller;
+- handled terminal generations;
+- internal composition branches;
+- every Command lifecycle event.
+
+Candidates sort by terminal timestamp, then stable Run identity, then `run_instance_id`. Replacement generations with the same logical Run id remain distinct internal members.
+
+While `ctx.isIdle()` is false, candidates remain durable in their Run state and no terminal follow-up is sent. A flush snapshots eligible candidates into one immutable batch. While that batch remains unpresented, newer terminals stay unhandled for the next bounded completion epoch.
+
+## Batch Flush
+
+Flush one batch when:
+
+1. `agent_settled` fires for the still-active context and `ctx.isIdle()` remains true;
+2. terminals arrive while Pi is already idle and survive one short debounce window;
+3. session restoration discovers unhandled terminal generations or recoverable queued delivery state.
+
+The model-facing custom message uses `customType: "pi-actors-run-batch"`, `deliverAs: "followUp"`, and `triggerTurn: true`. It includes:
+
+- batch ID and completion window;
+- counts by terminal status;
+- stable Run, status, compact semantic summary, and bounded artifact rows;
+- explicit overflow evidence and the canonical runtime Inspect route.
+
+The journal may retain at most 256 members and 1 MiB. Model-facing content lists at most 64 exact rows within the centralized model-output bound. Additional members remain represented by exact status counts and supported Inspect guidance. More than 256 unhandled generations form a later batch rather than being discarded.
+
+Completion member details remain redacted through existing terminal projection rules: no raw model policy, secrets, private Recipe paths, or machine-local source paths enter the message.
+
+## Presentation Acknowledgment And Recovery
+
+Register a `context` lifecycle adapter that scans model-bound messages for exact pi-actors batch and steer IDs. On a matching active-owner envelope it atomically:
+
+1. moves the envelope to `presented`;
+2. marks every still-present member generation terminal-handled;
+3. records a non-attention `delivery.steer_presented` marker in the exact Run generation for a presented steer;
+4. retains a bounded owner receipt sufficient for near-term deduplication and diagnostics.
+
+The generation-fenced Trace marker prevents a retained historical steer from replaying after bounded owner receipts rotate: suffix compaction cannot retain the older steer while discarding its newer presentation marker. Missing, archived, pruned, or replaced Run state needs no marker because it can no longer replay that original generation.
+
+Recovery rules:
+
+- Send failure: keep `pending`, record failure evidence, and retry.
+- Crash after queueing: inspect existing owned Pi session evidence for the exact custom message ID.
+- Queued message exists: do not resend; wait for `context` presentation.
+- Queued message is absent: return the envelope to `pending`.
+- Presented envelope: never resend.
+- Session or context replacement: close timers and callbacks; never deliver through stale context.
+- Owner mismatch: do not inspect, acknowledge, or deliver the envelope.
+
+Session evidence inspection must reuse the existing bounded owned-session readers rather than adding raw unbounded session parsing.
+
+## Explicit Urgent Steer
+
+Extend canonical Trace attention with `"steer"`:
+
+```json
+{
+  "kind": "checkpoint.blocked",
+  "summary": "Approval required before destructive migration",
+  "attention": "steer"
+}
+```
+
+A steer event is:
+
+- explicit and actor-authored;
+- admitted to the durable owner delivery journal before Pi delivery;
+- sent through `deliverAs: "steer"` with `triggerTurn: true`;
+- presented only when its exact event ID appears in model-bound `context`;
+- retried after delivery failure without duplicate presentation;
+- independent from the eventual root-terminal batch.
+
+Pi steering is a safe-boundary continuation, not token-level interruption: while streaming, Pi delivers it after the current assistant turn finishes its tool calls and before the next LLM call. If Pi is idle, it triggers a new turn immediately.
+
+Urgent steer capacity is bounded to 64 unpresented envelopes within the same 1 MiB owner journal. Capacity pressure remains visible and retryable; it never degrades into generic follow-up or drops an admitted envelope silently.
+
+## Settled Lifecycle Ordering
+
+`onAgentSettled` must use this order:
+
+```text
+active-context and exact-owner check
+-> completion flush
+-> if a batch was sent, defer automatic Recipe review
+-> batch-triggered model run settles
+-> schedule automatic review only when no batch remains
+```
+
+Another extension may start work during `agent_settled`; recheck `ctx.isIdle()` immediately before sending. A completion/settled race places each generation in either the current immutable batch or the next batch, never both.
+
+## Validation Contract
+
+Implementation is complete only when source and packed-extension tests prove:
+
+1. Multiple Runs finishing during one agent run cause no immediate terminal turns and one settled batch.
+2. Idle completions inside the debounce window form one batch.
+3. Completion/settled races project every generation exactly once.
+4. Send failure and restart before queueing retry without a handled marker.
+5. Restart after queueing but before presentation neither loses nor duplicates the batch.
+6. Exact `context` presentation acknowledges members atomically and idempotently.
+7. Replacement generations sharing a Run id remain distinct.
+8. Silent, stopped, cancelled, handled, and foreign-owner Runs remain excluded.
+9. Legacy or malformed `command.done` attention, including `steer`, remains non-projectable.
+10. Explicit steer reaches the next safe Pi boundary once and root terminal still batches later.
+11. Overflow, corruption, journal backpressure, archive/prune races, and stale contexts fail safely.
+12. Completion flushing precedes automatic Recipe review.
+13. Pi 0.84.4 remains the exact minimum source and packed lifecycle baseline.
+
+Focused observability and delivery tests precede TypeScript/build/import checks. The acceptance checkpoint then runs full product validation, dependency audit, package dry-run, and ABCd context validation.
+
+## Rollout
+
+This is one minor release because durable batching, presentation acknowledgment, lifecycle ordering, and explicit steer share one model-delivery invariant. Do not ship partial batching that marks terminals handled at `sendMessage()` acceptance, and do not ship steer before its durable deduplication path exists.
+
+Update README and Run documentation only when implementation establishes the new public behavior. Move the accepted outcome from BACKLOG to CHANGELOG only after complete validation.

package/index.ts

@@ -15,6 +15,9 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   );
   pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
   pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
+  pi.on("context", async (event, ctx) => ({
+    messages: runtime.onContext(event.messages, ctx) as typeof event.messages,
+  }));
   pi.on("session_shutdown", async (event, ctx) =>
     runtime.onSessionShutdown(event.reason, ctx),
   );

package/lib/async-runs.ts

@@ -1136,30 +1136,51 @@ function stopRun(
 export function markRunTerminalNotificationHandled(
   stateDir: string,
   status: string,
-): void {
-  markTerminalHandled(stateDir, {
-    event: "run.notification",
-    status,
-  });
+  expectedRunInstanceId: string,
+): boolean {
+  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(
+export function markRunSteerPresentationHandled(
   stateDir: string,
-  status: string,
-  error: unknown,
-): void {
-  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(),
-  });
+  expectedRunInstanceId: string,
+  eventId: string,
+  steerId: string,
+): boolean {
+  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(

package/lib/extension-runtime.ts

@@ -26,6 +26,7 @@ export interface ActorExtensionRuntime {
   discoverResources(metaUrl: string): { skillPaths: string[] } | undefined;
   getRunOwnerId(ctx: Pi.ExtensionContext): string;
   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;
@@ -142,7 +143,11 @@ export function createActorExtensionRuntime(
     },
     getRunOwnerId,
     onAgentSettled(ctx) {
-      if (activeRunContext === ctx) automaticReview.schedule();
+      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);

package/lib/limits.ts

@@ -28,3 +28,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/lib/observability.ts

@@ -26,6 +26,7 @@ import {
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
 import * as RunsTrace from "./runs-trace.ts";
+import type { RunCompletionBatchMember } from "./run-delivery.ts";
 import { readJsonlFileResilient } from "./state-readers.ts";
 
 export type RunObservedStatus =
@@ -35,7 +36,7 @@ export type RunObservedStatus =
   | "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 {
@@ -53,6 +54,7 @@ export interface RunObservation {
   terminalHandled?: boolean;
   retireWhen?: string;
   run: string;
+  runInstanceId?: string;
   semanticResult?: RunTerminalSemanticResult;
   tool?: string;
   stateDir?: string;
@@ -149,70 +151,6 @@ export function pruneRunUiObservationState(
   );
 }
 
-export function deliverRunTransitionNotifications(
-  transitions: RunTransition[],
-  sink: RunUiNotificationSink,
-  inFlight: Set<string> = new Set(),
-): void {
-  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: {
-  inFlight?: Set<string>;
-  ownerId: string;
-  sink: RunUiNotificationSink;
-  state: RunUiObservationState;
-  stateRoot?: string;
-  includeAttention?: boolean;
-}): RunUiSnapshot {
-  const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
-    includeAttention: input.includeAttention,
-    stateRoot: input.stateRoot,
-  });
-  deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
-  if (input.includeAttention)
-    deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
-  pruneRunUiObservationState(input.state, snapshot);
-  return snapshot;
-}
-
 export function deliverRunAttentionNotifications(
   events: RunAttentionEvent[],
   sink: RunUiNotificationSink,
@@ -447,7 +385,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;
@@ -477,6 +417,7 @@ export interface RunAttentionEvent {
   level: RunTraceLevel;
   metadata?: Record<string, unknown>;
   run: string;
+  runInstanceId?: string;
   stateDir: string;
   summary: string;
   ts: string;
@@ -513,11 +454,18 @@ function getProgress(status: Record<string, unknown>): Record<string, unknown> {
 
 function getUpdatedAt(status: Record<string, unknown>): string | undefined {
   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 as Record<string, unknown>
+    : {};
+  return typeof result.completed_at === "string"
+    ? result.completed_at
+    : typeof progress.updatedAt === "string"
+      ? progress.updatedAt
+      : typeof status.createdAt === "string"
+        ? status.createdAt
+        : undefined;
 }
 
 function scanRunStateDirs(
@@ -658,6 +606,9 @@ function observeRun(stateDir: string): RunObservation | undefined {
       ...(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 }
@@ -1060,8 +1011,10 @@ export function detectRunTransitions(
         ...(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 } : {}),
       });
@@ -1107,7 +1060,9 @@ function parseAttentionRecord(
     ...(raw.body !== undefined ? { body: raw.body } : {}),
     ...(raw.data !== undefined ? { data: raw.data } : {}),
     attention:
-      raw.attention === "notify" || raw.attention === "followup"
+      raw.attention === "notify" ||
+      raw.attention === "followup" ||
+      raw.attention === "steer"
         ? raw.attention
         : normalizeTraceAttention(raw.delivery),
     id,
@@ -1119,6 +1074,7 @@ function parseAttentionRecord(
       ? { metadata: raw.metadata as Record<string, unknown> }
       : {}),
     run: run.run,
+    ...(run.runInstanceId ? { runInstanceId: run.runInstanceId } : {}),
     stateDir: run.stateDir,
     summary,
     ts,
@@ -1167,6 +1123,16 @@ export function detectRunAttentionEvents(
     const read = readTraceAttentionRecords(run);
     const retained = new Set<string>();
     const seen = seenEventIds.get(key) ?? new Set<string>();
+    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 as Record<string, unknown>).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()) {
@@ -1174,8 +1140,14 @@ export function detectRunAttentionEvents(
       if (!event || !shouldNotifyRunAttentionEvent(event) ||
           event.kind === "runtime.trace_compacted") continue;
       retained.add(event.id);
-      if (prime || run.notificationPolicy === "silent") seen.add(event.id);
-      else if (index >= start && !seen.has(event.id)) {
+      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);
       }
     }
@@ -1194,7 +1166,20 @@ export function getRunAttentionNotificationType(
 
 export function shouldNotifyRunAttentionEvent(event: RunAttentionEvent): boolean {
   if (event.kind === "command.done") return false;
-  return event.attention === "notify" || event.attention === "followup";
+  return event.attention === "notify" ||
+    event.attention === "followup" ||
+    event.attention === "steer";
+}
+
+export function isRunSteerAttentionEvent(event: RunAttentionEvent): boolean {
+  return event.kind !== "command.done" && event.attention === "steer";
+}
+
+export function retryRunAttentionEvent(
+  state: RunUiObservationState,
+  event: Pick<RunAttentionEvent, "id" | "stateDir">,
+): void {
+  state.attentionEventIds.get(event.stateDir)?.delete(event.id);
 }
 
 export function shouldSendRunAttentionFollowUp(event: RunAttentionEvent): boolean {
@@ -1297,10 +1282,43 @@ export function shouldNotifyRunTransition(transition: RunTransition): boolean {
   );
 }
 
-export function shouldSendRunTransitionFollowUp(
-  transition: RunTransition,
-): boolean {
-  return shouldNotifyRunTransition(transition);
+/** Build exact immutable generation members for owner-journal admission. */
+export function collectRunCompletionBatchMembers(
+  transitions: RunTransition[],
+): RunCompletionBatchMember[] {
+  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): entry is [string, string] =>
+        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 as RunCompletionBatchMember["status"],
+      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;