@llblab/pi-actors 0.42.0 → 0.42.1

package/BACKLOG.md

@@ -1,7 +1,3 @@
 # Project Backlog
 
-## Open Work
-
-### Windows filesystem fencing verification
-
-- [ ] Add Windows CI and native NTFS regressions for consolidation root identity, directory junction/reparse-point substitution, lifecycle locks, and recovery without requiring privileged symbolic-link creation. Keep bigint device/inode capture, document filesystems that report weak or zero file identity, and evaluate a native handle-relative mutation layer only if real Windows evidence justifies expanding beyond Node’s portable process-crash and trusted-state-tree contract.
+No open items.

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.42.1: Terminal Delivery and Cross-platform Validation
+
+- `[Terminal Delivery]` Added one bounded semantic terminal result with durable launch/tool-call correlation and bounded adapter-provided transport context. Explicit advertised semantic envelopes win; successful accepted reviews that advertise `review.completed` deterministically synthesize it when absent, while failed runs include their terminal error. Watcher and reconciliation delivery share the existing live in-flight dedupe guard, failed sends persist bounded retry evidence without writing the handled marker, and status exposes the latest failure. Impact: coordinators and Telegram-style chat/thread adapters can retain the exact launch/result relationship across detached completion instead of receiving only run-file metadata.
+- `[Inspector Kill Dialog]` Replaced the inline kill prompt with a dedicated responsive confirmation overlay showing the exact run and current status, explicit destructive copy, Cancel-first focus, arrow/Tab selection, Enter activation, and direct Y/N/Escape behavior. Exact owner, generation, and running status still revalidate through canonical control after confirmation, and bounded feedback returns to the Inspector. Impact: destructive actor termination now has an unmistakable, keyboard-predictable safety boundary.
+- `[Cross-platform CI]` Added identical release-validation matrix jobs for Ubuntu, macOS, and Windows with fail-fast disabled, bounded timeouts, pinned Node setup, npm caching, and `npm ci`; dependency audit now runs once in a separate Ubuntu job. Added invariants that keep audit outside platform-neutral validation. Impact: the package has one baseline release path across all supported host filesystems and shells.
+- `[macOS Run Ownership]` Recognized the exact platform-owned `/var` to `/private/var` temporary-root alias without weakening nested-parent or leaf-symlink rejection. Impact: run-state ownership remains fail-closed for caller-controlled aliases while macOS temporary directories pass canonical ownership checks.
+- `[Portable Build and Cleanup]` Invoked local JavaScript entrypoints through Node instead of relying on shell-specific executable resolution, recognized both path separators when resolving run state, converted file URLs with the platform API, made path assertions native, serialized release suites that exercise shared watchers, and cancelled live fixtures before removing their state. Impact: Windows paths and builds remain shell-free while macOS and Windows cleanup no longer races active worker writes.
+- `[Windows Filesystem Fencing]` Added native-only NTFS regressions for bigint consolidation-root identity, unprivileged directory-junction alias locking, lifecycle locking, draft-root reparse substitution, and trusted-root recovery replacement. Documented weak/zero device-inode filesystems and retained the portable realpath/root-identity/CAS contract without preemptively introducing a native handle-relative mutation layer. Impact: the Windows runner now owns concrete evidence for the deeper filesystem boundary rather than inheriting Unix symlink assumptions.
+- `[Cross-platform Validation Evidence]` Completed the release-validation matrix on Ubuntu, macOS, and Windows in GitHub Actions run `30322093465`, including native NTFS bigint root identity, directory-junction mutation/lifecycle locking, draft-root junction substitution, and trusted-root replacement recovery regressions. The failures found while establishing the matrix were portable path, command, process-tree, temporary-root alias, line-ending, and fixture-lifecycle gaps; no residual trusted-state-tree substitution window was reproduced, so a native handle-relative mutation layer is not warranted. Impact: the release boundary now has direct platform evidence for the portable process-crash and trusted-state-tree contract.
+
 ## 0.42.0: Automatic Recipe Evolution and Recipe-first Inspector
 
 - `Recipe-first Inspector`: The Inspector now opens on a bounded, redacted `Recipe` document for the selected owned run, showing authored identity, resolved launch template and values, composition, policy, mailbox, and artifacts without following mutable external recipe paths. `Messages` and `Turns` remain adjacent tabs; Turns use one scrollable detail level without duplicated recipe context, and documents/timelines/details support arrows plus PageUp/PageDown. Nested values render as compact indented text with label-first, separator-aware wrapping and consistent lowercase hints. Recipe documents retain ↑-at-top/← navigation to tabs, and ← now also returns a scrolled Messages or Turns list directly to its tabs without resetting the selected row. Turns retain one cached evidence snapshot while list/detail navigation remains active, eliminating repeated full session-file parsing on every arrow key while preserving periodic refresh when focus returns to higher-level controls.

