@llblab/pi-actors 0.39.0 → 0.40.1

package/docs/command-templates.md

@@ -57,6 +57,7 @@ Common object fields:
 - `defaults`: Placeholder default values by name.
 - `timeout`: Optional execution timeout in milliseconds. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely. Numeric control fields may be literal numbers or placeholders such as `"{timeout_ms}"`.
 - `delay`: Optional wait in milliseconds before starting this node. Default is no delay. It may be a literal number or placeholder.
+- `accept_output`: Optional fail-closed semantic output contract. `review_evidence` requires successful stdout to begin with `ACTOR_REVIEW_RESULT`; missing markers become code-65 failures while rejected stdout remains visible in branch diagnostics.
 - `output`: Optional result selector. Default is `"stdout"`; runtime values such as `"ogg"` are valid.
 - `retry`: Optional max attempts including the first. Default is `1`.
 - `failure`: Optional failure propagation scope: `continue`, `branch`, or `root`. Default is `continue`.
@@ -185,7 +186,8 @@ Composition rules:
 - Top-level `args` and `defaults` apply to every leaf unless the leaf defines private values
 - Leaf `args` replace inherited `args`; leaf `defaults` merge over inherited defaults; `timeout` and `output` are not inherited into leaves
 - Timeout is disabled by default; configure a positive `timeout` for bounded commands that should fail closed
-- Each sequence leaf receives the previous leaf's stdout on stdin by default, while the final leaf stdout remains the default composition result
+- Child stdout and stderr are captured as raw bytes with independent bounded in-memory tails; streams that exceed the capture limit spill completely to byte-exact diagnostic files and return byte counts, truncation flags, and spill paths. Text tails align their start to a UTF-8 code-point boundary so chunking or truncation does not corrupt valid multibyte output. Async runs persist complete streams even below the capture limit under command- and retry-specific run-state paths
+- Each sequence leaf receives the previous leaf's complete stdout on stdin by default, reading the byte-complete spill when the model-facing capture is truncated; the final leaf stdout remains the bounded default composition result. Parallel joins likewise use complete branch spills for downstream stdin while branch details and returned output stay bounded. If a declared spill is unavailable, the pipeline fails closed instead of forwarding a partial tail
 - Skipped nodes preserve current stdin/stdout flow and do not execute commands
 - Each parallel child receives the same stdin, and child stdout values are joined in stable array order before flowing to the next sequence leaf
 - Parallel branch joins include branch label and status, and tool details include branch metadata plus coverage summary
@@ -401,7 +403,7 @@ string           → leaf command
 string[]         → sequential composition
 { template }     → leaf command object
 { parallel, template } → sequence or parallel subtree
