@llblab/pi-actors 0.42.0 → 0.42.2

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) }
         : {}),
@@ -517,6 +517,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       };
       throw error;
     }
+    writeEvidenceManifest("done");
+    progress("done", {
+      completed: 1,
+      failures: result.details.nonCriticalFailures || [],
+    });
     writeJsonAtomic(resultPath, {
       code: result.details.code,
       command: result.details.command,
@@ -525,26 +530,11 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       truncated: result.details.truncated,
       completedAt: new Date().toISOString(),
     });
-    writeEvidenceManifest("done");
-    progress("done", {
-      completed: 1,
-      failures: result.details.nonCriticalFailures || [],
-    });
     event("run.done", { code: result.details.code });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const details = error && typeof error === "object" ? error.details : undefined;
     appendFileSync(stderrPath, `${message}\n`);
-    writeJsonAtomic(resultPath, {
-      code: typeof details?.code === "number" ? details.code : 1,
-      error: message,
-      killed: Boolean(details?.killed),
-      ...(Array.isArray(details?.branches) ? { branches: details.branches } : {}),
-      ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),
-      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
-      ...(details?.softQuorum ? { soft_quorum: details.softQuorum } : {}),
-      completedAt: new Date().toISOString(),
-    });
     writeEvidenceManifest("failed");
     progress("failed", {
       completed: 0,
@@ -555,6 +545,16 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
           : [{ message }],
       ...(details?.failureReason ? { failureReason: details.failureReason } : {}),
     });
