@jameslovespancakes/pi-plus 1.0.11 → 1.0.13

package/src/domains/workflows/runtime/advisory-challenge.ts

@@ -0,0 +1,75 @@
+import { Type, type Static } from "typebox";
+import { collectAdvisoryStage, type AdvisoryStageCoverage } from "./advisory-evidence.ts";
+import { DEFAULT_ADVISORY_TOOLS, DEFAULT_ADVISORY_TOOL_HINTS, type AdvisoryVerified } from "./workflow-advisory-utils.ts";
+import type { WorkflowApi } from "./types.ts";
+
+const ChallengeSchema = Type.Object({
+  outcome: Type.Union([Type.Literal("counterexample"), Type.Literal("alternative-explanation"), Type.Literal("supports-original"), Type.Literal("no-counterexample")]),
+  evidence: Type.Array(Type.String()),
+  experiment: Type.String({ description: "Smallest distinguishing experiment, with observed result if actually run." }),
+});
+const AdjudicationSchema = Type.Object({
+  outcome: Type.Union([Type.Literal("upheld"), Type.Literal("refuted"), Type.Literal("unresolved")]),
+  evidence: Type.Array(Type.String()),
+  reason: Type.String(),
+});
+export type ChallengeRecord =
+  | { status: "complete"; challenge: Static<typeof ChallengeSchema>; adjudication: Static<typeof AdjudicationSchema> }
+  | { status: "failed"; challenge?: Static<typeof ChallengeSchema> };
+export interface AdvisoryChallengeOptions {
+  maxChallenges: number;
+  shouldChallenge?: (finding: AdvisoryVerified) => boolean;
+}
+
+/** Opt in with --challenge or --challenge=N (hard bound of 10). */
+export function parseChallengeArgs(args: string): { args: string; options: AdvisoryChallengeOptions } {
+  let maxChallenges = 0;
+  const remaining = args.replace(/(?:^|\s)--challenge(?:=([^\s]*))?(?=\s|$)/g, (_match, limit: string | undefined) => {
+    if (limit !== undefined && !/^\d+$/.test(limit)) {
+      throw new Error(`Invalid --challenge value "${limit}". Use --challenge or --challenge=N with a non-negative integer; zero disables challenges.`);
+    }
+    maxChallenges = Math.min(10, limit === undefined ? 3 : Number(limit));
+    return " ";
+  });
+  return { args: remaining.trim(), options: { maxChallenges } };
+}
+
+export function needsChallenge(finding: AdvisoryVerified): boolean {
+  return finding.verdict === "PLAUSIBLE" || finding.verdict === "NOT_SUBSTANTIATED" || finding.evidence.length === 0 ||
+    /\b(security|concurren\w*|race|persist\w*|cancel\w*|retr(?:y|ies)|data loss|corrupt\w*|high impact)\b/i.test(`${finding.category} ${finding.summary} ${finding.impact}`);
+}
+
+/** 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">,
+  findings: T[],
+  context: string,
+  options: AdvisoryChallengeOptions,
+  coverage: AdvisoryStageCoverage[],
+): 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 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.
+    replacements.set(finding.candidateId, { ...finding, verdict: "NOT_SUBSTANTIATED", challenge: { status: "failed" } });
+    const challenge = await api.agent(
+      `Assume this finding is a false positive. Try to DISPROVE it. Find the strongest concrete counterexample or alternative root cause. Inspect callers, invariants, tests and control flow. For a repair, seek an input, race or error path that still fails. State the smallest experiment distinguishing explanations. Do not edit files or claim tests you did not run. No counterexample found is not proof.\n\nExact review context:\n${context}\n\nCandidate and verifier evidence:\n${JSON.stringify(finding)}`,
+      { label: `challenge:${finding.candidateId}`, phase: "Challenge", profile: "medium", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, schema: ChallengeSchema },
+    );
+    replacements.set(finding.candidateId, { ...finding, verdict: "NOT_SUBSTANTIATED", challenge: { status: "failed", challenge } });
+    const adjudication = await api.agent(
+      `Adjudicate the original finding, independent verifier evidence and falsification attempt below. Preserve unresolved conflict; do not force consensus. A missing counterexample alone cannot upgrade a plausible claim. Cite concrete evidence and observed test results; never invent experiments.\nContext:\n${context}\nOriginal and verifier:\n${JSON.stringify(finding)}\nChallenger:\n${JSON.stringify(challenge)}`,
+      { label: `adjudicate:${finding.candidateId}`, phase: "Challenge", profile: "medium", tools: [], schema: AdjudicationSchema },
+    );
+    replacements.set(finding.candidateId, {
+      ...finding,
+      verdict: adjudication.outcome === "refuted" ? "REFUTED" : adjudication.outcome === "unresolved" ? "NOT_SUBSTANTIATED" : finding.verdict,
+      evidence: [...finding.evidence, ...challenge.evidence, ...(challenge.experiment ? [challenge.experiment] : []), ...adjudication.evidence, adjudication.reason],
+      challenge: { status: "complete", challenge, adjudication },
+    });
+    return finding.candidateId;
+  } })), coverage);
+  return findings.map((finding) => replacements.get(finding.candidateId) ?? finding);
+}

package/src/domains/workflows/runtime/advisory-evidence.ts

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { Type, type Static } from "typebox";
+import { AdvisorySeveritySchema, type IdentifiedAdvisoryCandidate, type AdvisoryCandidate, type AdvisoryReport } from "./advisory-schema.ts";
+import type { WorkflowApi } from "./types.ts";
+
+export interface AdvisoryStageCoverage {
+  stage: string;
+  expected: number;
+  completed: number;
+  failed: number;
+  failures: { branch: string; reason: string; candidate?: AdvisoryCandidate }[];
+}
+
+/** Settled results are required here: a missing branch is not a negative finding. */
+export async function collectAdvisoryStage<T>(
+  api: Pick<WorkflowApi, "parallel">,
+  stage: string,
+  branches: { id: string; candidate?: AdvisoryCandidate; run(): Promise<T> }[],
+  coverage: AdvisoryStageCoverage[],
+): Promise<T[]> {
+  const results = await api.parallel(branches.map((branch) => branch.run), { settled: true });
+  const failures = results.flatMap((result, index) => result.ok ? [] : [{ branch: branches[index]!.id, reason: result.error.message, ...(branches[index]!.candidate ? { candidate: branches[index]!.candidate } : {}) }]);
+  coverage.push({ stage, expected: branches.length, completed: results.length - failures.length, failed: failures.length, failures });
+  return results.flatMap((result) => result.ok ? [result.value] : []);
+}
+
+export function identifyCandidates(candidates: readonly AdvisoryCandidate[], lens: string): IdentifiedAdvisoryCandidate[] {
+  return candidates.map((candidate, index) => {
+    const candidateId = createHash("sha256").update(JSON.stringify([lens, index, candidate])).digest("hex").slice(0, 20);
+    // Identities are assigned by the workflow, never accepted from a finder.
+    return { ...candidate, candidateId, sourceCandidateIds: [candidateId] };
+  });
+}
+
+function normalizedSummary(summary: string): string {
+  return summary.toLowerCase().replace(/\s+/g, " ").trim().replace(/[.!?]+$/, "");
+}
+
+function candidateDedupKey(candidate: AdvisoryCandidate): string {
+  const location = candidate.locations[0];
+  return JSON.stringify([candidate.category, location?.file.replace(/^\.\//, "").replace(/^[ab]\//, ""),
+    location?.symbol ?? location?.line ?? null, normalizedSummary(candidate.summary)]);
+}
+
+/** Collapse only equivalent claims at the same anchor; keep every discovery ID and location. */
+export function dedupeCandidates<T extends IdentifiedAdvisoryCandidate>(candidates: readonly T[]): T[] {
+  const seen = new Map<string, T>();
+  for (const candidate of candidates) {
+    const key = candidateDedupKey(candidate);
+    const previous = seen.get(key);
+    if (!previous) seen.set(key, { ...candidate });
+    else {
+      previous.sourceCandidateIds = [...new Set([...previous.sourceCandidateIds, ...candidate.sourceCandidateIds])];
+      previous.locations = uniqueLocations([...previous.locations, ...candidate.locations]);
+      previous.impact = [...new Set([previous.impact, candidate.impact])].join("\n");
+      previous.discoveryEvidence = [...new Set([...(previous.discoveryEvidence ?? []), ...(candidate.discoveryEvidence ?? [])])];
+    }
+  }
+  return [...seen.values()];
+}
+
+export function uniqueLocations(locations: AdvisoryCandidate["locations"]): AdvisoryCandidate["locations"] {
+  return [...new Map(locations.map((location) => [JSON.stringify(location), location])).values()];
+}
+
+// Synthesis selects evidence records. It has no fields with which to replace their evidence.
+export const AdvisorySynthesisSchema = Type.Object({
+  summary: Type.String(),
+  findings: Type.Array(Type.Object({
+    sourceCandidateIds: Type.Array(Type.String(), { minItems: 1 }),
+    severity: AdvisorySeveritySchema,
+    recommendation: Type.String(),
+  })),
+  nextSteps: Type.Array(Type.String()),
+});
+export type AdvisorySynthesis = Static<typeof AdvisorySynthesisSchema>;
+export const SYNTHESIS_ID_INSTRUCTIONS = "Select or merge findings only by sourceCandidateIds shown below. Return severity and an advisory recommendation per selection. Never select an ID absent from these verified records. ";
+
+export function withAdvisoryCoverage<T extends AdvisoryReport>(report: T, coverage: AdvisoryStageCoverage[]) {
+  const incomplete = coverage.some((stage) => stage.failed > 0);
+  const gaps = coverage.flatMap((stage) => stage.failures.map((failure) => `${stage.stage}/${failure.branch}: ${failure.reason}`));
+  return {
+    ...report,
+    status: incomplete ? "incomplete" as const : "complete" as const,
+    summary: incomplete ? `Incomplete review: ${gaps.length} branch(es) failed. ${report.findings.length} finding(s) available; no clean conclusion is possible.` : report.summary,
+    nextSteps: incomplete ? ["Inspect failed branches and rerun missing work.", ...(report.findings.length > 0 ? report.nextSteps : [])] : report.nextSteps,
+    coverage,
+    gaps,
+  };
+}

package/src/domains/workflows/runtime/advisory-schema.ts

@@ -0,0 +1,83 @@
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+export const AdvisorySeveritySchema = Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")], {
+  description: "Impact level of an advisory finding.",
+});
+
+export const AdvisoryConfidenceSchema = Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")], {
+  description: "Confidence that the finding is actionable.",
+});
+
+export const AdvisoryVerifierVerdictSchema = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED"), Type.Literal("NOT_SUBSTANTIATED")], {
+  description: "Verifier judgment for a candidate finding.",
+});
+
+export const AdvisoryLocationSchema = Type.Object({
+  file: Type.String({ description: "Repository-relative file path." }),
+  line: Type.Optional(Type.Number({ description: "Relevant 1-based line number when known." })),
+  symbol: Type.Optional(Type.String({ description: "Relevant function, class, type, or other symbol when known." })),
+});
+
+export const AdvisoryCandidateSchema = Type.Object({
+  discoveryEvidence: Type.Optional(Type.Array(Type.String())),
+  reviewAnchor: Type.Optional(AdvisoryLocationSchema),
+  summary: Type.String({ description: "One-line candidate finding or hypothesis." }),
+  category: Type.String({ description: "Workflow-specific category such as bug, duplication, root-cause, or io." }),
+  locations: Type.Array(AdvisoryLocationSchema, { description: "Relevant code or configuration locations." }),
+  impact: Type.String({ description: "Concrete consequence if this candidate is real." }),
+  recommendation: Type.Optional(Type.String({ description: "Optional first-step recommendation before synthesis." })),
+});
+
+export const AdvisoryCandidatesSchema = Type.Object({
+  candidates: Type.Array(AdvisoryCandidateSchema, { description: "Candidate advisory findings or hypotheses." }),
+});
+
+export const AdvisoryVerdictSchema = Type.Object({
+  verdict: AdvisoryVerifierVerdictSchema,
+  evidence: Type.Array(Type.String({ description: "Quoted or cited evidence supporting the verdict." })),
+  confidence: Type.Optional(AdvisoryConfidenceSchema),
+});
+
+export const AdvisoryFindingSchema = Type.Object({
+  verdict: Type.Optional(AdvisoryVerifierVerdictSchema),
+  sourceCandidateIds: Type.Optional(Type.Array(Type.String())),
+  reviewAnchor: Type.Optional(AdvisoryLocationSchema),
+  summary: Type.String({ description: "One-line final finding." }),
+  category: Type.String({ description: "Workflow-specific category for grouping and display." }),
+  severity: AdvisorySeveritySchema,
+  confidence: AdvisoryConfidenceSchema,
+  locations: Type.Array(AdvisoryLocationSchema, { description: "Relevant code or configuration locations." }),
+  evidence: Type.Array(Type.String({ description: "Quoted or cited evidence." })),
+  impact: Type.String({ description: "Concrete user, runtime, maintenance, or performance impact." }),
+  recommendation: Type.String({ description: "Advisory next action; not an automatic edit." }),
+});
+
+export const AdvisoryReportSchema = Type.Object({
+  status: Type.Optional(Type.Union([Type.Literal("complete"), Type.Literal("incomplete")])),
+  gaps: Type.Optional(Type.Array(Type.String())),
+  coverage: Type.Optional(Type.Array(Type.Object({
+    stage: Type.String(), expected: Type.Number(), completed: Type.Number(), failed: Type.Number(),
+    failures: Type.Array(Type.Object({ branch: Type.String(), reason: Type.String(), candidate: Type.Optional(AdvisoryCandidateSchema) })),
+  }))),
+  summary: Type.String({ description: "Short overall advisory summary." }),
+  findings: Type.Array(AdvisoryFindingSchema, { description: "Verified and ranked advisory findings." }),
+  nextSteps: Type.Array(Type.String({ description: "Concrete follow-up commands, inspections, or decisions." })),
+});
+
+export const AdvisoryReportWithStatsSchema = Type.Object({
+  ...AdvisoryReportSchema.properties,
+  stats: Type.Optional(Type.Record(Type.String(), Type.Union([Type.String(), Type.Number()]))),
+});
+
+export type AdvisoryLocation = Static<typeof AdvisoryLocationSchema>;
+export type AdvisoryCandidate = Static<typeof AdvisoryCandidateSchema>;
+export type IdentifiedAdvisoryCandidate = AdvisoryCandidate & { candidateId: string; sourceCandidateIds: string[] };
+export type AdvisoryVerdict = Static<typeof AdvisoryVerdictSchema>;
+export type AdvisoryFinding = Static<typeof AdvisoryFindingSchema>;
+export type AdvisoryReport = Static<typeof AdvisoryReportSchema>;
+export type AdvisoryReportWithStats = Static<typeof AdvisoryReportWithStatsSchema>;
+
+export function isAdvisoryReport(value: unknown): value is AdvisoryReportWithStats {
+  return Value.Check(AdvisoryReportWithStatsSchema, value);
+}

