@llblab/pi-actors 0.39.0 → 0.40.0

package/AGENTS.md

@@ -102,20 +102,25 @@ Pi host
 ## Runtime Contract
 
 - Register trusted command templates with placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary fallback, and split-first command argv construction.
+- Serialize extension-authored recipe mutations with the canonical-path file lock across the complete check/read/write/runtime-update window; keep usage telemetry in locked `.usage/<recipe-filename>.json` sidecars so metadata cannot overwrite authored recipes, and do not replace keyed locking with a broad registry lock.
 - Keep command templates synchronous and portable; `async: true` is the detached run switch.
 - Preserve node controls: `when`, positive `timeout`, `delay`, bounded `retry`, `failure`, and `recover` cleanup.
+- Persist every async command's complete byte-exact stdout/stderr under command- and retry-specific run-state paths while keeping returned tails bounded and pipeline stdin complete.
 - Keep async run state under `~/.pi/agent/tmp/pi-actors/runs` with injected `{run_id}` and `{state_dir}` values.
-- Preserve event-driven observability: terminal follow-ups, coordinator-bound outbox messages, branch-aware triangles, process-tree expansion, and bounded body previews.
-- Do not restore busy-polling examples, duplicate terminal follow-ups, or duplicate follow-ups for handled `cancel`, `kill`, or control-stop actions.
+- Preserve event-driven observability: durable retrying terminal steering notifications, coordinator-bound outbox messages, branch-aware triangles, process-tree expansion, and bounded body previews. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window.
+- When a deferred actor result gates the next step, wait for its terminal steering notification. Do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs; inspect early only on operator request, meaningful actor event, or diagnosis of an overdue/stuck run.
+- Do not restore busy-polling examples, duplicate terminal notifications, or duplicate notifications for handled `cancel`, `kill`, or control-stop actions.
 
 ## Recipes And Registry
 
 - `~/.pi/agent/recipes/*.json` is executable muscle memory: recipes there become persistent tools by location.
 - Preserve filename identity, atomic writes, explicit operator-gated changes, and local transportability.
+- Recipe live reload must watch the parent when the user recipe root is absent, switch to the root watcher when it appears, and rearm after deletion/rename without polling or duplicate watcher ownership.
 - Packaged/ad hoc recipes outside the agent root are components, not user tools.
 - Register existing recipes by importing them from the user-root wrapper and using a `{ "name": "alias" }` template node; do not duplicate a ready recipe's script command, defaults, mailbox, or artifact contract in the wrapper.
 - Skill-owned scripts must be exposed through skill-owned recipes first. If a local tool needs that capability, import the skill recipe via `{agent}/skills/<skill>/recipes/<recipe>.json` instead of calling `{agent}/skills/<skill>/scripts/*` directly.
 - Tool definitions use `template`, not `script`, and built-in/core tool names must not be shadowed.
+- Host registrations may remain visible because Pi cannot unregister dynamic definitions, but extension-local `message` and `inspect` lookup must consult the current runtime recipe registry before returning or executing a cached definition.
 - Packaged recipe growth is demand-driven: prefer reusable components over speculative scenario catalogs.
 - Recipe templates may point directly at executable helper scripts when the recipe owns that script boundary; keep script executable bits and avoid unnecessary `node` prefixes.
 
@@ -131,12 +136,14 @@ Pi host
 
 ## State, IO, And Safety
 
-- Tool stdout and temp state must stay bounded and local.
+- Tool stdout and temp state must stay bounded and local; preserve complete high-volume streams in spill files with byte/truncation metadata, and never feed a truncated capture tail into pipeline stdin.
 - Feedback hints must be evidence-backed, bounded, and action-shaped; prefer `next_actions` pointing to existing verbs over prose, and avoid hints when no concrete next step is justified.
 - Keep tail truncation, full-output temp files, failure formatting, and centralized limits intact.
 - Published docs must not include machine-local absolute paths.
 - Any view scanning run directories must apply coordinator/session ownership filters before exposing summaries or previews.
 - Direct branch messages are active inbox queues; guard branch-local append/status rewrites with the branch inbox lock and keep claim/handled/failed transitions tested.
+- Run-state launch and destructive retention require the runtime ownership marker bound to the canonical directory and run id; reject non-run directories, missing/mismatched markers, and symlink aliases rather than trusting `run.json`.
+- Runner lifecycle and destructive process controls require the persisted cross-platform process identity proof (start time, command, and cwd where available); dead, mismatched, or unsupported proofs stay distinct and fail closed rather than degrading to pid liveness.
 - Room/branch provenance checks should validate that accepted `from` addresses belong to the addressed run.
 
 ## Coordination And Lifecycle

package/BACKLOG.md

@@ -37,9 +37,9 @@ Non-goals:
 - Arbitrary subrooms.
 - Heavy broker abstraction.
 
-## Hotfix Backlog
+## Open Work
 
-No open hotfix items.
+No active implementation or release-preparation work remains. The `0.40.0` release candidate is validated locally; commit, tag, merge, publish, and release actions remain operator-gated rather than backlog work.
 
 ## Backlog Curation Rules
 
