forgeos 0.1.0-alpha.70 → 0.1.0-alpha.72

package/examples/agent-fabric-v2/README.md

@@ -52,3 +52,19 @@ The owner registry is project configuration, not workflow input. `cache: none` i
 default. Only commands declared to depend entirely on their captured workspace inputs
 may opt into `cache: workspace`; the owner must account for external inputs. SDK output
 reuse is disabled until its effective instruction closure can be attested.
+
+## Current workflow runtime and UI example
+
+`ui-audit.workflow.ts` uses the current operatorVersion 2 architecture directly. `run-ui-fixture.ts` is a disposable local integration example: twenty HTML pages, three known defects, command-only agents, item and final checks, capture receipts, compose and gate. Run `node bin/forge-bun.mjs run examples/agent-fabric-v2/run-ui-fixture.ts` from the Forge checkout. It sets the no-LLM fuse and never applies to a user project.
+
+`runUiFixture(count, defects, browserPath?)` also accepts an explicit Chromium/Edge executable for real local headless screenshots; the default uses valid PNG fixtures. Both reviewers are deterministic checks of fixture attributes, not visual AI evaluation. The worker's cooperative process capability must be owner-authorized.
+
+The static lowerer and TS author API share the same example including `as const`, `satisfies`, typed refs and scoped checks. Arbitrary TS execution is unsupported. Legacy file-conversion example remains a separate usage example, not a compatibility interpreter. See docs/agent-fabric-programs.md for all fifty author constructors and fifteen controls.
+
+## Typed reusable subworkflow and visual cases
+
+`item-child.workflow.ts` is a finite typed inspection program. Lower it and register its IR as `inspect-item@v2`; the root `map-child.workflow.ts` calls it with explicit input and a map quota of one. Supply owner schemas `path@v2` (object path:string), `inspection@v2` (object ok:boolean), `any@v2`, policy `local@v2`, acceptance `data@v2`, and executor `inspect@v2` with inputSchema path@v2/output schema inspection@v2. These are templates, not automatically installed executors. Child quotas/cancellation inherit from the root; keep the same policy/acceptance.
+
+`visual-population.json` demonstrates separate desktop/ready and mobile/error cases for one route. Replace the baseline placeholder with the owner-captured digest and enumerate all required scenarios. Matching itemKey alone cannot close a visual case when route, viewport, state or dimensions differ. Image header validation is not proof of visual correctness.
+
+Use program-explain to retrieve the template graph, observed expansions and a Mermaid diagram. Format 3 runs live in program-runs-v3; older checkpoint directories are preserved and not loaded.

package/examples/agent-fabric-v2/item-child.workflow.ts

@@ -0,0 +1,11 @@
+import { defineWorkflow, schemaRef, policyRef, acceptanceRef, executorRef, workflowInput, agent, output } from "forgeos/agent-fabric/workflows";
+
+// Register this IR as inspect-item@v2. Owner schemas/executor remain authoritative.
+const inspect = agent("inspect", {
+  executor: executorRef<{ path: string }, { ok: boolean }>("inspect", "v2"),
+  input: workflowInput<{ path: string }>()
+});
+export default defineWorkflow({
+  id: "inspect-item", version: 2, mode: "data", inputSchema: schemaRef("path", "v2"), outputSchema: schemaRef("inspection", "v2"),
+  policy: policyRef("local", "v2"), acceptance: acceptanceRef("data", "v2"), steps: [inspect], result: output(inspect)
+});

package/examples/agent-fabric-v2/map-child.workflow.ts

@@ -0,0 +1,10 @@
+import { defineWorkflow, schemaRef, policyRef, acceptanceRef, programRef, map, subworkflow, item, field, output } from "forgeos/agent-fabric/workflows";
+
+export default defineWorkflow({
+  id: "inspect-files", version: 2, mode: "data", inputSchema: schemaRef("any", "v2"), outputSchema: schemaRef("any", "v2"),
+  policy: policyRef("local", "v2"), acceptance: acceptanceRef("data", "v2"),
+  steps: [map("files", {
+    items: [{ path: "src/a.ts" }, { path: "src/b.ts" }], key: field(item(), "path"), concurrency: 1, completion: "all-required",
+    body: subworkflow("inspect", { program: programRef<{ path: string }, { ok: boolean }>("inspect-item", "v2"), input: item<{ path: string }>() })
+  })], result: output("files")
+});

