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

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.71 input=c1757bb141bbcdd4d235a6d1af230b3a767ec7e4354f7fc3afb49fd46e893f06 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,11 @@
 # 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

package/docs/agent-fabric-programs.md

@@ -136,7 +136,7 @@ Barrier replan recomputes changed branches and dependents, preserving compatible
 
 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. Conflicts need resolution; no automatic resolution recipe is implemented.
+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).
 
@@ -148,4 +148,36 @@ Apply commits an immutable intent before the first write, pins candidate/contrac
 
 `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 Codex 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. Future extensions (cross-run cache, distributed owner, automatic GC/resolution, unlimited streaming/race, additional harnesses) remain out of this implementation.
+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/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.

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

@@ -0,0 +1,137 @@
+# Forge Agent Fabric — plano técnico final
+
+Data: 2026-10-10. Baseline: `3e7475f7a0e47be0d351d5c37355ed9f3a5c0ecd`.
+Escopo autorizado: implementação local completa com subagentes, validação focada e redução de redundâncias na CI. Nenhuma publicação, push, deployment ou instalação global faz parte desta entrega. Este plano não autoriza inferência paga para benchmarks.
+
+## Objetivo e critérios de sucesso
+
+Evoluir `program-*` para workflows de programação completos, observáveis, recuperáveis e eficientes. Superioridade competitiva exige qualidade externa, tempo e consumo por resultado correto, trabalho repetido após falha e intervenções humanas; aprovação do próprio gate não é a definição de sucesso. Comparações precisam declarar modelos, ferramentas, contexto, versões e budgets.
+
+O baseline já contém DSL finita/IR v2, schemas e tipos nominais, owner exclusivo, gates, aplicação separada, templates básicos, contexto de repositório em `run-*`, cache verificado de dependências, journal encadeado e artefatos por conteúdo. Não reconstruir esses mecanismos.
+
+## Invariantes
+
+- Modelo propõe; owner valida registry, autoridade, escopo e aceitação.
+- Completed não significa accepted. Review/checks/evidence/coverage pertencem ao candidato observado.
+- Cancelamento solicitado não comprova término da árvore de processos.
+- Efeitos não observados continuam uncertain; não há exactly-once externo.
+- Resume não repõe débitos nem estende deadlines.
+- Apply continua separado e vinculado ao gate atual; múltiplos arquivos não formam transação atômica.
+- Eventos tardios não concluem gerações sucessoras.
+- Telemetria distingue observado, estimado e desconhecido; desconhecido nunca é zero.
+- Mudanças de semântica/persistência são versionadas; não reinterpretar checkpoints antigos silenciosamente.
+- Command e adapters cooperativos não são sandbox forte.
+
+## Entregas, prioridade e dependências
+
+| ID | Prioridade | Entrega | Depende de |
+|---|---|---|---|
+| E0 | P0 | Baseline e protocolo de avaliação externa | — |
+| E1 | P0 | Telemetria durável e diagnóstico | definições E0 |
+| E2 | P0 | Round-robin real e capacidade owner configurável | E0/E1 para liberação |
+| E3 | P0 | Cancelamento, reconciliação e recuperação segura | E1 |
+| E4 | P0 | Review, bugfix e migration completos; autoria assistida | E1/E3 |
+| E5 | P1 | Contexto existente em program workers | E0/E1 |
+| E6 | P1 | Orçamento de admissão e reservas | E1/E2/E3 |
+| E7 | P1 | Eficiência de preparação/persistência | profiling E0/E1, invariantes E3 |
+| E8 | P1 | Resolução de conflitos e replan assistido | E3/E4 |
+| E9 | P2 | Harness adicional, owner background e multimodalidade | gates específicos |
+
+## E0 — baseline e avaliação
+
+Separar workloads determinísticos (runtime) de tarefas de programação (qualidade externa). Registrar configuração, versão, workload, modelo, ambiente e fontes. Medir fila, preparo, execução, captura, persistência, integração, tokens, consumo desconhecido, bytes, sucesso externo, regressões e intervenção humana. Relatório recusa tratar acceptance do próprio owner como sucesso externo.
+
+Aceite: relatórios validados, campos ausentes explícitos, condições comparáveis declaradas e métricas de sucesso definidas antes da avaliação. Benchmarks reais ficam pendentes de execução explicitamente autorizada; fixtures demonstram apenas seus contratos.
+
+## E1 — telemetria
+
+Normalizar observações de lifecycle e usage com identidade, sequência, origem, unidade e semântica delta/cumulative. Persistir usage antes de validar output final. Preservar observações em falhas e restart; deduplicar. Armazenar detalhes limitados sem credentials nem transcripts ilimitados. Expor status/explain compartilhados CLI/MCP com motivos e ações possíveis.
+
+Módulos: `codex-sdk-worker`, `program-worker`, `program-contract`, `program-service`, `program-store`, `program-view`; interfaces públicas CLI/MCP.
+
+Aceite: output inválido não apaga usage observado; duplicatas não somam duas vezes; unknown não é zero; eventos antigos não aprovam sucessor; razões de bloqueio são estruturadas. Telemetria não cria escrita de snapshot por mensagem token a token.
+
+## E2 — scheduling
+
+Filas por run e round-robin explícito entre runs elegíveis. Config owner validada (default quatro, teto inicial existente 32), run e ancestor scopes. Alteração para capacidade menor impede novas admissões sem matar atividades. Reservas uncertain permanecem ativas.
+
+Módulos: `program-scheduler`, `program-service`, `program-contract`, `program-view`.
+
+Aceite: >=3 runs continuamente admissíveis recebem atendimento; quotas respeitadas; parent controls não ocupam slots; release idempotente; cancelamento não vaza slots. Usar barreiras determinísticas, não assertions de throughput baseadas em sleeps curtos.
+
+## E3 — continuidade
+
+Observar processo/thread/workspace/candidato antes de decidir reutilização, resume thread, nova tentativa ou reconcile. SDK já suporta resume; program adapter deve recebê-lo apenas com workspace original compatível e efeitos verificados. Registrar checkpoints e observações, preservar deltas parciais e owners epochs. Expor reconciliação assistida com fatos e desconhecidos.
+
+Módulos: `program-worker`, `codex-sdk-worker`, `managed-workspace`, `program-service`, `program-contract`, `program-store`, `program-owner`, `program-lock`, `program-view`.
+
+Aceite: sem redispatch incerto/escritor duplicado; intactos independentes reutilizados; prazos/budgets preservados; workspace incompatível bloqueia resume; callbacks tardios não alteram sucessor. Não prometer cancelamento de árvore sem adapter capaz de observar essa garantia.
+
+## E4 — autoria e workflows
+
+Três templates owner-validated: revisão sem alteração, bugfix limitado, migration por população fechada. Entrada natural do agente produz proposta de template/IR; proposta não substitui registry. Schemas, scopes, checks, review e parada explícitos. Gerar refs tipadas a partir do registry. Explicar erros por operação/campo e distinguir completion/acceptance/apply. Aproveitar DSL finita e exemplos existentes; não criar interpretador geral.
+
+Módulos: `program-api`, `program-dsl`, `program-types`, `program-structure`, módulos de authoring/templates, `program-view`, CLI/MCP e exemplos.
+
+Aceite: proposta válida contém refs/criteria/checks/scopes/limites; checks obrigatórios não podem desaparecer; caso correto não exige edits; alteração invalida review incompatível; workflows executam com fixtures sem LLM.
+
+## E5 — contexto
+
+Integrar `prepareFabricRepositoryContext` existente ao clone/candidato de programas. Selecionar símbolos, contratos, dependências, checks sugeridos e lacunas por papel/atividade. Contexto limitado e identificado por snapshot; checks sugeridos não executam implicitamente. Ausência de manifesto segue diagnóstico/política explícita.
+
+Aceite: clone atual e contexto correspondem; mudanças revalidam; truncamento explícito; melhoria de qualidade ou eficiência deve ser medida, não inferida de tamanho menor do prompt.
+
+## E6 — recursos
+
+Ledger observado/reservado/estimado/desconhecido, tokens por run/owner, reservas para atividades e avaliação final. Serializar admissão agregada sob owner exclusivo, reservas duráveis associadas à tentativa. Reinício reconstrói saldo/reservas. Monetary reporting somente com modalidade/pricing declarados; subscription não vira dólar fictício. Hard enforcement somente conforme capability do adapter; demais perfis têm admission budget e overshoot possível de trabalho em curso.
+
+Módulos: `program-contract`, `program-service`, `program-scheduler`, `program-store`, `program-worker`, `program-view`.
+
+Aceite: admissões não gastam o mesmo saldo; restart não repõe; unknown policy explícita; atingir limite preserva resultados e bloqueia novos dispatches; revisão/checks conservam reserva. Não transformar orçamento em licença para omitir obrigações.
+
+## E7 — eficiência
+
+Instrumentar cache hit/verificação/cópia/instalação; materialização de workspace; serialização/validação/fsync/bytes. Aplicar melhorias locais que evitem trabalho redundante comprovado. Cache existente permanece verificado; mutable trees não são compartilhadas. Snapshot incremental, GC e cache de respostas LLM são extensões condicionais ao profiling e não obrigatórias sem gargalo demonstrado.
+
+Aceite: ganho demonstrado em workload definido; cache corrupto bloqueia; isolamento, histórico e recuperação permanecem íntegros; artefatos ligados a apply uncertain preservados.
+
+## E8 — conflitos e adaptação
+
+Resolver recebe baseline, candidatos conflitantes e contrato e produz novo candidato, sem aprovação herdada. Requer nova avaliação final. Replan propõe delta sem enfraquecer obrigações; preserva branches intactos. Repetição sem progresso termina explicitamente.
+
+Módulos: `program-service`, contratos/types/structure, worker/workspace, templates/view.
+
+Aceite: conflito não vira approval automático; candidato integrado reavaliado; checks/obligations mantidos; late callbacks fenced. Fencing local e novos operadores só entram por necessidade demonstrada.
+
+## E9 — expansão opt-in
+
+- Segundo harness nativo: schema, identidade, usage, término, cancelamento, isolamento, retomada e late callbacks conformes. CLI externa via command não basta. Adapter Claude explícito com capabilities honestas, sem bypass automático nem inferência real nesta validação.
+- Owner background local: preservar IPC autenticado, lease e recovery; pausar/uncertain não retomam implicitamente. Reutilizar startup existente, sem instalar serviço global silenciosamente.
+- Multimodal: imagem explicitamente entregue pelo adapter, provenance vinculada; receipts não demonstram compreensão. UI exige avaliação integrada final e cobertura do catálogo.
+
+## Mudanças por módulo
+
+| Módulo | Mudança |
+|---|---|
+| program-contract/service | observações, admissão, recovery, compose resolver |
+| program-scheduler | fairness/capacidade/quota |
+| program-store | observações duráveis e métricas; preservação CAS |
+| program-worker/codex-sdk-worker | lifecycle/usage/context/resume/multimodal |
+| managed-environment/workspace | profiling/materialização/compatibilidade |
+| repository-context | contexto por candidato |
+| program-api/dsl/types/structure | autoria e refs typed; resolver options |
+| program-view | diagnóstico e garantias reais |
+| program-owner/lock/project-runtime | exclusividade/background seguro |
+| cli/fabric, agent-memory/mcp, local-task-server | paridade pública e autoria sem dispatch |
+| examples/agent-fabric-v2 | três workflows completos |
+| tests/agent-fabric, scripts, CI | validação focada e redução de redundância |
+
+## Validação rápida e CI
+
+Usar poucos testes agrupados de alto valor para invariantes novas: usage+invalid output+restart, fairness>=3, orçamento concorrente, recovery incompatível, proposta/gate e resolver. Reutilizar fixtures existentes; não adicionar testes que apenas espelham implementação. Não executar modelos reais. Typecheck/lint e geração/check necessários permanecem. Uma rodada focada após integração; repetir só por mudança/falha.
+
+CI: reduzir matrix/smokes redundantes, seleção de PR fail-closed (common/unknown/missing history mantém cobertura ampla), preservar checks de contrato/segurança e checks exigidos. Não apagar testes existentes ou enfraquecer assertions para conseguir green. Branch principal preserva verificação abrangente; mudanças de packaging mantêm smoke relevante.
+
+## Gates e conclusão
+
+G1 integridade; G2 continuidade; G3 operação explicável; G4 qualidade externa nos três workflows; G5 eficiência vs baseline; G6 competitividade controlada. G1-G3 validados deterministicamente. G4-G6 ficam condicionados a avaliações representativas posteriores, não ao sucesso de fixtures nem a implementação local. Documento de evidências deve distinguir implementado, verificado, opt-in e não medido.

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

@@ -0,0 +1,56 @@
+# Forge Agent Fabric — revisão da implementação contra o plano
+
+Data: 2026-10-10. Plano: `WORKFLOW_PROGRAM_COMPETITIVE_PLAN.md`.
+Revisão e correções locais sobre a implementação em andamento, sem commit, push ou publicação.
+
+## Método e resultado
+
+Três subagentes revisaram módulos diferentes daqueles que implementaram: runtime, workers e autoria/CI. A integração principal revisou a interface pública MCP e os limites das evidências. A revisão encontrou bugs e lacunas de implementação, corrigidos nesta entrega. Testes determinísticos foram direcionados aos caminhos afetados; nenhum modelo Codex/Claude real foi executado.
+
+## Correções por prioridade e módulo
+
+| Prioridade / etapa | Problema encontrado | Mudança e critério de aceite |
+|---|---|---|
+| P0 / E3,E5 | Recuperação podia aceitar contexto/evidências diferentes; segunda recuperação podia perder a thread | `program-worker` vincula contexto entregue, observações adicionais e bytes das evidências ao fingerprint; `program-service` persiste threadId no novo dispatch. Retomada compatível passa e incompatibilidades bloqueiam antes do modelo. |
+| P0 / E8 | Colisões arquivo/diretório e diferenças de caixa escapavam; resolver podia descartar arquivos fora de seu scope | `program-service` detecta colisões por trie e exige scope cobrindo todos os arquivos propostos. Resolver ainda produz candidato novo, com avaliação final nova. |
+| P0 / E4 | Templates aceitavam contratos de aprovação/captura sem construir o fluxo necessário | `program-templates` exige approvalSchema compatível, cria waitEvent vinculado e gate autorizado; captura exige migration com population/evidence. Perfis não suportados são rejeitados antes do dispatch. |
+| P0 / E1,E6 | Contadores inválidos ou semânticas misturadas podiam contaminar accounting | `program-observation` valida inteiros seguros, cached ≤ input e semântica por origem antes da persistência. Observações inválidas não alteram registro. |
+| P1 / interface pública | MCP author-types sem argumentos exigia runId e falhava | `agent-memory/mcp` trata a ação separadamente. Chamada autenticada com `{}` chega ao owner; argumentos extras são rejeitados. |
+| P1 / E4 | Autoria podia produzir scopes incompatíveis com executores/policy | Preflight intersecta permissões de acceptance/policy/executor e valida reviewers, checks, implementers e resolver, incluindo override explícito. |
+| P1 / E2 | Capacidade em execução não podia diminuir pela API do host | `program-scheduler` e `program-service.updateRuntimeOptions` preservam attempts ativos e limitam novas admissões. Arquivo de configuração continua aplicado no startup/restart. |
+| P1 / E6 | Usage desconhecido após apply não podia ser reconciliado | Reconciliação autenticada de usage aceita em applied, sem reabrir publicação, gate ou resume. |
+| P1 / workers | UTF-8 dividido entre chunks podia ser corrompido | Workers command/Claude usam decodificação streaming; fixture de subprocesso local preserva caracteres multibyte. |
+| P1 / CI | Bun retorna sucesso com filtro sem testes; guardas poderiam desaparecer silenciosamente | Política valida arquivos/nome dos testes; runner exige linha de resultado passing para cada gate crítico. Cobertura ampla continua nos módulos centrais. |
+| P1 / lifecycle | Razão antiga de espera permanecia após aprovação e sucesso | Serviço limpa reason ao acordar e concluir validamente, preservando razões reais de falha e histórico. |
+| P2 / E0 | Resumo individual não comparava equivalência entre relatórios | `compareBenchmarkReports` e CLI pareada verificam tasks/model/tools/context/contract/budget/criteria. Missing permanece null, contadores inválidos/overflow são rejeitados e entradas diferentes não autorizam superioridade controlada. |
+| P2 / E7 | Perfil não separava cache/preparação/execução | `managed-environment` emite cache.verify/cache.copy/dependencies.install; worker observa workspace, environment, captura e execução, inclusive falhas. Duracões aninhadas não são soma de wall time. |
+
+## Dependências e compatibilidade
+
+- ApprovalSchema e evidence executors pertencem ao registro do owner; workers não autorizam aprovação humana.
+- Resume depende de término observado, reconciliação, workspace original e fingerprint compatível. Markers antigos sem a nova vinculação não são reescritos para parecer compatíveis.
+- Redução de capacidade usa API confiável do host. Não há watcher automático nem parâmetro de workflow alterando a capacidade global.
+- Review/bugfix convenience templates não suportam diretamente captura de população; migration suporta o perfil explícito. Fluxos UI mais amplos continuam disponíveis via IR existente, não devem ser apresentados como autoria automática universal.
+- Métricas de preparação podem ocorrer antes da admissão; orçamento de tokens não mede custo de CPU/storage e não garante teto monetário.
+
+## Verificação focada
+
+| Grupo | Evidência |
+|---|---|
+| Runtime | Quatro testes focados: counters inválidos/semântica, recuperação dupla, resize sem interrupção, reconciliação pós-apply e conflitos exact/hierarchy/case. Caso de conflito: 8,78 s após trie. |
+| Workers | Dois testes direcionados, 23 assertions, aproximadamente 3 s; fingerprint adicional com 4 assertions. Git/contexto reais locais, sem provedor. |
+| Interface pública | Dois testes, 17 assertions, 2,95 s; inclui owner HTTP local autenticado para MCP author-types. |
+| Autoria/templates/benchmark/CI | Sete testes passaram em 4,99 s, incluindo aprovação humana consumida e gate novo. Seis testes unitários passaram em 316 ms após a guarda final de resultados de CI; sintaxe do runner válida. |
+| Typecheck global e lint | Exit 0 em ambos. |
+| Geração/export e framework | Geração, exports generic/codex e framework aprovados; 11 etapas, nenhuma falha, typecheck/testes omitidos somente nesta execução. Aviso existente FORGE_RLS_PGLITE_NOT_AUTHORITATIVE preservado. |
+
+Os números correspondem a rodadas específicas e não devem ser somados como testes únicos. Verificação de framework omite suíte completa e repetição de typecheck, executados separadamente no escopo indicado. Não houve instalação de dependências, GitHub Actions ou inferência paga.
+
+## O que ainda falta
+
+1. **P0 de avaliação, G4–G6:** executar avaliação independente pareada de qualidade, eficiência e robustez em tarefas representativas. Depende de inputs controlados, critérios externos e medição completa. Sem essa evidência, não afirmar superioridade sobre Claude Code.
+2. **P1 operacional:** smoke com versão real compatível do Claude CLI e execução da nova CI no GitHub. Fixtures de protocolo não comprovam compatibilidade instalada ou duração real da CI.
+3. **P2 de conveniência:** ampliar templates review/bugfix para perfis UI/população, se necessário ao produto. Hoje a rejeição explícita impede gerar programas impossíveis; IR customizado oferece o fluxo completo.
+4. **Condicionais do plano:** cache entre runs, snapshots incrementais, GC e owner distribuído permanecem extensões, dependentes de medição ou necessidade concreta. Não são apresentados como implementados.
+
+Os artefatos gerados são atualizados pelo gerador. Mudanças permanecem locais; arquivos preexistentes foram preservados. Esta revisão delimita a implementação e suas evidências, sem certificar produção ou qualidade de modelos.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.71",
+  "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",
@@ -28,6 +29,9 @@
     "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.71","releaseId":"forgeos@0.1.0-alpha.71+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.71 input=c1757bb141bbcdd4d235a6d1af230b3a767ec7e4354f7fc3afb49fd46e893f06 content=cd16693ecfd3d8410340a10ca8d2fbd0c9a99361acd460af97c00a8c58a5032d
+// @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.71",
-  "releaseId": "forgeos@0.1.0-alpha.71+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();
+  });
+}