@@ -49,10 +49,6 @@ No open hotfix items.
 - Prefer semantic compression before file splitting: fewer public nouns, consistent outcomes, compact diagnostics, and domain-owned constants/helpers.
 - Preserve signal/noise balance: feedback should be state-backed, compact, and action-shaped; do not add advisory prose just because a surface exists.
 
-## Minor Backlog
-
-No open minor items.
-
 The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
 ## Explicitly Deferred
@@ -64,11 +60,6 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 - Cross-session force kill or attach/adopt/reparent: useful later, but ownership policy should not change until observability makes current boundaries clear.
 - Actor address helper CLI: keep diagnostics improving opportunistically inside existing parser/tests.
 - Golden flow docs and flow conformance runner: useful after the diagnostic and promotion surfaces are stable.
-- Documentation refactor: defer until the canonical mailbox loop and worker recipe exist; avoid rewriting docs twice.
 - Host-level tool unregistration: blocked on host API support.
 - Branch-local checkpoint semantics: wait for real collaborative branch-runner experiments.
 - Actor recipe feedback loop: keep advisory and operator-gated after real runs produce evidence.
-
-## Suggested Milestone Order
-
-1. Re-curate after the next real packaged review-swarm dogfood run.

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## Unreleased
 
+## 0.40.0: Durable Review and Runtime Hardening
+
+- `[Runtime]` Collapsed every natural-language positional fragment in child `pi -p` launches into one inspectable prompt file while preserving Pi options and intentional `@file` attachments, so review stages receive one authoritative user turn and preflight diagnostics resolve the concrete stage.
+- `[Tests]` Made the packaged review-readiness dogfood fake Pi reject fragmented prompt argv, covering preflight, reviewer, verifier, merger, judge, and normalizer transport through the real detached runner.
+- `[Reviews]` Added opt-in `accept_output: review_evidence` semantics and marked packaged reviewer, verifier, merger, judge, and normalizer outputs with `ACTOR_REVIEW_RESULT`, so code-zero format acknowledgements or input requests fail closed instead of satisfying quorum or reaching later stages.
+- `[Diagnostics]` Preserved rejected parallel stdout alongside its semantic rejection reason, allowing degraded review runs to retain accepted and rejected branch evidence without counting placeholders as usable.
+- `[Breaking]` Removed public `spawn.state_dir` overrides and reject direct attempts with a retention-safety diagnostic, keeping every public `run:<id>` actor under the runtime-owned addressable run root.
+- `[Safety]` Added canonical run-state ownership markers and require them before launch reuse, archive, or prune; existing non-run directories, forged metadata, mismatched run ids, and symlink aliases now fail closed before destructive retention.
+- `[Safety]` Added and persisted Linux, macOS, and Windows process-identity proofs with start-time, command, and available cwd evidence; status, state reuse, message delivery, cancellation, kill, and retirement now distinguish dead pids, owner mismatches, unsupported proofs, and valid ownership instead of degrading to liveness alone.
+- `[Execution]` Bounded stdout and stderr tails while child commands are running, spilling complete high-volume streams independently with total byte counts, truncation flags, and diagnostic file paths instead of accumulating unbounded strings in memory.
+- `[Execution]` Propagated capture metadata through foreground results, retries, parallel branch diagnostics, and async run events; sequence and parallel pipelines now fail closed with `incomplete pipeline stdin` instead of feeding truncated tails downstream.
+- `[Registry]` Added cross-process file mutation locks keyed by canonical recipe path and wrapped register, update, delete, and draft-promotion windows; concurrent same-name registrations now have one explicit winner.
+- `[Registry]` Moved user-recipe usage telemetry into locked `.usage/<recipe-filename>.json` sidecars and merge it during discovery, so sibling-process counters remain monotonic while external recipe edits and file-watcher refreshes cannot be overwritten by metadata writes.
+- `[Routing]` Made `message to=tool:<name>` and `inspect tool:<name>` resolve definitions only when the current runtime recipe registry still marks the tool active; deleted/external-removed recipes are revoked immediately and updates route only to the newest extension-local definition despite host-level unregister limitations.
+- `[Retention]` Made pruned artifact preservation collision-safe with readable artifact-name/hash/basename targets and timestamp preservation; duplicate basenames remain distinct, missing optional artifacts stay skipped, and any copy failure aborts before source run state is deleted.
+- `[Registry]` Rearmed recipe live reload through an advisory parent watcher when `~/.pi/agent/recipes` is absent or renamed, switching back to the root watcher on creation and reloading on deletion; first-run creation, recreation, and idempotent shutdown now work without polling or session restart.
+- `[Backlog]` Rewrote the remaining packaged hardening review milestone as ordered open-checkbox tasks with decision-grade evidence, finding classification, reconciliation, and validation exit criteria.
+- `[Review]` Completed the six-lens packaged hardening pipeline above quorum. The normalized verdict was blocked by a reproduced UTF-8 capture defect; other reported concerns remained hypotheses because raw stage outputs were not retained for independent audit. Re-curated the backlog around durable per-stage review evidence before the next release-readiness run.
+- `[Execution]` Preserved raw command bytes across stream chunk boundaries and aligned bounded tails to UTF-8 code-point boundaries, preventing split multibyte output from becoming replacement characters while keeping complete spill files byte-exact.
+- `[Actors]` Added an async-patience invariant to the runtime prompt, project context, and bundled actors skill: when deferred actor output gates the next step, wait for the terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the reviewed scope.
+- `[Backlog]` Decomposed durable review provenance into nine ordered open tasks covering byte-exact stage output, evidence manifests, bounded inspection, report references, regression proof, re-review, finding classification, and final context validation.
+- `[Evidence]` Persisted complete stdout and stderr for every async command, including small streams, under collision-safe `captures/command-NNN/attempt-NNN/{stdout,stderr}.log` identities; retries remain distinct while bounded result tails and complete pipeline stdin behavior stay unchanged.
+- `[Evidence]` Added terminal `review-evidence.json` manifests mapping stable command/stage occurrences and repeated branches to prompts, byte-exact attempt files, byte counts, truncation, exit state, semantic marker acceptance, recipe context, and inherited/explicit model policy; manifests update during execution and finish with aligned `done`/`failed` status.
+- `[Inspector]` Exposed owned review-evidence manifests and referenced capture paths through existing `inspect run:<id> view=files|artifacts` responses, bounding command entries by `lines` and reporting total/truncated counts without adding a public verb or bypassing session ownership checks.
+- `[Review Evidence]` Injected stable prior-stage `ACTOR_EVIDENCE_REF` entries into verifier, merger, judge, and normalizer prompts; normalized reports now retain auditable reviewer/downstream references, terminal manifests record cited and missing sources, and a report claiming `complete` fails closed when any required reviewer, verifier, merger, or judge reference is absent.
+- `[Review Dogfood]` Expanded deterministic provenance coverage across small, spilled, UTF-8, retry, parallel, semantic-marker rejection, partial-quorum, and terminal paths; the packaged review fixture now reconstructs reviewer branch identity, accepted/rejected counts, rejected raw output, downstream source references, final degraded status, and exactly-once capture files solely from retained run state.
+- `[Review]` Completed the auditable six-lens `hardening-review-040` run with all 14 stages accepted and every required evidence reference retained. Re-curated confirmed release blockers covering canonical alias locks, live owner-mismatch reuse, symlink-cwd identity, public custom state directories, complete large-pipeline stdin, exact evidence markers, semantic notification alignment, interrupted evidence finalization, and missed terminal replay; kept the cancellation timing race and native platform gaps explicitly unconfirmed.
+- `[Locking]` Keyed mutation locks by filesystem identity: existing targets or nearest existing ancestors are resolved through native `realpath`, nonexistent suffixes are preserved, Windows identities are case-normalized, and stale lock directories are reclaimed only after their persisted owner PID is proven dead. Added a cross-process real-parent/symlink-parent serialization regression.
+- `[Run Safety]` Made live `owner_mismatch` state reuse fail closed in both preflight and state-directory preparation, including terminal-result timing windows; tampered process identity can no longer clear/reuse an occupied run directory while its original runner remains alive.
+- `[Process Identity]` Canonicalized existing launch cwd paths through native `realpath` before matching the runner's process proof, with Windows case normalization; Linux integration now proves a symlinked launch cwd retains a valid, controllable process identity while injected Darwin/Windows contracts remain intact.
+- `[Public Boundary]` Removed lifecycle `state_dir` from `register_tool`, persisted/co-located recipe normalization, generated schemas, result details, serialization, recipe-reference resolution, and prompt copy. Legacy stored values are ignored, and registered async tools now always launch under the runtime-owned run root where `run:<id>` inspection, messaging, indexing, and retention agree.
+- `[Pipeline Dataflow]` Downstream sequence commands now receive complete spilled stdout from sequential and parallel producers while model-facing output, branch reports, and diagnostics remain bounded. Missing or unreadable spill files still fail closed; exact >1 MiB consumer-count regressions cover both composition shapes.
+- `[Review Evidence]` Tightened semantic acceptance to require `ACTOR_REVIEW_RESULT` as the exact first non-whitespace line in both execution policy and persisted evidence manifests; prefixed markers such as `ACTOR_REVIEW_RESULT_BOGUS` now fail with code 65 and remain rejected evidence.
+- `[Review Notifications]` Applied semantic output acceptance before async command accounting, so rejected code-zero review output is consistently recorded as code 65 in `command.done`, terminal progress failures, evidence, and outbox summaries, with follow-up delivery and error severity instead of a false success notification.
+- `[Interrupted Evidence]` Review evidence records now exist before command launch and are finalized as `cancelled` or `killed` by lifecycle control even when the command never returns. Async captures create byte-exact stdout/stderr files at attempt start, preserving small partial streams as well as spills; manifests retain interruption status, signal-derived effective exit code, capture bytes, and semantic interruption state.
+- `[Terminal Delivery]` Terminal actor notifications now use Pi steering with `triggerTurn: true`: busy agents receive completion at the next safe tool boundary and idle agents start a normal turn without a racy manual idle check. Unhandled owned terminal runs retry during same-runtime and replacement reconciliation until `terminal-handled.json` is written after a successful send, without replaying historical outbox traffic. Delivery is honestly at-least-once: a process crash between send and marker persistence may duplicate a notification.
+- `[Cancel Race]` Authoritative terminal result/control state now short-circuits cancel/kill before process-identity probing because no signal will be sent. This removes transient `unsupported proof` classifications while preserving fail-closed identity checks for running processes and derived `exited` states; a 30-run completion/cancel stress regression consistently returns `not running`.
+- `[Release Review]` Completed the final six-lens hardening review with all branches and downstream stages successful and durable evidence under `hardening-review-040-final`. The review blocked release on five bounded correctness findings: large marked-output acceptance, cross-process registry collision state, live aged start locks, same-runtime terminal-delivery retry, and disappearing-run inspection tolerance. Per operator direction, no further reviewer runs are required before release; fixes use local regressions and validation.
+- `[Large Review Output]` Semantic marker acceptance now reads byte-complete captured stdout when the bounded tail is truncated, while returned model-facing output remains bounded. Foreground and async regressions prove valid `ACTOR_REVIEW_RESULT` output above 1 MiB succeeds and persists accepted evidence metadata.
+- `[Registry Collision]` Same-name registration now rereads authoritative recipe state while holding the canonical cross-process mutation lock instead of trusting a process-local tool map. A sibling-process regression proves exactly one create wins and the loser receives the explicit `update=true` collision error without overwriting the recipe.
+- `[Start Lock Ownership]` Run-start locks now persist the starter's process identity and aged locks are reclaimed only when the recorded PID is proven dead. Live, mismatched, unavailable, and malformed ownership proofs remain protected regardless of age; regressions cover both live-owner retention and dead-owner recovery.
+- `[Inspection TOCTOU]` Runtime triage now treats a run that disappears between inventory and status read as a skipped stale entry instead of failing the entire inspection. Injectable inventory/status ports provide a deterministic disappearance regression without weakening ownership filtering for surviving runs.
+- `[Package Entrypoint]` Added a named compiled wrapper at `dist/pi-actors/index.js` and pointed package metadata to it, preserving the compiled runtime while making Pi's extension list identify `pi-actors` instead of the anonymous parent label `dist`.
+- `[Release]` Updated package, lockfile, bundled skill metadata, compiled assets, and changelog identity for the release candidate; validation, conformance, package dry-run, diff checks, and context reconciliation are green.
+
 ## 0.39.0: Actor Kernel Welcome Refresh
 
 - `[Docs]` Reworked the root README as a product/onboarding entrypoint for the local actor kernel, with clearer positioning, first-run path, feature showcase, recipe-memory model, address/message examples, and practical surface-selection guidance. Impact: new operators can understand when to use `spawn`, `message`, `inspect`, recipes, rooms, and artifacts without reading deep implementation docs first.