package/examples/agent-fabric-v2/migrate.workflow.ts

@@ -1,7 +1,7 @@
 import { defineWorkflow, schemaRef, policyRef, acceptanceRef, populationRef, executorRef, recipeRef, agent, map, field, item, output, population, coverageFor, repair, candidateFromBaseline, compose, acceptedCandidates, outputCandidate, acceptedCandidate, gate, coverageReceipt } from "forgeos/agent-fabric/workflows";
 
 const recipe = {
-  recipe: recipeRef("repair", "v1"),
+  recipe: recipeRef("repair", "v2"),
   implement: executorRef("migrate", "v1"), review: executorRef("review", "v1"),
   checks: ["check@v1"], maxRepairRounds: 3, maxAssessmentAttempts: 6,
   maxInfrastructureAttempts: 2,

package/examples/agent-fabric-v2/run-ui-fixture.ts

@@ -0,0 +1,48 @@
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ProgramRunService } from "../../src/forge/agent-fabric/program-service.ts";
+import { programDigest, type ProgramRegistry, type ProgramRunV2 } from "../../src/forge/agent-fabric/program-contract.ts";
+import { lowerWorkflowSource, schemaRef } from "../../src/forge/agent-fabric/program-dsl.ts";
+
+export async function runUiFixture(count = 20, defects = [2, 9, 17], browserPath?: string) {
+  const root = await mkdtemp(join(tmpdir(), "forge-ui-fixture-"));
+  let service: ProgramRunService | undefined;
+  const startedAt = performance.now();
+  try {
+    await mkdir(join(root, "src")); await mkdir(join(root, ".forge"));
+    for (let index = 0; index < count; index++) await writeFile(join(root, "src", `ui-${String(index).padStart(2, "0")}.html`), `<!doctype html><html><title>UI ${index}</title><body data-fixture="${defects.includes(index) ? "bad" : "good"}"><h1>Local fixture ${index}</h1></body></html>`);
+    for (const args of [["init", "--quiet"], ["add", "src"], ["-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "--quiet", "-m", "UI fixture baseline"]]) {
+      const result = spawnSync("git", args, { cwd: root, encoding: "utf8", windowsHide: true }); if (result.status) throw new Error(result.stderr);
+    }
+    const registry: ProgramRegistry = { schemas: { "any@v2": {} }, executors: {}, policies: {}, acceptance: {}, populations: {} };
+    const worker = fileURLToPath(new URL("./ui-fixture-worker.cjs", import.meta.url));
+    for (const id of ["discover", "capture", "implement", "review", "local-check", "global-check"]) registry.executors[`${id}@v2`] = {
+      id, version: "v2", kind: "command", effect: id === "implement" ? "isolated-write" : "read", role: id === "implement" ? "implementer" : id === "review" ? "reviewer" : "investigator",
+      argv: [process.execPath, worker, id, ...(id === "capture" && browserPath ? [browserPath] : [])], timeoutMs: id === "capture" && browserPath ? 120000 : 10000, writeScope: id === "implement" ? ["src"] : [], network: "host", isolation: "cooperative", schema: schemaRef("any", "v2")
+    };
+    registry.policies["local@v2"] = { id: "local", version: "v2", concurrency: 4, maxItems: 100, maxAttempts: 500, maxOperations: 2000, maxDepth: 12, deadlineMs: 240000, maxOutputBytes: 4 * 1024 * 1024, writeScope: ["src"], executors: Object.keys(registry.executors), allowNetwork: true, allowCooperativeCommands: true };
+    registry.acceptance["ui@v2"] = { id: "ui", version: "v2", criteria: ["Known fixture attributes are correct"], requireReview: true, allowNoWork: false, writeScope: ["src"], requiredChecks: [],
+      requiredChecksByScope: { item: ["local-check@v2"], final: ["global-check@v2"] }, assessmentBindings: { page: "item", final: "final" },
+      obligations: [{ id: "layout", scope: "item", criteria: ["known fixture constraint"], requiredEvidence: ["capture"] }, { id: "integration", scope: "final", criteria: ["all pages correct together"] }] };
+    registry.populations["pages@v2"] = { id: "pages", version: "v2", members: [], baselineDigest: "owner-capture", inventoryRoots: ["src"], extensions: [".html"], exclusions: [], allowNoWork: false, evidence: "owner filesystem inventory" };
+    await writeFile(join(root, ".forge/fabric-programs.json"), JSON.stringify(registry));
+    const source = await readFile(new URL("./ui-audit.workflow.ts", import.meta.url), "utf8"), program = lowerWorkflowSource(source);
+    service = await ProgramRunService.open(root);
+    const initial = await service.execute("program-start", { requestId: "ui-fixture", program, input: {} }) as ProgramRunV2;
+    let run: ProgramRunV2;
+    do { await new Promise(resolve => setTimeout(resolve, 20)); run = (await service.store.read(initial.runId))!; } while (run.status === "executing");
+    if (run.status !== "acceptance-ready") throw new Error(`UI fixture failed: ${run.status}: ${run.reason}`);
+    const assessment = Object.values(run.assessments).find(receipt => receipt.phase === "final")!;
+    const implementations = Object.values(run.attempts).filter(attempt => attempt.operationId.endsWith("/implement"));
+    const beforeApply = await readFile(join(root, "src", `ui-${String(defects[0] ?? 0).padStart(2, "0")}.html`), "utf8");
+    const report = { datasetDigest: programDigest({ count, defects }), pages: count, knownDefects: defects.length, implementations: implementations.length, attempts: run.totalAttempts,
+      captures: Object.keys(run.artifactRecords ?? {}).length, finalObligations: assessment.satisfiedObligationIds?.length, finalCaptures: assessment.evidenceRefs?.length,
+      destinationPreserved: beforeApply.includes(`data-fixture="${defects.length ? "bad" : "good"}"`), llmCalls: 0, elapsedMs: Math.round(performance.now() - startedAt), storage: service.store.metrics,
+      captureMode: browserPath ? "local-headless-browser" : "png-fixture", limitations: [browserPath ? "Local browser rendering; no visual model evaluation" : "PNG fixtures; no browser rendering or visual model evaluation", "Cooperative command isolation", "No automatic apply; no Claude benchmark"] };
+    return report;
+  } finally { await service?.close(); await rm(root, { recursive: true, force: true }); }
+}
+if (import.meta.main) { process.env.FORGE_FABRIC_TEST_MODE = "1"; console.log(JSON.stringify(await runUiFixture(), null, 2)); }

package/examples/agent-fabric-v2/templates/README.md

@@ -0,0 +1,46 @@
+# Owner-bound authoring templates
+
+These JSON requests select the review, bugfix and migration templates. `program-author`
+validates references against the owner's registry and returns a proposal without running
+workers, replacing policies, applying changes or spending model tokens. Start is a
+separate action. The supplied registry's workers and migration criteria are text-file
+fixtures; replace them with real project contracts and verification commands for coding.
+
+Review begins with assessment and requests an empty write scope. A negative assessment
+cannot change files; bounded follow-up may end exhausted or stalled. Bugfix assesses
+first, avoiding edits to an already accepted baseline. Migration consumes
+`input.items: [{id, allowedPaths}]`, seals coverage against the owner population, repairs
+each item only after a negative assessment, composes accepted candidates and assesses the integrated candidate before gate. An optional owner-authorized resolver can be selected in migration options; its candidate requires fresh final population evaluation.
+
+Each repair preserves mandatory checks. Scoped acceptance must bind `component` to
+`item` and `assessment` to `final`; templates do not mutate these owner bindings.
+Human approval, when required, remains outstanding at the gate. Apply remains separate.
+`program-author-types` exports owner schema/executor declarations for author assistance;
+runtime validation is still authoritative.
+
+## Independent benchmark reports
+
+`program-benchmark.ts` defines a versioned observation report. Record identity of runtime,
+model, tools, context, contracts and budget for each task. Queue/preparation/execution/
+capture/persistence/integration timings are optional observations; omitted means absent,
+not zero. Consumption is observed, estimated or unknown. Independent evaluation requires
+an assessor and criteria digest fixed independently of the implementer. Owner gate
+approval alone does not qualify as external success.
+
+Read and summarize an already collected report with:
+
+```sh
+node --import tsx scripts/summarize-fabric-benchmark.mjs report.json
+```
+
+This command only validates data. It does not run workflows, providers or benchmarks.
+The existing deterministic benchmark scripts remain runtime references and do not prove
+superiority over Claude or coding quality. Real evaluations are a separate explicit run.
+
+## CI scope
+
+PRs changing only explicitly covered authoring, observation, benchmark or adapter modules use a small critical suite. Missing critical files fail closed.
+Core owner/store/workspace/services, shared or unknown paths and main runs retain the full Agent Fabric suite. Workflow
+contracts, typecheck, compiler checks, lint and the separate security gate remain.
+Ubuntu/Node 22 CLI smoke runs once in verify; the matrix adds Windows 22 for PRs and
+Ubuntu 24 on main. Manual CI includes macOS.

package/examples/agent-fabric-v2/templates/bugfix.json

@@ -0,0 +1,12 @@
+{
+  "kind": "bugfix",
+  "options": {
+    "id": "bugfix-workflow",
+    "inputSchema": { "id": "input", "version": "v1" },
+    "outputSchema": { "id": "gate", "version": "v1" },
+    "policy": { "id": "local", "version": "v1" },
+    "acceptance": { "id": "migration", "version": "v1" },
+    "implement": { "id": "migrate", "version": "v1" },
+    "review": { "id": "review", "version": "v1" }
+  }
+}

package/examples/agent-fabric-v2/templates/migration.json

@@ -0,0 +1,13 @@
+{
+  "kind": "migration",
+  "options": {
+    "id": "migration-workflow",
+    "inputSchema": { "id": "discovery", "version": "v1" },
+    "outputSchema": { "id": "gate", "version": "v1" },
+    "policy": { "id": "local", "version": "v1" },
+    "acceptance": { "id": "migration", "version": "v1" },
+    "implement": { "id": "migrate", "version": "v1" },
+    "review": { "id": "review", "version": "v1" },
+    "population": { "id": "files", "version": "v1" }
+  }
+}

package/examples/agent-fabric-v2/templates/review.json

@@ -0,0 +1,12 @@
+{
+  "kind": "review",
+  "options": {
+    "id": "review-workflow",
+    "inputSchema": { "id": "input", "version": "v1" },
+    "outputSchema": { "id": "gate", "version": "v1" },
+    "policy": { "id": "local", "version": "v1" },
+    "acceptance": { "id": "migration", "version": "v1" },
+    "implement": { "id": "migrate", "version": "v1" },
+    "review": { "id": "review", "version": "v1" }
+  }
+}

package/examples/agent-fabric-v2/ui-audit.workflow.ts

@@ -0,0 +1,28 @@
+import { defineWorkflow, schemaRef, executorRef, policyRef, acceptanceRef, populationRef, recipeRef, agent, map, repair, compose, gate, field, item, output, population, coverageFor, candidateFromBaseline, acceptedCandidates, outputCandidate, acceptedCandidate, coverageReceipt, type WorkflowOptions } from "forgeos/agent-fabric/workflows";
+
+const repairPolicy = {
+  recipe: recipeRef("repair", "v2"), implement: executorRef("implement", "v2"), review: executorRef("review", "v2"), evidence: [executorRef("capture", "v2")],
+  entryMode: "assess-first", maxRepairRounds: 3, maxAssessmentAttempts: 6, maxInfrastructureAttempts: 2,
+  progressPolicy: { unchangedCandidateRounds: 2, repeatedFindingsRounds: 2 }
+} as const;
+const itemRepair = {
+  ...repairPolicy, evidence: [executorRef("capture", "v2")], assessmentScope: "item", checks: ["local-check@v2"], initialCandidate: candidateFromBaseline(item()), writeScope: field(item(), "allowedPaths")
+} satisfies WorkflowOptions["repair"];
+
+export default defineWorkflow({
+  id: "ui-audit", version: 1, operatorVersion: 2, mode: "candidate", inputSchema: schemaRef("any", "v2"), outputSchema: schemaRef("any", "v2"),
+  policy: policyRef("local", "v2"), acceptance: acceptanceRef("ui", "v2"), population: populationRef("pages", "v2"),
+  steps: [
+    agent("discover", { executor: executorRef("discover", "v2"), input: {} }),
+    map("pages", {
+      items: field(output("discover"), "items"), key: field(item(), "id"), coverage: coverageFor(population(), output("discover")), completion: "all-required", concurrency: 4,
+      body: repair("page", itemRepair)
+    }),
+    compose("integrated", { candidates: acceptedCandidates("pages"), onConflict: "needs-resolution" }),
+    repair("final", {
+      ...repairPolicy, evidence: [executorRef("capture", "v2")], assessmentScope: "final", checks: ["global-check@v2"],
+      initialCandidate: outputCandidate("integrated"), writeScope: ["src"]
+    }),
+    gate("ready", { candidate: acceptedCandidate("final"), coverage: coverageReceipt("pages") })
+  ], result: output("ready")
+});

package/examples/agent-fabric-v2/ui-fixture-worker.cjs

@@ -0,0 +1,36 @@
+// Deterministic fixture worker. Does not call an LLM or make network requests.
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { pathToFileURL } = require('node:url');
+const role = process.argv[2];
+const data = JSON.parse(fs.readFileSync(process.env.FORGE_PROGRAM_INPUT_PATH, 'utf8'));
+const context = data.assessmentContext;
+const inventory = () => fs.readdirSync('src').filter(name => name.endsWith('.html')).sort().map(name => ({ id: 'src/' + name, allowedPaths: ['src/' + name] }));
+const items = data.workItem ? [data.workItem] : inventory();
+const invalid = () => items.filter(item => !fs.readFileSync(item.id, 'utf8').includes('data-fixture="good"'));
+let result;
+if (role === 'discover') result = { items: inventory() };
+else if (role === 'implement') {
+  for (const item of invalid()) fs.writeFileSync(item.id, fs.readFileSync(item.id, 'utf8').replace('data-fixture="bad"', 'data-fixture="good"'));
+  result = { summary: 'Repaired known fixture attributes' };
+} else if (role === 'review') {
+  const findings = invalid().map(item => ({ itemKey: item.id, reason: 'Known deterministic fixture defect' }));
+  result = { verdict: findings.length ? 'changes_requested' : 'approved', findings, coveredObligationIds: context.obligationIds };
+} else if (role === 'local-check' || role === 'global-check') result = { passed: invalid().length === 0 };
+else if (role === 'capture') {
+  // A valid PNG fixture proves artifact transport/binding, not browser rendering.
+  const bytes = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aGfoAAAAASUVORK5CYII=', 'base64');
+  result = { evidenceArtifacts: items.map((item, index) => {
+    const name = 'capture-' + index + '.png', file = path.join(process.env.FORGE_PROGRAM_SCRATCH_DIRECTORY, name);
+    const browser = process.argv[3];
+    if (browser) {
+      const profile = path.join(process.env.FORGE_PROGRAM_SCRATCH_DIRECTORY, 'profile-' + index);
+      const rendered = spawnSync(browser, ['--headless', '--disable-gpu', '--disable-extensions', '--disable-background-networking', '--no-first-run', '--no-default-browser-check', '--hide-scrollbars', '--window-size=800,600', '--user-data-dir=' + profile, '--screenshot=' + file, pathToFileURL(path.resolve(item.id)).href], { windowsHide: true, timeout: 15000, stdio: 'pipe' });
+      if (rendered.error || rendered.status !== 0 || !fs.existsSync(file)) throw new Error('Headless browser capture failed');
+    } else fs.writeFileSync(file, bytes);
+    const image = fs.readFileSync(file), width = image.readUInt32BE(16), height = image.readUInt32BE(20);
+    return { path: name, itemKey: item.id, buildDigest: data.candidateDigest, environmentRef: context.environmentRef, mime: 'image/png', width, height, route: '/' + item.id, viewport: width + 'x' + height, state: browser ? 'local-browser-render' : 'deterministic-fixture' };
+  }) };
+} else throw new Error('Unknown fixture role');
+console.log(JSON.stringify(result));

package/examples/agent-fabric-v2/visual-population.json

@@ -0,0 +1,13 @@
+{
+  "id": "checkout-cases",
+  "version": "v2",
+  "members": ["checkout-desktop-ready", "checkout-mobile-error"],
+  "exclusions": [],
+  "baselineDigest": "OWNER_MUST_SUPPLY_CAPTURED_BASELINE_DIGEST",
+  "evidence": "Owner catalog of required checkout scenarios; extend explicitly for every route, viewport and state",
+  "allowNoWork": false,
+  "visualCases": [
+    { "itemKey": "checkout-desktop-ready", "route": "/checkout", "viewport": "desktop", "state": "ready", "width": 1440, "height": 900 },
+    { "itemKey": "checkout-mobile-error", "route": "/checkout", "viewport": "mobile", "state": "error", "width": 390, "height": 844 }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.70",
+  "version": "0.1.0-alpha.72",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,7 @@
     "bin/",
     "scripts/field-test-forgeos.mjs",
     "scripts/install-agent-fabric-skill.mjs",
+    "scripts/summarize-fabric-benchmark.mjs",
     ".agents/skills/forge-agent-fabric/",
     "docs/cair-protocol.md",
     "docs/forge-protocol.md",
@@ -26,6 +27,11 @@
     "docs/architecture/agent-fabric/WORKFLOW_PROGRAM_V2_PLAN.md",
     "docs/architecture/agent-fabric/WORKFLOW_PROGRAM_V2_ADR.md",
     "docs/architecture/agent-fabric/WORKFLOW_PROGRAM_V2_EVIDENCE.md",
+    "docs/architecture/agent-fabric/WORKFLOW_PROGRAM_V2_CORRECTIONS.md",
+    "docs/architecture/agent-fabric/WORKFLOW_PROGRAM_V2_CORRECTIONS_EVIDENCE.md",
+    "docs/architecture/agent-fabric/WORKFLOW_PROGRAM_COMPETITIVE_PLAN.md",
+    "docs/architecture/agent-fabric/WORKFLOW_PROGRAM_COMPETITIVE_EVIDENCE.md",
+    "docs/architecture/agent-fabric/WORKFLOW_PROGRAM_COMPETITIVE_REVIEW.md",
     "examples/go-billing/",
     "examples/agent-fabric-v2/",
     "examples/java-billing/",

package/scripts/summarize-fabric-benchmark.mjs

@@ -0,0 +1,6 @@
+import { readFile } from "node:fs/promises";
+import { summarizeBenchmarkReport, compareBenchmarkReports } from "../src/forge/agent-fabric/program-benchmark.ts";
+const path = process.argv[2];
+if (!path) throw new Error("Usage: node --import tsx scripts/summarize-fabric-benchmark.mjs REPORT.json [COUNTERPART.json]");
+const report = JSON.parse(await readFile(path, "utf8"));
+console.log(JSON.stringify(process.argv[3] ? compareBenchmarkReports(report, JSON.parse(await readFile(process.argv[3], "utf8"))) : summarizeBenchmarkReport(report), null, 2));

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.70","releaseId":"forgeos@0.1.0-alpha.70+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.72","releaseId":"forgeos@0.1.0-alpha.72+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.70 input=c9c2b146d0cb312a96b8d2ba635c2e26634645a24895b1d003e2f65ae17a3e02 content=0b7cd4e138639e7ccdf2e6723e47f5d231465b6da9b553bb37ba21b68ceb2c5b
+// @forge-generated generator=0.1.0-alpha.72 input=4096e19589f57b9568accde0ae34aa0782c1598f54261e161e1ff5ac7cc857b9 content=d749e9d32ae5d270f7ba002ac58ee67da6d8e1a0dd704ad5e9a05a4decf4d59f
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.70",
-  "releaseId": "forgeos@0.1.0-alpha.70+unknown",
+  "packageVersion": "0.1.0-alpha.72",
+  "releaseId": "forgeos@0.1.0-alpha.72+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/agent-fabric/claude-program-worker.ts

@@ -0,0 +1,95 @@
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { ProgramWorkerObservation } from "./program-observation.ts";
+
+/** The CLI is cooperative: neither network denial nor process-tree termination is attested. */
+export const claudeProgramCapabilities = Object.freeze({ adapter: "claude", protocol: "stream-json", minimumVersion: "2.1.259", isolation: "cooperative", network: "host", structuredOutput: true, threadResume: true, nativeImages: false, hardTokenLimit: false, processTreeTermination: false });
+export function validateClaudeProgramVersion(output: string): string {
+  const match = /^\s*(\d+)\.(\d+)\.(\d+)(?:\s|$)/.exec(output);
+  if (!match) throw new Error("Claude CLI version identity unavailable");
+  const [major, minor, patch] = match.slice(1).map(Number);
+  if (![major, minor, patch].every(Number.isSafeInteger) || major! < 2 || major === 2 && (minor! < 1 || minor === 1 && patch! < 259)) throw new Error("Claude CLI requires version >=2.1.259 for restricted unattended protocol");
+  return `${major}.${minor}.${patch}`;
+}
+export interface ClaudeProgramInput {
+  binary: string; cwd: string; prompt: string; schema: unknown; model?: string; threadId?: string;
+  writable: boolean; signal: AbortSignal; environment: NodeJS.ProcessEnv;
+  onThread: (id: string) => Promise<void>;
+  onEvent: (event: Omit<ProgramWorkerObservation, "id" | "at">) => Promise<void>;
+}
+export function claudeProgramArguments(input: Pick<ClaudeProgramInput, "schema" | "model" | "threadId" | "writable">): string[] {
+  const tools = input.writable ? "Read,Glob,Grep,Edit,Write" : "Read,Glob,Grep";
+  return ["--print", "--output-format", "stream-json", "--verbose", "--json-schema", JSON.stringify(input.schema),
+    "--restricted", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--disable-slash-commands",
+    "--settings", '{"disableAllHooks":true}', "--setting-sources", "", "--permission-mode", "dontAsk", "--permission-prompts", "none",
+    "--tools", tools, "--allowedTools", tools, ...(input.model ? ["--model", input.model] : []), ...(input.threadId ? ["--resume", input.threadId] : [])];
+}
+/** Parse only the documented operational envelope; never persist assistant/tool text. */
+export function claudeProgramResult(event: Record<string, unknown>): { data: unknown; usage?: ProgramWorkerObservation["usage"] } {
+  if (event.type !== "result" || event.subtype !== "success" || event.is_error === true || !("structured_output" in event)) throw new Error("Claude structured completion not observed");
+  return { data: event.structured_output, usage: claudeProgramUsage(event) };
+}
+export function claudeProgramUsage(event: Record<string, unknown>): ProgramWorkerObservation["usage"] | undefined {
+  const raw = event.usage as Record<string, unknown> | undefined;
+  if (!raw) return undefined;
+  for (const key of ["input_tokens", "output_tokens"]) if (!Number.isSafeInteger(raw[key]) || (raw[key] as number) < 0) throw new Error("Invalid Claude usage counters");
+  for (const key of ["cache_read_input_tokens", "cache_creation_input_tokens"]) if (raw[key] !== undefined && (!Number.isSafeInteger(raw[key]) || (raw[key] as number) < 0)) throw new Error("Invalid Claude cache usage");
+  const cached = (raw.cache_read_input_tokens as number | undefined) ?? 0;
+  const inputTokens = (raw.input_tokens as number) + cached + ((raw.cache_creation_input_tokens as number | undefined) ?? 0);
+  if (!Number.isSafeInteger(inputTokens)) throw new Error("Claude aggregate usage exceeds safe counter bound");
+  return { input_tokens: inputTokens, cached_input_tokens: cached, output_tokens: raw.output_tokens as number };
+}
+export async function runClaudeProgramWorker(input: ClaudeProgramInput): Promise<{ data: unknown; usage?: ProgramWorkerObservation["usage"] }> {
+  if (process.env.FORGE_FABRIC_TEST_MODE === "1") throw new Error("Real Claude workers forbidden in deterministic test mode");
+  if (input.signal.aborted) throw new Error("Claude canceled before dispatch");
+  const identity = await promisify(execFile)(input.binary, ["--version"], { cwd: input.cwd, env: input.environment, windowsHide: true, timeout: 10000, maxBuffer: 4096, signal: input.signal }).catch(() => { throw new Error("Claude CLI version inspection failed; model dispatch refused"); });
+  const version = validateClaudeProgramVersion(identity.stdout);
+  await input.onEvent({ type: "adapter.version", source: "claude", metadata: { version, minimumVersion: claudeProgramCapabilities.minimumVersion } });
+  if (input.signal.aborted) throw new Error("Claude canceled before model dispatch");
+  return new Promise((resolve, reject) => {
+    const child = spawn(input.binary, claudeProgramArguments(input), { cwd: input.cwd, env: input.environment, shell: false, windowsHide: true });
+    let pending = "", bytes = 0, count = 0, resultObserved = false, sessionId = input.threadId, final: ReturnType<typeof claudeProgramResult> | undefined;
+    let queue = Promise.resolve(), failure: unknown, settled = false, grace: ReturnType<typeof setTimeout> | undefined;
+    const finish = (error?: unknown) => { if (settled) return; settled = true; if (grace) clearTimeout(grace); input.signal.removeEventListener("abort", abort); if (error) reject(error); else resolve(final!); };
+    const abort = () => { child.kill(); grace ??= setTimeout(() => { child.stdout.destroy(); child.stderr.destroy(); child.unref(); finish(new Error("Claude termination/effects unknown; reconcile before retry")); }, 1000); };
+    input.signal.addEventListener("abort", abort, { once: true });
+    const consume = (line: string) => {
+      queue = queue.then(async () => {
+        if (settled || failure) return;
+        if (++count > 10000) throw new Error("Claude event budget exceeded");
+        const event = JSON.parse(line) as Record<string, unknown>;
+        if (typeof event.session_id === "string") {
+          if (!/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(event.session_id) || sessionId && event.session_id !== sessionId) throw new Error("Claude session identity mismatch");
+          if (!sessionId) { sessionId = event.session_id; await input.onThread(sessionId); }
+        }
+        if (event.type === "result") {
+          if (settled) return;
+          if (resultObserved) throw new Error("Duplicate Claude result");
+          resultObserved = true;
+          const usage = claudeProgramUsage(event);
+          if (usage) await input.onEvent({ type: "usage", source: "claude", usage, semantics: "incremental" });
+          final = claudeProgramResult(event);
+        }
+      }).catch(error => { failure = error; abort(); });
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      bytes += Buffer.byteLength(chunk);
+      if (bytes > 4 * 1024 * 1024) { failure = new Error("Claude output budget exceeded"); abort(); return; }
+      pending += chunk; let index: number;
+      while ((index = pending.indexOf("\n")) >= 0) { const line = pending.slice(0, index).trim(); pending = pending.slice(index + 1); if (line) consume(line); }
+    });
+    child.stderr.on("data", () => {});
+    child.once("error", () => finish(new Error("Claude executable unavailable or launch failed")));
+    child.once("close", async code => {
+      if (pending.trim()) consume(pending.trim()); await queue;
+      try {
+        await input.onEvent({ type: "process.closed", source: "claude", metadata: { exitCode: code, rootTerminationObserved: true, processTreeTermination: false } });
+        finish(failure || input.signal.aborted || code !== 0 || !final ? new Error("Claude completion/effects require reconciliation") : undefined);
+      } catch (error) { finish(error); }
+    });
+    child.stdin.on("error", () => { failure = new Error("Claude input delivery failed"); abort(); });
+    child.stdin.end(input.prompt);
+    if (input.signal.aborted) abort();
+  });
+}

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;
@@ -165,6 +166,7 @@ async function runCodexWorkerInternal(input: CodexWorkerInput, factory: CodexWor
 }
 
 export async function runCodexWorker(input: CodexWorkerInput, factory?: CodexWorkerFactory): Promise<CodexWorkerOutput> {
+  if (process.env.FORGE_FABRIC_TEST_MODE === "1" && !factory) fail("AF_CODEX_TEST_MODE", "Real LLM calls forbidden; provide a simulated SDK factory");
   try { return await runCodexWorkerInternal(input, factory ?? ((options) => isolatedCodexClient(options, input.cwd, input.signal))); }
   catch (error) {
     if (error instanceof CodexWorkerError) throw error;
@@ -182,20 +184,26 @@ 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"); }
   return { threadId, data, ...(observedUsage ? { usage: observedUsage } : {}) };
 }
 export async function runTypedCodexWorker(input: CodexWorkerInput & { outputSchema: unknown; validateOutput: (data: unknown) => void }, factory?: CodexWorkerFactory): Promise<{ threadId: string; data: unknown; usage?: CodexWorkerUsage }> {
+  if (process.env.FORGE_FABRIC_TEST_MODE === "1" && !factory) fail("AF_CODEX_TEST_MODE", "Real LLM calls forbidden; provide a simulated SDK factory");
   try { return await runTypedCodexWorkerInternal(input, factory); }
   catch (error) { if (error instanceof CodexWorkerError) throw error; fail("AF_CODEX_EXECUTION", "Typed SDK or persistence failed; reconcile before retry"); }
 }

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; }