harnery 0.10.0 → 0.12.0

package/src/core/workflow/engine.ts

@@ -21,16 +21,36 @@ import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { snapshotRepo } from "../context/index.ts";
+import type { ExternalMutationRequest, PolicyDecision, PolicyRequest } from "../policy/index.ts";
+import {
+  evaluatePolicy,
+  normalizePolicy,
+  PolicyDeniedError,
+  policyDigest,
+  summarizePolicyRequest,
+} from "../policy/index.ts";
 import { type BillingProbe, probeBilling } from "./billing.ts";
+import {
+  buildWorkflowProof,
+  createEvidenceRecord,
+  digestResult,
+  normalizeWorkflowMeta,
+  writeWorkflowProof,
+} from "./proof.ts";
 import type {
   AgentOpts,
   EngineOpts,
   HarnessName,
   RunReport,
   SpawnResult,
+  WorkflowAgentProof,
   WorkflowContext,
+  WorkflowEvidenceRecord,
   WorkflowModule,
+  WorkflowProof,
 } from "./types.ts";
+import { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";
 import { parseStageOutput, validateAgainstSchema } from "./validate.ts";
 
 const DEFAULT_MAX_AGENTS = 50;
@@ -38,6 +58,20 @@ const DEFAULT_CONCURRENCY = 4;
 const DEFAULT_MAX_ATTEMPTS = 2;
 const DEFAULT_TIMEOUT_MS = 300_000;
 const DEFAULT_MAX_TURNS = 25;
+const DEFAULT_POLICY_ASK_TIMEOUT_MS = 60_000;
+const MAX_POLICY_DECISIONS = 50;
+
+export class WorkflowRunError extends Error {
+  readonly runId: string;
+  readonly proofPath: string;
+
+  constructor(message: string, runId: string, proofPath: string, cause?: unknown) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "WorkflowRunError";
+    this.runId = runId;
+    this.proofPath = proofPath;
+  }
+}
 
 export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise<RunReport> {
   const absScript = isAbsolute(scriptPath) ? scriptPath : resolve(process.cwd(), scriptPath);
@@ -45,18 +79,25 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
   if (typeof mod.default !== "function") {
     throw new Error(`${scriptPath}: workflow script must \`export default async (ctx) => …\``);
   }
-  const name = mod.meta?.name ?? scriptPath.replace(/^.*\//, "").replace(/\.[cm]?js$/, "");
+  const fallbackName = scriptPath.replace(/^.*\//, "").replace(/\.[cm]?js$/, "");
+  const meta = normalizeWorkflowMeta(mod.meta, fallbackName);
+  const name = meta.name;
 
   const runId = `wf-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
   const runDir = join(opts.coordRoot, ".harnery", "workflows", runId);
   mkdirSync(runDir, { recursive: true });
   const journalPath = join(runDir, "journal.jsonl");
+  const proofPath = join(runDir, "proof.json");
 
   const maxAgents = opts.maxAgents ?? DEFAULT_MAX_AGENTS;
   const concurrency = opts.concurrency ?? DEFAULT_CONCURRENCY;
   const cwd = opts.cwd ?? opts.coordRoot;
   const log = opts.onLog ?? ((line: string) => process.stderr.write(`${line}\n`));
   const defaultHarness: HarnessName = opts.defaultHarness ?? "claude-code";
+  const isolation = opts.isolation ?? "shared";
+  const networkAccess = opts.networkAccess ?? "unknown";
+  const policy = opts.policy ? normalizePolicy(opts.policy, { baseDir: cwd }) : undefined;
+  const repoBefore = snapshotRepo(cwd);
 
   // Per-child fixed context overhead: children spawn in `cwd` and load its
   // repo-instructions file into their system prompt, cache-writing it once
@@ -77,12 +118,21 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
   let agentsSpawned = 0;
   let agentsCached = 0;
   let costUsd = 0;
+  let reservedCostUsd = 0;
   let currentStage = "";
   let agentSeq = 0;
+  let evidenceSeq = 0;
+  let policySeq = 0;
   const billingProbed = new Map<HarnessName, BillingProbe>();
+  const agentProofs = new Map<string, WorkflowAgentProof>();
+  const evidenceRecords: WorkflowEvidenceRecord[] = [];
+  const policyDecisions: PolicyDecision[] = [];
+  const acceptanceIds = new Set(meta.acceptance.map((criterion) => criterion.id));
 
   const journal = (event: string, data: Record<string, unknown>): void => {
     const line = JSON.stringify({
+      schema_version: WORKFLOW_PROOF_SCHEMA_VERSION,
+      run_id: runId,
       ts: new Date().toISOString(),
       event,
       stage: currentStage,
@@ -109,7 +159,98 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
     waiters.shift()?.();
   };
 
+  // Policy checks that affect the shared cost reservation ledger serialize.
+  // Spawns still run concurrently after authorization; only the last-moment
+  // check-and-reserve section is exclusive.
+  let policyGate = Promise.resolve();
+  const withDispatchPolicyGate = async <T>(work: () => Promise<T>): Promise<T> => {
+    const previous = policyGate;
+    let open!: () => void;
+    policyGate = new Promise<void>((resolveGate) => {
+      open = resolveGate;
+    });
+    await previous;
+    try {
+      return await work();
+    } finally {
+      open();
+    }
+  };
+
+  const authorizePolicyRequest = async (rawRequest: PolicyRequest): Promise<PolicyDecision> => {
+    if (!policy) {
+      throw new Error("external mutation authorization requires a host policy");
+    }
+    if (policyDecisions.length >= MAX_POLICY_DECISIONS) {
+      throw new Error(
+        `workflow policy decision cap reached (${MAX_POLICY_DECISIONS}); split the workflow or reduce protected actions`,
+      );
+    }
+    const request = summarizePolicyRequest(rawRequest);
+    const evaluation = evaluatePolicy(policy, request);
+    const id = `p${++policySeq}`;
+    const checkedAt = new Date().toISOString();
+    journal("policy.check", {
+      id,
+      policy: policy.name,
+      policy_sha256: policyDigest(policy),
+      request,
+      verdict: evaluation.verdict,
+      rules: evaluation.rules,
+    });
+
+    let verdict: "allow" | "deny" = evaluation.verdict === "allow" ? "allow" : "deny";
+    let resolvedBy: PolicyDecision["resolved_by"] = "policy";
+    let reason = evaluation.reason;
+    if (evaluation.verdict === "ask") {
+      resolvedBy = "fail_closed";
+      if (!opts.resolvePolicyAsk) {
+        reason = `${evaluation.reason}; no host approval resolver is configured`;
+      } else {
+        try {
+          const resolution = await withTimeout(
+            Promise.resolve(opts.resolvePolicyAsk(request, evaluation)),
+            opts.policyAskTimeoutMs ?? DEFAULT_POLICY_ASK_TIMEOUT_MS,
+          );
+          if (!resolution || (resolution.verdict !== "allow" && resolution.verdict !== "deny")) {
+            reason = `${evaluation.reason}; host returned an invalid approval resolution`;
+          } else {
+            verdict = resolution.verdict;
+            resolvedBy = "host";
+            reason = boundedPolicyReason(resolution.reason ?? evaluation.reason);
+          }
+        } catch (error) {
+          reason = `${evaluation.reason}; approval failed closed: ${(error as Error).message}`;
+        }
+      }
+    }
+
+    const decision: PolicyDecision = {
+      id,
+      checked_at: checkedAt,
+      policy: policy.name,
+      phase: request.phase,
+      initial_verdict: evaluation.verdict,
+      verdict,
+      resolved_by: resolvedBy,
+      reason: boundedPolicyReason(reason),
+      rule_codes: evaluation.rules.map((rule) => rule.code),
+      request,
+    };
+    policyDecisions.push(decision);
+    journal("policy.resolve", { ...decision });
+    if (decision.verdict === "deny") {
+      throw new PolicyDeniedError(
+        `policy ${JSON.stringify(policy.name)} denied ${request.phase} ${JSON.stringify(request.action)}: ${decision.reason}`,
+        decision.id,
+      );
+    }
+    return decision;
+  };
+
   const agent = async (prompt: string, agentOpts: AgentOpts = {}): Promise<unknown> => {
+    let reservedForDispatch = 0;
+    let spawnCountClaimed = false;
     const harness = agentOpts.harness ?? defaultHarness;
     const spawner = opts.spawners[harness];
     if (!spawner) {
@@ -119,7 +260,19 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
     }
     const id = `a${++agentSeq}`;
     const label = agentOpts.label ?? `${prompt.slice(0, 60).replace(/\s+/g, " ")}…`;
+    const proofLabel = agentOpts.label ?? id;
     const maxAttempts = agentOpts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const agentProof: WorkflowAgentProof = {
+      id,
+      label: proofLabel,
+      stage: currentStage || undefined,
+      harness,
+      model: agentOpts.model,
+      status: "failed",
+      attempts: 0,
+      duration_ms: 0,
+    };
+    agentProofs.set(id, agentProof);
 
     // Call identity for resume: same stage + harness + model + effort + turns + schema
     // + ORIGINAL prompt → same key. Retry-mutated prompts never enter the key.
@@ -127,63 +280,141 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
     const cached = resumeCache.get(key);
     if (cached) {
       agentsCached++;
-      journal("agent.cached", { id, label, key, kind: cached.kind });
+      agentProof.status = "cached";
+      agentProof.result = digestResult(cached.value, cached.kind);
+      journal("agent.cached", {
+        id,
+        label,
+        key,
+        harness,
+        model: agentOpts.model ?? null,
+        kind: cached.kind,
+      });
       log(
         `[${name}] ${currentStage || "(no stage)"} → ${id} ${label} (cached from ${opts.resumeFrom})`,
       );
       return cached.value;
     }
 
+    if (policy) {
+      const estimateRequest = summarizePolicyRequest({
+        phase: "dispatch",
+        action: "spawn agent",
+        path: cwd,
+        harness,
+        model: agentOpts.model,
+        effort: agentOpts.effort,
+        max_attempts: maxAttempts,
+        max_turns: agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
+        timeout_ms: agentOpts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        prompt_bytes: Buffer.byteLength(prompt),
+        isolation,
+        network_access: networkAccess,
+        current_cost_usd: round4(costUsd + reservedCostUsd),
+        projected_cost_usd: null,
+      });
+      let projectedCost: number | null = null;
+      if (policy.max_cost_usd !== undefined && opts.estimateDispatchCost) {
+        try {
+          const candidate = await opts.estimateDispatchCost(estimateRequest);
+          if (candidate !== null && (!Number.isFinite(candidate) || candidate < 0)) {
+            throw new Error("cost estimator returned a non-finite or negative value");
+          }
+          projectedCost = candidate;
+        } catch (error) {
+          journal("policy.cost_estimate_failed", {
+            harness,
+            model: agentOpts.model ?? null,
+            error: boundedPolicyReason((error as Error).message),
+          });
+        }
+      }
+      try {
+        await withDispatchPolicyGate(async () => {
+          assertAgentCapacity(agentsSpawned, maxAgents);
+          const dispatchRequest = {
+            ...estimateRequest,
+            current_cost_usd: round4(costUsd + reservedCostUsd),
+            projected_cost_usd: projectedCost,
+          };
+          await authorizePolicyRequest(dispatchRequest);
+          if (policy.max_cost_usd !== undefined) {
+            reservedForDispatch =
+              projectedCost ?? Math.max(0, policy.max_cost_usd - dispatchRequest.current_cost_usd);
+            reservedCostUsd += reservedForDispatch;
+          }
+          agentsSpawned++;
+          spawnCountClaimed = true;
+        });
+      } catch (error) {
+        agentProof.error = (error as Error).message;
+        throw error;
+      }
+    } else {
+      try {
+        assertAgentCapacity(agentsSpawned, maxAgents);
+      } catch (error) {
+        agentProof.error = (error as Error).message;
+        throw error;
+      }
+    }
+
     // Billing safeguard: on a harness's FIRST spawn this run, classify which
     // auth its children will use and refuse the silent-override state (an
     // exported API key shadowing a stored subscription login) unless the
     // caller explicitly opted into API billing. Cached agents never reach
     // this — no spawn, no billing.
-    if (!billingProbed.has(harness)) {
-      const probe = (opts.probeBilling ?? probeBilling)(harness);
-      billingProbed.set(harness, probe);
-      journal("billing.probe", {
-        harness,
-        mode: opts.subscriptionOnly ? "subscription" : probe.mode,
-        api_key_source: probe.apiKeySource,
-        login: probe.login,
-        subscription_only: Boolean(opts.subscriptionOnly),
-      });
-      if (opts.subscriptionOnly) {
-        if (probe.login === "absent") {
+    try {
+      if (!billingProbed.has(harness)) {
+        const probe = (opts.probeBilling ?? probeBilling)(harness);
+        billingProbed.set(harness, probe);
+        journal("billing.probe", {
+          harness,
+          mode: opts.subscriptionOnly ? "subscription" : probe.mode,
+          api_key_source: probe.apiKeySource,
+          login: probe.login,
+          subscription_only: Boolean(opts.subscriptionOnly),
+        });
+        if (opts.subscriptionOnly) {
+          if (probe.login === "absent") {
+            throw new Error(
+              `subscription-only: no stored login detected for ${harness}; ` +
+                `log the harness CLI in (or drop --subscription-only for a key-only host)`,
+            );
+          }
+          log(`[billing] ${harness}: subscription-only (API-key vars scrubbed from child env)`);
+        } else if (probe.mode === "api-key-override" && !opts.allowApiBilling) {
           throw new Error(
-            `subscription-only: no stored login detected for ${harness}; ` +
-              `log the harness CLI in (or drop --subscription-only for a key-only host)`,
+            `${probe.apiKeySource} is set AND a stored ${harness} login exists — the key silently ` +
+              `overrides your subscription auth, so children would bill per-token API rates. ` +
+              `Either unset ${probe.apiKeySource}, run with --subscription-only to scrub it from ` +
+              `child envs, or pass --allow-api-billing if API billing is intended`,
+          );
+        } else if (probe.mode === "api-key") {
+          log(
+            `[billing] ${harness}: API-key billing (${probe.apiKeySource}; no stored login detected) — ` +
+              `children bill per-token rates`,
+          );
+        } else if (probe.mode === "api-key-override") {
+          log(
+            `[billing] ${harness}: API-key billing (--allow-api-billing; key overrides stored login)`,
           );
+        } else {
+          log(`[billing] ${harness}: subscription login`);
         }
-        log(`[billing] ${harness}: subscription-only (API-key vars scrubbed from child env)`);
-      } else if (probe.mode === "api-key-override" && !opts.allowApiBilling) {
-        throw new Error(
-          `${probe.apiKeySource} is set AND a stored ${harness} login exists — the key silently ` +
-            `overrides your subscription auth, so children would bill per-token API rates. ` +
-            `Either unset ${probe.apiKeySource}, run with --subscription-only to scrub it from ` +
-            `child envs, or pass --allow-api-billing if API billing is intended`,
-        );
-      } else if (probe.mode === "api-key") {
-        log(
-          `[billing] ${harness}: API-key billing (${probe.apiKeySource}; no stored login detected) — ` +
-            `children bill per-token rates`,
-        );
-      } else if (probe.mode === "api-key-override") {
-        log(
-          `[billing] ${harness}: API-key billing (--allow-api-billing; key overrides stored login)`,
-        );
-      } else {
-        log(`[billing] ${harness}: subscription login`);
       }
+    } catch (error) {
+      reservedCostUsd = Math.max(0, reservedCostUsd - reservedForDispatch);
+      reservedForDispatch = 0;
+      if (spawnCountClaimed) {
+        agentsSpawned--;
+        spawnCountClaimed = false;
+      }
+      agentProof.error = (error as Error).message;
+      throw error;
     }
 
-    if (agentsSpawned >= maxAgents) {
-      throw new Error(
-        `workflow agent cap reached (${maxAgents}); raise --max-agents deliberately if the fan-out is intended`,
-      );
-    }
-    agentsSpawned++;
+    if (!spawnCountClaimed) agentsSpawned++;
 
     await acquire();
     try {
@@ -199,6 +430,7 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
 
       let attemptPrompt = prompt;
       let last: SpawnResult | null = null;
+      let agentCostUsd = 0;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         last = await spawner({
           prompt: attemptPrompt,
@@ -210,6 +442,9 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
           runId,
           subscriptionOnly: opts.subscriptionOnly,
         });
+        agentProof.attempts = attempt;
+        agentProof.duration_ms += last.durationMs;
+        agentCostUsd += last.costUsd ?? 0;
         costUsd += last.costUsd ?? 0;
 
         if (!last.ok) {
@@ -217,6 +452,11 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
           continue; // spawn-level failure: retry with the original prompt
         }
         if (!agentOpts.schema) {
+          agentProof.status = "succeeded";
+          agentProof.cost_usd =
+            agentCostUsd > 0 || last.costUsd !== undefined ? agentCostUsd : undefined;
+          agentProof.session_id = last.sessionId;
+          agentProof.result = digestResult(last.text, "text");
           journal("agent.end", {
             id,
             key,
@@ -236,6 +476,11 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
             ? [parsed.error]
             : validateAgainstSchema(parsed.value, agentOpts.schema);
         if (problems.length === 0) {
+          agentProof.status = "succeeded";
+          agentProof.cost_usd =
+            agentCostUsd > 0 || last.costUsd !== undefined ? agentCostUsd : undefined;
+          agentProof.session_id = last.sessionId;
+          agentProof.result = digestResult(parsed.value, "json");
           journal("agent.end", {
             id,
             key,
@@ -261,9 +506,17 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
       const reason = last?.ok
         ? `schema validation failed after ${maxAttempts} attempt(s)`
         : (last?.error ?? "spawn failed");
+      agentProof.cost_usd =
+        agentCostUsd > 0 || last?.costUsd !== undefined ? agentCostUsd : undefined;
+      agentProof.session_id = last?.sessionId;
+      agentProof.error = reason;
       journal("agent.failed", { id, error: reason });
-      throw new Error(`agent ${id} (${label}): ${reason}`);
+      throw new Error(`agent ${proofLabel}: ${reason}`);
+    } catch (error) {
+      agentProof.error ??= (error as Error).message;
+      throw error;
     } finally {
+      reservedCostUsd = Math.max(0, reservedCostUsd - reservedForDispatch);
       release();
     }
   };
@@ -288,12 +541,91 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
     log(`[${name}] ── stage: ${title}`);
   };
 
-  const ctx: WorkflowContext = { agent, parallel, stage, log };
+  const evidence = (input: Parameters<WorkflowContext["evidence"]>[0]): string => {
+    const record = createEvidenceRecord({
+      value: input,
+      sequence: evidenceSeq + 1,
+      acceptanceIds,
+      stage: currentStage || undefined,
+    });
+    evidenceSeq++;
+    evidenceRecords.push(record);
+    journal("evidence.recorded", { ...record });
+    return record.id;
+  };
+
+  const authorize = async (input: ExternalMutationRequest): Promise<PolicyDecision> => {
+    const network =
+      input.network === true || input.service !== undefined || input.target !== undefined
+        ? "enabled"
+        : "disabled";
+    return authorizePolicyRequest({
+      phase: "external_mutation",
+      action: input.action,
+      path: input.path ? resolve(cwd, input.path) : undefined,
+      isolation,
+      network_access: network,
+      service: input.service,
+      target: input.target,
+      current_cost_usd: round4(costUsd),
+    });
+  };
+
+  const ctx: WorkflowContext = { agent, parallel, stage, log, evidence, authorize };
 
   const t0 = Date.now();
-  journal("run.start", { name, script: absScript, max_agents: maxAgents, concurrency });
+  const startedAt = new Date(t0).toISOString();
+  journal("run.start", {
+    name,
+    script: absScript,
+    objective: meta.objective ?? null,
+    acceptance: meta.acceptance,
+    max_agents: maxAgents,
+    concurrency,
+    policy: policy ? { name: policy.name, sha256: policyDigest(policy) } : null,
+    isolation,
+    network_access: networkAccess,
+  });
   try {
     const result = await mod.default(ctx);
+    const endedAt = new Date().toISOString();
+    const durationMs = Date.now() - t0;
+    journal("run.end", {
+      ok: true,
+      agents: agentsSpawned,
+      cached: agentsCached,
+      cost_usd: round4(costUsd),
+      duration_ms: durationMs,
+    });
+    let proof: WorkflowProof;
+    try {
+      proof = buildWorkflowProof({
+        runId,
+        meta,
+        status: "succeeded",
+        startedAt,
+        endedAt,
+        durationMs,
+        journalPath,
+        before: repoBefore,
+        after: snapshotRepo(cwd),
+        agents: Array.from(agentProofs.values()),
+        evidence: evidenceRecords,
+        harnessEvidence: opts.harnessEvidence,
+        policy: policy
+          ? { config: policy, decisions: policyDecisions, isolation, networkAccess }
+          : undefined,
+        result,
+      });
+      writeWorkflowProof(proofPath, proof);
+    } catch (error) {
+      throw new WorkflowRunError(
+        `workflow completed but its proof packet could not be written: ${(error as Error).message}`,
+        runId,
+        proofPath,
+        error,
+      );
+    }
     const report: RunReport = {
       runId,
       name,
@@ -301,31 +633,59 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
       agentsSpawned,
       agentsCached,
       costUsd: round4(costUsd),
-      durationMs: Date.now() - t0,
+      durationMs,
       journalPath,
+      proofPath,
+      acceptance: proof.acceptance.summary,
       contextTokensPerChildEstimate,
       billing: Array.from(billingProbed.values()).map((p) => ({
         harness: p.harness,
         mode: opts.subscriptionOnly ? "subscription" : p.mode,
       })),
+      policy: proof.policy?.summary,
     };
-    journal("run.end", {
-      ok: true,
-      agents: agentsSpawned,
-      cached: agentsCached,
-      cost_usd: report.costUsd,
-      duration_ms: report.durationMs,
-    });
     return report;
   } catch (err) {
+    if (err instanceof WorkflowRunError) throw err;
+    const endedAt = new Date().toISOString();
+    const durationMs = Date.now() - t0;
     journal("run.end", {
       ok: false,
       error: (err as Error).message,
       agents: agentsSpawned,
       cached: agentsCached,
       cost_usd: round4(costUsd),
+      duration_ms: durationMs,
     });
-    throw err;
+    try {
+      const proof = buildWorkflowProof({
+        runId,
+        meta,
+        status: "failed",
+        startedAt,
+        endedAt,
+        durationMs,
+        journalPath,
+        before: repoBefore,
+        after: snapshotRepo(cwd),
+        agents: Array.from(agentProofs.values()),
+        evidence: evidenceRecords,
+        harnessEvidence: opts.harnessEvidence,
+        policy: policy
+          ? { config: policy, decisions: policyDecisions, isolation, networkAccess }
+          : undefined,
+        error: (err as Error).message,
+      });
+      writeWorkflowProof(proofPath, proof);
+    } catch (proofError) {
+      throw new WorkflowRunError(
+        `${(err as Error).message}; proof packet write also failed: ${(proofError as Error).message}`,
+        runId,
+        proofPath,
+        err,
+      );
+    }
+    throw new WorkflowRunError((err as Error).message, runId, proofPath, err);
   }
 }
 
@@ -401,3 +761,42 @@ function loadResumeCache(
 function round4(n: number): number {
   return Math.round(n * 10_000) / 10_000;
 }
+
+function assertAgentCapacity(agentsSpawned: number, maxAgents: number): void {
+  if (agentsSpawned >= maxAgents) {
+    throw new Error(
+      `workflow agent cap reached (${maxAgents}); raise --max-agents deliberately if the fan-out is intended`,
+    );
+  }
+}
+
+function boundedPolicyReason(value: string): string {
+  const normalized = Array.from(value, (character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127 ? " " : character;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  return normalized.length > 2_000 ? `${normalized.slice(0, 1_999)}…` : normalized;
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("policyAskTimeoutMs must be a positive finite number");
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`approval timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}