@llblab/pi-actors 0.38.1 → 0.40.0

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" &&