@daniellins/power-claude 0.16.3

package/scripts/pod-export-executor.cjs

@@ -0,0 +1,678 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pod-export-executor.cjs — ENTRYPOINT de PRODUÇÃO do épico pod-export (F2, Story SF10.2).
+ *
+ * Dirige a Messages API da Anthropic com o prompt e o modelo PINADO vindos do BUNDLE compilado
+ * por F1 (`pod-export-compile.cjs`), usando SÓ as 4 tools confinadas (`pod-export-tools.cjs`), e
+ * REUSA o motor de produção `pc-run-pod.cjs` POR IMPORT (state/vetos/verificação-em-disco/retomada
+ * — ZERO reimplementação). Industrializa o PoC `spike/pod-export-c3/` (barra 7/7), consumindo o
+ * BUNDLE (não a compilação manual do spike) e corrigindo os 2 bugs medidos no spike (loop
+ * descartando tool_use em max_tokens; teto pequeno em fases multi-artefato).
+ *
+ * CLI (ADR-018 Adendo F2 / Decisão 1):
+ *   node scripts/pod-export-executor.cjs <bundle-dir> <run|resume|approve|status> [runId] \
+ *        [--input <payload.json>] [--runs-root <dir>] [--lock <path>] [--kill-during <phase>]
+ *
+ * Decisões vinculantes (seção "Arquitetura" da story + ADR-018 Adendo F2):
+ *   DF2-1  `pc-run-pod.cjs` INTOCADO; framework é dependência versionada; AC16 fail-loud:
+ *          framework_version do motor == framework_version do lock do bundle (senão RECUSA).
+ *   DF2-2  isolamento de memória por CÓDIGO: memoryPodDir efêmero por run (nunca o memory/ do bundle).
+ *   DF2-3  whitelist de fetch derivada do payload declarado; isBlockedHost barra incondicionalmente.
+ *   DF5-1  (SF10.8) MATERIALIZAÇÃO da referência: os inputs pinados do run são copiados POR
+ *          CÓDIGO para `<runDir>/inputs/` no arranque (`materializeInputs`), porque o motor é
+ *          cego ao `inputs_dir` e o veto `phash-gate.cjs` precisa alcançar a referência por um
+ *          path FIXO. Determinística — NÃO depende de o modelo chamar `read_image`. O motor
+ *          segue INTOCADO (a mudança vive aqui, cujo blast radius não alcança pc-run-pipeline).
+ *   DF-SF10.11-1/-2 (SF10.11, Adendo F6-a) FIXER determinístico PRÉ-VETO: entre `runPhase` e
+ *          `motor.advance`, `pod-export-postprocess.cjs` normaliza a classe MECÂNICA (tabela
+ *          declarada) em TODOS os paths de `write_file` da tentativa — não só o artefato que o
+ *          veto lê. Módulo in-process do export: NÃO blessed, NÃO command_check, motor INTOCADO.
+ *   DF-SF10.12-1 (SF10.12, Adendo F6-a) CORREÇÃO GUIADA PÓS-VETO: quando `motor.advance` devolve
+ *          `blocked/verification_failed`, a tentativa seguinte NÃO reamostra às cegas — ela RETOMA
+ *          a MESMA conversa (`runPhase` devolve `messages`, `execPhase` repassa, `drive` reinjeta)
+ *          com as `failures[]` REAIS do motor + o diff do fixer + a ordem de EDITAR, não refazer.
+ *          Antes desta story cada retry reconstruía `userContent` do zero e `messages` nascia
+ *          vazio: o artefato reprovado NUNCA entrava no contexto (`DF-SF10.11+12-0(b)`).
+ *   DF-SF10.12-2 (SF10.12) ZERO LIMITES NOVOS: a correção guiada CONSOME o `MAX_RETRY` que já
+ *          existe. Nenhuma constante, contador ou laço novo — o número de edições guiadas é
+ *          `MAX_RETRY - 1`, DERIVADO. `MAX_TOKENS`/`MAX_ITERS` seguem governando `runPhase`.
+ *          LIMITE DE PROCESSO DECLARADO: a conversa vive em memória; após crash/`resume` a fase
+ *          recomeça no comportamento atual (`buildUserContent` fresco), sem convergência herdada.
+ *   DF-SF10.19-2 (SF10.19, Adendo F6-b) A PROVENIÊNCIA BLOQUEIA AQUI, não no veto do wf: o blessed
+ *          `phash-gate.cjs` virou MEDIDA-ONLY (nunca sai não-zero por insumo) porque o mesmo
+ *          `wf-*.yaml` é consumido por um 2º driver não-confinado (`pc-run-pod.cjs`), onde a
+ *          premissa da invariante é INSATISFAZÍVEL (DF-SF10.19-0). O invariante não perdeu força:
+ *          mudou de HOSPEDEIRO — `tools.assertRunProvenance` roda no fim de `execPhase`, antes de
+ *          `motor.advance`, e violação é HALT do run (SEM consumir `MAX_RETRY`, DF-SF10.19-2/e3).
+ *   DF5-6  (SF10.8, fix round) PROVENIÊNCIA: cada referência materializada tem o sha256
+ *          registrado no ledger `<runDir>.provenance.json` (IRMÃO do runDir ⇒ fora do alcance
+ *          de escrita das tools), e cada imagem gravada por `openrouter_image` também. É o que
+ *          o veto passa a exigir — o limiar perceptual (R4) foi FALSIFICADO e revogado.
+ *
+ * NÃO faz: serviço-irmão/systemd/deploy (SF10.3), login/UI/aprovação por identidade (F3),
+ * release/selo/paridade selada (F4). Sem git push/PR (exclusivo pc-devops).
+ *
+ * Node >= 18. Rede INJETÁVEL (callModel/tool transports) → suíte de CI hermética.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const https = require('node:https');
+
+// MOTOR DE PRODUÇÃO reusado por IMPORT (read-only, INTOCADO — DF2-1 / AC9).
+const motor = require('./pc-run-pod.cjs');
+const tools = require('./pod-export-tools.cjs');
+// FIXER determinístico pré-veto (SF10.11 / DF-SF10.11-2): módulo in-process do EXPORT — NÃO é
+// blessed, NÃO é command_check, NÃO é declarável em wf-*.yaml. Roda entre runPhase e motor.advance.
+const postprocess = require('./pod-export-postprocess.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const MAX_TOKENS = 8192; // Achado 3/5 do spike: 4096 truncava assembly (7 HTMLs). FIXO.
+const MAX_ITERS = 30;    // teto de turns da API por fase (assembly multi-peça precisa de folga).
+const MAX_RETRY = 3;     // tentativas por fase quando o veto de máquina reprova (feedback real).
+
+// ---------------------------------------------------------------------------
+// Bundle + coerência de versão (AC16 / DF2-1).
+// ---------------------------------------------------------------------------
+
+function loadBundle(bundleDir) {
+  const root = path.resolve(bundleDir);
+  const bundleJsonPath = path.join(root, 'bundle.json');
+  if (!fs.existsSync(bundleJsonPath)) throw new Error(`bundle inválido: bundle.json ausente em ${bundleDir}`);
+  const bundle = JSON.parse(fs.readFileSync(bundleJsonPath, 'utf8'));
+  const wfPath = path.join(root, 'workflow.yaml');
+  if (!fs.existsSync(wfPath)) throw new Error(`bundle inválido: workflow.yaml ausente em ${bundleDir}`);
+  if (!bundle.modelo_pinado || !bundle.modelo_pinado.agents) throw new Error('bundle inválido: modelo_pinado.agents ausente em bundle.json');
+  return { root, bundle, wfPath };
+}
+
+/** framework_version do motor instalado (mesma fonte que o compilador usa: package.json do repo). */
+function engineFrameworkVersion() {
+  return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version;
+}
+
+/** Localiza o lock do bundle: --lock explícito; senão exports/<pod>/export.lock.json no repo. */
+function resolveLockPath(bundle, lockOverride) {
+  if (lockOverride) return path.resolve(lockOverride);
+  return path.join(REPO_ROOT, 'exports', bundle.pod, 'export.lock.json');
+}
+
+/**
+ * AC16 / DF2-1 — invariante fail-loud: o motor NÃO roda blessed de versão diferente da que a
+ * paridade selou. Divergência entre framework_version do motor e do lock = run RECUSADO.
+ */
+function assertFrameworkCoherence(bundle, lockPath, engineVersion = engineFrameworkVersion()) {
+  if (!fs.existsSync(lockPath)) {
+    throw new Error(`AC16: export.lock.json não encontrado (${lockPath}) — impossível conferir coerência de framework_version. Run RECUSADO.`);
+  }
+  let lock;
+  try { lock = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch (e) { throw new Error(`AC16: lock ilegível (${lockPath}): ${e.message}`); }
+  const lockVersion = lock.framework_version;
+  if (!lockVersion) throw new Error(`AC16: lock sem framework_version (${lockPath}) — run RECUSADO.`);
+  if (String(lockVersion) !== String(engineVersion)) {
+    throw new Error(
+      `AC16: MISMATCH de framework_version — motor instalado=${engineVersion}, lock do bundle=${lockVersion}. ` +
+      `O bundle foi selado contra outra versão do framework; blessed/vetos podem divergir da paridade. Run RECUSADO (fail-loud).`,
+    );
+  }
+  return { engineVersion, lockVersion };
+}
+
+// ---------------------------------------------------------------------------
+// Loop de tool-use da Messages API (industrialização de executor.cjs do spike).
+// ---------------------------------------------------------------------------
+
+const TOOL_DEFS = [
+  { name: 'http_fetch', description: 'Busca uma URL via HTTP GET. Só hosts da whitelist do run; sem SSRF. Retorna o corpo (texto).', input_schema: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] } },
+  { name: 'openrouter_image', description: 'Gera uma imagem via OpenRouter (modelo PINADO do bundle) e salva como arquivo no runDir. Confirma por path+tamanho (nunca devolve o base64).', input_schema: { type: 'object', properties: { prompt: { type: 'string' }, out_path: { type: 'string', description: 'ex.: assets/cover-bg.png (relativo ao runDir)' } }, required: ['prompt', 'out_path'] } },
+  { name: 'write_file', description: 'Escreve um arquivo de texto confinado ao runDir (sem traversal, sem path absoluto). Em fases multi-artefato, escreva UM arquivo por turn.', input_schema: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] } },
+  { name: 'read_image', description: 'Referência pinada "inputs:<nome>" → devolve a imagem para você VER (multimodal). Imagem já gerada (path no runDir) → confirma por path+tamanho, sem re-enviar o base64.', input_schema: { type: 'object', properties: { ref: { type: 'string' } }, required: ['ref'] } },
+];
+
+/** Chamada real à Messages API. Rede INJETÁVEL via `transport` (CI hermética). */
+function anthropicCall({ apiKey, model, system, messages, toolDefs, maxTokens = MAX_TOKENS, transport = null }) {
+  const payload = { model, max_tokens: maxTokens, system, messages, tools: toolDefs };
+  if (transport) return Promise.resolve(transport(payload));
+  const body = JSON.stringify(payload);
+  return new Promise((resolve, reject) => {
+    const req = https.request('https://api.anthropic.com/v1/messages', {
+      method: 'POST', timeout: 120000,
+      headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+    }, (res) => {
+      let s = '';
+      res.on('data', (d) => { s += d; });
+      res.on('end', () => { try { const j = JSON.parse(s); if (j.type === 'error') return reject(new Error(`anthropic ${j.error.type}: ${j.error.message}`)); resolve(j); } catch (e) { reject(new Error(`parse: ${e.message} :: ${s.slice(0, 200)}`)); } });
+    });
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout anthropic')); });
+    req.on('error', reject);
+    req.write(body); req.end();
+  });
+}
+
+async function execTool(name, input, env) {
+  if (name === 'http_fetch') {
+    const r = await tools.httpFetch(input.url, { whitelistHosts: env.whitelistHosts, transport: env.httpTransport });
+    return r.ok ? { text: `status ${r.status} (${r.bytes}B)\n${r.body}` } : { text: `ERRO: ${r.error}`, isError: true };
+  }
+  if (name === 'write_file') {
+    try { const r = tools.writeFile(input.path, input.content, { runDir: env.runDir }); return { text: `escrito: ${r.path} (${r.bytes}B)` }; }
+    catch (e) { return { text: `ERRO: ${e.message}`, isError: true }; }
+  }
+  if (name === 'openrouter_image') {
+    const r = await tools.openrouterImage(input.prompt, input.out_path, { runDir: env.runDir, model: env.imageModel, apiKey: env.orKey, imageTransport: env.imageTransport });
+    return r.ok ? { text: `imagem salva: ${r.path} (${r.bytes}B, modelo ${r.model}) — confirmada por path+tamanho` } : { text: `ERRO: ${r.error}`, isError: true };
+  }
+  if (name === 'read_image') {
+    const r = tools.readImage(input.ref, { runDir: env.runDir, inputsDir: env.inputsDir });
+    if (!r.ok) return { text: `ERRO: ${r.error}`, isError: true };
+    if (r.kind === 'reference') return { image: { base64: r.base64, mediaType: r.mediaType } };
+    return { text: `imagem confirmada em disco: ${r.path} (${r.bytes}B). NÃO reenviada como base64 (economia de contexto).` };
+  }
+  return { text: `tool desconhecida: ${name}`, isError: true };
+}
+
+function toolResultContent(out) {
+  if (out.image) return [{ type: 'image', source: { type: 'base64', media_type: out.image.mediaType, data: out.image.base64 } }, { type: 'text', text: 'referência carregada (veja acima).' }];
+  return [{ type: 'text', text: out.text }];
+}
+
+/**
+ * Acrescenta um turn `user` a uma conversa VIVA sem quebrar a alternância de papéis da Messages API.
+ *
+ * `runPhase` pode parar com a última mensagem no papel `user` (tool_results do turn que estourou
+ * `MAX_ITERS`). Empilhar outra mensagem `user` ali seria REJEITADO pela API ("roles must
+ * alternate"), então o texto entra como mais um bloco DENTRO daquele turn. Não-mutante de
+ * propósito: a conversa anterior é insumo de auditoria e não pode ser reescrita por efeito colateral.
+ */
+function appendUserTurn(messages, text) {
+  const last = messages[messages.length - 1];
+  if (last && last.role === 'user' && Array.isArray(last.content)) {
+    return messages.slice(0, -1).concat([{ role: 'user', content: last.content.concat([{ type: 'text', text }]) }]);
+  }
+  return messages.concat([{ role: 'user', content: text }]);
+}
+
+/**
+ * Roda UMA fase até o agente parar (sem tool_use) ou o teto de iterações. AC2 (regressão do bug
+ * do spike): em stop_reason=max_tokens COM tool_use, NÃO descarta as tools — executa e CONTINUA;
+ * só encerra quando a resposta NÃO contém bloco tool_use. `callModel` injetável (CI).
+ *
+ * `priorMessages` (SF10.12 / DF-SF10.12-1): conversa VIVA da tentativa anterior desta MESMA fase.
+ * Quando presente, `userContent` é a MENSAGEM DE CORREÇÃO (não o contrato da fase) e a conversa
+ * CONTINUA — o modelo segue vendo o artefato que ele mesmo escreveu e as tools que já executou.
+ * Ausente (o padrão, e todo `resume`), a conversa nasce do zero: comportamento pré-SF10.12.
+ * Devolve `messages` para que `drive` possa reinjetá-lo na tentativa seguinte.
+ */
+async function runPhase({ system, userContent, priorMessages = null, apiKey, model, env, maxIters = MAX_ITERS, onLog, killAfterTurn = 0, callModel = anthropicCall }) {
+  const messages = Array.isArray(priorMessages) && priorMessages.length > 0
+    ? appendUserTurn(priorMessages, userContent)
+    : [{ role: 'user', content: userContent }];
+  let iters = 0; let inTok = 0; let outTok = 0; const toolTrail = [];
+  while (iters < maxIters) {
+    iters++;
+    const resp = await callModel({ apiKey, model, system, messages, toolDefs: TOOL_DEFS, maxTokens: MAX_TOKENS, transport: env.apiTransport });
+    if (resp.usage) { inTok += resp.usage.input_tokens || 0; outTok += resp.usage.output_tokens || 0; }
+    if (killAfterTurn && iters >= killAfterTurn) {
+      if (onLog) onLog(`  >>> KILL SIMULADO no MEIO da fase (após turn ${iters}, antes do artefato). PID ${process.pid} saindo hard.`);
+      process.exit(137);
+    }
+    messages.push({ role: 'assistant', content: resp.content });
+    const toolUses = (resp.content || []).filter((c) => c.type === 'tool_use');
+    if (onLog) onLog(`  turn ${iters}: stop=${resp.stop_reason} tools=[${toolUses.map((t) => t.name).join(',') || '—'}]`);
+    // AC2: encerra SOMENTE quando não há tool_use (end_turn/texto puro). Em max_tokens COM
+    // tool_use, o one-file-per-turn evita truncar o bloco e o loop continua.
+    if (toolUses.length === 0) break;
+    const results = [];
+    for (const tu of toolUses) {
+      const out = await execTool(tu.name, tu.input, env);
+      toolTrail.push({ name: tu.name, ok: !out.isError, arg: tu.name === 'write_file' ? tu.input.path : (tu.name === 'openrouter_image' ? tu.input.out_path : (tu.input.url || tu.input.ref || '')) });
+      results.push({ type: 'tool_result', tool_use_id: tu.id, content: toolResultContent(out), is_error: Boolean(out.isError) });
+    }
+    messages.push({ role: 'user', content: results });
+  }
+  return { iters, inTok, outTok, toolTrail, messages };
+}
+
+// ---------------------------------------------------------------------------
+// Ponte bundle → user content da fase (o bundle.user.md é só o CONTRATO/template; o
+// executor injeta os INPUTS pinados do run + o contexto das fases anteriores + a diretiva
+// de runtime de escrita-por-peça). Nenhum knowledge/agente é reinjetado (já está no system.md).
+// ---------------------------------------------------------------------------
+
+function readIf(p) { return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : ''; }
+
+function pinnedInputsBlock(payload) {
+  const meta = new Set(['pod', 'workflow', 'fetch_allow_hosts', 'inputs_dir']);
+  const pinned = {};
+  for (const [k, v] of Object.entries(payload || {})) if (!meta.has(k)) pinned[k] = v;
+  if (Object.keys(pinned).length === 0) return '';
+  return ['## Inputs FIXADOS do run (não substitua; use-os como fonte pinada)', '```json', JSON.stringify(pinned, null, 2), '```'].join('\n');
+}
+
+function priorArtifactsBlock(bundleRoot, runDir, order, stepId) {
+  const idx = order.indexOf(stepId);
+  const parts = [];
+  for (let i = 0; i < idx; i++) {
+    const prev = order[i];
+    const content = readIf(path.join(runDir, 'artifacts', `${prev}.md`));
+    if (content.trim()) parts.push([`## Artefato da fase anterior — ${prev}`, '```', content.trim(), '```'].join('\n'));
+  }
+  return parts.join('\n\n');
+}
+
+function buildUserContent({ bundleRoot, stepId, payload, runDir, order, whitelist }) {
+  const contract = readIf(path.join(bundleRoot, 'phases', stepId, 'user.md'));
+  const artRel = path.join('artifacts', `${stepId}.md`);
+  const parts = [`# RODADA — fase ${stepId}`];
+  const pinned = pinnedInputsBlock(payload);
+  if (pinned) parts.push(pinned);
+  const prior = priorArtifactsBlock(bundleRoot, runDir, order, stepId);
+  if (prior) parts.push(prior);
+  parts.push(contract);
+  parts.push([
+    '## Execução (runtime server-side)',
+    `- Escreva o artefato final da fase com write_file EXATAMENTE em: ${artRel} (path relativo ao runDir).`,
+    `- Para buscar dados, use http_fetch — SÓ os hosts da whitelist deste run são permitidos: ${whitelist.join(', ') || '(nenhum)'}. Hosts privados/metadata são bloqueados.`,
+    '- Se a fase produz MÚLTIPLOS arquivos (ex.: peças HTML), escreva UM arquivo por turn (um único write_file por vez), aguarde a confirmação e escreva o próximo — nunca despeje tudo num turn (trunca).',
+    '- Gere imagens só com openrouter_image (modelo pinado). Falha de API = pare, nunca substitua (regra de ouro do pod). Confirme imagens geradas por path+tamanho; não peça o base64 de volta.',
+    '- Ao terminar o artefato final da fase, pare (não peça confirmação).',
+  ].join('\n'));
+  return parts.join('\n\n');
+}
+
+/**
+ * MENSAGEM DE CORREÇÃO GUIADA (SF10.12 / `DF-SF10.12-1`) — o turn `user` que retoma a conversa
+ * depois de `motor.advance` reprovar. Substitui a reamostragem cega de antes.
+ *
+ * Três insumos, exatamente os da decisão:
+ *   (i)   as `failures[]` REAIS do motor, LITERAIS (AC5) — nunca resumo/paráfrase. Quem julga é
+ *         `verifyStep`/`evalVeto`; reescrever o veredito da autoridade seria fabricar oráculo.
+ *   (ii)  o diff do FIXER da SF10.11, se houve, via `postprocess.renderFixMessage` — sem ele o
+ *         modelo reescreve por cima da normalização mecânica que já está em disco.
+ *   (iii) a ordem de EDITAR o que existe, não refazer a fase. É a diferença inteira entre esta
+ *         tentativa e as três amostras independentes que o retry produzia (`DF-SF10.11+12-0(b)`).
+ *
+ * Sem `artRel` nem contrato da fase reinjetados: eles já estão na conversa que está sendo retomada.
+ */
+function buildCorrectionContent({ stepId, attempt, failures, fixReport }) {
+  const list = (failures || []).map((f) => String(f));
+  const parts = [
+    `# VERIFICAÇÃO DE MÁQUINA REPROVOU — fase ${stepId} (tentativa ${attempt})`,
+    [
+      'O verificador determinístico do motor (não eu, não você) rodou sobre o que está EM DISCO e',
+      'devolveu as falhas abaixo. Elas são o veredito LITERAL da máquina, transcrito sem edição:',
+      '',
+      ...(list.length > 0 ? list.map((f) => `- ${f}`) : ['- (o motor reprovou sem detalhar falhas)']),
+    ].join('\n'),
+  ];
+  const fixBlock = postprocess.renderFixMessage(fixReport);
+  if (fixBlock) parts.push(fixBlock);
+  parts.push([
+    '## O QUE FAZER AGORA — EDITE, não refaça',
+    '- O artefato e os demais arquivos que você escreveu CONTINUAM EM DISCO, do jeito que estão acima.',
+    '- Corrija EXATAMENTE as falhas listadas, com a menor alteração possível. Não reescreva o que já passou.',
+    '- Regrave com write_file APENAS os arquivos que precisam mudar — reenvie o conteúdo COMPLETO do arquivo corrigido.',
+    '- NÃO gere imagem de novo: as imagens desta fase já estão em disco e foram confirmadas nesta conversa. Regerá-las custa dinheiro e não corrige nenhuma falha de texto.',
+    '- Não recomece a fase do zero e não repita as buscas que você já fez.',
+    '- Terminada a correção, pare (não peça confirmação).',
+  ].join('\n'));
+  return parts.join('\n\n');
+}
+
+// ---------------------------------------------------------------------------
+// Driver: reusa o motor por import (mesma lógica do spike run-c3.cjs), sem reimplementar
+// state/vetos/verificação/retomada. execPhase produz o artefato; motor.advance VERIFICA em disco.
+// ---------------------------------------------------------------------------
+
+/**
+ * Executa UMA tentativa da fase. `guided` (SF10.12) é `{ messages, correction }` da tentativa
+ * anterior REPROVADA: presente ⇒ a conversa CONTINUA com a mensagem de correção; ausente ⇒ a
+ * conversa nasce de `buildUserContent` (1ª tentativa da fase, e TODO `resume` — DF-SF10.12-1).
+ * Um único ramo, sem caminho morto: a correção nunca existe sem a conversa que ela corrige.
+ */
+async function execPhase(ctx, run, stepId, guided, killAfterTurn) {
+  const bundle = run.bundle;
+  const model = bundle.modelo_pinado.agents[stepId];
+  if (!model) throw new Error(`fase "${stepId}" sem modelo pinado em bundle.json (modelo_pinado.agents) — nunca hardcodar (AC3)`);
+  const system = readIf(path.join(run.bundleRoot, 'phases', stepId, 'system.md'));
+  const priorMessages = guided ? guided.messages : null;
+  const userContent = guided
+    ? guided.correction
+    : buildUserContent({ bundleRoot: run.bundleRoot, stepId, payload: run.payload, runDir: ctx.runDir, order: ctx.order, whitelist: run.whitelist });
+  const env = {
+    runDir: ctx.runDir,
+    inputsDir: run.inputsDir,
+    whitelistHosts: run.whitelist,
+    imageModel: bundle.modelo_pinado.image, // AC3: modelo de imagem pinado do bundle.
+    orKey: run.orKey,
+    apiTransport: run.deps.apiTransport,
+    httpTransport: run.deps.httpTransport,
+    imageTransport: run.deps.imageTransport,
+  };
+  const r = await runPhase({ system, userContent, priorMessages, apiKey: run.anthropicKey, model, env, onLog: run.log, killAfterTurn: killAfterTurn || 0, callModel: run.deps.callModel || anthropicCall });
+  run.log(`  [${stepId}] ${r.iters} turns, tools=${r.toolTrail.map((t) => t.name).join(',') || '—'}`);
+  // PASSO 2 do laço (SF10.11 / DF-SF10.11+12-1): o FIXER determinístico é o ÚLTIMO ESCRITOR ANTES
+  // DE TODA VERIFICAÇÃO. Domínio = os paths de `write_file` DESTA tentativa (DF-SF10.11-1) — cobre
+  // as 7 peças HTML, não só o artefato que o veto lê. `motor.advance` roda logo depois, em `drive`,
+  // e continua sendo a última linha: o fixer reduz quantas vezes o veto DISPARA, nunca o substitui.
+  // Fail-loud de propósito (sem try/catch): erro aqui é bug de domínio e o run deve PARAR.
+  const fix = postprocess.postProcessAttempt({ runDir: ctx.runDir, toolTrail: r.toolTrail, log: run.log });
+  // PASSO 3 do laço (SF10.19 / DF-SF10.19-2/e2): ASSERÇÃO DE PROVENIÊNCIA — o invariante que a
+  // SF10.8 entregou como `command_check` e que NÃO pode viver num veto de wf, porque o mesmo yaml é
+  // consumido por um driver não-confinado (`pc-run-pod.cjs`), onde a premissa dele é insatisfazível
+  // (DF-SF10.19-0). Aqui a premissa vale: as 4 tools são a única porta de bytes deste run.
+  // ONDE: última linha de `execPhase`, DEPOIS do fixer (que é o último escritor) e imediatamente
+  // antes de `motor.advance` em `drive` — nenhuma escrita acontece entre uma coisa e outra, então
+  // não há janela para gravar depois da asserção e antes da verificação.
+  // FORMA: módulo in-process do EXPORT (não blessed, não `command_check`, não declarável por pod),
+  // mesmo slot do fixer (precedente `DF-SF10.11-2`), fail-loud SEM try/catch: lançar aqui é o HALT
+  // do run (`DF-SF10.19-2/e3`) — a exceção atravessa o laço de tentativas SEM consumir `MAX_RETRY`,
+  // porque violação de proveniência não é conteúdo que o modelo possa corrigir. Nenhum contador,
+  // constante ou limite novo nasce disto (`MAX_TOKENS`/`MAX_ITERS`/`MAX_RETRY` seguem os únicos 3).
+  // HERANÇA (DF-SF10.19-4): todo driver de bundle futuro que rode uma fase passa por `execPhase` —
+  // é o ponto que ele teria de reescrever de propósito para não asserir.
+  tools.assertRunProvenance({
+    runDir: ctx.runDir,
+    stepId,
+    requireNonVacuous: phasesRequiringRefs(run.bundleRoot).includes(stepId),
+  });
+  // Usage da fase (DF3-4): tokens acumulados no runPhase + imagens OpenRouter geradas com sucesso
+  // (contadas do toolTrail — barato). Agregado por drive ao longo do run e exposto no RESULTADO.
+  const images = r.toolTrail.filter((t) => t.name === 'openrouter_image' && t.ok).length;
+  // `fix` sobe junto do usage: é evidência de auditoria (AC4) E o insumo ESTRUTURADO que a mensagem
+  // de correção da SF10.12 consome (DF-SF10.12-1(ii)) — não só log local.
+  // `messages` (SF10.12): a conversa VIVA desta tentativa, para `drive` retomá-la se o veto reprovar.
+  // `toolTrail` sobe junto porque é o ORÁCULO da reivindicação de custo (AC3): zero `openrouter_image`
+  // na tentativa guiada é verificável nele, não em relato.
+  return { input_tokens: r.inTok || 0, output_tokens: r.outTok || 0, images, fix, messages: r.messages, toolTrail: r.toolTrail };
+}
+
+function currentState(state, order) {
+  const running = order.find((id) => state.steps[id].status === 'running');
+  const awaiting = order.find((id) => state.steps[id].status === 'awaiting_approval');
+  const allDone = order.every((id) => state.steps[id].status === 'done');
+  return { running, awaiting, allDone };
+}
+
+async function drive(ctx, run, { killDuring } = {}) {
+  const order = ctx.order;
+  // Usage AGREGADO do run (DF3-4) — somado a cada fase e exposto no RESULTADO final (o ledger do
+  // serviço lê `result.usage`). Não altera fases/tools/vetos/coerência/retomada: só observa.
+  const usage = { input_tokens: 0, output_tokens: 0, images: 0 };
+  // AC4 (SF10.11) — trilha COMPACTA do fixer determinístico por tentativa que mudou algo. O
+  // relatório COMPLETO (com diff por linha) não entra aqui: ele viaja em `lastFix`, que é o insumo
+  // da mensagem de correção da SF10.12 (DF-SF10.12-1(ii)). Aqui fica só o que um operador precisa
+  // ler no ledger da fila, limitado por construção (fases x MAX_RETRY).
+  const fixes = [];
+  while (true) {
+    const state = motor.readState(ctx.statePath); ctx.state = state;
+    const { running, awaiting, allDone } = currentState(state, order);
+    if (awaiting) { run.log(`\n>>> CHECKPOINT HUMANO: fase "${awaiting}" em awaiting_approval. Rode: approve ${state.run_id}`); return { awaiting, usage, fixes }; }
+    if (allDone) { run.log('\n>>> PIPELINE COMPLETO (todas as fases done).'); return { complete: true, usage, fixes }; }
+    if (!running) { run.log('\n>>> parado sem fase running (state inconsistente?)'); return { halted: true, usage, fixes }; }
+    const killMid = killDuring && killDuring === running;
+    let ok = false;
+    // Último relatório do fixer da fase corrente. SF10.11 o PRODUZ e o CARREGA até aqui; a SF10.12
+    // o CONSOME (junto das `failures[]` reais) ao retomar a conversa em vez de reamostrar às cegas.
+    let lastFix = null;
+    // PASSO 4 do laço (SF10.12 / DF-SF10.12-1): a conversa VIVA da fase corrente. `null` na 1ª
+    // tentativa e em TODO `resume` (memória de PROCESSO, limite declarado, nunca persistida no
+    // runDir). Preenchida só quando o veto reprova ⇒ custo ZERO no caminho limpo.
+    // Escopo: declarada DENTRO do `while` ⇒ morre com a fase; nenhuma conversa vaza entre fases.
+    let guided = null;
+    for (let attempt = 1; attempt <= MAX_RETRY; attempt++) {
+      const phaseUsage = await execPhase(ctx, run, running, guided, killMid ? 1 : 0);
+      usage.input_tokens += phaseUsage.input_tokens; usage.output_tokens += phaseUsage.output_tokens; usage.images += phaseUsage.images;
+      lastFix = phaseUsage.fix || null;
+      if (lastFix && lastFix.changed) fixes.push({ step: running, attempt, files: lastFix.files.length, replacements: lastFix.totalReplacements });
+      const res = motor.advance(ctx); // VERIFICAÇÃO EM DISCO (verifyStep/evalVeto) — motor de produção, INTOCADO.
+      if (res.action === 'blocked' && res.reason === 'verification_failed') {
+        const failures = res.failures || [];
+        run.log(`  [${running}] VETO DISPAROU (tentativa ${attempt}): ${failures.join(' | ')}`);
+        // DF-SF10.11+12-2(3): quando o veto reprova, o diff do fixer aparece AO LADO das falhas, na
+        // mesma tentativa — se foi o fixer que causou a reprovação, as duas causas ficam visíveis
+        // juntas, nunca a duas tentativas de distância.
+        if (lastFix && lastFix.changed) run.log(`  [${running}] (o fixer havia alterado ${lastFix.files.length} arquivo(s) nesta tentativa: ${lastFix.files.map((f) => f.path).join(', ')})`);
+        // AC5 — auditoria do que o MODELO recebe: cada falha REAL do motor, uma por linha, LITERAL.
+        // O log do run precisa permitir conferir que nenhuma paráfrase foi entregue no lugar do
+        // veredito da máquina; sem isso a promessa "failures reais" não é verificável depois do fato.
+        // Sem laço de statement de propósito (AC2/DF-SF10.12-2): esta story não acrescenta NENHUMA
+        // estrutura de repetição ao arquivo — o único laço que governa tentativas segue sendo o
+        // `for (attempt <= MAX_RETRY)` acima.
+        if (failures.length > 0) run.log(failures.map((f) => `  [${running}] → entregue ao modelo (literal): ${f}`).join('\n'));
+        if (attempt < MAX_RETRY) {
+          // Retoma a MESMA conversa em vez de reamostrar às cegas. Nenhum contador/limite novo:
+          // quem governa quantas edições guiadas existem é o `MAX_RETRY` acima (DF-SF10.12-2).
+          guided = {
+            messages: phaseUsage.messages,
+            correction: buildCorrectionContent({ stepId: running, attempt, failures, fixReport: lastFix }),
+          };
+          run.log(`  [${running}] CORREÇÃO GUIADA: retomando a MESMA conversa (${phaseUsage.messages.length} mensagens) com ordem de EDITAR, não refazer (DF-SF10.12-1).`);
+        }
+        continue;
+      }
+      run.log(`  [${running}] advance → ${res.action}${res.step ? ' (' + res.step + ')' : ''}`);
+      ok = true; break;
+    }
+    if (!ok) { run.log(`\n>>> BLOQUEIO: fase "${running}" não passou o veto em ${MAX_RETRY} tentativas.`); return { blocked: running, usage, fixes }; }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Setup de um run (comum a run/resume/approve/status). Reúne bundle + payload + chaves + deps.
+// ---------------------------------------------------------------------------
+
+function readEnvVar(file, key) {
+  if (!fs.existsSync(file)) return null;
+  const line = fs.readFileSync(file, 'utf8').split(/\r?\n/).find((l) => l.startsWith(`${key}=`));
+  return line ? (line.slice(key.length + 1).trim().replace(/^["']|["']$/g, '') || null) : null;
+}
+
+function loadPayload(inputPath) {
+  if (!inputPath) return {};
+  const abs = path.resolve(inputPath);
+  if (!fs.existsSync(abs)) throw new Error(`--input não encontrado: ${inputPath}`);
+  const payload = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  payload.__dir = path.dirname(abs);
+  return payload;
+}
+
+/**
+ * Monta o objeto `run` (bundle carregado, coerência AC16 já conferida, whitelist derivada,
+ * memoryPodDir efêmero (DF2-2), chaves de runtime, deps injetáveis). NÃO abre o motor ainda.
+ */
+function setupRun({ bundleDir, lockOverride, payload = {}, deps = {}, log }) {
+  const { root: bundleRoot, bundle } = loadBundle(bundleDir);
+  const lockPath = resolveLockPath(bundle, lockOverride);
+  const coherence = assertFrameworkCoherence(bundle, lockPath); // AC16 fail-loud ANTES de qualquer run.
+  const whitelist = tools.computeWhitelist(payload);
+  const inputsDir = payload.inputs_dir
+    ? (path.isAbsolute(payload.inputs_dir) ? payload.inputs_dir : path.resolve(payload.__dir || process.cwd(), payload.inputs_dir))
+    : null;
+  const anthropicKey = process.env.ANTHROPIC_API_KEY
+    || readEnvVar(path.join(os.homedir(), 'projetos/dev/second-brain/app/.env.local'), 'ANTHROPIC_API_KEY');
+  const orKey = process.env.OPENROUTER_API_KEY
+    || readEnvVar(path.join(os.homedir(), 'projetos/bench/.env'), 'OPENROUTER_API_KEY');
+  return {
+    bundleRoot, bundle, lockPath, coherence, whitelist, inputsDir,
+    payload, anthropicKey, orKey, deps,
+    pod: bundle.pod,
+    workflow: payload.workflow || `wf-${bundle.pod}`,
+    log: log || ((m) => console.log(m)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Materialização dos inputs pinados no runDir (DF5-1 / SF10.8) — o par de máquina da não-cópia.
+// ---------------------------------------------------------------------------
+
+// Fonte ÚNICA da convenção: a constante vive em `pod-export-tools.cjs`, que é quem PRECISA dela
+// para negar escrita sob `<runDir>/inputs/` (camada 1 de INTEG-1). Aqui só se reexporta — duas
+// cópias literais divergiriam em silêncio e reabririam o vetor.
+const RUN_INPUTS_DIRNAME = tools.RUN_INPUTS_DIRNAME; // convenção FIXA lida pelo veto (`--refs-dir ../inputs`)
+const PHASH_VETO_SCRIPT = 'phash-gate.cjs';          // blessed que EXIGE a referência materializada
+
+/**
+ * Fases do bundle que declaram o veto de pHash (lidas de `phases/<id>/meta.json`, escrito pelo
+ * compilador a partir das assertions `command_check` do wf — não de texto de agente).
+ */
+function phasesRequiringRefs(bundleRoot) {
+  const phasesDir = path.join(bundleRoot, 'phases');
+  if (!fs.existsSync(phasesDir)) return [];
+  const out = [];
+  for (const id of fs.readdirSync(phasesDir).sort()) {
+    const metaPath = path.join(phasesDir, id, 'meta.json');
+    if (!fs.existsSync(metaPath)) continue;
+    try {
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      if (Array.isArray(meta.veto_scripts) && meta.veto_scripts.includes(PHASH_VETO_SCRIPT)) out.push(id);
+    } catch { /* meta ilegível: o compilador já falharia antes; não inventar requisito aqui */ }
+  }
+  return out;
+}
+
+/**
+ * COPIA os inputs pinados do run para `<runDir>/inputs/` (DF5-1). Determinística e idempotente
+ * (roda igual em run e resume). Só arquivos regulares, um nível — nomes preservados; nada de
+ * symlink/traversal (o destino é sempre `<runDir>/inputs/<basename>`).
+ *
+ * REGISTRA o sha256 de CADA referência materializada no ledger de proveniência do run
+ * (`<runDir>.provenance.json`, IRMÃO do runDir — fora da árvore gravável pelo agente). É a
+ * camada 2 do fechamento de INTEG-1 (DF5-6/e1): o veto recusa fail-loud se o arquivo em
+ * `inputs/` divergir do hash aqui registrado, mesmo que a camada 1 (denylist de escrita nas
+ * tools) tenha algum caminho não antecipado.
+ *
+ * FAIL-LOUD: se alguma fase declara o veto `phash-gate.cjs` e o run NÃO tem `inputs_dir` com
+ * imagem, ABORTA ANTES de gastar API — o veto bloquearia adiante de qualquer forma, e falhar
+ * cedo com mensagem acionável é melhor que queimar tokens para morrer no gate.
+ */
+function materializeInputs({ bundleRoot, inputsDir, runDir, log = () => {} }) {
+  const required = bundleRoot ? phasesRequiringRefs(bundleRoot) : [];
+  const dest = path.join(runDir, RUN_INPUTS_DIRNAME);
+  let copied = [];
+  if (inputsDir && fs.existsSync(inputsDir)) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const e of fs.readdirSync(inputsDir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (!e.isFile() || e.name.startsWith('.')) continue;
+      const target = path.join(dest, path.basename(e.name));
+      fs.copyFileSync(path.join(inputsDir, e.name), target);
+      // Proveniência da REFERÊNCIA: o hash é tirado DEPOIS da cópia, do arquivo que o veto vai
+      // ler — é exatamente a igualdade bit-a-bit que o invariante promete.
+      tools.recordProvenance(runDir, 'inputs', target, { source: 'materializeInputs' });
+      copied.push(e.name);
+    }
+  }
+  if (required.length > 0 && copied.length === 0) {
+    throw new Error(
+      `fase(s) [${required.join(', ')}] declaram o veto de não-cópia "${PHASH_VETO_SCRIPT}", que compara as ` +
+      `imagens geradas contra a REFERÊNCIA do run — mas nenhum input foi materializado em ${dest}. ` +
+      'Passe --input com "inputs_dir" apontando o diretório da referência (ADR-018 Adendo F5/DF5-1). ' +
+      'ABORTANDO antes de gastar API (o veto bloquearia a etapa de qualquer forma).',
+    );
+  }
+  if (copied.length > 0) log(`[inputs] materializados em ${RUN_INPUTS_DIRNAME}/: ${copied.join(', ')} (DF5-1 — referência do veto de não-cópia)`);
+  return { dest, copied, required };
+}
+
+// ---------------------------------------------------------------------------
+// CLI.
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--input') flags.input = argv[++i];
+    else if (a === '--runs-root') flags.runsRoot = argv[++i];
+    else if (a === '--lock') flags.lock = argv[++i];
+    else if (a === '--kill-during') flags.killDuring = argv[++i];
+    else positionals.push(a);
+  }
+  return { positionals, flags };
+}
+
+async function main() {
+  const { positionals, flags } = parseArgs(process.argv.slice(2));
+  const bundleDir = positionals[0];
+  const cmd = positionals[1];
+  const runIdArg = positionals[2];
+  if (!bundleDir || !cmd) {
+    console.error('Uso: node scripts/pod-export-executor.cjs <bundle-dir> <run|resume|approve|status> [runId] [--input <payload.json>] [--runs-root <dir>] [--lock <path>] [--kill-during <phase>]');
+    process.exit(2);
+  }
+  const runsRoot = flags.runsRoot ? path.resolve(flags.runsRoot) : path.join(REPO_ROOT, '.power-claude', 'pod-export-runs');
+  fs.mkdirSync(runsRoot, { recursive: true });
+
+  const payload = loadPayload(flags.input);
+  const run = setupRun({ bundleDir, lockOverride: flags.lock, payload });
+  run.log(`[coerência] framework_version motor=${run.coherence.engineVersion} == lock=${run.coherence.lockVersion} (AC16 OK)`);
+
+  if (cmd === 'run') {
+    if (!run.anthropicKey) { console.error('[FALHA] ANTHROPIC_API_KEY não encontrada (env ou second-brain/app/.env.local).'); process.exit(1); }
+    const runId = runIdArg || ('pex-' + new Date().toISOString().replace(/[:.]/g, '-'));
+    const memoryPodDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pex-mem-')); // DF2-2: memória efêmera, NUNCA o bundle.
+    run.log(`\n=== RUN ${runId} — pod ${run.pod} — modelos ${JSON.stringify(run.bundle.modelo_pinado.agents)} ===`);
+    const { ctx } = motor.startRun({ workflowPath: run.bundleRoot + '/workflow.yaml', podRootOverride: run.bundleRoot, pod: run.pod, workflow: run.workflow, runsRoot, runId, memoryPodDir });
+    run.log(`runDir=${ctx.runDir}`);
+    materializeInputs({ bundleRoot: run.bundleRoot, inputsDir: run.inputsDir, runDir: ctx.runDir, log: run.log }); // DF5-1
+    const r = await drive(ctx, run, { killDuring: flags.killDuring });
+    console.log('\nRESULTADO:', JSON.stringify(r));
+  } else if (cmd === 'resume') {
+    const statePath = motor.findStateByRunId(runsRoot, runIdArg);
+    if (!statePath) { console.error(`run ${runIdArg} não encontrado em ${runsRoot}`); process.exit(1); }
+    const memoryPodDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pex-mem-'));
+    const ctx = motor.openRun({ statePath, workflowPath: run.bundleRoot + '/workflow.yaml', podRootOverride: run.bundleRoot, memoryPodDir });
+    materializeInputs({ bundleRoot: run.bundleRoot, inputsDir: run.inputsDir, runDir: ctx.runDir, log: run.log }); // DF5-1 (idempotente)
+    run.log(`\n=== RESUME ${runIdArg} ===`);
+    const r = await drive(ctx, run, {});
+    console.log('\nRESULTADO:', JSON.stringify(r));
+  } else if (cmd === 'approve') {
+    const statePath = motor.findStateByRunId(runsRoot, runIdArg);
+    if (!statePath) { console.error(`run ${runIdArg} não encontrado em ${runsRoot}`); process.exit(1); }
+    const memoryPodDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pex-mem-'));
+    const ctx = motor.openRun({ statePath, workflowPath: run.bundleRoot + '/workflow.yaml', podRootOverride: run.bundleRoot, memoryPodDir });
+    const res = motor.approve(ctx);
+    run.log(`\n>>> CHECKPOINT APROVADO (operador; sem identidade nesta fase — F3). approve → ${res.action}`);
+    console.log('\nRESULTADO:', JSON.stringify({ approved: true, next: res.next && res.next.action }));
+  } else if (cmd === 'status') {
+    const statePath = motor.findStateByRunId(runsRoot, runIdArg);
+    if (!statePath) { console.error(`run ${runIdArg} não encontrado em ${runsRoot}`); process.exit(1); }
+    const ctx = motor.openRun({ statePath, workflowPath: run.bundleRoot + '/workflow.yaml', podRootOverride: run.bundleRoot });
+    console.log(motor.statusSummary(ctx));
+  } else {
+    console.error('cmd: run|resume|approve|status');
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('[ERRO]', e.message); process.exit(1); });
+}
+
+module.exports = {
+  loadBundle,
+  engineFrameworkVersion,
+  resolveLockPath,
+  assertFrameworkCoherence,
+  anthropicCall,
+  execTool,
+  runPhase,
+  appendUserTurn,
+  buildUserContent,
+  buildCorrectionContent,
+  pinnedInputsBlock,
+  priorArtifactsBlock,
+  setupRun,
+  materializeInputs,
+  phasesRequiringRefs,
+  RUN_INPUTS_DIRNAME,
+  PHASH_VETO_SCRIPT,
+  drive,
+  execPhase,
+  parseArgs,
+  TOOL_DEFS,
+  MAX_TOKENS,
+};