package/src/domains/workflows/runtime/agent-attempt.ts

@@ -0,0 +1,177 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { assertWorkflowBudgetAvailable } from "./budget.ts";
+import { isWorkflowPauseError } from "./cancellation.ts";
+import type { WorkflowAgentReservation } from "./agent-limits.ts";
+import {
+  type AgentExecutionOptions,
+  type AgentRunTags,
+  type RunContext,
+} from "./agent-runner-types.ts";
+import {
+  captureReplayIdentity,
+  captureIsolatedRepositoryAfterSetup,
+  captureSharedRepositoryBeforeSetup,
+  isReplayEnabled,
+  lookupReplayResult,
+  validateReplayEvidence,
+  validateReplayIdentity,
+  type AgentAttemptResult,
+  type AgentReplayEvidence,
+  type AgentReplayPlan,
+} from "./agent-replay.ts";
+import { openAgentSession, promptAgentSession, type AgentSessionHandle } from "./agent-session.ts";
+import {
+  createAgentWorkspace,
+  type AgentWorkspace,
+} from "./agent-workspace.ts";
+import type { AgentResumeBaseContext, AgentResumeContext, RepositoryResumeContext } from "./resume-context.ts";
+import { captureRepositoryMutationGuard } from "./resume-context.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+/** Execute one agent attempt. Sessions close immediately; worktrees settle at the workflow boundary. */
+export async function executeAgentAttempt(input: {
+  readonly rc: RunContext;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly resumeBaseContext: AgentResumeBaseContext;
+  readonly model: Model<Api> | undefined;
+  readonly replay: AgentReplayPlan;
+  readonly label: string;
+  readonly rowId: number;
+  readonly tags: AgentRunTags;
+  readonly reserveLiveAgent: () => WorkflowAgentReservation;
+}): Promise<AgentAttemptResult> {
+  const { rc, prompt, opts, resumeBaseContext, model, replay, label, rowId, tags, reserveLiveAgent } = input;
+  let repositoryBefore: RepositoryResumeContext | undefined;
+  let evidence: AgentReplayEvidence | undefined;
+  if (isReplayEnabled(replay)) {
+    if (replay.kind === "isolated") {
+      const mutationGuard = await captureRepositoryMutationGuard(rc.cwd, rc.signal);
+      if (mutationGuard.kind === "unverifiable") {
+        repositoryBefore = mutationGuard;
+      } else {
+        evidence = { kind: "isolated", mutationGuard: mutationGuard.fingerprint };
+      }
+    } else {
+      repositoryBefore = await captureSharedRepositoryBeforeSetup(rc, prompt, opts, replay);
+      evidence = { kind: "shared" };
+    }
+  }
+  let workspace: AgentWorkspace | undefined;
+  let handle: AgentSessionHandle | undefined;
+  let admission: WorkflowAgentReservation | undefined;
+  let liveStarted = false;
+
+  try {
+    // Calls with no replay path cannot become cache hits. Reserve their live
+    // slot before creating a disposable worktree or model session so a limit
+    // error cannot leave behind a fresh, untouched workspace.
+    if (!isReplayEnabled(replay)) {
+      assertWorkflowBudgetAvailable(rc.budget);
+      admission = reserveLiveAgent();
+    }
+    workspace = await createAgentWorkspace(rc, opts, label);
+    if (replay.kind === "isolated" && evidence?.kind === "isolated") {
+      if (workspace.kind !== "isolated") throw new Error("Isolated replay created a shared workspace.");
+      repositoryBefore = await captureIsolatedRepositoryAfterSetup(rc, prompt, opts, workspace);
+    }
+    handle = await openAgentSession({ rc, prompt, opts, cwd: workspace.cwd, model, label, tags });
+
+    let identity: AgentResumeContext | undefined;
+    if (isReplayEnabled(replay) && repositoryBefore && evidence) {
+      const capture = await captureReplayIdentity({
+        rc,
+        base: resumeBaseContext,
+        repository: repositoryBefore,
+        selectedSkills: handle.selectedSkills,
+        session: handle.session,
+        sessionCwd: workspace.cwd,
+      });
+      if (capture.kind === "unverifiable") {
+        rc.progress.log(`${label}: resume disabled for this call (${capture.reason})`);
+      } else {
+        identity = capture.identity;
+        const cached = await lookupReplayResult({ rc, key: replay.key, identity, opts, workspace });
+        if (cached.hit) {
+          const contract = await validateReplayIdentity({
+            rc,
+            identity,
+            selectedSkills: handle.selectedSkills,
+            session: handle.session,
+            sessionCwd: workspace.cwd,
+            replay,
+            workspace,
+          });
+          const validation = contract.ok
+            ? await validateReplayEvidence(rc, evidence)
+            : contract;
+          if (validation.ok) {
+            return { kind: "cache-hit", result: cached.result, identity, evidence };
+          }
+          rc.progress.log(`${label}: cached result invalidated (${validation.reason})`);
+        } else if (cached.reason) {
+          rc.progress.log(`${label}: cached result invalidated (${cached.reason})`);
+        }
+      }
+    }
+
+    if (!admission) {
+      assertWorkflowBudgetAvailable(rc.budget);
+      admission = reserveLiveAgent();
+    }
+    admission.commit();
+    liveStarted = true;
+    if (workspace.kind === "isolated") rc.worktrees.markRecoverable(workspace.cwd);
+    const rawResult = await promptAgentSession({
+      rc,
+      handle,
+      prompt,
+      opts,
+      label,
+      rowId,
+      tags,
+    });
+    const result = await workspace.wrapResult(rawResult);
+    if (!identity) return { kind: "live-unrecordable", result };
+    if (!isReplayEnabled(replay) || !evidence) throw new Error("Replay identity produced without complete replay evidence.");
+
+    const contract = await validateReplayIdentity({
+      rc,
+      identity,
+      selectedSkills: handle.selectedSkills,
+      session: handle.session,
+      sessionCwd: workspace.cwd,
+      replay,
+      workspace,
+    });
+    const validation = contract.ok
+      ? await validateReplayEvidence(rc, evidence)
+      : contract;
+    if (validation.ok) {
+      return { kind: "live-recordable", result, identity, evidence };
+    }
+    rc.progress.log(`${label}: read-only resume contract was not recorded (${validation.reason})`);
+    return { kind: "live-unrecordable", result };
+  } catch (error) {
+    if (
+      workspace?.kind === "isolated"
+      && liveStarted
+      && !rc.signal?.aborted
+      && !isWorkflowPauseError(error)
+    ) {
+      rc.worktrees.preserve(workspace.cwd);
+      rc.progress.log(`${label}: retained failed worktree ${workspace.cwd}`);
+    }
+    throw error;
+  } finally {
+    admission?.release();
+    const session = handle?.session;
+    if (session) {
+      try {
+        rc.perf.timeSync("agent.dispose_ms", () => session.dispose(), tags);
+      } catch (error) {
+        rc.progress.log(`${label}: session cleanup failed (${unknownErrorMessage(error)})`);
+      }
+    }
+  }
+}

