@llblab/pi-actors 0.39.0 → 0.40.0

package/lib/execution.ts

@@ -4,6 +4,8 @@
  * Owns command-template invocation execution and pi tool-result payload formatting
  */
 
+import { readFile } from "node:fs/promises";
+
 import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 import {
@@ -15,11 +17,18 @@ import * as Schema from "./schema.ts";
 
 export interface ToolExecOptions {
   actorRecipeContext?: CommandTemplates.CommandTemplateActorRecipeContext;
+  evidenceContext?: {
+    acceptOutput?: "review_evidence";
+    label?: string;
+    repeatIndex?: string;
+  };
   cwd?: string;
   signal?: AbortSignal;
   stdin?: string;
   timeout?: number;
   retry?: number;
+  captureDir?: string;
+  captureLimitBytes?: number;
 }
 
 export interface ToolExecResult {
@@ -27,6 +36,15 @@ export interface ToolExecResult {
   stderr: string;
   code: number;
   killed: boolean;
+  stdoutBytes?: number;
+  stderrBytes?: number;
+  stdoutFile?: string;
+  stderrFile?: string;
+  evidenceRef?: string;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
+  /** Complete internal stdout for downstream pipeline stdin; never returned to model-facing output. */
+  pipelineStdout?: string;
 }
 
 export interface BranchReport {
@@ -38,8 +56,14 @@ export interface BranchReport {
   status: "done" | "failed" | "timeout";
   stderr?: string;
   stderrBytes: number;
+  stderrCapturedBytes: number;
+  stderrFile?: string;
+  stderrTruncated?: boolean;
   stdout?: string;
   stdoutBytes: number;
+  stdoutCapturedBytes: number;
+  stdoutFile?: string;
+  stdoutTruncated?: boolean;
 }
 
 export interface SoftQuorumReport {
@@ -59,6 +83,14 @@ export interface RegisteredToolExecutionResult {
     command: string;
     fullOutputPath?: string;
     killed: boolean;
+    stderrBytes?: number;
+    stderrCapturedBytes?: number;
+    stderrFile?: string;
+    stderrTruncated?: boolean;
+    stdoutBytes?: number;
+    stdoutCapturedBytes?: number;
+    stdoutFile?: string;
+    stdoutTruncated?: boolean;
     nonCriticalFailures?: Array<{
       code: number;
       command: string;
@@ -163,6 +195,66 @@ function getBranchStatus(result: ToolExecResult): BranchReport["status"] {
   return result.killed ? "timeout" : "failed";
 }
 
+const REVIEW_RESULT_MARKER = "ACTOR_REVIEW_RESULT";
+
+export async function applyOutputAcceptancePolicy(
+  result: ToolExecResult,
+  output: string | undefined,
+): Promise<ToolExecResult> {
+  if (result.code !== 0 || output !== "review_evidence") return result;
+  let semanticStdout = result.pipelineStdout ?? result.stdout;
+  if (result.pipelineStdout === undefined && result.stdoutTruncated) {
+    if (!result.stdoutFile) semanticStdout = "";
+    else {
+      try {
+        semanticStdout = await readFile(result.stdoutFile, "utf8");
+      } catch {
+        semanticStdout = "";
+      }
+    }
+  }
+  const firstNonWhitespaceLine = semanticStdout
+    .split(/\r?\n/)
+    .find((line) => line.trim().length > 0);
+  if (firstNonWhitespaceLine?.trim() === REVIEW_RESULT_MARKER) return result;
+  return {
+    ...result,
+    code: 65,
+    stderr: [
+      result.stderr,
+      `review evidence rejected: missing ${REVIEW_RESULT_MARKER} marker`,
+    ].filter(Boolean).join("\n"),
+  };
+}
+
+async function resolvePipelineStdout(
+  result: ToolExecResult,
+): Promise<string | undefined> {
+  let stdout = result.pipelineStdout ?? result.stdout;
+  if (result.pipelineStdout === undefined && result.stdoutTruncated) {
+    if (!result.stdoutFile) return undefined;
+    try {
+      stdout = await readFile(result.stdoutFile, "utf8");
+    } catch {
+      return undefined;
+    }
+  }
+  return result.evidenceRef
+    ? `${stdout}\nACTOR_EVIDENCE_REF: ${result.evidenceRef}`
+    : stdout;
+}
+
+function rejectIncompletePipelineOutput(result: ToolExecResult): ToolExecResult {
+  return {
+    ...result,
+    code: 74,
+    stderr: [
+      result.stderr,
+      `incomplete pipeline stdin: complete stdout unavailable${result.stdoutFile ? `; capture path unreadable: ${result.stdoutFile}` : ""}`,
+    ].filter(Boolean).join("\n"),
+  };
+}
+
 function getBranchFailureReason(
   result: ToolExecResult,
 ): string | undefined {
@@ -187,14 +279,24 @@ function createBranchReport(
     label,
     status: getBranchStatus(result),
     ...(result.stderr ? { stderr: result.stderr.slice(-1000) } : {}),
-    stderrBytes: Buffer.byteLength(result.stderr),
+    stderrBytes: result.stderrBytes ?? Buffer.byteLength(result.stderr),
+    stderrCapturedBytes: Buffer.byteLength(result.stderr),
+    ...(result.stderrFile ? { stderrFile: result.stderrFile } : {}),
+    ...(result.stderrTruncated ? { stderrTruncated: true } : {}),
     ...(result.stdout ? { stdout: result.stdout.slice(-1000) } : {}),
-    stdoutBytes: Buffer.byteLength(result.stdout),
+    stdoutBytes: result.stdoutBytes ?? Buffer.byteLength(result.stdout),
+    stdoutCapturedBytes: Buffer.byteLength(result.stdout),
+    ...(result.stdoutFile ? { stdoutFile: result.stdoutFile } : {}),
+    ...(result.stdoutTruncated ? { stdoutTruncated: true } : {}),
   };
 }
 
 function isUsableBranch(branch: BranchReport): boolean {
-  return branch.status === "done" && branch.stdoutBytes > 0;
+  return (
+    branch.status === "done" &&
+    branch.stdoutBytes > 0 &&
+    branch.stdoutTruncated !== true
+  );
 }
 
 function createSoftQuorum(
@@ -399,6 +501,12 @@ function formatParallelStatusHeader(
   )} usable: ${countUsableBranches(branches)} expected: ${branches.length} minimum: ${minSuccessful} ---`;
 }
 
+function stdoutWithEvidenceReference(result: ToolExecResult): string {
+  return result.evidenceRef
+    ? `${result.stdout}\nACTOR_EVIDENCE_REF: ${result.evidenceRef}`
+    : result.stdout;
+}
+
 function joinParallelStdout(
   branches: BranchReport[],
   results: ToolExecResult[],
@@ -407,10 +515,15 @@ function joinParallelStdout(
   const body = results
     .map((result, index) => {
       const branch = branches[index];
-      const header = `--- branch: ${branch.label} status: ${branch.status} ---`;
-      if (branch.status === "done") return `${header}\n${result.stdout}`;
+      const evidence = result.evidenceRef
+        ? ` evidence_ref: ${result.evidenceRef}`
+        : "";
+      const header = `--- branch: ${branch.label} status: ${branch.status}${evidence} ---`;
+      if (branch.status === "done")
+        return `${header}\n${stdoutWithEvidenceReference(result)}`;
+      const stdout = result.stdout ? `\nrejected_stdout: ${result.stdout}` : "";
       const stderr = branch.stderr ? `\nstderr: ${branch.stderr}` : "";
-      return `${header}\nexit: ${branch.code}${stderr}`;
+      return `${header}\nexit: ${branch.code}${stdout}${stderr}`;
     })
     .join("\n");
   return [formatParallelStatusHeader(branches, minSuccessful), body]
@@ -643,8 +756,18 @@ async function executeTemplateConfig(
       cwd,
       { emptyMessage: "Tool template produced an empty command." },
     );
-    const result = await exec(invocation.command, invocation.args, {
+    const evidenceContext = {
+      ...(normalized.accept_output
+        ? { acceptOutput: normalized.accept_output }
+        : {}),
+      ...(normalized.label ? { label: normalized.label } : {}),
+      ...(typeof controlValues.index === "string"
+        ? { repeatIndex: controlValues.index }
+        : {}),
+    };
+    const rawResult = await exec(invocation.command, invocation.args, {
       ...(actorRecipeContext ? { actorRecipeContext } : {}),
+      ...(Object.keys(evidenceContext).length > 0 ? { evidenceContext } : {}),
       cwd,
       signal,
       stdin,
@@ -665,6 +788,10 @@ async function executeTemplateConfig(
         ? { retry: normalizeRetry(normalized.retry, controlValues) }
         : {}),
     });
+    const result = await applyOutputAcceptancePolicy(
+      rawResult,
+      normalized.accept_output,
+    );
     return {
       branches: [],
       commands: [formatInvocationDetail(invocation)],
@@ -700,6 +827,14 @@ async function executeTemplateConfig(
         actorRecipeContext,
       ),
     );
+    const branchPipelineStdouts = await Promise.all(
+      branchResults.map((item) => resolvePipelineStdout(item.result)),
+    );
+    for (const [index, item] of branchResults.entries()) {
+      if (item.result.stdoutTruncated && branchPipelineStdouts[index] === undefined) {
+        item.result = rejectIncompletePipelineOutput(item.result);
+      }
+    }
     const commands = branchResults.flatMap((item) => item.commands);
     const failures = branchResults.flatMap((item) => item.failures);
     const branches = branchResults.map((item, index) =>
@@ -748,9 +883,14 @@ async function executeTemplateConfig(
     const successful = branchResults.map((item) => {
       if (item.result.code === 0) return item.result;
       addResultFailure(failures, item);
-      return { ...item.result, code: 0, stdout: "" };
+      return { ...item.result, code: 0 };
     });
-    const result = {
+    const completeSuccessful = successful.map((item, index) => ({
+      ...item,
+      stdout: branchPipelineStdouts[index] ?? item.stdout,
+      evidenceRef: undefined,
+    }));
+    const result: ToolExecResult = {
       code: 0,
       killed: successful.some((item) => item.killed),
       stderr: successful
@@ -758,6 +898,18 @@ async function executeTemplateConfig(
         .filter(Boolean)
         .join("\n"),
       stdout: joinParallelStdout(branches, successful, minSuccessful),
+      pipelineStdout: joinParallelStdout(
+        branches,
+        completeSuccessful,
+        minSuccessful,
+      ),
+      stdoutBytes: successful.reduce(
+        (total, item) => total + (item.stdoutBytes ?? Buffer.byteLength(item.stdout)),
+        0,
+      ),
+      ...(successful.some((item) => item.stdoutTruncated)
+        ? { stdoutTruncated: true }
+        : {}),
     };
     if (quorumUnmet && nodeFailure === "root") {
       return {
@@ -821,7 +973,7 @@ async function executeTemplateConfig(
     [];
   let nextStdin = stdin;
   let result: ToolExecResult | undefined;
-  for (const step of steps) {
+  for (const [stepIndex, step] of steps.entries()) {
     const executed = await executeTemplateConfig(
       step,
       context,
@@ -836,7 +988,24 @@ async function executeTemplateConfig(
     branches.push(...executed.branches);
     commands.push(...executed.commands);
     failures.push(...executed.failures);
-    result = executed.result;
+    const pipelineStdout = await resolvePipelineStdout(executed.result);
+    const incompletePipelineInput =
+      stepIndex < steps.length - 1 && pipelineStdout === undefined;
+    result = incompletePipelineInput
+      ? rejectIncompletePipelineOutput(executed.result)
+      : executed.result;
+    executed.result = result;
+    if (incompletePipelineInput) {
+      addResultFailure(failures, executed);
+      return {
+        branches,
+        commands,
+        criticalFailure: true,
+        failureScope: "root",
+        failures,
+        result,
+      };
+    }
     if (result.code !== 0) {
       const failureScope = maxFailureScope(
         executed.failureScope,
@@ -870,7 +1039,7 @@ async function executeTemplateConfig(
       nextStdin = "";
       continue;
     }
-    nextStdin = result.stdout;
+    nextStdin = pipelineStdout;
   }
   return { branches, commands, failures, result: result! };
 }
@@ -895,6 +1064,19 @@ async function executeTemplateSteps(
   );
 }
 
+function getCaptureDetails(result: ToolExecResult): Record<string, unknown> {
+  return {
+    stdoutBytes: result.stdoutBytes ?? Buffer.byteLength(result.stdout),
+    stdoutCapturedBytes: Buffer.byteLength(result.stdout),
+    stderrBytes: result.stderrBytes ?? Buffer.byteLength(result.stderr),
+    stderrCapturedBytes: Buffer.byteLength(result.stderr),
+    ...(result.stdoutFile ? { stdoutFile: result.stdoutFile } : {}),
+    ...(result.stderrFile ? { stderrFile: result.stderrFile } : {}),
+    ...(result.stdoutTruncated ? { stdoutTruncated: true } : {}),
+    ...(result.stderrTruncated ? { stderrTruncated: true } : {}),
+  };
+}
+
 export async function executeRegisteredTool(
   cfg: RegisteredTool,
   params: Record<string, unknown>,
@@ -925,7 +1107,9 @@ export async function executeRegisteredTool(
         branches: executed.branches,
         code: result.code,
         command,
+        fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
         killed: result.killed,
+        ...getCaptureDetails(result),
         ...(executed.failures.length > 0
           ? { nonCriticalFailures: executed.failures }
           : {}),
@@ -950,8 +1134,9 @@ export async function executeRegisteredTool(
     details: {
       code: result.code,
       command,
-      fullOutputPath: formatted.fullOutputPath,
+      fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
       killed: result.killed,
+      ...getCaptureDetails(result),
       ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
       ...(executed.failures.length > 0
         ? { nonCriticalFailures: executed.failures }

package/lib/file-state.ts

@@ -4,9 +4,112 @@
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
 
-import { randomUUID } from "node:crypto";
-import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, parse, resolve } from "node:path";
+
+const FILE_MUTATION_LOCK_TIMEOUT_MS = 5000;
+const FILE_MUTATION_LOCK_STALE_MS = 30000;
+const FILE_MUTATION_LOCK_ROOT = join(tmpdir(), "pi-actors-file-locks");
+
+function canonicalMutationPath(path: string): string {
+  const absolute = resolve(path);
+  const suffix: string[] = [];
+  let existing = absolute;
+  while (!existsSync(existing)) {
+    const parent = dirname(existing);
+    if (parent === existing || existing === parse(existing).root) break;
+    suffix.unshift(basename(existing));
+    existing = parent;
+  }
+  const canonicalAncestor = existsSync(existing)
+    ? realpathSync.native(existing)
+    : existing;
+  const canonical = resolve(canonicalAncestor, ...suffix);
+  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
+function mutationLockPath(path: string): string {
+  const key = createHash("sha256")
+    .update(canonicalMutationPath(path))
+    .digest("hex");
+  return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
+}
+
+function lockOwnerIsDead(lockPath: string): boolean {
+  try {
+    const owner = JSON.parse(
+      readFileSync(join(lockPath, "owner.json"), "utf8"),
+    ) as { pid?: unknown };
+    const pid = Number(owner.pid);
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === "ESRCH";
+    }
+  } catch {
+    return false;
+  }
+}
+
+export function withFileMutationLock<T>(path: string, mutate: () => T): T {
+  mkdirSync(FILE_MUTATION_LOCK_ROOT, { recursive: true });
+  const lockPath = mutationLockPath(path);
+  const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
+  for (;;) {
+    try {
+      mkdirSync(lockPath);
+      try {
+        writeFileSync(
+          join(lockPath, "owner.json"),
+          `${JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() })}\n`,
+          "utf8",
+        );
+      } catch (error) {
+        rmSync(lockPath, { recursive: true, force: true });
+        throw error;
+      }
+      break;
+    } catch (error) {
+      try {
+        if (
+          Date.now() - statSync(lockPath).mtimeMs >
+            FILE_MUTATION_LOCK_STALE_MS &&
+          lockOwnerIsDead(lockPath)
+        ) {
+          rmSync(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
+          cause: error,
+        });
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+  try {
+    return mutate();
+  } finally {
+    rmSync(lockPath, { recursive: true, force: true });
+  }
+}
 
 export function writeJsonAtomic(path: string, value: unknown): void {
   mkdirSync(dirname(path), { recursive: true });

package/lib/observability.ts

@@ -81,7 +81,7 @@ export interface RunUiSnapshot {
 
 export interface RunUiNotificationSink {
   notify(message: string, level: "info" | "warning" | "error"): void;
-  sendFollowUp(message: {
+  sendSteering(message: {
     customType: string;
     content: string;
     display: true;
@@ -140,12 +140,18 @@ export function deliverRunTransitionNotifications(
     const text = formatRunTransitionMessage(transition);
     sink.notify(text, getRunTransitionNotificationType(transition));
     if (!shouldSendRunTransitionFollowUp(transition)) continue;
-    sink.sendFollowUp({
+    sink.sendSteering({
       customType: "pi-actors-run",
       content: text,
       display: true,
       details: transition,
     });
+    if (transition.stateDir) {
+      AsyncRuns.markRunTerminalNotificationHandled(
+        transition.stateDir,
+        transition.to,
+      );
+    }
   }
 }
 
@@ -158,7 +164,7 @@ export function deliverRunOutboxNotifications(
     const text = formatRunOutboxMessage(event);
     sink.notify(text, getRunOutboxNotificationType(event));
     if (!shouldSendRunOutboxFollowUp(event)) continue;
-    sink.sendFollowUp({
+    sink.sendSteering({
       customType: "pi-actors-run-message",
       content: text,
       display: true,
@@ -747,9 +753,9 @@ export function detectRunTransitions(
   for (const run of summary.runs) {
     const key = runObservationKey(run);
     const old = previous.get(key);
-    if (old && old !== run.status && TERMINAL.has(run.status)) {
+    if (!run.terminalHandled && TERMINAL.has(run.status)) {
       transitions.push({
-        from: old,
+        from: old ?? "running",
         run: run.run,
         ...(run.stateDir ? { stateDir: run.stateDir } : {}),
         ...(run.artifacts ? { artifacts: run.artifacts } : {}),

package/lib/pi.ts

@@ -13,7 +13,7 @@ export type { ExtensionAPI, ExtensionContext };
 
 export interface PiNotificationSink {
   notify(message: string, level: "info" | "warning" | "error"): void;
-  sendFollowUp(message: {
+  sendSteering(message: {
     customType: string;
     content: string;
     display: true;
@@ -31,9 +31,9 @@ export function createNotificationSink(
 ): PiNotificationSink {
   return {
     notify: (message, level) => ctx.ui.notify(message, level),
-    sendFollowUp: (message) =>
+    sendSteering: (message) =>
       pi.sendMessage(message, {
-        deliverAs: "followUp",
+        deliverAs: "steer",
         triggerTurn: true,
       }),
   };

package/lib/prompts.ts

@@ -22,14 +22,14 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, output.
+- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. 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 for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
@@ -42,8 +42,6 @@ export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
   async:
     "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
-  state_dir:
-    "Optional async run state directory for a co-located template recipe.",
   template:
     "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.",
   templateArray:

package/lib/recipes-context.ts

@@ -63,10 +63,10 @@ function isPiFileArgument(arg: string): boolean {
   return arg.startsWith("@") && arg.length > 1;
 }
 
-export function findPiPrintPromptIndex(args: string[]): number | undefined {
+function findPiPrintPromptIndexes(args: string[]): number[] {
   let printMode = false;
   let positionalOnly = false;
-  let promptIndex: number | undefined;
+  const promptIndexes: number[] = [];
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (!positionalOnly && arg === "--") {
@@ -82,9 +82,13 @@ export function findPiPrintPromptIndex(args: string[]): number | undefined {
       continue;
     }
     if (!printMode || isPiFileArgument(arg)) continue;
-    promptIndex = index;
+    promptIndexes.push(index);
   }
-  return promptIndex;
+  return promptIndexes;
+}
+
+export function findPiPrintPromptIndex(args: string[]): number | undefined {
+  return findPiPrintPromptIndexes(args).at(-1);
 }
 
 function matchesActorContext(
@@ -175,13 +179,17 @@ export function materializePiPrintPromptArg(
   promptFile: string | (() => string),
 ): MaterializedPiPrintPromptArgs {
   if (!isPiCommand(command)) return { args };
-  const promptIndex = findPiPrintPromptIndex(args);
-  if (promptIndex === undefined) return { args };
-  const prompt = args[promptIndex];
+  const promptIndexes = findPiPrintPromptIndexes(args);
+  if (promptIndexes.length === 0) return { args };
+  const prompt = promptIndexes.map((index) => args[index]).join(" ");
   const path = typeof promptFile === "function" ? promptFile() : promptFile;
   writeFileSync(path, prompt, "utf8");
-  const next = [...args];
-  next[promptIndex] = `@${path}`;
+  const promptIndexSet = new Set(promptIndexes);
+  const firstPromptIndex = promptIndexes[0];
+  const next = args.flatMap((arg, index) => {
+    if (index === firstPromptIndex) return [`@${path}`];
+    return promptIndexSet.has(index) ? [] : [arg];
+  });
   return {
     args: next,
     promptBytes: Buffer.byteLength(prompt),

package/lib/recipes-discovery.ts

@@ -14,6 +14,7 @@ import type { RegisteredTool } from "./config.ts";
 import * as ModelContext from "./model-context.ts";
 import type { TemplateRecipeConfig } from "./recipes-references.ts";
 import * as RecipesReferences from "./recipes-references.ts";
+import * as RecipesUsage from "./recipes-usage.ts";
 import * as Schema from "./schema.ts";
 
 export interface DiscoveredRecipe {
@@ -374,9 +375,13 @@ export function discoverRecipes(roots: string[]): RecipesDiscoveryResult {
 }
 
 function recipeUsage(
-  config: TemplateRecipeConfig | undefined,
+  entry: DiscoveredRecipe,
 ): Record<string, unknown> | undefined {
-  const usage = (config as { usage?: unknown } | undefined)?.usage;
+  const stored = entry.mutableUsage
+    ? RecipesUsage.readRecipeUsage(entry.path)
+    : undefined;
+  if (stored) return stored;
+  const usage = (entry.config as { usage?: unknown } | undefined)?.usage;
   return usage && typeof usage === "object" && !Array.isArray(usage)
     ? (usage as Record<string, unknown>)
     : undefined;
@@ -409,7 +414,7 @@ function cleanupRecommendation(
       actions: ["keep disabled", "delete", "archive"],
     };
   }
-  const usage = recipeUsage(entry.config);
+  const usage = recipeUsage(entry);
   const calls = Number(usage?.calls ?? 0);
   if (entry.mutableUsage && entry.tool && calls === 0) {
     return {
@@ -767,8 +772,8 @@ export function summarizeDiscovery(
             }
           : {}),
         ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
-        ...(recipeUsage(entry.config)
-          ? { usage: recipeUsage(entry.config) }
+        ...(recipeUsage(entry)
+          ? { usage: recipeUsage(entry) }
           : {}),
       }))
       .sort((a, b) => a.id.localeCompare(b.id)),