@daniellins/power-claude 0.16.3

package/scripts/pod-export-service.cjs

@@ -0,0 +1,1297 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pod-export-service.cjs — SERVIÇO-IRMÃO de longa duração do épico pod-export (F2, Story SF10.3).
+ *
+ * Processo systemd PRÓPRIO na VPS (fora da instância Next.js do `second-brain` — isola o blast
+ * radius, ADR-018 premissa travada linha 24). NÃO reimplementa nada de SF10.2: hospeda o executor
+ * (`pod-export-executor.cjs`) por spawn e reusa o motor (`pc-run-pod.cjs`) por import (frontier
+ * command_check). Sem superfície de rede: o trigger é um CONTRATO DE DIRETÓRIO (DF2-5).
+ *
+ * Topologia (a) / DF2-1: a VPS deploya o framework NA VERSÃO pinada do lock; o motor resolve os
+ * blessed do PRÓPRIO checkout (`VETO_CHECKS_ROOT` ancorado em `__dirname`, INTOCADO). A fronteira
+ * `command_check` sai de graça — é o MESMO code-path de produção, não uma reprodução manual.
+ *
+ * Fila (DF2-5, contrato de diretório):
+ *   <queue>/pending/<id>.json      → payload de input dropado por um escritor de trigger (CLI/F3)
+ *   <queue>/processing/<runId>.json → o serviço moveu para cá e disparou o executor
+ *   <queue>/done/<runId>.json       → PIPELINE COMPLETO (todas as fases passaram) — sucesso real.
+ *   <queue>/awaiting/<runId>.json   → o run PAUSOU num checkpoint humano (result.awaiting) e saiu
+ *                                     exit 0. NÃO concluiu: é RETOMÁVEL. Sai de awaiting/ quando o
+ *                                     operador aprova (`approve <runId>` reconcilia o marcador para
+ *                                     o estado REAL do run). Achado 5 do smoke real VPS: rotear a
+ *                                     done/ era errado (o run vai continuar após o approve).
+ *   <queue>/blocked/<runId>.json    → o executor esgotou o veto numa fase (result.blocked) e saiu
+ *                                     exit 0 (bloqueio é resultado NORMAL, não crash). NÃO é sucesso:
+ *                                     roteado para cá, NUNCA para done/ (achado 4 do smoke real —
+ *                                     ver runbook §"roteamento por RESULTADO"). Triagem: qualidade,
+ *                                     não infra.
+ *   <queue>/failed/<runId>.json     → executor CRASHOU (exit != 0) — falha de infra/erro real.
+ *   <queue>/.tmp/                    → área de publicação atômica do `enqueue` (tmp + rename; DF-SF10.16-2.3).
+ *   <queue>/.service.lock           → lock O_EXCL de instância única do loop `serve` (DF-SF10.16-3.1).
+ *   approve = subcomando do PRÓPRIO serviço (`node scripts/pod-export-service.cjs approve <runId>`):
+ *             lê PODEXPORT_RUNS_DIR/BUNDLE_DIR da config e invoca o executor com --runs-root correto
+ *             (achado 6 — o approve DIRETO do executor exige a flag ou dá EACCES no dir default).
+ *
+ * Roteamento por RESULTADO (achados 4+5 do smoke real): o veredito NÃO é só o exit code. O executor
+ * imprime `RESULTADO: {...}` (`{complete:true}` | `{blocked:"<fase>"}` | `{awaiting:"<fase>"}`) e
+ * sai exit 0 nos três — bloqueio de veto e checkpoint são resultados normais, não crash. O serviço
+ * CAPTURA essa saída (parseExecutorResult) e roteia (classifyOutcome, precedência crash > awaiting/
+ * blocked > done): crash(exit!=0)→failed/, awaiting→awaiting/, blocked→blocked/, resto→done/.
+ * Overloadar done/ com runs bloqueados/pausados era um verde-falso semântico.
+ *
+ * Preflight de ARRANQUE (fail-loud, ADR-015 anti-autoatestado — o serviço RECUSA subir se a
+ * fronteira não estiver íntegra, nunca sobe "verde falso"):
+ *   1. chaves da ORG do env da VPS (getAnthropicApiKey/OpenRouter) — ausência FALHA ALTO (AC2).
+ *   2. Chrome headless presente (probeChrome do render-gate; fail-loud, ADR-011 D3, herdado) (AC4).
+ *   3. coerência framework_version motor == lock do bundle (assertFrameworkCoherence de SF10.2,
+ *      FIADA no arranque do serviço — não só no 1º run) (AC3/DF2-1).
+ *   4. self-check da fronteira command_check: prova em-deployment que blessed é aceito e
+ *      não-blessed é RECUSADO no MESMO code-path que os runs usarão (defesa em profundidade) (AC3).
+ *   5. manifesto blessed (installer/motor-scripts.js) DISPONÍVEL e não-vazio — sem ele o Guard B do
+ *      motor degrada MUDO e um .cjs plantado sob scripts/veto-checks/ passaria pelo nome
+ *      (NOTE-1 do gate de SF10.3; Story SF10.9/AC1, aferido dentro de assertCommandCheckFrontier).
+ *
+ * CONFIG por ENV (a instância VPS-específica vive no `second-brain`; aqui é genérico/parametrizável):
+ *   PODEXPORT_BUNDLE_DIR  (obrigatório p/ start) — dir do bundle compilado por F1.
+ *   PODEXPORT_QUEUE_DIR   (obrigatório p/ start) — raiz da fila (pending/processing/done/failed).
+ *   PODEXPORT_RUNS_DIR    (default <repo>/.power-claude/pod-export-runs) — runs root do executor.
+ *   PODEXPORT_LOCK        (opcional) — override do export.lock.json.
+ *   PODEXPORT_POLL_MS     (default 3000) — intervalo de poll da fila.
+ *   ANTHROPIC_API_KEY / OPENROUTER_API_KEY — chaves da ORG (nunca por request, nunca logadas).
+ *   CHROME_BIN (opcional) — honrado estritamente por render-gate.
+ *
+ * Node >= 18, zero dep externa. Rede/relógio/executor INJETÁVEIS → suíte de CI hermética.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawn } = require('node:child_process');
+
+const motor = require('./pc-run-pod.cjs');                 // INTOCADO — frontier por import (DF2-1).
+const render = require('./veto-checks/render-gate.cjs');   // probeChrome (fail-loud, ADR-011 D3).
+const executor = require('./pod-export-executor.cjs');     // assertFrameworkCoherence (AC16 de SF10.2).
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const EXECUTOR_PATH = path.join(__dirname, 'pod-export-executor.cjs');
+const MOTOR_SCRIPTS_JS = path.join(REPO_ROOT, 'installer', 'motor-scripts.js');
+const DEFAULT_POLL_MS = 3000;
+
+// ---------------------------------------------------------------------------
+// Identificador de run (SF10.9/AC5; estreitado por SF10.15/AC1) — FONTE ÚNICA da regra, no BACKEND.
+//
+// A UI (SF10.5) já validava `runId` em rejectRun/runDirFor com esta mesma regra, mas o BACKEND
+// (`approveRun`) não validava nada: o valor chegava CRU do form HTTP (`form.run`) até
+// `buildApproveArgs`/`spawn`. A regra passa a viver AQUI (o gate real, DF3-3: a UI nunca é a única
+// barreira) e a UI a reusa — um único predicado, sem duas cópias que podem divergir.
+//
+// SF10.15 (FIND-1 do gate de SF10.9, `docs/qa/gates/sf10.9.yaml`): o alfabeto aceitava `-` em
+// QUALQUER posição — inclusive a PRIMEIRA. Um runId em forma de FLAG (`--runs-root`, `--input`,
+// `--lock`, `--kill-during`, `--help`, `-rf`) passava o predicado e chegava ao `spawn` como argv,
+// onde o `parseArgs` do executor (`pod-export-executor.cjs` L342-353, casamento por string EXATA)
+// o lia como FLAG e deslocava o parsing (reproduzido pela rota real `POST /approve`). O 1º
+// caractere passa a EXIGIR `[A-Za-z0-9._]`; o `-` segue aceito nas demais posições (todo runId
+// gerado por `genRunId` é `pex-<slug>-<stamp>` — nunca começa por `-`). O fix vive no PRODUTOR do
+// argv; `parseArgs` (o consumidor) NÃO é tocado.
+// ---------------------------------------------------------------------------
+
+const RUNID_RE = /^[A-Za-z0-9._][A-Za-z0-9._-]*$/;
+
+/**
+ * True se `id` é um runId aceitável: alfabeto `[A-Za-z0-9._-]`, PRIMEIRO caractere nunca `-`
+ * (nada em forma de flag chega ao argv do executor), sem separador de path, sem `..`, sem NUL,
+ * tamanho sane (1-255).
+ */
+function safeRunId(id) {
+  return typeof id === 'string' && id.length > 0 && id.length < 256 && RUNID_RE.test(id) && !id.includes('..');
+}
+
+// ---------------------------------------------------------------------------
+// (c) Chaves da ORG do env da VPS — padrão getAnthropicApiKey (fail-loud, nunca por request).
+// ---------------------------------------------------------------------------
+
+/**
+ * Padrão `getAnthropicApiKey` da plataforma (achado concreto, second-brain/app): lê SÓ de
+ * `process.env` (env da VPS/systemd), lança fail-loud se ausente. NUNCA hardcoded, NUNCA por
+ * usuário/client/request. O valor NÃO é logado nem devolvido — só um booleano de presença.
+ */
+function getApiKey(name, envObj = process.env) {
+  const v = envObj[name];
+  if (typeof v !== 'string' || v.trim() === '') {
+    throw new Error(
+      `[FAIL-LOUD] ${name} ausente no env do serviço (VPS). Chaves da ORG são lidas do env da ` +
+      `VPS (padrão getAnthropicApiKey) — nunca hardcoded, nunca por request. Defina no unit systemd ` +
+      `(EnvironmentFile) e reinicie. O serviço RECUSA subir sem ela.`,
+    );
+  }
+  return v;
+}
+
+function getAnthropicApiKey(envObj = process.env) { return getApiKey('ANTHROPIC_API_KEY', envObj); }
+function getOpenRouterApiKey(envObj = process.env) { return getApiKey('OPENROUTER_API_KEY', envObj); }
+
+// ---------------------------------------------------------------------------
+// F3 — MODELO DE IDENTIDADE (Story SF10.4; ADR-018 Adendo F3, DF3-1..DF3-5).
+//
+// DOIS níveis de confiança, SEPARADOS por design (DF3-3):
+//   - ATRIBUIÇÃO (`started_by`): SELEÇÃO honesta, barreira FRACA. Validada contra a lista de
+//     identidades conhecidas (não é campo livre — rastreabilidade real numa equipe cooperante),
+//     persistida e consultável. NUNCA prova de identidade — o código não finge que seleção é auth.
+//   - AUTORIZAÇÃO (`approve`): SEGREDO do aprovador, verificado no BACKEND (scrypt + timingSafeEqual
+//     vs hash em env). Selecionar "Daniel" NÃO aprova; aprovar exige provar posse do segredo.
+//
+// Split genérico/instância (DF3-5): o MECANISMO (schema, loader fail-loud, enforcement) vive aqui,
+// versionado. A INSTÂNCIA (nomes reais dos 5-20, quem é `is_approver`, o HASH do segredo) é dado de
+// operador na VPS — arquivo apontado por `PODEXPORT_IDENTITIES` (chmod 600), FORA do commit. O CLARO
+// do segredo NUNCA é residente/logado: só o HASH mora no env; o claro é fornecido por-ação e
+// verificado transientemente. Zero-dep (só `node:crypto`), coerente com a doutrina do framework.
+// ---------------------------------------------------------------------------
+
+const SCRYPT_KEYLEN = 64;
+
+/**
+ * Carrega e VALIDA a config de identidades (fail-loud, DF3-5). Fonte: arquivo apontado por
+ * `opts.file` (ou `PODEXPORT_IDENTITIES` no env). Invariantes impostos NA CARGA (config inválida
+ * → recusa, nunca "verde falso"):
+ *   - env/arquivo ausente ou ilegível → recusa;
+ *   - JSON inválido, `identities` não-array, lista vazia → recusa;
+ *   - `id` ausente/vazio/não-string, ou duplicado → recusa;
+ *   - EXATAMENTE 1 `is_approver: true` (zero ou >1 → recusa) — o aprovador designado único é invariante.
+ * Retorna `{ identities, approver, byId }`. Nunca lê/expõe segredo aqui (segredo é do `approve`).
+ */
+function loadIdentities(opts = {}) {
+  const env = opts.env || process.env;
+  const file = opts.file || env.PODEXPORT_IDENTITIES;
+  if (!file || String(file).trim() === '') {
+    throw new Error(
+      '[FAIL-LOUD] PODEXPORT_IDENTITIES ausente no env — a lista de identidades conhecidas é dado de ' +
+      'operador na VPS (arquivo JSON, chmod 600, fora do commit). Sem ela não há started_by válido nem ' +
+      'aprovador designado. Defina no unit systemd (EnvironmentFile). Ver runbook §identidade.',
+    );
+  }
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); }
+  catch (e) { throw new Error(`[FAIL-LOUD] config de identidades ilegível (${file}): ${e.code || e.message}. O serviço RECUSA operar sem uma lista de identidades válida.`); }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch { throw new Error(`[FAIL-LOUD] config de identidades não é JSON válido (${file}).`); }
+  const list = parsed && Array.isArray(parsed.identities) ? parsed.identities : null;
+  if (!list || list.length === 0) {
+    throw new Error(`[FAIL-LOUD] config de identidades vazia ou sem array "identities" (${file}) — nunca operar sem operadores conhecidos.`);
+  }
+  const byId = Object.create(null);
+  let approver = null;
+  for (const it of list) {
+    if (!it || typeof it.id !== 'string' || it.id.trim() === '') {
+      throw new Error(`[FAIL-LOUD] identidade sem "id" (string não-vazia) na config (${file}).`);
+    }
+    if (Object.prototype.hasOwnProperty.call(byId, it.id)) {
+      throw new Error(`[FAIL-LOUD] "id" duplicado na config de identidades: "${it.id}" (${file}).`);
+    }
+    byId[it.id] = it;
+    if (it.is_approver === true) {
+      if (approver) {
+        throw new Error(`[FAIL-LOUD] mais de uma identidade com is_approver:true na config (${file}) — o aprovador designado deve ser ÚNICO (premissa travada "só Daniel aprova").`);
+      }
+      approver = it;
+    }
+  }
+  if (!approver) {
+    throw new Error(`[FAIL-LOUD] nenhuma identidade com is_approver:true na config (${file}) — exatamente 1 aprovador designado é invariante.`);
+  }
+  return { identities: list, approver, byId };
+}
+
+/** True se `id` é uma identidade conhecida (existe na config). Seleção honesta, não autenticação. */
+function isKnownIdentity(identityModel, id) {
+  return typeof id === 'string' && Object.prototype.hasOwnProperty.call(identityModel.byId, id);
+}
+
+/**
+ * Deriva o hash do segredo do aprovador via `scrypt` (KDF nativo, zero-dep). Formato armazenado:
+ * `scrypt$<saltHex>$<keyHex>`. Usado pelo subcomando `hash-secret` (o operador gera o hash a partir
+ * de PODEXPORT_APPROVER_SECRET e o coloca em PODEXPORT_APPROVER_SECRET_HASH). O CLARO nunca é
+ * devolvido nem logado — só o hash (que é inútil ao atacante isolado).
+ */
+function hashApproverSecret(secret, saltHex) {
+  const salt = saltHex ? Buffer.from(saltHex, 'hex') : crypto.randomBytes(16);
+  const key = crypto.scryptSync(String(secret), salt, SCRYPT_KEYLEN);
+  return `scrypt$${salt.toString('hex')}$${key.toString('hex')}`;
+}
+
+/**
+ * Verifica o segredo fornecido contra o hash armazenado, em tempo CONSTANTE (crypto.timingSafeEqual
+ * sobre buffers de mesmo comprimento — nunca compara strings com `==`, que vaza timing). Qualquer
+ * entrada malformada (segredo vazio, hash sem o formato scrypt$salt$key) → false, sem lançar. Não
+ * loga nada. Retorna só booleano.
+ */
+function verifyApproverSecret(provided, stored) {
+  if (typeof provided !== 'string' || provided === '' || typeof stored !== 'string') return false;
+  const parts = stored.split('$');
+  if (parts.length !== 3 || parts[0] !== 'scrypt') return false;
+  let salt; let expected;
+  try { salt = Buffer.from(parts[1], 'hex'); expected = Buffer.from(parts[2], 'hex'); }
+  catch { return false; }
+  if (expected.length === 0) return false;
+  let derived;
+  try { derived = crypto.scryptSync(provided, salt, expected.length); }
+  catch { return false; }
+  if (derived.length !== expected.length) return false;
+  return crypto.timingSafeEqual(derived, expected);
+}
+
+/**
+ * O GATE crítico de SF10.4 (DF3-3): SELEÇÃO ≠ AUTORIZAÇÃO. Decide se um `approve` é autorizado.
+ * Aceita SOMENTE quando (1) `asId` é a identidade designada aprovadora (`is_approver:true` na config
+ * — por flag, nunca por igualdade de string solta) E (2) o invocador prova posse do segredo do
+ * aprovador (`scrypt`+`timingSafeEqual` vs o hash em env). Recusa fail-loud e com RAZÃO (nunca o
+ * segredo) para: aprovador não configurado, `asId` ausente/vazio, identidade desconhecida,
+ * identidade não-aprovadora, segredo ausente, segredo inválido. Função PURA e hermética (sem env,
+ * sem spawn) — o alvo do teste adversarial do QA. Chamar o backend direto com identidade/segredo
+ * errado passa por AQUI e é RECUSADO.
+ */
+function authorizeApproval({ identityModel, asId, providedSecret, secretHash } = {}) {
+  if (typeof secretHash !== 'string' || secretHash.trim() === '') {
+    return { ok: false, reason: 'aprovador não configurado (PODEXPORT_APPROVER_SECRET_HASH ausente no env)' };
+  }
+  if (typeof asId !== 'string' || asId.trim() === '') {
+    return { ok: false, reason: 'identidade de aprovação ausente — approve exige --as <id>' };
+  }
+  const ident = identityModel && identityModel.byId ? identityModel.byId[asId] : null;
+  if (!ident) {
+    return { ok: false, reason: `identidade desconhecida: "${asId}" (fora da lista de identidades)` };
+  }
+  if (ident.is_approver !== true) {
+    return { ok: false, reason: `identidade "${asId}" NÃO é a aprovadora designada — selecionar não autoriza` };
+  }
+  if (typeof providedSecret !== 'string' || providedSecret === '') {
+    return { ok: false, reason: 'segredo do aprovador ausente (PODEXPORT_APPROVER_SECRET) — seleção não basta' };
+  }
+  if (!verifyApproverSecret(providedSecret, secretHash)) {
+    return { ok: false, reason: 'segredo do aprovador inválido' };
+  }
+  return { ok: true, approver: asId };
+}
+
+// ---------------------------------------------------------------------------
+// Fronteira command_check (AC3) — self-check em-deployment via motor.evalVeto (MESMO code-path).
+// ---------------------------------------------------------------------------
+
+/**
+ * Deriva o conjunto BLESSED de veto-checks da MESMA fonte que o motor carrega em runtime
+ * (`installer/motor-scripts.js` → `motorRels()`, filtrado por `scripts/veto-checks/` — ADR-007).
+ * O motor (`pc-run-pod.cjs`, INTOCADO) faz essa carga em `try/catch` silencioso: manifesto ausente
+ * ou ilegível o deixa com um `Set` VAZIO e o Guard B (`blessed.size > 0 && !blessed.has(...)`) passa
+ * a ser PULADO — estado degradado em que um `.cjs` PLANTADO fisicamente sob `scripts/veto-checks/`
+ * satisfaz a checagem de nome. Aqui a mesma carga é feita SEM catch, para que o preflight possa
+ * AFERIR a disponibilidade do manifesto e recusar o arranque (fail-loud) nesse estado.
+ * `deps.loadMotorScripts`/`deps.motorScriptsPath` injetáveis (CI hermética).
+ */
+function blessedVetoRels(deps = {}) {
+  const load = deps.loadMotorScripts || (() => require(deps.motorScriptsPath || MOTOR_SCRIPTS_JS));
+  const mod = load();
+  const rels = mod && typeof mod.motorRels === 'function' ? mod.motorRels() : [];
+  const set = new Set();
+  for (const rel of rels) if (String(rel).startsWith('scripts/veto-checks/')) set.add(String(rel));
+  return set;
+}
+
+/**
+ * Prova, no arranque, que a fronteira de ADR-011 está íntegra NESTE deployment (topologia (a)):
+ *   - o manifesto blessed (ADR-007) está DISPONÍVEL e NÃO-VAZIO — sem ele o Guard B do motor
+ *     degrada MUDO (NOTE-1 do gate de SF10.3; SF10.9/AC1);
+ *   - um nome de script NÃO-blessed é RECUSADO (sem execução) pela resolução do motor;
+ *   - um script BLESSED (html-valid.cjs) sobre HTML válido é ACEITO.
+ * Reusa `motor.evalVeto` — o code-path REAL de produção, ancorado em `VETO_CHECKS_ROOT`
+ * (`__dirname/veto-checks` do checkout deployado). Fail-loud se qualquer invariante quebrar:
+ * um serviço que sobe com a fronteira furada é exatamente o "verde falso" que ADR-015 proíbe.
+ * `deps.evalVeto` injetável para CI; default é o motor real.
+ */
+function assertCommandCheckFrontier(deps = {}) {
+  const evalVeto = deps.evalVeto || motor.evalVeto;
+  const roots = { runDir: os.tmpdir(), podRoot: REPO_ROOT };
+
+  // 0. Manifesto blessed disponível e NÃO-VAZIO (AC1). O motor pula o Guard B quando o Set está
+  //    vazio (`blessed.size > 0 && ...`): manifesto ausente/ilegível é um estado DEGRADADO silencioso
+  //    em que um `.cjs` plantado sob scripts/veto-checks/ passaria pela checagem de nome. O serviço
+  //    RECUSA subir assim — fail-loud no arranque, nunca "verde falso" (ADR-015).
+  const blessedFn = deps.blessedVetoRels || blessedVetoRels;
+  let blessed;
+  try { blessed = blessedFn(deps); } catch (e) {
+    throw new Error(
+      `[FAIL-LOUD] manifesto de scripts blessed INDISPONÍVEL (installer/motor-scripts.js: ${e.code || e.message}). ` +
+      'Sem ele o Guard B do command_check degrada MUDO (um .cjs plantado sob scripts/veto-checks/ passaria ' +
+      'na checagem de nome). Deploy incompleto — serviço RECUSADO.',
+    );
+  }
+  if (!blessed || typeof blessed.size !== 'number' || blessed.size === 0) {
+    throw new Error(
+      '[FAIL-LOUD] conjunto BLESSED de veto-checks VAZIO (installer/motor-scripts.js sem entradas ' +
+      'scripts/veto-checks/). Nesse estado o Guard B do command_check é PULADO e um script plantado ' +
+      'no diretório seria aceito pelo nome. Deploy corrompido — serviço RECUSADO.',
+    );
+  }
+
+  // 1. Não-blessed → RECUSADO (nome que não existe no manifesto/veto-checks).
+  const rejected = evalVeto(
+    { type: 'command_check', command: '__frontier_probe_should_be_rejected__.cjs' },
+    '', path.join(os.tmpdir(), 'x'), roots,
+  );
+  if (rejected.ok) {
+    throw new Error('[FAIL-LOUD] fronteira command_check FURADA: script não-blessed foi ACEITO. Deploy corrompido — serviço RECUSADO.');
+  }
+  // 2. Traversal → RECUSADO.
+  const traversal = evalVeto(
+    { type: 'command_check', command: '../smoke-pod-workflow.cjs' },
+    '', path.join(os.tmpdir(), 'x'), roots,
+  );
+  if (traversal.ok) {
+    throw new Error('[FAIL-LOUD] fronteira command_check FURADA: traversal para fora de veto-checks/ foi ACEITO. Serviço RECUSADO.');
+  }
+  // 3. Blessed sobre HTML válido → ACEITO (prova que a resolução do checkout deployado funciona).
+  const validHtml = deps.validHtmlPath || path.join(REPO_ROOT, 'scripts', '__fixtures__', 'veto-checks', 'slide-ok.html');
+  let accepted = { ok: true };
+  if (fs.existsSync(validHtml)) {
+    accepted = evalVeto({ type: 'command_check', command: 'html-valid.cjs' }, '', validHtml, roots);
+    if (!accepted.ok) {
+      throw new Error(`[FAIL-LOUD] fronteira command_check quebrada: blessed html-valid.cjs RECUSOU HTML válido (${accepted.reason}). Deploy incompleto — serviço RECUSADO.`);
+    }
+  }
+  return {
+    blessedCount: blessed.size,
+    rejectedNonBlessed: !rejected.ok,
+    rejectedTraversal: !traversal.ok,
+    acceptedBlessed: accepted.ok,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Preflight de arranque (fail-loud). Reúne 1-4 acima.
+// ---------------------------------------------------------------------------
+
+/**
+ * Executa o preflight completo. `deps` injetável (CI hermética):
+ *   deps.env         → objeto de env (default process.env)
+ *   deps.probeChrome → () => string|null (default render.probeChrome)
+ *   deps.evalVeto    → frontier (default motor.evalVeto)
+ *   deps.assertFrameworkCoherence → (bundle, lockPath) => {...} (default do executor)
+ * Retorna um resumo (booleanos/versões), NUNCA os valores das chaves. Lança na 1ª falha.
+ */
+function preflight(cfg, deps = {}) {
+  const env = deps.env || process.env;
+  const summary = { keys: {}, chrome: null, coherence: null, frontier: null };
+
+  // (1) chaves da ORG (AC2) — presença, nunca o valor.
+  getAnthropicApiKey(env);
+  getOpenRouterApiKey(env);
+  summary.keys = { anthropic: true, openrouter: true };
+
+  // (2) Chrome headless presente (AC4/e) — fail-loud herdado de ADR-011 D3, aferido no ARRANQUE.
+  const probe = deps.probeChrome || render.probeChrome;
+  const chromeBin = probe();
+  if (!chromeBin) {
+    throw new Error(
+      '[FAIL-LOUD] Chrome headless AUSENTE na VPS — o render-gate (ADR-011) não pode rodar. Defina ' +
+      'CHROME_BIN ou instale google-chrome/chromium (ver runbook: provisionamento de Chrome). ' +
+      'O serviço RECUSA subir sem ele (nunca skip-silencioso — seria verde falso).',
+    );
+  }
+  summary.chrome = path.basename(String(chromeBin));
+
+  // (3) coerência framework_version motor == lock do bundle (AC3/DF2-1) — FIADA no arranque.
+  if (cfg && cfg.bundleDir) {
+    const { bundle } = executor.loadBundle(cfg.bundleDir);
+    const lockPath = executor.resolveLockPath(bundle, cfg.lockOverride);
+    const assertCoherence = deps.assertFrameworkCoherence || executor.assertFrameworkCoherence;
+    summary.coherence = assertCoherence(bundle, lockPath); // lança fail-loud em MISMATCH.
+  }
+
+  // (4) self-check da fronteira command_check (AC3) — MESMO code-path de produção.
+  summary.frontier = assertCommandCheckFrontier(deps);
+
+  return summary;
+}
+
+// ---------------------------------------------------------------------------
+// Contrato de diretório (DF2-5). Nomes/dirs da fila.
+//
+// CONCORRÊNCIA CROSS-PROCESSO (Story SF10.16; ADR-018 Adendo F5-b, DF-SF10.16-1..DF-SF10.16-4) — a fila tem TRÊS
+// processos mutadores desde F3, com o MESMO usuário de sistema e o MESMO `ReadWritePaths`:
+//   (1) este serviço (`serve`: pending/ → processing/ → {done,awaiting,blocked,failed}/);
+//   (2) `pod-export-ui.service` (unit PRÓPRIO: `rejectRun` e `approveRun`);
+//   (3) o escritor de trigger (`enqueue`, processo separado por contrato).
+// A premissa de "instância única" com que o contrato foi escrito em F2 CADUCOU. A invariante real é
+// **cada item é reivindicado e mutado por exatamente UM ator** — e ela é mecanizada por um primitivo
+// único: `rename(2)`. Quem quer atuar sobre um item MOVE o item primeiro; o rename que sucede É a
+// autorização de agir (`existsSync`+ação está PROIBIDO como padrão de fronteira: é TOCTOU). Perder a
+// disputa é `ENOENT` — o ÚNICO errno absorvido, e só no rename de reivindicação (`claimByRename`).
+// Qualquer outro errno continua fail-loud (try/catch cego trocaria crash barulhento por degradação
+// muda — o anti-padrão que ADR-015/NOTE-1 existem para barrar).
+// ---------------------------------------------------------------------------
+
+const QUEUE_SUBDIRS = ['pending', 'processing', 'done', 'awaiting', 'blocked', 'failed'];
+/** Área de publicação atômica (DF-SF10.16-2.3): tmp NO MESMO filesystem que `pending/`, fora do caminho de
+ *  dados (`listPending` só lê `pending/` e só `*.json`). Nome com ponto = oculto ao operador. */
+const TMP_SUBDIR = '.tmp';
+/** Lock de instância do loop `serve` (DF-SF10.16-3.1) — dentro do `<queue>`, ao lado do recurso protegido. */
+const SERVICE_LOCK_FILE = '.service.lock';
+
+function ensureQueue(queueDir) {
+  const dirs = {};
+  for (const sub of QUEUE_SUBDIRS) {
+    const d = path.join(queueDir, sub);
+    fs.mkdirSync(d, { recursive: true });
+    dirs[sub] = d;
+  }
+  const tmp = path.join(queueDir, TMP_SUBDIR);
+  fs.mkdirSync(tmp, { recursive: true });
+  dirs.tmp = tmp;
+  return dirs;
+}
+
+/**
+ * PRIMITIVO ÚNICO de reivindicação da fila (DF-SF10.16-2.1/6.2). Move `src` → `dest` com `rename(2)`
+ * (atômico por POSIX: exatamente um ator entre N concorrentes vence).
+ *   - sucesso  → `true`  = REIVINDIQUEI, posso agir sobre o item.
+ *   - `ENOENT` → `false` = outro ator ganhou (ou o item nunca existiu). Caminho NORMAL: o chamador
+ *                pula o item e SEGUE (o serviço nunca encerra o loop; a UI responde "já tratado").
+ *   - qualquer OUTRO errno (`EACCES`, `EIO`, `ENOSPC`, `EXDEV`, `ENOTDIR`...) → RELANÇA, fail-loud.
+ * Nunca use `try/catch` cego em volta desta chamada: a sanção é POR CÓDIGO DE ERRO, por desenho.
+ */
+function claimByRename(src, dest) {
+  try {
+    fs.renameSync(src, dest);
+    return true;
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return false; // perdi a disputa — sinal sancionado, não erro.
+    throw e;                                     // todo o resto continua fail-loud.
+  }
+}
+
+/** Lista os payloads pendentes em ordem estável (FIFO por nome). Só `*.json`. */
+function listPending(queueDir) {
+  const pend = path.join(queueDir, 'pending');
+  if (!fs.existsSync(pend)) return [];
+  return fs.readdirSync(pend).filter((f) => f.endsWith('.json')).sort()
+    .map((f) => path.join(pend, f));
+}
+
+function genRunId(baseName) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const slug = path.basename(baseName, '.json').replace(/[^A-Za-z0-9_-]/g, '') || 'run';
+  return `pex-${slug}-${stamp}`;
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch do executor (SF10.2) por SPAWN. Injetável para CI (deps.runExecutor).
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrai o RESULTADO do executor da sua saída. O executor imprime, na última linha, uma linha
+ * `RESULTADO: {json}` com o desfecho do drive (`{complete:true}` | `{blocked:"<fase>"}` |
+ * `{awaiting:"<fase>"}` | `{halted:true}`). Devolve o objeto parseado, ou null se ausente/ilegível.
+ * Varre de baixo para cima (o último RESULTADO é o vigente). Testável sem VPS (parsing puro).
+ */
+function parseExecutorResult(stdout) {
+  const lines = String(stdout || '').split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const m = lines[i].match(/^\s*RESULTADO:\s*(\{.*\})\s*$/);
+    if (m) { try { return JSON.parse(m[1]); } catch { return null; } }
+  }
+  return null;
+}
+
+/**
+ * Classifica o desfecho de um run em kind da fila a partir de (exit code + RESULTADO capturado).
+ * Precedência: crash > awaiting/blocked > done (achados 4 e 5 do smoke real VPS):
+ *   crash (code != 0)          → 'failed'   (erro/infra — o executor caiu).
+ *   result.awaiting (exit 0)   → 'awaiting' (PAUSOU no checkpoint humano — NÃO concluiu; retomável
+ *                                 via approve. Rotear a done/ era errado: o run vai continuar).
+ *   result.blocked (exit 0)    → 'blocked'  (veto esgotado numa fase — resultado normal, NÃO sucesso).
+ *   caso contrário (exit 0)    → 'done'     (pipeline completo — dispatch concluído com sucesso).
+ * `awaiting` e `blocked` são mutuamente exclusivos no drive; a ordem entre eles não altera o veredito.
+ */
+function classifyOutcome(result) {
+  const code = result && typeof result.code === 'number' ? result.code : 1;
+  const outcome = result && result.result;
+  if (code !== 0) return { kind: 'failed', code, blocked: null, awaiting: null };
+  if (outcome && outcome.awaiting) return { kind: 'awaiting', code, blocked: null, awaiting: outcome.awaiting };
+  if (outcome && outcome.blocked) return { kind: 'blocked', code, blocked: outcome.blocked, awaiting: null };
+  return { kind: 'done', code, blocked: null, awaiting: null };
+}
+
+/**
+ * Dispara o executor de SF10.2 como processo filho: `node pod-export-executor.cjs <bundle> run
+ * <runId> --input <payload> --runs-root <runs>`. As chaves da ORG são passadas por ENV do filho
+ * (nunca por CLI/arquivo por request). CAPTURA stdout (para ler o RESULTADO — achado 4) e ainda o
+ * ecoa ao journald (tee); stderr continua herdado. Resolve { code, result } no exit. deps.spawn
+ * injetável.
+ */
+function spawnExecutor(cfg, payloadPath, runId, deps = {}) {
+  return new Promise((resolve) => {
+    const spawnFn = deps.spawn || spawn;
+    const args = [EXECUTOR_PATH, cfg.bundleDir, 'run', runId, '--input', payloadPath, '--runs-root', cfg.runsRoot];
+    if (cfg.lockOverride) args.push('--lock', cfg.lockOverride);
+    const child = spawnFn(process.execPath, args, {
+      env: {
+        ...(deps.env || process.env),
+        ANTHROPIC_API_KEY: getAnthropicApiKey(deps.env || process.env),
+        OPENROUTER_API_KEY: getOpenRouterApiKey(deps.env || process.env),
+      },
+      stdio: ['ignore', 'pipe', 'inherit'], // stdout PIPE p/ capturar o RESULTADO; stderr → journald.
+    });
+    let out = '';
+    if (child.stdout) child.stdout.on('data', (d) => { const s = d.toString(); out += s; process.stdout.write(s); });
+    child.on('exit', (code) => resolve({ code: code == null ? 1 : code, result: parseExecutorResult(out) }));
+    child.on('error', () => resolve({ code: 1, result: null }));
+  });
+}
+
+/**
+ * Processa UM payload pendente: move pending → processing, dispara o executor, e roteia para
+ * done/ | blocked/ | failed/ conforme (exit code + RESULTADO capturado) — ver classifyOutcome
+ * (achado 4 do smoke real: bloqueio de veto sai exit 0 e NÃO pode cair em done/). Escreve um
+ * `<runId>.result.json` com o veredito (nunca o relato do subagente decide). `deps.runExecutor`
+ * injetável (CI): deve resolver `{ code, result }` (result = RESULTADO parseado, ou null).
+ */
+async function processOne(cfg, pendingPath, deps = {}) {
+  const dirs = ensureQueue(cfg.queueDir);
+  const runId = genRunId(pendingPath);
+  const processingPath = path.join(dirs.processing, `${runId}.json`);
+  const log = deps.log || ((m) => console.log(m));
+  // REIVINDICAÇÃO (DF-SF10.16-2.1): o rename É a autorização de processar. Se outro ator (2º loop `serve`,
+  // um `enqueue` que sobrescreveu, um operador) ganhou a disputa, `ENOENT` significa "não é meu" —
+  // pula o item e SEGUE servindo. Antes de SF10.16 isto lançava e derrubava o worker inteiro por UM
+  // item (com `Restart=on-failure`+`StartLimitBurst`, 5 colisões em 60s = unit em `failed` permanente).
+  if (!claimByRename(pendingPath, processingPath)) {
+    log(`[fila] item já reivindicado por outro ator: ${path.basename(pendingPath)} — pulando (o serviço SEGUE servindo)`);
+    return { claimed: false, skipped: true, pendingPath, reason: 'claim-lost' };
+  }
+  log(`[fila] pickup ${path.basename(pendingPath)} → processing/${runId}.json`);
+
+  // started_by/pod do payload movido (AC3: persistência/rastreabilidade). Tolerante a payload
+  // legado sem started_by (drop direto no dir — DF2-5): registra null, não fail-loud aqui (a
+  // validação fail-loud é do enqueue, o boundary de ingestão sancionado).
+  //
+  // SF10.16/AC3 — payload ILEGÍVEL (não é JSON) NÃO é despachado. Antes, um payload observado
+  // meio-publicado (`enqueue` gravava direto no destino: o nome ficava visível ao `readdir` ANTES do
+  // conteúdo) era reivindicado, entregue VAZIO ao executor e registrado com `started_by: null` — o
+  // gate fail-loud de identidade de DF3-3 ("nunca run anônimo") era contornado EM SILÊNCIO. A
+  // publicação agora é atômica (`enqueue` via `.tmp/`+rename), e este guard fecha a via residual
+  // (drop manual de operador apanhado no meio de um `cp`): vai para `failed/` sem gastar LLM.
+  let meta = null;
+  let parseError = null;
+  try { meta = JSON.parse(fs.readFileSync(processingPath, 'utf8')); } catch (e) { parseError = e; }
+  if (!meta || typeof meta !== 'object') {
+    const reason = `payload ILEGÍVEL ou incompleto (${parseError ? parseError.message : 'não é um objeto JSON'}) — publicação parcial ou arquivo corrompido`;
+    const failedPath = path.join(dirs.failed, `${runId}.json`);
+    fs.renameSync(processingPath, failedPath);
+    fs.writeFileSync(path.join(dirs.failed, `${runId}.result.json`), JSON.stringify({
+      runId, kind: 'failed', exitCode: 2, ok: false, started_by: null, blocked: null, awaiting: null,
+      outcome: null, at: new Date().toISOString(), error: reason,
+    }, null, 2));
+    log(`[fila][FAIL-LOUD] ${runId}: ${reason}. NÃO despachado ao executor (nenhum run anônimo, nenhum gasto de LLM). Publique com \`enqueue\` (atômico) ou copie para <queue>/.tmp/ e só então \`mv\` para pending/.`);
+    return { claimed: true, runId, ok: false, kind: 'failed', exitCode: 2, blocked: null, awaiting: null, finalPath: failedPath, resultPath: path.join(dirs.failed, `${runId}.result.json`), rejectedPayload: true };
+  }
+  const startedBy = typeof meta.started_by === 'string' ? meta.started_by : null;
+
+  const runExecutor = deps.runExecutor || ((c, p, id, d) => spawnExecutor(c, p, id, d));
+  let result;
+  try {
+    result = await runExecutor(cfg, processingPath, runId, deps);
+  } catch (e) {
+    result = { code: 1, error: e.message, result: null };
+  }
+  const { kind, code, blocked, awaiting } = classifyOutcome(result);
+  const ok = kind === 'done';
+  const finalDir = dirs[kind];
+  const finalPath = path.join(finalDir, `${runId}.json`);
+  fs.renameSync(processingPath, finalPath);
+  const resultPath = path.join(finalDir, `${runId}.result.json`);
+  fs.writeFileSync(resultPath, JSON.stringify({
+    runId, kind, exitCode: code, ok, started_by: startedBy, blocked: blocked || null, awaiting: awaiting || null,
+    outcome: (result && result.result) || null, at: new Date().toISOString(), error: result && result.error,
+  }, null, 2));
+  // Ledger de uso por started_by (DF3-4) — 1 registro por run finalizado (freio, não billing).
+  const usage = extractUsage(result);
+  appendUsage(cfg, { started_by: startedBy, runId, pod: meta.pod || null, kind, ...usage, at: new Date().toISOString() });
+  const tag = blocked ? `, blocked@${blocked}` : (awaiting ? `, awaiting@${awaiting}` : '');
+  log(`[fila] ${kind.toUpperCase()} ${runId} (exit ${code}${tag})`);
+  return { claimed: true, runId, ok, kind, exitCode: code, blocked: blocked || null, awaiting: awaiting || null, finalPath, resultPath };
+}
+
+// ---------------------------------------------------------------------------
+// approve via o SERVIÇO (achado 6). O approve DIRETO do executor NÃO honra PODEXPORT_RUNS_DIR (usa
+// o default .power-claude/pod-export-runs, relativo ao framework — EACCES para o usuário do serviço)
+// e EXIGE a flag --runs-root. Aqui o operador aprova com a MESMA config do serviço (consistente com
+// enqueue/status): lê runsRoot/bundleDir da config e passa --runs-root correto ao executor.
+// ---------------------------------------------------------------------------
+
+/** Monta o argv do executor para `approve <runId>` COM --runs-root da config (achado 6). Puro/testável. */
+function buildApproveArgs(cfg, runId) {
+  const args = [EXECUTOR_PATH, cfg.bundleDir, 'approve', runId, '--runs-root', cfg.runsRoot];
+  if (cfg.lockOverride) args.push('--lock', cfg.lockOverride);
+  return args;
+}
+
+/**
+ * Deriva o kind REAL de um run a partir do seu state.json em disco (motor, read-only) — usado para
+ * reconciliar o marcador da fila após um approve (NÃO adivinha; lê o estado verdadeiro):
+ *   qualquer step failed            → 'failed'
+ *   qualquer step awaiting_approval → 'awaiting' (outro checkpoint — continua retomável)
+ *   todos os steps done             → 'done'
+ *   ainda em progresso (running/pending) → null (nada a reconciliar por approve).
+ * `deps.findStateByRunId`/`deps.readState` injetáveis (CI hermética; default = motor de produção).
+ */
+function deriveRunKind(cfg, runId, deps = {}) {
+  const findState = deps.findStateByRunId || motor.findStateByRunId;
+  const readState = deps.readState || motor.readState;
+  const statePath = findState(cfg.runsRoot, runId);
+  if (!statePath) return null;
+  const statuses = Object.values(readState(statePath).steps).map((s) => s.status);
+  if (statuses.some((s) => s === 'failed')) return 'failed';
+  if (statuses.some((s) => s === 'awaiting_approval')) return 'awaiting';
+  if (statuses.length > 0 && statuses.every((s) => s === 'done')) return 'done';
+  return null;
+}
+
+/**
+ * REIVINDICAÇÃO do marcador para um `approve` (SF10.16/AC1, DF-SF10.16-2.1). Chamada ESTRITAMENTE DEPOIS da
+ * decisão de autorização de DF3-3 (segredo/`is_approver`) e ANTES do `spawn` do executor: ela não
+ * autoriza nada — apenas SERIALIZA quem já foi autorizado. Sem ela, dois `approve` concorrentes do
+ * mesmo `runId` davam DOIS `spawn` sobre o MESMO `runDir` (dois escritores no mesmo `state.json` e
+ * gasto de LLM DUPLICADO — o vetor mais caro e menos visível dos três).
+ *
+ * Mecânica: `awaiting/<runId>.json` → `processing/<runId>.json` por `claimByRename`.
+ *   - `{ claimed: true }`               → sou o dono; sigo para o spawn.
+ *   - `{ claimed: false, busy: true }`  → o marcador está em `processing/`: OUTRO ator (approve
+ *                                         concorrente ou o próprio worker) o detém → RECUSA.
+ *   - `{ claimed: false, absent: true }` → o run não tem marcador na fila (approve fora-da-fila,
+ *                                         ex.: run disparado direto pelo executor) → comportamento
+ *                                         INALTERADO: segue e aprova. A reivindicação é CONDICIONAL
+ *                                         à existência do marcador, NUNCA um novo motivo de recusa.
+ */
+function claimApproveMarker(cfg, runId, deps = {}) {
+  if (!cfg.queueDir) return { claimed: false, absent: true };
+  const dirs = ensureQueue(cfg.queueDir);
+  const src = path.join(dirs.awaiting, `${runId}.json`);
+  const dest = path.join(dirs.processing, `${runId}.json`);
+  if (claimByRename(src, dest)) return { claimed: true, src, dest };
+  // Não estava em awaiting/. Se está em processing/, outro ator o reivindicou AGORA (ou o worker o
+  // está processando): recusar é o comportamento correto. Caso contrário, não há marcador na fila.
+  if (fs.existsSync(dest)) return { claimed: false, busy: true, dest };
+  return { claimed: false, absent: true };
+}
+
+/** Devolve um marcador reivindicado por `claimApproveMarker` a `awaiting/` (approve sem efeito de
+ *  fila: executor falhou ou nada a reconciliar). Mantém o estado observável idêntico ao pré-SF10.16. */
+function releaseApproveMarker(cfg, runId, claim, deps = {}) {
+  if (!claim || !claim.claimed) return false;
+  const dirs = ensureQueue(cfg.queueDir);
+  const back = claimByRename(claim.dest, path.join(dirs.awaiting, `${runId}.json`));
+  if (!back) {
+    (deps.log || ((m) => console.log(m)))(`[approve][AVISO] marcador de ${runId} não estava mais em processing/ ao devolver — outro ator já o moveu (o run em disco é a fonte da verdade).`);
+  }
+  return back;
+}
+
+/**
+ * Move o marcador da fila `<runId>.json` (tipicamente em awaiting/ após um checkpoint) para o
+ * subdir do `kind` derivado, e reescreve o `<runId>.result.json`. Idempotente. Sem queueDir ou sem
+ * kind → no-op (approve de um run que não veio da fila). Testável só com fs.
+ */
+function reconcileMarker(cfg, runId, kind, deps = {}) {
+  if (!cfg.queueDir || !kind) return null;
+  const dirs = ensureQueue(cfg.queueDir);
+  const dest = path.join(dirs[kind], `${runId}.json`);
+  // SF10.16/AC1: reivindicar em vez de `existsSync`+ação. O approve chega aqui já DONO do marcador
+  // (reivindicado em `claimApproveMarker`, tipicamente em `processing/`), mas a varredura continua
+  // tolerante: o rename que sucede é a autorização; `ENOENT` = outro ator já moveu (segue para o
+  // próximo candidato). Qualquer outro errno permanece fail-loud.
+  let moved = false;
+  if (fs.existsSync(dest)) {
+    moved = true; // já está no destino (idempotência) — nada a mover.
+  } else {
+    for (const sub of ['processing', 'awaiting', 'done', 'blocked', 'failed']) {
+      if (sub === kind) continue;
+      if (claimByRename(path.join(dirs[sub], `${runId}.json`), dest)) { moved = true; break; }
+    }
+  }
+  if (!moved) return null;
+  const resultPath = path.join(dirs[kind], `${runId}.result.json`);
+  fs.writeFileSync(resultPath, JSON.stringify({ runId, kind, ok: kind === 'done', reconciledBy: 'approve', at: new Date().toISOString() }, null, 2));
+  (deps.log || ((m) => console.log(m)))(`[approve] ${runId} reconciliado → ${kind}/`);
+  return { runId, kind, dest, resultPath };
+}
+
+/**
+ * Aprova um checkpoint via o serviço. GATE crítico de SF10.4 (DF3-3): ANTES de qualquer efeito, o
+ * `approve` só é aceito quando a identidade `--as` é a aprovadora designada (`is_approver:true`) E o
+ * invocador prova o segredo do aprovador (scrypt+timingSafeEqual vs PODEXPORT_APPROVER_SECRET_HASH).
+ * Este é o MESMO code-path da CLI e da futura UI (SF10.5): chamar o backend direto com
+ * identidade/segredo errado passa por aqui e é RECUSADO (sem spawn, sem reconciliação) — recusa
+ * fail-loud e LOGADA com a razão (NUNCA o segredo). Só após autorizar: invoca o executor `approve`
+ * com --runs-root da config (achado 6), captura o RESULTADO, e reconcilia o marcador da fila para o
+ * estado REAL do run (achado 5). Identidade/segredo vêm de deps (CI) ou do env (CLI):
+ * `deps.asId`/PODEXPORT_APPROVER_AS, `deps.approverSecret`/PODEXPORT_APPROVER_SECRET,
+ * `deps.approverSecretHash`/PODEXPORT_APPROVER_SECRET_HASH. Resolve { code, result } ou
+ * { code, denied:true, reason } na recusa.
+ */
+function approveRun(cfg, runId, deps = {}) {
+  return new Promise((resolve) => {
+    const env = deps.env || process.env;
+    const log = deps.log || ((m) => console.log(m));
+    // (0a) SF10.9/AC5 — `runId` é entrada NÃO-CONFIÁVEL (vem cru do form HTTP da UI, `form.run`).
+    // Validação PRIMEIRO, antes de QUALQUER efeito: antes de ler a config de identidades, antes do
+    // gate de autorização e — sobretudo — antes de `buildApproveArgs`/`spawn`. Mesma regra já usada
+    // em rejectRun/runDirFor (safeRunId, fonte única acima). Nunca ecoa o valor recebido no log.
+    if (!safeRunId(runId)) {
+      const reason = 'runId inválido (formato não aceito: exige [A-Za-z0-9._-] com 1º caractere ≠ "-", sem "..", 1-255 chars)';
+      log(`[approve][RECUSADO] runId inválido: ${reason} — recusado antes de qualquer efeito (sem spawn).`);
+      return resolve({ code: 3, denied: true, reason, result: null });
+    }
+    // (0b) GATE F3 — seleção ≠ autorização. Recusa ANTES de qualquer spawn/efeito.
+    let identityModel;
+    try { identityModel = deps.identityModel || loadIdentities({ env, file: cfg.identitiesFile }); }
+    catch (e) { log(`[approve][RECUSADO] ${runId}: ${e.message}`); return resolve({ code: 3, denied: true, reason: e.message, result: null }); }
+    const auth = authorizeApproval({
+      identityModel,
+      asId: deps.asId != null ? deps.asId : env.PODEXPORT_APPROVER_AS,
+      providedSecret: deps.approverSecret != null ? deps.approverSecret : env.PODEXPORT_APPROVER_SECRET,
+      secretHash: deps.approverSecretHash != null ? deps.approverSecretHash : env.PODEXPORT_APPROVER_SECRET_HASH,
+    });
+    if (!auth.ok) {
+      log(`[approve][RECUSADO] ${runId}: ${auth.reason}`); // razão nunca contém o segredo.
+      return resolve({ code: 3, denied: true, reason: auth.reason, result: null });
+    }
+    log(`[approve][AUTORIZADO] ${runId} por ${auth.approver} (segredo verificado, timing-safe)`);
+    // (0c) SF10.16/AC1 — REIVINDICAÇÃO, estritamente DEPOIS da decisão de autorização acima e ANTES
+    // do spawn. Não altera QUEM pode aprovar (o gate de DF3-3 já decidiu): serializa quem já foi
+    // autorizado, fechando o DUPLO SPAWN (dois executores no mesmo runDir = gasto de LLM em dobro).
+    const claim = claimApproveMarker(cfg, runId, deps);
+    if (claim.busy) {
+      const reason = 'checkpoint já reivindicado por outra aprovação em andamento (o marcador saiu de awaiting/)';
+      log(`[approve][RECUSADO] ${runId}: ${reason} — nenhum spawn (evita executor duplicado no mesmo runDir).`);
+      return resolve({ code: 3, denied: true, gone: true, reason, result: null });
+    }
+    const spawnFn = deps.spawn || spawn;
+    const child = spawnFn(process.execPath, buildApproveArgs(cfg, runId), {
+      env: deps.env || process.env,
+      stdio: ['ignore', 'pipe', 'inherit'],
+    });
+    let out = '';
+    if (child.stdout) child.stdout.on('data', (d) => { const s = d.toString(); out += s; process.stdout.write(s); });
+    child.on('exit', (code) => {
+      const result = { code: code == null ? 1 : code, result: parseExecutorResult(out) };
+      let reconciled = null;
+      if (result.code === 0) {
+        try { const kind = deriveRunKind(cfg, runId, deps); if (kind) reconciled = reconcileMarker(cfg, runId, kind, deps); }
+        catch (e) { (deps.log || ((m) => console.log(m)))(`[approve] aviso: reconciliação do marcador falhou (${e.message}) — o run em disco é a fonte da verdade.`); }
+      }
+      // Sem reconciliação (executor falhou, ou o run ainda não mudou de estado): DEVOLVE o marcador a
+      // awaiting/ — o checkpoint continua visível/retomável, exatamente como antes de SF10.16.
+      if (!reconciled) releaseApproveMarker(cfg, runId, claim, deps);
+      resolve(result);
+    });
+    child.on('error', () => { releaseApproveMarker(cfg, runId, claim, deps); resolve({ code: 1, result: null }); });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Loop de serviço (systemd de longa duração). Poll da fila; sem superfície de rede.
+// ---------------------------------------------------------------------------
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Path do lock de instância do `serve`, DENTRO do `<queue>` (já em `ReadWritePaths`, já com o
+ *  ownership do serviço) — nunca em `/run/...`: zero mudança de unit/provision (DF-SF10.16-3.1). */
+function serviceLockPath(queueDir) { return path.join(queueDir, SERVICE_LOCK_FILE); }
+
+/**
+ * Liveness de um pid (DF-SF10.16-3.1). `ESRCH` = MORTO (única condição que autoriza tomar posse do lock).
+ * `EPERM` = processo VIVO sob outro dono — NUNCA interpretar como morto. Qualquer outro erro é
+ * tratado conservadoramente como VIVO (recusar arranque é reversível; roubar o lock de um worker
+ * vivo produziria dois workers na mesma fila, o estado que este lock existe para impedir).
+ */
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return !(e && e.code === 'ESRCH'); }
+}
+
+/**
+ * PUBLICAÇÃO do lock: COMPLETO ou inexistente, e EXCLUSIVA (SF10.16/LOCK-1).
+ *
+ * Grava o conteúdo inteiro em `<queue>/.tmp/` e publica com **`link(2)`** — o irmão EXCLUSIVO do
+ * `rename(2)`: falha com `EEXIST` se o destino já existe, em vez de substituí-lo em silêncio.
+ * `rename` seria ERRADO aqui (roubaria o lock de um dono vivo); `link` dá as duas propriedades de que
+ * o lock precisa ao mesmo tempo: **atomicidade de conteúdo** e **exclusão mútua**.
+ *
+ * Era exatamente aqui que estava o defeito LOCK-1: `openSync(lockPath, 'wx')` cria o arquivo VAZIO e
+ * só depois o preenche. Nessa janela, um segundo arranque lia um arquivo vazio, concluía
+ * "corrompido/órfão" e REMOVIA o lock VIVO do vencedor — dois donos simultâneos, de forma
+ * determinística. É o mesmo defeito que esta story fecha em `pending/` (nome visível antes do
+ * conteúdo), que faltava aplicar ao próprio lock. Retorna `true` se publicou, `false` em `EEXIST`.
+ */
+function publishServiceLock(dirs, lockPath, payload) {
+  const tmp = path.join(dirs.tmp, `service.lock.${payload.pid}.${crypto.randomBytes(6).toString('hex')}`);
+  fs.writeFileSync(tmp, JSON.stringify(payload, null, 2)); // completo ANTES de existir sob o nome oficial.
+  let published = false;
+  try {
+    fs.linkSync(tmp, lockPath); // EEXIST se já há dono — nunca sobrescreve.
+    published = true;
+  } catch (e) {
+    if (!e || e.code !== 'EEXIST') throw e; // EACCES/EIO/EXDEV/... → fail-loud.
+  }
+  try { fs.unlinkSync(tmp); } catch (e) { if (!e || e.code !== 'ENOENT') throw e; }
+  return published;
+}
+
+/**
+ * Lê um arquivo de lock e CLASSIFICA, com sanção por errno (nunca catch-all — era o corolário de
+ * LOCK-1: um `catch { prev = null }` engolia `EACCES` e o tratava como "corrompido", o que levava a
+ * REMOVER um lock que talvez estivesse vivo):
+ *   `gone`    → `ENOENT`: sumiu entre a tentativa e a leitura (o chamador reavalia).
+ *   `corrupt` → conteúdo ilegível/sem `pid` (veredito de CONTEÚDO, não erro de E/S).
+ *   `ok`      → `{pid, host, startedAt}` válido.
+ * Qualquer OUTRO errno de leitura é RELANÇADO (fail-loud).
+ */
+function readServiceLock(lockPath) {
+  let raw;
+  try { raw = fs.readFileSync(lockPath, 'utf8'); }
+  catch (e) {
+    if (e && e.code === 'ENOENT') return { state: 'gone' };
+    throw e; // EACCES/EIO/... — nunca confundir "não consigo ler" com "está corrompido".
+  }
+  let parsed = null;
+  try { parsed = JSON.parse(raw); } catch { parsed = null; } // veredito de conteúdo, não de E/S.
+  if (!parsed || typeof parsed.pid !== 'number') return { state: 'corrupt', raw };
+  return { state: 'ok', lock: parsed, raw };
+}
+
+/**
+ * ASSERÇÃO da invariante residual de instância única do loop `serve` (SF10.16/AC4, DF-SF10.16-3.1).
+ * Publica `<queue>/.service.lock` COMPLETO e em EXCLUSÃO MÚTUA (`publishServiceLock`: tmp + `link`).
+ * Em `EEXIST`, ARBITRA sobre um conteúdo que — por construção — nunca está "meio escrito":
+ *   - conteúdo ilegível/corrompido → assume ÓRFÃO, AVISA ALTO e toma posse (um lock corrompido jamais
+ *     pode imobilizar o serviço);
+ *   - `host` diferente → RECUSA fail-loud (a fila é local por contrato);
+ *   - pid MORTO (`ESRCH`) → AVISA ALTO e toma posse (cobre `SIGKILL`/`OOM`);
+ *   - pid VIVO (inclusive `EPERM`) → RECUSA fail-loud com mensagem ACIONÁVEL (pid, desde quando, como limpar).
+ *
+ * A TOMADA DE POSSE é REIVINDICADA, não presumida: o órfão é movido para `.tmp/` com `claimByRename`
+ * (exatamente um ator consegue mover um dado arquivo; os demais recebem `ENOENT` e reavaliam) e o que
+ * foi movido é CONFERIDO contra o que se julgou. Se o arquivo capturado não for o órfão julgado — ou
+ * seja, se alguém publicou um lock novo entre o julgamento e a captura — ele é DEVOLVIDO por `link`
+ * (que nunca sobrescreve) e a arbitragem recomeça. Assim nenhum caminho remove um lock VIVO.
+ * Restrição DOMINANTE do desenho: **nenhum caminho pode deixar o serviço permanentemente incapaz de
+ * subir** (órfão real, lock ilegível e lock sumido continuam todos se resolvendo sozinhos).
+ */
+function acquireServiceLock(cfg, deps = {}) {
+  const log = deps.log || ((m) => console.log(m));
+  const warn = deps.warn || ((m) => console.error(m));
+  const isAlive = deps.pidAlive || pidAlive;
+  const host = deps.hostname || os.hostname();
+  const pid = deps.pid || process.pid;
+  const dirs = ensureQueue(cfg.queueDir);
+  const lockPath = serviceLockPath(cfg.queueDir);
+  for (let attempt = 0; attempt < 8; attempt++) {
+    if (publishServiceLock(dirs, lockPath, { pid, host, startedAt: new Date().toISOString() })) {
+      log(`[lock] instância única assegurada: ${lockPath} (pid ${pid}, host ${host})`);
+      return { path: lockPath, pid, host };
+    }
+    // Há um dono publicado. Arbitra sobre conteúdo COMPLETO (a publicação é atômica).
+    const cur = readServiceLock(lockPath);
+    if (cur.state === 'gone') continue; // liberado entre o link e a leitura — tenta publicar de novo.
+    if (cur.state === 'ok') {
+      const prev = cur.lock;
+      if (prev.host && prev.host !== host) {
+        throw new Error(
+          `[FAIL-LOUD] a fila ${cfg.queueDir} está travada por um serviço em OUTRO host ("${prev.host}", pid ${prev.pid}, desde ${prev.startedAt || '?'}) — ` +
+          'a fila é LOCAL por contrato (DF2-5): dois hosts sobre o mesmo diretório é erro de operação. Corrija o mount/deploy. ' +
+          `Se tiver CERTEZA de que aquele serviço não existe mais, remova ${lockPath} e suba de novo.`,
+        );
+      }
+      if (isAlive(prev.pid)) {
+        throw new Error(
+          `[FAIL-LOUD] já existe um pod-export-service servindo esta fila (pid ${prev.pid} em ${prev.host || '?'}, desde ${prev.startedAt || '?'}). ` +
+          'Um SEGUNDO loop `serve` na mesma fila não é a topologia suportada (SF10.16/DF-SF10.16-3). Como resolver: ' +
+          `\`systemctl status pod-export\` e \`systemctl stop pod-export\` antes de subir outro; ou, se o pid ${prev.pid} comprovadamente não existe ` +
+          `(\`ps -p ${prev.pid}\`), remova ${lockPath} e suba de novo.`,
+        );
+      }
+      warn(`[lock][AVISO ALTO] lock ÓRFÃO em ${lockPath} (pid ${prev.pid} MORTO, desde ${prev.startedAt || '?'}) — provável SIGKILL/queda abrupta. Tomando posse.`);
+    } else {
+      warn(`[lock][AVISO ALTO] ${lockPath} ilegível/corrompido — assumindo lock ÓRFÃO e tomando posse (um lock ilegível nunca pode imobilizar o serviço).`);
+    }
+
+    // Tomada de posse REIVINDICADA: move o órfão para um nome privado. Só UM ator consegue.
+    const stash = path.join(dirs.tmp, `service.lock.orfao.${pid}.${crypto.randomBytes(6).toString('hex')}`);
+    if (!claimByRename(lockPath, stash)) continue; // outro ator já o moveu — reavalia do zero.
+    const taken = readServiceLock(stash);
+    const mesmoOrfao = (cur.state === 'corrupt' && taken.state === 'corrupt' && taken.raw === cur.raw)
+      || (cur.state === 'ok' && taken.state === 'ok'
+        && taken.lock.pid === cur.lock.pid && taken.lock.startedAt === cur.lock.startedAt);
+    if (!mesmoOrfao) {
+      // Capturei um lock PUBLICADO DEPOIS do meu julgamento (dono possivelmente VIVO): devolvo por
+      // `link` — que nunca sobrescreve — e recomeço a arbitragem sobre ele.
+      let devolvido = false;
+      try { fs.linkSync(stash, lockPath); devolvido = true; }
+      catch (e) { if (!e || e.code !== 'EEXIST') throw e; }
+      try { fs.unlinkSync(stash); } catch (e) { if (!e || e.code !== 'ENOENT') throw e; }
+      if (!devolvido) {
+        throw new Error(
+          `[FAIL-LOUD] corrida de arranque anômala em ${lockPath}: o lock foi trocado por outro ator duas vezes durante a arbitragem. ` +
+          'NENHUM lock foi tomado por este processo (recusa é o desfecho seguro: nunca dois serviços na mesma fila). ' +
+          'Verifique quantos `systemctl start`/processos concorrentes existem sobre esta fila e suba um só.',
+        );
+      }
+      continue;
+    }
+    try { fs.unlinkSync(stash); } catch (e) { if (!e || e.code !== 'ENOENT') throw e; }
+    // `lockPath` está livre e o órfão foi meu: a próxima volta publica (e o `link` reserializa).
+  }
+  throw new Error(
+    `[FAIL-LOUD] não foi possível adquirir ${lockPath} após 8 tentativas — disputa persistente de arranque. ` +
+    'Verifique se há mais de um `systemctl start` concorrente sobre a mesma fila.',
+  );
+}
+
+/** Libera o lock de instância. Só remove o lock que É NOSSO (compara o pid gravado) — nunca o de um
+ *  sucessor que já tomou posse. Best-effort e LOGADO: falhar aqui deixa um órfão, que o arranque
+ *  seguinte cura sozinho; lançar durante `SIGTERM` seria pior (DF-SF10.16-3: nada imobiliza o serviço). */
+function releaseServiceLock(handle, deps = {}) {
+  if (!handle || !handle.path) return false;
+  const warn = deps.warn || ((m) => console.error(m));
+  // Mesma sanção por errno da aquisição (LOCK-1): `ENOENT` = nada a liberar; conteúdo de OUTRO dono =
+  // não é nosso, não removemos; e um erro de E/S REAL (EACCES/EIO) não pode ser confundido com
+  // "corrompido" — sem conseguir provar a posse, NÃO removemos (o órfão resultante se cura no
+  // arranque seguinte; remover o lock de outro seria pior). Nunca lança: roda em SIGTERM/finally.
+  let cur;
+  try { cur = readServiceLock(handle.path); }
+  catch (e) {
+    warn(`[lock][AVISO ALTO] não foi possível LER ${handle.path} para liberar (${e.code || e.message}) — posse não comprovada, o lock NÃO será removido. O próximo arranque arbitra.`);
+    return false;
+  }
+  if (cur.state === 'gone') return false;
+  if (cur.state === 'ok' && cur.lock.pid !== handle.pid) return false; // já é de outro dono.
+  try { fs.unlinkSync(handle.path); return true; }
+  catch (e) {
+    if (e && e.code === 'ENOENT') return false;
+    warn(`[lock][AVISO ALTO] falha ao liberar ${handle.path} (${e.code || e.message}) — o próximo arranque tomará posse do órfão automaticamente.`);
+    return false;
+  }
+}
+
+/**
+ * RELATO de órfãos em `processing/` no arranque (SF10.16/AC5, DF-SF10.16-3.2): marcadores deixados por um
+ * run interrompido (`systemctl restart`/crash no meio). São LISTADOS e LOGADOS ALTO com a idade.
+ * **REQUEUE AUTOMÁTICO É PROIBIDO**: o run órfão pode ter consumido LLM e escrito um `runDir`
+ * parcial — reenfileirar por conta própria gasta dinheiro de novo e pode produzir estado
+ * inconsistente. Reenfileirar é AÇÃO DE OPERADOR, documentada no runbook. Esta função NUNCA move
+ * nada; só informa (a resposta honesta a "e um restart no meio de um run?": o run é perdido, e agora
+ * se SABE disso — antes o marcador ficava lá para sempre, sem dono e sem alarme).
+ */
+function reportProcessingOrphans(cfg, deps = {}) {
+  const warn = deps.warn || ((m) => console.error(m));
+  const dir = path.join(cfg.queueDir, 'processing');
+  if (!fs.existsSync(dir)) return [];
+  const now = deps.now ? deps.now() : Date.now();
+  const orphans = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    if (!f.endsWith('.json') || f.endsWith('.result.json')) continue;
+    const p = path.join(dir, f);
+    let mtimeMs = null;
+    try { mtimeMs = fs.statSync(p).mtimeMs; } catch (e) { if (!e || e.code !== 'ENOENT') throw e; continue; }
+    orphans.push({ name: f, path: p, ageMs: Math.max(0, now - mtimeMs), runId: f.slice(0, -'.json'.length) });
+  }
+  if (orphans.length > 0) {
+    warn(`[fila][AVISO ALTO] ${orphans.length} marcador(es) ÓRFÃO(S) em processing/ — runs interrompidos (restart/crash no meio). REQUEUE AUTOMÁTICO NÃO É FEITO (o run pode ter gasto LLM e escrito runDir parcial): triagem é ação de operador — ver runbook §"Órfão em processing/".`);
+    for (const o of orphans) {
+      warn(`[fila][AVISO ALTO]   ${o.name} (parado há ${Math.round(o.ageMs / 1000)}s) — inspecione com \`status ${o.runId}\` antes de decidir.`);
+    }
+  }
+  return orphans;
+}
+
+/**
+ * Loop principal: preflight (fail-loud), lock de instância única, relato de órfãos, e então poll de
+ * pending/. `deps.stopAfter` (nº de ciclos) e `deps.sleep` tornam o loop TESTÁVEL sem rodar para
+ * sempre. Sem stopAfter roda indefinido.
+ *
+ * SF10.16: o loop NUNCA encerra por perder uma disputa de item — `processOne` devolve
+ * `{claimed:false}` e o serviço SEGUE servindo (antes, o `ENOENT` do rename subia até `main().catch`
+ * e derrubava o worker inteiro por UM item). O `existsSync` pré-pickup foi REMOVIDO: era TOCTOU puro
+ * (a única autorização válida é o rename que sucede).
+ */
+async function serve(cfg, deps = {}) {
+  const log = deps.log || ((m) => console.log(m));
+  const summary = preflight(cfg, deps);
+  log(`[preflight OK] chrome=${summary.chrome} framework=${summary.coherence ? summary.coherence.engineVersion : 'n/a'} frontier=${JSON.stringify(summary.frontier)}`);
+  ensureQueue(cfg.queueDir);
+  // Lock APÓS o preflight e ANTES do primeiro poll (DF-SF10.16-3.1).
+  const lock = acquireServiceLock(cfg, deps);
+  reportProcessingOrphans(cfg, deps);
+  // Liberação em saída limpa E em SIGTERM/SIGINT: sem estes handlers, todo `systemctl stop` (que
+  // envia SIGTERM) deixaria um lock órfão e a tomada de posse viraria ROTINA em vez de rede de
+  // segurança. SIGKILL continua coberto pela tomada de posse no arranque seguinte.
+  const onExit = () => { releaseServiceLock(lock, deps); };
+  const onSignal = (sig) => { log(`[lock] ${sig} recebido — liberando ${lock.path} e encerrando.`); releaseServiceLock(lock, deps); process.exit(sig === 'SIGINT' ? 130 : 143); };
+  const onTerm = () => onSignal('SIGTERM');
+  const onInt = () => onSignal('SIGINT');
+  if (deps.installSignalHandlers !== false) {
+    process.on('exit', onExit); process.on('SIGTERM', onTerm); process.on('SIGINT', onInt);
+  }
+  const doSleep = deps.sleep || sleep;
+  let cycles = 0;
+  const processed = [];
+  try {
+    while (true) {
+      const pending = listPending(cfg.queueDir);
+      for (const p of pending) {
+        const r = await processOne(cfg, p, deps); // a reivindicação (rename) É a autorização.
+        if (r && r.claimed) processed.push(r);
+      }
+      cycles++;
+      if (deps.stopAfter && cycles >= deps.stopAfter) break;
+      await doSleep(cfg.pollMs || DEFAULT_POLL_MS);
+    }
+  } finally {
+    if (deps.installSignalHandlers !== false) {
+      process.removeListener('exit', onExit); process.removeListener('SIGTERM', onTerm); process.removeListener('SIGINT', onInt);
+    }
+    releaseServiceLock(lock, deps);
+  }
+  return { cycles, processed };
+}
+
+// ---------------------------------------------------------------------------
+// CLI: start | approve | enqueue | preflight | status.
+// ---------------------------------------------------------------------------
+
+function loadConfig(env = process.env, overrides = {}) {
+  const bundleDir = overrides.bundleDir || env.PODEXPORT_BUNDLE_DIR;
+  const queueDir = overrides.queueDir || env.PODEXPORT_QUEUE_DIR;
+  return {
+    bundleDir: bundleDir ? path.resolve(bundleDir) : null,
+    queueDir: queueDir ? path.resolve(queueDir) : null,
+    runsRoot: path.resolve(overrides.runsRoot || env.PODEXPORT_RUNS_DIR || path.join(REPO_ROOT, '.power-claude', 'pod-export-runs')),
+    lockOverride: overrides.lock || env.PODEXPORT_LOCK || null,
+    pollMs: Number(overrides.pollMs || env.PODEXPORT_POLL_MS || DEFAULT_POLL_MS),
+    identitiesFile: overrides.identitiesFile || env.PODEXPORT_IDENTITIES || null,
+  };
+}
+
+/**
+ * enqueue: escritor de trigger (CLI/F3). Valida `started_by` (AC1/AC2, DF3-3) e escreve o payload em
+ * <queue>/pending/. `started_by` é OBRIGATÓRIO e deve ser uma identidade CONHECIDA (config
+ * PODEXPORT_IDENTITIES) — ausente ou fora da lista → recusa fail-loud (nunca run anônimo na v1).
+ * `deps.startedBy` é o açúcar `--started-by` (injeta o campo se o payload não o traz; a fonte-de-
+ * verdade continua sendo o campo do payload). `deps.identityModel` injetável (CI hermética).
+ */
+function enqueue(cfg, srcPayload, deps = {}) {
+  const dirs = ensureQueue(cfg.queueDir);
+  const src = path.resolve(srcPayload);
+  if (!fs.existsSync(src)) throw new Error(`payload não encontrado: ${srcPayload}`);
+  const payload = JSON.parse(fs.readFileSync(src, 'utf8')); // valida que é JSON antes de enfileirar.
+  if (deps.startedBy != null) payload.started_by = deps.startedBy; // açúcar --started-by.
+  const identityModel = deps.identityModel || loadIdentities({ env: deps.env || process.env, file: cfg.identitiesFile });
+  const startedBy = payload.started_by;
+  if (typeof startedBy !== 'string' || startedBy.trim() === '') {
+    throw new Error(
+      '[FAIL-LOUD] payload sem "started_by" — todo run registra quem o iniciou (seleção honesta, ' +
+      'DF3-3). Nunca run anônimo na v1. Adicione "started_by":"<id>" ao payload ou use --started-by <id>.',
+    );
+  }
+  if (!isKnownIdentity(identityModel, startedBy)) {
+    throw new Error(
+      `[FAIL-LOUD] started_by "${startedBy}" fora da lista de identidades conhecidas (PODEXPORT_IDENTITIES) — ` +
+      'não é campo livre; é rastreabilidade real. Adicione a identidade à config ou corrija o payload.',
+    );
+  }
+  const name = `${Date.now()}-${path.basename(src)}`;
+  const dest = path.join(dirs.pending, name);
+  // PUBLICAÇÃO ATÔMICA (SF10.16/AC3, DF-SF10.16-2.3): grava em `<queue>/.tmp/` (MESMO filesystem, requisito
+  // do rename) e só então renomeia para `pending/`. O item passa a existir COMPLETO ou a não existir.
+  // Antes, `writeFileSync` direto no destino tornava o nome visível ao `readdir` do serviço ANTES do
+  // conteúdo: um payload meio-publicado era reivindicado, entregue VAZIO ao executor e registrado com
+  // `started_by: null` — o gate fail-loud de identidade de DF3-3 era contornado EM SILÊNCIO.
+  const tmp = path.join(dirs.tmp, `${name}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  fs.writeFileSync(tmp, JSON.stringify(payload, null, 2)); // grava o payload (pode ter started_by injetado).
+  try {
+    fs.renameSync(tmp, dest); // torna VISÍVEL, já completo.
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch (e2) { if (!e2 || e2.code !== 'ENOENT') throw e2; } // não deixa lixo em .tmp/.
+    throw e; // publicação falhou → fail-loud (nada de "enfileirado" que não existe).
+  }
+  return dest;
+}
+
+// ---------------------------------------------------------------------------
+// Ledger de USO por `started_by` (DF3-4) — freio mínimo, NÃO billing. Log append-only JSONL, 1
+// registro por run finalizado (escrito pelo serviço em processOne). Campos: {started_by, runId, pod,
+// tokens_in, tokens_out, imagens, at}. Os tokens vêm do `usage` que o executor expõe no RESULTADO
+// (forward-compat: quando ausente, registra 0 — o freio fica vazio, honesto). `usage` AGREGA por
+// started_by: dá para VER quem gasta, NUNCA para CAPAR (linha 127 do ADR verbatim).
+// ---------------------------------------------------------------------------
+
+function usageLogPath(cfg) { return path.join(cfg.queueDir, 'usage.log.jsonl'); }
+
+/** Extrai o usage de um RESULTADO do executor (tolerante a nomes: input_tokens/tokens_in etc). */
+function extractUsage(result) {
+  const u = (result && result.result && result.result.usage) || {};
+  return {
+    tokens_in: Number(u.input_tokens || u.tokens_in || 0) || 0,
+    tokens_out: Number(u.output_tokens || u.tokens_out || 0) || 0,
+    imagens: Number(u.images || u.imagens || 0) || 0,
+  };
+}
+
+/** Anexa 1 registro ao ledger append-only (JSONL). No-op sem queueDir. Idempotência não garantida (é log). */
+function appendUsage(cfg, record) {
+  if (!cfg.queueDir) return null;
+  ensureQueue(cfg.queueDir);
+  const line = JSON.stringify({
+    started_by: record.started_by || null,
+    runId: record.runId,
+    pod: record.pod || null,
+    kind: record.kind || null,
+    tokens_in: record.tokens_in || 0,
+    tokens_out: record.tokens_out || 0,
+    imagens: record.imagens || 0,
+    at: record.at || new Date().toISOString(),
+  });
+  fs.appendFileSync(usageLogPath(cfg), `${line}\n`);
+  return usageLogPath(cfg);
+}
+
+/** Agrega o ledger por `started_by`: {started_by, runs, tokens_in, tokens_out, imagens}. Linhas ilegíveis são puladas. */
+function aggregateUsage(cfg) {
+  const p = usageLogPath(cfg);
+  const agg = Object.create(null);
+  if (!cfg.queueDir || !fs.existsSync(p)) return agg;
+  for (const line of fs.readFileSync(p, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let r; try { r = JSON.parse(line); } catch { continue; }
+    const k = r.started_by || '(desconhecido)';
+    if (!agg[k]) agg[k] = { started_by: k, runs: 0, tokens_in: 0, tokens_out: 0, imagens: 0 };
+    agg[k].runs += 1;
+    agg[k].tokens_in += Number(r.tokens_in || 0) || 0;
+    agg[k].tokens_out += Number(r.tokens_out || 0) || 0;
+    agg[k].imagens += Number(r.imagens || 0) || 0;
+  }
+  return agg;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  const cfg = loadConfig();
+
+  if (cmd === 'start') {
+    if (!cfg.bundleDir || !cfg.queueDir) { console.error('start exige PODEXPORT_BUNDLE_DIR e PODEXPORT_QUEUE_DIR no env.'); process.exit(2); }
+    console.log(`[pod-export-service] start — bundle=${cfg.bundleDir} queue=${cfg.queueDir} runs=${cfg.runsRoot}`);
+    await serve(cfg);
+  } else if (cmd === 'preflight') {
+    if (!cfg.bundleDir) { console.error('preflight exige ao menos PODEXPORT_BUNDLE_DIR (coerência de versão) no env.'); process.exit(2); }
+    try {
+      const s = preflight(cfg);
+      console.log('[preflight OK]', JSON.stringify(s));
+    } catch (e) { console.error(e.message); process.exit(1); }
+  } else if (cmd === 'enqueue') {
+    if (!cfg.queueDir) { console.error('enqueue exige PODEXPORT_QUEUE_DIR no env.'); process.exit(2); }
+    const sbIdx = argv.indexOf('--started-by');
+    const startedBy = sbIdx !== -1 ? argv[sbIdx + 1] : undefined; // açúcar; a fonte-de-verdade é o campo do payload.
+    try {
+      const dest = enqueue(cfg, argv[1], { startedBy });
+      console.log(`[enqueue] ${dest}`);
+    } catch (e) { console.error(e.message); process.exit(1); }
+  } else if (cmd === 'approve') {
+    // approve via o PRÓPRIO serviço (achado 6) + GATE F3 (DF3-3): exige --as <id> (aprovador
+    // designado) E o segredo do aprovador (PODEXPORT_APPROVER_SECRET no env desta invocação,
+    // verificado vs PODEXPORT_APPROVER_SECRET_HASH). Seleção não autoriza; o backend recusa
+    // identidade/segredo errado. --runs-root vem da config; reconcilia o marcador de awaiting/.
+    const runId = argv[1];
+    const asIdx = argv.indexOf('--as');
+    const asId = asIdx !== -1 ? argv[asIdx + 1] : undefined;
+    if (!cfg.bundleDir || !runId) { console.error('approve exige PODEXPORT_BUNDLE_DIR e <runId> --as <id> (segredo via PODEXPORT_APPROVER_SECRET; runsRoot de PODEXPORT_RUNS_DIR).'); process.exit(2); }
+    const r = await approveRun(cfg, runId, { asId });
+    if (r.denied) { console.error(`[approve][RECUSADO] ${r.reason}`); process.exit(r.code || 3); }
+    process.exit(r.code || 0);
+  } else if (cmd === 'status') {
+    const runId = argv[1];
+    if (!cfg.bundleDir || !runId) { console.error('status exige PODEXPORT_BUNDLE_DIR e <runId>.'); process.exit(2); }
+    const child = spawn(process.execPath, [EXECUTOR_PATH, cfg.bundleDir, 'status', runId, '--runs-root', cfg.runsRoot], { stdio: 'inherit' });
+    child.on('exit', (code) => process.exit(code || 0));
+  } else if (cmd === 'usage') {
+    // Ledger de uso agregado por started_by (DF3-4) — freio, VER quem gasta; NUNCA capar orçamento.
+    if (!cfg.queueDir) { console.error('usage exige PODEXPORT_QUEUE_DIR no env.'); process.exit(2); }
+    console.log(JSON.stringify(aggregateUsage(cfg), null, 2));
+  } else if (cmd === 'identities') {
+    // Valida/inspeciona a config de identidades (fail-loud). Nunca imprime segredo (não há segredo aqui).
+    try {
+      const m = loadIdentities({ file: cfg.identitiesFile });
+      console.log(JSON.stringify({ count: m.identities.length, approver: m.approver.id, ids: m.identities.map((i) => i.id) }, null, 2));
+    } catch (e) { console.error(e.message); process.exit(1); }
+  } else if (cmd === 'hash-secret') {
+    // Gera o hash a colocar em PODEXPORT_APPROVER_SECRET_HASH a partir de PODEXPORT_APPROVER_SECRET.
+    // Imprime SÓ o hash (inútil ao atacante isolado); o CLARO nunca é logado.
+    const s = process.env.PODEXPORT_APPROVER_SECRET;
+    if (!s || String(s).trim() === '') { console.error('defina PODEXPORT_APPROVER_SECRET no env para gerar o hash (o claro nunca é logado).'); process.exit(2); }
+    console.log(hashApproverSecret(s));
+  } else {
+    console.error('Uso: node scripts/pod-export-service.cjs <start|preflight|enqueue <payload.json> [--started-by <id>]|approve <runId> --as <id>|status <runId>|usage|identities|hash-secret>');
+    console.error('Config por ENV: PODEXPORT_BUNDLE_DIR, PODEXPORT_QUEUE_DIR, PODEXPORT_RUNS_DIR, PODEXPORT_LOCK, PODEXPORT_POLL_MS, PODEXPORT_IDENTITIES, PODEXPORT_APPROVER_SECRET(_HASH), ANTHROPIC_API_KEY, OPENROUTER_API_KEY, CHROME_BIN.');
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('[ERRO]', e.message); process.exit(1); });
+}
+
+module.exports = {
+  getApiKey,
+  getAnthropicApiKey,
+  getOpenRouterApiKey,
+  safeRunId,
+  blessedVetoRels,
+  assertCommandCheckFrontier,
+  preflight,
+  ensureQueue,
+  claimByRename,
+  listPending,
+  genRunId,
+  parseExecutorResult,
+  classifyOutcome,
+  spawnExecutor,
+  processOne,
+  buildApproveArgs,
+  deriveRunKind,
+  claimApproveMarker,
+  releaseApproveMarker,
+  reconcileMarker,
+  approveRun,
+  serviceLockPath,
+  pidAlive,
+  acquireServiceLock,
+  releaseServiceLock,
+  reportProcessingOrphans,
+  serve,
+  loadConfig,
+  enqueue,
+  loadIdentities,
+  isKnownIdentity,
+  hashApproverSecret,
+  verifyApproverSecret,
+  authorizeApproval,
+  usageLogPath,
+  extractUsage,
+  appendUsage,
+  aggregateUsage,
+  QUEUE_SUBDIRS,
+  TMP_SUBDIR,
+  SERVICE_LOCK_FILE,
+  EXECUTOR_PATH,
+};