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

package/.agents/skills/forge-agent-fabric/SKILL.md

@@ -166,4 +166,13 @@ Validate source against the owner registry before dispatch. Every mutation needs
 requestId; subsequent mutations pin expectedVersion. Never treat data-only completed as
 acceptance-ready or infer authority to apply from a worker's report. Preserve uncertain
 outcomes and reconcile observed effects before resume. Fenced replan uses a global barrier;
-SDK output caching is disabled. Publication still requires the user's task authorization.
+Same-run completed output reuse happens before worker preparation; cross-run SDK caching is absent.
+Use operatorVersion 2, explicit Blocks/results, after/sequence and waiting semantics; no legacy migration is required.
+For scoped UI acceptance require item/final owner checks, current evidence and full final obligations.
+Use program-history/program-explain/program-artifact-get/program-diff for inspection.
+When avoiding LLM spending set FORGE_FABRIC_TEST_MODE=1 and use deterministic adapters/SDK stubs.
+Publication still requires the user's task authorization.
+
+## Workflow correction contract R2.2
+
+Program subworkflows inherit ancestor activity quotas and cancellation; input is explicit. Owner visualCases binds route/viewport/state/dimensions to each population member; do not promise exhaustive UI coverage beyond that catalog. Capture obligations apply by assessment scope. New program runs use program-runs-v3/format 3 with immutable linked journal; no migration of old runs. program-explain includes graph nodes, observed instances and Mermaid. Typed refs/output(operation) improve authoring, while owner schemas remain authoritative. See docs/agent-fabric-programs.md and WORKFLOW_PROGRAM_V2_CORRECTIONS.md in the Forge source. For deterministic validation keep FORGE_FABRIC_TEST_MODE=1; do not launch real providers without explicit user authority.

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.70 input=c9c2b146d0cb312a96b8d2ba635c2e26634645a24895b1d003e2f65ae17a3e02 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.72 input=4096e19589f57b9568accde0ae34aa0782c1598f54261e161e1ff5ac7cc857b9 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # forgeos
 
+## 0.1.0-alpha.72
+
+### Patch Changes
+
+- Add owner-bound workflow authoring templates, durable usage budgets, fair scheduling, compatible recovery, conflict resolution and optional Claude adapter. Harden approval, evidence, accounting, Unicode transport and MCP interfaces; add paired benchmark reporting and focused CI coverage. Real-provider smoke and competitive quality evaluation remain unperformed.
+
+## 0.1.0-alpha.71
+
+### Patch Changes
+
+- Complete Agent Fabric workflow R2.2 with typed authoring, inherited subworkflow quotas and cancellation, shared owner scheduling, crash-recoverable leases, compact durable history, scoped evidence and visual case validation. Ship workflow templates, graph explanations and deterministic coverage. Validate the real Codex adapter with one bounded read-only smoke; retain explicit limits on local durability and model cost.
+
 ## 0.1.0-alpha.70
 
 ### Patch Changes

package/docs/agent-fabric-programs.md

