@llblab/pi-actors 0.42.0 → 0.42.2

package/dist/lib/observability.js

@@ -3,8 +3,8 @@
  * 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 { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
+import { closeSync, existsSync, fstatSync, openSync, readdirSync, readFileSync, readSync, watch, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
 import { readJsonlFileResilient } from "./state-readers.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 } : {}),
@@ -825,83 +958,29 @@ export function shouldNotifyRunTransition(transition) {
 export function shouldSendRunTransitionFollowUp(transition) {
     return shouldNotifyRunTransition(transition);
 }
-function getRunArtifacts(transition) {
-    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"),
-    ];
-}
-function isUserRecipeFile(file) {
-    if (!file)
-        return false;
-    const recipeRoot = resolve(Paths.getRecipeRoot());
-    const path = resolve(file);
-    return path === recipeRoot || path.startsWith(`${recipeRoot}/`);
-}
-export function shouldSuggestRecipePersistence(transition) {
-    if (transition.to !== "done")
-        return false;
-    if (isUserRecipeFile(transition.recipeFile))
-        return false;
-    return Boolean(transition.recipeFile) || transition.launchSource === "spawn";
-}
-function formatRecipePersistenceSuggestion(transition) {
-    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) {
-    if (!transition.modelPolicy)
-        return "";
-    const axis = (key, label) => {
-        const value = transition.modelPolicy?.[key];
-        if (!value || typeof value !== "object" || Array.isArray(value))
-            return undefined;
-        const record = value;
-        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) => Boolean(line));
-    return lines.length ? `\nPolicy:\n- ${lines.join("\n- ")}` : "";
-}
-function formatTransitionNextActions(transition) {
-    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(" | ")}`;
+const TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT = 4;
+const TERMINAL_FOLLOW_UP_IDENTIFIER_CHARS = 120;
+const TERMINAL_FOLLOW_UP_PATH_CHARS = 320;
+function compactTerminalText(value, limit) {
+    const compact = value.replaceAll(/\s+/g, " ").trim();
+    return compact.length > limit ? `${compact.slice(0, limit - 1)}…` : compact;
+}
+function formatTerminalPath(path) {
+    return `\`${compactTerminalText(path, TERMINAL_FOLLOW_UP_PATH_CHARS)}\``;
+}
+function formatTerminalResultLocations(transition) {
+    const artifactPaths = [...new Set(Object.values(transition.artifacts ?? {}).filter((path) => 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) {
-    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)}`;
 }

package/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -23,7 +23,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;

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

@@ -2,6 +2,7 @@
  * Async run process control primitives.
  * Owns: platform signal planning, owned-process signalling, and terminal control markers.
  */
+import { spawnSync } from "node:child_process";
 import { type RunProcessIdentity, type RunProcessIdentityResult } from "./runs-process.ts";
 export interface RunProcessSignalPlan {
     args?: string[];
@@ -12,6 +13,7 @@ export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Sign
 export interface RunProcessSignalDeps {
     killProcess?: typeof process.kill;
     runtimePlatform?: NodeJS.Platform;
+    spawnProcess?: typeof spawnSync;
     verifyIdentity?: (pid: number, expected: RunProcessIdentity, runtimePlatform: NodeJS.Platform) => RunProcessIdentityResult;
 }
 export declare function signalOwnedRunProcess(pid: number, signal: NodeJS.Signals, expectedIdentity?: RunProcessIdentity, deps?: RunProcessSignalDeps): RunProcessSignalPlan;

package/dist/lib/runs-control.js

@@ -31,8 +31,21 @@ export function signalOwnedRunProcess(pid, signal, expectedIdentity, deps = {})
     }
     const plan = getRunProcessSignalPlan(pid, signal, runtimePlatform);
     if (plan.command && plan.args) {
-        const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
+        const spawnProcess = deps.spawnProcess ?? spawnSync;
+        let result = spawnProcess(plan.command, plan.args, { encoding: "utf8" });
+        if (runtimePlatform === "win32" &&
+            result.status !== 0 &&
+            !plan.args.includes("/F")) {
+            result = spawnProcess(plan.command, [...plan.args, "/F"], {
+                encoding: "utf8",
+            });
+        }
         if (result.status !== 0) {
+            if (expectedIdentity) {
+                const finalProof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(pid, expectedIdentity, runtimePlatform);
+                if (finalProof.status === "dead_pid")
+                    return plan;
+            }
             throw new Error(result.stderr?.trim() ||
                 result.stdout?.trim() ||
                 `${plan.command} failed`);

package/dist/lib/runs-ownership.js

@@ -4,7 +4,8 @@
  */
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { writeJsonAtomic } from "./file-state.js";
 export const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
 function markerPath(stateDir) {
@@ -14,13 +15,26 @@ function comparablePath(path) {
     const resolved = resolve(path);
     return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
+function isSystemTempRootAlias(resolved, canonical) {
+    const tempRoot = resolve(tmpdir());
+    const relativeStateDir = relative(tempRoot, resolved);
+    if (relativeStateDir === ".." ||
+        relativeStateDir.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) ||
+        isAbsolute(relativeStateDir)) {
+        return false;
+    }
+    const canonicalTempRoot = realpathSync.native(tempRoot);
+    const expectedCanonical = resolve(canonicalTempRoot, relativeStateDir);
+    return comparablePath(canonical) === comparablePath(expectedCanonical);
+}
 function assertCanonicalDirectory(stateDir) {
     const resolved = resolve(stateDir);
     if (lstatSync(resolved).isSymbolicLink()) {
         throw new Error(`Run state directory cannot be a symlink: ${resolved}`);
     }
-    const canonical = realpathSync(resolved);
-    if (comparablePath(canonical) !== comparablePath(resolved)) {
+    const canonical = realpathSync.native(resolved);
+    if (comparablePath(canonical) !== comparablePath(resolved) &&
+        !isSystemTempRootAlias(resolved, canonical)) {
         throw new Error(`Run state directory has an ambiguous symlink alias: ${resolved}`);
     }
     return resolved;

package/dist/lib/runs-process.js

@@ -5,7 +5,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { platform } from "node:os";
-import { resolve } from "node:path";
+import { posix, win32 } from "node:path";
 export function isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -90,8 +90,9 @@ export function captureRunProcessIdentity(pid, cwd, stateDir, runnerPath, runtim
     if (!identity.command.includes(runnerPath) || !identity.command.includes(stateDir)) {
         return undefined;
     }
-    const resolvedCwd = resolve(cwd);
-    const canonicalCwd = existsSync(resolvedCwd)
+    const pathApi = runtimePlatform === "win32" ? win32 : posix;
+    const resolvedCwd = pathApi.resolve(cwd);
+    const canonicalCwd = runtimePlatform === platform() && existsSync(resolvedCwd)
         ? realpathSync.native(resolvedCwd)
         : resolvedCwd;
     const expectedCwd = runtimePlatform === "win32" ? canonicalCwd.toLowerCase() : canonicalCwd;

package/dist/lib/runs-start.js

@@ -52,6 +52,7 @@ export function prepareStateDirForStart(stateDir, readJson, _runnerPath) {
         "result.json",
         "stderr.log",
         "stdout.log",
+        "terminal-delivery-failure.json",
         "terminal-handled.json",
     ]) {
         rmSync(join(stateDir, file), { force: true });

package/dist/lib/runs-status.js

@@ -30,6 +30,7 @@ export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath,
             ? "running"
             : (getInterruptedRunStatus(stateDir) ?? "exited");
     const terminalHandled = readJson(join(stateDir, "terminal-handled.json"));
+    const terminalDeliveryFailure = readJson(join(stateDir, "terminal-delivery-failure.json"));
     return {
         ...meta,
         eventsFile: join(stateDir, "events.jsonl"),
@@ -39,6 +40,8 @@ export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath,
         process_identity_status: processIdentity.status,
         progress: readJson(join(stateDir, "progress.json")) || null,
         result: result || null,
+        ...(terminalDeliveryFailure
+            ? { terminal_delivery_failure: terminalDeliveryFailure } : {}),
         ...(terminalHandled ? { terminal_handled: terminalHandled } : {}),
         state_dir: String(meta.state_dir ?? stateDir),
         stderrLog: join(stateDir, "stderr.log"),

package/dist/lib/tools-inspect.js

@@ -6,6 +6,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as AsyncRuns from "./async-runs.js";
 import * as Limits from "./limits.js";
 import * as Messages from "./messages.js";
@@ -229,7 +230,7 @@ function getPiActorsRuntimeStatus() {
     catch {
         git_commit = undefined;
     }
-    const entrypoint = new URL(import.meta.url).pathname;
+    const entrypoint = fileURLToPath(import.meta.url);
     return {
         automatic_recipe_review: Paths.isAutomaticRecipeReviewEnabled(),
         entrypoint,

package/dist/lib/tools-local.js

@@ -100,6 +100,10 @@ export function createRuntimeToolDefinition(cfg, exec) {
     }
     if (isAsyncRecipe)
         paramSchema.run_id = Schema.stringSchema("Optional run id override for this async template recipe invocation.");
+    if (isAsyncRecipe) {
+        paramSchema.correlation_id = Schema.stringSchema("Optional workflow correlation id preserved in terminal follow-up delivery.");
+        paramSchema.transport_context = Schema.looseObjectSchema("Optional originating transport route preserved for detached terminal follow-up.");
+    }
     return {
         name: cfg.name,
         label: cfg.name,
@@ -108,7 +112,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
         promptSnippet: isRecipe
             ? Prompts.formatRecipeToolPromptSnippet(cfg.recipe?.name ?? String(cfg.template), isAsyncRecipe)
             : Prompts.formatRegisteredToolPromptSnippet(cfg.template),
-        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+        async execute(toolCallId, params, signal, _onUpdate, ctx) {
             try {
                 if (cfg.sourcePath &&
                     !RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool")) {
@@ -116,7 +120,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
                 }
                 if (isAsyncRecipe) {
                     const input = params;
-                    const { run_id, ...values } = input;
+                    const { correlation_id, run_id, transport_context, ...values } = input;
                     const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
                     const runId = typeof run_id === "string" && run_id.trim()
                         ? run_id.trim()
@@ -124,6 +128,17 @@ export function createRuntimeToolDefinition(cfg, exec) {
                     const meta = AsyncRuns.startRun({
                         ...base,
                         launch_source: "tool",
+                        launch_correlation: {
+                            ...(typeof correlation_id === "string"
+                                ? { correlation_id } : {}),
+                            tool_call_id: toolCallId,
+                        },
+                        ...(transport_context &&
+                            typeof transport_context === "object" &&
+                            !Array.isArray(transport_context)
+                            ? {
+                                transport_context: transport_context,
+                            } : {}),
                         ownerId: getRunOwnerId(ctx),
                         run_id: runId,
                         tool: cfg.name,

package/dist/lib/tools-spawn.js

@@ -95,6 +95,7 @@ export function createSpawnToolDefinition() {
         parameters: Schema.objectSchema({
             artifacts: Schema.looseObjectSchema("Optional named artifact paths for the spawned actor."),
             as: Schema.stringSchema("Optional actor address for the spawned run, e.g. run:<id>."),
+            correlation_id: Schema.stringSchema("Optional workflow correlation id preserved in terminal follow-up delivery."),
             file: Schema.stringSchema("Optional template recipe JSON file. Bare names resolve under ~/.pi/agent/recipes."),
             recipe: Schema.stringSchema("Alias for file; template recipe JSON file/name to spawn."),
             template: Schema.unionSchema([
@@ -103,9 +104,10 @@ export function createSpawnToolDefinition() {
                 Schema.looseObjectSchema("Inline command-template object with flags such as parallel, repeat, retry, failure, and nested template."),
             ]),
             values: Schema.looseObjectSchema("Runtime placeholder values passed to the actor."),
+            transport_context: Schema.looseObjectSchema("Optional originating transport route preserved for detached terminal follow-up, e.g. Telegram chat_id and thread_id."),
             verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
         }, []),
-        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        async execute(toolCallId, params, _signal, _onUpdate, ctx) {
             const input = asRecord(params);
             if (input.state_dir !== undefined) {
                 throw new Error("spawn.state_dir is not supported; run state is runtime-owned so run:<id> remains addressable and retention-safe.");
@@ -121,7 +123,14 @@ export function createSpawnToolDefinition() {
                 meta = AsyncRuns.startRun({
                     file: recipe,
                     launch_source: "spawn",
+                    launch_correlation: {
+                        ...(typeof input.correlation_id === "string"
+                            ? { correlation_id: input.correlation_id } : {}),
+                        tool_call_id: toolCallId,
+                    },
                     ownerId: getRunOwnerId(ctx),
+                    ...(input.transport_context
+                        ? { transport_context: asRecord(input.transport_context) } : {}),
                     run_id: runId,
                     ...(input.template !== undefined
                         ? {