engine-kit 0.2.5 → 0.2.7

package/CONTRATO-MOTOR.md

@@ -64,13 +64,14 @@ O script faz, em ordem e com *fail-loud* em cada passo:
 2. assina cada artefato e **prova a assinatura na hora** (valida o legítimo, recusa o adulterado);
 3. cria a release no registry (recusa se a tag já existir — artefato assinado não se sobrescreve);
 4. espelha no repo privado, se `-SourceRepo` (falha aqui **avisa**, não aborta: não é o canônico);
-5. atualiza o `manifest.json` **parseado** (nunca regex em JSON);
+5. num worktree temporário a partir da `main` (`tools/publish-manifest.mjs`), atualiza o `manifest.json`
+   **parseado** (nunca regex em JSON) e a linha do motor no README;
 6. **prova o caminho real**: baixa a release publicada e valida `sha256` + assinatura como um
    consumidor faria. *"Publiquei"* não é prova — asset faltando, `.sig` esquecido e tag errada só
-   aparecem quando alguém tenta instalar, em produção.
-
-Depois: commitar e enviar o `manifest.json`. **Consumidores só enxergam a mudança após o push** —
-até lá o registry publicado continua descrevendo a versão anterior.
+   aparecem quando alguém tenta instalar, em produção;
+7. com a prova verde, commita e envia o manifest e o README para a `main` (é dela que os consumidores
+   leem) e mescla a `main` na `develop` (conflito só no manifest ou no README: a `develop` recebe a mesma mudança).
+   Prova vermelha não envia nada; a cópia de trabalho local não é tocada.
 
 ## 4. Onde o motor instala — e como o consumidor ACHA
 

package/README.md

@@ -1,8 +1,13 @@
 # engine-registry
 
-Vitrine de **MOTORES** compartilhados e, em uma seção separada, de aplicativos
+Repositório (marketplace) de **MOTORES independentes** e, em uma seção separada, de aplicativos
 distribuídos. O `engine-kit` continua lendo somente `manifest.engines`.
 
+O registry não é um motor que acopla outros motores: é a prateleira de onde cada motor é baixado,
+conferido e atualizado. Cada motor tem a própria release, a própria chave de assinatura e a própria
+versão; nenhum motor declara dependência de outro no manifest, e cada um recebe atualizações
+separadamente (e pode ser fixado sozinho com `engine-kit pin`).
+
 Um motor **não é um plugin**: não se instala pela vitrine de extensões, não tem `hooks` nem
 `extensions`. Ele é **infraestrutura**: instala **uma vez por máquina** em `~/.<motor>` e serve
 **N consumidores** (Copilot, Claude Code, Cursor, VS Code, scripts…), sem depender do host.
@@ -26,13 +31,13 @@ vive num lugar só e o consumidor apenas **declara a dependência**.
 | Motor | Versão | Tipo | O que faz |
 |---|---|---|---|
 | `embed-house` | 1.0.5 | `daemon` (http) | Casa de embeddings (MiniLM-L6-v2, 384-dim): carrega o modelo uma vez e serve vetores a N consumidores. |
-| `vox-engine` | 0.28.7 | `daemon` (pipe), **self-managed** | Motor de voz (STT/TTS) compartilhado, com auto-unload quando ocioso. Traz o próprio instalador e updater. |
-| `mcp-gateway` | 0.17.2 | `daemon` (http) | Agregador MCP: conecta uma vez em cada servidor MCP e reexpõe tudo num endpoint único. |
-| `neural-link` | 0.7.15 | `cli` | Dispatcher adaptativo de hooks: recebe o evento por stdin, pontua os handlers e devolve uma decisão composta. |
-| `vxk` | 0.21.0 | `cli` | Explicações visuais animadas e narradas como servidor MCP (stdio): devolve UM HTML autocontido e offline, ou o vídeo MP4 (preset, aplicativo real, Motion) e o PDF. Um daemon único por máquina atende os agentes. A narração vem do `vox-engine`. |
+| `vox-engine` | 0.33.1 | `daemon` (pipe), **self-managed** | Motor de voz (STT/TTS) compartilhado, com auto-unload quando ocioso. Traz o próprio instalador e updater. |
+| `mcp-gateway` | 0.17.5 | `daemon` (http) | Agregador MCP: conecta uma vez em cada servidor MCP e reexpõe tudo num endpoint único. |
+| `neural-link` | 0.7.16 | `cli` | Dispatcher adaptativo de hooks: recebe o evento por stdin, pontua os handlers e devolve uma decisão composta. |
+| `vxk` | 0.23.0 | `cli` | Explicações visuais animadas e narradas como servidor MCP (stdio): devolve UM HTML autocontido e offline, ou o vídeo MP4 (preset, aplicativo real, Motion) e o PDF. Um daemon único por máquina atende os agentes. A narração vem do `vox-engine`. |
 | `cerne` | 0.4.14 | `daemon`, **self-managed** | Leitura ativa de vídeo (captura, quadros, transcrição, tradução) exposta via MCP. Instalador Inno por usuário, Windows. |
-| `skill-engine` | 0.2.1 | `cli` | Gerencia skills de agentes fora de qualquer IDE: busca repositórios em quarentena, varre com regras determinísticas e só ativa o que sai limpo. |
-| `client-harness` | 0.1.5 | `cli` | Daemon local que faz o Claude Code e o Codex respeitarem os padrões de cada cliente: confere cada ação do agente contra as regras da pasta e recusa antes de gravar, com o motivo. |
+| `skill-engine` | 0.3.0 | `cli` | Gerencia skills de agentes fora de qualquer IDE: busca repositórios em quarentena, varre com regras determinísticas e só ativa o que sai limpo. |
+| `client-harness` | 0.1.8 | `cli` | Daemon local que faz o Claude Code e o Codex respeitarem os padrões de cada cliente: confere cada ação do agente contra as regras da pasta e recusa antes de gravar, com o motivo. |
 
 **Todos** são publicados aqui, assinados com Ed25519 e verificados antes de instalar.
 
@@ -59,7 +64,10 @@ Sem clonar o repositório, com Node 18 ou mais:
 
 ```sh
 npx engine-kit ensure vxk                     # instala ou atualiza; reusa se já estiver em dia
-npx engine-kit ensure vxk --version 0.21.0    # pin de versão
+npx engine-kit ensure vxk --version 0.23.0    # versão exata (downgrade permitido)
+npx engine-kit pin vxk                        # congela o vxk na versão instalada
+npx engine-kit pin vxk --version 0.22.0       # instala essa versão (assinatura conferida) e congela
+npx engine-kit unpin vxk                      # o vxk volta a receber atualizações
 ```
 
 O `npx` baixa o kit do npm e o kit baixa o motor da release, confere o **sha256**, a **assinatura Ed25519**
@@ -74,6 +82,12 @@ mesmo comando nela (o `npx` sem versão reusaria a da cache); o motor instalado
 registry, com o aviso `motor atualizado: <motor> vA → vB`. `ENGINE_KIT_NO_AUTO_UPDATE=1` desliga as duas trocas e
 deixa só o aviso de versão nova disponível. `--version` explícito sempre vale.
 
+Pin por motor: `engine-kit pin <motor>` grava a versão fixada só desse motor no `trust.json` da máquina. A
+atualização automática (o `ensure`, o `doctor --fix` e o `ensureEngine` dos consumidores) pula os motores fixados e
+continua atualizando os outros. Um `ensure --version` diferente da versão fixada é recusado com a saída (trocar o pin
+ou `unpin`); um consumidor que exige versão maior que a fixada recebe `available:false` explicando o `unpin`. Motores
+`self-managed` não são fixados pelo kit.
+
 Publicar o kit: tag `engine-kit-v<versão do package.json>` criada na `main`; o workflow `.github/workflows/publish.yml`
 roda a suíte e publica por OIDC (sem token guardado). Conferir a proveniência: `npm audit signatures` num projeto
 que dependa do `engine-kit`, ou o selo "Provenance" na página do pacote.
