@daniellins/power-claude 0.16.3

package/scripts/pod-export-service.test.cjs

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pod-export-service.test.cjs — SMOKE HERMÉTICO do serviço-irmão (Story SF10.3, F2).
+ *
+ * NÃO exige SSH/VPS/produção. Simula a topologia (a) do serviço-irmão LOCALMENTE (paths,
+ * resolução de blessed, leitura de env, pickup de fila) e PROVA a MESMA rejeição de script
+ * fora-da-whitelist que `pc-run-pod.cjs` garante em produção — é isto que dá ao QA como validar
+ * a fronteira command_check sem produção. Rede/executor/relógio INJETADOS; zero rede real.
+ *
+ * Cobre:
+ *   AC2  — chaves lidas do env; ausência FALHA ALTO (fail-loud), nunca por request.
+ *   AC3  — fronteira command_check: blessed ACEITO, não-blessed/traversal RECUSADO no MESMO
+ *          code-path (motor.evalVeto, VETO_CHECKS_ROOT ancorado no checkout) + arquivo estranho
+ *          PLANTADO em veto-checks/ ainda é RECUSADO (Guard B do manifesto — defesa em profundidade).
+ *   AC4  — Chrome aferido no ARRANQUE; ausência FALHA ALTO (fail-loud herdado de ADR-011).
+ *   AC6  — pickup de fila (contrato de diretório DF2-5): pending → processing → done/blocked/failed.
+ *   AC3  — coerência framework_version FIADA no preflight (MISMATCH recusa o arranque).
+ *
+ * Fix pós-deploy (achados 4/5/6 do smoke real VPS): roteamento por RESULTADO + approve via serviço.
+ * Um run BLOQUEADO no veto (achado 4) ou PAUSADO num checkpoint (achado 5) sai exit 0 e NÃO pode
+ * cair em done/ (verde-falso semântico). O approve via o serviço (achado 6) passa --runs-root da
+ * config (sem EACCES) e reconcilia o marcador de awaiting/. Cobrimos a LÓGICA sem VPS:
+ * parseExecutorResult (parsing puro), classifyOutcome (crash > awaiting/blocked > done), roteamento
+ * fim-a-fim de blocked/awaiting injetados → blocked//awaiting/ (nunca done/), buildApproveArgs
+ * (--runs-root threading), deriveRunKind (estado real do run) e approveRun (marcador sai de awaiting/).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const svc = require('./pod-export-service.cjs');
+const motor = require('./pc-run-pod.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const VETO_CHECKS = path.join(REPO_ROOT, 'scripts', 'veto-checks');
+const VALID_HTML = path.join(REPO_ROOT, 'scripts', '__fixtures__', 'veto-checks', 'slide-ok.html');
+
+let failures = 0;
+function assert(ok, msg) {
+  if (ok) console.log(`[OK   ] ${msg}`);
+  else { console.error(`[FALHA] ${msg}`); failures++; }
+}
+function throwsFail(fn) { try { fn(); return false; } catch { return true; } }
+function tmpDir(label) { return fs.mkdtempSync(path.join(os.tmpdir(), `sf10.3-${label}-`)); }
+
+// ---------------------------------------------------------------------------
+// AC2 — chaves da ORG do env (padrão getAnthropicApiKey); ausência FALHA ALTO.
+// ---------------------------------------------------------------------------
+function envKeyTests() {
+  console.log('\n--- AC2: chaves da ORG lidas do env, fail-loud na ausência ---');
+  const good = { ANTHROPIC_API_KEY: 'sk-ant-XXX', OPENROUTER_API_KEY: 'sk-or-XXX' };
+  assert(svc.getAnthropicApiKey(good) === 'sk-ant-XXX', 'getAnthropicApiKey lê do env fornecido');
+  assert(svc.getOpenRouterApiKey(good) === 'sk-or-XXX', 'getOpenRouterApiKey lê do env fornecido');
+  assert(throwsFail(() => svc.getAnthropicApiKey({})), 'ANTHROPIC_API_KEY ausente → FAIL-LOUD (não silencioso)');
+  assert(throwsFail(() => svc.getOpenRouterApiKey({ ANTHROPIC_API_KEY: 'x' })), 'OPENROUTER_API_KEY ausente → FAIL-LOUD');
+  assert(throwsFail(() => svc.getAnthropicApiKey({ ANTHROPIC_API_KEY: '   ' })), 'chave em branco NÃO conta como presente (fail-loud)');
+  // O valor da chave NUNCA aparece na mensagem de erro (nunca logar chaves).
+  let msg = '';
+  try { svc.getApiKey('ANTHROPIC_API_KEY', {}); } catch (e) { msg = e.message; }
+  assert(/nunca hardcoded, nunca por request/.test(msg), 'mensagem de fail-loud reforça a doutrina "nunca por request"');
+}
+
+// ---------------------------------------------------------------------------
+// AC3 (crítico) — fronteira command_check PROVADA na topologia do serviço-irmão, sem VPS.
+// ---------------------------------------------------------------------------
+function frontierTests() {
+  console.log('\n--- AC3: fronteira command_check reproduzida na topologia do serviço-irmão (sem VPS) ---');
+
+  // (a) self-check do serviço usa o MESMO motor.evalVeto (code-path de produção).
+  const s = svc.assertCommandCheckFrontier({ validHtmlPath: VALID_HTML });
+  assert(s.rejectedNonBlessed, 'self-check: script NÃO-blessed RECUSADO pela resolução do motor (sem execução)');
+  assert(s.rejectedTraversal, 'self-check: traversal ../ para fora de veto-checks/ RECUSADO');
+  assert(s.acceptedBlessed, 'self-check: blessed html-valid.cjs ACEITO sobre HTML válido (resolução do checkout funciona)');
+
+  // (b) Prova direta contra o motor (a MESMA garantia que pc-run-pod dá em produção): um nome
+  //     fora da whitelist é recusado ANTES de qualquer execFileSync.
+  const roots = { runDir: os.tmpdir(), podRoot: REPO_ROOT };
+  const outside = motor.evalVeto({ type: 'command_check', command: 'nao-existe-blessed.cjs' }, '', path.join(os.tmpdir(), 'x'), roots);
+  assert(!outside.ok && /blessed|resolve|não é/.test(outside.reason), 'motor: script fora da whitelist RECUSADO (mesma rejeição que produção)');
+  const blessed = motor.evalVeto({ type: 'command_check', command: 'html-valid.cjs' }, '', VALID_HTML, roots);
+  assert(blessed.ok, 'motor: blessed html-valid.cjs ACEITO (fronteira não bloqueia o legítimo)');
+
+  // (c) Defesa em profundidade (Guard B): arquivo ESTRANHO PLANTADO dentro de veto-checks/ — nome
+  //     que NÃO está no manifesto motor-scripts.json — ainda é RECUSADO. Prova que a fronteira não
+  //     confia na mera presença no diretório (o cenário exato do ataque à VPS). Cleanup garantido.
+  const planted = path.join(VETO_CHECKS, '__sf10_3_evil_probe__.cjs');
+  let plantedExisted = fs.existsSync(planted);
+  try {
+    fs.writeFileSync(planted, `require('node:fs').writeFileSync(${JSON.stringify(planted + '.pwned')}, 'x'); process.exit(0);`);
+    const r = motor.evalVeto({ type: 'command_check', command: '__sf10_3_evil_probe__.cjs' }, '', VALID_HTML, roots);
+    assert(!r.ok, 'PLANTADO em veto-checks/ mas fora do manifesto → RECUSADO (Guard B; não confia no dir)');
+    assert(!fs.existsSync(planted + '.pwned'), 'o payload plantado NUNCA executou (sem side-effect no disco)');
+  } finally {
+    if (!plantedExisted) { try { fs.unlinkSync(planted); } catch {} }
+    try { fs.unlinkSync(planted + '.pwned'); } catch {}
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AC4 — Chrome aferido no ARRANQUE; ausência FALHA ALTO (herdado de ADR-011).
+// ---------------------------------------------------------------------------
+function chromePreflightTests() {
+  console.log('\n--- AC4: Chrome aferido no arranque, fail-loud se ausente ---');
+  const env = { ANTHROPIC_API_KEY: 'x', OPENROUTER_API_KEY: 'y' };
+  // Chrome ausente (probe injetado → null) deve FALHAR ALTO antes de aceitar qualquer run.
+  let msg = '';
+  try {
+    svc.preflight({}, { env, probeChrome: () => null, evalVeto: motor.evalVeto });
+  } catch (e) { msg = e.message; }
+  assert(/Chrome headless AUSENTE/.test(msg), 'Chrome ausente no arranque → FAIL-LOUD (nunca skip-silencioso)');
+
+  // Chrome presente (probe injetado) + fronteira íntegra → preflight passa (sem bundle = sem coerência).
+  const s = svc.preflight({}, { env, probeChrome: () => '/usr/bin/chromium', evalVeto: motor.evalVeto, validHtmlPath: VALID_HTML });
+  assert(s.chrome === 'chromium' && s.keys.anthropic && s.keys.openrouter, 'preflight OK com Chrome presente + chaves + fronteira íntegra');
+  assert(s.frontier && s.frontier.rejectedNonBlessed && s.frontier.acceptedBlessed, 'preflight embute o self-check da fronteira (AC3)');
+}
+
+// ---------------------------------------------------------------------------
+// AC3 — coerência framework_version FIADA no arranque (MISMATCH recusa o serviço).
+// ---------------------------------------------------------------------------
+function coherencePreflightTests() {
+  console.log('\n--- AC3/DF2-1: coerência framework_version fiada no arranque ---');
+  const env = { ANTHROPIC_API_KEY: 'x', OPENROUTER_API_KEY: 'y' };
+  const bundleDir = tmpDir('bundle');
+  // bundle mínimo que loadBundle aceita.
+  fs.writeFileSync(path.join(bundleDir, 'bundle.json'), JSON.stringify({ pod: 'demo', modelo_pinado: { agents: { p1: 'm' } }, framework_version: '9.9.9' }));
+  fs.writeFileSync(path.join(bundleDir, 'workflow.yaml'), 'id: wf-demo\n');
+  const lockPath = path.join(bundleDir, 'export.lock.json');
+
+  // MISMATCH: lock diz 9.9.9, motor injetado diz 1.0.0 → RECUSA (usa a função REAL do executor).
+  fs.writeFileSync(lockPath, JSON.stringify({ framework_version: '9.9.9' }));
+  const cfg = { bundleDir, lockOverride: lockPath };
+  const deps = {
+    env, probeChrome: () => '/usr/bin/chromium', evalVeto: motor.evalVeto, validHtmlPath: VALID_HTML,
+    assertFrameworkCoherence: (bundle, lp) => require('./pod-export-executor.cjs').assertFrameworkCoherence(bundle, lp, '1.0.0'),
+  };
+  assert(throwsFail(() => svc.preflight(cfg, deps)), 'framework_version MISMATCH (motor 1.0.0 != lock 9.9.9) → arranque RECUSADO');
+
+  // MATCH: motor injetado == lock → passa.
+  const depsOk = { ...deps, assertFrameworkCoherence: (bundle, lp) => require('./pod-export-executor.cjs').assertFrameworkCoherence(bundle, lp, '9.9.9') };
+  const s = svc.preflight(cfg, depsOk);
+  assert(s.coherence && s.coherence.engineVersion === '9.9.9', 'framework_version coerente → preflight passa e reporta a versão');
+}
+
+// ---------------------------------------------------------------------------
+// AC6 — pickup de fila (contrato de diretório DF2-5), executor INJETADO (sem rede/LLM).
+// ---------------------------------------------------------------------------
+async function queuePickupTests() {
+  console.log('\n--- AC6/DF2-5: pickup da fila por contrato de diretório (pending→processing→done/blocked/failed) ---');
+  const queueDir = tmpDir('queue');
+  // bundleDir=null: coerência de versão é coberta pelo teste dedicado acima; aqui o foco é o
+  // contrato de fila. O executor é INJETADO, então nenhum bundle real é necessário.
+  const cfg = { queueDir, bundleDir: null, runsRoot: tmpDir('runs'), pollMs: 1 };
+
+  // Dropar 4 payloads em pending/: (1) concluído (exit 0, complete); (2) CRASH (exit 1);
+  // (3) BLOQUEADO no veto (exit 0 + {blocked} — achado 4); (4) PAUSADO no checkpoint (exit 0 +
+  // {awaiting} — achado 5: NÃO pode ir a done/, é retomável via approve).
+  const dirs = svc.ensureQueue(queueDir);
+  fs.writeFileSync(path.join(dirs.pending, 'a-ok.json'), JSON.stringify({ pod: 'demo', n: 1 }));
+  fs.writeFileSync(path.join(dirs.pending, 'b-fail.json'), JSON.stringify({ pod: 'demo', n: 2 }));
+  fs.writeFileSync(path.join(dirs.pending, 'c-blocked.json'), JSON.stringify({ pod: 'demo', n: 3 }));
+  fs.writeFileSync(path.join(dirs.pending, 'd-awaiting.json'), JSON.stringify({ pod: 'demo', n: 4 }));
+  assert(svc.listPending(queueDir).length === 4, 'listPending enxerga os 4 payloads dropados em pending/');
+
+  // Executor INJETADO: lê o payload movido para processing/ e decide por 'n' (prova que o
+  // pickup entrega o payload correto ao executor). Sem rede, sem LLM, sem spawn real.
+  // n=1 → done; n=2 → crash; n=3 → blocked (achado 4); n=4 → awaiting/checkpoint (achado 5).
+  const seen = [];
+  const deps = {
+    log: () => {},
+    runExecutor: async (c, processingPath) => {
+      const p = JSON.parse(fs.readFileSync(processingPath, 'utf8'));
+      seen.push({ n: p.n, existsInProcessing: fs.existsSync(processingPath) });
+      if (p.n === 2) return { code: 1, result: null };                       // crash real
+      if (p.n === 3) return { code: 0, result: { blocked: 'lexical-check' } }; // veto esgotado (exit 0)
+      if (p.n === 4) return { code: 0, result: { awaiting: 'assembly' } };     // checkpoint (exit 0)
+      return { code: 0, result: { complete: true } };                         // pipeline completo
+    },
+    sleep: async () => {},
+    stopAfter: 1,
+  };
+  const res = await svc.serve(
+    cfg,
+    { ...deps, env: { ANTHROPIC_API_KEY: 'x', OPENROUTER_API_KEY: 'y' }, probeChrome: () => '/usr/bin/chromium', evalVeto: motor.evalVeto, validHtmlPath: VALID_HTML },
+  );
+  assert(res.processed.length === 4, 'serve processou os 4 payloads num ciclo');
+  assert(seen.every((x) => x.existsInProcessing), 'o payload foi ENTREGUE ao executor a partir de processing/ (movido do pending)');
+  assert(svc.listPending(queueDir).length === 0, 'pending/ esvaziou após o pickup');
+  const okRun = res.processed.find((r) => r.kind === 'done');
+  const failRun = res.processed.find((r) => r.kind === 'failed');
+  const blockedRun = res.processed.find((r) => r.kind === 'blocked');
+  assert(okRun && okRun.ok && fs.existsSync(okRun.finalPath) && okRun.finalPath.includes(`${path.sep}done${path.sep}`), 'run COMPLETO (exit 0, result.complete) foi para done/');
+  assert(failRun && !failRun.ok && fs.existsSync(failRun.finalPath) && failRun.finalPath.includes(`${path.sep}failed${path.sep}`), 'run com exit != 0 (crash) foi para failed/ (veredito pelo exit, não pelo relato)');
+  // Achado 4 — o coração do fix: bloqueado sai exit 0 mas NÃO é sucesso.
+  assert(blockedRun && !blockedRun.ok, 'run BLOQUEADO NÃO é marcado ok (exit 0 sozinho não basta)');
+  assert(blockedRun && fs.existsSync(blockedRun.finalPath) && blockedRun.finalPath.includes(`${path.sep}blocked${path.sep}`), 'achado 4: run BLOQUEADO (exit 0 + result.blocked) foi para blocked/, NUNCA done/');
+  assert(!blockedRun.finalPath.includes(`${path.sep}done${path.sep}`), 'achado 4: run bloqueado NÃO contaminou done/ (verde-falso evitado)');
+  const blockedResult = JSON.parse(fs.readFileSync(blockedRun.resultPath, 'utf8'));
+  assert(blockedResult.kind === 'blocked' && blockedResult.blocked === 'lexical-check' && blockedResult.ok === false, 'result.json do bloqueado registra kind=blocked, a fase e ok=false');
+  // Achado 5 — checkpoint humano NÃO é conclusão: vai para awaiting/, retomável via approve.
+  const awaitingRun = res.processed.find((r) => r.kind === 'awaiting');
+  assert(awaitingRun && !awaitingRun.ok, 'run PAUSADO no checkpoint NÃO é marcado ok (não concluiu)');
+  assert(awaitingRun && fs.existsSync(awaitingRun.finalPath) && awaitingRun.finalPath.includes(`${path.sep}awaiting${path.sep}`), 'achado 5: run com {awaiting:"assembly"} foi para awaiting/, NUNCA done/');
+  assert(!awaitingRun.finalPath.includes(`${path.sep}done${path.sep}`), 'achado 5: checkpoint NÃO contaminou done/ (verde-falso evitado)');
+  const awaitingResult = JSON.parse(fs.readFileSync(awaitingRun.resultPath, 'utf8'));
+  assert(awaitingResult.kind === 'awaiting' && awaitingResult.awaiting === 'assembly' && awaitingResult.ok === false, 'result.json do pausado registra kind=awaiting, a fase e ok=false');
+  assert(fs.existsSync(okRun.resultPath) && JSON.parse(fs.readFileSync(okRun.resultPath, 'utf8')).ok === true, 'result.json registra o veredito do run OK');
+
+  // approve é CLI SEPARADA — nunca chega pela fila (DF2-5). Confirma que enqueue valida JSON.
+  const badPayload = path.join(tmpDir('bad'), 'bad.json');
+  fs.writeFileSync(badPayload, '{not json');
+  assert(throwsFail(() => svc.enqueue(cfg, badPayload)), 'enqueue RECUSA payload que não é JSON válido (não polui a fila)');
+}
+
+// ---------------------------------------------------------------------------
+// Achado 4 (smoke real VPS) — parsing do RESULTADO + classificação do desfecho, LÓGICA pura.
+// ---------------------------------------------------------------------------
+function outcomeRoutingTests() {
+  console.log('\n--- Achado 4: parseExecutorResult + classifyOutcome (roteamento por RESULTADO, sem VPS) ---');
+
+  // parseExecutorResult: pega a ÚLTIMA linha `RESULTADO: {json}` da saída do executor.
+  const stdoutBlocked = 'runDir=/x\n  [lexical-check] VETO DISPAROU (tentativa 3): em-dash: 23\n>>> BLOQUEIO: fase "lexical-check"\nRESULTADO: {"blocked":"lexical-check"}\n';
+  assert(svc.parseExecutorResult(stdoutBlocked).blocked === 'lexical-check', 'parseExecutorResult lê {blocked:"<fase>"} do stdout do executor');
+  assert(svc.parseExecutorResult('foo\nRESULTADO: {"complete":true}\n').complete === true, 'parseExecutorResult lê {complete:true}');
+  assert(svc.parseExecutorResult('RESULTADO: {"awaiting":"aprovacao"}').awaiting === 'aprovacao', 'parseExecutorResult lê {awaiting:"<fase>"} (checkpoint)');
+  assert(svc.parseExecutorResult('sem resultado aqui') === null, 'parseExecutorResult devolve null quando não há linha RESULTADO');
+  assert(svc.parseExecutorResult('RESULTADO: {quebrado') === null, 'parseExecutorResult devolve null em JSON ilegível (não crasha)');
+  // Última RESULTADO vence (resume pode imprimir mais de uma).
+  assert(svc.parseExecutorResult('RESULTADO: {"blocked":"a"}\nRESULTADO: {"complete":true}').complete === true, 'parseExecutorResult usa o ÚLTIMO RESULTADO impresso');
+
+  // classifyOutcome: precedência crash > awaiting/blocked > done.
+  assert(svc.classifyOutcome({ code: 1, result: null }).kind === 'failed', 'classify: exit != 0 → failed (crash), mesmo sem RESULTADO');
+  assert(svc.classifyOutcome({ code: 1, result: { blocked: 'x' } }).kind === 'failed', 'classify: crash tem precedência sobre blocked (exit != 0 → failed)');
+  assert(svc.classifyOutcome({ code: 1, result: { awaiting: 'x' } }).kind === 'failed', 'classify: crash tem precedência sobre awaiting (exit != 0 → failed)');
+  const b = svc.classifyOutcome({ code: 0, result: { blocked: 'lexical-check' } });
+  assert(b.kind === 'blocked' && b.blocked === 'lexical-check', 'classify: exit 0 + result.blocked → blocked/ (achado 4)');
+  const aw = svc.classifyOutcome({ code: 0, result: { awaiting: 'assembly' } });
+  assert(aw.kind === 'awaiting' && aw.awaiting === 'assembly', 'classify: exit 0 + result.awaiting → awaiting/ (achado 5, NÃO done/)');
+  assert(svc.classifyOutcome({ code: 0, result: { complete: true } }).kind === 'done', 'classify: exit 0 + complete → done');
+  assert(svc.classifyOutcome({ code: 0, result: null }).kind === 'done', 'classify: exit 0 sem RESULTADO → done (compat)');
+}
+
+// ---------------------------------------------------------------------------
+// Achado 6 (smoke real VPS) — approve via o serviço: --runs-root da config + reconciliação do
+// marcador de awaiting/. LÓGICA testável sem VPS (args puros, fs, motor injetado).
+// ---------------------------------------------------------------------------
+function approveWiringTests() {
+  console.log('\n--- Achado 6: approve via o serviço (--runs-root de PODEXPORT_RUNS_DIR + reconciliação) ---');
+
+  // buildApproveArgs: o CORAÇÃO do achado 6 — o executor recebe --runs-root da config do serviço
+  // (não o default .power-claude/... que dá EACCES para o usuário do serviço).
+  const cfg = svc.loadConfig({ PODEXPORT_BUNDLE_DIR: '/opt/bundle', PODEXPORT_QUEUE_DIR: '/var/q', PODEXPORT_RUNS_DIR: '/var/lib/pod-export/runs' });
+  const args = svc.buildApproveArgs(cfg, 'pex-abc');
+  const i = args.indexOf('--runs-root');
+  assert(i !== -1 && args[i + 1] === path.resolve('/var/lib/pod-export/runs'), 'buildApproveArgs passa --runs-root = PODEXPORT_RUNS_DIR (achado 6: sem EACCES no default)');
+  assert(args.includes('approve') && args.includes('pex-abc') && args[0] === svc.EXECUTOR_PATH, 'buildApproveArgs delega ao executor: approve <runId>');
+  const cfgLock = { ...cfg, lockOverride: '/opt/bundle/export.lock.json' };
+  assert(svc.buildApproveArgs(cfgLock, 'pex-abc').includes('--lock'), 'buildApproveArgs propaga --lock quando há override');
+
+  // deriveRunKind: lê o estado REAL do run (motor injetado) — não adivinha.
+  const depAwaiting = { findStateByRunId: () => '/x/state.json', readState: () => ({ steps: { s1: { status: 'done' }, s2: { status: 'awaiting_approval' } } }) };
+  assert(svc.deriveRunKind(cfg, 'r', depAwaiting) === 'awaiting', 'deriveRunKind: step em awaiting_approval → awaiting (outro checkpoint)');
+  const depDone = { findStateByRunId: () => '/x/state.json', readState: () => ({ steps: { s1: { status: 'done' }, s2: { status: 'done' } } }) };
+  assert(svc.deriveRunKind(cfg, 'r', depDone) === 'done', 'deriveRunKind: todos os steps done → done');
+  const depFail = { findStateByRunId: () => '/x/state.json', readState: () => ({ steps: { s1: { status: 'failed' } } }) };
+  assert(svc.deriveRunKind(cfg, 'r', depFail) === 'failed', 'deriveRunKind: step failed → failed');
+  const depNone = { findStateByRunId: () => null };
+  assert(svc.deriveRunKind(cfg, 'r', depNone) === null, 'deriveRunKind: run não encontrado → null (nada a reconciliar)');
+
+  // reconcileMarker + approveRun: o marcador SAI de awaiting/ quando aprovado (achado 5+6 juntos).
+  const queueDir = tmpDir('approve-q');
+  const cfg2 = { queueDir, bundleDir: '/opt/bundle', runsRoot: tmpDir('approve-runs'), pollMs: 1 };
+  const dirs = svc.ensureQueue(queueDir);
+  const runId = 'pex-hn-carousel-1';
+  fs.writeFileSync(path.join(dirs.awaiting, `${runId}.json`), JSON.stringify({ pod: 'hn-carousel' })); // pausado no checkpoint
+
+  // approveRun com spawn INJETADO (sem executor real): simula exit 0 + RESULTADO {approved} e o run
+  // agora com todos os steps done → reconcilia awaiting/ → done/.
+  const EventEmitter = require('node:events');
+  const fakeSpawn = () => {
+    const child = new EventEmitter();
+    child.stdout = new EventEmitter();
+    setImmediate(() => { child.stdout.emit('data', Buffer.from('\nRESULTADO: {"approved":true,"next":"complete"}\n')); child.emit('exit', 0); });
+    return child;
+  };
+  const capturedArgs = [];
+  const spyingSpawn = (bin, a, opts) => { capturedArgs.push(a); return fakeSpawn(bin, a, opts); };
+  // O approve agora é GATEADO (SF10.4/DF3-3): passa a autorização válida (aprovador + segredo certo)
+  // para exercitar a reconciliação (achado 6). O enforcement em si é coberto por identityTests.
+  const idModel = { identities: [{ id: 'daniel', is_approver: true }], approver: { id: 'daniel', is_approver: true }, byId: { daniel: { id: 'daniel', is_approver: true } } };
+  const secretHash = svc.hashApproverSecret('correct horse');
+  return svc.approveRun(cfg2, runId, {
+    spawn: spyingSpawn, log: () => {},
+    identityModel: idModel, asId: 'daniel', approverSecret: 'correct horse', approverSecretHash: secretHash,
+    findStateByRunId: () => '/x/state.json',
+    readState: () => ({ steps: { digest: { status: 'done' }, visuals: { status: 'done' }, assembly: { status: 'done' } } }),
+  }).then((r) => {
+    assert(r.code === 0, 'approveRun resolve exit 0 do executor');
+    const passedArgs = capturedArgs[0];
+    assert(passedArgs.indexOf('--runs-root') !== -1 && passedArgs[passedArgs.indexOf('--runs-root') + 1] === cfg2.runsRoot, 'approveRun invocou o executor COM --runs-root da config (achado 6)');
+    assert(!fs.existsSync(path.join(dirs.awaiting, `${runId}.json`)), 'achado 5: o marcador SAIU de awaiting/ após o approve');
+    assert(fs.existsSync(path.join(dirs.done, `${runId}.json`)), 'achado 5: run aprovado e concluído → marcador reconciliado para done/');
+    const rr = JSON.parse(fs.readFileSync(path.join(dirs.done, `${runId}.result.json`), 'utf8'));
+    assert(rr.kind === 'done' && rr.reconciledBy === 'approve', 'result.json do reconciliado registra kind=done e reconciledBy=approve');
+  });
+}
+
+// ===========================================================================
+// SF10.4 (F3) — modelo de identidade: started_by (seleção) + approve (segredo) + ledger de uso.
+// ===========================================================================
+
+// Escreve um arquivo de config de identidades e devolve seu path.
+function writeIdentities(obj) {
+  const p = path.join(tmpDir('ids'), 'identities.json');
+  fs.writeFileSync(p, JSON.stringify(obj));
+  return p;
+}
+const VALID_IDS = { identities: [{ id: 'daniel', label: 'Daniel', is_approver: true }, { id: 'alice', label: 'Alice' }, { id: 'bob', label: 'Bob' }] };
+
+// ---------------------------------------------------------------------------
+// AC2/AC6 + invariante — loader fail-loud da config de identidades (exatamente 1 is_approver).
+// ---------------------------------------------------------------------------
+function identityConfigTests() {
+  console.log('\n--- SF10.4 AC6/DF3-5: loader de identidades fail-loud (exatamente 1 is_approver) ---');
+  const okFile = writeIdentities(VALID_IDS);
+  const m = svc.loadIdentities({ file: okFile });
+  assert(m.identities.length === 3 && m.approver.id === 'daniel', 'config válida: carrega e identifica o aprovador único');
+  assert(svc.isKnownIdentity(m, 'alice') && !svc.isKnownIdentity(m, 'mallory'), 'isKnownIdentity distingue conhecido de desconhecido');
+
+  assert(throwsFail(() => svc.loadIdentities({ file: undefined, env: {} })), 'PODEXPORT_IDENTITIES ausente → FAIL-LOUD');
+  assert(throwsFail(() => svc.loadIdentities({ file: '/nao/existe/ids.json' })), 'arquivo inexistente/ilegível → FAIL-LOUD');
+  const badJson = path.join(tmpDir('ids'), 'bad.json'); fs.writeFileSync(badJson, '{quebrado');
+  assert(throwsFail(() => svc.loadIdentities({ file: badJson })), 'JSON inválido → FAIL-LOUD');
+  assert(throwsFail(() => svc.loadIdentities({ file: writeIdentities({ identities: [] }) })), 'lista vazia → FAIL-LOUD');
+  assert(throwsFail(() => svc.loadIdentities({ file: writeIdentities({ identities: [{ id: 'a' }, { id: 'b' }] }) })), 'ZERO is_approver → FAIL-LOUD (aprovador designado é invariante)');
+  assert(throwsFail(() => svc.loadIdentities({ file: writeIdentities({ identities: [{ id: 'a', is_approver: true }, { id: 'b', is_approver: true }] }) })), '>1 is_approver → FAIL-LOUD (aprovador deve ser ÚNICO)');
+  assert(throwsFail(() => svc.loadIdentities({ file: writeIdentities({ identities: [{ id: 'dup', is_approver: true }, { id: 'dup' }] }) })), 'id duplicado → FAIL-LOUD');
+  assert(throwsFail(() => svc.loadIdentities({ file: writeIdentities({ identities: [{ id: '', is_approver: true }] }) })), 'id vazio → FAIL-LOUD');
+}
+
+// ---------------------------------------------------------------------------
+// AC1/AC2 — started_by obrigatório e validado no enqueue (nunca run anônimo).
+// ---------------------------------------------------------------------------
+function startedByEnqueueTests() {
+  console.log('\n--- SF10.4 AC1/AC2: started_by obrigatório e validado no enqueue ---');
+  const queueDir = tmpDir('q-sb');
+  const idFile = writeIdentities(VALID_IDS);
+  const cfg = svc.loadConfig({ PODEXPORT_QUEUE_DIR: queueDir, PODEXPORT_IDENTITIES: idFile });
+  assert(cfg.identitiesFile === idFile, 'loadConfig expõe PODEXPORT_IDENTITIES em cfg.identitiesFile');
+
+  function payloadFile(obj) { const p = path.join(tmpDir('pl'), 'p.json'); fs.writeFileSync(p, JSON.stringify(obj)); return p; }
+
+  const good = svc.enqueue(cfg, payloadFile({ pod: 'hn-carousel', started_by: 'alice' }));
+  assert(fs.existsSync(good) && JSON.parse(fs.readFileSync(good, 'utf8')).started_by === 'alice', 'enqueue com started_by conhecido → enfileira e persiste started_by');
+  assert(throwsFail(() => svc.enqueue(cfg, payloadFile({ pod: 'x' }))), 'started_by AUSENTE → recusa fail-loud (nunca run anônimo)');
+  assert(throwsFail(() => svc.enqueue(cfg, payloadFile({ pod: 'x', started_by: 'mallory' }))), 'started_by DESCONHECIDO (fora da lista) → recusa fail-loud');
+  assert(throwsFail(() => svc.enqueue(cfg, payloadFile({ pod: 'x', started_by: '   ' }))), 'started_by em branco → recusa fail-loud');
+  // Açúcar --started-by injeta o campo num payload que não o traz.
+  const injected = svc.enqueue(cfg, payloadFile({ pod: 'x' }), { startedBy: 'bob' });
+  assert(JSON.parse(fs.readFileSync(injected, 'utf8')).started_by === 'bob', '--started-by injeta started_by quando o payload não o traz');
+  assert(throwsFail(() => svc.enqueue(cfg, payloadFile({ pod: 'x' }), { startedBy: 'mallory' })), '--started-by com id desconhecido → recusa (o açúcar não contorna a validação)');
+}
+
+// ---------------------------------------------------------------------------
+// AC3/AC5 — started_by persistido no result.json + ledger de uso agregado por pessoa.
+// ---------------------------------------------------------------------------
+async function persistenceAndUsageTests() {
+  console.log('\n--- SF10.4 AC3/AC5: started_by persistido + ledger de uso por started_by ---');
+  const queueDir = tmpDir('q-usage');
+  const cfg = { queueDir, bundleDir: null, runsRoot: tmpDir('runs-u'), pollMs: 1 };
+  const dirs = svc.ensureQueue(queueDir);
+  // 3 runs: alice (usage 100/50/2), bob (200/10/0), alice de novo (50/25/1).
+  fs.writeFileSync(path.join(dirs.pending, 'a1.json'), JSON.stringify({ pod: 'hn', started_by: 'alice', n: 1 }));
+  fs.writeFileSync(path.join(dirs.pending, 'b1.json'), JSON.stringify({ pod: 'hn', started_by: 'bob', n: 2 }));
+  fs.writeFileSync(path.join(dirs.pending, 'a2.json'), JSON.stringify({ pod: 'hn', started_by: 'alice', n: 3 }));
+  const deps = {
+    log: () => {},
+    runExecutor: async (c, processingPath) => {
+      const p = JSON.parse(fs.readFileSync(processingPath, 'utf8'));
+      // `usage` no formato EXATO que o executor agora expõe no RESULTADO (DF3-4 fechado): o ledger
+      // registra uso REAL, nunca 0. Ver a prova de agregação por fase em pod-export-executor.test.cjs.
+      const u = { 1: { input_tokens: 100, output_tokens: 50, images: 2 }, 2: { input_tokens: 200, output_tokens: 10, images: 0 }, 3: { input_tokens: 50, output_tokens: 25, images: 1 } }[p.n];
+      return { code: 0, result: { complete: true, usage: u } };
+    },
+    sleep: async () => {}, stopAfter: 1,
+    env: { ANTHROPIC_API_KEY: 'x', OPENROUTER_API_KEY: 'y' }, probeChrome: () => '/usr/bin/chromium', evalVeto: motor.evalVeto, validHtmlPath: VALID_HTML,
+  };
+  const res = await svc.serve(cfg, deps);
+  assert(res.processed.length === 3, 'serve processou os 3 runs');
+  const doneRun = res.processed.find((r) => r.kind === 'done');
+  const rj = JSON.parse(fs.readFileSync(doneRun.resultPath, 'utf8'));
+  assert(typeof rj.started_by === 'string', 'AC3: result.json persiste started_by do run');
+
+  const agg = svc.aggregateUsage(cfg);
+  assert(agg.alice && agg.alice.runs === 2 && agg.alice.tokens_in === 150 && agg.alice.tokens_out === 75 && agg.alice.imagens === 3, 'AC5: usage agregado de alice (2 runs, 150 in / 75 out / 3 img)');
+  assert(agg.bob && agg.bob.runs === 1 && agg.bob.tokens_in === 200, 'AC5: usage agregado de bob (1 run, 200 in)');
+  assert(fs.existsSync(svc.usageLogPath(cfg)), 'ledger usage.log.jsonl append-only foi escrito');
+  // Ledger é freio, não billing: só agrega, não capa (nenhum campo de limite/enforcement).
+  assert(!('limit' in agg.alice) && !('cap' in agg.alice), 'ledger é VER (agrega), NUNCA CAPAR (sem limite/cap) — linha 127 do ADR');
+}
+
+// ---------------------------------------------------------------------------
+// AC4 (CRÍTICO, alvo do QA adversarial) — approve: SELEÇÃO ≠ AUTORIZAÇÃO (segredo do aprovador).
+// ---------------------------------------------------------------------------
+async function approveEnforcementTests() {
+  console.log('\n--- SF10.4 AC4 (adversarial): approve exige is_approver E segredo (scrypt+timingSafeEqual) ---');
+  const idModel = svc.loadIdentities({ file: writeIdentities(VALID_IDS) });
+  const SECRET = 'correct horse battery staple';
+  const HASH = svc.hashApproverSecret(SECRET);
+
+  // Roundtrip de hash/verify + timing-safe.
+  assert(svc.verifyApproverSecret(SECRET, HASH), 'verifyApproverSecret aceita o segredo certo (roundtrip scrypt)');
+  assert(!svc.verifyApproverSecret('errado', HASH), 'verifyApproverSecret RECUSA segredo errado');
+  assert(!svc.verifyApproverSecret(SECRET, 'formato-invalido'), 'verifyApproverSecret RECUSA hash malformado (sem crashar)');
+  assert(!svc.verifyApproverSecret('', HASH), 'verifyApproverSecret RECUSA segredo vazio');
+  assert(svc.hashApproverSecret(SECRET) !== svc.hashApproverSecret(SECRET), 'hash usa salt aleatório (dois hashes do mesmo segredo diferem)');
+
+  // authorizeApproval — a função PURA do gate. Cada furo que o QA tentaria:
+  const A = (over) => svc.authorizeApproval({ identityModel: idModel, asId: 'daniel', providedSecret: SECRET, secretHash: HASH, ...over });
+  assert(A().ok, 'aprovador designado (daniel) + segredo CERTO → AUTORIZADO');
+  assert(!A({ providedSecret: 'errado' }).ok, '(a) segredo ERRADO → RECUSADO (mesmo sendo o aprovador)');
+  assert(!A({ providedSecret: '' }).ok && /segredo do aprovador ausente/.test(A({ providedSecret: '' }).reason), '(a) segredo AUSENTE → RECUSADO');
+  assert(!A({ asId: 'alice' }).ok && /NÃO é a aprovadora/.test(A({ asId: 'alice' }).reason), '(b) identidade NÃO-aprovadora (alice) + segredo certo → RECUSADO (seleção não autoriza)');
+  assert(!A({ asId: 'mallory' }).ok, '(b) identidade DESCONHECIDA → RECUSADO');
+  assert(!A({ asId: '' }).ok, '(b) identidade VAZIA → RECUSADO');
+  assert(!A({ asId: 'Daniel' }).ok, '(b) variação de CAIXA (Daniel≠daniel) → RECUSADO (não é igualdade frouxa)');
+  assert(!A({ asId: undefined }).ok, '(b) SEM parâmetro de identidade → RECUSADO');
+  assert(!A({ secretHash: undefined }).ok && /não configurado/.test(A({ secretHash: undefined }).reason), '(e) hash do aprovador NÃO configurado → RECUSADO fail-loud');
+
+  // O segredo NUNCA aparece na razão da recusa (nunca vaza em log).
+  const reasonLeaks = [A({ providedSecret: SECRET, asId: 'alice' }), A({ providedSecret: 'ERRADO-SECRETO' }), A({ asId: 'mallory', providedSecret: SECRET })]
+    .some((r) => String(r.reason).includes(SECRET) || String(r.reason).includes('ERRADO-SECRETO'));
+  assert(!reasonLeaks, 'razão de recusa NUNCA contém o segredo (fornecido ou correto) em claro');
+
+  // approveRun (backend, MESMO code-path da CLI/UI): chamada DIRETA com segredo errado é RECUSADA,
+  // sem spawn e sem mover o marcador de awaiting/ (o teste adversarial do QA — padrão SF10.3).
+  const queueDir = tmpDir('q-approve');
+  const cfg = { queueDir, bundleDir: '/opt/bundle', runsRoot: tmpDir('runs-a'), pollMs: 1, identitiesFile: writeIdentities(VALID_IDS) };
+  const dirs = svc.ensureQueue(queueDir);
+  const runId = 'pex-guarded-1';
+  fs.writeFileSync(path.join(dirs.awaiting, `${runId}.json`), JSON.stringify({ pod: 'hn', started_by: 'alice' }));
+  let spawned = 0; const spySpawn = () => { spawned++; throw new Error('spawn NÃO deveria ocorrer numa recusa'); };
+  const logs = [];
+  const denied = await svc.approveRun(cfg, runId, { spawn: spySpawn, log: (m) => logs.push(m), asId: 'daniel', approverSecret: 'ERRADO', approverSecretHash: HASH });
+  assert(denied.denied && denied.code !== 0, 'approveRun com segredo ERRADO → RECUSADO (code != 0), sem aprovar');
+  assert(spawned === 0, 'approveRun recusado NÃO chamou spawn (nenhum efeito no executor)');
+  assert(fs.existsSync(path.join(dirs.awaiting, `${runId}.json`)), 'marcador PERMANECE em awaiting/ após recusa (nada foi reconciliado)');
+  assert(logs.some((m) => /RECUSADO/.test(m)) && !logs.some((m) => m.includes(SECRET) || m.includes('ERRADO')), 'recusa é LOGADA mas NUNCA loga o segredo (claro ou fornecido)');
+
+  // Não-aprovadora com segredo certo → recusada, também sem spawn.
+  const denied2 = await svc.approveRun(cfg, runId, { spawn: spySpawn, log: () => {}, asId: 'alice', approverSecret: SECRET, approverSecretHash: HASH });
+  assert(denied2.denied && spawned === 0, 'approveRun por identidade não-aprovadora (alice) mesmo com segredo certo → RECUSADO, sem spawn');
+}
+
+// ---------------------------------------------------------------------------
+// loadConfig — parametrização por env (genérico, sem instância VPS embutida).
+// ---------------------------------------------------------------------------
+function configTests() {
+  console.log('\n--- Config genérico por ENV (sem instância VPS hardcoded) ---');
+  const cfg = svc.loadConfig({ PODEXPORT_BUNDLE_DIR: '/b', PODEXPORT_QUEUE_DIR: '/q', PODEXPORT_POLL_MS: '500' });
+  assert(cfg.bundleDir === path.resolve('/b') && cfg.queueDir === path.resolve('/q'), 'loadConfig resolve bundle/queue do env');
+  assert(cfg.pollMs === 500, 'loadConfig lê PODEXPORT_POLL_MS');
+  const empty = svc.loadConfig({});
+  assert(empty.bundleDir === null && empty.queueDir === null, 'sem env → cfg sem paths (start exige explicitamente, fail-loud no CLI)');
+  assert(empty.runsRoot.includes('.power-claude'), 'runsRoot tem default sob .power-claude');
+}
+
+async function run() {
+  console.log('=== SF10.3 — smoke hermético do serviço-irmão (sem VPS) ===');
+  envKeyTests();
+  frontierTests();
+  chromePreflightTests();
+  coherencePreflightTests();
+  await queuePickupTests();
+  outcomeRoutingTests();
+  await approveWiringTests();
+  identityConfigTests();
+  startedByEnqueueTests();
+  await persistenceAndUsageTests();
+  await approveEnforcementTests();
+  configTests();
+
+  console.log(`\n=== ${failures === 0 ? 'PASS' : 'FALHOU'} — ${failures} falha(s) ===`);
+  process.exit(failures === 0 ? 0 : 1);
+}
+
+run().catch((e) => { console.error('[ERRO FATAL]', e); process.exit(1); });