package/README.md

@@ -56,7 +56,7 @@ Or from git:
 pi install git:github.com/llblab/pi-actors
 ```
 
-The npm package is dist-first for JavaScript-only runtimes: Pi metadata points at compiled `dist/` entrypoints and mirrored runtime assets. Source TypeScript and source skills remain packaged for TypeScript-native or checkout-based runtimes.
+The npm package is dist-first for JavaScript-only runtimes: Pi metadata points at the named compiled entrypoint `dist/pi-actors/index.js` plus mirrored runtime assets, so extension discovery identifies `pi-actors` rather than an anonymous `dist` directory. Source TypeScript and source skills remain packaged for TypeScript-native or checkout-based runtimes.
 
 ## First run: actor mode in one minute
 
@@ -125,12 +125,12 @@ Routing comes from `to`, actor ownership, and runtime policy. `type` describes i
 | --- | --- | --- |
 | Command templates | Portable command graphs with placeholders, defaults, guards, retries, parallel nodes, recovery, and timeouts | Wrap a trusted local executable without writing a bespoke tool |
 | Recipes | JSON/Markdown capability specs with metadata, args, defaults, imports, mailbox contracts, artifacts, and async mode | Save a known-good local workflow as reusable muscle memory |
-| Async runs | File-backed detached lifecycle, logs, progress, output, cancellation, artifacts, and terminal follow-ups | Let model work, media jobs, services, or pipelines continue after the turn |
+| Async runs | File-backed detached lifecycle, logs, progress, output, cancellation, artifacts, and durable terminal steering notifications | Let model work, media jobs, services, or pipelines continue after the turn |
 | Message protocol | Typed envelopes across run, tool, branch, room, coordinator, and session targets | Continue, approve, kill, or route work without restarting actors |
 | Rooms and rosters | Run-local group timeline with actor join/leave, contacts, previews, and branch-aware delivery | Coordinate multiple subagents under one visible run |
 | Registry and recipe doctor | Discovered tools, overrides, drafts, invalid recipes, and advisory risk labels | Audit local capability memory before using or promoting it |
 | Draft promotion | Captured ad hoc spawn patterns can become explicit recipes after operator approval | Turn successful improvisation into durable local tools |
-| Review/swarm recipes | Maintained packaged pipelines with preflight, quorum knobs, model/thinking inheritance, prompt-file transport, and diagnostics | Delegate reviews without rebuilding fanout commands |
+| Review/swarm recipes | Maintained packaged pipelines with preflight, marked semantic evidence, quorum knobs, model/thinking inheritance, one-turn prompt-file transport, and diagnostics | Delegate reviews without rebuilding fanout commands |
 | Actor inspector | Compact TUI/debug views for active actor coordination, unread branch inboxes, room messages, and attention markers | Watch only the actor traffic that matters right now |
 | Packaged recipe QA | Installed-package-safe checks for helper paths, mailbox contracts, platform scope, artifacts, and recipe structure | Keep shipped actor components executable and diagnosable |
 
@@ -275,7 +275,7 @@ Packaged recipes are building blocks. Use `spawn file=<recipe>` for maintained p
 | A useful output that should survive context compression | Artifacts |
 | A repeated local workflow | Recipe/tool memory |
 
-When a directly spawned inline/ad hoc actor or a recipe outside the user recipe root completes successfully, `pi-actors` may send the launching agent a follow-up suggesting promotion. The agent should ask first and never auto-save.
+When a directly spawned inline/ad hoc actor or a recipe outside the user recipe root completes successfully, `pi-actors` may include a promotion suggestion in its terminal steering notification. The agent should ask first and never auto-save.
 
 ## Platform support
 

package/dist/index.js

@@ -30,7 +30,7 @@ export default function toolRegistryExtension(pi) {
             sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
         });
     };
-    const updateRunUi = (ctx, notify = false) => {
+    const updateRunUi = (ctx, notify = false, terminalOnly = false) => {
         const ownerId = getRunOwnerId(ctx);
         const snapshot = Observability.readRunUiSnapshot(runUi, ownerId);
         ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
@@ -62,7 +62,9 @@ export default function toolRegistryExtension(pi) {
         retireCandidateRuns(ctx, snapshot.summary);
         Observability.deliverRunTransitionNotifications(snapshot.transitions, notificationSink);
         Observability.pruneRunUiObservationState(runUi, snapshot);
-        Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, notificationSink);
+        if (!terminalOnly) {
+            Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, notificationSink);
+        }
     };
     const closeRunWatchers = () => {
         runWatcher.close();
@@ -126,7 +128,7 @@ export default function toolRegistryExtension(pi) {
         activeRunContext = ctx;
         await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
         runtime.loadTools(ctx);
-        updateRunUi(ctx);
+        updateRunUi(ctx, true, true);
         closeRunWatchers();
         recipeReload.close();
         runWatcher.refresh();
@@ -178,7 +180,7 @@ export default function toolRegistryExtension(pi) {
     Pi.registerToolDefinitions(pi, Tools.createCoreActorToolDefinitions({
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         getActiveTools: () => pi.getActiveTools(),
-        getRuntimeTool: (name) => actorToolDefinitions.get(name),
+        getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
         registryRuntime: runtime,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     }).map(withCurrentThinkingContext));

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

@@ -7,6 +7,7 @@ import { type CurrentPolicyProvenance } from "./model-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
 import { type RunOutboxEvent } from "./runs-outbox.ts";
+import { type RunProcessIdentity } from "./runs-process.ts";
 import * as RunsIndex from "./runs-index.ts";
 import { type ProcessRunInboxResult, type RunInboxMessage, type RunInboxStatus } from "./runs-mailbox.ts";
 import { type SendRunMessageOptions } from "./runs-messages.ts";
@@ -35,6 +36,7 @@ export interface AsyncRunStartParams {
     when?: boolean | string;
     timeout?: number | string;
     delay?: number | string;
+    accept_output?: "review_evidence";
     output?: string;
     artifacts?: Record<string, RunArtifactDeclaration>;
     mailbox?: RecipesReferences.TemplateRecipeMailbox;
@@ -68,6 +70,7 @@ export interface AsyncRunMeta {
     control?: AsyncRunControlEndpoint;
     mailbox?: RecipesReferences.TemplateRecipeMailbox;
     model_policy?: CurrentPolicyProvenance;
+    process_identity?: RunProcessIdentity;
     recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
 }
@@ -112,6 +115,7 @@ export type { SendRunMessageOptions } from "./runs-messages.ts";
 export declare function sendRunMessage(runOrDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;
 export { getRunProcessSignalPlan } from "./runs-control.ts";
 export type { RunProcessSignalPlan } from "./runs-control.ts";
+export declare function markRunTerminalNotificationHandled(stateDir: string, status: string): void;
 export declare function cancelRun(runOrDir: string): Record<string, unknown>;
 export declare function archiveRun(runOrDir: string): Record<string, unknown>;
 export declare function pruneRun(runOrDir: string, options?: {

package/dist/lib/async-runs.js

@@ -3,8 +3,8 @@
  * Owns launch, state observation, listing, message/control facade methods, and retention while runs-* subdomains own narrower run internals.
  */
 import { spawn } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, writeFileSync, } from "node:fs";
-import { basename, dirname, extname, join, resolve } from "node:path";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeJsonAtomic } from "./file-state.js";
 import { CURRENT_MODEL_VALUE_KEY, CURRENT_THINKING_VALUE_KEY, describeCurrentPolicyProvenance, } from "./model-context.js";
@@ -15,8 +15,9 @@ import { resolveArtifactPaths, } from "./runs-artifacts.js";
 import { safeRunId } from "./runs-identity.js";
 import { buildTerminalProgress, markTerminalHandled, signalOwnedRunProcess, } from "./runs-control.js";
 import { buildRunOutboxEventPayload, parseRunOutboxEventLine, } from "./runs-outbox.js";
+import { claimRunStateDirectory } from "./runs-ownership.js";
 import { archiveTerminalRun, pruneTerminalRun } from "./runs-retention.js";
-import { isAlive, isWithinRunnerIdentityGrace, pidMatchesRun, } from "./runs-process.js";
+import { captureRunProcessIdentity, verifyRunProcessIdentity, } from "./runs-process.js";
 import * as RunsStart from "./runs-start.js";
 import * as RunsIndex from "./runs-index.js";
 import { claimRunInboxMessageInStateDir, parseRunInboxLine, processRunInboxMessagesInStateDir, runInboxFile, updateRunInboxMessageStatusInStateDir, } from "./runs-mailbox.js";
@@ -57,6 +58,7 @@ function resolveRunTemplate(params) {
         "when",
         "timeout",
         "delay",
+        "accept_output",
         "output",
         "retry",
         "failure",
@@ -228,6 +230,7 @@ export function startRun(params, cwd) {
     mkdirSync(stateDir, { recursive: true });
     const releaseStartLock = acquireStateStartLock(stateDir);
     try {
+        claimRunStateDirectory(stateDir, run);
         assertNoActiveRunState(stateDir);
         prepareStateDirForStart(stateDir);
         const stdout = join(stateDir, "stdout.log");
@@ -289,6 +292,9 @@ export function startRun(params, cwd) {
         closeSync(outFd);
         closeSync(errFd);
         meta.pid = child.pid ?? 0;
+        const processIdentity = captureRunProcessIdentity(meta.pid, cwd, stateDir, RUNNER_PATH);
+        if (processIdentity)
+            meta.process_identity = processIdentity;
         writeJsonAtomic(join(stateDir, "run.json"), meta);
         writeJsonAtomic(join(stateDir, "progress.json"), {
             completed: 0,
@@ -384,14 +390,18 @@ export async function sendRunMessage(runOrDir, message, options = {}) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
     const run = String(status.run ?? runOrDir);
-    if (status.status !== "running")
-        throw new Error(`Run is not running: ${run}`);
     const pid = Number(status.pid || 0);
-    if (!pid || !isAlive(pid))
-        throw new Error(`Run pid is not alive: ${run}`);
-    if (!pidMatchesRun(pid, String(status.cwd), stateDir, RUNNER_PATH) &&
-        !isWithinRunnerIdentityGrace(status, RUNNER_IDENTITY_GRACE_MS))
-        throw new Error(`Run pid owner mismatch: ${run}`);
+    const identity = verifyRunProcessIdentity(pid, status.process_identity);
+    if (status.status !== "running") {
+        if (identity.status === "owner_mismatch" ||
+            identity.status === "unsupported_proof") {
+            throw new Error(`Run process identity ${identity.status}: ${run}`);
+        }
+        throw new Error(`Run is not running: ${run}`);
+    }
+    if (!identity.valid) {
+        throw new Error(`Run process identity ${identity.status}: ${run}`);
+    }
     return deliverRunMessage(status, run, stateDir, message, options);
 }
 export { getRunProcessSignalPlan } from "./runs-control.js";
@@ -402,26 +412,111 @@ function markTerminalProgress(stateDir, phase) {
         : undefined;
     writeJsonAtomic(join(stateDir, "progress.json"), buildTerminalProgress(progress, phase));
 }
+function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
+    const evidencePath = join(stateDir, "review-evidence.json");
+    const manifest = readJson(evidencePath);
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        return;
+    const record = manifest;
+    if (!Array.isArray(record.commands))
+        return;
+    const completedAt = new Date().toISOString();
+    const effectiveExitCode = signal === "SIGKILL" ? 137 : 143;
+    const commands = record.commands.map((command) => {
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            return command;
+        }
+        const entry = command;
+        if (entry.status !== "running" || typeof entry.id !== "string")
+            return entry;
+        const captureDir = join(stateDir, "captures", entry.id);
+        const attempts = existsSync(captureDir)
+            ? readdirSync(captureDir)
+                .filter((name) => /^attempt-\d+$/.test(name))
+                .sort()
+                .map((name, index) => {
+                const attemptDir = join(captureDir, name);
+                const stdoutFile = join(attemptDir, "stdout.log");
+                const stderrFile = join(attemptDir, "stderr.log");
+                return {
+                    attempt: index + 1,
+                    stdout: {
+                        path: relative(stateDir, stdoutFile),
+                        bytes: existsSync(stdoutFile) ? statSync(stdoutFile).size : 0,
+                    },
+                    stderr: {
+                        path: relative(stateDir, stderrFile),
+                        bytes: existsSync(stderrFile) ? statSync(stderrFile).size : 0,
+                    },
+                };
+            })
+            : [];
+        return {
+            ...entry,
+            status: phase,
+            completed_at: completedAt,
+            attempts,
+            effective_exit_code: effectiveExitCode,
+            killed: true,
+            ...(entry.semantic_acceptance === "pending"
+                ? { semantic_acceptance: "interrupted" }
+                : {}),
+        };
+    });
+    writeJsonAtomic(evidencePath, {
+        ...record,
+        status: phase,
+        commands,
+        updated_at: completedAt,
+    });
+}
 function stopRun(runOrDir, signal, event) {
     const status = getRunStatus(runOrDir);
     const pid = Number(status.pid || 0);
     const stateDir = String(status.state_dir);
-    if (status.status !== "running")
+    if (status.status !== "running" && status.status !== "exited") {
         return { stopped: false, reason: "not running", status };
-    if (!pid || !isAlive(pid))
-        return { stopped: false, reason: "pid not alive", status };
-    if (!pidMatchesRun(pid, String(status.cwd), stateDir, RUNNER_PATH)) {
-        return { stopped: false, reason: "pid owner mismatch", status };
+    }
+    const identity = verifyRunProcessIdentity(pid, status.process_identity);
+    if (status.status === "exited") {
+        if (identity.status === "owner_mismatch" ||
+            identity.status === "unsupported_proof") {
+            return {
+                stopped: false,
+                reason: identity.status.replaceAll("_", " "),
+                process_identity_status: identity.status,
+                status,
+            };
+        }
+        return { stopped: false, reason: "not running", status };
+    }
+    if (!identity.valid) {
+        return {
+            stopped: false,
+            reason: identity.status.replaceAll("_", " "),
+            process_identity_status: identity.status,
+            status,
+        };
     }
     const signalResult = signalOwnedRunProcess(pid, signal);
     writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event, pid, signal, ...signalResult, ts: new Date().toISOString() })}\n`, { flag: "a" });
     markTerminalHandled(stateDir, { event, signal });