@@ -85,7 +99,8 @@ node kit/doctor.mjs          # diagnostica: o que reusar, atualizar ou baixar
 node kit/doctor.mjs --fix    # aplica
 ```
 
-Desatualizado → atualiza. Ausente → baixa. **Atualizado → reusa** — e o diagnóstico não baixa nada,
+Desatualizado → atualiza. Ausente → baixa. **Atualizado → reusa**. Fixado (`engine-kit pin`) → `FIXADO`, fica na
+versão fixada; instalado diferente do pin → `FORA DO PIN`, e o `--fix` instala a versão fixada. O diagnóstico não baixa nada,
 porque reusar é o caminho comum e precisa ser barato. Antes de trocar um daemon vivo, o doctor pede
 o `shutdownPath` que o registry declara: no Windows, arquivo em uso não pode ser sobrescrito.
 
@@ -170,6 +185,16 @@ dele não exige reassinar nada):
 **Uma chave por motor**, não uma chave do publisher: um vazamento obriga a republicar aquele
 motor, não a casa inteira.
 
+Backup da pasta de chaves, cifrado com uma frase-senha (scrypt + AES-256-GCM) e gravado igual em duas mídias offline:
+
+```sh
+node tools/backup-keys.mjs backup --to E:\ --to F:\        # pede a frase-senha sem eco; relê e decifra as duas cópias
+node tools/backup-keys.mjs check E:\engine-signing-<data>.ekb   # decifra e compara com ~/.engine-signing
+node tools/backup-keys.mjs restore E:\engine-signing-<data>.ekb --to <pasta nova>
+```
+
+A frase-senha nunca vai em argumento, variável de ambiente ou log (`--passphrase-stdin` lê da entrada padrão).
+
 Política do `provision`, sem meio-termo silencioso:
 
 | Situação no registry | O que acontece |
@@ -192,7 +217,9 @@ assim:
 | **Pin do consumidor** | `ensureEngine(nome, { trustedKeys: { "<motor>": "<hex>" } })`; divergência = **ABORT** já no 1º contato | não depende do registry em momento nenhum (padrão do `vox-engine`) |
 | **Chave no pacote** (`npx engine-kit ensure`) | o comando fixa a chave do `manifest.json` embarcado no pacote do npm | registry comprometido **antes** do 1º contato: trocar a chave exige publicar um engine-kit novo, e a publicação deixa proveniência pública |
 
-Rotação legítima é **ato explícito**: apagar a entrada em `~/.engine-kit/trust.json`.
+Rotação legítima é **ato explícito**: apagar a entrada em `~/.engine-kit/trust.json`. Um `trust.json` que existe e
+não se lê falha fechado: `ensure`, `pin`, `unpin`, `ensureEngine` e o doctor recusam explicando e não regravam o arquivo,
+para não apagar as chaves de primeiro contato e os pins dos outros motores.
 
 **O que isto NÃO cobre, dito na cara:** comprometimento **anterior** ao primeiro contato (o TOFU
 grava a chave do atacante), downgrade/replay e expiração. Fechar isso exige transparência pública
@@ -210,8 +237,10 @@ kit/
   resolve.mjs      # descobre o motor no registry (cache 6h, degrada p/ cache obsoleto)
   provision.mjs    # baixa/atualiza: SHA256 + assinatura fail-closed, lock e swap atômico
   lifecycle.mjs    # garante o processo vivo (daemon) ou entrega o binário (cli)
-  cli.mjs          # comando `engine-kit` (bin do pacote): `npx engine-kit ensure <motor>`
-  ensure.mjs       # ensure: resolve → provision com a chave do manifest embarcado no pacote
+  trust.mjs        # trust.json por motor: chave do 1º contato, maior versão vista (anti-rollback) e o pin
+  cli.mjs          # comando `engine-kit` (bin do pacote): ensure, pin e unpin
+  ensure.mjs       # ensure, pin e unpin: resolve → provision com a chave do manifest embarcado no pacote
+  doctor.mjs       # concilia a máquina inteira (OK, DESATUALIZADO, AUSENTE, FIXADO...); --fix aplica
   update.mjs       # o kit se atualiza (relança na última versão do npm); ENGINE_KIT_NO_AUTO_UPDATE=1 desliga
   signature.mjs    # contrato ed25519-sha256-raw — assinar e verificar na MESMA fonte
   keystore.mjs     # onde moram as chaves privadas (~/.engine-signing)
@@ -224,7 +253,7 @@ kit/
 consumers/
   mcp-gateway.mjs  # adaptador pronto: handshake + token + shutdown do agregador MCP
 site/               # vitrine de produto dos motores (estática); processo em docs/PAGES.md
-tools/              # pages-branch.mjs: publica site/ na gh-pages
+tools/              # pages-branch.mjs: publica site/ na gh-pages; publish-manifest.mjs: manifest e README na main
 tests/
   smoke.mjs          # contratos do kit: node tests/smoke.mjs
   test-*.mjs         # contratos hermeticos (assinatura, trust, tar, apps, cache, doctor, gateway)
@@ -243,6 +272,13 @@ node tests/e2e-install.mjs               # baixa e sobe o mcp-gateway num HOME i
 node tests/e2e-install.mjs --local       # idem, mas usando o manifest.json que você vai publicar
 ```
 
+Para ver quais repositórios e workflows consomem os minutos do GitHub Actions da conta logada no `gh` (só leitura; os maiores
+consumidores vêm marcados, assim como jobs que nem iniciaram por cobrança):
+
+```sh
+node tools/actions-minutes.mjs [--month AAAA-MM] [--days 3] [--top 5] [--json]
+```
+
 ## Publicar um motor
 
 Veja o passo a passo completo em [`CONTRATO-MOTOR.md`](./CONTRATO-MOTOR.md). Em resumo:
@@ -256,8 +292,10 @@ pwsh kit/publish-base.ps1 -Engine <motor> -Version <x.y.z> -Asset <artefato.tgz>
 
 O `publish-base.ps1` confere a identidade do `gh` (o app Copilot injeta o token de uma conta de
 trabalho nos processos filhos e o `gh` publica pela conta errada), assina, publica no registry,
-atualiza o `manifest.json` **parseado** e então **prova**: baixa a release publicada e valida
-`sha256` + assinatura pelo caminho de um consumidor.
+atualiza o `manifest.json` **parseado** e a linha do README num worktree da `main`, **prova** (baixa a
+release publicada e valida `sha256` + assinatura pelo caminho de um consumidor) e só então envia o commit
+para a `main` e mescla na `develop`, sem passo manual. Se a mescla conflitar só no `manifest.json` ou no
+README (linhas vizinhas mudadas nos dois ramos), o arquivo da `develop` recebe a mesma mudança que a `main` recebeu.
 
 O artefato deve ser **self-contained** (traz o próprio `node_modules` trimado): o motor precisa
 subir numa máquina limpa, sem depender do consumidor.
@@ -271,7 +309,8 @@ plataforma, e a release mora aqui, no registry público, com download **sem logi
 
 | App | Versão | Plataformas | O que faz |
 |---|---|---|---|