package/README.md

@@ -295,6 +295,8 @@ Packaged recipes are building blocks. Use `spawn file=<recipe>` for maintained p
 
 When a directly spawned inline/ad hoc actor or a recipe outside the user recipe root completes successfully, `pi-actors` may include a promotion suggestion in its terminal follow-up notification. The agent should ask first and never auto-save.
 
+Terminal completion returns one bounded semantic result to the originating coordinator, not only run-state paths. `spawn` and saved async tools preserve their tool-call correlation automatically; callers may add `correlation_id` plus bounded `transport_context` when an adapter must retain an exact detached route, including Telegram `chat_id`/`thread_id`. Recipes that advertise `review.completed` either emit that envelope explicitly or receive one synthesized from successfully accepted review output. Watcher and periodic reconciliation share one in-flight guard, while failed sends remain retryable and visible in run status.
+
 ## Platform support
 
 Core actor state, inspection, foreground tools, and basic async runs are portable Node.js behavior. Run-local messaging and stop/kill use platform adapters under the same `message` API.

package/dist/lib/async-runs.d.ts

@@ -18,6 +18,7 @@ export interface AsyncRunControlEndpoint {
     path: string;
     type: "fifo" | "mailbox" | "named-pipe";
 }
+export declare function normalizeRunTransportContext(value: unknown): Record<string, string | number | boolean> | undefined;
 export interface AsyncRunStartParams {
     async?: boolean;
     control?: AsyncRunControlEndpoint;
@@ -26,6 +27,10 @@ export interface AsyncRunStartParams {
     lifecycleHooks?: {
         onLockContention?(): void;
     };
+    launch_correlation?: {
+        correlation_id?: string;
+        tool_call_id?: string;
+    };
     name?: string;
     ownerId?: string;
     run_id?: string;
@@ -50,6 +55,7 @@ export interface AsyncRunStartParams {
     retry?: number | string;
     failure?: CommandTemplateFailureScope;
     recover?: CommandTemplateValue;
+    transport_context?: Record<string, unknown>;
     repeat?: number;
     values?: Record<string, unknown>;
     policy_values?: Record<string, unknown>;
@@ -62,6 +68,10 @@ export interface AsyncRunMeta {
     createdAt: string;
     cwd: string;
     launch_source?: AsyncRunLaunchSource;
+    launch_correlation?: {
+        correlation_id?: string;
+        tool_call_id?: string;
+    };
     ownerId?: string;
     pid: number;
     recipe?: string;
@@ -81,6 +91,7 @@ export interface AsyncRunMeta {
     process_identity?: RunProcessIdentity;
     recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
+    transport_context?: Record<string, unknown>;
 }
 export { safeRunId } from "./runs-identity.ts";
 export { resolveArtifactManifest } from "./runs-artifacts.ts";
@@ -136,6 +147,7 @@ export interface RunControlExpectation {
     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 cancelRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;
 export declare function archiveRun(runOrDir: string): Record<string, unknown>;
 export declare function pruneRun(runOrDir: string, options?: {

package/dist/lib/async-runs.js

@@ -5,7 +5,7 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, writeFileSync, } from "node:fs";
-import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeJsonAtomic } from "./file-state.js";
 import { CURRENT_MODEL_VALUE_KEY, CURRENT_THINKING_VALUE_KEY, describeCurrentPolicyProvenance, } from "./model-context.js";
@@ -27,6 +27,27 @@ import { deliverRunMessage, } from "./runs-messages.js";
 import { buildRunStatus, tailFile, tailLines, } from "./runs-status.js";
 import { readJsonFileResilient } from "./state-readers.js";
 const RUNNER_IDENTITY_GRACE_MS = 5000;
+export function normalizeRunTransportContext(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const normalized = {};
+    for (const [key, item] of Object.entries(value).slice(0, 16)) {
+        const safeKey = key.trim().slice(0, 64);
+        if (!safeKey)
+            continue;
+        if (typeof item === "string") {
+            normalized[safeKey] = item.trim().slice(0, 256);
+            continue;
+        }
+        if (typeof item === "number" && Number.isFinite(item)) {
+            normalized[safeKey] = item;
+            continue;
+        }
+        if (typeof item === "boolean")
+            normalized[safeKey] = item;
+    }
+    return Object.keys(normalized).length ? normalized : undefined;
+}
 const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
 const DEFAULT_RECIPE_ROOT = Paths.getRecipeRoot();
 function packageRoot() {
@@ -91,7 +112,8 @@ function resolveRecipeFile(file) {
 function isMutableUsageRecipeFile(file) {
     const userRoot = resolve(DEFAULT_RECIPE_ROOT);
     const resolved = resolve(file);
-    return resolved.startsWith(`${userRoot}/`);
+    const relation = relative(userRoot, resolved);
+    return relation !== "" && !relation.startsWith("..") && !isAbsolute(relation);
 }
 function readRecipeFile(file) {
     const path = resolveRecipeFile(file);
@@ -260,6 +282,7 @@ export function startRun(params, cwd) {
             ...(startParams.defaults || {}),
             ...values,
         };
+        const transportContext = normalizeRunTransportContext(startParams.transport_context);
         const artifacts = resolveArtifactPaths(startParams.artifacts, outputValues);
         const meta = {
             argv: [process.execPath, ...argv],
@@ -268,6 +291,8 @@ export function startRun(params, cwd) {
             ...(startParams.launch_source
                 ? { launch_source: startParams.launch_source }
                 : {}),
+            ...(startParams.launch_correlation
+                ? { launch_correlation: startParams.launch_correlation } : {}),
             ...(startParams.ownerId ? { ownerId: startParams.ownerId } : {}),
             pid: 0,
             ...(recipe ? { recipe } : {}),
@@ -292,6 +317,8 @@ export function startRun(params, cwd) {
             ...(startParams.retire_when === "children_terminal"
                 ? { retire_when: "children_terminal" }
                 : {}),
+            ...(transportContext
+                ? { transport_context: transportContext } : {}),
         };
         writeJsonAtomic(join(stateDir, "run.json"), meta);
         const child = spawn(process.execPath, argv, {
@@ -323,7 +350,7 @@ export function startRun(params, cwd) {
 }
 export { parseRunOutboxEventLine } from "./runs-outbox.js";
 function resolveRunStateDir(runOrDir) {
-    return resolve(runOrDir.includes("/")
+    return resolve(/[\\/]/u.test(runOrDir)
         ? runOrDir
         : join(DEFAULT_STATE_ROOT, safeRunId(runOrDir)));
 }
@@ -515,11 +542,11 @@ function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
                 return {
                     attempt: index + 1,
                     stdout: {
-                        path: relative(stateDir, stdoutFile),
+                        path: relative(stateDir, stdoutFile).replaceAll("\\", "/"),
                         bytes: existsSync(stdoutFile) ? statSync(stdoutFile).size : 0,
                     },
                     stderr: {
-                        path: relative(stateDir, stderrFile),
+                        path: relative(stateDir, stderrFile).replaceAll("\\", "/"),
                         bytes: existsSync(stderrFile) ? statSync(stderrFile).size : 0,
                     },
                 };
@@ -606,6 +633,20 @@ export function markRunTerminalNotificationHandled(stateDir, status) {
         status,
     });
 }
+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 cancelRun(runOrDir, expected = {}) {
     const result = stopRun(runOrDir, "SIGTERM", "run.cancel", expected);
     return Object.hasOwn(result, "stopped")

package/dist/lib/command-templates.js

@@ -344,7 +344,7 @@ export function splitCommandTemplate(input) {
     let active = false;
     for (const char of input) {
         if (escaped) {
-            current += char;
+            current += /[\s'"\\]/u.test(char) ? char : `\\${char}`;
             escaped = false;
             active = true;
             continue;

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

@@ -40,6 +40,7 @@ export declare class ActorInspectorOverlay {
     private detailTurn?;
     private feedback?;
     private killConfirmation?;
+    private killDialogChoice;
     private readonly readKeys;
     private focus;
     private filterControlIndex;
@@ -62,8 +63,9 @@ export declare class ActorInspectorOverlay {
     private selectRun;
     private cycleRun;
     private requestKill;
+    private cancelKill;
     private confirmKill;
-    private renderKillConfirmation;
+    private renderKillDialog;
     private listItemCount;
     private selectorAnchor;
     private renderKeyHints;
@@ -108,5 +110,6 @@ export declare class ActorInspectorOverlay {
     private row;
     private takeVisiblePrefix;
     private dropVisiblePrefix;
+    private center;
     private fit;
 }

package/dist/lib/inspector-overlay.js

@@ -33,6 +33,7 @@ export class ActorInspectorOverlay {
     detailTurn;
     feedback;
     killConfirmation;
+    killDialogChoice = "cancel";
     readKeys = new Set();
     focus = "tabs";
     filterControlIndex = 0;
@@ -67,13 +68,25 @@ export class ActorInspectorOverlay {
             return;
         }
         if (this.killConfirmation) {
-            if (matchesKey(data, "escape") || data.toLowerCase() === "n") {
-                this.feedback = { ok: false, message: "Kill cancelled." };
-                this.killConfirmation = undefined;
+            const key = data.toLowerCase();
+            if (matchesKey(data, "escape") || key === "n") {
+                this.cancelKill();
             }
-            else if (matchesKey(data, "return") || data.toLowerCase() === "y") {
+            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;
         }
@@ -200,6 +213,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 = [];
         lines.push(this.border("╭", " Actor Inspector ", "╮", innerWidth));
         lines.push(this.row(this.renderRunControl(), innerWidth));
@@ -229,13 +244,11 @@ export class ActorInspectorOverlay {
         else
             lines.push(this.border("├", "", "┤", innerWidth));
         this.contentStripeIndices = [];
-        const baseContent = this.killConfirmation
-            ? this.renderKillConfirmation()
-            : this.detailOpen
-                ? this.renderDetail(innerWidth)
-                : this.selectedRun
-                    ? this.renderTimeline(innerWidth)
-                    : this.renderRunSelector(innerWidth);
+        const baseContent = this.detailOpen
+            ? this.renderDetail(innerWidth)
+            : this.selectedRun
+                ? this.renderTimeline(innerWidth)
+                : this.renderRunSelector(innerWidth);
         const content = this.feedback && !this.killConfirmation
             ? [
                 this.theme.fg(this.feedback.ok
@@ -337,11 +350,19 @@ export class ActorInspectorOverlay {
         this.killConfirmation = {
             run: run.run,
             runInstanceId: run.runInstanceId,
+            status: run.status,
         };
+        this.killDialogChoice = "cancel";
+    }
+    cancelKill() {
+        this.feedback = { ok: false, message: "Kill cancelled." };
+        this.killConfirmation = undefined;
+        this.killDialogChoice = "cancel";
     }
     confirmKill() {
         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;
@@ -357,11 +378,41 @@ export class ActorInspectorOverlay {
             };
         }
     }
-    renderKillConfirmation() {
-        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."),
+    renderKillDialog(_width, innerWidth) {
+        const confirmation = this.killConfirmation;
+        const totalRows = this.contentViewportRows() + 7;
+        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.border("╰", " ←→/tab choose · enter activate · esc cancel ", "╯", innerWidth));
+        return lines;
     }
     listItemCount() {
         if (this.tab === "recipe")
@@ -1062,6 +1113,11 @@ export class ActorInspectorOverlay {
         }
         return plain.slice(index);
     }
+    center(content, width) {
+        const contentWidth = visibleWidth(content);
+        const leading = Math.max(0, Math.floor((width - contentWidth) / 2));
+        return `${" ".repeat(leading)}${content}`;
+    }
     fit(content, width) {
         // A Component render entry must remain exactly one terminal row. Persisted
         // prompts, messages, and tool results may contain line breaks or tabs;

package/dist/lib/inspector.js

@@ -126,7 +126,7 @@ export function readActorInspectorTurns(stateDir) {
                 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/dist/lib/observability.d.ts

@@ -15,6 +15,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";
@@ -22,6 +23,7 @@ export interface RunObservation {
     terminalHandled?: boolean;
     retireWhen?: string;
     run: string;
+    semanticResult?: RunTerminalSemanticResult;
     tool?: string;
     stateDir?: string;
     status: RunObservedStatus;
@@ -131,12 +133,22 @@ 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 {
     body?: unknown;

package/dist/lib/observability.js

@@ -3,7 +3,7 @@
  * Zones: async runtime, ambient UI, diagnostics
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
-import { existsSync, readdirSync, readFileSync, watch, } from "node:fs";
+import { closeSync, existsSync, fstatSync, openSync, readdirSync, readFileSync, readSync, watch, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
@@ -54,6 +54,13 @@ export function deliverRunTransitionNotifications(transitions, sink, inFlight =
                 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);
         }
@@ -282,6 +289,121 @@ function scanRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
     }
     return result;
 }
+const TERMINAL_RESULT_BYTES = 8 * 1024;
+const TERMINAL_RESULT_CHARS = 4_000;
+function readBoundedStart(path) {
+    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) {
+    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, stateDir, observedStatus) {
+    const correlation = status.launch_correlation &&
+        typeof status.launch_correlation === "object" &&
+        !Array.isArray(status.launch_correlation)
+        ? status.launch_correlation
+        : {};
+    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
+        : {};
+    const emits = Array.isArray(mailbox.emits)
+        ? mailbox.emits.filter((item) => typeof item === "string")
+        : [];
+    const outbox = readJsonlFileResilient(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 : {}),
+                ...(status.transport_context &&
+                    typeof status.transport_context === "object" &&
+                    !Array.isArray(status.transport_context)
+                    ? {
+                        transport_context: status.transport_context,
+                    } : {}),
+                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
+        : {};
+    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,
+                } : {}),
+            run: String(status.run ?? ""), status: observedStatus,
+        },
+        summary: reviewCompleted ? "Review completed." :
+            observedStatus === "done" ? "Run completed." : `Run ${observedStatus}.`,
+        synthesized: true,
+        type,
+    };
+}
+function formatSemanticBody(body) {
+    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) {
     try {
         const status = AsyncRuns.getRunStatus(stateDir);
@@ -289,9 +411,15 @@ function observeRun(stateDir) {
         const run = typeof status.run === "string" ? status.run : undefined;
         if (!run)
             return undefined;
+        const observedStatus = status.status;
         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 }
+                : {}),
             failures: Array.isArray(progress.failures)
                 ? progress.failures.length
                 : undefined,
@@ -321,9 +449,12 @@ function observeRun(stateDir) {
             ...(typeof status.retire_when === "string"
                 ? { retireWhen: status.retire_when }
                 : {}),
+            ...(TERMINAL.has(observedStatus)
+                ? { semanticResult: terminalSemanticResult(status, stateDir, observedStatus) }
+                : {}),
             run,
             stateDir,
-            status: status.status,
+            status: observedStatus,
             ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
             updatedAt: getUpdatedAt(status),
         };
@@ -626,9 +757,11 @@ export function detectRunTransitions(previous, summary) {
                 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 } : {}),
@@ -841,7 +974,8 @@ function isUserRecipeFile(file) {
         return false;
     const recipeRoot = resolve(Paths.getRecipeRoot());
     const path = resolve(file);
-    return path === recipeRoot || path.startsWith(`${recipeRoot}/`);
+    const relation = relative(recipeRoot, path);
+    return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
 }
 export function shouldSuggestRecipePersistence(transition) {
     if (transition.to !== "done")
@@ -887,16 +1021,26 @@ function formatTransitionNextActions(transition) {
     ].filter(Boolean);
     return `\nNext actions: ${actions.join(" | ")}`;
 }
+function formatTransitionSemanticResult(transition) {
+    const result = transition.semanticResult;
+    if (!result)
+        return "";
+    const correlation = result.correlationId
+        ? `\nCorrelation: ${result.correlationId}` : "";
+    const body = result.body ? `\nResult:\n${result.body}` : "";
+    return `\nSemantic result: ${result.type} — ${result.summary}${correlation}${body}`;
+}
 export function formatRunTransitionMessage(transition) {
     const artifacts = formatNamedArtifacts(transition.artifacts);
     const runFiles = formatRunFileList(getRunArtifacts(transition));
     const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
     const policy = formatTransitionPolicy(transition);
     const nextActions = formatTransitionNextActions(transition);
+    const semanticResult = formatTransitionSemanticResult(transition);
     if (transition.to === "done")
-        return `Run ${transition.run} completed successfully.${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
+        return `Run ${transition.run} completed successfully.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
     if (transition.to === "failed")
-        return `Run ${transition.run} failed.${policy}${artifacts}${runFiles}${nextActions}`;
+        return `Run ${transition.run} failed.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}`;
     if (transition.to === "cancelled")
         return `Run ${transition.run} was cancelled.${policy}${nextActions}`;
     if (transition.to === "killed")