@@ -1,168 +1,183 @@
-# Agent Fabric program workflows v2
-
-Program workflows are an opt-in interpreter hosted by the existing authenticated local
-project owner. Version-1 managed runs and accompanied task records retain their original
-commands, persistence and meaning. No existing run is automatically converted.
-
-Author a `WorkflowProgramV2` JSON value, or supply finite TypeScript source with named
-imports from `forgeos/agent-fabric/workflows`. The static lowerer accepts const data,
-literal arrays/objects, constructors and spreads of already lowered const data objects.
-It rejects arbitrary imports, loops, closures, accessors, computed properties, array
-spreads, runtime I/O and malformed syntax. Workflow source is never executed.
-
-The shipped example is `examples/agent-fabric-v2/`. Its file-conversion reviewers are
-deterministic command fixtures; configure a real distinct reviewer and project checks
-for coding acceptance. See the architecture ADR for normative boundaries.
-
-## Owner configuration and commands
-
-The owner reads `.forge/fabric-programs.json`, with versioned `schemas`, `executors`,
-`policies`, `acceptance`, `populations` and optional child `programs` registries.
-Requests cannot replace that registry. Each run pins its registry and external contracts.
-An author chooses registered references, not weaker review, coverage or effect authority.
-
-Keep `forge fabric serve` alive. Every mutation uses a unique `requestId`; subsequent
-mutations also require `runId` and `expectedVersion`. A repeated identical request is
-idempotent; changed contents under that request ID conflict. After a version conflict,
-read current status and use a new request ID for a changed decision.
-
-| CLI action | Meaning |
-| --- | --- |
-| `program-validate --file request.json` | Lower and validate without dispatch |
-| `program-start --file request.json` | Persist baseline, input and program before scheduling |
-| `program-status --run-id ID` | Read authoritative state |
-| `program-wait --file request.json` | Bounded wait using `{runId,cursor,waitMs}` |
-| `program-pause`, `program-resume` | Stop new dispatch / explicitly resume settled work |
-| `program-signal` | Persist an authorized event with target, generation, type and correlation |
-| `program-replan` | New program with barrier/additive/fenced modes |
-| `program-cancel` | Request cancellation; unobserved effects stay uncertain |
-| `program-reconcile` | Record observed failure or reconcile publication |
-| `program-apply` | Apply a gated candidate to local scoped files |
-
-Use `--file request.json --json` for mutations. Start accepts `{requestId,source,input}`
-or `{requestId,program,input}`. MCP exposes the same actions as
-`fabric_program_*`, using `{request: BODY}` for mutations and `{runId}` for status.
-Both transports use the same owner, state store and capability boundaries.
-The shared authenticated HTTP owner limits each request body to 40 KiB. Keep source and
-input below that transport bound; the offline lowerer's separate source cap is 256 KiB.
-
-## Operators and contracts
-
-`value`, `agent`, `command`, `map`, `branch`, `loop`, `repair`, `compose`, `gate`,
-`subworkflow` and `waitEvent` are finite primitives. Explicit output references infer
-dependencies; parent/body cycles are rejected before dispatch. Branches mark the other
-arm skipped. Child programs inherit policy/acceptance and global attempt/deadline limits.
-Loops require bounded rounds and a progress/termination decision. Each materialized
-operation has a stable invocation ID, generation and input/semantic digests.
-
-Schemas use a bounded JSON Schema subset: types, enum/const, properties, required,
-additionalProperties, items, array/string/numeric bounds and anyOf. Unsupported keywords
-are rejected. Conservative static inference checks known field, child-input, branch-merge
-and result types. Unknown shapes still require runtime validation. A completed process
-does not imply a valid output or approval: review payloads distinguish approved,
-changes_requested and inconclusive from operational failure.
-
-`repair@v1` is a built-in deterministic recipe. `implement-first` edits before assessment;
-`assess-first` can approve with zero edits. Every assessment reviews/checks the same
-candidate, with a distinct readonly reviewer and registered command checks. Candidate,
-feedback, phase, implementation/assessment/infrastructure counters and measured progress
-are checkpointed. Resume cannot replenish exhausted budgets. Nonaccepted recipes keep
-diagnostic output and stop their consumers; later values cannot mask rejection.
-
-`map` requires finite unique NFC keys, bounded concurrency, a seal and explicit completion:
-all-required, partial or quorum. All-required discovery must match the owner population.
-Coverage alone does not prove work was accepted: a separate closed collection ledger
-binds each item's accepted assessment and candidate contribution. Population gates require
-that ledger and retain every item's deltas/producers in the final candidate. Empty work
-requires explicit allowNoWork in both population and acceptance contracts.
-
-The initial inventory adapter enumerates files under captured `inventoryRoots` and optional
-extensions. It is a concrete file inventory, not a semantic proof that a glob found all
-components. Semantic populations require owner-supplied evidence and exact baseline pinning.
-Exclusions require an inventory member and a reason. Population changes require a successor
-run with a new captured contract; current replan cannot replace external contracts.
-
-## Candidate acceptance and application
-
-Candidates are immutable snapshot identities with ordered producer-specific deltas and
-parents. A shared ancestor is composed once; equal patches from independent producers
-are not silently deduplicated. Independent overlaps require resolution. Beforeimages,
-captured environment context, source types and scopes are checked before local writes.
-
-`completed` means a data program reached its typed result without a final acceptance gate.
-It is a re-openable computation checkpoint; it does not authorize application. Replan and
-resume are explicit owner decisions and the earlier state remains in immutable history.
-`acceptance-ready` requires an owner-issued gate and `acceptedCandidate`. A declared
-accepted result cannot bypass that gate or point to another candidate. Uncertain/active
-attempts block completion and application. `applied` and `canceled` require explicit successor
-runs for new work. No lifecycle state asserts human or production acceptance.
-
-`program-apply` requires current version, gate and authorization provenance. The owner
-commits ApplyIntent with candidate/program/contract digests, semantic version, seals and
-expected files before the first write. Signals received during application stay
-pending-after-apply. Publication checks each beforeimage, checks cancellation before each
-write, and stores observed completion. Multiple files are not one filesystem transaction.
-An interrupted/partial/divergent publication becomes apply-uncertain; it never silently retries.
-
-Publication reconciliation accepts `publication: true` only after observing all expected
-files. `publication: "retry"` requires authorization and the complete original baseline;
-it clears the old intent and pauses for explicit resume/revalidation. Partial or divergent
-files are preserved. Worker reconciliation requires attemptId, `resolution: "failed"`
-and an observed reason; parent uncertainty is reconciled after its worker attempts.
-
-## Durability, replan, effects and reuse
-
-Each run has one checksummed authoritative atomic record in
-`.forge/local/agent-fabric/program-runs`. Immutable artifacts and full stateRefs are fsynced
-before referencing transitions. Every historical transition points to the exact state,
-including prior programs, generations, decisions and counters. Store.history and artifact
-get APIs inspect that history. Locks use linked complete owner files and guarded dead-owner
-reclamation. Recovery marks incomplete dispatch/application uncertain and does not start work.
-Process-crash/replay behavior is tested. Directory fsync/power-loss durability across every
-filesystem is not asserted. Archive/GC is manual; preserving evidence consumes disk.
-
-Barrier replan requires settled work. Additive replan preserves all existing templates;
-after the previous scheduler cycle settles, controls and final gates are recomputed for
-the new semantic version. Fenced replan is owner opt-in: affected operations/dependents
-receive monotonic generations; running attempts become uncertain and receive abort requests.
-It currently uses a **global scheduling barrier**. Unaffected running work may finish, but
-resume waits for the scheduler to settle and uncertainty to be reconciled. Removed historical
-operations are retired/skipped after observation; history is retained. This is not arbitrary
-live replacement with independent branch schedulers.
-
-Commands use explicit argv, resolved/hashed actual executables, scrubbed environment,
-frozen clone inputs and optional locked dependencies with scripts ignored. They are
-cooperative OS processes, not a network/filesystem sandbox. Strong disabled-network claims
-are refused for commands. Codex workers use readonly/workspace-write sandbox, disabled
-network and inherited MCP isolation. captureScope is distinct from write authority, allowing
-readonly programs without granting source writes. Generated paths cannot conceal captured
-source; external scratch is separate from candidate files. Cancellation does not prove a
-process tree stopped; unknown outcomes require observation.
-
-Outputs are not reused by default. `cache: "workspace"` is an owner declaration for command
-executors whose complete relevant inputs are their captured workspace/data, observed binary,
-dependency tree and environment. External/network/time/global filesystem inputs invalidate
-that declaration unless separately closed by an adapter. Compatible completed outputs receive
-explicit reuse receipts. SDK output reuse is disabled because effective global instructions,
-plugins and model inputs are not yet fully attested. Prompt caching is a separate provider feature.
-
-Recommended initial concurrency is four. Hard caps: concurrency32, depth32, items10000,
-attempts10000, operations20000, output4MiB, state32MiB and20 plan revisions. Expression/DSL
-expansion is bounded before concatenation/cloning. A dispatch reserve leaves record space
-for recovery. These are limits, not measured performance claims at maximum scale.
-
-## Verification and remaining scope
-
-Tests cover finite lowering, output/generation/counter contracts, 80-item coverage, fabricated
-receipts, no-work, events, cache attestation, recovery, additive/fenced races, real commands,
-two-file composition, three same-file corrections, diamond ancestry, identical independent
-patch conflicts, application idempotency, beforeimage preservation and authenticated transport.
-The opt-in SDK pilot script performs a real readonly typed activity and records its bounded
-evidence separately. It is excluded from normal CI to avoid account/model usage.
-
-This alpha implements the bounded v2 foundation and conservative online controls. It does
-not establish complete F6/F7 product acceptance, semantic inventory adapters, extensible recipe
-registries, external effects exactly-once, streaming discovery, automatic GC, SDK output cache,
-high-concurrency scale, a live independent-branch scheduler or Claude product superiority.
-The benchmark harness labels its procedural comparison as a reference model, never as a
-measured Claude run. Production/EasyGrow/native-hook/App-closed acceptance remains separate.
+# Agent Fabric program workflows
+
+Current dev architecture: finite typed TypeScript → JSON IR (schemaVersion 2/operatorVersion 2) → exclusive local owner → activity scheduler → candidates/evidence → final assessment → gate → separate apply. There is no legacy interpreter or migration requirement. Start new runs after semantic upgrades. Normative architecture: `architecture/agent-fabric/WORKFLOW_PROGRAM_V2_ADR.md`; requirements and evidence are adjacent documents.
+
+## R2.2 correction contract
+
+Correction plan: `architecture/agent-fabric/WORKFLOW_PROGRAM_V2_CORRECTIONS.md`. Subworkflows inherit activity scopes, cancellation, dependencies, item identity and lexical loop state. Their `workflowInput()` is the explicit child input. Policy/acceptance cannot change; population is inherited and cannot be replaced. Prefer passing item data explicitly for portable child programs; static schemas remain authoritative.
+
+The owner/store share one PID/token hardlink lease protocol, including recovery of dead reclaim guards. A live guard is never removed. Unknown process liveness stays conservative. No exactly-once external guarantee is added.
+
+`ProgramExecutor.inputSchema` optionally validates activity input before preparation/dispatch, alongside conservative preflight inference. Output schemas remain mandatory. Typed author refs support `executorRef<Input,Output>` and `programRef<Input,Output>`; `schemaRef<Output>` types events. `output(operation)` retains output types, `field` checks typed keys, and typed map bodies retain collection result item types. `output("id")` remains schema-validated at preflight/runtime. Generics are author annotations, not inferred from registry files and not authority to weaken a schema. `WorkflowExpression`, `WorkflowValue`, `WorkflowResolved`, `WorkflowBody`, `WorkflowCollection`, `WorkflowActivityOptions` are exported type helpers. No second interpreter is introduced.
+
+```ts
+const inspect = agent("inspect", {
+  executor: executorRef<{path:string},{ok:boolean}>("inspect", "v2"),
+  input: {path: "src/a.ts"}
+});
+const ok = field(output(inspect), "ok"); // WorkflowExpression<boolean>
+```
+
+### Visual population
+
+An owner population may declare `visualCases`, exactly one case per member:
+
+```json
+{"itemKey":"checkout-mobile-error","route":"/checkout","viewport":"mobile","state":"error","width":390,"height":844}
+```
+
+Route/viewport/state tuples and member keys must be unique; excluded members remain cataloged but are not assessed. Every observed capture must match its owner tuple and dimensions. AssessmentContext carries the current expected cases to capture/review workers. Final capture requirements recapture every active case. Item capture requirements come only from item obligations; final-only obligations do not force local screenshots. Without visualCases, coverage is per member, not an inferred matrix. Receipt metadata and valid image headers do not prove that the pixels depict the declared route/state. The WebP header parser currently accepts VP8X only.
+
+Capture blobs commit before result; all receipts of one attempt commit atomically with the observed attempt result. Invalid batches leave no accepted partial receipts. Orphan blobs may remain until explicit maintenance; no GC is implied.
+
+### Storage and inspection
+
+New runs use `.forge/local/agent-fabric/program-runs-v3`. Format 3 envelopes contain snapshot/journal pointers and CAS receipts, not duplicate full snapshots/history arrays. Each immutable journal node links its predecessor; history verifies the chain and historical snapshot identities. Snapshot and journal commit before atomic envelope publication. Old directories are preserved but unused; no checkpoint migration. Identical internal mutations do not write another checkpoint; authenticated request receipts still commit. Dispatch keeps a 24 MiB snapshot reserve and 90,000-transition reserve for recovery.
+
+`program-explain.graph` returns `nodes`, observed `instances`, `mermaid`, and graph semantics. The diagram shows static dependencies, including control completion edges; dynamic map/loop expansions are separate instances. Mermaid labels are escaped. Storage metrics split actual written bytes into snapshot/journal/envelope/artifact categories, including temp files; full state snapshots still grow with the run. Profiling does not establish model speed or quality.
+
+Reusable examples: `examples/agent-fabric-v2/map-child.workflow.ts`, `item-child.workflow.ts`, and `visual-population.json` (owner baseline digest required).
+
+## Start and inspect
+
+The owner reads `.forge/fabric-programs.json`: versioned schemas, executors, policies, acceptance, populations and optional child programs. Authors select references; requests cannot substitute a weaker owner registry. Keep `forge fabric serve` alive. New dispatch/apply checks current owner authorization; immutable historical facts retain their pinned definitions.
+
+`forge fabric program-validate --file request.json --json` accepts `{source}` or `{program}`. Start adds `{requestId,input}`. CLI mutations use request files and `{runId,requestId,expectedVersion,...}`. The HTTP owner bounds requests at 40 KiB; offline source lowering caps at 256 KiB. Every control uses CAS and idempotency; use a new requestId when changing a decision after a conflict.
+
+| Action | Request/meaning |
+|---|---|
+| program-validate | source/program, no dispatch |
+| program-start | requestId, source/program, input |
+| program-status | --run-id ID, authoritative state |
+| program-wait | runId, cursor, waitMs; bounded long poll |
+| program-pause | stop new dispatch; active work is observed |
+| program-resume | continue settled work without replenishing budgets |
+| program-signal | signalId, target, generation, type, correlation, payload, authorization, optional subject/expiresAt |
+| program-replan | source/program, mode barrier/additive/fenced |
+| program-cancel | request cancellation; unknown effects remain uncertain |
+| program-reconcile | attemptId or operationId, resolution failed, observed reason; publication reconciliation is separate |
+| program-apply | current gated result and authorization; scoped local files |
+| program-history | --run-id ID, journal/stateRefs |
+| program-explain | --run-id ID, scopes/queue/scheduler/storage/guarantees |
+| program-artifact-get | runId, ref; optional binary:true/maxBytes; bounded reachable artifact only |
+| program-diff | runId and proposed source/program, graph changes |
+
+MCP exposes the same 15 actions as `fabric_program_*`. Status/history/explain accept `{runId}`; other actions use `{request:BODY}`. Both use the same authenticated owner and store. Apply is not automatic.
+
+## Complete author API: 50 constructors
+
+Import from `forgeos/agent-fabric/workflows`. Functions create finite IR data; they do not dispatch during authoring. `WorkflowDefinition`, `WorkflowOptions`, `WorkflowRef`, `WorkflowOperation` are exported author types. Normal TS compilation and static lowerer both support `as const`/`satisfies`; lowerer never evaluates callbacks, arbitrary imports or runtime I/O. JSON authors get identical owner validation.
+
+`defineWorkflow({id,version,operatorVersion:2,mode,inputSchema,outputSchema,policy,acceptance,population?,steps,result})` defines the root. Mode data returns typed data; candidate mode requires a gate for acceptance-ready. Schema subset supports bounded objects/arrays/scalars, properties/required/additionalProperties, enum/const, numeric/string/array bounds and anyOf; unsupported keywords reject.
+
+Seven reference constructors share `(id,version)` and have separate nominal kinds: `schemaRef`, `executorRef`, `policyRef`, `acceptanceRef`, `populationRef`, `recipeRef`, `programRef`.
+
+All 13 operators use `(id,options)`, with optional common `after:string[]` and label. `after` is control dependency, not an operator. Reference dependencies are also inferred; independent roots run concurrently. IDs are lexical and cycles reject before dispatch. Multi-step Blocks require `{steps,result}`; a single operation is shorthand.
+
+| Operator | Main options and result |
+|---|---|
+| value | value; pure data |
+| agent | executor, input?, candidate?, writeScope?; typed worker data |
+| command | same activity contract; registered command executor |
+| map | items,key,body,completion,coverage?,quorum?,concurrency?,order?; sealed collection with item outcomes |
+| branch | condition,then,else Blocks; selected result, unused arm skipped |
+| loop | initialState,maxRounds,body,next,until; final state, bounded progress |
+| repair | recipe,implement,review,checks,evidence?,assessmentScope?,entryMode,initialCandidate,writeScope,maxRepairRounds,maxAssessmentAttempts,maxInfrastructureAttempts,progressPolicy; accepted or explicit nonacceptance result |
+| compose | candidates,onConflict:needs-resolution; integrated candidate; conflicts block |
+| gate | candidate,coverage?,authorization?; owner-issued current receipt |
+| subworkflow | program,input; child result under inherited limits/contracts |
+| waitEvent | type,correlation,schema,subject?,timeoutMs?; one authorized event payload |
+| sequence | steps,result; serial required children |
+| parallel | steps,result,onFailure:collect-all/cancel-siblings; required children with diagnostics |
+
+All 29 expressions:
+
+| Expression | Meaning |
+|---|---|
+| workflowInput() | typed input |
+| item() | current map item, including nested loop |
+| loopState() | current loop state |
+| output(id) | data result of lexical invocation; activity envelope is unwrapped |
+| field(value,key) | bounded object field |
+| literal(value) | literal data, no nested expression interpretation |
+| object(record) | evaluate object entries |
+| array(...values) | evaluate array entries |
+| eq(a,b) | canonical data equality |
+| and(...values) | boolean conjunction |
+| or(...values) | boolean disjunction |
+| not(value) | boolean negation |
+| concat(...arrays) | bounded concatenation |
+| filter(values,key,equals) | field equality selection |
+| unique(values,key) | first unique field values |
+| sort(values,key) | UTF-8 field ordering |
+| take(values,count) | bounded prefix |
+| length(value) | collection/string length |
+| population() | owner population contract |
+| acceptance() | owner acceptance contract |
+| candidateFromBaseline(entry?) | owner baseline candidate; entry bounds item context |
+| outputCandidate(id) | candidate from completed activity/composition |
+| acceptedCandidate(id) | accepted repair candidate with owner receipt |
+| acceptedCandidates(id) | accepted candidate collection |
+| coverageFor(contract,discovered) | validate discovered items against owner catalog; issue receipt |
+| coverageReceipt(id) | collection coverage receipt |
+| acceptanceWriteScope(id) | inherited acceptance write scope |
+| approvedChecksFor(entry) | owner-approved checks for work entry |
+| acceptanceChecks(id) | checks inherited from the acceptance contract |
+
+## Recovery and scopes
+
+Owner activity capacity is four; run and ancestor map quotas can narrow it. Parent controls do not hold activity slots. Queue admission shares the absolute run deadline. Completed intact same-run outputs are reused before workspace/adapter preparation, including mocked/real SDK output records. This is distinct from cross-run cache, which is absent. Corrupt artifacts block and do not trigger silent redispatch.
+
+Waiting is its own state. Independent siblings continue and survive resume. Events persist before consumption; target/generation/type/correlation/subject/schema/expiry bind their use. A live owner wakes on authorized event or deadline. After restart use explicit resume. Paused stays paused. Completed data is not acceptance-ready. Unobserved cancellation/dispatch stays uncertain and retains reservations through restart until observation/reconciliation. Exactly-once external effects are not promised.
+
+Barrier replan recomputes changed branches and dependents, preserving compatible intact facts. Additive keeps existing templates. Fenced replacement requires owner opt-in and a global barrier; this is not independent live local fencing. Repair persists intent/counters before dispatch and never refunds exhausted budgets on resume.
+
+## UI and candidate acceptance
+
+Owner contracts declare `requiredChecksByScope:{item,final}`, `assessmentBindings` and obligations `{id,scope,criteria,requiredEvidence?}`. Review/check/capture receive AssessmentContext with candidateRef, obligationIds, environmentRef, itemKey and evidenceRefs. Evidence files are readonly inputs. Registered capture commands return JSON `evidenceArtifacts:[{path,itemKey,buildDigest,environmentRef,mime,width,height,route,viewport,state}]`; path must be in bounded scratch storage. Owner stores immutable bytes and issues capture receipts. Invalid/missing/stale evidence blocks; it does not become a UI defect requiring implementation.
+
+Assess-first means a correct UI produces zero edits. Review approval alone is insufficient: findings must be empty, checks passed, all obligations covered, current candidate/env/evidence bound and distinct observed reviewer attempt. Final assessment after compose recaptures the complete population and can reject an item previously approved locally. Compose can opt into an owner-registered resolver; conflicting artifacts are data for resolution rather than simultaneously materialized. The resolver starts from the baseline, produces a fresh candidate and inherits no approval. A new final assessment is required.
+
+Map keys normalize NFC before uniqueness, encode path segments once and order by UTF-8. Completion is all-required/partial/quorum; quorum is `{minAccepted:K}`, explicit and only closes when outcomes settle. Owner must authorize partial/quorum; such a result cannot alone satisfy all-required final obligations. Envelope item outcome is distinct from arbitrary user data (including a user field named status).
+
+If `requireHumanApproval:true`, add a wait subject `{candidate: acceptedCandidate(finalId), contract: acceptance()}` and give `output(waitId)` as gate authorization. The authenticated host supplies provenance and approved payload, not a worker. A declined/expired/fabricated approval does not authorize gate/apply.
+
+Apply commits an immutable intent before the first write, pins candidate/contract/semantic version/seals and checks beforeimages. Multiple files are not an atomic filesystem transaction. Divergent/partial writes become apply-uncertain. Reconciliation with `publication:true` requires observed complete files; retry requires authorization and complete original baseline, then explicit resume/revalidation. Source files remain untouched until apply.
+
+## Runnable examples and no-LLM verification
+
+`examples/agent-fabric-v2/ui-audit.workflow.ts` is the complete UI plan. `run-ui-fixture.ts` builds 20 local HTML pages with three known defects and registered deterministic discover/capture/review/implement/local/global-check commands. Test evidence: exactly three implementations, 43 captures including 20 fresh final captures, 21 final obligations, no apply and zero LLM calls. PNG fixtures verify transport/binding. Optional explicit browser path renders local HTML in headless Chromium/Edge; visual quality is still not model-evaluated.
+
+Run `FORGE_FABRIC_TEST_MODE=1` using the shell's environment syntax, then `node bin/forge-bun.mjs run examples/agent-fabric-v2/run-ui-fixture.ts`. The test fuse refuses default real model factories; stubs remain supported. Runtime profiling: `node bin/forge-bun.mjs run scripts/benchmark-fabric-workflows.ts report.json`, fixed fan-out/fault/restart, no provider. Neither is a Claude/model-quality benchmark. Cross-run cache, distributed owner, automatic GC and unlimited streaming/race remain future extensions.
+
+## Competitive workflow program
+
+The detailed implementation plan is `architecture/agent-fabric/WORKFLOW_PROGRAM_COMPETITIVE_PLAN.md`. Owner-bound review, bugfix and migration authoring requests are in `examples/agent-fabric-v2/templates/`. `program-author --file request.json` proposes validated IR; `program-author-types` reads declarations generated from the owner registry. Both use the authenticated owner and dispatch no worker. Start and apply remain separate.
+
+The owner reads optional `.forge/fabric-runtime.json` at startup:
+
+```json
+{"schemaVersion":1,"ownerCapacity":4,"ownerMaxTokens":100000}
+```
+
+Capacity accepts 1–32. Omit `ownerMaxTokens` to leave the owner token budget unspecified. Configuration is a regular bounded file, not a request override; changes take effect on explicit owner restart. Existing `ensure-owner` starts or reuses the detached local owner. No global service installation is required. Restart preserves uncertain attempts and does not automatically resume paused work.
+
+The owner token budget is cumulative across runs retained in its store, including unspent final reservations. It has no implicit daily reset and is not a monetary budget. Preparation may happen before admission; these counters do not price CPU or storage. Settled unknown provider usage requires the declared allowance or an authenticated `program-reconcile` request with `resolution: "usage"`, observed counters, authorization provenance and a reason. Observed usage cannot be silently overwritten.
+
+A policy may declare `resources: {maxTokens, reserveTokensPerAttempt, finalReserveTokens, unknownUsage: "block" | "allow"}`. These are durable admission budgets, not provider hard limits. In-flight work can exceed estimates. Unknown consumption is explicit and cannot be represented as measured zero. An owner-declared nonprovider command can use `tokenAccounting: "none"`; its usage is `not-applicable`, rather than measured zero. Arbitrary commands remain unknown without this declaration. Required final checks and review are never waived to fit a budget. `program-explain` reports usage liability, scheduler capacity, storage deduplication and actionable diagnostics. Observations are bounded, deduplicated and persisted before final schema validation; candidate acceptance still depends on owner receipts.
+
+Program model workers prepare existing repository context from their current clone and record context diagnostics. Codex can receive native local images with delivery receipts; delivery does not prove comprehension. Codex thread recovery requires observed termination, the original workspace and compatible invocation. Reconcile explicitly before resuming; do not retry uncertain effects blindly.
+
+The opt-in `kind: "claude"` executor requires one explicit native executable in `argv`, `isolation: "cooperative"`, `network: "host"` and owner policy allowing both. Its stream-JSON adapter uses structured output and restricted tools, disables inherited hooks/MCP, records usage including failed results, and checks session identity. It requires a CLI compatible with the documented flags (minimum indicated 2.1.259). This integration has deterministic protocol coverage; no real Claude smoke or quality comparison has been performed. Claude provides neither strong isolation nor observed process-tree termination here; native image delivery and workspace thread recovery are currently Codex capabilities.
+
+Independent coding quality and competitive superiority require external evaluation. `scripts/summarize-fabric-benchmark.mjs` validates collected reports and keeps missing usage or independent assessment explicit. Deterministic runtime tests do not establish superiority over Claude Code.
+
+### Corrections from implementation review
+
+Templates requiring human approval must supply an owner-registered `approvalSchema` accepting an object with `approved: true`. The template emits a bound wait event and passes its output to the gate. `evidence` accepts readonly owner-registered executors. Capture obligations currently require the population migration template with evidence executors; review/bugfix convenience templates reject that profile before dispatch. Custom workflow IR remains available for broader UI assessment flows. Template scopes must fit acceptance, policy and executor permissions; resolver scope must cover every proposed file.
+
+Trusted hosts may call `ProgramRunService.updateRuntimeOptions` to resize activity capacity without interrupting active attempts. File configuration remains startup/restart configuration. Completed publication may receive usage reconciliation, but does not reopen its gate or become resumable.
+
+Recovery now binds the delivered repository context, supplementary runtime observations and evidence bytes to the invocation fingerprint. Older markers that lack this binding are conservatively incompatible; do not rewrite them to bypass reconciliation. Preparation observations separate workspace, environment, cache verification/copy, dependency installation, capture and execution timings. Nested phase durations must not be summed as independent wall time.
+
+For paired external reports, use `node --import tsx scripts/summarize-fabric-benchmark.mjs LEFT.json RIGHT.json`. Comparison validates matching tasks, model, tools, context, contract and budget; unmatched inputs cannot establish controlled superiority. Missing metrics remain unknown. CI also verifies that each critical gate actually produces a passing test result.