-| `agent-launcher` | 1.3.5 | `win32-x64` | Abre Claude Code, Codex, Copilot CLI, VS Code e o Copilot app nos seus projetos por qualquer host de modelos. Leva só o launcher; cada ferramenta se instala pelo cartão dela. |
+| `agent-launcher` | 1.3.6 | `win32-x64` | Abre Claude Code, Codex, Copilot CLI, VS Code e o Copilot app nos seus projetos por qualquer host de modelos. Leva só o launcher; cada ferramenta se instala pelo cartão dela. |
+| `smart-design` | 0.2.2 | `win32-x64` | Serviço local que o agente de código chama por MCP para desenhar telas com sistema de design, renderizá-las e conferi-las em pixels antes de entregar. |
 
 Um app só entra nesta tabela e em `manifest.apps` **depois** de a release pública existir e passar
 em `node kit/verify-release.mjs --app <nome>` (download anônimo de todos os assets, `.sha256` e

package/consumers/mcp-gateway.mjs

@@ -19,6 +19,7 @@ import { join, dirname, resolve as resolvePath, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { ensureEngine } from "../kit/index.mjs";
+import { waitExit } from "../kit/lifecycle.mjs";
 
 const DEFAULT_HOME = join(homedir(), ".mcp-gateway");
 const DEFAULT_PORT = 7337;
@@ -32,8 +33,6 @@ function resolveHome() {
   return process.env.MCP_GATEWAY_DATA_DIR || DEFAULT_HOME;
 }
 
-const HOME = resolveHome();
-
 /**
  * Descritor do motor `mcp-gateway` lido do manifest.json do registry. Nunca lança: manifest
  * ilegível ou motor ausente do registro → null (quem chama sinaliza, não inventa um default).
@@ -50,7 +49,7 @@ function loadEngineDescriptor() {
 /** Lê a porta configurada pelo usuário (config.json), caindo no default do motor. */
 function configuredPort() {
   try {
-    return JSON.parse(readFileSync(join(HOME, "config.json"), "utf8")).port ?? DEFAULT_PORT;
+    return JSON.parse(readFileSync(join(resolveHome(), "config.json"), "utf8")).port ?? DEFAULT_PORT;
   } catch {
     return DEFAULT_PORT;
   }
@@ -108,13 +107,30 @@ async function healthCheck() {
   }
 }
 
-/** Derruba o daemon antes de sobrescrever os arquivos (Windows trava arquivo em uso). */
-async function onBeforeReplace() {
+/**
+ * Derruba o daemon antes de sobrescrever os arquivos (Windows trava arquivo em uso). Primeiro pede
+ * `POST /admin/drain` com `{reason, waitMs}`: o daemon espera as chamadas em curso (até `waitMs`),
+ * responde e sai com 0. Só se o gateway não drenar (sem a rota, token recusado, sem resposta em
+ * `drainMs` + 15 s ou ainda vivo `drainMs` depois de responder) cai no SIGTERM, que no Windows mata
+ * na hora.
+ */
+export async function onBeforeReplace({ home = resolveHome(), drainMs = 60000, reason = "engine-kit: atualização do mcp-gateway", log = () => {} } = {}) {
+  let rt;
+  try { rt = JSON.parse(readFileSync(join(home, "runtime.json"), "utf8")); } catch { return; }
+  if (!rt?.pid) { return; }
+  const token = readToken({ home, log });
   try {
-    const rt = JSON.parse(readFileSync(join(HOME, "runtime.json"), "utf8"));
-    if (rt?.pid) { process.kill(rt.pid, "SIGTERM"); }
-    await new Promise((r) => setTimeout(r, 1500));
-  } catch { /* já parado / sem runtime */ }
+    const res = await fetch(`http://127.0.0.1:${rt.port}/admin/drain`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify({ reason, waitMs: drainMs }),
+      signal: AbortSignal.timeout(drainMs + 15000),
+    });
+    if (res.ok && await waitExit(rt.pid, drainMs)) { return; }
+    log(`mcp-gateway: drain HTTP ${res.status}, ainda vivo; sinalizando`);
+  } catch (e) { log(`mcp-gateway: drain falhou (${e.message}); sinalizando`); }
+  try { process.kill(rt.pid, "SIGTERM"); } catch { return; }
+  await new Promise((r) => setTimeout(r, 1500));
 }
 
 /**
@@ -169,14 +185,14 @@ export function readInstructions() {
 export async function ensureGateway({ log = () => {}, version, allowNetwork = true, bootTimeoutMs = 45000, registryUrl, fetcher } = {}) {
   const r = await ensureEngine("mcp-gateway", {
     healthCheck,
-    onBeforeReplace,
+    onBeforeReplace: () => onBeforeReplace({ log }),
     log,
     version,
     allowNetwork,
     bootTimeoutMs,
     registryUrl,
     fetcher,
-    env: { MCP_GATEWAY_DATA_DIR: HOME },
+    env: { MCP_GATEWAY_DATA_DIR: resolveHome() },
   });
   if (!r.available) { return r; }
 

package/consumers/neural-link.mjs

@@ -19,7 +19,7 @@ import { pathToFileURL } from "node:url";
 import { ensureEngine } from "../kit/index.mjs";
 
 /** Pin default: última versão do neural-link confirmada publicada no manifest deste kit. */
-const DEFAULT_PIN = "0.7.15";
+const DEFAULT_PIN = "0.7.16";
 
 /**
  * Garante o dispatcher de hooks `neural-link` instalado/atualizado, e roda o `install()` dele

package/kit/budget.mjs

@@ -44,10 +44,19 @@ const ROOT = resolvePath(KIT, "..");
 //   2026-11-09 tooling 31000 → 34000: diagnóstico de vida (pid, porta, idade do runtime) e do ponteiro
 //   `cli.json` no doctor (diagnose.mjs), +2.7 KB. Só leitura, rodado na mão de quem diagnostica; o caminho do
 //   `import "engine-kit"` não mudou.
+//   2026-11-09 tooling 34000 → 37000 (loc 950 → 1050): pin por motor aprovado pelo dono — `engine-kit pin/unpin`
+//   (ensure.mjs, cli.mjs) e o estado FIXADO do doctor, +3.6 KB. No runtime o pin entrou sem subir o teto
+//   (dedup em provision/lifecycle pagou os bytes).
+//   2026-11-11 adapter 5000 → 5500: o adaptador do mcp-gateway passou a pedir `POST /admin/drain` (bearer) antes
+//   de sinalizar o daemon, +0.6 KB. É o contrato de desligamento do motor, que só o adaptador do motor conhece:
+//   no Windows o SIGTERM mata na hora e corta as chamadas em curso. O caminho do `import "engine-kit"` não mudou.
+//   2026-11-11 tooling 37000 → 37500: o `ensure` passou a avisar quando instala a partir do descritor em cache
+//   vencido (registry fora do ar) e quando o ponteiro `cli.json` do motor está quebrado, +0.3 KB (cli.mjs,
+//   ensure.mjs, reusando `pointerOf` do diagnose). O caminho do `import "engine-kit"` não mudou.
 const BUDGETS = {
   runtime: { codeBytes: 27000, baseline: 24519, loc: 900 },
-  tooling: { codeBytes: 34000, baseline: 16420, loc: 950 },
-  adapter: { codeBytes: 5000, baseline: 1859, loc: 150 },
+  tooling: { codeBytes: 37500, baseline: 16420, loc: 1050 },
+  adapter: { codeBytes: 5500, baseline: 1859, loc: 150 },
 };
 
 // `split("\n")` num arquivo terminado em newline devolve um elemento vazio no fim — linha

package/kit/cli.mjs

@@ -4,14 +4,18 @@
 //   npx engine-kit ensure <motor>                    # instala/atualiza verificando sha256 + Ed25519
 //   npx engine-kit ensure <motor> --version <x.y.z>  # pin de versão
 //   npx engine-kit ensure <motor> --registry-url <url>
+//   npx engine-kit pin <motor> [--version <x.y.z>]   # congela UM motor; a atualização automática pula só ele
+//   npx engine-kit unpin <motor>                     # o motor volta a receber atualizações
 //
 // Por padrão o kit se atualiza (roda de novo como a última versão do npm) e atualiza o motor instalado.
 // ENGINE_KIT_NO_AUTO_UPDATE=1 desliga os dois e deixa só o aviso de versão nova (ver update.mjs).
 // Exit code: 0 = motor instalado (ou reusado). 1 = recusou/falhou, com o motivo na saída de erro.
-import { ensureCommand } from "./ensure.mjs";
+import { ensureCommand, pinCommand, unpinCommand } from "./ensure.mjs";
 import { selfUpdate, autoUpdateEnabled } from "./update.mjs";
 
 const USAGE = "uso: engine-kit ensure <motor> [--version <x.y.z>] [--registry-url <url>]\n" +
+  "     engine-kit pin <motor> [--version <x.y.z>]   fixa a versão instalada (ou instala e fixa x.y.z)\n" +
+  "     engine-kit unpin <motor>                     solta o motor para voltar a atualizar\n" +
   "ENGINE_KIT_NO_AUTO_UPDATE=1 desliga a atualização automática do kit e dos motores (fica só o aviso).";
 
 const args = process.argv.slice(2);
@@ -20,8 +24,8 @@ const [cmd, name] = args;
 
 if (cmd === "--help" || cmd === "-h") {
   console.log(USAGE);
-} else if (cmd !== "ensure" || !name || name.startsWith("-")) {
-  console.error(cmd && cmd !== "ensure" ? `comando desconhecido: ${cmd}\n${USAGE}` : USAGE);
+} else if (!["ensure", "pin", "unpin"].includes(cmd) || !name || name.startsWith("-")) {
+  console.error(cmd && !["ensure", "pin", "unpin"].includes(cmd) ? `comando desconhecido: ${cmd}\n${USAGE}` : USAGE);
   process.exitCode = 1;
 } else if (args.includes("--version") && !/^\d+\.\d+\.\d+$/.test(flag("--version") ?? "")) {
   console.error(`--version precisa de x.y.z (recebi: ${flag("--version") ?? "nada"})`);
@@ -31,6 +35,14 @@ if (cmd === "--help" || cmd === "-h") {
   const u = await selfUpdate(args);
   if (u.action === "relaunched") {
     process.exitCode = u.status;
+  } else if (cmd === "unpin") {
+    const r = unpinCommand(name);
+    if (!r.ok) { console.error(`FALHOU ${name}: ${r.reason}`); process.exitCode = 1; }
+    else { console.log(r.was ? `OK ${name} solto (estava fixado em v${r.was}); o próximo ensure traz a versão do registry` : `OK ${name} não estava fixado`); }
+  } else if (cmd === "pin") {
+    const r = await pinCommand(name, { version: flag("--version"), registryUrl: flag("--registry-url"), log: (m) => console.log(m) });
+    if (!r.ok) { console.error(`FALHOU ${name}: ${r.reason}`); process.exitCode = 1; }
+    else { console.log(`OK ${name} fixado em v${r.pinned}; a atualização automática pula este motor (engine-kit unpin ${name} solta)`); }
   } else {
     const autoUpdate = autoUpdateEnabled();
     const r = await ensureCommand(name, { version: flag("--version"), registryUrl: flag("--registry-url"), autoUpdate, log: (m) => console.log(m) });
@@ -38,6 +50,9 @@ if (cmd === "--help" || cmd === "-h") {
       const how = r.reused ? "já instalado, reusado" : r.signed ? "assinatura Ed25519 conferida" : "SEM assinatura no registry";
       if (r.previous) { console.log(`motor atualizado: ${name} v${r.previous} → v${r.version}`); }
       console.log(`OK ${name} v${r.version} (${how}) em ${r.entryPath}`);
+      if (r.staleCache) { console.log(`aviso: registry inacessível; ${name} veio do descritor em cache vencido`); }
+      if (r.pointer && !["OK", "AUSENTE"].includes(r.pointer.state)) { console.log(`aviso: ponteiro cli.json ${r.pointer.state}: ${r.pointer.detail}`); }
+      if (r.pinned) { console.log(`fixado: ${name} fica em v${r.pinned} (engine-kit unpin ${name} volta a atualizar)`); }
       if (r.available) { console.log(`aviso: ${name} v${r.available} disponível; ENGINE_KIT_NO_AUTO_UPDATE ligado — rode sem ele para atualizar`); }
       if (r.kind === "daemon") { console.log("daemon: quem sobe o motor é o consumidor (ensureEngine com healthCheck)."); }
     } else {

package/kit/doctor.mjs

@@ -7,7 +7,7 @@
 //   node kit/doctor.mjs --engine <nome> # um motor só
 //
 // A regra é a mesma do kit e não muda aqui: **desatualizado → atualiza; ausente → baixa;
-// atualizado → REUSA**. Reusar é o caminho comum e precisa ser barato — por isso o diagnóstico
+// atualizado → REUSA**; motor fixado (`engine-kit pin`) fica na versão fixada. Reusar é o caminho comum e precisa ser barato — por isso o diagnóstico
 // não baixa nada, e o `--fix` delega ao `provision` (SHA256 + assinatura fail-closed, lock e swap
 // atômicos). O doctor não reimplementa instalação: ele só decide QUEM precisa.
 //
@@ -15,9 +15,10 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { resolve } from "./resolve.mjs";
-import { provision, satisfiesPin } from "./provision.mjs";
+import { provision, satisfiesPin, installedVersion } from "./provision.mjs";
 import { shutdown } from "./lifecycle.mjs";
 import { lifeOf, pointerOf } from "./diagnose.mjs";
+import { pinOf, readTrust } from "./trust.mjs";
 
 const args = process.argv.slice(2);
 const useLocal = args.includes("--local");
@@ -32,13 +33,7 @@ let manifest;
 try { manifest = JSON.parse(readFileSync(manifestPath, "utf8")); }
 catch (e) { console.error(`FALHOU: manifest local ilegível: ${e.message}`); process.exit(1); }
 
-/** Versão instalada no disco, lida do artefato — a mesma fonte que o provision usa para o pin. */
-function installedVersion(engine) {
-  const binDir = join(engine.homeDir, engine.install.extractTo ?? "bin");
-  try { return JSON.parse(readFileSync(join(binDir, "package.json"), "utf8")).version ?? null; }
-  catch { return null; }
-}
-
+try { readTrust(); } catch (e) { console.error(`FALHOU: ${e.message}`); process.exit(1); }
 const names = (manifest.engines ?? []).map((e) => e.name).filter((n) => !only || n === only);
 if (only && names.length === 0) {
   console.error(`FALHOU: motor "${only}" não existe no manifest`);
@@ -54,13 +49,16 @@ const rows = [];
 for (const name of names) {
   // `refresh`: diagnóstico com cache velho mente — dizer "atualizado" olhando um descritor
   // vencido é pior do que não diagnosticar. Aqui a requisição de rede vale a pena.
-  const r = await resolve(name, { allowNetwork: !useLocal, manifest: useLocal ? manifest : undefined, refresh: !useLocal, registryUrl });
+  const opts = { allowNetwork: !useLocal, manifest: useLocal ? manifest : undefined, refresh: !useLocal, registryUrl };
+  let r = await resolve(name, opts);
+  const latest = r.engine?.version, pin = r.ok && r.engine.status !== "self-managed" && pinOf(name);
+  if (pin && pin !== latest) { r = await resolve(name, { ...opts, version: pin }); }
   if (!r.ok) { rows.push({ name, state: "ERRO", detail: r.reason }); continue; }
 
   const engine = r.engine;
   const entry = join(engine.homeDir, engine.install.entry);
   const present = existsSync(entry);
-  const inst = present ? installedVersion(engine) : null;
+  const inst = present ? installedVersion(join(engine.homeDir, engine.install.extractTo ?? "bin")) : null;
 
   let state, detail;
   if (engine.status === "self-managed") {
@@ -68,23 +66,27 @@ for (const name of names) {
     // pelo caminho do manifest daria "ausente" para um motor que está instalado e funcionando,
     // só que em outro lugar. Reportar e não agir é a resposta honesta.
     state = "SELF-MANAGED"; detail = `v${engine.version} no registry — atualiza pelo próprio updater`;
+  } else if (pin && inst === pin) {
+    state = "FIXADO"; detail = `v${pin} fixado (registry v${latest}) → engine-kit unpin ${name} volta a atualizar`;
   } else if (!present) {
     state = "AUSENTE"; detail = `baixar v${engine.version}`;
   } else if (!inst) {
     // Estado desconhecido: o artefato está lá mas a versão não é legível. Não invente que está ok.
     state = "ILEGÍVEL"; detail = "instalado, mas package.json ausente/corrompido → reprovisionar";
+  } else if (pin) {
+    state = "FORA DO PIN"; detail = `v${inst} → v${pin} fixada`;
   } else if (satisfiesPin(inst, engine.version)) {
     state = "OK"; detail = `v${inst} satisfaz o pin v${engine.version} → reusar`;
   } else {
     state = "DESATUALIZADO"; detail = `v${inst} → v${engine.version}`;
   }
-  rows.push({ name, state, detail, engine, needsWork: state !== "OK" && state !== "SELF-MANAGED" });
+  rows.push({ name, state, detail, engine, pin, needsWork: !["OK", "SELF-MANAGED", "FIXADO"].includes(state) });
 }
 
 const pad = (s, n) => String(s).padEnd(n);
 const w = Math.max(12, ...rows.map((r) => r.name.length));
 for (const r of rows) {
-  const mark = (r.state === "OK" || r.state === "SELF-MANAGED") ? "  OK  " : r.state === "ERRO" ? " ERRO " : "  !!  ";
+  const mark = ["OK", "SELF-MANAGED", "FIXADO"].includes(r.state) ? "  OK  " : r.state === "ERRO" ? " ERRO " : "  !!  ";
   console.log(`${mark} ${pad(r.name, w)}  ${pad(r.state, 14)} ${r.detail}`);
   if (r.engine && r.engine.status !== "self-managed") {
     const life = lifeOf(r.engine), ptr = pointerOf(r.engine);
@@ -106,6 +108,7 @@ let failures = 0;
 for (const r of pending) {
   console.log(`\n${r.name}: ${r.detail}`);
   const p = await provision(r.engine, {
+    exact: Boolean(r.pin),
     log: (m) => console.log(`    ${m}`),
     // No Windows um arquivo EM USO não pode ser sobrescrito: sem derrubar o daemon antes, o
     // update de um motor vivo falha com EPERM no meio do swap. O kit não adivinha como parar

package/kit/ensure.mjs

@@ -14,8 +14,11 @@ import { join } from "node:path";
 import { resolve } from "./resolve.mjs";
 import { provision, installedVersion, satisfiesPin } from "./provision.mjs";
 import { shutdown } from "./lifecycle.mjs";
+import { pinOf, readTrust, saveTrust } from "./trust.mjs";
+import { pointerOf } from "./diagnose.mjs";
 
 const BUNDLED_MANIFEST = new URL("../manifest.json", import.meta.url);
+const installedOf = (e) => existsSync(join(e.homeDir, e.install.entry)) ? installedVersion(join(e.homeDir, e.install.extractTo ?? "bin")) : null;
 
 /** Manifest que viaja dentro do pacote (lança se ilegível; `ensureCommand` transforma em reason). */
 export function bundledManifest() {
@@ -32,8 +35,10 @@ export function bundledManifest() {
  * @param {Function=} opts.fetcher download injetável (testes).
  * @param {boolean=} opts.autoUpdate false = motor já instalado fica na versão dele e o retorno avisa a nova
  *        (`available`). Default true. Um `version` explícito sempre vale: foi pedido.
+ *        Motor fixado (`engine-kit pin`) fica sempre na versão fixada; `version` diferente dela é recusado.
  * @returns {Promise<{ok:true, entryPath:string, version:string, kind:string, reused?:boolean, signed?:boolean,
- *          previous?:string, available?:string} | {ok:false, reason:string}>} `previous` = versão substituída.
+ *          previous?:string, available?:string, pinned?:string} | {ok:false, reason:string}>} `previous` = versão
+ *          substituída; `pinned` = versão em que o motor está fixado.
  */
 export async function ensureCommand(name, { version, registryUrl, bundled, manifest, fetcher, autoUpdate = true, log = () => {} } = {}) {
   let local;
@@ -49,21 +54,26 @@ export async function ensureCommand(name, { version, registryUrl, bundled, manif
     return { ok: false, reason: `${name}: o manifest embarcado não traz publicKey → sem chave do primeiro contato não instalo (ABORT)` };
   }
 
+  let pin;
+  try { pin = pinOf(name); } catch (e) { return { ok: false, reason: e.message }; }
+  if (pin && version && version !== pin) {
+    return { ok: false, reason: `${name} está fixado em v${pin} → engine-kit pin ${name} --version ${version} troca a versão fixada; engine-kit unpin ${name} solta` };
+  }
   // refresh: instalar quer a verdade do registry, não um descritor de cache.
-  const r = await resolve(name, { version, registryUrl, refresh: true, ...(manifest ? { manifest } : {}) });
+  const r = await resolve(name, { version: version ?? pin, registryUrl, refresh: true, ...(manifest ? { manifest } : {}) });
   if (!r.ok) { return { ok: false, reason: r.reason }; }
 
   const engine = r.engine;
-  const entryPath = join(engine.homeDir, engine.install.entry);
-  const previous = existsSync(entryPath) ? installedVersion(join(engine.homeDir, engine.install.extractTo ?? "bin")) : null;
-  if (!autoUpdate && !version && previous && !satisfiesPin(previous, engine.version)) {
-    return { ok: true, entryPath, version: previous, kind: engine.kind, reused: true, available: engine.version };
+  const previous = installedOf(engine);
+  if (!autoUpdate && !version && !pin && previous && !satisfiesPin(previous, engine.version)) {
+    return { ok: true, entryPath: join(engine.homeDir, engine.install.entry), version: previous, kind: engine.kind, reused: true, available: engine.version };
   }
 
   const p = await provision(r.engine, {
     log,
     trustedKeys: { [name]: publicKey },
     allowDowngrade: Boolean(version),
+    exact: Boolean(pin),
     ...(fetcher ? { fetcher } : {}),
     // Windows: arquivo em uso não se sobrescreve. Derruba o daemon pelo shutdownPath que o registry declara.
     onBeforeReplace: async () => {
@@ -79,5 +89,57 @@ export async function ensureCommand(name, { version, registryUrl, bundled, manif
   return {
     ok: true, entryPath: p.entryPath, version: p.version, kind: engine.kind, reused: p.reused === true, signed: p.signed,
     ...(p.installed && previous && previous !== p.version ? { previous } : {}),
+    ...(pin ? { pinned: pin } : {}),
+    ...(engine.staleCache ? { staleCache: true } : {}),
+    ...(engine.kind === "cli" ? { pointer: pointerOf(engine) } : {}),
   };
 }
+
+/** Fixa (`version`) ou solta (null) um motor em trust.json; os outros motores não mudam. `was` = pin anterior. */
+function setPin(name, version) {
+  try {
+    const store = readTrust(), entry = { ...store[name] }, was = entry.pin ?? null;
+    if (!version && !was) { return { ok: true, was }; }
+    if (version) { entry.pin = version; } else { delete entry.pin; }
+    saveTrust({ ...store, [name]: entry });
+    return { ok: true, was };
+  } catch (e) {
+    return { ok: false, reason: e.message };
+  }
+}
+
+/**
+ * `engine-kit pin <motor> [--version x.y.z]`: congela UM motor. Sem `version`, fixa a versão instalada; com ela,
+ * instala essa versão (sha256 + Ed25519, downgrade permitido) e fixa. A autoatualização pula só este motor.
+ * Nunca lança. Opções de teste iguais às de `ensureCommand`.
+ * @returns {Promise<{ok:true, version:string, pinned:string} | {ok:false, reason:string}>}
+ */
+export async function pinCommand(name, { version, ...opts } = {}) {
+  if (version) {
+    const s = setPin(name, version), before = s.was;
+    if (!s.ok) { return s; }
+    const e = await ensureCommand(name, opts);
+    if (!e.ok) {
+      const back = setPin(name, before);
+      return { ok: false, reason: `${e.reason} → pin não aplicado${back.ok ? (before ? ` (pin anterior v${before} restaurado)` : "") : `; ${back.reason}`}` };
+    }
+    return e;
+  }
+  const r = await resolve(name, { registryUrl: opts.registryUrl, ...(opts.manifest ? { manifest: opts.manifest } : {}) });
+  if (!r.ok) { return { ok: false, reason: r.reason }; }
+  if (r.engine.status === "self-managed") {
+    return { ok: false, reason: `${name} é self-managed: atualiza pelo próprio updater, o engine-kit não fixa a versão dele` };
+  }
+  const inst = installedOf(r.engine);
+  if (!inst) {
+    return { ok: false, reason: `${name} não está instalado (ou a versão é ilegível) → engine-kit pin ${name} --version <x.y.z> instala e fixa` };
+  }
+  const s = setPin(name, inst);
+  return s.ok ? { ok: true, version: inst, pinned: inst } : s;
+}
+
+/** `engine-kit unpin <motor>`: o motor volta a receber atualizações. Nunca lança. */
+export function unpinCommand(name) {
+  const s = setPin(name, null);
+  return s.ok ? { ok: true, was: s.was } : s;
+}

package/kit/index.mjs

@@ -20,15 +20,17 @@ export {
 export { SIGNING_DIR, keyPathFor } from "./keystore.mjs";
 
 import { resolve } from "./resolve.mjs";
-import { provision } from "./provision.mjs";
+import { provision, satisfiesPin } from "./provision.mjs";
 import { lifecycle } from "./lifecycle.mjs";
+import { pinOf } from "./trust.mjs";
 
 /**
  * RESOLVE → PROVISION → LIFECYCLE numa chamada: o caminho que 99% dos consumidores querem.
  * @param {string} name nome do motor no registry.
  * @param {object} opts
  * @param {(runtime:object)=>Promise<object|null>} opts.healthCheck validação de saúde/protocolo (obrigatória).
- * @param {string=} opts.version pin de versão (default: a do registry).
+ * @param {string=} opts.version versão mínima pedida pelo consumidor (default: a do registry). Motor fixado
+ *        pelo dono (`engine-kit pin`) fica na versão fixada; se ela não serve o mínimo, `available:false`.
  * @param {boolean=} opts.allowNetwork permite baixar/atualizar (default true).
  * @param {Record<string,string>=} opts.trustedKeys chaves públicas FIXADAS pelo consumidor
  *        (`{ "<motor>": "<hex>" }`). Divergência com o registry = ABORT. Sem isso vale TOFU:
@@ -41,10 +43,15 @@ import { lifecycle } from "./lifecycle.mjs";
 export async function ensureEngine(name, opts = {}) {
   const { healthCheck, version, allowNetwork = true, registryUrl, log = () => {}, bootTimeoutMs, onBeforeReplace, env, trustedKeys, refresh = false, fetcher } = opts;
 
-  const r = await resolve(name, { version, allowNetwork, registryUrl, refresh });
+  let pin;
+  try { pin = pinOf(name); } catch (e) { return { available: false, reason: e.message }; }
+  if (pin && version && !satisfiesPin(pin, version)) {
+    return { available: false, reason: `${name} fixado em v${pin}; o consumidor pede v${version} → engine-kit unpin ${name}` };
+  }
+  const r = await resolve(name, { version: pin ?? version, allowNetwork, registryUrl, refresh });
   if (!r.ok) { return { available: false, reason: r.reason }; }
 
-  const p = await provision(r.engine, { log, allowNetwork, onBeforeReplace, trustedKeys, ...(fetcher ? { fetcher } : {}) });
+  const p = await provision(r.engine, { log, allowNetwork, onBeforeReplace, trustedKeys, exact: Boolean(pin), ...(fetcher ? { fetcher } : {}) });
   if (!p.ok) { return { available: false, reason: p.reason }; }
 
   const l = await lifecycle(r.engine, p.entryPath, { healthCheck, log, bootTimeoutMs, env });

package/kit/lifecycle.mjs

@@ -24,24 +24,19 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  */
 const DEFAULT_STALE_MS = 120000;
 
+const runtimeFile = (engine) => join(engine.homeDir, engine.runtime?.runtimeFile ?? "runtime.json");
+
 /** Lê o runtime.json do motor, sem julgar idade. `null` se ausente/ilegível. */
 export function readRuntime(engine) {
-  try {
-    const rt = join(engine.homeDir, engine.runtime?.runtimeFile ?? "runtime.json");
-    return JSON.parse(readFileSync(rt, "utf8"));
-  } catch {
-    return null;
-  }
+  try { return JSON.parse(readFileSync(runtimeFile(engine), "utf8")); } catch { return null; }
 }
 
 /** Lê o runtime.json do motor SE estiver fresco (heartbeat vivo). null se ausente/obsoleto. */
 export function readFreshRuntime(engine, { staleMs } = {}) {
-  const rt = join(engine.homeDir, engine.runtime?.runtimeFile ?? "runtime.json");
   const hb = engine.runtime?.heartbeatMs;
   const limit = staleMs ?? (hb ? hb * 3 : DEFAULT_STALE_MS);
   try {
-    if (Date.now() - statSync(rt).mtimeMs > limit) { return null; }
-    return JSON.parse(readFileSync(rt, "utf8"));
+    return Date.now() - statSync(runtimeFile(engine)).mtimeMs > limit ? null : readRuntime(engine);
   } catch {
     return null;
   }
@@ -66,7 +61,7 @@ async function findAlive(engine, healthCheck) {
 }
 
 /** Espera o processo sair (até `ms`). true = saiu. */
-async function waitExit(pid, ms) {
+export async function waitExit(pid, ms) {
   for (const fim = Date.now() + ms; Date.now() < fim; await sleep(500)) {
     try { process.kill(pid, 0); } catch { return true; }
   }

package/kit/provision.mjs

@@ -50,7 +50,7 @@ function extractTgz(tgz, dest) {
   try {
     execFileSync(tar, ["--version"], { stdio: "ignore", windowsHide: true });
   } catch {
-    return { ok: false, reason: "`tar` não encontrado no PATH — necessário para extrair o artefato (Windows 10 1803+, macOS e Linux já trazem). Instale-o e tente de novo." };
+    return { ok: false, reason: "`tar` não encontrado no PATH: instale-o para extrair o artefato." };
   }
   try {
     execFileSync(tar, ["-xzf", tgz, "-C", dest], { stdio: "ignore", windowsHide: true });
@@ -215,7 +215,7 @@ export async function fetchArtifact(engine, { log = () => {}, destDir, downloadT
  * adivinha como derrubar um daemon: quem sabe é o descritor/consumidor).
  * @returns {Promise<{ok:true, entryPath:string, version:string, reused?:boolean, installed?:boolean} | {ok:false, reason:string}>}
  */
-export async function provision(engine, { log = () => {}, allowNetwork = true, onBeforeReplace, downloadTimeoutMs = 120000, fetcher = fetchBuf, trustedKeys, allowDowngrade } = {}) {
+export async function provision(engine, { log = () => {}, allowNetwork = true, onBeforeReplace, downloadTimeoutMs = 120000, fetcher = fetchBuf, trustedKeys, allowDowngrade, exact } = {}) {
   const home = engine.homeDir;
   const binDir = join(home, engine.install.extractTo ?? "bin");
   const entryPath = join(home, engine.install.entry);
@@ -228,14 +228,14 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
   // numa instalação quebrada para sempre, ignorando o pin do registry.
   if (existsSync(entryPath)) {
     const inst = installedVersion(binDir);
-    if (inst && satisfiesPin(inst, engine.version)) {
+    if (inst && (exact ? inst === engine.version : satisfiesPin(inst, engine.version))) {
       noteVersion(engine.name, inst);
       return { ok: true, entryPath, version: inst, reused: true };
     }
     if (!inst && engine.status !== "self-managed") {
       log(`[engine-kit] ${engine.name}: instalação em estado desconhecido (versão ilegível) → reprovisionando`);
       if (!allowNetwork) {
-        return { ok: false, reason: `${engine.name}: instalação em estado desconhecido (package.json ausente/corrompido em ${binDir}) e rede desabilitada — não dá para validar nem reparar` };
+        return { ok: false, reason: `${engine.name}: instalação em estado desconhecido (package.json ausente/corrompido em ${binDir}) e rede desabilitada: sem como reparar` };
       }
     } else if (inst) {
       log(`[engine-kit] ${engine.name}: instalada v${inst} não satisfaz o pin v${engine.version} → atualizando`);
@@ -249,7 +249,7 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
   // Tentar provisionar aqui daria erro obscuro (o artefato é um instalador, não um tarball de
   // `extractTo`); melhor recusar dizendo QUEM instala.
   if (engine.status === "self-managed") {
-    return { ok: false, reason: `${engine.name} é self-managed: instala e atualiza pelo próprio updater, não pelo engine-kit (o registry guarda o descritor da release)` };
+    return { ok: false, reason: `${engine.name} é self-managed: instala e atualiza pelo próprio updater, não pelo engine-kit` };
   }
 
   if (!allowNetwork) { return { ok: false, reason: `${engine.name} ausente/desatualizado e rede desabilitada` }; }
@@ -257,7 +257,7 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
     return { ok: false, reason: `${engine.name} ainda não publicou release (status: pending-release)` };
   }
 
-  const rb = !allowDowngrade && rollbackReason(engine.name, engine.version);
+  const rb = !allowDowngrade && !exact && rollbackReason(engine.name, engine.version);
   if (rb) { return { ok: false, reason: rb }; }
 
   mkdirSync(home, { recursive: true });
@@ -270,7 +270,7 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
       if (existsSync(entryPath)) {
         const inst = installedVersion(binDir);
         // Se o vencedor terminou mas a versão continua ilegível, não invente: sinalize.
-        if (inst) { return { ok: true, entryPath, version: inst, reused: true }; }
+        if (inst && (!exact || inst === engine.version)) { return { ok: true, entryPath, version: inst, reused: true }; }
       }
       await sleep(1000);
     }
@@ -278,22 +278,10 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
   }
 
   try {
-    // 1-3) Sidecar SHA256 obrigatório, download e integridade: nada toca o disco antes de conferir.
-    const dl = await downloadChecked(engine, { log, fetcher, timeoutMs: downloadTimeoutMs });
-    if (!dl.buf) { return { ok: false, reason: dl.reason }; }
-    const buf = dl.buf;
-    const part = join(home, `${engine.assetName}.part`);
-    const tgz = join(home, engine.assetName);
-    writeFileSync(part, buf);
-    renameSync(part, tgz);
-
-    // 3.5) AUTENTICIDADE — antes de extrair. Um artefato não confiável não chega a tocar o disco
-    //      final: se a assinatura não confere, o .tgz é apagado e nada é instalado.
-    const auth = await verifyAuthenticity(engine, buf, { log, fetcher, trustedKeys });
-    if (!auth.ok) {
-      dropFile(tgz);
-      return { ok: false, reason: auth.reason };
-    }
+    // 1-3.5) Sidecar SHA256 obrigatório, integridade e AUTENTICIDADE antes de qualquer byte tocar o disco.
+    const auth = await fetchArtifact(engine, { log, destDir: home, downloadTimeoutMs, fetcher, trustedKeys });
+    if (!auth.ok) { return auth; }
+    const tgz = auth.path;
 
     // 4) Extrai em staging e faz o swap (com shutdown-first se já existe).
     const staging = join(home, `stage-${engine.version}`);

package/kit/publish-base.ps1

@@ -56,6 +56,14 @@ function Step($m) { Write-Host "==> $m" -ForegroundColor Cyan }
 function Warn($m) { Write-Host "AVISO: $m" -ForegroundColor Yellow }
 function Fail($m) { Write-Host "FALHOU: $m" -ForegroundColor Red; exit 1 }
 
+# Windows PowerShell 5.1 com ErrorActionPreference=Stop transforma o stderr de um exe nativo em
+# NativeCommandError mesmo com 2>$null; o chamador decide pelo $LASTEXITCODE.
+function Invoke-GhQuiet {
+    $previous = $ErrorActionPreference
+    $ErrorActionPreference = "Continue"
+    try { & gh @args 2>$null } finally { $ErrorActionPreference = $previous }
+}
+
 if ($Version -notmatch '^\d+\.\d+\.\d+$') { Fail "versao '$Version' invalida (esperado x.y.z)" }
 if ($Engine -notmatch '^[a-z0-9][a-z0-9-]*$') { Fail "motor '$Engine' invalido (minusculas, hifens)" }
 
@@ -67,7 +75,7 @@ $env:GITHUB_TOKEN = ''
 $env:GIT_CONFIG_PARAMETERS = ''
 
 Step "Conferindo identidade do gh"
-$who = (gh api user --jq '.login' 2>$null)
+$who = (Invoke-GhQuiet api user --jq '.login')
 if ($LASTEXITCODE -ne 0 -or -not $who) { Fail "gh nao autenticado - rode 'gh auth login' com a conta dona dos repos" }
 $owner = $Registry.Split('/')[0]
 if ($who.Trim() -ne $owner) { Fail "gh autenticado como '$($who.Trim())' mas o registry e de '$owner' (token da conta errada)" }
@@ -112,7 +120,7 @@ if ($DryRun) {
     $upload | ForEach-Object { Write-Host "      $([IO.Path]::GetFileName($_))" }
     if ($SourceRepo) { Write-Host "      + espelho no repo privado $SourceRepo (nao-fatal)" }
     if ($MarketplaceMirror) { Write-Host "      + ponte no canal antigo $MarketplaceMirror (nao-fatal)" }
-    Write-Host "    e atualizaria $manifest (publicKey=$pubKey, signatureRequired=true, repo=$Registry)"
+    Write-Host "    e levaria manifest e README a main de $Registry (publicKey=$pubKey, signatureRequired=true), mesclando na develop"
     exit 0
 }
 
@@ -121,7 +129,7 @@ Step "Publicando a release no registry ($Registry, tag $tag)"
 if (-not $Notes) {
     $Notes = "$Engine $Version. Artefato assinado com Ed25519 (ed25519-sha256-raw): o engine-kit e fail-closed e recusa artefato sem assinatura valida."
 }
-gh release view $tag --repo $Registry 2>$null | Out-Null
+Invoke-GhQuiet release view $tag --repo $Registry | Out-Null
 if ($LASTEXITCODE -eq 0) { Fail "a release '$tag' ja existe em $Registry - suba a versao ou apague a release antes (nao sobrescreva um artefato ja assinado)" }
 
 gh release create $tag --repo $Registry --title "$Engine $Version" --notes $Notes @upload
@@ -146,18 +154,19 @@ if ($MarketplaceMirror) {
     }
 }
 
-# --- 5. Manifest: parseado, nao editado com regex -----------------------------------------
-if (-not $SkipManifest) {
-    Step "Atualizando o manifest do registry"
-    node (Join-Path $kit "update-manifest.mjs") $Engine --version $Version --public-key $pubKey --repo $Registry --manifest $manifest
-    if ($LASTEXITCODE -ne 0) { Fail "update-manifest (a release esta publicada; corrija o manifest e commite)" }
+# --- 5. Manifest e README na main, provados antes do push --------------------------------
+# Worktree temporario a partir de origin/main: update-manifest (parseado, nao regex), linha do README, verify-release
+# (baixa do release como um consumidor e confere sha256 + assinatura), commit e push na main, mescla na develop.
+# A copia de trabalho local nao e tocada.
+if ($SkipManifest) {
+    Step "Provando o caminho REAL (baixa do release publicado e confere sha256 + assinatura)"
+    node (Join-Path $kit "verify-release.mjs") $Engine --manifest $manifest
+    if ($LASTEXITCODE -ne 0) { Fail "a release publicada NAO passa pelo caminho do consumidor - conserte antes de anunciar" }
+} else {
+    Step "Levando manifest e README a main (prova a release antes do push) e mesclando na develop"
+    node (Join-Path $RegistryPath "tools\publish-manifest.mjs") $Engine --version $Version --public-key $pubKey --repo $Registry
+    if ($LASTEXITCODE -ne 0) { Fail "publish-manifest (a release esta publicada; se a prova falhou nada foi enviado - veja o erro acima)" }
 }
 
-# --- 6. A prova: baixar do release como um consumidor faria -------------------------------
-Step "Provando o caminho REAL (baixa do release publicado e confere sha256 + assinatura)"
-node (Join-Path $kit "verify-release.mjs") $Engine --manifest $manifest
-if ($LASTEXITCODE -ne 0) { Fail "a release publicada NAO passa pelo caminho do consumidor - conserte antes de anunciar" }
-
 Write-Host ""
 Write-Host "OK: $Engine v$Version publicado e VERIFICADO em $Registry." -ForegroundColor Green
-Write-Host "Falta: commitar e enviar o manifest.json ($manifest) para o registry publico."

package/kit/resolve.mjs

@@ -77,7 +77,8 @@ export async function resolve(name, { registryUrl = DEFAULT_REGISTRY_URL, allowN
       if (!cached) { return { ok: false, reason: `registry inacessível (${e.message}) e sem cache` }; }
       manifest = cached.manifest;
       offline = true;
-      degraded = cached.stale; // AQUI é a degradação real: rede falhou e o cache está vencido
+      // AQUI é a degradação real: rede falhou e o cache está vencido
+      degraded = cached.stale;
     }
   } else if (cached) {
     manifest = cached.manifest;

package/kit/trust.mjs

@@ -26,18 +26,26 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 const trustDir = () => process.env.ENGINE_KIT_HOME || join(homedir(), ".engine-kit");
 const trustFile = () => join(trustDir(), "trust.json");
 
-function readTrust() {
-  try {
-    const v = JSON.parse(readFileSync(trustFile(), "utf8"));
-    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
-  } catch {
-    return {};
-  }
+/**
+ * Lê a raiz de confiança; ausente é `{}`. Existente e ilegível LANÇA: devolver `{}` faria a próxima gravação apagar
+ * a chave do primeiro contato, a maior versão vista e o pin dos outros motores.
+ */
+export function readTrust() {
+  const f = trustFile();
+  if (!existsSync(f)) return {};
+  try { const v = JSON.parse(readFileSync(f, "utf8")); if (v && typeof v == "object" && !Array.isArray(v)) return v; } catch {}
+  throw Error(`${f} ilegível: nada foi gravado; corrija-o ou apague-o de propósito (perde chaves e pins)`);
 }
 
+/** Grava a raiz de confiança inteira; lança se não conseguir. */
+export const saveTrust = (store) => {
+  mkdirSync(trustDir(), { recursive: true });
+  writeFileSync(trustFile(), JSON.stringify(store, null, 2));
+};
+
 /**
  * Confronta a chave que veio do registry com a raiz de confiança local.
- * @returns {{ok:true, tofu:boolean} | {ok:false, reason:string}} nunca lança.
+ * @returns {{ok:true, tofu:boolean} | {ok:false, reason:string}} lança só com trust.json ilegível (`readTrust`).
  */
 export function checkTrust(engineName, publicKey, { trustedKeys } = {}) {
   const pinned = trustedKeys?.[engineName];
@@ -59,9 +67,7 @@ export function checkTrust(engineName, publicKey, { trustedKeys } = {}) {
   if (known) return { ok: true, tofu: false };
 
   try {
-    mkdirSync(trustDir(), { recursive: true });
-    store[engineName] = { publicKey, firstSeen: new Date().toISOString(), source: pinned ? "pinned" : "tofu" };
-    writeFileSync(trustFile(), JSON.stringify(store, null, 2));
+    saveTrust({ ...store, [engineName]: { publicKey, firstSeen: new Date().toISOString(), source: pinned ? "pinned" : "tofu" } });
   } catch {
     // Não poder gravar a raiz não pode impedir a instalação — mas também não vira silêncio:
     // sem gravar, a próxima execução repete o TOFU (e o consumidor vê `tofu:true` de novo).
@@ -69,7 +75,7 @@ export function checkTrust(engineName, publicKey, { trustedKeys } = {}) {
   return { ok: true, tofu: true };
 }
 
-export const trustPath = () => trustFile();
+export const trustPath = trustFile;
 
 /** Compara versões `x.y.z` numericamente: negativo, zero ou positivo. */
 export const cmpVer = (a, b) => String(a).localeCompare(String(b), "en", { numeric: true });
@@ -80,12 +86,14 @@ export function rollbackReason(name, version) {
   return max && cmpVer(version, max) < 0 && `${name}: v${version} < v${max} já instalada → ABORT (rollback; downgrade só com --version)`;
 }
 
+/** Versão em que o dono fixou o motor nesta máquina (`engine-kit pin`), ou undefined. */
+export const pinOf = (name) => readTrust()[name]?.pin;
+
 /** Grava `version` como a maior vista do motor, se superar a registrada. */
 export function noteVersion(name, version) {
   const store = readTrust(), max = store[name]?.maxVersion;
   if (max && cmpVer(version, max) <= 0) return;
   try {
-    mkdirSync(trustDir(), { recursive: true });
-    writeFileSync(trustFile(), JSON.stringify({ ...store, [name]: { ...store[name], maxVersion: version } }, null, 2));
+    saveTrust({ ...store, [name]: { ...store[name], maxVersion: version } });
   } catch { /* sem gravar, a proteção vale a partir da próxima instalação */ }
 }

package/manifest.json

@@ -10,7 +10,7 @@
   "apps": [
     {
       "name": "agent-launcher",
-      "version": "1.3.5",
+      "version": "1.3.6",
       "summary": "Abre Claude Code, Codex, Copilot CLI, VS Code e o Copilot app nos seus projetos por qualquer host de modelos. Leva só o launcher; cada ferramenta se instala pelo cartão dela. Windows.",
       "homepage": "https://allansantos-dv.github.io/agent-launcher/",
       "license": "MIT",
@@ -32,6 +32,31 @@
         "signatureAlgorithm": "ed25519-sha256-raw",
         "signatureRequired": true
       }
+    },
+    {
+      "name": "smart-design",
+      "version": "0.2.2",
+      "summary": "Serviço local que o agente de código chama por MCP para desenhar telas com sistema de design, renderizá-las e conferi-las em pixels antes de entregar. Windows.",
+      "homepage": "https://allansantos-dv.github.io/smart-design/",
+      "license": "MIT",
+      "platforms": [
+        "win32-x64"
+      ],
+      "release": {
+        "repo": "AllanSantos-DV/engine-registry",
+        "tag": "smart-design-v{version}",
+        "assets": [
+          {
+            "name": "smart_design-{version}-py3-none-any.whl",
+            "platform": "win32-x64",
+            "checksum": "{asset}.sha256",
+            "signature": "{asset}.sig"
+          }
+        ],
+        "publicKey": "03b4f450fe0ef68d249a6d3503e7577ae45f9dcd89c6301fb4232f0195ef3457",
+        "signatureAlgorithm": "ed25519-sha256-raw",
+        "signatureRequired": true
+      }
     }
   ],
   "engines": [
@@ -71,7 +96,7 @@
     },
     {
       "name": "vox-engine",
-      "version": "0.28.7",
+      "version": "0.33.1",
       "kind": "daemon",
       "status": "self-managed",
       "summary": "Motor de voz (STT/TTS) compartilhado: transcreve e sintetiza para N consumidores a partir de uma única instância, com auto-unload quando ocioso.",
@@ -106,7 +131,7 @@
     },
     {
       "name": "mcp-gateway",
-      "version": "0.17.2",
+      "version": "0.17.5",
       "kind": "daemon",
       "summary": "Agregador MCP: conecta UMA vez em cada servidor MCP e reexpõe todas as tools num endpoint Streamable HTTP único, com auth bearer, namespacing condicional, resiliência e auditoria. Mata a multiplicação de processos por sessão.",
       "pagesPendente": "sem página de produto com vídeo; ela nasce do repositório do próprio motor e este registro só aponta para ela",
@@ -139,7 +164,7 @@
     },
     {
       "name": "neural-link",
-      "version": "0.7.15",
+      "version": "0.7.16",
       "kind": "cli",
       "summary": "Dispatcher adaptativo de hooks para agentes LLM: recebe o evento por stdin, pontua e executa os handlers registrados, e devolve UMA decisão composta. Não é daemon — é invocado a cada evento de hook, por qualquer host (Copilot CLI, VS Code, Claude Code).",
       "pagesPendente": "sem página de produto com vídeo; ela nasce do repositório do próprio motor e este registro só aponta para ela",
@@ -163,7 +188,7 @@
     },
     {
       "name": "vxk",
-      "version": "0.21.0",
+      "version": "0.23.0",
       "kind": "cli",
       "summary": "VXK — explicações visuais animadas e narradas como servidor MCP (stdio): qualquer cliente MCP (Claude Code, Codex, Copilot) compõe a biblioteca de componentes, ícones e o controle único de reprodução e recebe UM HTML autocontido e offline, ou o vídeo MP4 da mesma explicação (por preset, do aplicativo real ou em Motion) e o PDF. A narração é assada pelo motor vox-engine.",
       "pagesUrl": "https://allansantos-dv.github.io/visual-explainer/",
@@ -223,7 +248,7 @@
     },
     {
       "name": "skill-engine",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "kind": "cli",
       "summary": "Skill Manager v2: motor portátil que gerencia skills de agentes fora de qualquer IDE — busca repositórios de skills em quarentena, varre com regras determinísticas e só ativa o que sai limpo, nas pastas que Claude Code, Codex, Copilot e OpenCode leem. CLI `skill-engine`, não é daemon.",
       "pagesPendente": "sem página de produto com vídeo; ela nasce do repositório do próprio motor e este registro só aponta para ela (a sessão do skill-manager a constrói)",
@@ -247,7 +272,7 @@
     },
     {
       "name": "client-harness",
-      "version": "0.1.5",
+      "version": "0.1.8",
       "kind": "cli",
       "summary": "Daemon local que faz o Claude Code e o Codex respeitarem os padrões de cada cliente: confere cada ação do agente (hooks) contra as regras do cliente da pasta e recusa antes de gravar, em cerca de 1 ms, com o motivo e o que usar no lugar.",
       "pagesUrl": "https://allansantos-dv.github.io/harness-padroes-cliente/",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-kit",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Cliente das dependências compartilhadas (motores) do engine-registry: resolve, provisiona com SHA256 e assinatura Ed25519 fail-closed, e mantém o motor vivo — uma instalação por máquina, N consumidores.",
   "type": "module",
   "bin": {
@@ -24,10 +24,12 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node kit/budget.mjs && node tests/test-silencio.mjs && node tests/smoke.mjs && node tests/test-edge.mjs && node tests/test-signature.mjs && node tests/test-ensure.mjs && node tests/test-ensure-daemon.mjs && node tests/test-update.mjs && node tests/test-trust.mjs && node tests/test-rollback.mjs && node tests/test-diagnose.mjs && node tests/test-tar.mjs && node tests/test-apps.mjs && node tests/test-resolve-cache.mjs && node tests/test-doctor-exit.mjs && node tests/test-mcp-gateway-token.mjs && node tests/test-gateway-provision.mjs && node tests/test-neural-link-alignment.mjs && node tests/test-site.mjs && node tests/test-pages-branch.mjs && node tests/test-readme-versions.mjs && node tests/test-pages-gate.mjs && node tests/test-regras-escopo.mjs",
+    "test": "node kit/budget.mjs && node tests/test-silencio.mjs && node tests/smoke.mjs && node tests/test-edge.mjs && node tests/test-signature.mjs && node tests/test-ensure.mjs && node tests/test-ensure-daemon.mjs && node tests/test-ensure-avisos.mjs && node tests/test-update.mjs && node tests/test-trust.mjs && node tests/test-backup-keys.mjs && node tests/test-rollback.mjs && node tests/test-pin.mjs && node tests/test-diagnose.mjs && node tests/test-tar.mjs && node tests/test-apps.mjs && node tests/test-resolve-cache.mjs && node tests/test-doctor-exit.mjs && node tests/test-mcp-gateway-token.mjs && node tests/test-gateway-provision.mjs && node tests/test-gateway-drain.mjs && node tests/test-neural-link-alignment.mjs && node tests/test-site.mjs && node tests/test-pages-branch.mjs && node tests/test-publish-manifest.mjs && node tests/test-publish-base-ps.mjs && node tests/test-readme-versions.mjs && node tests/test-manifest-versions.mjs && node tests/test-pages-gate.mjs && node tests/test-regras-escopo.mjs && node tests/test-actions-minutes.mjs",
     "test:pages-live": "node tests/test-pages-gate.mjs --live",
+    "test:versions-live": "node tests/test-manifest-versions.mjs --live",
     "test:network": "node tests/smoke.mjs --network && node tests/test-signature.mjs --network",
     "test:e2e": "node tests/e2e-install.mjs",
+    "test:gateway-live": "node tests/e2e-gateway-drain-live.mjs",
     "gen-key": "node kit/gen-key.mjs",
     "verify-release": "node kit/verify-release.mjs",
     "budget": "node kit/budget.mjs"
@@ -46,7 +48,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/AllanSantos-DV/engine-registry.git"
+    "url": "git+https://github.com/AllanSantos-DV/engine-registry.git"
   },
   "license": "MIT",
   "private": false