@llblab/pi-actors 0.42.0 → 0.42.1

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
                         ? {

package/dist/scripts/async-runner.mjs

@@ -135,7 +135,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     try {
       return readdirSync(sessionDir, { withFileTypes: true })
         .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-        .map((entry) => relative(stateDir, join(sessionDir, entry.name)))
+        .map((entry) => relative(stateDir, join(sessionDir, entry.name)).replaceAll("\\", "/"))
         .sort();
     } catch {
       return [];
@@ -167,12 +167,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(recipeContext ? { recipe_context: recipeContext } : {}),
       command: commandDetail,
       ...(materialized.promptFile
-        ? { prompt_file: relative(stateDir, materialized.promptFile) }
+        ? { prompt_file: relative(stateDir, materialized.promptFile).replaceAll("\\", "/") }
         : {}),
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
-      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir).replaceAll("\\", "/") } : {}),
       attempts: [],
       semantic_acceptance:
         options?.evidenceContext?.acceptOutput === "review_evidence" ||
@@ -209,11 +209,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       attempts.push({
         attempt,
         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,
         },
       });
@@ -248,12 +248,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(recipeContext ? { recipe_context: recipeContext } : {}),
       command: commandDetail,
       ...(materialized.promptFile
-        ? { prompt_file: relative(stateDir, materialized.promptFile) }
+        ? { prompt_file: relative(stateDir, materialized.promptFile).replaceAll("\\", "/") }
         : {}),
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
-      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir).replaceAll("\\", "/") } : {}),
       ...(commandSessionFiles(sessionDir).length > 0
         ? { session_files: commandSessionFiles(sessionDir) }
         : {}),
@@ -386,7 +386,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       command: commandDetail,
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
-      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
     });
     progressRunning();
     const captureDir = join(stateDir, "captures", commandId);
@@ -457,7 +457,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...captureDetails(result),
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
-      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir).replaceAll("\\", "/") } : {}),
       ...(commandSessionFiles(session.sessionDir).length > 0
         ? { session_files: commandSessionFiles(session.sessionDir) }
         : {}),

package/dist/scripts/build-dist.mjs

