pi-workflow-engine 1.2.0 → 1.4.0

package/.pi/extensions/pi-workflow-engine/index.ts

@@ -616,7 +616,7 @@ function registerWorkflowTool(
       parallelSubmissionLimit: Type.Optional(Type.Number({ description: "Optional limit for eagerly submitted parallel thunks" })),
       maxAgents: Type.Optional(
         Type.Integer({
-          description: `Maximum live model calls started across this run; replay hits are excluded; clamped to ${WORKFLOW_MAX_AGENTS_MIN}-${WORKFLOW_MAX_AGENTS_MAX}`,
+          description: `Maximum live model calls started across this run; replay hits are excluded; clamped to ${WORKFLOW_MAX_AGENTS_MIN}-${WORKFLOW_MAX_AGENTS_MAX}. Leave unset for a registered workflow unless the user asks for a cap: it sizes its own stages`,
         }),
       ),
       agentTimeoutMs: Type.Optional(
@@ -646,13 +646,6 @@ function registerWorkflowTool(
           description: "Maximum delay accepted from a provider reset hint before automatic resume",
         }),
       ),
-      budget: Type.Optional(
-        Type.Integer({
-          minimum: WORKFLOW_BUDGET_MIN,
-          maximum: WORKFLOW_BUDGET_MAX,
-          description: "Optional output-token ceiling for the run; agent() throws once it is exceeded",
-        }),
-      ),
       perf: Type.Optional(Type.Boolean({ description: "Include workflow performance timing aggregates in the result details" })),
       resumeFromRunId: Type.Optional(Type.String({ minLength: 1, description: "Workflow run id to resume from by replaying matching completed agent results" })),
       resumeEditedWorkflow: Type.Optional(
@@ -681,7 +674,7 @@ function registerWorkflowTool(
         if (unavailable) return unavailable;
       }
       const turnBudget = dynamax.turnBudget(ctx);
-      const budget = resolveTurnBudget(params.budget, turnBudget, { min: WORKFLOW_BUDGET_MIN, max: WORKFLOW_BUDGET_MAX });
+      const budget = resolveTurnBudget(turnBudget, { min: WORKFLOW_BUDGET_MIN, max: WORKFLOW_BUDGET_MAX });
       if (budget.kind === "spent") {
         return workflowToolError(
           `The user's +${budget.total} output-token budget for this turn is spent by its earlier workflow runs. Do not start another workflow this turn unless the user raises the budget.`,

package/.pi/extensions/pi-workflow-engine/src/advisory-challenge.ts

@@ -41,7 +41,7 @@ export function needsChallenge(finding: AdvisoryVerified): boolean {
 
 /** A bounded recipe using existing agent/parallel calls, not a new runtime primitive. */
 export async function challengeFindings<T extends AdvisoryVerified>(
-  api: Pick<WorkflowApi, "agent" | "parallel">,
+  api: Pick<WorkflowApi, "agent" | "agents" | "log" | "parallel">,
   findings: T[],
   context: string,
   options: AdvisoryChallengeOptions,
@@ -49,7 +49,10 @@ export async function challengeFindings<T extends AdvisoryVerified>(
 ): Promise<T[]> {
   const limit = Number.isFinite(options.maxChallenges) ? Math.max(0, Math.min(10, Math.trunc(options.maxChallenges))) : 0;
   if (limit === 0) return findings;
-  const selected = findings.filter((finding) => finding.verdict !== "REFUTED" && (options.shouldChallenge ?? needsChallenge)(finding)).slice(0, limit);
+  const eligible = findings.filter((finding) => finding.verdict !== "REFUTED" && (options.shouldChallenge ?? needsChallenge)(finding)).slice(0, limit);
+  // A challenge takes two agents; keep one admission for the synthesis that follows.
+  const selected = eligible.slice(0, Math.max(0, Math.floor((api.agents.remaining() - 1) / 2)));
+  if (selected.length < eligible.length) api.log(`Challenging ${selected.length} of ${eligible.length} findings to fit the agent limit`);
   const replacements = new Map<string, T>();
   await collectAdvisoryStage(api, "Challenge", selected.map((finding) => ({ id: finding.candidateId, run: async () => {
     // Preserve the candidate as unresolved if either independent stage fails.

package/.pi/extensions/pi-workflow-engine/src/advisory-schema.ts

@@ -38,6 +38,14 @@ export const AdvisoryVerdictSchema = Type.Object({
   evidence: Type.Array(Type.String({ description: "Quoted or cited evidence supporting the verdict." })),
 });
 
+export const AdvisoryBatchVerdictSchema = Type.Object({
+  verdicts: Type.Array(Type.Object({
+    candidateId: Type.String({ description: "The candidateId of the record this verdict judges." }),
+    verdict: AdvisoryVerifierVerdictSchema,
+    evidence: Type.Array(Type.String({ description: "Quoted or cited evidence supporting the verdict." })),
+  }), { description: "One verdict per candidate record, each judged on its own." }),
+});
+
 export const AdvisoryFindingSchema = Type.Object({
   verdict: Type.Optional(AdvisoryVerifierVerdictSchema),
   sourceCandidateIds: Type.Optional(Type.Array(Type.String())),

package/.pi/extensions/pi-workflow-engine/src/agent-limits.ts

@@ -32,4 +32,8 @@ export class WorkflowAgentLimiter {
     if (this.admitted >= this.maxAgents) throw new WorkflowAgentLimitError(this.maxAgents);
     this.admitted++;
   }
+
+  remaining(): number {
+    return Math.max(0, this.maxAgents - this.admitted);
+  }
 }

package/.pi/extensions/pi-workflow-engine/src/background-workflows.ts

@@ -1,8 +1,6 @@
-import { join } from "node:path";
 import { SessionManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { WorkflowAbortError, WorkflowPauseError } from "./cancellation.ts";
 import { isRecord } from "./guards.ts";
-import { WORKFLOW_RUNS_DIR } from "./journal.ts";
 import type { WorkflowBackgroundOrigin } from "./types.ts";
 import {
   stopWorkflowRunRecord,
@@ -11,7 +9,7 @@ import {
   type WorkflowRunState,
 } from "./workflow-run-record.ts";
 import { updateWorkflowRunDelivery, type WorkflowRunDelivery } from "./workflow-run-background.ts";
-import { ProjectWorkflowRunStore, WORKFLOW_RUN_RECORD_SUFFIX, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
 import { truncateText } from "./text.ts";
 import { formatWorkflowUsageLine } from "./usage.ts";
 import { workflowResultSummary } from "./workflow-execution.ts";
@@ -375,10 +373,7 @@ function wokenDeliveryBody(record: WorkflowRunRecord, summary: string): string {
 
 /** The retained record, script and journal, relative to the workflow cwd like the synchronous result's lines. */
 function backgroundRunFileLines(record: WorkflowRunRecord): string[] {
-  return [
-    `Record: ${join(WORKFLOW_RUNS_DIR, `${record.runId}${WORKFLOW_RUN_RECORD_SUFFIX}`)}`,
-    ...formatWorkflowRunFileLines(record.runId, record.scriptFile !== undefined),
-  ];
+  return formatWorkflowRunFileLines(record.runId, record.scriptFile !== undefined);
 }
 
 function sessionHasBackgroundDelivery(ctx: ExtensionContext, runId: string): boolean {

package/.pi/extensions/pi-workflow-engine/src/dynamax.ts

@@ -147,20 +147,18 @@ export type DynamaxTurnBudgetResolution =
   | { readonly kind: "spent"; readonly total: number };
 
 /**
- * A run's budget. Without a turn pool it is the explicit one, if any. The user's pool caps every run in
- * its turn: the remainder, clamped to the run budget range, is the budget, and an explicit one can only
- * lower it. A pool with less than `min` left is spent.
+ * A tool run's budget. Only the user sets one: without a turn pool this adds none, and the pool caps
+ * every run in its turn at the remainder, clamped to the run budget range. A pool with less than `min`
+ * left is spent.
  */
 export function resolveTurnBudget(
-  explicit: number | undefined,
   pool: DynamaxTurnBudget | undefined,
   range: { readonly min: number; readonly max: number },
 ): DynamaxTurnBudgetResolution {
-  if (pool === undefined) return { kind: "budget", budget: explicit };
+  if (pool === undefined) return { kind: "budget", budget: undefined };
   const remaining = pool.remaining();
   if (remaining < range.min) return { kind: "spent", total: pool.total };
-  const cap = Math.min(range.max, Math.floor(remaining));
-  return { kind: "budget", budget: explicit === undefined ? cap : Math.min(explicit, cap) };
+  return { kind: "budget", budget: Math.min(range.max, Math.floor(remaining)) };
 }
 
 export function markDynamaxOneShot(state: DynamaxState): void {

package/.pi/extensions/pi-workflow-engine/src/engine.ts

@@ -474,6 +474,7 @@ export async function runWorkflowWithContext(
     input,
     cwd: rc.cwd,
     budget: rc.budget,
+    agents: { max: rc.agentLimiter.maxAgents, remaining: () => rc.agentLimiter.remaining() },
     signal: rc.signal,
   };
 

package/.pi/extensions/pi-workflow-engine/src/types.ts

@@ -280,10 +280,20 @@ export interface WorkflowApi {
    * `agent()` throws `WorkflowBudgetExceededError` once the ceiling is reached.
    */
   budget: WorkflowBudget;
+  /**
+   * The run's live-agent limit. `remaining()` is live: admissions left before `agent()` throws
+   * `WorkflowAgentLimitError` (journal replays take none). Reserve what later stages need before a fan-out.
+   */
+  agents: WorkflowAgentCapacity;
   /** Abort signal for the run, propagated from the host. */
   signal: AbortSignal | undefined;
 }
 
+export interface WorkflowAgentCapacity {
+  readonly max: number;
+  remaining(): number;
+}
+
 export type WorkflowRun = (api: WorkflowApi) => Promise<unknown>;
 
 /**

package/.pi/extensions/pi-workflow-engine/src/workflow-advisory-utils.ts

@@ -1,4 +1,4 @@
-import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, formatAdvisoryLocation, type AdvisoryCandidate, type AdvisoryFinding, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
+import { AdvisoryBatchVerdictSchema, AdvisoryCandidatesSchema, AdvisoryVerdictSchema, formatAdvisoryLocation, type AdvisoryCandidate, type AdvisoryFinding, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
 import { AdvisorySynthesisSchema, SYNTHESIS_ID_INSTRUCTIONS, withAdvisoryCoverage, collectAdvisoryStage, dedupeCandidates, identifyCandidates, mergeCandidateInto, repoPathCandidates, uniqueLocations, type AdvisoryStageCoverage, type AdvisorySynthesis } from "./advisory-evidence.ts";
 import { isFatalWorkflowError } from "./cancellation.ts";
 import { WorkflowClassifierUnavailableError } from "./classify.ts";
@@ -54,15 +54,29 @@ export function publishVerifiedKeptProgress(
 }
 
 export interface LensVerificationPipelineOptions {
-  api: Pick<WorkflowApi, "agent" | "classify" | "parallel" | "phase" | "progress" | "log">;
+  api: Pick<WorkflowApi, "agent" | "agents" | "classify" | "parallel" | "phase" | "progress" | "log">;
   lenses: readonly AdvisoryLens[];
   perLens: number;
   finderPhase?: "Find" | "Hypothesize";
+  finderProfile?: AgentOptions["profile"];
   finderPrompt(lens: AdvisoryLens): string;
-  verifierPrompt(candidate: IdentifiedAdvisoryCandidate): string;
+  /** One verifier's prompt. It gets several candidates only when the agent limit leaves fewer verifiers than candidates. */
+  verifierPrompt(candidates: readonly IdentifiedAdvisoryCandidate[]): string;
   boundCandidate?(candidate: IdentifiedAdvisoryCandidate, lens: AdvisoryLens): IdentifiedAdvisoryCandidate | undefined;
 }
 
+/** The candidate section of a verifier prompt: one record, or a batch judged in one pass. */
+export function verifierCandidates(
+  candidates: readonly IdentifiedAdvisoryCandidate[],
+  heading: { one: string; many: string },
+  fields: (candidate: IdentifiedAdvisoryCandidate) => string,
+): string {
+  if (candidates.length === 1) return `## ${heading.one}\n${fields(candidates[0]!)}`;
+  return `## ${heading.many} (${candidates.length}: the run's agent limit leaves one verifier for several)\n` +
+    candidates.map((candidate) => `### candidateId ${candidate.candidateId}\n${fields(candidate)}`).join("\n\n") +
+    "\n\nJudge each on its own evidence and return one verdict per candidateId.";
+}
+
 export interface AdvisoryBackfillDefaults {
   impact: string;
   recommendation?: string;
@@ -72,7 +86,7 @@ export interface AdvisoryBackfillDefaults {
 export async function runLensVerificationPipeline(
   options: LensVerificationPipelineOptions,
 ): Promise<LensVerificationPipelineResult> {
-  const { api, lenses, perLens, finderPhase = "Find", finderPrompt, verifierPrompt, boundCandidate } = options;
+  const { api, lenses, perLens, finderPhase = "Find", finderProfile = "small", finderPrompt, verifierPrompt, boundCandidate } = options;
   const coverage: AdvisoryStageCoverage[] = [];
   let rawCandidates = 0;
   let overCap = 0;
@@ -81,7 +95,7 @@ export async function runLensVerificationPipeline(
     const result = await api.agent(finderPrompt(lens), {
       phase: finderPhase, label: `${finderPhase.toLowerCase()}:${lens.label}`,
       tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
-      profile: "small", schema: AdvisoryCandidatesSchema,
+      profile: finderProfile, schema: AdvisoryCandidatesSchema,
     });
     rawCandidates += result.candidates.length;
     api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: result.candidates.length });
@@ -111,21 +125,55 @@ export async function runLensVerificationPipeline(
   }
   const dropped = overCap + duplicateOrOutOfScope;
   api.phase("Verify");
-  const verified = await collectAdvisoryStage(api, "Verify", candidates.map((candidate) => ({
-    id: candidate.candidateId, candidate, run: async (): Promise<AdvisoryVerified> => {
-      const location = primaryLocation(candidate);
-      const judged = await api.agent(`${verifierPrompt(candidate)}\nCandidate record: ${JSON.stringify(candidate)}`, {
-        phase: "Verify", label: `verify:${location.file.split("/").pop() ?? location.file}`,
-        tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
-        profile: "small", schema: AdvisoryVerdictSchema,
-      });
-      recordVerdictProgress(api.progress, candidate, judged);
-      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence };
-    },
-  })), coverage);
+  // Keep one admission for the synthesis that follows. A host-set agent limit can leave fewer verifiers than
+  // candidates; then each verifier judges a batch, so no candidate goes unverified and synthesis still runs.
+  const batches = verificationBatches(candidates, Math.max(1, api.agents.remaining() - 1));
+  if (batches.length < candidates.length) api.log(`Verifying ${candidates.length} candidates in ${batches.length} batch(es) to fit the agent limit`);
+  // Each candidate keeps its own coverage branch, so a failed batch still lists every candidate it held.
+  const verified = await collectAdvisoryStage(api, "Verify", batches.flatMap((batch) => {
+    let judged: Promise<AdvisoryVerified[]> | undefined;
+    return batch.map((candidate, index) => ({
+      id: candidate.candidateId, candidate,
+      run: async () => (await (judged ??= verifyBatch(api, batch, verifierPrompt)))[index]!,
+    }));
+  }), coverage);
   return { verified, rawCandidates, dropped, coverage };
 }
 
+/** Split candidates into at most `count` batches, keeping candidates in one file together where it fits. */
+function verificationBatches(candidates: readonly IdentifiedAdvisoryCandidate[], count: number): IdentifiedAdvisoryCandidate[][] {
+  if (candidates.length <= count) return candidates.map((candidate) => [candidate]);
+  const byFile = [...candidates].sort((a, b) => primaryLocation(a).file.localeCompare(primaryLocation(b).file));
+  const size = Math.ceil(byFile.length / count);
+  return Array.from({ length: Math.ceil(byFile.length / size) }, (_, index) => byFile.slice(index * size, (index + 1) * size));
+}
+
+async function verifyBatch(
+  api: Pick<WorkflowApi, "agent" | "progress">,
+  batch: readonly IdentifiedAdvisoryCandidate[],
+  verifierPrompt: LensVerificationPipelineOptions["verifierPrompt"],
+): Promise<AdvisoryVerified[]> {
+  const location = primaryLocation(batch[0]!);
+  const options = {
+    phase: "Verify", label: `verify:${location.file.split("/").pop() ?? location.file}${batch.length > 1 ? ` +${batch.length - 1}` : ""}`,
+    tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
+  } as const;
+  if (batch.length === 1) {
+    const candidate = batch[0]!;
+    const judged = await api.agent(`${verifierPrompt(batch)}\nCandidate record: ${JSON.stringify(candidate)}`, { ...options, profile: "small", schema: AdvisoryVerdictSchema });
+    recordVerdictProgress(api.progress, candidate, judged);
+    return [{ ...candidate, verdict: judged.verdict, evidence: judged.evidence }];
+  }
+  // One agent does several verifiers' work, so it gets the medium route.
+  const judged = await api.agent(`${verifierPrompt(batch)}\nCandidate records: ${JSON.stringify(batch)}`, { ...options, profile: "medium", schema: AdvisoryBatchVerdictSchema });
+  const verdicts = new Map(judged.verdicts.map((verdict) => [verdict.candidateId, verdict]));
+  return batch.map((candidate) => {
+    const verdict = verdicts.get(candidate.candidateId) ?? { verdict: "NOT_SUBSTANTIATED" as const, evidence: ["The batch verifier returned no verdict for this candidate."] };
+    recordVerdictProgress(api.progress, candidate, verdict);
+    return { ...candidate, verdict: verdict.verdict, evidence: verdict.evidence };
+  });
+}
+
 /** TypeSafe Jev routes in preference order. Jev is the classifier the duplicate merge was measured with. */
 export const DUPLICATE_CANDIDATE_CLASSIFIERS = [
   "typesafe/jev-latest",

package/.pi/extensions/pi-workflow-engine/src/workflow-result-context.ts

@@ -1,8 +1,17 @@
 import { join } from "node:path";
-import { formatAdvisoryLocation, isAdvisoryReport, type AdvisoryFinding, type AdvisoryReport } from "./advisory-schema.ts";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+import {
+  AdvisoryVerifierVerdictSchema,
+  formatAdvisoryLocation,
+  isAdvisoryReport,
+  type AdvisoryFinding,
+  type AdvisoryReport,
+} from "./advisory-schema.ts";
 import { isRecord } from "./guards.ts";
 import { WORKFLOW_RUNS_DIR } from "./journal.ts";
 import { workflowRunScriptFile } from "./workflow-run-record.ts";
+import { WORKFLOW_RUN_RECORD_SUFFIX } from "./workflow-run-store.ts";
 import { toReviewIssues } from "./review/review-issues.ts";
 import { formatPerfSummary } from "./perf.ts";
 import { prettyJson } from "./text.ts";
@@ -35,21 +44,31 @@ export function formatWorkflowRunLine(run: { readonly runId: string; readonly re
 }
 
 /**
- * Where the host model can read what the run did, relative to the workflow cwd: the persisted script it
- * can edit and rerun with `scriptPath`, and the replay journal of completed agent results.
+ * Where the host model can read what the run did, relative to the workflow cwd: the record holding the full
+ * result, the persisted script it can edit and rerun with `scriptPath`, and the replay journal of completed
+ * agent results.
  */
 export function formatWorkflowRunFileLines(runId: string, scriptPersisted: boolean): string[] {
   return [
+    `Record: ${join(WORKFLOW_RUNS_DIR, `${runId}${WORKFLOW_RUN_RECORD_SUFFIX}`)}`,
     ...(scriptPersisted ? [`Script: ${join(WORKFLOW_RUNS_DIR, workflowRunScriptFile(runId))}`] : []),
     `Journal: ${join(WORKFLOW_RUNS_DIR, `${runId}.jsonl`)}`,
     "If the result is empty or unexpected, read the journal before diagnosing.",
   ];
 }
 
+/** A verified candidate as lens reviews retain it beside their report, reduced to the fields the host listing reads. */
+const VerifiedCandidateSchema = Type.Object({
+  sourceCandidateIds: Type.Array(Type.String()),
+  summary: Type.String(),
+  verdict: AdvisoryVerifierVerdictSchema,
+});
+type VerifiedCandidate = Static<typeof VerifiedCandidateSchema>;
+
 /** A workflow result as the host model reads it: advisory reports as findings, other values as bounded JSON. */
 export function formatResultForContext(result: unknown): string {
   if (typeof result === "string") return result;
-  if (isAdvisoryReport(result)) return formatAdvisoryReportForContext(result);
+  if (isAdvisoryReport(result)) return formatAdvisoryReportForContext(result, unreportedCandidates(result));
   const summary = workflowResultSummary(result);
   if (summary !== undefined && isRecord(result) && Object.keys(result).length === 1) return summary;
   const json = formatResultJson(result);
@@ -57,7 +76,20 @@ export function formatResultForContext(result: unknown): string {
   return summary === undefined ? json : `${summary}\n\n${json}`;
 }
 
-function formatAdvisoryReportForContext(report: AdvisoryReport): string {
+/**
+ * Verified candidates that no finding draws on: ones synthesis left out under the reporting bar, and refuted
+ * ones. Listing them lets the host resolve the candidate IDs a synthesis summary cites when it explains an
+ * exclusion, without reading the run record.
+ */
+function unreportedCandidates(report: AdvisoryReport & { readonly verification?: unknown }): VerifiedCandidate[] {
+  const { verification } = report;
+  if (!Array.isArray(verification)) return [];
+  const reported = new Set(report.findings.flatMap((finding) => finding.sourceCandidateIds ?? []));
+  return verification.filter((entry): entry is VerifiedCandidate =>
+    Value.Check(VerifiedCandidateSchema, entry) && !entry.sourceCandidateIds.some((id) => reported.has(id)));
+}
+
+function formatAdvisoryReportForContext(report: AdvisoryReport, unreported: readonly VerifiedCandidate[]): string {
   const lines = [report.summary];
   const issues = toReviewIssues(report);
   if (issues.length > 0) {
@@ -75,6 +107,10 @@ function formatAdvisoryReportForContext(report: AdvisoryReport): string {
       );
     }
   }
+  if (unreported.length > 0) {
+    lines.push("", "Verified but not reported (verdict, candidate IDs):",
+      ...unreported.map((candidate) => `- ${candidate.verdict} ${candidate.sourceCandidateIds.join(", ")}: ${candidate.summary}`));
+  }
   if (report.gaps && report.gaps.length > 0) {
     lines.push("", "Coverage gaps:", ...report.gaps.map((gap) => `- ${gap}`));
   }

package/.pi/extensions/pi-workflow-engine/src/workflow-settings.ts

@@ -65,7 +65,7 @@ export function setWorkflowSize(configPath: string, size: WorkflowSizeGuideline)
 /** The catalog line for a size, or undefined when the guideline is off. */
 export function workflowSizeGuidelineLine(size: WorkflowSizeGuideline): string | undefined {
   if (size === "off") return undefined;
-  return `Workflow size guideline: ${size} — keep each workflow under ${SIZE_AGENT_LIMITS[size]} agents unless the user asks for more; the user changes this with /workflow:size.`;
+  return `Workflow size guideline: ${size} — keep each workflow script you author under ${SIZE_AGENT_LIMITS[size]} agents unless the user asks for more; registered workflows size their own stages, so run them without maxAgents unless the user sets a cap. The user changes this with /workflow:size.`;
 }
 
 type WorkflowSizeCommand =
@@ -76,7 +76,7 @@ type WorkflowSizeCommand =
 const USAGE = "Usage: /workflow:size [small|medium|large|off] [--user|--project]";
 const SIZE_COMPLETIONS = WORKFLOW_SIZE_GUIDELINES.map((value) => ({
   value,
-  description: value === "off" ? "No size guideline in the prompt" : `Keep each workflow under ${SIZE_AGENT_LIMITS[value]} agents`,
+  description: value === "off" ? "No size guideline in the prompt" : `Keep each authored workflow under ${SIZE_AGENT_LIMITS[value]} agents`,
 }));
 const SCOPE_COMPLETIONS = [
   { value: "--user", description: "Write the user-level workflow settings" },
@@ -110,7 +110,7 @@ export function formatWorkflowSize(resolved: ResolvedWorkflowSize): string {
   const source = resolved.source === "default" ? "default" : `${resolved.source} config ${resolved.configPath}`;
   const rule = resolved.size === "off"
     ? "no size guideline is added to the prompt"
-    : `keep each workflow under ${SIZE_AGENT_LIMITS[resolved.size]} agents unless the user asks for more`;
+    : `keep each authored workflow script under ${SIZE_AGENT_LIMITS[resolved.size]} agents unless the user asks for more; registered workflows are not capped by it`;
   return [
     `Workflow size guideline: ${resolved.size} (${source}) — ${rule}.`,
     `The maxAgents run limit (default ${DEFAULT_WORKFLOW_MAX_AGENTS}) stays the hard cap on live agents per run.`,

package/.pi/extensions/pi-workflow-engine/workflows/code-review.ts

@@ -1,5 +1,5 @@
 import { challengeFindings, parseChallengeArgs } from "../src/advisory-challenge.ts";
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
 import {
   type AdvisoryVerified,
   type AdvisoryLens,
@@ -9,6 +9,7 @@ import {
   formatEvidence,
   formatLocation,
   runLensVerificationPipeline,
+  verifierCandidates,
   EMPTY_LENS_REVIEW_STATS,
   verdictConfidence,
   DEFAULT_ADVISORY_TOOL_HINTS,
@@ -35,6 +36,16 @@ const ScopeSchema = Type.Object({
   conventions: Type.Optional(Type.String({ description: "Relevant AGENTS.md / project conventions" })),
 });
 
+// With review instructions, scope splits them by stage: finders get only where to look, because a reporting bar in a
+// finder prompt makes finders filter their own candidates before any verifier sees them; the bar goes to synthesis.
+const InstructedScopeSchema = Type.Object({
+  ...ScopeSchema.properties,
+  conventions: Type.Optional(Type.String({ description: "Repository conventions from AGENTS.md and project docs only. Do not restate the user's review instructions, filtering rules or already-reported findings here." })),
+  focus: Type.String({ description: "Where the user wants reviewers to look: areas, files, risks and lenses named in the instructions. Exclude any filtering, evidence, reporting or deduplication rules; write (none) if the instructions name no focus." }),
+  reportingBar: Type.String({ description: "The user's filtering, evidence, severity and reporting rules restated so a reader without file access can apply them, listing every already-reported issue to exclude (read any files the instructions reference). Write (none) if the instructions set no bar." }),
+});
+type Scope = Static<typeof ScopeSchema> & Partial<Pick<Static<typeof InstructedScopeSchema>, "focus" | "reportingBar">>;
+
 // The review lenses — this is the part you customise to your codebase's real failure modes.
 const ANGLES: AdvisoryLens[] = [
   { label: "logic-bugs", category: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
@@ -54,7 +65,7 @@ export function buildCodeReviewScopeBlock(input: {
   readonly summary: string;
   readonly conventions?: string;
   readonly diffText: string;
-  readonly target: string;
+  readonly instructions?: { readonly heading: string; readonly text: string };
 }): string {
   const diffBlock = input.diffText
     ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
@@ -67,7 +78,7 @@ export function buildCodeReviewScopeBlock(input: {
     `## Diff command\n${input.diffCommand}\n\n## Changed files\n${input.files.map((file) => `- ${file}`).join("\n")}\n\n` +
     `## Summary\n${input.summary}\n\n## Conventions\n${input.conventions ?? "(none noted)"}\n` +
     diffBlock +
-    (input.target ? `\n## User instructions (verbatim)\n${input.target}\n` : "")
+    (input.instructions?.text ? `\n## ${input.instructions.heading}\n${input.instructions.text}\n` : "")
   );
 }
 
@@ -82,7 +93,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
 
   // ─── Phase 0: Scope ───
   phase("Scope");
-  const scope = await agent(
+  const scopePrompt =
     "Establish the scope of a code review.\n" +
       (target
         ? `Target / instructions (verbatim): "${target}". If it names a PR number, branch, ref range, or files, build the matching diff command (use 'gh pr diff <number>' for a PR). Otherwise use the default selection below.\n`
@@ -98,9 +109,14 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       "4. Run the chosen command to confirm the diff is non-empty.\n\n" +
       "Then: list the changed files, summarize the change in one paragraph (mention the PR if one was found), " +
       "and read any relevant AGENTS.md or project docs noting conventions a reviewer should know.\n" +
-      "Return diffCommand exactly as a reviewer should run it. Structured output only.",
-    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
-  );
+      "Return diffCommand exactly as a reviewer should run it. Structured output only.";
+  const scopeOptions = { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium" } as const;
+  const scope: Scope = target
+    ? await agent(
+        `${scopePrompt}\nKeep the user's instructions out of conventions. Return focus (where to look) and reportingBar (the self-contained filtering and reporting bar, with every already-reported issue spelled out) as separate fields.`,
+        { ...scopeOptions, schema: InstructedScopeSchema },
+      )
+    : await agent(scopePrompt, { ...scopeOptions, schema: ScopeSchema });
 
   progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
   const diffTarget = parseAllowedDiffCommand(scope.diffCommand);
@@ -148,19 +164,27 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       : {}),
   };
 
-  const scopeBlock = `Reviewed snapshot identity: ${JSON.stringify(reviewContext.snapshot ?? "unavailable")}\n` + buildCodeReviewScopeBlock({
-    diffCommand,
-    files: scope.files,
-    summary: scope.summary,
-    conventions: scope.conventions,
-    diffText,
-    target,
-  });
+  const blockFor = (instructions?: { heading: string; text: string }) =>
+    `Reviewed snapshot identity: ${JSON.stringify(reviewContext.snapshot ?? "unavailable")}\n` + buildCodeReviewScopeBlock({
+      diffCommand,
+      files: scope.files,
+      summary: scope.summary,
+      conventions: scope.conventions,
+      diffText,
+      ...(instructions ? { instructions } : {}),
+    });
+  const scopeBlock = blockFor({ heading: "User instructions (verbatim)", text: target });
+  const focus = stated(scope.focus);
+  const reportingBar = stated(scope.reportingBar);
+  const finderBlock = blockFor(focus ? { heading: "Review focus (from the user's instructions)", text: focus } : undefined);
+  if (focus) log(`review focus: ${focus}`);
 
   const pipelineResult = await runLensVerificationPipeline({
     api,
     lenses: ANGLES,
     perLens: PER_ANGLE,
+    // Finders on `small` (thinking low by default) returned nothing on real PRs; they are the stage that must dig.
+    finderProfile: "medium",
     boundCandidate: (candidate, lens) => {
       const reviewAnchor = candidate.reviewAnchor
         ? diffAnchor(changed, candidate.reviewAnchor)
@@ -168,18 +192,18 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       return reviewAnchor ? { ...candidate, category: lens.category, reviewAnchor } : undefined;
     },
     finderPrompt: (lens) =>
-      `## Code-review finder — ${lens.label}\n\n${scopeBlock}\n` +
+      `## Code-review finder — ${lens.label}\n\n${finderBlock}\n` +
       `Review the change through ONLY this lens:\n${lens.text}\n` +
       "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
       "Set reviewAnchor to the changed line causing the issue; locations and discoveryEvidence may include unchanged callers and other files. " +
       `Surface up to ${PER_ANGLE} candidates. Use category exactly "${lens.category}". Each candidate must include a one-line summary, ` +
       "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
       "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
-    verifierPrompt: (candidate) =>
-      `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
-      `Location: ${formatLocation(candidate)}\n` +
-      `Category: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n\n` +
-      "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / NOT_SUBSTANTIATED / REFUTED) " +
+    verifierPrompt: (candidates) =>
+      `## Code-review verifier\n\n${scopeBlock}\n` +
+      verifierCandidates(candidates, { one: "Candidate", many: "Candidates" }, (candidate) =>
+        `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}`) + "\n\n" +
+      "Run the diff command, read the relevant file(s), and return exactly one verdict per candidate (CONFIRMED / PLAUSIBLE / NOT_SUBSTANTIATED / REFUTED) " +
       "with evidence quoting the line(s). Use NOT_SUBSTANTIATED when evidence is insufficient; use REFUTED only for concrete disproof. Structured output only.",
   });
   const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, pipelineResult.coverage);
@@ -194,11 +218,23 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
     synthesisPrompt: (block, ranked) =>
       `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
       "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
-      "Return summary, ID selections with severity (low/medium/high) and advisory recommendation, and nextSteps. Evidence and confidence are reconstructed from verified records. Structured output only.",
+      "Return summary, ID selections with severity (low/medium/high) and advisory recommendation, and nextSteps. Evidence and confidence are reconstructed from verified records. Structured output only." +
+      // Only a stated bar filters: a focus alone must not drop verified findings outside it.
+      (reportingBar
+        ? `\n\n## Reporting bar (the user's rules with referenced context resolved)\n${reportingBar}` +
+          `\n\n## User instructions (verbatim)\n${target}\n\n` +
+          "Apply the reporting bar when choosing which IDs to report: leave out findings it excludes, and say in the summary what you left out and why."
+        : ""),
   });
   return { ...report, reviewContext };
 }
 
+/** A scope field's text, or undefined when the scope agent left it blank or wrote (none). */
+function stated(value: string | undefined): string | undefined {
+  const text = value?.trim();
+  return text && text !== "(none)" ? text : undefined;
+}
+
 function rank(finding: AdvisoryVerified): number {
   return (finding.category === "cleanup" ? 2 : 0) + (finding.verdict !== "CONFIRMED" ? 1 : 0);
 }

package/.pi/extensions/pi-workflow-engine/workflows/diagnose.ts

@@ -8,6 +8,7 @@ import {
   formatLocation,
   formatRankedFinding,
   runLensVerificationPipeline,
+  verifierCandidates,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
@@ -77,10 +78,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       `Consider ONLY this hypothesis lens:\n${lens.text}\n\n` +
       `Surface up to ${PER_LENS} root-cause hypotheses. Use category exactly "${lens.category}". ` +
       "Each hypothesis must include a one-line summary, locations, impact explaining how it produces the symptom, and an optional recommendation for the next validation step. Structured output only.",
-    verifierPrompt: (candidate) =>
-      `## Diagnose verifier\n\n${scopeBlock}\n## Hypothesis\n` +
-      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
-      `Recommended validation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+    verifierPrompt: (candidates) =>
+      `## Diagnose verifier\n\n${scopeBlock}\n` +
+      verifierCandidates(candidates, { one: "Hypothesis", many: "Hypotheses" }, (candidate) =>
+        `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+        `Recommended validation: ${candidate.recommendation ?? "(none supplied)"}`) + "\n\n" +
       "Read relevant files and, when useful, run only safe read-only diagnostic commands from the scoped command list or commands explicitly requested by the user. " +
       "Do not run mutation, install, commit, network, or destructive commands. Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence. " +
       "Use NOT_SUBSTANTIATED when evidence is missing; REFUTED requires disproof. Structured output only.",

package/.pi/extensions/pi-workflow-engine/workflows/perf-review.ts

@@ -9,6 +9,7 @@ import {
   EMPTY_LENS_REVIEW_STATS,
   formatLocation,
   runLensVerificationPipeline,
+  verifierCandidates,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
@@ -85,10 +86,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
       "Each candidate must include a one-line summary, locations, impact stating the suspected performance consequence and workload where it matters, " +
       "and an optional recommendation. Prefer measurement recommendations when evidence is weak. Structured output only.",
-    verifierPrompt: (candidate) =>
-      `## Perf-review verifier\n\n${scopeBlock}\n## Candidate\n` +
-      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
-      `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+    verifierPrompt: (candidates) =>
+      `## Perf-review verifier\n\n${scopeBlock}\n` +
+      verifierCandidates(candidates, { one: "Candidate", many: "Candidates" }, (candidate) =>
+        `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+        `Recommendation: ${candidate.recommendation ?? "(none supplied)"}`) + "\n\n" +
       "Read relevant files and package/scripts. Run only safe read-only measurement or inspection commands when useful. " +
       "Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence from code, scripts, config, or measurement output. " +
       "Default toward PLAUSIBLE or REFUTED when no measurement exists; do not overstate a bottleneck. Structured output only.",

package/.pi/extensions/pi-workflow-engine/workflows/refactor-scout.ts

@@ -10,6 +10,7 @@ import {
   formatLocation,
   formatRankedFinding,
   runLensVerificationPipeline,
+  verifierCandidates,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
@@ -83,10 +84,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
       "Each candidate must include a one-line summary, locations, impact on maintainability or future correctness, and an optional safe first recommendation. " +
       "Only include opportunities where a small, reviewable first step is plausible. Structured output only.",
-    verifierPrompt: (candidate) =>
-      `## Refactor-scout verifier\n\n${scopeBlock}\n## Candidate\n` +
-      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
-      `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+    verifierPrompt: (candidates) =>
+      `## Refactor-scout verifier\n\n${scopeBlock}\n` +
+      verifierCandidates(candidates, { one: "Candidate", many: "Candidates" }, (candidate) =>
+        `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+        `Recommendation: ${candidate.recommendation ?? "(none supplied)"}`) + "\n\n" +
       "Read the relevant files and return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED. " +
       "Default toward REFUTED if the opportunity is generic, too broad, not evidenced by code, or lacks a safe first step. " +
       "Evidence must quote or cite code. Structured output only.",

package/USAGE.md

@@ -207,13 +207,13 @@ The catalog ends with one line telling the host agent how large to make each wor
 
 ```text
 /workflow:size                    # show the current guideline and where it comes from
-/workflow:size small              # keep each workflow under 5 agents
+/workflow:size small              # keep each authored workflow under 5 agents
 /workflow:size medium             # under 10 agents (the default)
 /workflow:size large --project    # under 25 agents, for this project only
 /workflow:size off                # leave the line out
 ```
 
-The line reads, for example, `Workflow size guideline: medium — keep each workflow under 10 agents unless the user asks for more; the user changes this with /workflow:size.` The setting is stored like the model profiles: `~/.pi/agent/workflow-settings.json` for the user, overridden by `<project>/.pi/workflow-settings.json`; setting a size writes the user file unless `--project` is given. A minimal file is `{ "size": "small" }`. Changing it rebuilds the current session's catalog once.
+The line reads, for example, `Workflow size guideline: medium — keep each workflow script you author under 10 agents unless the user asks for more; registered workflows size their own stages, so run them without maxAgents unless the user sets a cap. The user changes this with /workflow:size.` The setting is stored like the model profiles: `~/.pi/agent/workflow-settings.json` for the user, overridden by `<project>/.pi/workflow-settings.json`; setting a size writes the user file unless `--project` is given. A minimal file is `{ "size": "small" }`. Changing it rebuilds the current session's catalog once.
 
 The guideline only shapes what the host agent writes. The `maxAgents` run limit (default `64`, see [Runtime knobs](#runtime-knobs)) stays the separate hard cap: once a run has started that many live agents, further `agent()` calls fail with `WorkflowAgentLimitError`, whatever the guideline says.
 
@@ -287,7 +287,7 @@ Persistence is intentionally bounded and private by default. Raw workflow args,
 
 An inline run (a tool `script` or `scriptPath`) also saves its script to `.pi/.workflow-runs/<run-id>.script.js`, a separate file the record only references, because the record never holds prompts. The script holds nothing new: pi's session transcript already contains it as the tool call's arguments. A pruned record takes its script with it. Whenever the engine creates `.pi/.workflow-runs/`, it adds a `.gitignore` containing `*` so run files stay out of the project's git history; an existing `.gitignore` there is never replaced.
 
-The result handed to the host agent names the run's files after the run ID: `Script:` for an inline run, and `Journal:` with a reminder to read the journal before diagnosing an empty or unexpected result. A failed inline run lists the same lines after its error, a background start names the script too, and a background delivery names the record, script, and journal (see [Background workflows](#background-workflows)). To iterate, edit the script and rerun it with `scriptPath` (see [Author an inline workflow](#author-an-inline-workflow)).
+The result handed to the host agent names the run's files after the run ID: `Record:` (which holds the full result when the text is truncated), `Script:` for an inline run, and `Journal:` with a reminder to read the journal before diagnosing an empty or unexpected result. A failed run lists the same lines after its error, a background start names the script too, and a background delivery names the same files (see [Background workflows](#background-workflows)). A review result also lists the verified candidates that no reported finding draws on, with their verdicts and candidate IDs, so the host can resolve the IDs a synthesis summary cites when it explains what it left out. To iterate, edit the script and rerun it with `scriptPath` (see [Author an inline workflow](#author-an-inline-workflow)).
 
 ### Background workflows
 
@@ -606,7 +606,7 @@ Only tune these when a workflow is too slow, too expensive, or too noisy:
 | `--max-agents=N` / `PI_WORKFLOW_MAX_AGENTS=N` | Cap live model calls across the complete run, including sub-workflows. Default `64`; values are clamped to `1`–`10000`. Replay hits do not consume the cap. The `workflow` tool field is `maxAgents`. This is independent of the `/workflow:size` prompt guideline. |
 | `--agent-timeout-ms=N` / `PI_WORKFLOW_AGENT_TIMEOUT_MS=N` | Abort one live agent after this duration. Default `1800000` (30 minutes); values are clamped to `1000`–`86400000`. The session is aborted and its isolated worktree is cleaned up. The `workflow` tool field is `agentTimeoutMs`. |
 | `--agent-retries=N` / `PI_WORKFLOW_AGENT_RETRIES=N` | Restart the whole agent after a transient provider or transport failure that pi's in-session turn retry could not recover. Default `0`; values are clamped to `0`–`10`. Backoff starts at one second, doubles, and caps at 30 seconds. The `workflow` tool field is `agentRetries`. |
-| `--budget=N` / `PI_WORKFLOW_BUDGET=N` | Set an output-token ceiling across recorded subagent attempts, including failed provider attempts. `agent()` throws `WorkflowBudgetExceededError` before starting another model request once the ceiling is reached; agents already running may overshoot because the engine does not reserve per-agent estimates. |
+| `--budget=N` / `PI_WORKFLOW_BUDGET=N` | Set an output-token ceiling across recorded subagent attempts, including failed provider attempts. `agent()` throws `WorkflowBudgetExceededError` before starting another model request once the ceiling is reached; agents already running may overshoot because the engine does not reserve per-agent estimates. The `workflow` tool has no budget field; see [Turn budget directive](#turn-budget-directive). |
 | `--perf` / `PI_WORKFLOW_PERF=1` | Include internal timing aggregates. Usage/cost totals are reported separately from perf. |
 | `PI_WORKFLOW_LANE_ITEM_LIMIT=N` | Cap retained progress lane items. |
 
@@ -636,16 +636,18 @@ do not count, and values under 1,000 tokens are ignored so a `+1` in ordinary
 prose never caps a run. The first such token in a typed prompt wins; prompts
 that extensions send are not read.
 
-While the pool is active, a `workflow` tool call without its own `budget` runs
-with the pool's remainder as its budget (clamped to the tool's budget range),
-and each synchronous run's output tokens are subtracted once it finishes,
-failed or not. When less than one token remains, the tool refuses the call and
-tells the agent the turn's budget is spent. An explicit `budget` on the call
-can only lower that ceiling, is refused the same way once the pool is spent, and
-its spend is subtracted too. The pool clears when the run that
+While the pool is active, every `workflow` tool call runs with the pool's
+remainder as its budget (clamped to the run budget range), and each
+synchronous run's output tokens are subtracted once it finishes, failed or not.
+When less than one token remains, the tool refuses the call and tells the agent
+the turn's budget is spent. The pool clears when the run that
 received the prompt settles, so it still covers the run after pi retries a
 provider error or compacts an overflowing context within that run.
 
+The `workflow` tool has no `budget` field, so the host agent cannot choose a
+ceiling: one it guesses can run out before a run's final stage. Without a pool,
+a tool run takes `PI_WORKFLOW_BUDGET` if it is set and is otherwise unbudgeted.
+
 Background runs receive the current remainder as their budget but do not draw
 the pool down, because their usage lands after the turn. Parallel `workflow`
 calls in one assistant message each see the same remainder before any of them

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [

package/skills/workflow-authoring/SKILL.md

@@ -46,6 +46,7 @@ export default async function run(api) {
 | `workflow(nameOrRef, args?)` | Runs another workflow as a sub-step and returns its result: a registered workflow by name, or an inline-format script file via `{ scriptPath }`, relative to the workflow cwd. `args` is a string or any JSON value, which the child reads as `input` and `args`. One level of nesting only. Rejects on an unknown name, an unreadable `scriptPath`, or a script that does not compile. |
 | `phase(title)` / `log(message)` / `progress(event)` | Drive the live progress tree, logs, counters, and lanes. |
 | `budget` | `{ total, spent(), remaining() }` in output tokens; `total` is `null` when the run has no budget. |
+| `agents` | `{ max, remaining() }`: the run's live-agent limit and the admissions left before `agent()` throws. It is a live reading, not a reservation: agents running alongside, and retries, take admissions too, and journal replays take none, so a resumed run reads more. |
 | `input` | The arguments verbatim: the `/workflow` command's string, or the JSON value the tool call or `workflow()` passed; `""` when none was given. |
 | `args`, `cwd`, `signal` | The arguments as text (a string as is, any other JSON value as JSON text, `""` when none), the host working directory, and the run's abort signal. |
 
@@ -104,6 +105,7 @@ Host-written scripts in practice reached for `Promise.all` and never for `pipeli
 ## Quality patterns
 
 - **Adversarial verify.** Give each finding to a separate verifier told to refute it, and keep only what survives. Thin evidence means not substantiated, not confirmed.
+- **Filter after discovery, not during it.** When the user sets a reporting bar (evidence or experiment requirements, severity or MVP floors, net-LOC rules, dedupe against posted comments), give finders only where to look and ask for every candidate with a nameable impact; apply the bar in verify and synthesis. Finders told that returning nothing is preferred filter out their own candidates before any verifier sees them, and the run reports nothing.
 - **Perspective-diverse verify.** For findings that matter, use two or three verifiers with different methods (read the callers, reproduce it, check the tests) and require agreement.
 - **Judge panel.** Generate several independent answers or designs, then have a judge (or several) pick or merge them against stated criteria.
 - **Loop until dry.** Repeat discovery rounds, deduping each round against everything seen so far, not only the last round. Stop when a round adds nothing new, or at a round cap or budget guard.
@@ -116,7 +118,7 @@ Host-written scripts in practice reached for `Promise.all` and never for `pipeli
 
 - **Scout inline first, then orchestrate.** Use your own tools to find the work list (the files, failing tests, or findings) before writing the script, then fan out over that concrete list. Embed the list in the script or pass it as a JSON `args` value and read it from `api.input`.
 - **One single-phase workflow per turn.** For multi-phase work (understand, design, implement, review), run one workflow per phase and read each result before choosing the next, rather than one script that guesses every phase in advance.
-- **Scale to the request and the size guideline.** A focused question needs a few agents, a broad sweep more. The `<workflows>` section's size guideline line (set by the user with `/workflow:size`) bounds each workflow unless the user asks for more. The run's `maxAgents` limit (default 64) is a separate hard backstop, not a target.
+- **Scale to the request and the size guideline.** A focused question needs a few agents, a broad sweep more. The `<workflows>` section's size guideline line (set by the user with `/workflow:size`) bounds each workflow unless the user asks for more. The run's `maxAgents` limit (default 64) is a separate hard backstop, not a target. Under a tight limit, size a fan-out from `api.agents.remaining()` and keep the agents later stages need, such as a final synthesize, rather than letting the fan-out spend them; the built-in review workflows batch verification this way.
 - **Use `classify()` as a cheap gate** between stages: dedupe, triage, or route items without a full agent. It rejects when no classifier model is configured, so call it inside `api.parallel` or a `try`/`catch` and fall back to an agent or to keeping the item. Results are not journaled, so a resumed run classifies again.
 
 ```js
@@ -129,7 +131,7 @@ const keep = answers.real?.type === "bool" ? answers.real.probability > 0.5 : tr
 
 ## Budget
 
-`api.budget.total` is the output-token ceiling (`null` when unset); `spent()` and `remaining()` are live. When the user's prompt carries a `+500k`-style directive, every run that turn is capped at the remaining pool (its own `budget` can only lower that), and synchronous runs draw the pool down; once it is spent the tool refuses further runs that turn. Once the ceiling is reached `agent()` rejects with `WorkflowBudgetExceededError` (a `null` slot inside `parallel`); agents already running can overshoot. Scale fleets from `total`, and guard every loop with it so an unbudgeted run still terminates:
+`api.budget.total` is the output-token ceiling (`null` when unset); `spent()` and `remaining()` are live. Only the user sets a budget: the `workflow` tool takes none. When the user's prompt carries a `+500k`-style directive, every run that turn is capped at the remaining pool, and synchronous runs draw the pool down; once it is spent the tool refuses further runs that turn. Once the ceiling is reached `agent()` rejects with `WorkflowBudgetExceededError` (a `null` slot inside `parallel`); agents already running can overshoot. Scale fleets from `total`, and guard every loop with it so an unbudgeted run still terminates:
 
 ```js
 const width = api.budget.total ? Math.max(2, Math.min(8, Math.floor(api.budget.total / 40_000))) : 4;