forgeos 0.1.0-alpha.71 → 0.1.0-alpha.72

package/src/forge/agent-fabric/codex-sdk-worker.ts

@@ -1,4 +1,4 @@
-import { Codex, type CodexOptions, type ThreadOptions, type TurnOptions, type ThreadEvent } from "@openai/codex-sdk";
+import { Codex, type CodexOptions, type ThreadOptions, type TurnOptions, type ThreadEvent, type Input } from "@openai/codex-sdk";
 import { realpath, stat, readFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
@@ -13,6 +13,7 @@ export interface CodexWorkerEvent { type: string; threadId?: string; summary?: s
 export interface CodexWorkerInput {
   cwd: string; prompt: string; role: "implementer" | "reviewer" | "investigator" | "decision";
   model?: string; threadId?: string; signal: AbortSignal;
+  images?: { path: string }[];
   onEvent: (event: CodexWorkerEvent) => Promise<void> | void;
 }
 export interface CodexWorkerOutput {
@@ -22,7 +23,7 @@ export interface CodexWorkerOutput {
 }
 export interface CodexWorkerThread {
   readonly id: string | null;
-  runStreamed(prompt: string, options: TurnOptions): Promise<{ events: AsyncIterable<ThreadEvent> }>;
+  runStreamed(prompt: Input, options: TurnOptions): Promise<{ events: AsyncIterable<ThreadEvent> }>;
 }
 export interface CodexWorkerClient {
   startThread(options: ThreadOptions): CodexWorkerThread;
@@ -183,14 +184,19 @@ async function runTypedCodexWorkerInternal(input: CodexWorkerInput & { outputSch
   const threadOptions: ThreadOptions = { workingDirectory: cwd, sandboxMode: input.role === "implementer" ? "workspace-write" : "read-only", networkAccessEnabled: false, webSearchMode: "disabled", approvalPolicy: "never", ...(input.model ? { model: input.model } : {}) };
   const thread = input.threadId ? client.resumeThread(input.threadId, threadOptions) : client.startThread(threadOptions);
   let threadId = input.threadId ?? thread.id ?? "", finalMessage: string | undefined, completed = false, count = 0, observedUsage: CodexWorkerUsage | undefined;
-  const stream = await thread.runStreamed(`${input.prompt}\nReturn only data matching the requested output schema. Never include credentials.`, { outputSchema: input.outputSchema, signal: input.signal });
+  const prompt = `${input.prompt}\nReturn only data matching the requested output schema. Never include credentials.`;
+  if (input.images && (input.images.length > 100 || input.images.some(image => !text(image.path, 4096)))) fail("AF_CODEX_INPUT", "Invalid image inputs");
+  const content: Input = input.images?.length ? [{ type: "text", text: prompt }, ...input.images.map(image => ({ type: "local_image" as const, path: image.path }))] : prompt;
+  const stream = await thread.runStreamed(content, { outputSchema: input.outputSchema, signal: input.signal });
+  if (input.images?.length) await input.onEvent({ type: "input.images.delivered", summary: `${input.images.length} images supplied through SDK local_image; understanding is not attested` });
   for await (const event of stream.events) {
     checkAbort(input.signal); if (++count > 10000) fail("AF_CODEX_EVENT_LIMIT", "Typed worker event budget exceeded");
     if (!["thread.started", "turn.started", "item.completed", "item.started", "item.updated", "turn.completed", "turn.failed", "error"].includes(event.type)) fail("AF_CODEX_EVENT", "Unknown typed event");
     if (event.type === "thread.started") { if (!text(event.thread_id, 128) || !/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/u.test(event.thread_id) || threadId && threadId !== event.thread_id) fail("AF_CODEX_EVENT", "Thread identity changed"); threadId = event.thread_id; await input.onEvent({ type: event.type, threadId }); }
     else if (event.type === "item.completed" && event.item.type === "agent_message") { if (completed || !text(event.item.text, 4 * 1024 * 1024)) fail("AF_CODEX_REPORT", "Invalid typed message"); finalMessage = event.item.text; }
     else if (event.type === "turn.completed") { if (completed) fail("AF_CODEX_EVENT", "Duplicate completion"); completed = true; observedUsage = usage(event.usage); await input.onEvent({ type: event.type, usage: observedUsage }); }
-    else if (event.type === "turn.failed" || event.type === "error") fail("AF_CODEX_TURN_FAILED", "Typed worker failed; reconcile before retry");
+    else if (event.type === "turn.failed" || event.type === "error") { await input.onEvent({ type: event.type, summary: "Typed worker failed; reconcile before retry" }); fail("AF_CODEX_TURN_FAILED", "Typed worker failed; reconcile before retry"); }
+    else await input.onEvent({ type: event.type, summary: "Typed SDK activity observed" });
   }
   checkAbort(input.signal); if (!completed || !threadId || !finalMessage) fail("AF_CODEX_INCOMPLETE", "Typed worker completion not observed");
   let data: unknown; try { data = JSON.parse(finalMessage); input.validateOutput(data); } catch { fail("AF_CODEX_REPORT", "Typed worker output schema invalid"); }

package/src/forge/agent-fabric/index.ts

@@ -44,5 +44,10 @@ export { lowerWorkflowSource, PROGRAM_DSL_VERSION } from "./program-dsl.ts";
 export { ProgramRunService, PROGRAM_RUN_ACTIONS } from "./program-service.ts";
 export type { ProgramRunAction } from "./program-service.ts";
 export { ProgramRunStore } from "./program-store.ts";
+export * from "./program-authoring.ts";
+export * from "./program-templates.ts";
+export * from "./program-runtime-options.ts";
+export * from "./program-benchmark.ts";
+export * from "./program-observation.ts";
 export { validateProgramCapabilities } from "./program-worker.ts";
 export type { ProgramWorkerAdapter, ProgramWorkerInput, ProgramWorkerResult } from "./program-worker.ts";

package/src/forge/agent-fabric/local-task-server.ts

@@ -14,6 +14,7 @@ import { localFabricPath } from "./local-paths.ts";
 import { applyFabricProfile } from "./project-profile.ts";
 import { ProgramRunService, PROGRAM_RUN_ACTIONS, type ProgramRunAction } from "./program-service.ts";
 import { ProgramError } from "./program-contract.ts";
+import { readProgramRuntimeOptions } from "./program-runtime-options.ts";
 
 const MAX_REQUEST_BYTES = 40 * 1024;
 const ENDPOINT_FILENAME = "owner-endpoint.json";
@@ -200,7 +201,7 @@ export async function serveLocalTasks(
     attachedService = await AttachedTaskService.open(root);
     const { ManagedRunService: ManagedService } = await import("./managed-run-service.ts");
     managedService = await ManagedService.open(root);
-    programService = await ProgramRunService.open(root);
+    programService = await ProgramRunService.open(root, undefined, undefined, readProgramRuntimeOptions(root));
     const token = randomBytes(32).toString("hex");
     listener = createServer((request, response: ServerResponse) => {
       response.setHeader("Content-Type", "application/json; charset=utf-8");

package/src/forge/agent-fabric/managed-environment.ts

@@ -8,7 +8,8 @@ import { tmpdir } from "node:os";
 import { stableStringify } from "./canonical.ts";
 
 type Manager = "npm" | "pnpm" | "yarn" | "bun" | "none";
-export interface ManagedEnvironmentOptions { mode?: "auto" | "none"; ignoreScripts?: boolean; registry?: string; timeoutMs?: number; cacheDirectory?: string; signal?: AbortSignal }
+export interface ManagedEnvironmentOptions { mode?: "auto" | "none"; ignoreScripts?: boolean; registry?: string; timeoutMs?: number; cacheDirectory?: string; signal?: AbortSignal;
+  onTiming?: (measurement: { phase: "cache.verify" | "cache.copy" | "dependencies.install"; elapsedMs: number }) => Promise<void> | void }
 export interface ManagedEnvironment { schemaVersion: 1; directory: string; manager: Manager; lockDigest: string; dependencyDigest: string; derivedPaths: string[]; cacheHit: boolean }
 const execute = promisify(execFile);
 const hash = (value: string | Uint8Array) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
@@ -134,6 +135,11 @@ export async function verifyManagedEnvironment(environment: ManagedEnvironment):
   assert(await dependencyDigest(environment.directory, environment.derivedPaths) === environment.dependencyDigest, "prepared dependencies were modified; result is invalid");
 }
 export async function prepareManagedEnvironment(directory: string, options: ManagedEnvironmentOptions = {}): Promise<ManagedEnvironment> {
+  const timed = async <T>(phase: "cache.verify" | "cache.copy" | "dependencies.install", operation: () => Promise<T>): Promise<T> => {
+    const start = performance.now();
+    try { return await operation(); }
+    finally { await options.onTiming?.({ phase, elapsedMs: performance.now() - start }); }
+  };
   directory = resolve(directory); aborted(options.signal);
   assert(!(await lstat(directory)).isSymbolicLink(), "workspace root cannot be a symlink");
   const none = (): ManagedEnvironment => ({ schemaVersion: 1, directory, manager: "none", lockDigest: hash("none"), dependencyDigest: hash(stableStringify([])), derivedPaths: [], cacheHit: false });
@@ -160,9 +166,9 @@ export async function prepareManagedEnvironment(directory: string, options: Mana
   const cache = join(cacheRoot, lockDigest.slice(7)), marker = join(cache, "environment.json");
   if (await exists(marker)) {
     const cached = JSON.parse(await readFile(marker, "utf8")) as ManagedEnvironment;
-    assert(cached.lockDigest === lockDigest && cached.dependencyDigest === await dependencyDigest(join(cache, "tree"), cached.derivedPaths, options.signal), "dependency cache integrity failed");
-    await copyDependencyPaths(join(cache, "tree"), directory, cached.derivedPaths, options.signal);
-    const environment = { ...cached, directory, cacheHit: true }; await verifyManagedEnvironment(environment); return environment;
+    await timed("cache.verify", async () => { assert(cached.lockDigest === lockDigest && cached.dependencyDigest === await dependencyDigest(join(cache, "tree"), cached.derivedPaths, options.signal), "dependency cache integrity failed"); });
+    await timed("cache.copy", () => copyDependencyPaths(join(cache, "tree"), directory, cached.derivedPaths, options.signal));
+    const environment = { ...cached, directory, cacheHit: true }; await timed("cache.verify", () => verifyManagedEnvironment(environment)); return environment;
   }
   const configBackups: { path: string; bytes?: Buffer }[] = [];
   try {
@@ -178,7 +184,7 @@ export async function prepareManagedEnvironment(directory: string, options: Mana
       : Number.parseInt(version) >= 2 ? ["install", "--immutable", ...(ignore ? ["--mode=skip-builds"] : [])] : ["install", "--frozen-lockfile", "--non-interactive", `--registry=${registry}`, ...(ignore ? ["--ignore-scripts"] : [])];
     env.YARN_NODE_LINKER = "node-modules"; env.YARN_NM_MODE = "classic"; env.YARN_ENABLE_GLOBAL_CACHE = "false"; env.YARN_NPM_REGISTRY_SERVER = registry; env.YARN_ENABLE_SCRIPTS = ignore ? "false" : "true";
     env.NPM_CONFIG_CACHE = join(cacheRoot, "download-cache"); env.BUN_INSTALL_CACHE_DIR = join(cacheRoot, "bun-download-cache"); env.COREPACK_HOME = join(cacheRoot, "corepack-cache");
-    await execute(command.executable, [...command.prefix, ...args], { cwd: directory, env, windowsHide: true, timeout, signal: options.signal, maxBuffer: 1024 * 1024 });
+    await timed("dependencies.install", () => execute(command.executable, [...command.prefix, ...args], { cwd: directory, env, windowsHide: true, timeout, signal: options.signal, maxBuffer: 1024 * 1024 }));
   } catch (error) { if (options.signal?.aborted) throw new Error("managed environment: preparation canceled"); throw new Error(`managed environment: frozen ${manager} install failed: ${(error as Error).message.slice(0, 2000)}`); }
   finally { for (const config of configBackups) await writeFile(config.path, config.bytes!); }
   aborted(options.signal); const derivedPaths = await derivePaths(directory);
@@ -186,12 +192,12 @@ export async function prepareManagedEnvironment(directory: string, options: Mana
   derivedPaths.sort(); await portableLinks(directory, derivedPaths); const dependency = await dependencyDigest(directory, derivedPaths, options.signal);
   const environment: ManagedEnvironment = { schemaVersion: 1, directory, manager, lockDigest, dependencyDigest: dependency, derivedPaths, cacheHit: false };
   stage = join(cacheRoot, `${lockDigest.slice(7)}-${randomUUID()}.stage`); await mkdir(join(stage, "tree"), { recursive: true });
-  await copyDependencyPaths(directory, join(stage, "tree"), derivedPaths, options.signal);
-  assert(await dependencyDigest(join(stage, "tree"), derivedPaths, options.signal) === dependency, "cache copy integrity failed");
+  await timed("cache.copy", () => copyDependencyPaths(directory, join(stage!, "tree"), derivedPaths, options.signal));
+  await timed("cache.verify", async () => { assert(await dependencyDigest(join(stage!, "tree"), derivedPaths, options.signal) === dependency, "cache copy integrity failed"); });
   try {
     await rename(stage, cache); uncommittedCache = cache;
     await rebaseCacheJunctions(join(cache, "tree"), join(stage, "tree"), derivedPaths);
-    assert(await dependencyDigest(join(cache, "tree"), derivedPaths, options.signal) === dependency, "published cache integrity failed");
+    await timed("cache.verify", async () => { assert(await dependencyDigest(join(cache, "tree"), derivedPaths, options.signal) === dependency, "published cache integrity failed"); });
     const markerTemp = join(cache, "environment.json.tmp");
     await writeFile(markerTemp, stableStringify(environment)); await rename(markerTemp, join(cache, "environment.json")); uncommittedCache = undefined;
   } catch (error) { if (uncommittedCache || !["EEXIST", "ENOTEMPTY", "EPERM"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error; }

package/src/forge/agent-fabric/managed-workspace.ts

@@ -192,6 +192,10 @@ export async function captureManagedArtifact(base: ManagedBase, workspaceDirecto
   }
   const artifact = { digest: artifactDigest(files), files }; validateArtifact(artifact, writeScope); return artifact;
 }
+/** A bounded observation of the complete managed source delta, never a termination attestation. */
+export async function observeManagedWorkspace(base: ManagedBase, directory: string, inputDigest: string, environment?: ManagedEnvironment, generatedPaths: string[] = []): Promise<string> {
+  return (await captureManagedArtifact(base, directory, base.scope, inputDigest, environment, generatedPaths)).digest;
+}
 export async function publishManagedArtifacts(base: ManagedBase, artifacts: ManagedArtifact[], controls?: { beforeWrite?: () => Promise<void> }): Promise<{ digest: string; changedFiles: string[] }> {
   await validateBase(base); const before = await inventory(base.root, base.scope);
   assert(before.digest === base.digest && await currentContextMatches(base) && await git(base.root, ["rev-parse", "HEAD"]) === base.head, "source changed since capture (including readonly environment context)");

package/src/forge/agent-fabric/program-api.ts

@@ -26,7 +26,7 @@ export interface WorkflowOptions {
   branch: Common & { condition: boolean | ProgramExpr; then: Body; else: Body };
   loop: Common & { initialState: Data; maxRounds: number; body: Body; next: Data; until: boolean | ProgramExpr };
   repair: Common & { recipe: WorkflowRef<"recipe">; implement: WorkflowRef<"executor">; review: WorkflowRef<"executor">; checks: Data; input?: Data; evidence?: WorkflowRef<"executor">[]; assessmentScope?: "item" | "final"; entryMode: "implement-first" | "assess-first"; initialCandidate: Data; writeScope: Data; maxRepairRounds: number; maxAssessmentAttempts: number; maxInfrastructureAttempts: number; progressPolicy: { unchangedCandidateRounds: number; repeatedFindingsRounds: number } };
-  compose: Common & { candidates: Data; onConflict?: "needs-resolution" };
+  compose: Common & { candidates: Data; onConflict?: "needs-resolution"; resolver?: WorkflowRef<"executor">; resolverInput?: Data; resolverWriteScope?: Data };
   gate: Common & { candidate: Data; coverage?: Data; authorization?: Data };
   subworkflow: Common & { program: WorkflowRef<"program">; input: Data };
   waitEvent: Common & { type: string; correlation: Data; schema: WorkflowRef<"schema">; subject?: Data; timeoutMs?: number };

package/src/forge/agent-fabric/program-authoring.ts

@@ -0,0 +1,48 @@
+import { programDigest, programValueBytes, programWithin, refKey, registryEntry, validateWorkflowProgram, type ProgramRegistry, type ProgramSchema, type WorkflowProgramV2 } from "./program-contract.ts";
+import { programGraph } from "./program-structure.ts";
+import { buildWorkflowTemplate, type ProgramTemplateKind, type ProgramTemplateOptions } from "./program-templates.ts";
+
+export interface ProgramAuthorDiagnostic { code: string; message: string; operationId?: string }
+export interface ProgramAuthorProposal {
+  valid: boolean; program?: WorkflowProgramV2; digest?: string; diagnostics: ProgramAuthorDiagnostic[];
+  summary?: { criteria: string[]; requiredChecks: string[]; writeScope: string[]; humanApproval: boolean; operations: { id: string; kind: string; dependencies: string[] }[] };
+}
+export function validateProgramProposal(program: WorkflowProgramV2, registry: ProgramRegistry): ProgramAuthorProposal {
+  try {
+    validateWorkflowProgram(program, registry);
+    const acceptance = registryEntry(registry.acceptance, program.acceptance);
+    const policy = registryEntry(registry.policies, program.policy);
+    return { valid: true, program: structuredClone(program), digest: programDigest(program), diagnostics: [], summary: {
+      criteria: [...acceptance.criteria], requiredChecks: [...new Set([...acceptance.requiredChecks, ...(acceptance.requiredChecksByScope?.item ?? []), ...(acceptance.requiredChecksByScope?.final ?? [])])],
+      writeScope: [...new Set([...acceptance.writeScope, ...policy.writeScope])].filter(path => programWithin(path, acceptance.writeScope) && programWithin(path, policy.writeScope)), humanApproval: acceptance.requireHumanApproval === true,
+      operations: programGraph(program).map(entry => ({ id: entry.id, kind: entry.step.kind, dependencies: entry.dependencies })),
+    } };
+  } catch (error) {
+    return { valid: false, diagnostics: [{ code: (error as { code?: string }).code ?? "AF_PROGRAM_INVALID", message: error instanceof Error ? error.message : String(error) }] };
+  }
+}
+export function proposeWorkflowTemplate(kind: ProgramTemplateKind, options: ProgramTemplateOptions, registry: ProgramRegistry): ProgramAuthorProposal {
+  try { programValueBytes(options, 40000, 128); return validateProgramProposal(buildWorkflowTemplate(kind, options, registry), registry); }
+  catch (error) { return { valid: false, diagnostics: [{ code: "AF_PROGRAM_TEMPLATE_INVALID", message: error instanceof Error ? error.message : String(error) }] }; }
+}
+
+/** Generate authoring declarations from the owner's schemas, without evaluating authored code. */
+export function generateRegistryAuthorTypes(registry: ProgramRegistry): string {
+  programValueBytes(registry, 4 * 1024 * 1024);
+  const shape = (schema: ProgramSchema, depth = 0): string => {
+    if (depth > 32) throw new Error("Schema depth exceeded");
+    if (Object.hasOwn(schema, "const")) return JSON.stringify(schema.const);
+    if (schema.enum?.length) return schema.enum.map(value => JSON.stringify(value)).join(" | ");
+    if (schema.anyOf?.length) return schema.anyOf.map(value => shape(value, depth + 1)).join(" | ");
+    const types = schema.type ? Array.isArray(schema.type) ? schema.type : [schema.type] : [];
+    if (!types.length) return "unknown";
+    return types.map(type => {
+      if (type === "object") return `{ ${[...Object.entries(schema.properties ?? {}).map(([key, value]) => `${JSON.stringify(key)}${schema.required?.includes(key) ? "" : "?"}: ${shape(value, depth + 1)}`), ...(schema.additionalProperties === false ? [] : ["[key: string]: unknown"])].join("; ")} }`;
+      if (type === "array") return `Array<${shape(schema.items ?? {}, depth + 1)}>`;
+      return type === "integer" ? "number" : type;
+    }).join(" | ");
+  };
+  const schemas = Object.entries(registry.schemas).sort(([a], [b]) => a.localeCompare(b));
+  const refs = (entries: Record<string, unknown>) => Object.keys(entries).sort().map(key => JSON.stringify(key)).join(" | ") || "never";
+  return `// Generated owner registry authoring types; runtime owner validation remains authoritative.\nexport interface OwnerSchemas {\n${schemas.map(([key, value]) => `  ${JSON.stringify(key)}: ${shape(value)};`).join("\n")}\n}\nexport interface OwnerExecutors {\n${Object.entries(registry.executors).sort(([a], [b]) => a.localeCompare(b)).map(([key, executor]) => `  ${JSON.stringify(key)}: { input: ${executor.inputSchema ? `OwnerSchemas[${JSON.stringify(refKey(executor.inputSchema))}]` : "unknown"}; output: OwnerSchemas[${JSON.stringify(refKey(executor.schema))}] };`).join("\n")}\n}\nexport type OwnerPolicyKey = ${refs(registry.policies)};\nexport type OwnerAcceptanceKey = ${refs(registry.acceptance)};\n`;
+}

package/src/forge/agent-fabric/program-benchmark.ts

@@ -0,0 +1,76 @@
+import { programAssert, programDigest, programValueBytes } from "./program-contract.ts";
+
+export interface ProgramBenchmarkObservation {
+  taskId: string; runtimeVersion: string; model: string; toolsDigest: string; contextDigest: string; contractDigest: string;
+  category: "runtime" | "coding"; budget: string;
+  timingMs: Partial<Record<"queue" | "preparation" | "execution" | "capture" | "persistence" | "integration", number>>;
+  inputTokens?: number; outputTokens?: number; usageStatus: "observed" | "estimated" | "unknown";
+  externalEvaluation?: { assessor: string; criteriaDigest: string; independent: boolean; success: boolean; escapedDefects: number; unnecessaryChanges: number };
+  humanInterventions: number; repeatedActivities: number; retainedBytes?: number;
+}
+export interface ProgramBenchmarkReport { schemaVersion: 1; benchmarkId: string; observations: ProgramBenchmarkObservation[]; limitations: string[] }
+
+/** Data validation only: producing a report never executes a model or workflow. */
+export function validateBenchmarkReport(report: ProgramBenchmarkReport): void {
+  programValueBytes(report, 4 * 1024 * 1024);
+  programAssert(report?.schemaVersion === 1 && typeof report.benchmarkId === "string" && report.benchmarkId.length > 0, "Benchmark identity required");
+  programAssert(Array.isArray(report.observations) && report.observations.length > 0 && Array.isArray(report.limitations) && report.limitations.every(value => typeof value === "string"), "Benchmark observations and limitations required");
+  const identities = new Set<string>();
+  const count = (value: unknown) => Number.isSafeInteger(value) && Number(value) >= 0;
+  for (const entry of report.observations) {
+    programAssert(entry && typeof entry === "object", "Benchmark observation required");
+    for (const key of ["taskId", "runtimeVersion", "model", "toolsDigest", "contextDigest", "contractDigest", "budget"] as const) programAssert(typeof entry[key] === "string" && entry[key].length > 0, `Benchmark ${key} required`);
+    programAssert(!identities.has(entry.taskId), "Duplicate benchmark task identity"); identities.add(entry.taskId);
+    programAssert(["runtime", "coding"].includes(entry.category) && ["observed", "estimated", "unknown"].includes(entry.usageStatus), "Invalid benchmark category or usage status");
+    programAssert(entry.timingMs && typeof entry.timingMs === "object" && !Array.isArray(entry.timingMs), "Timing observations required");
+    for (const [key, value] of Object.entries(entry.timingMs)) programAssert(["queue", "preparation", "execution", "capture", "persistence", "integration"].includes(key) && typeof value === "number" && Number.isFinite(value) && value >= 0, "Invalid timing observation");
+    for (const value of [entry.humanInterventions, entry.repeatedActivities]) programAssert(count(value), "Invalid benchmark counter");
+    for (const value of [entry.inputTokens, entry.outputTokens, entry.retainedBytes]) if (value !== undefined) programAssert(count(value), "Invalid optional benchmark counter");
+    if (entry.usageStatus === "unknown") programAssert(entry.inputTokens === undefined && entry.outputTokens === undefined, "Unknown consumption cannot be represented as measured tokens");
+    else programAssert(entry.inputTokens !== undefined && entry.outputTokens !== undefined, "Observed or estimated consumption requires both token counters");
+    if (entry.externalEvaluation) {
+      const assessment = entry.externalEvaluation;
+      programAssert(typeof assessment.assessor === "string" && assessment.assessor.length > 0 && typeof assessment.criteriaDigest === "string" && assessment.criteriaDigest.length > 0, "External assessment provenance required");
+      programAssert(typeof assessment.independent === "boolean" && typeof assessment.success === "boolean" && count(assessment.escapedDefects) && count(assessment.unnecessaryChanges), "Invalid external assessment");
+    }
+  }
+}
+/** Pair by task identity, never by array position; unmatched/confounded trials fail eligibility. */
+export function compareBenchmarkReports(left: ProgramBenchmarkReport, right: ProgramBenchmarkReport) {
+  validateBenchmarkReport(left); validateBenchmarkReport(right);
+  programAssert(left.benchmarkId !== right.benchmarkId, "Paired reports require distinct benchmark identities");
+  const leftById = new Map(left.observations.map(entry => [entry.taskId, entry]));
+  const rightById = new Map(right.observations.map(entry => [entry.taskId, entry]));
+  const differences: { taskId: string; fields: string[] }[] = [];
+  const unmatchedTasks = [...new Set([...leftById.keys(), ...rightById.keys()])].filter(id => !leftById.has(id) || !rightById.has(id)).sort();
+  const pairs = left.observations.filter(entry => rightById.has(entry.taskId)).map(entry => {
+    const counterpart = rightById.get(entry.taskId)!;
+    const fields: string[] = (["category", "model", "toolsDigest", "contextDigest", "contractDigest", "budget"] as const).filter(key => entry[key] !== counterpart[key]);
+    if (entry.externalEvaluation?.criteriaDigest !== counterpart.externalEvaluation?.criteriaDigest) fields.push("criteriaDigest");
+    if (fields.length) differences.push({ taskId: entry.taskId, fields: [...new Set(fields)] });
+    return { taskId: entry.taskId, leftVersion: entry.runtimeVersion, rightVersion: counterpart.runtimeVersion };
+  });
+  const leftSummary = summarizeBenchmarkReport(left), rightSummary = summarizeBenchmarkReport(right);
+  const metrics = (report: ProgramBenchmarkReport) => {
+    const sum = (values: number[], integral = false) => { const total = values.reduce((total, value) => total + value, 0); programAssert(Number.isFinite(total) && (!integral || Number.isSafeInteger(total)), "Benchmark aggregate exceeds numeric limits"); return total; };
+    const verified = report.observations.filter(entry => entry.category === "coding" && entry.externalEvaluation?.independent && entry.externalEvaluation.success && entry.externalEvaluation.escapedDefects === 0).length;
+    const observedTokens = report.observations.every(entry => entry.usageStatus === "observed") ? sum(report.observations.flatMap(entry => [entry.inputTokens!, entry.outputTokens!]), true) : null;
+    const stages = ["queue", "preparation", "execution", "capture", "persistence", "integration"] as const;
+    const timeMs = report.observations.every(entry => stages.every(stage => entry.timingMs[stage] !== undefined)) ? sum(report.observations.flatMap(entry => stages.map(stage => entry.timingMs[stage]!))) : null;
+    return { verifiedTasks: verified, observedTokens, timeMs, tokensPerVerifiedTask: observedTokens !== null && verified ? observedTokens / verified : null, timeMsPerVerifiedTask: timeMs !== null && verified ? timeMs / verified : null, humanInterventions: sum(report.observations.map(entry => entry.humanInterventions), true), repeatedActivities: sum(report.observations.map(entry => entry.repeatedActivities), true) };
+  };
+  return { schemaVersion: 1, pairs, unmatchedTasks, differences, left: { ...leftSummary, metrics: metrics(left) }, right: { ...rightSummary, metrics: metrics(right) },
+    comparisonEligible: unmatchedTasks.length === 0 && differences.length === 0 && leftSummary.comparisonEligible && rightSummary.comparisonEligible,
+    limitations: ["Paired report validation does not execute benchmarks or verify assessor independence. Model, tools, context, contract, budget and criteria differences prevent a controlled superiority claim.", ...left.limitations, ...right.limitations] };
+}
+export function summarizeBenchmarkReport(report: ProgramBenchmarkReport) {
+  validateBenchmarkReport(report);
+  const coding = report.observations.filter(entry => entry.category === "coding");
+  const independentlyAssessed = coding.filter(entry => entry.externalEvaluation?.independent);
+  const success = independentlyAssessed.filter(entry => entry.externalEvaluation?.success && entry.externalEvaluation.escapedDefects === 0).length;
+  return { digest: programDigest(report), tasks: report.observations.length, independentlyAssessed: independentlyAssessed.length,
+    verifiedSuccessRate: independentlyAssessed.length ? success / independentlyAssessed.length : null,
+    unknownUsageTasks: report.observations.filter(entry => entry.usageStatus === "unknown").length,
+    comparisonEligible: coding.length > 0 && independentlyAssessed.length === coding.length,
+    limitations: [...report.limitations, "Eligibility does not prove superiority; comparison requires matched workloads and declared model/tool/context differences."] };
+}

package/src/forge/agent-fabric/program-capabilities.ts

@@ -0,0 +1,14 @@
+/** Shared public capability boundary; reports support, not real-provider certification. */
+export const programWorkflowExtensions = Object.freeze({
+  authoring: { templates: ["review", "bugfix", "migration"], ownerValidated: true, typedRegistry: true, dispatch: false },
+  runtimeConfig: ".forge/fabric-runtime.json",
+  scheduler: { fairness: "round-robin", defaultOwnerCapacity: 4, maxOwnerCapacity: 32 },
+  resources: { enforcement: "admission-only", unknownUsageExplicit: true, providerHardCap: false },
+  observations: { durable: true, deduplicated: true, invalidOutputRetainsUsage: true },
+  executors: ["codex", "command", "claude"],
+  claude: { optIn: true, isolation: "cooperative", network: "host", realProviderVerified: false },
+  nativeImages: ["codex"],
+  threadRecovery: "codex-observed-compatible-original-workspace",
+  conflictResolution: "owner-registered-resolver-fresh-final-assessment",
+  externalQualityEvaluated: false,
+});

package/src/forge/agent-fabric/program-contract.ts

@@ -3,6 +3,7 @@ import { stableStringify } from "./canonical.ts";
 import { programGraph } from "./program-structure.ts";
 import { validateVisualPopulation } from "./program-evidence.ts";
 import { validateProgramTypes } from "./program-types.ts";
+import type { ProgramWorkerObservation, ProgramUsageSummary } from "./program-observation.ts";
 
 export type ProgramValue = null | boolean | number | string | ProgramValue[] | { [key: string]: ProgramValue };
 export interface ProgramRef { id: string; version: string }
@@ -20,16 +21,18 @@ export type ProgramSchema = { type?: string | string[]; enum?: ProgramValue[]; c
   minimum?: number; maximum?: number; anyOf?: ProgramSchema[] };
 export interface ProgramLexicalContext { item?: ProgramSchema; state?: ProgramSchema }
 export interface ProgramExecutor {
-  id: string; version: string; kind: "command" | "codex"; effect: "read" | "isolated-write" | "idempotent-effect" | "non-idempotent-effect";
+  id: string; version: string; kind: "command" | "codex" | "claude"; effect: "read" | "isolated-write" | "idempotent-effect" | "non-idempotent-effect";
   argv?: string[]; prompt?: string; role?: "implementer" | "reviewer" | "investigator" | "decision";
   model?: string; timeoutMs: number; writeScope: string[]; allowedGeneratedPaths?: string[];
   network: "disabled" | "host"; isolation: "cooperative" | "sandbox"; schema: ProgramRef;
   allowedExitCodes?: number[]; environment?: Record<string, string>;
+  tokenAccounting?: "none" | "provider";
   inputSchema?: ProgramRef;
   dependencies?: "none" | "auto";
   cache?: "none" | "workspace";
 }
 export interface ProgramPolicy {
+  resources?: { maxTokens: number; reserveTokensPerAttempt: number; finalReserveTokens?: number; unknownUsage: "block" | "allow" };
   allowFencedReplan?: boolean;
   captureScope?: string[];
   id: string; version: string; maxItems: number; concurrency: number; maxAttempts: number;
@@ -58,6 +61,7 @@ export interface ProgramRegistry {
   populations: Record<string, ProgramPopulation>; programs?: Record<string, WorkflowProgramV2>;
 }
 export interface ProgramAssessment {
+  resolutionReceiptIds?: string[];
   receiptId?: string; generation?: number; operationId?: string;
   semanticDigest?: string; inputDigest?: string;
   phase?: "item" | "final"; obligationIds?: string[]; satisfiedObligationIds?: string[]; unsatisfiedObligationIds?: string[];
@@ -78,6 +82,11 @@ export interface ProgramAttempt {
   outcome: "running" | "completed" | "infrastructure_failed" | "invalid_output" | "uncertain" | "canceled_confirmed";
   outputRef?: string; threadId?: string; reason?: string;
   reservation?: { scopes: { id: string; limit: number }[]; status: "held" | "released"; ownerEpoch: string };
+  observations?: Record<string, ProgramWorkerObservation>;
+  usageApplicability?: "not-applicable" | "provider";
+  usageSummary?: ProgramUsageSummary;
+  resourceReservation?: { tokens: number; status: "held" | "released"; phase?: "work" | "final" };
+  recovery?: { directory: string; inputDigest: string; workspaceDigest: string; threadId?: string; terminationObserved?: boolean; generationCompatible?: boolean };
   usage?: unknown;
 }
 export interface ProgramOperationRecord {
@@ -111,6 +120,7 @@ export interface ProgramRunV2 {
   waits: Record<string, { generation: number; deadlineAt?: string; signalId?: string; outputRef?: string }>;
   repairs: Record<string, { semanticDigest: string; inputDigest: string; candidate: ProgramCandidate; rounds: number; assessments: number; infrastructure: number; unchanged: number; repeated: number; priorFindings: string; feedback: unknown; phase: "implement" | "implementation-active" | "assess" | "assessment-active" | "decide" | "accepted" | "exhausted" | "stalled"; assessment?: ProgramAssessment }>;
   collections: Record<string, { seal: string; coverageReceiptId: string | null; generation: number; ids: string[]; acceptedAssessmentIds: string[]; acceptedCandidateIds: string[]; obligationsSatisfied: boolean }>;
+  compositionResolutions?: Record<string, { receiptId: string; candidateId: string; candidateDigest: string; originalCandidateIds: string[]; attemptId: string; operationId: string; generation: number; semanticDigest: string; inputDigest: string; populationDigest: string; acceptanceDigest: string }>;
   resultRef?: string; gateRef?: string; intent?: ProgramApplyIntent; receiptRef?: string;
   acceptedCandidate?: ProgramCandidate;
   scopeResults?: Record<string, { outcomes: { id: string; status: string; reason?: string }[]; status: "completed" | "waiting" | "failed"; resultRef?: string }>;
@@ -212,6 +222,11 @@ export function validateWorkflowProgram(program: WorkflowProgramV2, registry: Pr
   const policy = registryEntry(registry.policies, program.policy), acceptance = registryEntry(registry.acceptance, program.acceptance);
   for (const field of ["maxItems", "concurrency", "maxAttempts", "maxOperations", "maxDepth", "deadlineMs", "maxOutputBytes"] as const) programAssert(Number.isSafeInteger(policy[field]) && policy[field] > 0, `Invalid limit ${field}`);
   programAssert(policy.concurrency <= 32 && policy.maxDepth <= 32 && policy.maxItems <= 10000 && policy.maxAttempts <= 10000 && policy.maxOperations <= 20000 && policy.maxOutputBytes <= 4 * 1024 * 1024, "Physical limits exceeded");
+  if (policy.resources) {
+    const budget = policy.resources;
+    for (const value of [budget.maxTokens, budget.reserveTokensPerAttempt, budget.finalReserveTokens ?? 0]) programAssert(Number.isSafeInteger(value) && value >= 0, "Invalid resource budget");
+    programAssert(budget.maxTokens > 0 && budget.reserveTokensPerAttempt > 0 && (budget.finalReserveTokens ?? 0) <= budget.maxTokens && ["block", "allow"].includes(budget.unknownUsage), "Invalid resource policy");
+  }
   for (const path of [...policy.writeScope, ...acceptance.writeScope, ...(policy.captureScope ?? [])]) programPath(path);
   programAssert(acceptance.criteria.length > 0 && new Set(acceptance.criteria).size === acceptance.criteria.length, "Acceptance criteria required and unique");
   if (program.population) { const population = registryEntry(registry.populations, program.population); programAssert(population.members.length <= policy.maxItems && new Set(population.members).size === population.members.length && population.evidence.length > 0, "Population inventory invalid"); validateVisualPopulation(population); }
@@ -235,7 +250,7 @@ export function validateWorkflowProgram(program: WorkflowProgramV2, registry: Pr
     map: ["items", "key", "coverage", "concurrency", "completion", "quorum", "body", "order"],
     branch: ["condition", "then", "else"], loop: ["initialState", "maxRounds", "body", "next", "until"],
     repair: ["recipe", "entryMode", "initialCandidate", "writeScope", "implement", "review", "checks", "input", "assessmentScope", "evidence", "maxRepairRounds", "maxAssessmentAttempts", "maxInfrastructureAttempts", "progressPolicy"],
-    compose: ["candidates", "onConflict"], gate: ["candidate", "coverage", "authorization"], subworkflow: ["program", "input"],
+    compose: ["candidates", "onConflict", "resolver", "resolverInput", "resolverWriteScope"], gate: ["candidate", "coverage", "authorization"], subworkflow: ["program", "input"],
     waitEvent: ["schema", "type", "correlation", "subject", "timeoutMs"], sequence: ["steps", "result"], parallel: ["steps", "result", "onFailure"],
   };
   kinds.add("sequence"); kinds.add("parallel");
@@ -255,7 +270,8 @@ export function validateWorkflowProgram(program: WorkflowProgramV2, registry: Pr
       if (step.options.completion === "quorum") programAssert(step.options.quorum && typeof step.options.quorum === "object" && Number.isSafeInteger((step.options.quorum as { minAccepted: number }).minAccepted) && (step.options.quorum as { minAccepted: number }).minAccepted > 0, "Quorum minAccepted required");
       else programAssert(step.options.quorum === undefined, "Quorum only applies to quorum completion");
     }
-    if (["agent", "command"].includes(step.kind)) { const executor = registryEntry(registry.executors, step.options.executor as ProgramRef); if (executor.inputSchema) registryEntry(registry.schemas, executor.inputSchema); }
+    if (["agent", "command"].includes(step.kind)) { const executor = registryEntry(registry.executors, step.options.executor as ProgramRef); programAssert(executor.tokenAccounting === undefined || executor.tokenAccounting === "provider" || executor.tokenAccounting === "none" && executor.kind === "command", "Token accounting exemption only applies to owner-declared nonprovider commands"); if (executor.inputSchema) registryEntry(registry.schemas, executor.inputSchema); }
+    if (step.kind === "compose" && step.options.resolver) programAssert(registryEntry(registry.executors, step.options.resolver as ProgramRef).effect === "isolated-write", "Conflict resolver must produce an isolated candidate");
     if (step.kind === "repair") {
       registryEntry(registry.executors, step.options.implement as ProgramRef); registryEntry(registry.executors, step.options.review as ProgramRef);
       programAssert(["implement-first", "assess-first"].includes(String(step.options.entryMode)), "Repair entryMode required");

package/src/forge/agent-fabric/program-observation.ts

@@ -0,0 +1,63 @@
+import { programAssert, programDigest, programValueBytes, type ProgramAttempt } from "./program-contract.ts";
+
+/** Adapter observations are data, not completion or acceptance authority. */
+export interface ProgramWorkerObservation {
+  id: string; type: string; source: string; at: string;
+  usage?: { input_tokens: number; cached_input_tokens?: number; output_tokens: number };
+  semantics?: "incremental" | "cumulative";
+  metadata?: Record<string, unknown>;
+}
+export interface ProgramUsageSummary {
+  inputTokens: number; outputTokens: number; cachedInputTokens: number;
+  totalTokens: number; certainty: "observed" | "unknown" | "not-applicable";
+}
+export function recordProgramObservation(attempt: ProgramAttempt, observation: ProgramWorkerObservation): void {
+  programValueBytes(observation, 16384, 128);
+  programAssert(typeof observation.id === "string" && observation.id.length > 0 && observation.id.length <= 256 &&
+    typeof observation.type === "string" && observation.type.length <= 128 && typeof observation.source === "string" && observation.source.length <= 128 &&
+    Number.isFinite(Date.parse(observation.at)), "Invalid worker observation");
+  programAssert(observation.semantics === undefined || ["incremental", "cumulative"].includes(observation.semantics), "Invalid usage semantics");
+  if (observation.usage) {
+    const usage = observation.usage;
+    programAssert(Number.isSafeInteger(usage.input_tokens) && usage.input_tokens >= 0 && Number.isSafeInteger(usage.output_tokens) && usage.output_tokens >= 0, "Usage requires nonnegative safe input/output counters");
+    programAssert(usage.cached_input_tokens === undefined || Number.isSafeInteger(usage.cached_input_tokens) && usage.cached_input_tokens >= 0 && usage.cached_input_tokens <= usage.input_tokens, "Invalid cached usage counter");
+  }
+  const observations = attempt.observations ??= {};
+  if (observations[observation.id]) { programAssert(programDigest(observations[observation.id]) === programDigest(observation), "Observation identity changed"); return; }
+  programAssert(Object.keys(observations).length < 1024, "Attempt observation budget exceeded");
+  const next = { ...attempt, observations: { ...observations, [observation.id]: structuredClone(observation) } };
+  const summary = summarizeProgramUsage(next);
+  observations[observation.id] = next.observations[observation.id];
+  attempt.usageSummary = summary;
+}
+export function summarizeProgramUsage(attempt: ProgramAttempt): ProgramUsageSummary {
+  let inputTokens = 0, outputTokens = 0, cachedInputTokens = 0, observed = false;
+  const cumulative = new Map<string, NonNullable<ProgramWorkerObservation["usage"]>>();
+  const semantics = new Map<string, string>();
+  for (const observation of Object.values(attempt.observations ?? {})) {
+    if (!observation.usage) continue; observed = true;
+    const mode = observation.semantics ?? "incremental";
+    programAssert(!semantics.has(observation.source) || semantics.get(observation.source) === mode, "Usage source mixes cumulative and incremental semantics");
+    semantics.set(observation.source, mode);
+    if (observation.semantics === "cumulative") {
+      const previous = cumulative.get(observation.source);
+      cumulative.set(observation.source, { input_tokens: Math.max(previous?.input_tokens ?? 0, observation.usage.input_tokens), output_tokens: Math.max(previous?.output_tokens ?? 0, observation.usage.output_tokens), cached_input_tokens: Math.max(previous?.cached_input_tokens ?? 0, observation.usage.cached_input_tokens ?? 0) });
+    } else { inputTokens += observation.usage.input_tokens; outputTokens += observation.usage.output_tokens; cachedInputTokens += observation.usage.cached_input_tokens ?? 0; }
+  }
+  for (const usage of cumulative.values()) { inputTokens += usage.input_tokens; outputTokens += usage.output_tokens; cachedInputTokens += usage.cached_input_tokens ?? 0; }
+  if (!observed && attempt.usage && typeof attempt.usage === "object") {
+    const usage = attempt.usage as { input_tokens?: number; output_tokens?: number; cached_input_tokens?: number };
+    if (Number.isSafeInteger(usage.input_tokens) && Number.isSafeInteger(usage.output_tokens) && usage.input_tokens! >= 0 && usage.output_tokens! >= 0) {
+      inputTokens = usage.input_tokens!; outputTokens = usage.output_tokens!;
+      cachedInputTokens = Number.isSafeInteger(usage.cached_input_tokens) && usage.cached_input_tokens! >= 0 ? usage.cached_input_tokens! : 0; observed = true;
+    }
+  }
+  programAssert([inputTokens, outputTokens, cachedInputTokens, inputTokens + outputTokens].every(value => Number.isSafeInteger(value) && value >= 0), "Usage aggregate exceeds safe integer range");
+  return { inputTokens, outputTokens, cachedInputTokens, totalTokens: inputTokens + outputTokens, certainty: observed ? "observed" : attempt.usageApplicability === "not-applicable" ? "not-applicable" : "unknown" };
+}
+/** Held reservations and unknown completed calls remain liabilities after owner restart. */
+export function programResourceLiability(attempt: ProgramAttempt): number {
+  const usage = summarizeProgramUsage(attempt);
+  const reserve = attempt.resourceReservation?.tokens ?? 0;
+  return usage.totalTokens + (attempt.resourceReservation?.status === "held" ? Math.max(0, reserve - usage.totalTokens) : usage.certainty === "unknown" ? reserve : 0);
+}

package/src/forge/agent-fabric/program-runtime-options.ts

@@ -0,0 +1,23 @@
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ProgramError } from "./program-contract.ts";
+
+export interface ProgramRuntimeOptions { ownerCapacity?: number; ownerMaxTokens?: number }
+
+/** Owner configuration is local trusted configuration, never a workflow request override. */
+export function readProgramRuntimeOptions(root: string): ProgramRuntimeOptions {
+  const directory = join(root, ".forge"), path = join(directory, "fabric-runtime.json");
+  if (lstatSync(directory, { throwIfNoEntry: false })?.isSymbolicLink()) throw new ProgramError("AF_PROGRAM_INVALID", "Runtime configuration directory cannot be a symbolic link");
+  const stat = lstatSync(path, { throwIfNoEntry: false });
+  if (!stat) return {};
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16 * 1024) throw new ProgramError("AF_PROGRAM_INVALID", "Runtime configuration must be a regular file up to 16 KiB");
+  const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ProgramError("AF_PROGRAM_INVALID", "Runtime configuration must be an object");
+  const record = value as Record<string, unknown>;
+  if (record.schemaVersion !== 1 || Object.keys(record).some(key => !["schemaVersion", "ownerCapacity", "ownerMaxTokens"].includes(key))) throw new ProgramError("AF_PROGRAM_INVALID", "Unsupported runtime configuration");
+  for (const key of ["ownerCapacity", "ownerMaxTokens"] as const) {
+    const number = record[key];
+    if (number !== undefined && (typeof number !== "number" || !Number.isSafeInteger(number) || number < 1 || (key === "ownerCapacity" && number > 32))) throw new ProgramError("AF_PROGRAM_INVALID", `Invalid ${key}`);
+  }
+  return { ownerCapacity: record.ownerCapacity as number | undefined, ownerMaxTokens: record.ownerMaxTokens as number | undefined };
+}

package/src/forge/agent-fabric/program-scheduler.ts

@@ -8,8 +8,15 @@ export class ProgramActivityScheduler {
   private active = new Map<string, number>();
   private scopes = new Map<string, number>();
   private count = 0;
-  private lastRun = "";
-  constructor(readonly ownerLimit = 4) { programAssert(Number.isSafeInteger(ownerLimit) && ownerLimit > 0 && ownerLimit <= 32, "Invalid owner capacity"); }
+  private runOrder: string[] = [];
+  private cursor = 0;
+  private capacity: number;
+  get ownerLimit(): number { return this.capacity; }
+  constructor(ownerLimit = 4) { programAssert(Number.isSafeInteger(ownerLimit) && ownerLimit > 0 && ownerLimit <= 32, "Invalid owner capacity"); this.capacity = ownerLimit; }
+  setOwnerCapacity(ownerLimit: number): void {
+    programAssert(Number.isSafeInteger(ownerLimit) && ownerLimit > 0 && ownerLimit <= 32, "Invalid owner capacity");
+    this.capacity = ownerLimit; this.drain();
+  }
   restore(runId: string, scopes: ActivityScope[]): () => void {
     this.count++; this.active.set(runId, (this.active.get(runId) ?? 0) + 1);
     for (const scope of scopes) this.scopes.set(scope.id, (this.scopes.get(scope.id) ?? 0) + 1);
@@ -20,19 +27,31 @@ export class ProgramActivityScheduler {
     return new Promise((resolve, reject) => {
       const ticket: Ticket = { runId, runLimit, scopes, resolve, reject, signal, abort: () => { this.tickets = this.tickets.filter(entry => entry !== ticket); reject(new Error("Activity admission canceled")); this.drain(); } };
       if (signal.aborted) { ticket.abort(); return; }
-      signal.addEventListener("abort", ticket.abort, { once: true }); this.tickets.push(ticket); this.drain();
+      signal.addEventListener("abort", ticket.abort, { once: true }); this.tickets.push(ticket);
+      if (!this.runOrder.includes(runId)) this.runOrder.push(runId);
+      this.drain();
     });
   }
   private drain(): void {
     while (this.count < this.ownerLimit) {
       const eligible = this.tickets.filter(ticket => !ticket.signal.aborted && (this.active.get(ticket.runId) ?? 0) < ticket.runLimit && ticket.scopes.every(scope => (this.scopes.get(scope.id) ?? 0) < scope.limit));
-      const ticket = eligible.find(entry => entry.runId !== this.lastRun) ?? eligible[0]; if (!ticket) return;
+      let ticket: Ticket | undefined;
+      for (let offset = 0; offset < this.runOrder.length; offset++) {
+        const index = (this.cursor + offset) % this.runOrder.length;
+        ticket = eligible.find(entry => entry.runId === this.runOrder[index]);
+        // Keep the next ordinal unwrapped: newly queued runs after a lone run
+        // must get their turn before the previously admitted run repeats.
+        if (ticket) { this.cursor = index + 1; break; }
+      }
+      if (!ticket) return;
       this.tickets.splice(this.tickets.indexOf(ticket), 1); ticket.signal.removeEventListener("abort", ticket.abort);
-      this.lastRun = ticket.runId; this.count++; this.active.set(ticket.runId, (this.active.get(ticket.runId) ?? 0) + 1);
+      this.count++; this.active.set(ticket.runId, (this.active.get(ticket.runId) ?? 0) + 1);
       for (const scope of ticket.scopes) this.scopes.set(scope.id, (this.scopes.get(scope.id) ?? 0) + 1);
       let released = false;
       ticket.resolve(() => { if (released) return; released = true; this.count--; this.active.set(ticket.runId, this.active.get(ticket.runId)! - 1); for (const scope of ticket.scopes) this.scopes.set(scope.id, this.scopes.get(scope.id)! - 1); this.drain(); });
     }
   }
-  snapshot(): { active: number; queued: number; ownerLimit: number } { return { active: this.count, queued: this.tickets.length, ownerLimit: this.ownerLimit }; }
+  snapshot(): { active: number; queued: number; ownerLimit: number; runs: { runId: string; active: number; queued: number }[] } {
+    return { active: this.count, queued: this.tickets.length, ownerLimit: this.ownerLimit, runs: [...new Set([...this.active.keys(), ...this.tickets.map(ticket => ticket.runId)])].map(runId => ({ runId, active: this.active.get(runId) ?? 0, queued: this.tickets.filter(ticket => ticket.runId === runId).length })) };
+  }
 }