package/docs/agent-fabric.md

@@ -9,12 +9,10 @@ Forge Agent Fabric is an experimental protocol-oriented execution layer for dyna
 
 ## Implementation status
 
-Status checked against local source `c8dfdf0c0c3cd6610bab68b4872ab9dcf8d4214c` on
-2026-10-07. The [current status summary](./architecture/agent-fabric/CODEX_DYNAMIC_WORKFLOWS.md#estado-atual-verificado-em-2026-10-07)
-distinguishes implemented accompanied/managed modes, recorded pilot evidence and
-remaining acceptance work. Historical plans and their original checklists are not
-the current capability inventory. This refresh did not rerun the SDK pilot or establish
-publication of the inspected revision.
+Workflow corrections R2.2: inherited subworkflow quotas/cancellation, shared recoverable leases, owner visual case catalogs, typed connections, compact linked journal and graph inspection. See [correction plan](architecture/agent-fabric/WORKFLOW_PROGRAM_V2_CORRECTIONS.md).
+
+Current development workflow runtime adopts operatorVersion 2 directly, without a legacy interpreter or migration requirement. See [workflow API](./agent-fabric-programs.md), [normative architecture](./architecture/agent-fabric/WORKFLOW_PROGRAM_V2_ADR.md) and [current implementation evidence](./architecture/agent-fabric/WORKFLOW_PROGRAM_V2_EVIDENCE.md). This revision adds activity quotas, durable waiting/continuation, scoped item/final obligations and immutable capture evidence. Historical plans and SDK pilots are not proof of current model quality. This implementation was validated without real LLM calls.
+
 
 The Codex-accompanied task mode now records acceptance criteria, scoped source snapshots,
 independent review and checks in a persistent local task. Its dynamic workflow scheduler

package/docs/architecture/agent-fabric/WORKFLOW_PROGRAM_COMPETITIVE_EVIDENCE.md

@@ -0,0 +1,75 @@
+# Forge Agent Fabric — implementação e evidências
+
+Data: 2026-10-10. Baseline: `3e7475f7a0e47be0d351d5c37355ed9f3a5c0ecd`.
+Plano: `WORKFLOW_PROGRAM_COMPETITIVE_PLAN.md`. Entrega local sem commit, push, publicação ou deployment.
+
+## Entrega por etapa
+
+| Etapa | Implementação | Evidência e limite |
+|---|---|---|
+| E0 | Relatório versionado de benchmark, validação e resumo com avaliação independente | Unknown não vira zero; aprovação do owner não prova sucesso externo. Nenhum benchmark de qualidade com provedor foi realizado. |
+| E1 | Observações duráveis, deduplicação, semântica incremental/cumulativa, usage em falhas, diagnóstico estruturado | Teste de output inválido preserva consumo após restart; contadores inválidos/overflow bloqueiam. Não aplicável é distinto de medição zero. |
+| E2 | Round-robin e capacidade owner configurável de 1 a 32 | Três runs elegíveis alternam; regressão T07 identificou e corrigiu cursor quando novas filas chegam. |
+| E3 | Reconciliação explícita e retomada Codex com workspace original, término observado, geração e fingerprint | Serviço encaminha thread compatível; fixture Git com preparação real rejeita delta incompatível e marker adulterado antes de iniciar modelo. |
+| E4 | Autoria pelo owner, declarações tipadas e templates review/bugfix/migration | Três templates executam até acceptance-ready com checks/gate; baseline correto gera zero implementação. Revisão negativa não edita nem aprova. |
+| E5 | Contexto existente do repositório integrado ao clone dos program workers | Snapshot/diagnósticos registrados; qualidade do código gerado com esse contexto não foi medida. |
+| E6 | Admissão serializada, reservas duráveis por run/owner e reserva final | Testes de restart, input forjado e orçamento entre runs. Uso real informado prevalece sobre declaração de comando sem provedor. |
+| E7 | Preparação instrumentada e CAS deduplicado antes de escrita/fsync | Duplicata não aumenta bytesWritten; conteúdo corrompido continua rejeitado. Não há alegação de ganho geral de latência. Cache existente de dependências foi preservado. |
+| E8 | Resolver autorizado, candidato novo e recibo causal de substituição | População fechada requer nova avaliação, obrigações de cada item e união de checks. Recibo vincula geração, semântica, contrato e população; relógio não autoriza reaproveitamento. |
+| E9 | Adapter Claude opt-in, validação de versão, reutilização do owner background existente e imagens nativas Codex | Protocolo simulado e transporte de imagem verificados. Claude real não foi executado; adapter cooperativo, rede do host, sem término garantido da árvore. |
+
+## Módulos e interfaces
+
+- Runtime: `program-contract`, `program-service`, `program-scheduler`, `program-store`, `program-observation` e `program-view`.
+- Workers: `program-worker`, `codex-sdk-worker`, `claude-program-worker`, observação de `managed-workspace` e contexto existente do repositório.
+- Autoria: `program-authoring`, `program-templates`, opções compose no `program-api` e exemplos em `examples/agent-fabric-v2/templates/`.
+- Interfaces: ações `program-author` e `program-author-types` em CLI/MCP/owner, configuração regular e limitada `.forge/fabric-runtime.json`, capabilities compartilhadas e exports públicos.
+- Avaliação: `program-benchmark` e `scripts/summarize-fabric-benchmark.mjs`; apenas validam relatórios previamente coletados.
+
+## Validação concluída
+
+Foram usadas suítes direcionadas, sem executar modelos reais. Os números abaixo descrevem grupos de verificações; algumas rodadas repetiram somente casos afetados por correções e não devem ser somadas como testes únicos.
+
+| Grupo | Resultado |
+|---|---|
+| SDK, autoria, configuração pública e templates | 21 testes passaram; 125 assertions na primeira integração |
+| Adapter Claude, imagens e recuperação com Git real | 3 testes passaram; 22 assertions; 1,71 s na integração final |
+| Runtime competitivo e execução de templates por ações do owner | 10 testes passaram; 69 assertions; 11,85 s na integração final |
+| Gates críticos existentes selecionados | 4 passaram; 40 filtrados; nenhum erro |
+| Contrato e classificador de CI | 2 passaram; caminhos centrais e desconhecidos preservam suíte ampla |
+| Regressões selecionadas após correção do scheduler | 16 passaram; 23 filtradas; 15,11 s |
+| Typecheck global | `node node_modules/typescript/bin/tsc --noEmit`: exit 0 |
+| Lint e whitespace | Lint aprovado; `git diff --check`: exit 0 |
+| Geração/export dos adapters | Geração e exports generic/codex aprovados |
+| `verify framework --skip-tests --skip-typecheck` | Aprovado: estabilidade da geração, contrato, compiler workspace, policy, auth, RLS estrutural, adapters e lint |
+
+A verificação framework omitiu deliberadamente a suíte completa e a repetição do typecheck, pois os testes selecionados e o typecheck foram executados separadamente. Não se declara aprovação da suíte completa. Uma rodada anterior de regressões foi interrompida após 59 aprovações ao revelar bloqueio no scheduler; o cursor foi corrigido e o caso afetado passou na seleção posterior. O aviso estrutural existente de RLS em pglite/memory não comprova isolamento em PostgreSQL.
+
+## CI reduzida
+
+Ubuntu/Node 22 roda uma vez no job verify. A matriz adicional usa Windows 22 em PRs, Windows 22 e Ubuntu 24 no main, e inclui macOS no disparo manual. Typecheck, geração estável, compiler checks, lint e segurança permanecem.
+
+Somente mudanças em módulos explicitamente cobertos de autoria/templates/observação/benchmark/view/Claude e seus testes selecionam a suíte crítica. Alterações em owner, lease, store, workspace, serviços, dependências, arquivos compartilhados, caminhos desconhecidos ou histórico ausente mantêm cobertura ampla. Main mantém a suíte completa de Agent Fabric. Nenhum teste existente foi removido ou assertion enfraquecida. O tempo total do GitHub Actions não foi medido e a nova configuração ainda não foi executada no GitHub.
+
+## Correções da revisão independente
+
+1. Comandos sem provedor usam declaração explícita do owner `tokenAccounting: "none"` e estado não aplicável; comandos arbitrários continuam desconhecidos. Uso informado inesperadamente é contabilizado.
+2. Resolver não herda aprovação dos itens: recibo causal permite substituir a proveniência original, com nova avaliação completa e checks de item/final.
+3. Freshness usa IDs dos recibos emitidos pelo owner, evitando reaproveitamento baseado em timestamps iguais ou relógio regressivo.
+4. CI reduzida foi restringida para preservar regressões dos módulos centrais.
+5. Recuperação foi exercitada com workspace/marker reais, além do encaminhamento simulado da thread.
+
+A revisão daquela rodada não encontrou bloqueadores adicionais no conjunto examinado. A revisão cruzada posterior encontrou e corrigiu bugs adicionais de recuperação, accounting, scopes, aprovação/evidências, Unicode, MCP e CI; veja `WORKFLOW_PROGRAM_COMPETITIVE_REVIEW.md` para os resultados atualizados e limites. Revisão estática e fixtures locais não certificam produção.
+
+## Condições de operação e pendências externas
+
+- OwnerMaxTokens é cumulativo sobre runs retidos e reservas finais; não se renova diariamente. É orçamento de admissão por tokens, sem preço de CPU/storage ou garantia de teto monetário.
+- Trabalho em curso pode exceder a estimativa reservada; término desconhecido mantém reservas e exige reconciliação.
+- Claude requer executável nativo compatível, versão >=2.1.259 e política cooperativa/rede explícita. A consulta de versão acontece antes de inferência no uso futuro; não foi executada nesta sessão.
+- Retomada no workspace original e imagens nativas estão habilitadas para Codex. Claude não recebe essas garantias neste adapter.
+- Imagem entregue não significa imagem compreendida. Protocolo simulado não demonstra qualidade de programação.
+- Owner background reutiliza o startup local existente; nenhum serviço global foi instalado e nenhum owner permanente foi iniciado nesta entrega.
+- Snapshot incremental, GC destrutivo, cache de respostas entre runs e owner distribuído continuam extensões condicionais, conforme o plano.
+- G4–G6 — qualidade externa, eficiência representativa e superioridade competitiva — exigem avaliação posterior. Não são inferidos dos testes locais.
+
+Os artefatos gerados foram atualizados pelo gerador, sem edição manual. Arquivos não rastreados preexistentes foram preservados. Alterações permanecem no checkout para revisão.