@@ -20,13 +20,18 @@ import { join } from "node:path";
 
 function run(command, args) {
   const result = spawnSync(command, args, { stdio: "inherit" });
+  if (result.error) throw result.error;
   if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
 rmSync("dist", { recursive: true, force: true });
 mkdirSync("dist", { recursive: true });
 
-run("tsc", ["-p", "tsconfig.build.json"]);
+run(process.execPath, [
+  join("node_modules", "typescript", "bin", "tsc"),
+  "-p",
+  "tsconfig.build.json",
+]);
 
 mkdirSync(join("dist", "pi-actors"), { recursive: true });
 writeFileSync(

package/dist/scripts/conformance.mjs

@@ -28,7 +28,12 @@ function packageRoot() {
 
 const result = spawnSync(
   process.execPath,
-  ["--experimental-strip-types", "--test", ...conformanceSuites],
+  [
+    "--experimental-strip-types",
+    "--test",
+    "--test-concurrency=1",
+    ...conformanceSuites,
+  ],
   { cwd: packageRoot(), encoding: "utf8", stdio: "pipe" },
 );
 

package/dist/scripts/recipe-utils.mjs

@@ -16,7 +16,7 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, extname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 
 function usage() {
   console.error(`Usage:
@@ -101,7 +101,7 @@ function collectRunSummary(rootValue) {
   const root = resolve(
     rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
   );
-  const files = walkFiles(root, 2).filter((file) => file.endsWith("/run.json"));
+  const files = walkFiles(root, 2).filter((file) => basename(file) === "run.json");
   const rows = [];
   for (const file of files) {
     const run = readJson(file);
@@ -118,7 +118,7 @@ function collectRunSummary(rootValue) {
     const progress = readJson(join(runDir, "progress.json"));
     const result = readJson(join(runDir, "result.json"));
     rows.push({
-      run: run.run_id ?? run.run ?? relative(root, file).split("/")[0],
+      run: run.run_id ?? run.run ?? relative(root, file).split(sep)[0],
       status: getRunStatus(run, progress, result),
       recipe: run.recipe ?? run.recipe_file ?? "",
       updated:

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use, including parallel actor launches, subagent fanout, and autonomous coordinator workflows. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.42.0
+  version: 0.42.1
 ---
 
 # Actors (pi-actors)

package/dist/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
 metadata:
-  version: 0.42.0
+  version: 0.42.1
 ---
 
 # Swarm

package/docs/actor-inspector.md

@@ -29,7 +29,7 @@ Escape    Close (or cancel the active options popup)
 
 Navigation stays bounded by available actions. `↑` on Run does nothing because no higher control exists. `↓` on Tabs enters the timeline only when it contains rows. Empty timelines therefore never receive focus.
 
-`K` appears only while Run is focused and the selected owned run reports `running`. It opens an in-overlay destructive confirmation; `Y`/Enter confirms and `N`/Escape cancels. Confirmation captures the immutable run generation and routes expected owner/generation through canonical `control.kill`; control compares both while serialized against same-directory restart, so terminal, ownership, or replacement-generation races reject without signaling. Success, cancellation, rejection, and failure remain bounded in the content area; terminal runs expose no Kill hint and reject a stale keypress.
+`K` appears only while Run is focused and the selected owned run reports `running`. It replaces the Inspector with a dedicated responsive `Confirm Actor Kill` overlay that names the exact `run:<id>`, shows its current status, and states that canonical `control.kill` is destructive and irreversible. Cancel owns initial focus; ←/→/Tab moves between Cancel and Kill actor, Enter activates the focused choice, `Y` confirms directly, and `N`/Escape cancels. Confirmation captures the immutable run generation and routes expected owner/generation through canonical `control.kill`; control compares owner, generation, and running status while serialized against same-directory restart, so terminal, ownership, or replacement-generation races reject without signaling. After the dialog closes, success, cancellation, rejection, and failure remain bounded in the Inspector content area; terminal runs expose no Kill hint and reject a stale keypress.
 
 Selection and focus remain separate visual states. Accent-blue text marks the current tab, active filter popup, and applied option. The Run control uses `← … →` markers plus a light neutral background to show both focus and horizontal cycling; menus and timeline rows retain the single `▶` focus marker, while selected tabs retain brackets. Opening a popup keeps its parent filter blue so the relationship remains visible. The footer uses accent color only for key names and arrows; descriptions remain muted.
 

package/docs/async-runs.md

@@ -83,12 +83,16 @@ Use `run_id` on async recipe tools or `as: "run:<id>"` on `spawn` when the calle
 
 Review commands that require semantic evidence apply marker acceptance before command completion accounting. Rejected code-zero output is reported consistently as a failed command in events, progress, evidence, and outbox delivery; it cannot emit a success-level completion notification. Evidence records are written before command launch and lifecycle cancellation or kill finalizes any running record with its interrupted state, effective exit code, and attempt capture paths. Async attempt stdout/stderr files exist from attempt start, so even small partial streams remain auditable when a command never returns.
 
+Terminal follow-ups carry one bounded semantic result in addition to run-file and artifact references. Direct `spawn` and saved async tools persist the originating tool-call correlation; callers may also provide `correlation_id` and a bounded scalar `transport_context`. A transport adapter can preserve an exact route such as `{ "transport": "telegram", "chat_id": 123456, "thread_id": 77 }`, and the same metadata is returned inside terminal follow-up details after detached completion. When a recipe advertises `review.completed`, an explicit matching outbox envelope wins; otherwise a successful accepted review result deterministically synthesizes one from the bounded beginning of `stdout.log`. Failed runs carry their bounded terminal error as `run.failed`.
+
+Watcher acceleration and periodic reconciliation share one live in-flight guard. Delivery remains at-least-once across the send/handled-marker crash window, but reentrant watcher/reconciliation races do not create parallel sends. A send failure leaves the run unhandled for retry, notifies the active operator, and persists bounded attempts/error/status evidence in `terminal-delivery-failure.json`; `getRunStatus` exposes the latest record as `terminal_delivery_failure`.
+
 ## State Files
 
 Use ordinary files under the extension temp directory so status tools stay simple and inspectable:
 
 - `.pi-actors-run-state.json`: runtime ownership marker binding the run id to the canonical state directory; launch reuse and destructive retention fail closed when it is absent, invalid, mismatched, or reached through a symlink alias. State reuse also fails closed whenever the persisted process identity mismatches a still-live pid, preventing corrupted metadata from admitting overlapping runners.
-- `run.json`: pid, cross-platform `process_identity` proof (start time, command, and canonical cwd where available), optional source metadata (`launch_source`, `tool`, `recipe`, `recipe_file`), command-template config, cwd, coordinator owner id, values, named `artifacts`, mailbox metadata, created time, and state dir. Existing launch cwd aliases are resolved through native `realpath` before proof matching, so symlinked working directories do not degrade control to `unsupported_proof`.
+- `run.json`: pid, cross-platform `process_identity` proof (start time, command, and canonical cwd where available), optional source metadata (`launch_source`, `tool`, `recipe`, `recipe_file`), `launch_correlation`, bounded scalar `transport_context`, command-template config, cwd, coordinator owner id, values, named `artifacts`, mailbox metadata, created time, and state dir. Existing launch cwd aliases are resolved through native `realpath` before proof matching, so symlinked working directories do not degrade control to `unsupported_proof`.
 - `communication.json`: compact actor communication snapshot with self/root/parent, default-room, member, and contact hints for room-aware scripts and agents.
 - `progress.json`: phase, active command count, completed count, failures, updated time, and optional `model_policy` provenance for inherited/explicit model and thinking values.
 - `events.jsonl`: append-only implementation lifecycle log.
@@ -98,6 +102,8 @@ Use ordinary files under the extension temp directory so status tools stay simpl
 - `captures/command-NNN/attempt-NNN/{stdout,stderr}.log`: complete byte-exact command streams, retained even below the bounded in-memory capture limit and separated across retries.
 - `review-evidence.json`: stable command/stage manifest linking prompts, repeated branches, capture attempts, byte counts, exit state, semantic marker acceptance, recipe context, and model/thinking policy; terminal status aligns with the run. Review pipelines inject prior-stage `ACTOR_EVIDENCE_REF` values into downstream prompts, record cited/missing report sources, and fail closed if a normalized report claims `complete` without every required reviewer, verifier, merger, and judge reference.
 - `result.json`: final code, killed flag, output selector, and optional full-output path.
+- `terminal-delivery-failure.json`: latest bounded failed follow-up attempt count, status, error, and timestamp; a later successful retry writes `terminal-handled.json`.
+- `terminal-handled.json`: durable proof that terminal follow-up delivery or an explicit terminal control completed; notification delivery writes it only after the follow-up send returns successfully.
 
 Public `spawn` always uses the runtime-owned run root; caller-selected state directories are rejected so `run:<id>` addressing and retention share one boundary. Internal adapters may still supply isolated state directories for deterministic fixtures, but those are not part of the public actor contract. Every launched runner also persists a process identity proof and revalidates it for status, state reuse, message delivery, cancellation, kill, and retirement; dead pids, reused-pid owner mismatches, and unavailable platform proofs remain distinct diagnostics and destructive controls fail closed.
 

package/docs/tool-registry.md

@@ -22,6 +22,8 @@ Because the user recipe directory is sticky agent muscle memory, runtime launche
 
 `register_tool` is the preferred agent-facing mutation API. It creates, updates, and deletes recipe files in `~/.pi/agent/recipes`; agents do not need to edit the files directly for normal registration. Extension-authored register, update, delete, draft-promotion, and usage-metadata mutations hold a cross-process lock keyed by filesystem-canonical recipe identity across the complete check/read/write/runtime-update window. Existing targets or the nearest existing parent are resolved through `realpath`, so real and symlink aliases serialize while unrelated recipes remain independent; stale locks are reclaimed only after their owner is proven dead. Direct file edits are still valid for operators and advanced agents. Runtime behavior is reactive: file creation, deletion, or edits in the user recipe root trigger validation and tool-set refresh, with invalid recipes surfaced as diagnostics rather than silently ignored. If the recipe root does not exist at session start, an advisory parent watcher detects its creation and switches to the normal root watcher; deletion or rename rearms the parent watcher without polling.
 
+Draft-consolidation journals capture root `dev` and `ino` from Node bigint stats and retain them as lossless decimal strings alongside lexical and native-real paths. Some network, virtual, or compatibility filesystems may report weak or zero device/inode identity; those values remain evidence but not a standalone trust claim because recovery also requires unchanged lexical paths, native realpaths, non-reparse directory roots, source/target hashes, and journal CAS. Native Windows regressions use unprivileged NTFS directory junctions to verify canonical mutation/lifecycle locks and fail-closed recovery after draft-root or trusted-root reparse substitution. This evidence supports the current portable process-crash and trusted-state-tree contract; a native handle-relative mutation layer is not justified unless real Windows runs expose a residual substitution window that these independent checks cannot fence.
+
 Inspect the loaded pi-actors runtime and discovered registry with:
 
 ```text

package/lib/async-runs.ts

@@ -16,7 +16,7 @@ import {
   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 type {
@@ -94,6 +94,29 @@ export interface AsyncRunControlEndpoint {
   type: "fifo" | "mailbox" | "named-pipe";
 }
 
+export function normalizeRunTransportContext(
+  value: unknown,
+): Record<string, string | number | boolean> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const normalized: Record<string, string | number | boolean> = {};
+  for (const [key, item] of Object.entries(
+    value as Record<string, unknown>,
+  ).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;
+}
+
 export interface AsyncRunStartParams {
   async?: boolean;
   control?: AsyncRunControlEndpoint;
@@ -102,6 +125,10 @@ export interface AsyncRunStartParams {
   lifecycleHooks?: {
     onLockContention?(): void;
   };
+  launch_correlation?: {
+    correlation_id?: string;
+    tool_call_id?: string;
+  };
   name?: string;
   ownerId?: string;
   run_id?: string;
@@ -126,6 +153,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>;
@@ -140,6 +168,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;
@@ -159,6 +191,7 @@ export interface AsyncRunMeta {
   process_identity?: RunProcessIdentity;
   recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
   retire_when?: "children_terminal";
+  transport_context?: Record<string, unknown>;
 }
 
 const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
@@ -242,7 +275,8 @@ function resolveRecipeFile(file: string): string {
 function isMutableUsageRecipeFile(file: string): boolean {
   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: string): AsyncRunStartParams {
@@ -498,6 +532,9 @@ export function startRun(
       ...(startParams.defaults || {}),
       ...values,
     };
+    const transportContext = normalizeRunTransportContext(
+      startParams.transport_context,
+    );
     const artifacts = resolveArtifactPaths(startParams.artifacts, outputValues);
     const meta: AsyncRunMeta = {
       argv: [process.execPath, ...argv],
@@ -506,6 +543,8 @@ export function startRun(
       ...(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 } : {}),
@@ -530,6 +569,8 @@ export function startRun(
       ...(startParams.retire_when === "children_terminal"
         ? { retire_when: "children_terminal" as const }
         : {}),
+      ...(transportContext
+        ? { transport_context: transportContext } : {}),
     };
     writeJsonAtomic(join(stateDir, "run.json"), meta);
     const child = spawn(process.execPath, argv, {
@@ -576,7 +617,7 @@ export type {
 
 function resolveRunStateDir(runOrDir: string): string {
   return resolve(
-    runOrDir.includes("/")
+    /[\\/]/u.test(runOrDir)
       ? runOrDir
       : join(DEFAULT_STATE_ROOT, safeRunId(runOrDir)),
   );
@@ -906,11 +947,11 @@ function finalizeInterruptedReviewEvidence(
             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,
               },
             };
@@ -1030,6 +1071,25 @@ export function markRunTerminalNotificationHandled(
   });
 }
 
+export function recordRunTerminalDeliveryFailure(
+  stateDir: string,
+  status: string,
+  error: unknown,
+): void {
+  const path = join(stateDir, "terminal-delivery-failure.json");
+  const previous = readJson(path);
+  const message = (error instanceof Error ? error.message : String(error))
+    .replaceAll(/\s+/g, " ")
+    .trim()
+    .slice(0, 500);
+  writeJsonAtomic(path, {
+    attempts: Math.max(0, Number(previous?.attempts ?? 0)) + 1,
+    error: message || "unknown delivery failure",
+    status,
+    ts: new Date().toISOString(),
+  });
+}
+
 export function cancelRun(
   runOrDir: string,
   expected: RunControlExpectation = {},

package/lib/command-templates.ts

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