@llblab/pi-actors 0.42.0 → 0.42.2

package/lib/inspector-overlay.ts

@@ -69,7 +69,8 @@ export class ActorInspectorOverlay {
   private detailScroll = 0;
   private detailTurn?: Inspector.ActorInspectorTurnItem;
   private feedback?: ActorInspectorOverlayActionResult;
-  private killConfirmation?: { run: string; runInstanceId: string };
+  private killConfirmation?: { run: string; runInstanceId: string; status: string };
+  private killDialogChoice: "cancel" | "kill" = "cancel";
   private readonly readKeys = new Set<string>();
   private focus: "runs" | "tabs" | "recipe" | "list" | "detail" | "select" = "tabs";
   private filterControlIndex = 0;
@@ -105,11 +106,21 @@ export class ActorInspectorOverlay {
       return;
     }
     if (this.killConfirmation) {
-      if (matchesKey(data, "escape") || data.toLowerCase() === "n") {
-        this.feedback = { ok: false, message: "Kill cancelled." };
-        this.killConfirmation = undefined;
-      } else if (matchesKey(data, "return") || data.toLowerCase() === "y") {
+      const key = data.toLowerCase();
+      if (matchesKey(data, "escape") || key === "n") {
+        this.cancelKill();
+      } else if (
+        matchesKey(data, "left") ||
+        matchesKey(data, "right") ||
+        matchesKey(data, "tab")
+      ) {
+        this.killDialogChoice =
+          this.killDialogChoice === "cancel" ? "kill" : "cancel";
+      } else if (key === "y") {
         this.confirmKill();
+      } else if (matchesKey(data, "return")) {
+        if (this.killDialogChoice === "kill") this.confirmKill();
+        else this.cancelKill();
       }
       this.tui.requestRender();
       return;
@@ -215,6 +226,8 @@ export class ActorInspectorOverlay {
     this.ensureSelectedRun(this.runs());
     const safeWidth = Math.max(24, width);
     const innerWidth = Math.max(1, safeWidth - 2);
+    if (this.killConfirmation)
+      return this.renderKillDialog(safeWidth, innerWidth);
     const lines: string[] = [];
     lines.push(this.border("╭", " Actor Inspector ", "╮", innerWidth));
     lines.push(this.row(this.renderRunControl(), innerWidth));
@@ -257,13 +270,11 @@ export class ActorInspectorOverlay {
         Math.max(0, innerWidth - visibleWidth(selectorTop) - selectorAnchor),
       );
       lines.push(
-        `${this.theme.fg("border", `├${leadingBorder}`)}${selectorTop}${this.theme.fg("border", `${remainingBorder}┤`)}`,
+        `${this.theme.fg("borderAccent", `├${leadingBorder}`)}${selectorTop}${this.theme.fg("borderAccent", `${remainingBorder}┤`)}`,
       );
     } else lines.push(this.border("├", "", "┤", innerWidth));
     this.contentStripeIndices = [];
-    const baseContent = this.killConfirmation
-      ? this.renderKillConfirmation()
-      : this.detailOpen
+    const baseContent = this.detailOpen
         ? this.renderDetail(innerWidth)
         : this.selectedRun
           ? this.renderTimeline(innerWidth)
@@ -311,9 +322,7 @@ export class ActorInspectorOverlay {
       );
       lines.push(this.row(`${leadingBase}${visiblePopup}${preservedBase}`, innerWidth, true));
     }
-    lines.push(this.border("├", "", "┤", innerWidth));
-    lines.push(this.row(this.renderKeyHints(), innerWidth));
-    lines.push(this.border("╰", "", "╯", innerWidth));
+    lines.push(this.footerBorder(this.renderKeyHints(), innerWidth));
     return lines;
   }
 
@@ -333,7 +342,7 @@ export class ActorInspectorOverlay {
 
   private contentViewportRows(): number {
     const overlayRows = Math.floor(this.tui.terminal.rows * 0.94);
-    return Math.max(4, Math.min(16, overlayRows - 7));
+    return Math.max(4, Math.min(24, overlayRows - 5));
   }
 
   private selectRun(run: string, index: number): void {
@@ -392,12 +401,21 @@ export class ActorInspectorOverlay {
     this.killConfirmation = {
       run: run.run,
       runInstanceId: run.runInstanceId,
+      status: run.status,
     };
+    this.killDialogChoice = "cancel";
+  }
+
+  private cancelKill(): void {
+    this.feedback = { ok: false, message: "Kill cancelled." };
+    this.killConfirmation = undefined;
+    this.killDialogChoice = "cancel";
   }
 
   private confirmKill(): void {
     const confirmation = this.killConfirmation;
     this.killConfirmation = undefined;
+    this.killDialogChoice = "cancel";
     if (!confirmation || !this.killRun) {
       this.feedback = { ok: false, message: "Kill unavailable in this Inspector." };
       return;
@@ -416,14 +434,40 @@ export class ActorInspectorOverlay {
     }
   }
 
-  private renderKillConfirmation(): string[] {
-    return [
-      this.theme.fg(
-        "error",
-        ` Kill running actor run:${this.killConfirmation?.run}?`,
-      ),
-      this.theme.fg("muted", " This sends canonical control.kill and cannot be undone."),
+  private renderKillDialog(_width: number, innerWidth: number): string[] {
+    const confirmation = this.killConfirmation!;
+    const totalRows = this.contentViewportRows() + 5;
+    const cancel = this.killDialogChoice === "cancel"
+      ? this.theme.bg("selectedBg", this.theme.fg("accent", "  Cancel  "))
+      : this.theme.fg("muted", "  Cancel  ");
+    const kill = this.killDialogChoice === "kill"
+      ? this.theme.bg("selectedBg", this.theme.fg("error", "  Kill actor  "))
+      : this.theme.fg("error", "  Kill actor  ");
+    const body = [
+      "",
+      this.theme.fg("error", "Kill this running actor?"),
+      "",
+      `${this.theme.fg("muted", "Run:")} ${this.theme.fg("accent", `run:${confirmation.run}`)}`,
+      `${this.theme.fg("muted", "Current status:")} ${this.theme.fg("warning", confirmation.status)}`,
+      "",
+      this.theme.fg("text", "This sends canonical control.kill."),
+      this.theme.fg("error", "The action is destructive and cannot be undone."),
+      "",
+      `${cancel}    ${kill}`,
+      "",
     ];
+    const lines = [this.border("╭", " Confirm Actor Kill ", "╮", innerWidth)];
+    const availableRows = Math.max(1, totalRows - 2);
+    const topPadding = Math.max(0, Math.floor((availableRows - body.length) / 2));
+    const dialogRows = [
+      ...Array.from({ length: topPadding }, () => ""),
+      ...body,
+    ].slice(0, availableRows);
+    while (dialogRows.length < availableRows) dialogRows.push("");
+    for (const line of dialogRows)
+      lines.push(this.row(this.center(line, innerWidth), innerWidth));
+    lines.push(this.footerBorder(this.renderKeyHints(), innerWidth));
+    return lines;
   }
 
   private listItemCount(): number {
@@ -449,27 +493,53 @@ export class ActorInspectorOverlay {
 
   private renderKeyHints(): string {
     const hint = (keys: string, description: string) =>
-      `${this.theme.fg("accent", keys)}${this.theme.fg("dim", ` ${description}`)}`;
+      `${this.theme.fg("accent", keys)}${this.theme.fg("borderAccent", ` ${description}`)}`;
+    const divider = this.theme.fg("borderAccent", " ─ ");
+    const hints = (...items: Array<[string, string]>) =>
+      items.map(([keys, description]) => hint(keys, description)).join(divider);
     if (this.killConfirmation)
-      return ` ${hint("y/enter", "confirm kill")}  ${hint("n/esc", "cancel")}`;
+      return hints(
+        ["←→/tab", "choose"],
+        ["enter/y", "confirm"],
+        ["esc/n", "cancel"],
+      );
     if (this.focus === "select")
       return this.menuLevel === "value"
-        ? ` ${hint("↑↓", "option")}  ${hint("enter", "apply")}  ${hint("←/esc", "back")}`
-        : ` ${hint("↑↓", "option")}  ${hint("→/enter", "open")}  ${hint("←/esc", "back")}`;
+        ? hints(["↑↓", "option"], ["enter", "apply"], ["←/esc", "back"])
+        : hints(["↑↓", "option"], ["→/enter", "open"], ["←/esc", "back"]);
     if (this.focus === "recipe")
-      return ` ${hint("↑↓/pgup/pgdn", "scroll")}  ${hint("↑ at top", "tabs")}  ${hint("←/esc", "tabs")}`;
+      return hints(
+        ["↑↓/pgup/pgdn", "scroll"],
+        ["↑ at top", "tabs"],
+        ["←/esc", "tabs"],
+      );
     if (this.focus === "detail")
-      return ` ${hint("↑↓/pgup/pgdn", "scroll")}  ${hint("←/esc", "back")}`;
+      return hints(["↑↓/pgup/pgdn", "scroll"], ["←/esc", "back"]);
     if (this.focus === "list")
-      return ` ${hint("↑↓/pgup/pgdn", "row")}  ${hint("→/enter", "open")}  ${hint("←", "tabs")}  ${hint("esc", "close")}`;
+      return hints(
+        ["↑↓/pgup/pgdn", "row"],
+        ["→/enter", "open"],
+        ["←", "tabs"],
+        ["esc", "close"],
+      );
     if (this.focus === "runs") {
+      const items: Array<[string, string]> = [
+        ["←→", "run"],
+        ["↓", "tabs"],
+        ["enter", "list"],
+      ];
       const run = this.runs().find((item) => item.run === this.selectedRun);
-      const killHint = this.killRun && run?.status === "running" && run.runInstanceId
-        ? `  ${hint("k", "kill")}`
-        : "";
-      return ` ${hint("←→", "run")}  ${hint("↓", "tabs")}  ${hint("enter", "list")}${killHint}  ${hint("esc", "close")}`;
+      if (this.killRun && run?.status === "running" && run.runInstanceId)
+        items.push(["k", "kill"]);
+      items.push(["esc", "close"]);
+      return hints(...items);
     }
-    return ` ${hint("←→", "navigate")}  ${hint("↑↓", "change row")}  ${hint("enter", "select")}  ${hint("esc", "close")}`;
+    return hints(
+      ["←→", "navigate"],
+      ["↑↓", "change row"],
+      ["enter", "select"],
+      ["esc", "close"],
+    );
   }
 
   private renderRunControl(): string {
@@ -1154,7 +1224,7 @@ export class ActorInspectorOverlay {
     );
     const border = (left: string, right: string, marker = "") =>
       this.theme.fg(
-        "border",
+        "borderAccent",
         `${omitLeftBorder ? "" : left}${marker}${"─".repeat(Math.max(0, contentWidth - visibleWidth(marker)))}${omitRightBorder ? "" : right}`,
       );
     return [
@@ -1169,7 +1239,7 @@ export class ActorInspectorOverlay {
         const styled = focused || index === parentIndex
           ? this.theme.bg("selectedBg", colored)
           : colored;
-        return `${omitLeftBorder ? "" : this.theme.fg("border", "│")}${styled}${omitRightBorder ? "" : this.theme.fg("border", "│")}`;
+        return `${omitLeftBorder ? "" : this.theme.fg("borderAccent", "│")}${styled}${omitRightBorder ? "" : this.theme.fg("borderAccent", "│")}`;
       }),
       border("╰", "╯", hiddenBelow ? "↓" : ""),
     ];
@@ -1239,10 +1309,27 @@ export class ActorInspectorOverlay {
     this.focus = "list";
   }
 
+  private footerBorder(hints: string, width: number): string {
+    const prefix = " ";
+    const suffix = " ─";
+    const content = truncateToWidth(
+      hints,
+      Math.max(0, width - visibleWidth(prefix) - visibleWidth(suffix)),
+      "",
+    );
+    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}╯`)}`;
+  }
+
   private border(left: string, title: string, right: string, width: number): string {
     const titleText = truncateToWidth(title, width, "");
     const fill = "─".repeat(Math.max(0, width - visibleWidth(titleText)));
-    return this.theme.fg("border", `${left}${titleText}${fill}${right}`);
+    return this.theme.fg("borderAccent", `${left}${titleText}${fill}${right}`);
   }
 
   private stripeBackground(content: string, index: number): string {
@@ -1265,7 +1352,7 @@ export class ActorInspectorOverlay {
 
   private row(content: string, width: number, fitted = false): string {
     const body = fitted ? content : this.fit(content, width);
-    return `${this.theme.fg("border", "│")}${body}${this.theme.fg("border", "│")}`;
+    return `${this.theme.fg("borderAccent", "│")}${body}${this.theme.fg("borderAccent", "│")}`;
   }
 
   private takeVisiblePrefix(content: string, width: number): string {
@@ -1293,6 +1380,12 @@ export class ActorInspectorOverlay {
     return plain.slice(index);
   }
 
+  private center(content: string, width: number): string {
+    const contentWidth = visibleWidth(content);
+    const leading = Math.max(0, Math.floor((width - contentWidth) / 2));
+    return `${" ".repeat(leading)}${content}`;
+  }
+
   private fit(content: string, width: number): string {
     // A Component render entry must remain exactly one terminal row. Persisted
     // prompts, messages, and tool results may contain line breaks or tabs;

package/lib/inspector.ts

@@ -248,7 +248,7 @@ export function readActorInspectorTurns(stateDir: string): ActorInspectorTurnIte
             withFileTypes: true,
           })
           .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
-          .map((file) => path.join("sessions", entry.name, file.name))
+          .map((file) => path.posix.join("sessions", entry.name, file.name))
           .filter((file) => !recordedFiles.has(file));
         return files.length > 0
           ? [{ id: entry.name, session_files: files, stage: "subagent" }]

package/lib/observability.ts

@@ -5,9 +5,13 @@
  */
 
 import {
+  closeSync,
   existsSync,
+  fstatSync,
+  openSync,
   readdirSync,
   readFileSync,
+  readSync,
   watch,
   type FSWatcher,
 } from "node:fs";
@@ -17,7 +21,6 @@ import {
   isAbsolute,
   join,
   relative,
-  resolve,
 } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
@@ -41,6 +44,7 @@ export interface RunObservation {
   failures?: number;
   ownerId?: string;
   artifacts?: Record<string, string>;
+  launchCorrelation?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
   modelPolicy?: Record<string, unknown>;
   notificationPolicy?: "normal" | "silent";
@@ -48,6 +52,7 @@ export interface RunObservation {
   terminalHandled?: boolean;
   retireWhen?: string;
   run: string;
+  semanticResult?: RunTerminalSemanticResult;
   tool?: string;
   stateDir?: string;
   status: RunObservedStatus;
@@ -162,6 +167,19 @@ export function deliverRunTransitionNotifications(
           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);
     }
@@ -420,12 +438,23 @@ export interface RunTransition {
   run: string;
   stateDir?: string;
   artifacts?: Record<string, string>;
+  launchCorrelation?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
   modelPolicy?: Record<string, unknown>;
   recipeFile?: string;
   terminalHandled?: boolean;
   to: RunObservedStatus;
   tool?: string;
+  semanticResult?: RunTerminalSemanticResult;
+}
+
+export interface RunTerminalSemanticResult {
+  body?: string;
+  correlationId?: string;
+  metadata: Record<string, unknown>;
+  summary: string;
+  synthesized: boolean;
+  type: string;
 }
 
 export interface RunOutboxEvent {
@@ -504,15 +533,145 @@ function scanRunStateDirs(
   return result;
 }
 
+const TERMINAL_RESULT_BYTES = 8 * 1024;
+const TERMINAL_RESULT_CHARS = 4_000;
+
+function readBoundedStart(path: string): string {
+  if (!existsSync(path)) return "";
+  const fd = openSync(path, "r");
+  try {
+    const size = Math.min(fstatSync(fd).size, TERMINAL_RESULT_BYTES);
+    const buffer = Buffer.alloc(size);
+    const bytes = readSync(fd, buffer, 0, size, 0);
+    const text = buffer.subarray(0, bytes).toString("utf8").trim();
+    return text.length > TERMINAL_RESULT_CHARS
+      ? `${text.slice(0, TERMINAL_RESULT_CHARS - 1)}…`
+      : text;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function semanticBodyFromStdout(stateDir: string): string | undefined {
+  const text = readBoundedStart(join(stateDir, "stdout.log"));
+  if (!text) return undefined;
+  const withoutMarker = text.replace(/^ACTOR_REVIEW_RESULT\s*(?:\r?\n)?/, "").trim();
+  return withoutMarker || undefined;
+}
+
+function terminalSemanticResult(
+  status: Record<string, unknown>,
+  stateDir: string,
+  observedStatus: RunObservedStatus,
+): RunTerminalSemanticResult {
+  const correlation = status.launch_correlation &&
+    typeof status.launch_correlation === "object" &&
+    !Array.isArray(status.launch_correlation)
+    ? status.launch_correlation as Record<string, unknown>
+    : {};
+  const correlationId =
+    typeof correlation.correlation_id === "string"
+      ? correlation.correlation_id
+      : typeof correlation.tool_call_id === "string"
+        ? correlation.tool_call_id
+        : undefined;
+  const mailbox = status.mailbox &&
+    typeof status.mailbox === "object" &&
+    !Array.isArray(status.mailbox)
+    ? status.mailbox as Record<string, unknown>
+    : {};
+  const emits = Array.isArray(mailbox.emits)
+    ? mailbox.emits.filter((item): item is string => typeof item === "string")
+    : [];
+  const outbox = readJsonlFileResilient<Record<string, unknown>>(
+    join(stateDir, "outbox.jsonl"),
+  ).records;
+  const explicit = outbox.findLast((record) => {
+    const type = String(record.type ?? record.event ?? "");
+    return emits.includes(type) && !["command.done", "run.done", "run.failed"].includes(type);
+  });
+  if (explicit) {
+    const type = String(explicit.type ?? explicit.event);
+    return {
+      ...(explicit.body === undefined
+        ? {} : { body: formatSemanticBody(explicit.body) }),
+      ...(typeof explicit.correlation_id === "string"
+        ? { correlationId: explicit.correlation_id } : correlationId ? { correlationId } : {}),
+      metadata: {
+        ...(explicit.metadata &&
+        typeof explicit.metadata === "object" &&
+        !Array.isArray(explicit.metadata)
+          ? explicit.metadata as Record<string, unknown> : {}),
+        ...(status.transport_context &&
+        typeof status.transport_context === "object" &&
+        !Array.isArray(status.transport_context)
+          ? {
+              transport_context: status.transport_context as Record<string, unknown>,
+            } : {}),
+        run: String(status.run ?? ""),
+        status: observedStatus,
+      },
+      summary: String(explicit.summary ?? type),
+      synthesized: false,
+      type,
+    };
+  }
+  const reviewCompleted = observedStatus === "done" && emits.includes("review.completed");
+  const result = status.result &&
+    typeof status.result === "object" &&
+    !Array.isArray(status.result)
+    ? status.result as Record<string, unknown>
+    : {};
+  const type = reviewCompleted
+    ? "review.completed"
+    : observedStatus === "done" ? "run.done" : "run.failed";
+  const stdoutBody = observedStatus === "done"
+    ? semanticBodyFromStdout(stateDir) : undefined;
+  return {
+    ...(stdoutBody
+      ? { body: stdoutBody }
+      : typeof result.error === "string" ? { body: result.error } : {}),
+    ...(correlationId ? { correlationId } : {}),
+    metadata: {
+      ...(status.transport_context &&
+      typeof status.transport_context === "object" &&
+      !Array.isArray(status.transport_context)
+        ? {
+            transport_context: status.transport_context as Record<string, unknown>,
+          } : {}),
+      run: String(status.run ?? ""), status: observedStatus,
+    },
+    summary: reviewCompleted ? "Review completed." :
+      observedStatus === "done" ? "Run completed." : `Run ${observedStatus}.`,
+    synthesized: true,
+    type,
+  };
+}
+
+function formatSemanticBody(body: unknown): string {
+  const rendered = typeof body === "string" ? body : JSON.stringify(body);
+  const text = typeof rendered === "string" ? rendered : String(body);
+  const compact = text.trim();
+  return compact.length > TERMINAL_RESULT_CHARS
+    ? `${compact.slice(0, TERMINAL_RESULT_CHARS - 1)}…`
+    : compact;
+}
+
 function observeRun(stateDir: string): RunObservation | undefined {
   try {
     const status = AsyncRuns.getRunStatus(stateDir);
     const progress = getProgress(status);
     const run = typeof status.run === "string" ? status.run : undefined;
     if (!run) return undefined;
+    const observedStatus = status.status as RunObservedStatus;
     return {
       activeSubagents: toNumber(progress.activeSubagents),
       completed: toNumber(progress.completed),
+      ...(status.launch_correlation &&
+      typeof status.launch_correlation === "object" &&
+      !Array.isArray(status.launch_correlation)
+        ? { launchCorrelation: status.launch_correlation as Record<string, string> }
+        : {}),
       failures: Array.isArray(progress.failures)
         ? progress.failures.length
         : undefined,
@@ -542,9 +701,12 @@ function observeRun(stateDir: string): RunObservation | undefined {
       ...(typeof status.retire_when === "string"
         ? { retireWhen: status.retire_when }
         : {}),
+      ...(TERMINAL.has(observedStatus)
+        ? { semanticResult: terminalSemanticResult(status, stateDir, observedStatus) }
+        : {}),
       run,
       stateDir,
-      status: status.status as RunObservedStatus,
+      status: observedStatus,
       ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
       updatedAt: getUpdatedAt(status),
     };
@@ -933,9 +1095,11 @@ export function detectRunTransitions(
         run: run.run,
         ...(run.stateDir ? { stateDir: run.stateDir } : {}),
         ...(run.artifacts ? { artifacts: run.artifacts } : {}),
+        ...(run.launchCorrelation ? { launchCorrelation: run.launchCorrelation } : {}),
         ...(run.launchSource ? { launchSource: run.launchSource } : {}),
         ...(run.modelPolicy ? { modelPolicy: run.modelPolicy } : {}),
         ...(run.recipeFile ? { recipeFile: run.recipeFile } : {}),
+        ...(run.semanticResult ? { semanticResult: run.semanticResult } : {}),
         ...(run.terminalHandled ? { terminalHandled: true } : {}),
         to: run.status,
         ...(run.tool ? { tool: run.tool } : {}),
@@ -1180,86 +1344,40 @@ export function shouldSendRunTransitionFollowUp(
   return shouldNotifyRunTransition(transition);
 }
 
-function getRunArtifacts(transition: RunTransition): string[] {
-  if (!transition.stateDir) return [];
-  return [
-    join(transition.stateDir, "stdout.log"),
-    join(transition.stateDir, "stderr.log"),
-    join(transition.stateDir, "result.json"),
-    join(transition.stateDir, "events.jsonl"),
-    join(transition.stateDir, "outbox.jsonl"),
-  ];
-}
+const TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT = 4;
+const TERMINAL_FOLLOW_UP_IDENTIFIER_CHARS = 120;
+const TERMINAL_FOLLOW_UP_PATH_CHARS = 320;
 
-function isUserRecipeFile(file: string | undefined): boolean {
-  if (!file) return false;
-  const recipeRoot = resolve(Paths.getRecipeRoot());
-  const path = resolve(file);
-  return path === recipeRoot || path.startsWith(`${recipeRoot}/`);
+function compactTerminalText(value: string, limit: number): string {
+  const compact = value.replaceAll(/\s+/g, " ").trim();
+  return compact.length > limit ? `${compact.slice(0, limit - 1)}…` : compact;
 }
 
-export function shouldSuggestRecipePersistence(
-  transition: RunTransition,
-): boolean {
-  if (transition.to !== "done") return false;
-  if (isUserRecipeFile(transition.recipeFile)) return false;
-  return Boolean(transition.recipeFile) || transition.launchSource === "spawn";
+function formatTerminalPath(path: string): string {
+  return `\`${compactTerminalText(path, TERMINAL_FOLLOW_UP_PATH_CHARS)}\``;
 }
 
-function formatRecipePersistenceSuggestion(transition: RunTransition): string {
-  if (!shouldSuggestRecipePersistence(transition)) return "";
-  if (transition.recipeFile) {
-    return `\nAgent note: this actor completed successfully from recipe ${transition.recipeFile}. If this recipe fits this machine's recurring workflow, ask the operator whether to copy or register it as a durable tool recipe under ~/.pi/agent/recipes. Do not auto-save without confirmation.`;
-  }
-  return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern fits this machine's recurring workflow, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
-}
-
-function formatTransitionPolicy(transition: RunTransition): string {
-  if (!transition.modelPolicy) return "";
-  const axis = (key: "model" | "thinking", label: string): string | undefined => {
-    const value = transition.modelPolicy?.[key];
-    if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-    const record = value as Record<string, unknown>;
-    const source = typeof record.source === "string" ? record.source : "unused";
-    if (source === "unused") return undefined;
-    const renderedValue =
-      typeof record.value === "string" && record.value.trim()
-        ? ` (${record.value.trim()})`
-        : "";
-    return `${label}: ${source}${renderedValue}`;
-  };
-  const lines = [axis("model", "Model"), axis("thinking", "Thinking")].filter(
-    (line): line is string => Boolean(line),
-  );
-  return lines.length ? `\nPolicy:\n- ${lines.join("\n- ")}` : "";
-}
-
-function formatTransitionNextActions(transition: RunTransition): string {
-  const actions = [
-    `inspect target=run:${transition.run} view=status`,
-    transition.to === "done" && Object.keys(transition.artifacts ?? {}).length > 0
-      ? `inspect target=run:${transition.run} view=artifacts`
-      : `inspect target=run:${transition.run} view=tail`,
-    `inspect target=run:${transition.run} view=messages`,
-  ].filter(Boolean);
-  return `\nNext actions: ${actions.join(" | ")}`;
+function formatTerminalResultLocations(transition: RunTransition): string {
+  const artifactPaths = [...new Set(
+    Object.values(transition.artifacts ?? {}).filter(
+      (path): path is string => typeof path === "string" && path.length > 0,
+    ),
+  )];
+  if (artifactPaths.length === 0)
+    return transition.stateDir ? `\nBase: ${formatTerminalPath(transition.stateDir)}` : "";
+  const base = commonDirectory(artifactPaths);
+  const artifactPreview = artifactPaths
+    .slice(0, TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT)
+    .map((path) => formatTerminalPath(base ? relativeName(base, path) : path));
+  const omitted = artifactPaths.length - artifactPreview.length;
+  const artifacts = `${artifactPreview.join(", ")}${omitted > 0 ? ` (+${omitted} more)` : ""}`;
+  return `${base ? `\nBase: ${formatTerminalPath(base)}` : ""}\nArtifacts: ${artifacts}`;
 }
 
 export function formatRunTransitionMessage(transition: RunTransition): string {
-  const artifacts = formatNamedArtifacts(transition.artifacts);
-  const runFiles = formatRunFileList(getRunArtifacts(transition));
-  const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
-  const policy = formatTransitionPolicy(transition);
-  const nextActions = formatTransitionNextActions(transition);
-  if (transition.to === "done")
-    return `Run ${transition.run} completed successfully.${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
-  if (transition.to === "failed")
-    return `Run ${transition.run} failed.${policy}${artifacts}${runFiles}${nextActions}`;
-  if (transition.to === "cancelled")
-    return `Run ${transition.run} was cancelled.${policy}${nextActions}`;
-  if (transition.to === "killed")
-    return `Run ${transition.run} was force-killed.${policy}${nextActions}`;
-  if (transition.to === "exited")
-    return `Run ${transition.run} exited before writing a result.${policy}${nextActions}`;
-  return `Run ${transition.run} finished with status ${transition.to}.${policy}${nextActions}`;
+  const run = compactTerminalText(
+    transition.run,
+    TERMINAL_FOLLOW_UP_IDENTIFIER_CHARS,
+  );
+  return `Run: \`${run}\`\nStatus: \`${transition.to}\`${formatTerminalResultLocations(transition)}`;
 }