package/src/domains/workflows/runtime/agent-failure.ts

@@ -0,0 +1,14 @@
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+/** Retains every failed attempt when a later retry is blocked or also fails. */
+export function combinedAgentAttemptError(
+  label: string,
+  prior: readonly unknown[],
+  finalError: unknown,
+): AggregateError {
+  const earlier = prior.map(unknownErrorMessage).join("; ");
+  return new AggregateError(
+    [...prior, finalError],
+    `Workflow agent "${label}" could not complete. Earlier attempt: ${earlier}. Final failure: ${unknownErrorMessage(finalError)}`,
+  );
+}

package/src/domains/workflows/runtime/agent-limits.ts

@@ -0,0 +1,66 @@
+import { throwIfAborted } from "./cancellation.ts";
+
+export class WorkflowAgentLimitError extends Error {
+  override readonly name = "WorkflowAgentLimitError";
+  readonly code = "WORKFLOW_AGENT_LIMIT_EXCEEDED";
+  readonly maxAgents: number;
+
+  constructor(maxAgents: number) {
+    super(`Workflow live-agent limit of ${maxAgents} has been reached; no new model request was started.`);
+    this.maxAgents = maxAgents;
+  }
+}
+
+export class WorkflowAgentTimeoutError extends Error {
+  override readonly name = "WorkflowAgentTimeoutError";
+  readonly code = "WORKFLOW_AGENT_TIMEOUT";
+  readonly label: string;
+  readonly timeoutMs: number;
+
+  constructor(label: string, timeoutMs: number) {
+    super(`Workflow agent "${label}" exceeded its ${timeoutMs}ms duration limit.`);
+    this.label = label;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/** Shared run-level admission counter. Cache hits do not call admit(). */
+export interface WorkflowAgentReservation {
+  /** Permanently count this reservation as a live model attempt. */
+  commit(): void;
+  /** Return an uncommitted reservation after setup or replay succeeds/fails. */
+  release(): void;
+}
+
+export class WorkflowAgentLimiter {
+  readonly maxAgents: number | null;
+  private admitted = 0;
+
+  constructor(maxAgents: number | null) {
+    this.maxAgents = maxAgents;
+  }
+
+  reserve(signal: AbortSignal | undefined): WorkflowAgentReservation {
+    throwIfAborted(signal);
+    if (this.maxAgents !== null && this.admitted >= this.maxAgents) {
+      throw new WorkflowAgentLimitError(this.maxAgents);
+    }
+    this.admitted++;
+    let state: "pending" | "committed" | "released" = "pending";
+    return {
+      commit() {
+        if (state === "released") throw new Error("Cannot commit a released workflow agent reservation.");
+        state = "committed";
+      },
+      release: () => {
+        if (state !== "pending") return;
+        state = "released";
+        this.admitted--;
+      },
+    };
+  }
+
+  admit(signal: AbortSignal | undefined): void {
+    this.reserve(signal).commit();
+  }
+}