@neetru/cli 2.32.1 → 2.33.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ Convenção: [Keep a Changelog](https://keepachangelog.com/) + [SemVer](https://
 
 ## [Unreleased]
 
+## [2.33.0] — 2026-10-19 (`neetru db frontdoor` e confirmação da VM na limpeza forçada)
+
+> **Por que MINOR.** Entram um comando novo (`neetru db frontdoor enable|status|disable`) e uma flag nova (`neetru servers force-cleanup --confirm-instance-id`), sem quebrar comportamento existente. Os dois só funcionam contra um Core com o core#727 e o core#732 no ar; antes disso a rota da porta de entrada responde 404, e a limpeza forçada ignora a confirmação.
+
+### Adicionado
+
+- **`neetru db frontdoor enable|status|disable` — porta de entrada privada de um banco Postgres em VM para um app em OUTRA VM da rede interna, sem mover o banco** (Core #727, bug_5c0e7738). Até aqui o único caminho era o `neetru db move`, que recusa destino igual à origem — um banco que já estava na VM certa não tinha como atender um app noutra VM (caso do Zelo: banco na snee-003-db, app indo para a snee-002-multi).
+  - `neetru db frontdoor enable <dbId> --app-server <serverId> --reason "<motivo>"` pede ao Core que prepare o PgBouncer na VM do banco, teste a conexão a partir da VM do app, teste o login pelo IP interno na própria VM do banco e só então grave o novo endereço. Falha em qualquer passo não muda nada para o app. Enquanto o Core trabalha, a CLI mostra o passo em que ele está (1 de 3, 2 de 3, 3 de 3). A operação só anda enquanto o comando roda: se o Core devolver a operação ainda em curso, ou a conexão cair, a CLI chama de novo e o Core retoma a mesma operação; repetir o comando depois também retoma. `--dry-run` só confere os requisitos, sem alterar nada e sem MFA (inclusive o novo "VM do app é da frota da Neetru"). A confirmação avisa que o PgBouncer da VM do banco reinicia uma vez. Só o endereço gravado no cadastro do banco faz o comando dizer "ligada": o vencimento do certificado pode aparecer antes, ou depois de uma falha, e não conta.
+  - `neetru db frontdoor status <dbId>` mostra se a porta está ligada (e em que IP), quando o certificado vence e a última operação, com o erro e o que fazer; uma operação parada no meio vem com o comando para retomar ou cancelar.
+  - `neetru db frontdoor disable <dbId> --reason "<motivo>"` volta o app ao endereço local da VM do banco e cancela uma ligação em andamento. **Desligar uma porta ligada (o desfazer normal) exige `--force`**, e também quando não se sabe em que VM o app roda: o app volta ao endereço local da VM do banco e, se ainda roda em outra VM, fica sem banco. A CLI explica isso antes de pedir MFA e, com `--force`, pede confirmação forte (digitar o id do banco; em script, `--yes` junto). Cancelar uma ligação em andamento que ainda não gravou nada não precisa de `--force`. Um endereço gravado por outra origem (por exemplo uma mudança de VM do banco) nunca é tirado por aqui: a CLI avisa que ele ficou (`host_kept`) ou que nem `--force` o desfaz (`FRONT_DOOR_HOST_NOT_OWNED`).
+  - MFA como no `db move`: `--mfa-token` ou a sessão de 1h de `neetru auth mfa-session`; sessão recusada pelo Core leva a um pedido de TOTP fresco, uma vez. O TOTP é de uso único, então nas retomadas o código já usado não é reenviado (vale a sessão, ou um TOTP novo).
+  - Cada código `FRONT_DOOR_*` da rota tem mensagem própria em português (a do Core primeiro, depois o que fazer); no `--json`, `{ ok:false, error, message, guidance }`.
+  - `neetru db move` passa a explicar a recusa `RELOCATE_FRONT_DOOR_OP_IN_PROGRESS` (409): há uma ligação da porta de entrada do banco em andamento — esperar ou cancelá-la com `neetru db frontdoor disable` e rodar a mudança de novo.
+  - Conferência opt-in contra o Core de verdade (`NEETRU_CORE_DIR`, a mesma do manifesto de MFA): todo código que a CLI trata existe no código das rotas do Core, todo `FRONT_DOOR_*` do Core tem mensagem na CLI e todo requisito do preflight tem nome legível.
+  - **Depende do Core #727** (rotas `POST|GET /api/cli/v1/db/{id}/frontdoor` e `POST /api/cli/v1/db/{id}/frontdoor/disable`); antes do deploy dele o comando responde 404.
+
+- **`neetru servers force-cleanup --confirm-instance-id <id>` — confirmar a VM que a limpeza forçada vai apagar** (core#732, bug_90ec21cd). O Core passou a só apagar a VM de um servidor quando ela é provadamente a dele: nome de VM é reaproveitado (uma VM recriada com o mesmo nome já foi apagada no lugar da velha). Quando o servidor não tem o id da VM registrado e existe uma VM com o mesmo nome, o Core recusa (`vm_sem_externalid`) e diz o id que viu e o comando `gcloud` para conferir; o operador confere e repete o comando com `--confirm-instance-id <id que conferiu>`. A CLI mostra, em português, a mensagem de cada recusa da guarda (`vm_sem_externalid`, `vm_confirmacao_nao_confere`, `vm_id_divergente`, `vm_leitura_falhou` — esta quando o Google Cloud não pôde ser lido — e `vm_nome_em_uso_por_outro_servidor`, quando outro servidor registrado e ativo usa uma VM com o mesmo nome e zona: nesse caso **não adianta confirmar o id**, o Core recusa mesmo com `--confirm-instance-id`, e a CLI lista os outros servidores) com o que fazer. Quando o Core manda os detalhes da recusa, a CLI mostra o id visto, a criação da VM ao lado da criação do servidor (a VM do próprio servidor nasce segundos depois dele; diferença grande indica VM recriada) e o comando de conferência. No `--json` devolve `{ ok:false, error, message, guidance, details? }`. `--confirm-instance-id` vazio ou só com espaços é recusado (`invalid_param`), sem ir ao Core. O `CliApiError` passa a carregar em `details` os campos extras do erro canônico `{ error: { code, message, … } }`. **A CLI nunca preenche o id a partir da resposta nem tenta de novo sozinha**: quem confere digita. Id fora do formato numérico é recusado antes de ir ao Core. No sucesso, a CLI diz como a VM foi identificada (pelo id registrado, pelo id confirmado, ou que a VM com aquele nome era de outro servidor e não foi tocada). **Depende do core#732**: antes do deploy dele o Core ignora a flag e ainda apaga a VM pelo nome, sem conferir a identidade (o comportamento antigo).
+
 ## [2.32.1] — 2026-10-18 (comandos sem pergunta não carregam o `inquirer`)
 
 > **Por que PATCH.** Só conserto de desempenho e testes, sem mudança de comportamento nem de saída documentada.

package/dist/commands/db-frontdoor.d.ts

@@ -0,0 +1,116 @@
+export type FrontDoorState = 'planning' | 'preparing' | 'verifying_app' | 'verifying_local' | 'enabled' | 'failed' | 'cancelled' | 'disabled';
+export interface FrontDoorLedger {
+    serverId: string | null;
+    frontDoorHost: string | null;
+    frontDoorCertNotAfter: string | null;
+}
+export interface FrontDoorOp {
+    opId: string;
+    state: FrontDoorState;
+    dbServerId: string;
+    appServerId: string;
+    host: string;
+    port: number;
+    allowedClientCidr: string | null;
+    frontDoorCertNotAfter: string | null;
+    preparedAt: string | null;
+    appVerifiedAt: string | null;
+    localVerifiedAt: string | null;
+    enabledAt: string | null;
+    failedAt: string | null;
+    cancelledAt: string | null;
+    disabledAt: string | null;
+    lastError: {
+        code: string;
+        message: string;
+        at: string;
+    } | null;
+    reason: string;
+    updatedAt: string;
+}
+export interface FrontDoorCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface FrontDoorEnableResponse {
+    ok: true;
+    dbId: string;
+    dryRun: boolean;
+    done: boolean;
+    alreadyEnabled: boolean;
+    state: FrontDoorState;
+    preflight: {
+        ok: boolean;
+        checks: FrontDoorCheck[];
+    };
+    op: FrontDoorOp | null;
+    ledger: FrontDoorLedger | null;
+}
+export interface FrontDoorStatusResponse {
+    ok: true;
+    dbId: string;
+    ledger: FrontDoorLedger;
+    op: FrontDoorOp | null;
+}
+export interface FrontDoorDisableResponse {
+    ok: true;
+    dbId: string;
+    /**
+     * `host_kept` (Core #727, rodada 2): a ligação em curso foi cancelada, mas o
+     * endereço gravado no cadastro não é desta porta de entrada e FICOU.
+     */
+    outcome: 'disabled' | 'already_disabled' | 'host_kept';
+    previousFrontDoorHost: string | null;
+    opTransition: 'cancelled' | 'disabled' | null;
+    opId: string | null;
+    ledger: FrontDoorLedger | null;
+}
+/** O que cada estado quer dizer, em português simples. */
+export declare const STATE_LABELS: Record<FrontDoorState, string>;
+export declare function isInFlight(state: FrontDoorState | undefined): boolean;
+/** Nome legível de cada requisito do `--dry-run` (o Core manda o nome técnico). */
+export declare const CHECK_LABELS: Record<string, string>;
+/**
+ * O que fazer para cada código `FRONT_DOOR_*` que a rota devolve. A mensagem
+ * do Core (com VMs, IPs e o motivo do agente) vem antes; isto é o "e agora?".
+ */
+export declare const FRONT_DOOR_GUIDANCE: Record<string, string>;
+/** Mensagem do Core primeiro (dados reais), depois o que fazer. Pura. */
+export declare function describeFrontDoorError(code: string, serverMessage: string): string;
+export interface DbFrontdoorEnableOptions {
+    appServer?: string;
+    reason?: string;
+    dryRun?: boolean;
+    yes?: boolean;
+    mfaToken?: string;
+    json?: boolean;
+    /** Somente testes: intervalo da consulta de progresso (ms). Default 3000. */
+    pollIntervalMs?: number;
+    /** Somente testes: prazo total somando as voltas (ms). Default 20 min. */
+    timeoutMs?: number;
+    /** Somente testes: espera de cada POST no Core (s). Default 240 (o máximo da rota). */
+    waitSeconds?: number;
+}
+export declare function runDbFrontdoorEnable(dbId: string, opts?: DbFrontdoorEnableOptions): Promise<void>;
+export declare function runDbFrontdoorStatus(dbId: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export interface DbFrontdoorDisableOptions {
+    reason?: string;
+    force?: boolean;
+    yes?: boolean;
+    mfaToken?: string;
+    json?: boolean;
+}
+/**
+ * Desligar (desfazer) — regras do Core #727 (rodada 2), decididas na transação:
+ *  - porta LIGADA por este comando pra um app noutra VM (o desfazer normal) ⇒
+ *    exige `--force`; idem quando não se sabe em que VM o app roda;
+ *  - ligação em curso sem endereço gravado ⇒ só cancela, sem `--force`;
+ *  - endereço gravado por OUTRA origem (ex.: mudança de VM do banco) nunca é
+ *    tirado por aqui: `host_kept` (cancelou a ligação em curso) ou
+ *    `FRONT_DOOR_HOST_NOT_OWNED` (409, nem com `--force`).
+ * Com `--force` a confirmação é forte: digitar o id do banco (ou `--yes`).
+ */
+export declare function runDbFrontdoorDisable(dbId: string, opts?: DbFrontdoorDisableOptions): Promise<void>;

package/dist/commands/db-frontdoor.js

@@ -0,0 +1,567 @@
+/**
+ * `neetru db frontdoor` — PORTA DE ENTRADA privada de um banco Postgres em VM,
+ * SEM mover o banco (Core #727, bug_5c0e7738).
+ *
+ * Caso de uso: o banco fica onde está e o app passa a rodar (ou já roda) em
+ * OUTRA VM da rede interna — ex.: banco do Zelo na snee-003-db, app indo pra
+ * snee-002-multi. O `neetru db move` não serve (recusa destino == origem).
+ *
+ *   enable <dbId> --app-server <serverId> --reason "<motivo>"
+ *     O Core prepara o PgBouncer na VM do banco, testa a conexão a partir da VM
+ *     do app, testa o login pelo IP interno NA PRÓPRIA VM do banco e só então
+ *     grava o novo endereço no cadastro do banco. Falha em qualquer passo = nada
+ *     muda para o app. `--dry-run` só confere os requisitos (sem MFA).
+ *   status <dbId>
+ *   disable <dbId> --reason "<motivo>" [--force]
+ *     Volta o endereço do app para o local da VM do banco (desfazer).
+ *
+ * COMO ANDA (contrato do Core): a operação só avança DENTRO da chamada de
+ * `enable` (não há nada rodando no Core em segundo plano). Por isso o CLI faz o
+ * POST com espera longa e, enquanto ele roda, consulta o GET pra mostrar o
+ * passo em que está. Se o POST voltar com a operação ainda em curso, o CLI
+ * chama de novo (o Core RETOMA a mesma operação) até um fim ou o prazo total.
+ * Repetir o comando depois também retoma.
+ *
+ * MFA (igual ao `db move`/`products db set-status`): `--mfa-token` ou a sessão
+ * de 1h de `neetru auth mfa-session`; sessão recusada pelo Core ⇒ pede um TOTP
+ * fresco UMA vez. O TOTP é de uso único: nas retomadas o código já gasto não é
+ * reenviado (vale a sessão, ou um TOTP novo).
+ *
+ * Endpoints (Core):
+ *   POST /api/cli/v1/db/{id}/frontdoor          — liga/retoma/dry-run (MFA fora do dry-run)
+ *   GET  /api/cli/v1/db/{id}/frontdoor          — estado
+ *   POST /api/cli/v1/db/{id}/frontdoor/disable  — desliga (MFA)
+ *
+ * Plain PT-BR em toda string visível ao usuário.
+ */
+import { createInterface } from 'node:readline';
+import chalk from 'chalk';
+import ora from 'ora';
+import { apiRequest, CliApiError, CliNetworkError } from '../lib/api-client.js';
+import { handleApiError } from '../lib/api-error.js';
+import { requireToken } from '../lib/cli-read.js';
+import { confirmDestructive, resolveStepUp, withStepUpRetry } from '../lib/cli-write.js';
+import { log } from '../utils/logger.js';
+import { isSafeExitHalt, safeExit, setSafeExitCode } from '../utils/safe-exit.js';
+// ---------------------------------------------------------------------------
+// Textos (puros — testáveis sem rede)
+// ---------------------------------------------------------------------------
+/** O que cada estado quer dizer, em português simples. */
+export const STATE_LABELS = {
+    planning: 'conferindo os requisitos',
+    preparing: 'passo 1 de 3 — preparando o PgBouncer na VM do banco',
+    verifying_app: 'passo 2 de 3 — testando a conexão a partir da VM do app',
+    verifying_local: 'passo 3 de 3 — testando o login pelo IP interno na própria VM do banco',
+    enabled: 'ligada',
+    failed: 'falhou (nada mudou para o app)',
+    cancelled: 'cancelada (nada mudou para o app)',
+    disabled: 'desligada',
+};
+const IN_FLIGHT = new Set(['preparing', 'verifying_app', 'verifying_local']);
+export function isInFlight(state) {
+    return !!state && IN_FLIGHT.has(state);
+}
+/** Nome legível de cada requisito do `--dry-run` (o Core manda o nome técnico). */
+export const CHECK_LABELS = {
+    db_active: 'banco ativo',
+    engine_supported: 'tipo de banco suportado',
+    db_server_known: 'VM do banco conhecida',
+    credentials: 'credencial do banco registrada',
+    endpoint: 'endereço do banco legível',
+    distinct_server: 'app e banco em VMs diferentes',
+    db_server_ready: 'VM do banco no ar',
+    app_server_ready: 'VM do app no ar',
+    front_door_plan: 'IPs internos das duas VMs',
+    front_door_host_consistent: 'sem outro endereço já gravado',
+    no_active_relocate: 'nenhuma mudança de VM do banco em andamento',
+    app_environment: 'onde o produto diz que o app roda',
+    app_server_fleet: 'VM do app é da frota da Neetru',
+};
+/**
+ * O que fazer para cada código `FRONT_DOOR_*` que a rota devolve. A mensagem
+ * do Core (com VMs, IPs e o motivo do agente) vem antes; isto é o "e agora?".
+ */
+export const FRONT_DOOR_GUIDANCE = {
+    FRONT_DOOR_INPUT_INVALID: 'Algum dado do pedido está fora do formato: o banco é um id que começa com pdb_ e a VM do app é o id do servidor.',
+    FRONT_DOOR_DB_NOT_FOUND: 'Banco não encontrado. Confira o id do banco com `neetru db where --product <slug>`.',
+    FRONT_DOOR_DB_NOT_ACTIVE: 'O banco não está ativo (ou o cadastro dele está incompleto). Só dá para ligar a porta de entrada de um banco ativo.',
+    FRONT_DOOR_ENGINE_UNSUPPORTED: 'A porta de entrada só existe para Postgres em VM (vm-postgres-single).',
+    FRONT_DOOR_NO_CREDENTIALS: 'O banco não tem credencial registrada, então não há como testar o login pela porta nova. Fale com o Dev Core.',
+    FRONT_DOOR_SAME_SERVER: 'A VM do app informada é a própria VM do banco. Nesse caso o app já fala com o banco pelo endereço local — não há nada a ligar.',
+    FRONT_DOOR_DB_SERVER_NOT_READY: 'A VM do banco não está no ar ou o agente dela está sem dar sinal há mais de 5 minutos. Verifique a VM e tente de novo.',
+    FRONT_DOOR_APP_SERVER_NOT_READY: 'A VM do app não existe, não está no ar ou o agente dela está sem dar sinal há mais de 5 minutos. Confira o id passado em --app-server.',
+    FRONT_DOOR_APP_SERVER_NOT_FLEET: 'A VM do app não é uma VM da Neetru (é de cliente ou não tem identidade no Google Cloud do projeto). A liberação abre o banco para a VM inteira, então só vale para VM da frota. Confira o id passado em --app-server.',
+    FRONT_DOOR_NOT_PLANNABLE: 'Não foi possível descobrir o IP interno de uma das VMs (ou ele não é da rede interna). Nada foi alterado.',
+    FRONT_DOOR_RELOCATE_IN_PROGRESS: 'Este banco está mudando de VM. Até a mudança terminar a porta de entrada é dela — acompanhe com `neetru db move status <id>` e tente depois.',
+    FRONT_DOOR_HOST_CONFLICT: 'O cadastro do banco já aponta outro IP interno, diferente do IP atual da VM do banco. Desligue primeiro com `neetru db frontdoor disable <dbId>` e ligue de novo.',
+    FRONT_DOOR_IN_PROGRESS: 'Já há uma ligação em andamento para outra VM do app. Repita o comando com aquela VM para concluir, ou cancele com `neetru db frontdoor disable <dbId>`.',
+    FRONT_DOOR_PREPARE_FAILED: 'O preparo na VM do banco falhou (o motivo acima vem da própria VM). Nada mudou para o app: ele segue usando o endereço local.',
+    FRONT_DOOR_VERIFY_APP_FAILED: 'A VM do app não conseguiu chegar ao banco pela rede interna (rede, firewall ou certificado). Nada mudou para o app.',
+    FRONT_DOOR_VERIFY_LOCAL_FAILED: 'O teste de login pelo IP interno, feito na própria VM do banco, falhou — o app que roda lá poderia perder o banco, então nada foi gravado.',
+    FRONT_DOOR_UNVERIFIED: 'Os testes ficaram antigos (mais de 10 minutos) antes da gravação. Rode o mesmo comando de novo: ele recomeça e testa outra vez.',
+    FRONT_DOOR_STATE_CHANGED: 'O banco mudou (de VM, de credencial ou de estado) enquanto a porta era testada, ou a operação foi trocada por outra. Nada foi gravado — confira com `neetru db frontdoor status <dbId>` e tente de novo.',
+    // NÃO está na lista de códigos do Core (`FRONT_DOOR_OP_ERROR_CODES`): é o
+    // `lastError.code` que o desligar grava na operação que ele cancela
+    // (`frontdoor-op-deps.ts`). A rota o devolve quando uma ligação em curso
+    // percebe o cancelamento; e o ramo "terminou sem erro" do `enable` também o
+    // sintetiza a partir do estado (`FRONT_DOOR_<ESTADO>`) — defesa em
+    // profundidade, porque o Core sempre responde erro numa operação cancelada.
+    FRONT_DOOR_CANCELLED: 'A ligação foi cancelada porque a porta de entrada foi desligada enquanto ela andava. Nada foi gravado.',
+    FRONT_DOOR_APP_ON_OTHER_VM: 'Desligar faz o app voltar a receber o endereço local da VM do banco: um app que roda em OUTRA VM fica sem banco. ' +
+        'Desligar uma porta ligada (o desfazer normal) sempre pede --force, e também quando não se sabe em que VM o app roda. ' +
+        'Leve o app de volta para a VM do banco antes ou, se é isso mesmo, repita com --force.',
+    FRONT_DOOR_HOST_NOT_OWNED: 'O endereço gravado no cadastro do banco não foi ligado por este comando (veio de outra origem, por exemplo uma mudança de VM do banco). ' +
+        'Ele não é desfeito por aqui, nem com --force. Fale com o Dev Core.',
+};
+/** Mensagem do Core primeiro (dados reais), depois o que fazer. Pura. */
+export function describeFrontDoorError(code, serverMessage) {
+    const guidance = FRONT_DOOR_GUIDANCE[code];
+    return guidance ? `${serverMessage}\n  ${guidance}` : serverMessage;
+}
+/** Erro da rota: `FRONT_DOOR_*` vira mensagem + o que fazer; o resto vai pro handler comum. */
+function failFrontDoor(err, json) {
+    if (isSafeExitHalt(err))
+        throw err;
+    if (err instanceof CliApiError && typeof err.code === 'string' && err.code.startsWith('FRONT_DOOR_')) {
+        if (json) {
+            console.log(JSON.stringify({
+                ok: false,
+                error: err.code,
+                message: err.message,
+                guidance: FRONT_DOOR_GUIDANCE[err.code] ?? null,
+            }));
+        }
+        else {
+            log.error(describeFrontDoorError(err.code, err.message));
+        }
+        return safeExit(1);
+    }
+    return handleApiError(err, json);
+}
+function inputError(message, json) {
+    if (json)
+        console.log(JSON.stringify({ ok: false, error: 'input', message }));
+    else
+        log.error(message);
+    return safeExit(1);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Sinal interno: o POST longo caiu por rede/tempo — retoma na próxima volta. */
+class RetomarVolta extends Error {
+}
+/**
+ * Consulta o estado em paralelo ao POST longo, só pra mostrar o passo. Erro de
+ * consulta não importa (é exibição). Devolve a função que para.
+ */
+function acompanharPassos(dbId, intervalMs, onOp) {
+    let parado = false;
+    void (async () => {
+        while (!parado) {
+            await sleep(intervalMs);
+            if (parado)
+                break;
+            try {
+                const s = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`);
+                if (!parado && s.op)
+                    onOp(s.op);
+            }
+            catch {
+                /* só exibição */
+            }
+        }
+    })();
+    return () => {
+        parado = true;
+    };
+}
+export async function runDbFrontdoorEnable(dbId, opts = {}) {
+    if (!opts.json)
+        log.banner();
+    if (!dbId || !dbId.trim())
+        inputError('Informe o id do banco (pdb_…).', opts.json);
+    if (!opts.appServer || !opts.appServer.trim()) {
+        inputError('--app-server <serverId> é obrigatório (a VM onde o app roda ou vai rodar).', opts.json);
+    }
+    if (!opts.reason || !opts.reason.trim()) {
+        inputError('--reason "<texto>" é obrigatório (vai para o registro de auditoria).', opts.json);
+    }
+    const appServer = opts.appServer.trim();
+    await requireToken(opts.json);
+    // ── Estado ANTES: mostra o plano e falha cedo no caso óbvio. Rede instável
+    //    não bloqueia (o Core confere tudo de novo). ─────────────────────────────
+    let before = null;
+    try {
+        before = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`);
+    }
+    catch (err) {
+        if (!(err instanceof CliNetworkError))
+            failFrontDoor(err, opts.json);
+    }
+    const dbServer = before?.ledger.serverId ?? null;
+    if (dbServer && dbServer === appServer) {
+        const msg = describeFrontDoorError('FRONT_DOOR_SAME_SERVER', `A VM do app (${appServer}) é a mesma VM do banco.`);
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, error: 'FRONT_DOOR_SAME_SERVER', message: msg }));
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+    }
+    if (!opts.json) {
+        log.heading(opts.dryRun ? 'Porta de entrada do banco (só conferência)' : 'Porta de entrada do banco');
+        log.info(`Banco:          ${chalk.cyan(dbId)}`);
+        log.info(`VM do banco:    ${dbServer ? chalk.bold(dbServer) : chalk.dim('(o Core confere)')}`);
+        log.info(`VM do app:      ${chalk.bold(appServer)}`);
+        log.info(`Hoje:           ${before?.ledger.frontDoorHost
+            ? `ligada em ${before.ledger.frontDoorHost}:5433`
+            : 'desligada — o app recebe o endereço local da VM do banco'}`);
+    }
+    const body = { appServerId: appServer, reason: opts.reason.trim() };
+    // ── Só conferência: nada é criado, sem MFA. ───────────────────────────────
+    if (opts.dryRun) {
+        const { headers } = await resolveStepUp({ dryRun: true, json: opts.json, mfaToken: opts.mfaToken });
+        let r;
+        try {
+            r = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`, {
+                method: 'POST',
+                body: { ...body, dryRun: true },
+                headers,
+            });
+        }
+        catch (err) {
+            failFrontDoor(err, opts.json);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ ...r, ok: r.preflight.ok }));
+            if (!r.preflight.ok)
+                setSafeExitCode(1);
+            return;
+        }
+        log.heading('Requisitos');
+        for (const c of r.preflight.checks) {
+            const mark = c.ok ? chalk.green('✓') : chalk.red('✗');
+            log.dim(`  ${mark} ${CHECK_LABELS[c.name] ?? c.name}${c.detail ? ` — ${c.detail}` : ''}`);
+        }
+        if (r.preflight.ok) {
+            log.success('Tudo certo para ligar. Nada foi alterado. Rode de novo sem --dry-run para ligar.');
+        }
+        else {
+            log.error('Algum requisito falhou — a porta de entrada não seria ligada. Nada foi alterado.');
+            setSafeExitCode(1);
+        }
+        return;
+    }
+    await confirmDestructive(`Ligar a porta de entrada do banco ${dbId} para a VM ${appServer}? O PgBouncer da VM do banco ` +
+        'reinicia uma vez (as conexões do app caem e voltam em segundos). Depois de ligada, TODO app ' +
+        'deste banco passa a falar com ele pelo IP interno da VM do banco — isso é testado antes de gravar.', { yes: opts.yes, json: opts.json });
+    // ── Voltas de POST longo (o Core anda só durante a chamada) ───────────────
+    const intervalMs = opts.pollIntervalMs ?? 3000;
+    const totalMs = opts.timeoutMs ?? 20 * 60 * 1000;
+    const waitSeconds = opts.waitSeconds ?? 240;
+    const inicio = Date.now();
+    const spinner = opts.json ? null : ora({ text: 'Ligando a porta de entrada…', color: 'blue' }).start();
+    let ultimoEstado = '';
+    const mostrar = (state) => {
+        if (state === ultimoEstado)
+            return;
+        ultimoEstado = state;
+        if (spinner)
+            spinner.text = STATE_LABELS[state] ?? state;
+    };
+    let volta = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (Date.now() - inicio >= totalMs) {
+            spinner?.fail('Prazo esgotado esperando a porta de entrada.');
+            const msg = 'A ligação continua registrada no Core e não mudou nada para o app. ' +
+                `Rode de novo \`neetru db frontdoor enable ${dbId} --app-server ${appServer} --reason "<motivo>"\` para retomar.`;
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, error: 'watch_timeout', dbId, message: msg }));
+            else
+                log.warn(msg);
+            setSafeExitCode(1);
+            return;
+        }
+        volta += 1;
+        const parar = spinner ? acompanharPassos(dbId, intervalMs, (op) => mostrar(op.state)) : () => undefined;
+        let r = null;
+        try {
+            r = await withStepUpRetry(
+            // O TOTP é de uso único: só a 1ª volta manda o `--mfa-token`; as
+            // retomadas usam a sessão de 1h (ou pedem um TOTP fresco).
+            { mfaToken: volta === 1 ? opts.mfaToken : undefined, json: opts.json, yes: opts.yes }, (headers) => apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`, {
+                method: 'POST',
+                body: { ...body, waitSeconds },
+                headers,
+                timeoutMs: (waitSeconds + 60) * 1000,
+            }), (err) => {
+                // POST longo que caiu por rede/tempo: o Core segue com a operação
+                // registrada — a próxima volta retoma.
+                if (err instanceof CliNetworkError)
+                    throw new RetomarVolta();
+                parar();
+                spinner?.fail('A porta de entrada NÃO foi ligada.');
+                return failFrontDoor(err, opts.json);
+            }, () => {
+                parar();
+                spinner?.stop();
+            });
+        }
+        catch (err) {
+            if (!(err instanceof RetomarVolta))
+                throw err;
+        }
+        finally {
+            parar();
+        }
+        if (!r) {
+            if (spinner)
+                spinner.text = 'Conexão com o Core caiu — retomando…';
+            await sleep(Math.min(intervalMs, 3000));
+            continue;
+        }
+        mostrar(r.state);
+        if (r.done) {
+            // Só o `frontDoorHost` do cadastro diz que a porta está ligada. O Core #727
+            // grava `frontDoorCertNotAfter` antes (no despacho do preparo), inclusive
+            // em operação que depois falha — esse campo NUNCA é prova de "ligada".
+            const hostLigado = r.ledger?.frontDoorHost ?? null;
+            if (!hostLigado) {
+                spinner?.fail('A porta de entrada NÃO aparece ligada no cadastro do banco.');
+                const msg = `O Core respondeu que terminou, mas o cadastro do banco ${dbId} não tem o endereço da porta de entrada — ` +
+                    `nada é dado como ligado. Confira com \`neetru db frontdoor status ${dbId}\`.`;
+                if (opts.json)
+                    console.log(JSON.stringify({ ok: false, error: 'not_recorded', dbId, message: msg }));
+                else
+                    log.error(msg);
+                setSafeExitCode(1);
+                return;
+            }
+            spinner?.succeed(r.alreadyEnabled ? 'A porta de entrada já estava ligada.' : 'Porta de entrada LIGADA.');
+            if (opts.json) {
+                console.log(JSON.stringify(r));
+                return;
+            }
+            const op = r.op;
+            if (r.alreadyEnabled) {
+                log.info(`Já estava ligada para a VM ${appServer} — nada mudou.`);
+            }
+            else {
+                log.success(`O banco ${dbId} agora atende a VM ${appServer} pelo IP interno ${hostLigado}:${op?.port ?? 5433}.`);
+                log.dim('  Vale para todo app deste banco, inclusive o que ainda roda na VM do banco ' +
+                    '(o login por esse caminho foi testado lá antes de gravar).');
+            }
+            const vence = r.ledger?.frontDoorCertNotAfter;
+            if (vence)
+                log.dim(`  Certificado do PgBouncer vence em: ${vence}`);
+            log.info(`Próximo passo: faça o deploy do app na VM ${appServer} e confira login e uma operação real.`);
+            return;
+        }
+        if (!isInFlight(r.state)) {
+            // Não deveria acontecer (o Core responde erro na falha), mas sem mentir:
+            const code = r.op?.lastError?.code ?? `FRONT_DOOR_${String(r.state).toUpperCase()}`;
+            const message = r.op?.lastError?.message ?? `Operação terminou em ${r.state}.`;
+            spinner?.fail('A porta de entrada NÃO foi ligada.');
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, error: code, message, guidance: FRONT_DOOR_GUIDANCE[code] ?? null }));
+            }
+            else {
+                log.error(describeFrontDoorError(code, message));
+            }
+            setSafeExitCode(1);
+            return;
+        }
+        // Ainda andando depois da espera do Core: chama de novo (retoma a mesma operação).
+        await sleep(Math.min(intervalMs, 3000));
+    }
+}
+// ---------------------------------------------------------------------------
+// neetru db frontdoor status <dbId>
+// ---------------------------------------------------------------------------
+export async function runDbFrontdoorStatus(dbId, opts = {}) {
+    await requireToken(opts.json);
+    let s;
+    try {
+        s = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`);
+    }
+    catch (err) {
+        failFrontDoor(err, opts.json);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(s));
+        return;
+    }
+    log.heading(`Porta de entrada do banco ${s.dbId}`);
+    log.info(`VM do banco:    ${s.ledger.serverId ?? '—'}`);
+    log.info(`Porta:          ${s.ledger.frontDoorHost
+        ? chalk.green(`ligada em ${s.ledger.frontDoorHost}:5433`)
+        : 'desligada — o app recebe o endereço local da VM do banco'}`);
+    if (s.ledger.frontDoorCertNotAfter) {
+        log.dim(`  certificado do PgBouncer vence em: ${s.ledger.frontDoorCertNotAfter}` +
+            (s.ledger.frontDoorHost ? '' : ' (ele segue na VM do banco mesmo com a porta desligada)'));
+    }
+    const op = s.op;
+    if (!op) {
+        log.dim('  Nenhuma ligação feita por este comando até agora.');
+        return;
+    }
+    log.heading('Última operação');
+    log.info(`Estado:         ${STATE_LABELS[op.state] ?? op.state}`);
+    log.info(`VM do app:      ${op.appServerId}${op.allowedClientCidr ? ` (liberada: ${op.allowedClientCidr})` : ''}`);
+    log.dim(`  pedido: ${op.reason}`);
+    if (op.preparedAt)
+        log.dim(`  preparado na VM do banco em: ${op.preparedAt}`);
+    if (op.appVerifiedAt)
+        log.dim(`  testado a partir da VM do app em: ${op.appVerifiedAt}`);
+    if (op.localVerifiedAt)
+        log.dim(`  login testado na VM do banco em: ${op.localVerifiedAt}`);
+    if (op.enabledAt)
+        log.dim(`  ligada em: ${op.enabledAt}`);
+    if (op.failedAt)
+        log.dim(`  falhou em: ${op.failedAt}`);
+    if (op.cancelledAt)
+        log.dim(`  cancelada em: ${op.cancelledAt}`);
+    if (op.disabledAt)
+        log.dim(`  desligada em: ${op.disabledAt}`);
+    if (op.lastError)
+        log.warn(describeFrontDoorError(op.lastError.code, op.lastError.message));
+    if (isInFlight(op.state)) {
+        log.warn('Esta ligação só anda enquanto o comando de ligar estiver rodando. Para concluir, rode de novo ' +
+            `\`neetru db frontdoor enable ${s.dbId} --app-server ${op.appServerId} --reason "<motivo>"\`; ` +
+            `para cancelar, \`neetru db frontdoor disable ${s.dbId} --reason "<motivo>"\`.`);
+    }
+}
+/** Uma pergunta no terminal (a confirmação forte do `disable --force`). */
+function perguntar(pergunta) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(`  ${pergunta} `, (resposta) => {
+            rl.close();
+            resolve(resposta.trim());
+        });
+    });
+}
+/**
+ * Desligar (desfazer) — regras do Core #727 (rodada 2), decididas na transação:
+ *  - porta LIGADA por este comando pra um app noutra VM (o desfazer normal) ⇒
+ *    exige `--force`; idem quando não se sabe em que VM o app roda;
+ *  - ligação em curso sem endereço gravado ⇒ só cancela, sem `--force`;
+ *  - endereço gravado por OUTRA origem (ex.: mudança de VM do banco) nunca é
+ *    tirado por aqui: `host_kept` (cancelou a ligação em curso) ou
+ *    `FRONT_DOOR_HOST_NOT_OWNED` (409, nem com `--force`).
+ * Com `--force` a confirmação é forte: digitar o id do banco (ou `--yes`).
+ */
+export async function runDbFrontdoorDisable(dbId, opts = {}) {
+    if (!opts.json)
+        log.banner();
+    if (!dbId || !dbId.trim())
+        inputError('Informe o id do banco (pdb_…).', opts.json);
+    if (!opts.reason || !opts.reason.trim()) {
+        inputError('--reason "<texto>" é obrigatório (vai para o registro de auditoria).', opts.json);
+    }
+    await requireToken(opts.json);
+    let before = null;
+    try {
+        before = await apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor`);
+    }
+    catch (err) {
+        if (!(err instanceof CliNetworkError))
+            failFrontDoor(err, opts.json);
+    }
+    const host = before?.ledger.frontDoorHost ?? null;
+    const dbServer = before?.ledger.serverId ?? null;
+    const opAntes = before?.op ?? null;
+    // A VM do app que a porta ligada atende (se a porta é deste comando e está ligada).
+    const appLigado = host && opAntes && opAntes.state === 'enabled' && opAntes.host === host && opAntes.dbServerId === dbServer
+        ? opAntes.appServerId
+        : null;
+    const appNoutraVm = appLigado && appLigado !== dbServer ? appLigado : null;
+    const vmDoBanco = dbServer ?? 'VM do banco';
+    // ── Desfazer uma porta ligada pede --force: explica ANTES de pedir MFA. ──
+    if (appNoutraVm && !opts.force) {
+        const msg = `A porta de entrada está ligada para a VM do app ${appNoutraVm}. Desligar exige --force: o app volta a ` +
+            `receber o endereço local da VM do banco ${vmDoBanco}, e um app que ainda rode em ${appNoutraVm} FICA SEM ` +
+            'BANCO até voltar para a VM do banco.';
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: false,
+                error: 'FRONT_DOOR_APP_ON_OTHER_VM',
+                message: msg,
+                guidance: FRONT_DOOR_GUIDANCE.FRONT_DOOR_APP_ON_OTHER_VM,
+            }));
+        }
+        else {
+            log.error(msg);
+        }
+        safeExit(1);
+    }
+    if (opts.force) {
+        const efeito = `Desligar com --force: o app deixa de receber o IP interno${host ? ` ${host}:5433` : ''} e volta para o ` +
+            `endereço local da VM ${vmDoBanco}. ` +
+            (appNoutraVm
+                ? `Se o app ainda roda em ${appNoutraVm}, ele CAI (fica sem banco) até voltar para a VM do banco.`
+                : 'Um app que rode em outra VM CAI (fica sem banco).');
+        if (!opts.yes) {
+            if (opts.json || !process.stdin.isTTY) {
+                const msg = 'Desligar com --force pede confirmação forte: digite o id do banco num terminal interativo, ' +
+                    'ou passe --yes junto com --force.';
+                if (opts.json)
+                    console.log(JSON.stringify({ ok: false, error: 'confirmation_required', message: msg }));
+                else
+                    log.error(msg);
+                safeExit(1);
+            }
+            log.warn(efeito);
+            const digitado = await perguntar(`Para confirmar, digite o id do banco (${dbId}):`);
+            if (digitado !== dbId) {
+                log.error('O id não conferiu. Nada foi alterado.');
+                safeExit(1);
+            }
+        }
+        else if (!opts.json) {
+            log.warn(efeito);
+        }
+    }
+    else {
+        await confirmDestructive(`Desligar a porta de entrada do banco ${dbId}? O app volta a receber o endereço local da VM ${vmDoBanco}` +
+            (host ? ` (hoje recebe ${host}:5433)` : '') +
+            '. Uma ligação em andamento é cancelada.', { yes: opts.yes, json: opts.json });
+    }
+    const spinner = opts.json ? null : ora({ text: 'Desligando a porta de entrada…', color: 'blue' }).start();
+    const r = await withStepUpRetry({ mfaToken: opts.mfaToken, json: opts.json, yes: opts.yes }, (headers) => apiRequest(`/api/cli/v1/db/${encodeURIComponent(dbId)}/frontdoor/disable`, {
+        method: 'POST',
+        body: { reason: opts.reason.trim(), ...(opts.force ? { force: true } : {}) },
+        headers,
+    }), (err) => {
+        spinner?.fail('A porta de entrada NÃO foi desligada.');
+        return failFrontDoor(err, opts.json);
+    }, () => spinner?.stop());
+    spinner?.stop();
+    if (opts.json) {
+        console.log(JSON.stringify(r));
+        return;
+    }
+    const vmFinal = r.ledger?.serverId ?? vmDoBanco;
+    if (r.outcome === 'already_disabled') {
+        log.info('A porta de entrada já estava desligada — o endereço do app não mudou.');
+    }
+    else if (r.outcome === 'host_kept') {
+        log.warn(`A ligação em andamento (${r.opId}) foi cancelada, mas o endereço gravado no cadastro` +
+            `${r.previousFrontDoorHost ? ` (${r.previousFrontDoorHost}:5433)` : ''} não é desta porta de entrada ` +
+            '(veio de outra origem, por exemplo uma mudança de VM do banco) e FICOU como estava.');
+    }
+    else {
+        log.success(`Porta de entrada DESLIGADA. O app volta a receber o endereço local da VM ${vmFinal}` +
+            `${r.previousFrontDoorHost ? ` (antes: ${r.previousFrontDoorHost}:5433)` : ''}.`);
+        if (appNoutraVm) {
+            log.warn(`Se o app ainda roda em ${appNoutraVm}, ele está SEM BANCO agora — leve-o para a VM ${vmFinal}.`);
+        }
+    }
+    if (r.opTransition === 'cancelled' && r.outcome !== 'host_kept') {
+        log.warn(`A ligação que estava em andamento (${r.opId}) foi cancelada.`);
+    }
+    log.dim('  Na VM do banco o PgBouncer segue escutando no IP interno, liberado só para a VM do app — ' +
+        'isso não é desfeito por este comando.');
+}
+//# sourceMappingURL=db-frontdoor.js.map

package/dist/commands/db-move.d.ts

@@ -182,6 +182,11 @@ export interface DbMoveStartOptions {
     /** Somente testes: teto do wall-clock do poll (ms). Default 30min. */
     pollTimeoutMs?: number;
 }
+/**
+ * Recusas do KICKOFF (`POST /db/{id}/relocate`) com código estável e o que
+ * fazer, em PT-BR. As outras recusas seguem pelo tratamento comum.
+ */
+export declare const RELOCATE_START_REFUSAL_GUIDANCE: Record<string, string>;
 export declare function runDbMoveStart(opts: DbMoveStartOptions): Promise<void>;
 /**
  * Acompanha a máquina de estados até um estado terminal (done/rolled_back/failed)

package/dist/commands/db-move.js

@@ -283,6 +283,17 @@ async function resolveTargetDb(opts) {
     }
     return { dbId: dbs[0].id, source: dbs[0] };
 }
+/**
+ * Recusas do KICKOFF (`POST /db/{id}/relocate`) com código estável e o que
+ * fazer, em PT-BR. As outras recusas seguem pelo tratamento comum.
+ */
+export const RELOCATE_START_REFUSAL_GUIDANCE = {
+    // Core #727: o preflight do relocate recusa enquanto uma ligação da porta de
+    // entrada do banco (`neetru db frontdoor`) estiver em andamento.
+    RELOCATE_FRONT_DOOR_OP_IN_PROGRESS: 'Há uma ligação da porta de entrada deste banco em andamento. Espere ela terminar ' +
+        '(acompanhe com `neetru db frontdoor status <dbId>`) ou cancele com ' +
+        '`neetru db frontdoor disable <dbId> --reason "<motivo>"`, e então rode a mudança de VM de novo.',
+};
 export async function runDbMoveStart(opts) {
     if (!opts.json)
         log.banner();
@@ -371,6 +382,22 @@ export async function runDbMoveStart(opts) {
     }
     catch (err) {
         spinner?.fail('Falha ao iniciar relocação.');
+        // Recusa conhecida do kickoff (409 com código estável) ⇒ o que significa +
+        // o que fazer, em vez da mensagem genérica.
+        if (err instanceof CliApiError && RELOCATE_START_REFUSAL_GUIDANCE[err.code]) {
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    ok: false,
+                    error: err.code,
+                    message: err.message,
+                    guidance: RELOCATE_START_REFUSAL_GUIDANCE[err.code],
+                }));
+            }
+            else {
+                log.error(`${err.message}\n  ${RELOCATE_START_REFUSAL_GUIDANCE[err.code]}`);
+            }
+            safeExit(1);
+        }
         handleApiError(err, opts.json);
     }
     // ── Dry-run: só o preflight. Nada foi provisionado. ─────────────────────────

package/dist/commands/servers.d.ts

@@ -53,7 +53,36 @@ export declare function runServersDeactivate(id: string | undefined, opts: StepU
  */
 export interface ServersForceCleanupOptions extends StepUpOptions {
     reason: string;
+    /**
+     * core#732 (bug_90ec21cd): id numérico da instância no Google Cloud que o
+     * operador CONFERIU. Só faz falta quando o servidor não tem o id da VM
+     * registrado (`externalId`) e existe uma VM com o mesmo nome — o Core recusa
+     * com `vm_sem_externalid` e mostra o id visto + o comando de conferência.
+     * A CLI NUNCA preenche este id a partir da resposta: o operador digita.
+     */
+    confirmInstanceId?: string;
+}
+/**
+ * core#732: recusas da guarda de identidade da VM no force-cleanup. A mensagem
+ * do Core (com o id visto e o comando de conferência) vem antes; isto é o que
+ * fazer. Nenhum texto monta o comando com o id preenchido — de propósito.
+ */
+export declare const FORCE_CLEANUP_IDENTITY_GUIDANCE: Record<string, string>;
+/**
+ * Detalhes que o core#732 manda junto da recusa (`{ error: { …, instanceId?,
+ * instanceCreatedAt?, docCreatedAt?, outrosServidores?, comandoConferencia? } }`),
+ * só os campos conhecidos e com o tipo certo. Nunca vira comando com o id.
+ */
+export interface ForceCleanupIdentityDetails {
+    instanceId?: string;
+    instanceCreatedAt?: string;
+    docCreatedAt?: string;
+    outrosServidores?: string[];
+    comandoConferencia?: string;
 }
+export declare function forceCleanupIdentityDetails(raw: unknown): ForceCleanupIdentityDetails | undefined;
+/** Linhas legíveis dos detalhes (texto). Mostra o id VISTO, mas não monta comando com ele. */
+export declare function forceCleanupIdentityDetailLines(d: ForceCleanupIdentityDetails | undefined): string[];
 export declare function runServersForceCleanup(id: string, opts: ServersForceCleanupOptions): Promise<void>;
 export interface ServersDispatchOptions extends StepUpOptions {
     params?: string;

package/dist/commands/servers.js

@@ -342,6 +342,73 @@ export async function runServersDeactivate(id, opts) {
     }
     printWriteResult(res.dryRun ? res : { serverId: res.serverId, status: res.status }, `Servidor ${res.serverId} → ${res.status}`, opts.json);
 }
+/** Formato que a rota do Core aceita (id numérico da instância no GCP). */
+const INSTANCE_ID_RE = /^[1-9][0-9]{0,19}$/;
+/**
+ * core#732: recusas da guarda de identidade da VM no force-cleanup. A mensagem
+ * do Core (com o id visto e o comando de conferência) vem antes; isto é o que
+ * fazer. Nenhum texto monta o comando com o id preenchido — de propósito.
+ */
+export const FORCE_CLEANUP_IDENTITY_GUIDANCE = {
+    vm_sem_externalid: 'Este servidor não tem o id da VM registrado, e existe no Google Cloud uma VM com o mesmo nome — ' +
+        'pode ser OUTRA VM (nome reaproveitado). Nada foi apagado. Rode o comando de conferência acima; se a VM ' +
+        'for mesmo a deste servidor, repita o force-cleanup com --confirm-instance-id <id que você conferiu>. ' +
+        'A CLI não preenche esse id por você.',
+    vm_confirmacao_nao_confere: 'O id passado em --confirm-instance-id não é o da VM que o Core leu (a mensagem acima mostra os dois). ' +
+        'Nada foi apagado. Confira de novo antes de repetir.',
+    vm_id_divergente: 'O Google Cloud devolveu outra instância ao ler o id registrado deste servidor. Nada foi apagado — ' +
+        'fale com o Dev Core antes de tentar de novo.',
+    vm_leitura_falhou: 'Não deu para ler a VM no Google Cloud agora. Nada foi apagado. Tente de novo em alguns minutos; ' +
+        'se continuar, fale com o Dev Core.',
+    // core#732 rodada 2: a confirmação do id NÃO destrava este caso — nada de
+    // orientar "repita com o id".
+    vm_nome_em_uso_por_outro_servidor: 'Outro servidor registrado e ativo usa uma VM com o mesmo nome e zona — a VM pode ser dele. Nada foi apagado, ' +
+        'e NÃO adianta confirmar o id: o Core recusa este caso mesmo com --confirm-instance-id. Confira de qual servidor ' +
+        'é a VM e registre o id dela no servidor certo antes de excluir (fale com o Dev Core).',
+};
+export function forceCleanupIdentityDetails(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const texto = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+    const out = {};
+    const instanceId = texto(r.instanceId);
+    const instanceCreatedAt = texto(r.instanceCreatedAt);
+    const docCreatedAt = texto(r.docCreatedAt);
+    const comandoConferencia = texto(r.comandoConferencia);
+    const outros = Array.isArray(r.outrosServidores)
+        ? r.outrosServidores.map(texto).filter((x) => !!x)
+        : [];
+    if (instanceId)
+        out.instanceId = instanceId;
+    if (instanceCreatedAt)
+        out.instanceCreatedAt = instanceCreatedAt;
+    if (docCreatedAt)
+        out.docCreatedAt = docCreatedAt;
+    if (outros.length > 0)
+        out.outrosServidores = outros;
+    if (comandoConferencia)
+        out.comandoConferencia = comandoConferencia;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Linhas legíveis dos detalhes (texto). Mostra o id VISTO, mas não monta comando com ele. */
+export function forceCleanupIdentityDetailLines(d) {
+    if (!d)
+        return [];
+    const linhas = [];
+    if (d.outrosServidores) {
+        linhas.push(`Outro(s) servidor(es) ativo(s) com o mesmo nome e zona: ${d.outrosServidores.join(', ')}`);
+    }
+    if (d.instanceId)
+        linhas.push(`VM vista no Google Cloud: id ${d.instanceId}`);
+    if (d.instanceCreatedAt || d.docCreatedAt) {
+        linhas.push(`Criação da VM: ${d.instanceCreatedAt ?? '?'} · criação deste servidor: ${d.docCreatedAt ?? '?'} ` +
+            '(a VM do próprio servidor nasce segundos depois dele; diferença grande indica VM recriada)');
+    }
+    if (d.comandoConferencia)
+        linhas.push(`Para conferir (só leitura): ${d.comandoConferencia}`);
+    return linhas;
+}
 export async function runServersForceCleanup(id, opts) {
     if (!id || !/^[a-zA-Z0-9_-]{1,64}$/.test(id)) {
         log.error('serverId inválido. Uso: neetru servers force-cleanup <serverId> --reason="<motivo min 10 chars>"');
@@ -351,6 +418,16 @@ export async function runServersForceCleanup(id, opts) {
         log.error('--reason obrigatório com pelo menos 10 caracteres (paper-trail audit).');
         safeExit(1);
     }
+    // `--confirm-instance-id ""` (ou só espaços) é RECUSADO — não vira "flag não passada".
+    const confirmInstanceId = opts.confirmInstanceId === undefined ? undefined : opts.confirmInstanceId.trim();
+    if (confirmInstanceId !== undefined && !INSTANCE_ID_RE.test(confirmInstanceId)) {
+        const msg = '--confirm-instance-id deve ser o id numérico da VM no Google Cloud (o que você conferiu no comando de conferência).';
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, error: 'invalid_param', message: msg }));
+        else
+            log.error(msg);
+        safeExit(1);
+    }
     const token = await requireToken(opts.json);
     // Double-confirm (digitar o ID) — dry-run não aplica nada, então pula: nada
     // destrutivo acontece, não faz sentido travar numa confirmação interativa.
@@ -369,7 +446,11 @@ export async function runServersForceCleanup(id, opts) {
         }
         console.log(chalk.yellow.bold('\n⚠  FORCE-CLEANUP é IRREVERSÍVEL.'));
         console.log(chalk.dim('   Server stuck em provisioning/timeout que está bloqueando o pipeline.'));
-        console.log(chalk.dim('   Audit pesado + notification all staff serão gerados.\n'));
+        console.log(chalk.dim('   Audit pesado + notification all staff serão gerados.'));
+        if (confirmInstanceId) {
+            console.log(chalk.dim(`   VM a apagar: a instância de id ${confirmInstanceId}, conferida por você.`));
+        }
+        console.log('');
         const inquirer = await carregarInquirer();
         const ans = await inquirer.prompt([
             {
@@ -396,12 +477,28 @@ export async function runServersForceCleanup(id, opts) {
             body: {
                 reason: opts.reason.trim(),
                 confirm: 'I-UNDERSTAND-FORCE-CLEANUP',
+                ...(confirmInstanceId ? { confirmInstanceId } : {}),
             },
         });
         spinner?.stop();
     }
     catch (error) {
         spinner?.fail('Falha no force-cleanup.');
+        // core#732: a guarda de identidade da VM recusou — nada foi apagado. Mostra
+        // a mensagem do Core (id visto + comando de conferência) e o que fazer. Sem
+        // nova tentativa automática e sem montar o comando com o id: o operador
+        // confere e digita.
+        if (error instanceof CliApiError && FORCE_CLEANUP_IDENTITY_GUIDANCE[error.code]) {
+            const guidance = FORCE_CLEANUP_IDENTITY_GUIDANCE[error.code];
+            const details = forceCleanupIdentityDetails(error.details);
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, error: error.code, message: error.message, guidance, ...(details ? { details } : {}) }));
+            }
+            else {
+                log.error([error.message, ...forceCleanupIdentityDetailLines(details), guidance].join('\n  '));
+            }
+            safeExit(1);
+        }
         handleApiError(error, opts.json);
     }
     if (opts.json) {
@@ -414,6 +511,16 @@ export async function runServersForceCleanup(id, opts) {
     }
     log.success(`Server ${res.serverId} force-cleanup concluído.`);
     log.dim(`  Status anterior: ${res.previousStatus} (há ${res.ageMinutes}min)`);
+    if (res.vmIdentidade) {
+        const identidade = {
+            'confere:externalId': 'conferida pelo id registrado no servidor',
+            'confere:confirmacao': 'conferida pelo id que você confirmou',
+            'ausente:id_ausente': 'a VM registrada já não existia',
+            'ausente:nome_ausente': 'não havia VM com o nome do servidor',
+            'ausente:nome_de_outro_servidor': 'a VM com esse nome é de OUTRO servidor — não foi tocada',
+        };
+        log.dim(`  Identidade da VM: ${identidade[res.vmIdentidade] ?? res.vmIdentidade}`);
+    }
     if (res.vmDeleted) {
         log.dim('  VM GCP: deletada com sucesso.');
     }

package/dist/index.js

@@ -854,6 +854,7 @@ serversCmd
     .option('--yes', 'pula a confirmação interativa (modo script)')
     .option('--mfa-token <code>', 'código TOTP para step-up MFA (ou use `neetru auth mfa-session`)')
     .option('--dry-run', 'valida e retorna o efeito sem aplicar (sem MFA)')
+    .option('--confirm-instance-id <id>', 'id numérico da VM no Google Cloud que você conferiu — só quando o Core pedir (servidor sem o id da VM registrado)')
     .option('--json', 'saída em JSON')
     .action(async (id, opts) => {
     const { runServersForceCleanup } = await import('./commands/servers.js');
@@ -862,6 +863,7 @@ serversCmd
         yes: !!opts.yes,
         mfaToken: opts.mfaToken,
         dryRun: !!opts.dryRun,
+        confirmInstanceId: opts.confirmInstanceId,
         json: !!opts.json,
     });
 });
@@ -2281,6 +2283,60 @@ dbMoveCmd
         json: !!opts.json,
     });
 });
+// ── neetru db frontdoor ───────────────────────────────────────────────
+// Porta de entrada PRIVADA de um banco Postgres em VM para um app em OUTRA VM,
+// sem mover o banco (Core #727, bug_5c0e7738). O Core prepara o PgBouncer na
+// VM do banco, testa a partir da VM do app e na própria VM do banco, e só então
+// grava o novo endereço. `enable` repetido RETOMA a mesma operação.
+const dbFrontdoorCmd = dbCmd
+    .command('frontdoor')
+    .description('Porta de entrada privada do banco para um app em outra VM da rede interna (sem mover o banco)');
+dbFrontdoorCmd
+    .command('enable <dbId>')
+    .description('Ligar a porta de entrada para a VM do app (POST /api/cli/v1/db/[id]/frontdoor — exige MFA; repetir retoma)')
+    .requiredOption('--app-server <serverId>', 'VM onde o app roda ou vai rodar (recebe a liberação na rede interna)')
+    .requiredOption('--reason <text>', 'motivo (vai para o registro de auditoria)')
+    .option('--dry-run', 'só confere os requisitos (não altera nada, sem MFA)')
+    .option('-y, --yes', 'pula a confirmação interativa (modo script)')
+    .option('--mfa-token <code>', 'código TOTP step-up MFA (ou use `neetru auth mfa-session`)')
+    .option('--json', 'saída em JSON estruturado')
+    .action(async (dbId, opts) => {
+    const { runDbFrontdoorEnable } = await import('./commands/db-frontdoor.js');
+    await runDbFrontdoorEnable(dbId, {
+        appServer: opts.appServer,
+        reason: opts.reason,
+        dryRun: !!opts.dryRun,
+        yes: !!opts.yes,
+        mfaToken: opts.mfaToken,
+        json: !!opts.json,
+    });
+});
+dbFrontdoorCmd
+    .command('status <dbId>')
+    .description('Estado da porta de entrada e da última operação (GET /api/cli/v1/db/[id]/frontdoor)')
+    .option('--json', 'saída em JSON')
+    .action(async (dbId, opts) => {
+    const { runDbFrontdoorStatus } = await import('./commands/db-frontdoor.js');
+    await runDbFrontdoorStatus(dbId, { json: !!opts.json });
+});
+dbFrontdoorCmd
+    .command('disable <dbId>')
+    .description('Desligar a porta de entrada — o app volta ao endereço local da VM do banco (POST /api/cli/v1/db/[id]/frontdoor/disable — exige MFA)')
+    .requiredOption('--reason <text>', 'motivo (vai para o registro de auditoria)')
+    .option('--force', 'obrigatório para desligar uma porta ligada (o desfazer normal) ou quando não se sabe onde o app roda: o app volta ao endereço local da VM do banco e, se ele roda em outra VM, fica sem banco')
+    .option('-y, --yes', 'pula a confirmação interativa (modo script)')
+    .option('--mfa-token <code>', 'código TOTP step-up MFA (ou use `neetru auth mfa-session`)')
+    .option('--json', 'saída em JSON')
+    .action(async (dbId, opts) => {
+    const { runDbFrontdoorDisable } = await import('./commands/db-frontdoor.js');
+    await runDbFrontdoorDisable(dbId, {
+        reason: opts.reason,
+        force: !!opts.force,
+        yes: !!opts.yes,
+        mfaToken: opts.mfaToken,
+        json: !!opts.json,
+    });
+});
 // ── neetru db where ───────────────────────────────────────────────────
 // READ-ONLY: onde o banco de um produto VIVE hoje (VM/serverId + endpoint).
 // Complementa `neetru db status <dbId>` (que exige o dbId) aceitando --product.

package/dist/lib/api-client.d.ts

@@ -16,7 +16,14 @@ export declare class CliApiError extends Error {
      * por quem faz vários envios em sequência (ex.: `neetru docs sync`).
      */
     readonly retryAfterSeconds?: number;
-    constructor(status: number, code: string, message: string, correlationId?: string, retryAfterSeconds?: number);
+    /**
+     * Campos EXTRAS do erro canônico `{ error: { code, message, ...detalhes } }`
+     * (ex.: core#732 — `instanceId`, `instanceCreatedAt`, `docCreatedAt`,
+     * `outrosServidores`, `comandoConferencia` no force-cleanup). Ausente quando
+     * o corpo só traz `code`/`message`. Quem usa valida o tipo de cada campo.
+     */
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(status: number, code: string, message: string, correlationId?: string, retryAfterSeconds?: number, details?: Readonly<Record<string, unknown>>);
 }
 /** `Retry-After` em segundos (aceita número ou data HTTP). undefined se ausente/ilegível. */
 export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;

package/dist/lib/api-client.js

@@ -17,13 +17,22 @@ export class CliApiError extends Error {
      * por quem faz vários envios em sequência (ex.: `neetru docs sync`).
      */
     retryAfterSeconds;
-    constructor(status, code, message, correlationId, retryAfterSeconds) {
+    /**
+     * Campos EXTRAS do erro canônico `{ error: { code, message, ...detalhes } }`
+     * (ex.: core#732 — `instanceId`, `instanceCreatedAt`, `docCreatedAt`,
+     * `outrosServidores`, `comandoConferencia` no force-cleanup). Ausente quando
+     * o corpo só traz `code`/`message`. Quem usa valida o tipo de cada campo.
+     */
+    details;
+    constructor(status, code, message, correlationId, retryAfterSeconds, details) {
         super(message);
         this.name = 'CliApiError';
         this.status = status;
         this.code = code;
         this.correlationId = correlationId;
         this.retryAfterSeconds = retryAfterSeconds;
+        if (details && Object.keys(details).length > 0)
+            this.details = details;
     }
 }
 /** `Retry-After` em segundos (aceita número ou data HTTP). undefined se ausente/ilegível. */
@@ -182,6 +191,7 @@ export async function apiRequest(path, opts = {}) {
         const errBody = parsed;
         let code = `http_${response.status}`;
         let message = `Erro HTTP ${response.status}`;
+        let details;
         if (errBody?.error) {
             if (typeof errBody.error === 'string') {
                 // Formato RFC. Auditoria cli/v1 2026-09-29: o 401 do `requireCliAuth`
@@ -196,6 +206,12 @@ export async function apiRequest(path, opts = {}) {
                 // Formato interno Neetru
                 code = errBody.error.code ?? code;
                 message = errBody.error.message ?? message;
+                // Campos além de `code`/`message` (core#732): vão em `details`, crus.
+                const { code: _c, message: _m, ...extras } = errBody.error;
+                void _c;
+                void _m;
+                if (Object.keys(extras).length > 0)
+                    details = extras;
             }
         }
         else if (typeof parsed === 'string' && parsed.trim() !== '') {
@@ -242,7 +258,7 @@ export async function apiRequest(path, opts = {}) {
         }
         // LABS #6 (2026-09-28): captura o x-correlation-id do Core p/ o rodapé do erro.
         const correlationId = response.headers.get('x-correlation-id') ?? undefined;
-        throw new CliApiError(response.status, code, message, correlationId, parseRetryAfter(response.headers.get('retry-after')));
+        throw new CliApiError(response.status, code, message, correlationId, parseRetryAfter(response.headers.get('retry-after')), details);
     }
     return parsed;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neetru/cli",
-  "version": "2.32.1",
+  "version": "2.33.0",
   "type": "module",
   "description": "Neetru Developer Kit — scaffold, AI assistant, publish, build e deploy de produtos SaaS Neetru via Core (VM-based agents)",
   "keywords": [