-{ parallel, concurrency, min_successful, when, args, defaults, delay, retry, failure, recover, output, template } → full node
+{ parallel, concurrency, min_successful, when, args, defaults, delay, retry, failure, recover, accept_output, output, template } → full node
 ```
 
 Start with a string. Add composition when needed. Add `parallel: true` when independent work can run concurrently. Add `when` when a node is conditional. Add delay when launch pacing matters. Add retry when flaky. Add `failure` when propagation scope matters. Add `recover` when a retried node needs cleanup before another attempt. Same contract, growing capability, no dead weight.

package/docs/recipe-library.md

@@ -30,6 +30,7 @@ Core subagent recipes:
 - `recipes/subagent-tools.json`: Start a subagent with an explicit tool allowlist.
 - `recipes/subagents-prompts.json`: Run prompt fanout with one imported subagent component.
 - `recipes/subagent-preflight.json`: Tiny model/thinking/tool-policy smoke check before expensive fanout; failures surface `ACTOR_PREFLIGHT_FAILED` with stage, selected policy, provider error class, prompt file, and override args.
+- Packaged reviewer, verifier, merger, judge, and normalizer stages use `accept_output: review_evidence` and require `ACTOR_REVIEW_RESULT` as the exact first non-whitespace output line. Marker prefixes, format acknowledgements, and input requests therefore remain rejected branch diagnostics rather than usable quorum evidence.
 - `recipes/subagent-review.json`: Evidence-grounded review lens.
 - `recipes/subagent-critic.json`: Assumption and failure-mode critique.
 - `recipes/subagent-plan.json`: Bounded plan slices and validation gates.

package/docs/template-recipes.md

@@ -19,7 +19,7 @@ async: true     = run through detached lifecycle
 
 A recipe wraps one command-template tree. The wrapped `template` keeps the normal command-template semantics: argv splitting, placeholders, defaults, typed args, sequence, `parallel: true`, `when`, delay, retry, failure propagation, recover cleanup, and output selection.
 
-Layer boundary: `imports`, `{ "name": "alias" }` imported-recipe nodes, `{alias.defaults.key}` references, fallback expressions, and recipe-local ternaries are recipe-loading features. They resolve before the command-template graph runs and do not extend the portable Command Template Standard. Typed imports are recipe definitions: they expose the imported recipe's command-template-shaped metadata (`template`, `args`, `defaults`, flags, and `values`), while async-run launch fields such as `async`, `state_dir`, and `retire_when` remain lifecycle configuration for starting a run, not part of the imported execution graph.
+Layer boundary: `imports`, `{ "name": "alias" }` imported-recipe nodes, `{alias.defaults.key}` references, fallback expressions, and recipe-local ternaries are recipe-loading features. They resolve before the command-template graph runs and do not extend the portable Command Template Standard. Typed imports are recipe definitions: they expose the imported recipe's command-template-shaped metadata (`template`, `args`, `defaults`, flags, and `values`), while async-run launch fields such as `async` and `retire_when` remain lifecycle configuration for starting a run, not part of the imported execution graph. Run state directories are runtime-owned and are not recipe or `register_tool` configuration; `{state_dir}` remains an injected run-local value for commands and artifact paths.
 
 Packaged recipes are the pi-actors recipe standard library: declarative actor config components that can be imported, launched, inspected, overridden, or composed by user recipes. Treat them as stable building blocks rather than user-local policy.
 
@@ -109,18 +109,16 @@ Higher-priority files shadow lower-priority files with the same basename. Within
 
 ## Usage Metadata
 
-User-owned recipes may accumulate extension-maintained usage metadata:
+User-owned recipe launches may accumulate extension-maintained usage metadata in `.usage/<recipe-filename>.json` sidecars:
 
 ```json
 {
-  "usage": {
-    "calls": 12,
-    "last_called": "2026-05-22T10:30:00.000Z"
-  }
+  "calls": 12,
+  "last_called": "2026-05-22T10:30:00.000Z"
 }
 ```
 
-The extension increments `usage.calls` and updates `usage.last_called` when it starts that concrete recipe, either through a recipe-backed tool call or a direct async recipe-file run. It also stores a content `usage.fingerprint`; if the authored recipe content changes, the next launch resets `usage.calls` before counting the new launch and records `usage.reset_at`. Agents should treat these fields as cleanup evidence, not as authored recipe contract. Packaged standard-library recipes are not mutated for usage metadata.
+The extension increments `calls` and updates `last_called` when it starts that concrete recipe, either through a recipe-backed tool call or a direct async recipe-file run. The sidecar also stores a content `fingerprint`; if authored recipe content changes, the next launch resets `calls` before counting the new launch and records `reset_at`. Keeping telemetry outside the recipe prevents usage writes from replacing concurrent operator edits; discovery merges sidecar usage into inspection. Agents should treat these fields as cleanup evidence, not as authored recipe contract. Packaged standard-library recipes do not receive usage metadata.
 
 There is intentionally no failure counter in the recipe contract. A failed launch can reflect caller misuse, missing runtime values, or an environmental problem rather than recipe uselessness. Cleanup decisions should be explicit operator work: keep as a tool, move out of the agent recipe root to retain recipe-only memory, merge, delete, or archive.
 

package/docs/tool-registry.md

@@ -16,9 +16,9 @@ The registry source is location-discovered recipes, not a live tool-only JSON fi
 - Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.
 - Same-id JSON shadows Markdown in the same priority layer.
 
-Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls`, `usage.last_called`, and a content `usage.fingerprint` on user-owned recipe files. If authored recipe content changes, the next launch resets `usage.calls` and records `usage.reset_at` before counting the launch, so usage evidence follows the current recipe meaning rather than an older file history. `inspect target=recipes view=summary verbose=true` includes usage metadata and operator-gated cleanup recommendations for invalid, shadowed, disabled, component-only, unused, or overriding recipes. Recommended actions stay explicit: keep as a tool/component, enable, merge, fix, delete, or archive. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.
+Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls`, `usage.last_called`, and a content `usage.fingerprint` in `.usage/<recipe-filename>.json` sidecars rather than rewriting authored recipe files. If authored recipe content changes, the next launch resets `usage.calls` and records `usage.reset_at` before counting the launch, so usage evidence follows the current recipe meaning without racing operator edits. Discovery and file-watcher refresh merge sidecar usage into inspect summaries. `inspect target=recipes view=summary verbose=true` includes usage metadata and operator-gated cleanup recommendations for invalid, shadowed, disabled, component-only, unused, or overriding recipes. Recommended actions stay explicit: keep as a tool/component, enable, merge, fix, delete, or archive. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.
 
-`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. 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.
+`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.
 
 Inspect the loaded pi-actors runtime and discovered registry with:
 
@@ -36,6 +36,8 @@ The recipe summary reports active, shadowed, invalid, disabled, and diagnostic e
 
 Routine shadowing is quiet. If a bare `spawn` recipe launch already fails because an invalid or `disabled: true` user recipe blocks a lower-priority fallback, the launch error adds compact tokens such as `reason=shadowed_invalid` or `reason=shadowed_disabled`, `active_path`, `blocked_fallback`, and `hint=inspect_recipes_doctor`.
 
+Pi cannot currently unregister an already published dynamic tool definition from the complete host registry. The extension therefore gates its own `message to=tool:<name>` and `inspect tool:<name>` lookup through the current recipe registry: deleting or externally removing a recipe immediately makes those routes inactive, and recipe updates replace the extension-local executable definition even if stale host metadata remains visible until reload.
+
 ## Registering Tools
 
 `register_tool` is the interactive API for listing, creating, updating, or deleting persistent tools. Call it without arguments to list registered tools.

package/index.ts

@@ -36,7 +36,11 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
         AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
     });
   };
-  const updateRunUi = (ctx: Pi.ExtensionContext, notify = false): void => {
+  const updateRunUi = (
+    ctx: Pi.ExtensionContext,
+    notify = false,
+    terminalOnly = false,
+  ): void => {
     const ownerId = getRunOwnerId(ctx);
     const snapshot = Observability.readRunUiSnapshot(runUi, ownerId);
     ctx.ui.setStatus(
@@ -78,10 +82,12 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
       notificationSink,
     );
     Observability.pruneRunUiObservationState(runUi, snapshot);
-    Observability.deliverRunOutboxNotifications(
-      snapshot.outboxEvents,
-      notificationSink,
-    );
+    if (!terminalOnly) {
+      Observability.deliverRunOutboxNotifications(
+        snapshot.outboxEvents,
+        notificationSink,
+      );
+    }
   };
   const closeRunWatchers = (): void => {
     runWatcher.close();
@@ -144,7 +150,7 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     activeRunContext = ctx;
     await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
     runtime.loadTools(ctx);
-    updateRunUi(ctx);
+    updateRunUi(ctx, true, true);
     closeRunWatchers();
     recipeReload.close();
     runWatcher.refresh();
@@ -204,7 +210,12 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({
       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/lib/async-runs.ts

@@ -10,11 +10,12 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
+  readdirSync,
   rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
-import { basename, dirname, extname, join, resolve } from "node:path";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import type {
@@ -50,11 +51,12 @@ import {
   parseRunOutboxEventLine,
   type RunOutboxEvent,
 } from "./runs-outbox.ts";
+import { claimRunStateDirectory } from "./runs-ownership.ts";
 import { archiveTerminalRun, pruneTerminalRun } from "./runs-retention.ts";
 import {
-  isAlive,
-  isWithinRunnerIdentityGrace,
-  pidMatchesRun,
+  captureRunProcessIdentity,
+  verifyRunProcessIdentity,
+  type RunProcessIdentity,
 } from "./runs-process.ts";
 import * as RunsStart from "./runs-start.ts";
 import * as RunsIndex from "./runs-index.ts";
@@ -105,6 +107,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;
@@ -146,6 +149,7 @@ export interface AsyncRunMeta {
   control?: AsyncRunControlEndpoint;
   mailbox?: RecipesReferences.TemplateRecipeMailbox;
   model_policy?: CurrentPolicyProvenance;
+  process_identity?: RunProcessIdentity;
   recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
   retire_when?: "children_terminal";
 }
@@ -196,6 +200,7 @@ function resolveRunTemplate(params: AsyncRunStartParams): {
     "when",
     "timeout",
     "delay",
+    "accept_output",
     "output",
     "retry",
     "failure",
@@ -445,6 +450,7 @@ export function startRun(
   mkdirSync(stateDir, { recursive: true });
   const releaseStartLock = acquireStateStartLock(stateDir);
   try {
+    claimRunStateDirectory(stateDir, run);
     assertNoActiveRunState(stateDir);
     prepareStateDirForStart(stateDir);
     const stdout = join(stateDir, "stdout.log");
@@ -512,6 +518,13 @@ export function startRun(
     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,
@@ -704,15 +717,23 @@ export async function sendRunMessage(
   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 as RunProcessIdentity | undefined,
+  );
+  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);
 }
 
@@ -734,6 +755,66 @@ function markTerminalProgress(
   );
 }
 
+function finalizeInterruptedReviewEvidence(
+  stateDir: string,
+  phase: "cancelled" | "killed",
+  signal: NodeJS.Signals,
+): void {
+  const evidencePath = join(stateDir, "review-evidence.json");
+  const manifest = readJson(evidencePath);
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) return;
+  const record = manifest as Record<string, unknown>;
+  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 as Record<string, unknown>;
+    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: string,
   signal: NodeJS.Signals,
@@ -742,12 +823,34 @@ function stopRun(
   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 };
+  }
+  const identity = verifyRunProcessIdentity(
+    pid,
+    status.process_identity as RunProcessIdentity | undefined,
+  );
+  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 (!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 };
+  }
+  if (!identity.valid) {
+    return {
+      stopped: false,
+      reason: identity.status.replaceAll("_", " "),
+      process_identity_status: identity.status,
+      status,
+    };
   }
   const signalResult = signalOwnedRunProcess(pid, signal);
   writeFileSync(
@@ -756,11 +859,27 @@ function stopRun(
     { flag: "a" },
   );
   markTerminalHandled(stateDir, { event, signal });
-  if (event === "run.kill") markTerminalProgress(stateDir, "killed");
-  if (event === "run.cancel") markTerminalProgress(stateDir, "cancelled");
+  if (event === "run.kill") {
+    finalizeInterruptedReviewEvidence(stateDir, "killed", signal);
+    markTerminalProgress(stateDir, "killed");
+  }
+  if (event === "run.cancel") {
+    finalizeInterruptedReviewEvidence(stateDir, "cancelled", signal);
+    markTerminalProgress(stateDir, "cancelled");
+  }
   return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
 }
 
+export function markRunTerminalNotificationHandled(
+  stateDir: string,
+  status: string,
+): void {
+  markTerminalHandled(stateDir, {
+    event: "run.notification",
+    status,
+  });
+}
+
 export function cancelRun(runOrDir: string): Record<string, unknown> {
   const result = stopRun(runOrDir, "SIGTERM", "run.cancel");
   return Object.hasOwn(result, "stopped")

package/lib/command-templates.ts

@@ -5,8 +5,9 @@
  */
 
 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";
 
 export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
@@ -30,6 +31,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;
@@ -60,6 +62,8 @@ export interface CommandTemplateExecOptions {
   stdin?: string;
   killGrace?: number;
   retry?: number;
+  captureDir?: string;
+  captureLimitBytes?: number;
 }
 
 export interface CommandTemplateExecResult {
@@ -67,6 +71,12 @@ export interface CommandTemplateExecResult {
   stderr: string;
   code: number;
   killed: boolean;
+  stdoutBytes?: number;
+  stderrBytes?: number;
+  stdoutFile?: string;
+  stderrFile?: string;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
 }
 
 export type CommandTemplateRiskLabel =
@@ -80,6 +90,8 @@ export type CommandTemplateRiskLabel =
   | "risk.platform_specific"
   | "risk.secret_touching";
 
+const DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES = 1024 * 1024;
+
 const COMMAND_TEMPLATE_RISK_LABEL_ORDER: CommandTemplateRiskLabel[] = [
   "risk.shell",
   "risk.eval",
@@ -584,9 +596,9 @@ export function expandCommandTemplateExecutable(
   cwd: string,
 ): string {
   if (command === "~") return homedir();
-  if (command.startsWith("~/")) return resolve(homedir(), command.slice(2));
+  if (command.startsWith("~/")) return resolvePath(homedir(), command.slice(2));
   if (command.includes("/") && !isAbsolute(command))
-    return resolve(cwd, command);
+    return resolvePath(cwd, command);
   return command;
 }
 
@@ -840,13 +852,83 @@ export async function execCommandTemplate(
     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;
 }
 
+interface BoundedCommandCapture {
+  append(value: Buffer | string): void;
+  result(): {
+    bytes: number;
+    content: string;
+    file?: string;
+    truncated: boolean;
+  };
+}
+
+function trimCaptureTail(value: Buffer, limit: number): Buffer {
+  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: "stdout" | "stderr",
+  limit: number,
+  getCaptureDir: () => string,
+  persistCompleteStream: boolean,
+): BoundedCommandCapture {
+  let bytes = 0;
+  let content: Buffer = 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: string,
   args: string[],
@@ -858,8 +940,32 @@ function execCommandTemplateOnce(
       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: string | undefined;
+    const getCaptureDir = (): string => {
+      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: NodeJS.Timeout | undefined;
@@ -879,7 +985,20 @@ function execCommandTemplateOnce(
       if (killTimeoutId) 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) killProcess();
@@ -888,16 +1007,16 @@ function execCommandTemplateOnce(
     }
     if (options.timeout !== undefined && options.timeout > 0)
       timeoutId = setTimeout(killProcess, options.timeout);
-    proc.stdout?.on("data", (data) => {
-      stdout += data.toString();
+    proc.stdout?.on("data", (data: Buffer) => {
+      stdoutCapture.append(data);
     });
-    proc.stderr?.on("data", (data) => {
-      stderr += data.toString();
+    proc.stderr?.on("data", (data: Buffer) => {
+      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) => {

package/lib/config.ts

@@ -47,7 +47,6 @@ export function serializeTools(
       entry.defaults = cfg.storedDefaults;
     if (cfg.recipe?.name) entry.name = cfg.recipe.name;
     if (cfg.recipe?.async !== undefined) entry.async = cfg.recipe.async;
-    if (cfg.recipe?.state_dir) entry.state_dir = cfg.recipe.state_dir;
     if (cfg.recipe?.values) entry.values = cfg.recipe.values;
     if (cfg.template) entry.template = cfg.template;
     result[name] = entry;
@@ -145,9 +144,6 @@ export function normalizeStoredTool(
     ? {
         name: recipeName,
         ...(typeof record.async === "boolean" ? { async: record.async } : {}),
-        ...(typeof record.state_dir === "string" && record.state_dir.trim()
-          ? { state_dir: record.state_dir.trim() }
-          : {}),
         template,
         ...(record.values &&
         typeof record.values === "object" &&