+    writeJsonAtomic(resultPath, {
+      code: typeof details?.code === "number" ? details.code : 1,
+      error: message,
+      killed: Boolean(details?.killed),
+      ...(Array.isArray(details?.branches) ? { branches: details.branches } : {}),
+      ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),
+      ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
+      ...(details?.softQuorum ? { soft_quorum: details.softQuorum } : {}),
+      completedAt: new Date().toISOString(),
+    });
     event("run.failed", {
       error: message,
       ...(details?.failureReason ? { failure_reason: details.failureReason } : {}),

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.2
 ---
 
 # Actors (pi-actors)
@@ -69,7 +69,7 @@ Rules:
 - Command-template strings execute directly without a shell. Operators such as `&&`, `||`, pipes, redirects, and `cd` remain literal argv unless an explicit trusted shell is the executable. Prefer absolute paths or template arrays for sequencing; put non-trivial shell behavior in a reviewed script.
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
-- When a successful actor follow-up suggests persistence, decide whether the pattern deserves durable tool memory; call `register_tool` yourself only when the evidence is strong, and ask before writing the user recipe root.
+- Terminal follow-up context contains only run id, status, one base path, and relative artifact names. Inspect the run for contents; semantic output and correlation remain in non-LLM details and state. Decide whether a successful pattern deserves durable tool memory only after inspection, and ask before writing the user recipe root.
 - Use stable `as` names when you will inspect or message the actor later.
 - Public run state is runtime-owned; do not pass custom `state_dir` paths. This keeps `run:<id>` addressability and retention on one boundary.
 - `async: true` on the recipe is the detached run switch.
@@ -126,7 +126,7 @@ Views:
 - `artifacts`: declared artifact paths/status plus the same bounded owned review-evidence manifest when present.
 - `recipes` target: registry summary for active, shadowed, invalid, disabled, and diagnostic recipe entries.
 
-Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
+Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. Their LLM context content stays limited to run id, status, one base path, and relative artifact names; inspect state for raw output while correlation and semantic details remain outside LLM context. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
 
 ## Runtime Communication Rules
 

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.2
 ---
 
 # Swarm

package/docs/actor-inspector.md

@@ -29,9 +29,9 @@ 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.
+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. Key hints live directly in the bottom overlay border rather than a dedicated body row: border-accent `─` connectors run through and between them instead of bullet glyphs, while key names and arrows retain blue accent color and descriptions use the border accent.
 
 The top Run control aligns vertically with the tab labels, names the selected owned run, and colors its textual lifecycle status semantically. ←/→ cycles owned runs directly with wraparound, while Enter opens the complete owned-run list immediately beneath the control. That run list starts one cell farther left than the filter menus so its border aligns with the Run control rather than the tab/filter grid. It still overlays the tab row rather than leaving a detached gap. The timeline no longer renders run metadata as a data row.
 
@@ -39,7 +39,7 @@ Filters live behind their tab rather than occupying a permanent row. Non-default
 
 Nested menus overlay rather than replace the timeline. Only rows and columns containing menu borders or values occlude underlying cells. When adjacent menus have different heights, the unused corner remains transparent and preserves the separator, striped background, and timeline data beneath it. Every run, filter, and nested value menu is viewport-bounded: ↑/↓ moves through the complete option set, the visible window follows focus, and `↑`/`↓` border markers disclose hidden options above or below without growing past the available inspector rows.
 
-The overlay uses most of the available terminal width and height and reduces its content/menu viewport on shorter terminals. The bordered header keeps all three tabs visible, while the body shows the selected run and its current status above the active document or evidence rows. Run, Message, and Turn lists place the newest retained item directly below their control; a newly opened Inspector therefore selects the latest owned run, and ↓ moves backward in time toward older entries. Run options, Messages, and Turns all use compact descending `#N` labels, providing one timestamp-free time axis without repeating type words on every row. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. Unused viewport padding stays on the plain overlay background instead of drawing fake striped rows beneath the last item. The footer exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
+The overlay uses most of the available terminal width and height and reduces its content/menu viewport on shorter terminals. Its border-embedded key rail replaces the former three-row footer, returning two rows to a viewport that now caps at 24 rows. The bordered header keeps all three tabs visible, while the body shows the selected run and its current status above the active document or evidence rows. Run, Message, and Turn lists place the newest retained item directly below their control; a newly opened Inspector therefore selects the latest owned run, and ↓ moves backward in time toward older entries. Run options, Messages, and Turns all use compact descending `#N` labels, providing one timestamp-free time axis without repeating type words on every row. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. Unused viewport padding stays on the plain overlay background instead of drawing fake striped rows beneath the last item. The bottom frame exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
 
 ## Recipe Document
 

package/docs/async-runs.md

@@ -83,21 +83,27 @@ 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-up content stays deliberately minimal: run id, status, one base path, and relative artifact names only. With declared artifacts, `Base` names their common directory and `Artifacts` lists bounded relative names; without them, `Base` names the run state directory. It never embeds stdout, stderr, semantic body, terminal error, model policy, persistence advice, completion type, or an inspect command into LLM context. The follow-up's non-LLM details retain one bounded semantic result, launch/tool-call correlation, and optional bounded scalar `transport_context`; a transport adapter can preserve an exact route such as `{ "transport": "telegram", "chat_id": 123456, "thread_id": 77 }`. 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 retain their bounded terminal error as `run.failed` details.
+
+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.
-- `outbox.jsonl`: implementation storage for actor-message envelopes used by `inspect view=messages`, coordinator notifications, or follow-up context. Coordinator follow-ups preserve bounded `body` previews plus message metadata for decision points.
+- `outbox.jsonl`: implementation storage for actor-message envelopes used by `inspect view=messages`, coordinator notifications, or follow-up context. Script-authored decision-point follow-ups may preserve bounded `body` previews plus message metadata; automatic terminal follow-ups stay limited to run id, status, one base path, and relative artifact names.
 - `stdout.log` and `stderr.log`: detached process output.
 - `prompts/command-NNN.md`: state-owned prompt files that collapse child `pi -p` natural-language positional fragments and appended recipe context into one authoritative `@file` prompt while preserving intentional file/image arguments.
 - `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.
+- `result.json`: final code, killed flag, output selector, and optional full-output path. It publishes only after terminal `progress.json` and `review-evidence.json`, so readers never observe a result before its terminal state.
+- `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.
 
@@ -137,7 +143,7 @@ The core loop is:
    { "recipe": "music-player.json", "as": "run:music" }
    ```
 
-2. Let terminal completion, `command.done`, and script-authored follow-up messages reach the launching coordinator automatically. When a directly spawned inline/ad hoc actor or a recipe outside `~/.pi/agent/recipes` completes successfully, the coordinator follow-up tells the agent to offer recipe persistence only as a question to the operator; it must not auto-save.
+2. Let terminal completion, `command.done`, and script-authored follow-up messages reach the launching coordinator automatically. Terminal completion gives the coordinator only run id, status, a base path, and relative artifact names; inspect the run when result content changes the next decision. Decide whether a successful pattern deserves recipe persistence only after inspection and operator confirmation.
 
 3. Respond with explicit run-local messages when needed:
 

package/docs/recipe-library.md

@@ -135,7 +135,7 @@ The repeatable smoke surface is the normal validation suite:
 npm test
 ```
 
-The scenario coverage is intentionally local-first and bounded: shared room coordination and roster snapshots (`rooms` / `tools` tests), direct branch delivery and claim/handle transitions (`tools` and coordinator tests), inspector navigation (`inspector` tests), recipe context injection (`recipes-context` / async-runs tests), recipe persistence suggestions (`observability` tests), and opt-in retirement candidate/execution smoke (`observability` / async-runs tests). These scenarios exercise public `spawn` / `message` / `inspect` behavior or the packaged script surfaces rather than relying on manual swarm demos.
+The scenario coverage is intentionally local-first and bounded: shared room coordination and roster snapshots (`rooms` / `tools` tests), direct branch delivery and claim/handle transitions (`tools` and coordinator tests), inspector navigation (`inspector` tests), recipe context injection (`recipes-context` / async-runs tests), compact terminal follow-up delivery (`observability` tests), and opt-in retirement candidate/execution smoke (`observability` / async-runs tests). These scenarios exercise public `spawn` / `message` / `inspect` behavior or the packaged script surfaces rather than relying on manual swarm demos.
 
 ## Music Player
 

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,8 +569,17 @@ export function startRun(
       ...(startParams.retire_when === "children_terminal"
         ? { retire_when: "children_terminal" as const }
         : {}),
+      ...(transportContext
+        ? { transport_context: transportContext } : {}),
     };
     writeJsonAtomic(join(stateDir, "run.json"), meta);
+    writeJsonAtomic(join(stateDir, "progress.json"), {
+      completed: 0,
+      failures: [],
+      model_policy: modelPolicy,
+      phase: "starting",
+      updatedAt: new Date().toISOString(),
+    });
     const child = spawn(process.execPath, argv, {
       cwd,
       detached: true,
@@ -548,13 +596,6 @@ export function startRun(
     );
     if (processIdentity) meta.process_identity = processIdentity;
     writeJsonAtomic(join(stateDir, "run.json"), meta);
-    writeJsonAtomic(join(stateDir, "progress.json"), {
-      completed: 0,
-      failures: [],
-      model_policy: modelPolicy,
-      phase: "starting",
-      updatedAt: new Date().toISOString(),
-    });
     writeFileSync(
       join(stateDir, "events.jsonl"),
       `${JSON.stringify({ event: "run.start", run, run_instance_id: meta.run_instance_id, pid: meta.pid, ts: new Date().toISOString() })}\n`,
@@ -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;