-    if (event === "run.kill")
+    if (event === "run.kill") {
+        finalizeInterruptedReviewEvidence(stateDir, "killed", signal);
         markTerminalProgress(stateDir, "killed");
-    if (event === "run.cancel")
+    }
+    if (event === "run.cancel") {
+        finalizeInterruptedReviewEvidence(stateDir, "cancelled", signal);
         markTerminalProgress(stateDir, "cancelled");
+    }
     return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
 }
+export function markRunTerminalNotificationHandled(stateDir, status) {
+    markTerminalHandled(stateDir, {
+        event: "run.notification",
+        status,
+    });
+}
 export function cancelRun(runOrDir) {
     const result = stopRun(runOrDir, "SIGTERM", "run.cancel");
     return Object.hasOwn(result, "stopped")

package/dist/lib/command-templates.d.ts

@@ -23,6 +23,7 @@ export interface CommandTemplateObjectConfig {
     defaults?: Record<string, unknown>;
     timeout?: number | string;
     delay?: number | string;
+    accept_output?: "review_evidence";
     output?: string;
     retry?: number | string;
     failure?: CommandTemplateFailureScope;
@@ -45,12 +46,20 @@ export interface CommandTemplateExecOptions {
     stdin?: string;
     killGrace?: number;
     retry?: number;
+    captureDir?: string;
+    captureLimitBytes?: number;
 }
 export interface CommandTemplateExecResult {
     stdout: string;
     stderr: string;
     code: number;
     killed: boolean;
+    stdoutBytes?: number;
+    stderrBytes?: number;
+    stdoutFile?: string;
+    stderrFile?: string;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
 }
 export type CommandTemplateRiskLabel = "risk.shell" | "risk.eval" | "risk.broad_fs_write" | "risk.destructive_fs" | "risk.network" | "risk.external_side_effect" | "risk.long_running" | "risk.platform_specific" | "risk.secret_touching";
 export type CommandTemplateExecCommand = (command: string, args: string[], options?: CommandTemplateExecOptions) => Promise<CommandTemplateExecResult>;

package/dist/lib/command-templates.js

@@ -4,8 +4,10 @@
  * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 import { spawn } from "node:child_process";
-import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, resolve as resolvePath } from "node:path";
+const DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES = 1024 * 1024;
 const COMMAND_TEMPLATE_RISK_LABEL_ORDER = [
     "risk.shell",
     "risk.eval",
@@ -386,9 +388,9 @@ export function expandCommandTemplateExecutable(command, cwd) {
     if (command === "~")
         return homedir();
     if (command.startsWith("~/"))
-        return resolve(homedir(), command.slice(2));
+        return resolvePath(homedir(), command.slice(2));
     if (command.includes("/") && !isAbsolute(command))
-        return resolve(cwd, command);
+        return resolvePath(cwd, command);
     return command;
 }
 function evaluateCommandTemplateExpression(expression, values) {
@@ -592,13 +594,67 @@ export async function execCommandTemplate(command, args, options = {}) {
         killed: false,
     };
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        const result = await execCommandTemplateOnce(command, args, options);
+        const attemptOptions = options.captureDir
+            ? {
+                ...options,
+                captureDir: join(options.captureDir, `attempt-${String(attempt).padStart(3, "0")}`),
+            }
+            : options;
+        const result = await execCommandTemplateOnce(command, args, attemptOptions);
         if (result.code === 0)
             return result;
         lastResult = result;
     }
     return lastResult;
 }
+function trimCaptureTail(value, limit) {
+    if (value.length <= limit)
+        return value;
+    let start = value.length - limit;
+    while (start < value.length && (value[start] & 0xc0) === 0x80)
+        start += 1;
+    return value.subarray(start);
+}
+function createBoundedCommandCapture(stream, limit, getCaptureDir, persistCompleteStream) {
+    let bytes = 0;
+    let content = Buffer.alloc(0);
+    let file = persistCompleteStream
+        ? join(getCaptureDir(), `${stream}.log`)
+        : undefined;
+    if (file)
+        writeFileSync(file, Buffer.alloc(0));
+    let truncated = false;
+    return {
+        append(value) {
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            bytes += chunk.length;
+            if (bytes > limit)
+                truncated = true;
+            if (!file && bytes <= limit) {
+                content = Buffer.concat([content, chunk]);
+                return;
+            }
+            if (!file) {
+                file = join(getCaptureDir(), `${stream}.log`);
+                writeFileSync(file, content);
+            }
+            appendFileSync(file, chunk);
+            content = trimCaptureTail(Buffer.concat([content, chunk]), limit);
+        },
+        result() {
+            if (!file && persistCompleteStream) {
+                file = join(getCaptureDir(), `${stream}.log`);
+                writeFileSync(file, content);
+            }
+            return {
+                bytes,
+                content: content.toString("utf8"),
+                ...(file ? { file } : {}),
+                truncated,
+            };
+        },
+    };
+}
 function execCommandTemplateOnce(command, args, options = {}) {
     return new Promise((resolve) => {
         const proc = spawn(command, args, {
@@ -606,8 +662,20 @@ function execCommandTemplateOnce(command, args, options = {}) {
             shell: false,
             stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
         });
-        let stdout = "";
-        let stderr = "";
+        const captureLimit = Math.max(1, options.captureLimitBytes ?? DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES);
+        let captureDir;
+        const getCaptureDir = () => {
+            if (captureDir)
+                return captureDir;
+            captureDir = options.captureDir
+                ? resolvePath(options.captureDir)
+                : mkdtempSync(join(tmpdir(), "pi-actors-command-"));
+            mkdirSync(captureDir, { recursive: true });
+            return captureDir;
+        };
+        const persistCompleteStreams = options.captureDir !== undefined;
+        const stdoutCapture = createBoundedCommandCapture("stdout", captureLimit, getCaptureDir, persistCompleteStreams);
+        const stderrCapture = createBoundedCommandCapture("stderr", captureLimit, getCaptureDir, persistCompleteStreams);
         let killed = false;
         let settled = false;
         let timeoutId;
@@ -632,7 +700,20 @@ function execCommandTemplateOnce(command, args, options = {}) {
                 clearTimeout(killTimeoutId);
             if (options.signal)
                 options.signal.removeEventListener("abort", killProcess);
-            resolve({ stdout, stderr, code, killed });
+            const stdout = stdoutCapture.result();
+            const stderr = stderrCapture.result();
+            resolve({
+                stdout: stdout.content,
+                stderr: stderr.content,
+                code,
+                killed,
+                stdoutBytes: stdout.bytes,
+                stderrBytes: stderr.bytes,
+                ...(stdout.file ? { stdoutFile: stdout.file } : {}),
+                ...(stderr.file ? { stderrFile: stderr.file } : {}),
+                ...(stdout.truncated ? { stdoutTruncated: true } : {}),
+                ...(stderr.truncated ? { stderrTruncated: true } : {}),
+            });
         };
         if (options.signal) {
             if (options.signal.aborted)
@@ -643,16 +724,16 @@ function execCommandTemplateOnce(command, args, options = {}) {
         if (options.timeout !== undefined && options.timeout > 0)
             timeoutId = setTimeout(killProcess, options.timeout);
         proc.stdout?.on("data", (data) => {
-            stdout += data.toString();
+            stdoutCapture.append(data);
         });
         proc.stderr?.on("data", (data) => {
-            stderr += data.toString();
+            stderrCapture.append(data);
         });
         proc.stdin?.on("error", () => { });
         if (options.stdin !== undefined)
             proc.stdin?.end(options.stdin);
         proc.on("error", (error) => {
-            stderr += error instanceof Error ? error.message : String(error);
+            stderrCapture.append(error instanceof Error ? error.message : String(error));
             settle(1);
         });
         proc.on("close", (code) => {