@microteia/console 2.35.0 → 2.38.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,24 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.38.0] — 2026-11-05
+
+- feat(provision): deploys the Cloud Functions source an extension ships in its package, after the project operator approves that exact SHA-256. The Console recomputes the hash over what it writes (mismatch or a path outside the folder is refused), shows the files, the npm dependencies and the kind of each function, and asks; outside a terminal it holds the extension and prints `microteia provision --approve <id>@<hash>`. Approved source goes to `.microteia/packaged-functions/` and is read like any extension source (gate, duplicate names, dependencies); the copy to read before approving goes to `.microteia/packaged-review/` and is never mounted. A source already in the installation or the kernel wins over the packaged one.
+- feat(provision): approval belongs to the project — the hash approved on any active copy counts, and the stamp propagates it with the approver (`gcloud` account) to every copy with the same fingerprint. A held extension stays refused, so `--prune` keeps the previous version's functions running. With different versions across organizations, the newest one is deployed. `deploy` passes `--approve` through.
+
+#### [2.37.0] — 2026-11-05
+
+- feat(provision): records on each installed copy WHY an extension is still pending (`backendPending`), refused claims included — function source not found, claim refused (platform or shared name, misgated trigger), gate missing, deploy failed — with the functions involved, so the Extensions screen can say it. The stamp now writes `backendState` and clears `backendPending` in one PATCH, so the screen never shows an extension as running and as refused at once. A copy already stamped is left alone.
+
+#### [2.36.1] — 2026-11-05
+
+- fix(publish): resuming an interrupted kernel publish now takes the release out of draft (`gh release edit --draft=false`) before writing the catalog. `gh release create` with assets creates a draft, uploads, then publishes; a GitHub 502 in between left the draft, and the resume only re-uploaded the assets — so `kernel/index.json` promoted to `latest` a tarball that only the publisher could download. On a release already published the edit changes nothing.
+
+#### [2.36.0] — 2026-11-05
+
+- fix(environment): every command that acts on an installation (`readEnvironment`) refuses when the installation's `CONSOLE-VERSIONS.md` names a Console newer than the one running. An older Console rewrites `microteia.yaml` with only the sections it knows and replaces `CONSOLE-VERSIONS.md` and `MICROTEIA.md` with its own texts — nothing failed: a forgotten copy of Console 2.6.0, left in a folder of the installation, ran `unpack` there, the `login:` block disappeared and the Console history lost thirty versions without a word. No new field marks it, on purpose: an older Console would drop the field it does not know.
+- feat(version): `microteia --version` still answers in that case, and says which Console last updated the installation.
+
 #### [2.35.0] — 2026-11-02
 
 - feat(publish): the releases repository README links to the official documentation (https://doc.microteia.com), and `publish` rewrites it whenever it differs from the current text — after the catalog, warning instead of failing. It was written only when seeding an empty repository, so the README of an existing one stayed frozen at the text of its first `publish` and no change to it ever arrived. `publish --dry-run` says when it would be rewritten.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.35.0
+# Microteia Console 2.38.0
 
 Installs and updates Microteia in a Firebase project you own. It has no npm dependencies of its own —
 what it needs are command-line tools that are already on the machine, listed at the bottom.

package/lib/console/backendPending.d.ts

@@ -0,0 +1,36 @@
+import type { BackendPendingReason, PluginBackendRequirement } from '../kernel/backendShape.js';
+export interface PendingCause {
+    reason: BackendPendingReason;
+    functions: string[];
+}
+/** O que uma execução do `provision` sabe sobre as functions — a mesma conta que ele já faz. */
+export interface PendingInputs {
+    /**
+     * As extensões cuja fonte EMPACOTADA não subiu nesta execução: aguardando aprovação, ou recusada por
+     * não conferir. Vem antes de tudo — sem ela, a fonte "não existe" para o resto da conta, e o motivo
+     * mandaria procurar a pasta que o autor nunca precisou criar.
+     */
+    held?: ReadonlyMap<string, BackendPendingReason>;
+    /** O que existe para ser deployado: o pacote do kernel mais as fontes da instalação. */
+    deployable: ReadonlySet<string>;
+    /** Nome -> a extensão cuja reivindicação foi recusada por ele (plataforma, comum, portão trocado). */
+    refusedClaims: ReadonlyMap<string, string>;
+    /** As que estavam na fila e saíram dela por falta do portão. */
+    ungated: ReadonlySet<string>;
+    /** O que está no ar depois desta execução: aplicado antes, subido agora ou pulado por estar igual. */
+    satisfied: ReadonlySet<string>;
+}
+/**
+ * Por que ESTA extensão continua pendente, na ordem em que um autor teria de resolver.
+ *
+ * A ordem importa porque as causas se encadeiam: sem fonte não há portão a conferir, e sem portão não
+ * há deploy que possa falhar. Relatar a última em vez da primeira mandaria corrigir algo que nem chegou
+ * a ser tentado.
+ *
+ * Nulo quando nada falta — inclusive quando a extensão não exige function nenhuma: índice que não
+ * converge derruba o comando inteiro, e parâmetro vazio não impede o carimbo.
+ */
+export declare const pendingCauseOf: (claim: {
+    pluginId: string;
+    backend: PluginBackendRequirement;
+}, inputs: PendingInputs) => PendingCause | null;

package/lib/console/backendPending.js

@@ -0,0 +1,30 @@
+/**
+ * Por que ESTA extensão continua pendente, na ordem em que um autor teria de resolver.
+ *
+ * A ordem importa porque as causas se encadeiam: sem fonte não há portão a conferir, e sem portão não
+ * há deploy que possa falhar. Relatar a última em vez da primeira mandaria corrigir algo que nem chegou
+ * a ser tentado.
+ *
+ * Nulo quando nada falta — inclusive quando a extensão não exige function nenhuma: índice que não
+ * converge derruba o comando inteiro, e parâmetro vazio não impede o carimbo.
+ */
+export const pendingCauseOf = (claim, inputs) => {
+    const names = claim.backend.functions ?? [];
+    const pick = (test) => names.filter(test);
+    const held = inputs.held?.get(claim.pluginId);
+    if (held !== undefined && names.length > 0)
+        return { reason: held, functions: [...names] };
+    const missing = pick((name) => !inputs.deployable.has(name));
+    if (missing.length > 0)
+        return { reason: 'function-source-missing', functions: missing };
+    const refused = pick((name) => inputs.refusedClaims.get(name) === claim.pluginId);
+    if (refused.length > 0)
+        return { reason: 'function-claim-refused', functions: refused };
+    const ungated = pick((name) => inputs.ungated.has(name));
+    if (ungated.length > 0)
+        return { reason: 'gate-missing', functions: ungated };
+    const failed = pick((name) => !inputs.satisfied.has(name));
+    if (failed.length > 0)
+        return { reason: 'deploy-failed', functions: failed };
+    return null;
+};

package/lib/console/customFunctions.d.ts

@@ -73,6 +73,7 @@ export interface FunctionSource {
  * `export const x = onCall(...)` de quem declara no lugar, e o `export { a, b }` de quem reexporta.
  */
 export declare const exportedNames: (source: string) => string[];
+export declare const readFunctionSource: (path: string, label: string, slug: string, shared: boolean) => Promise<FunctionSource>;
 /** Onde o escritório pode ter escrito function, na ordem em que as mensagens as citam. */
 export declare const findFunctionSources: (root: string) => Promise<FunctionSource[]>;
 /**

package/lib/console/customFunctions.js

@@ -2,6 +2,7 @@ import { access, cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/pro
 import { basename, join } from 'node:path';
 import { callableFunctionNames, declaredParametersIn } from '../kernel/manifest.js';
 import { callableDeclarations, triggerDeclarations, unscopedDeclarations, } from './functionGate.js';
+import { packagedFunctionsPath, packagedLabel } from './packagedPaths.js';
 /**
  * As Cloud Functions do ESCRITÓRIO — as que ele escreve, não as do kernel.
  *
@@ -107,7 +108,7 @@ const readServes = async (path, label) => {
     }
     return serves;
 };
-const readSource = async (path, label, slug, shared) => {
+export const readFunctionSource = async (path, label, slug, shared) => {
     const entry = join(path, 'index.ts');
     if (!await exists(entry)) {
         throw new Error(`${label}/ has no index.ts.\n`
@@ -160,7 +161,7 @@ const readSource = async (path, label, slug, shared) => {
 export const findFunctionSources = async (root) => {
     const found = [];
     if (await exists(join(root, FUNCTIONS_DIR))) {
-        found.push(await readSource(join(root, FUNCTIONS_DIR), FUNCTIONS_DIR, 'shared', true));
+        found.push(await readFunctionSource(join(root, FUNCTIONS_DIR), FUNCTIONS_DIR, 'shared', true));
     }
     const extensions = join(root, EXTENSIONS_DIR);
     if (await exists(extensions)) {
@@ -170,7 +171,18 @@ export const findFunctionSources = async (root) => {
             const path = join(extensions, entry.name, FUNCTIONS_DIR);
             if (!await exists(path))
                 continue;
-            found.push(await readSource(path, `${EXTENSIONS_DIR}/${entry.name}/${FUNCTIONS_DIR}`, entry.name, false));
+            found.push(await readFunctionSource(path, `${EXTENSIONS_DIR}/${entry.name}/${FUNCTIONS_DIR}`, entry.name, false));
+        }
+    }
+    // A fonte que veio DENTRO do pacote de uma extensão, extraída pelo `provision` — só a que foi aprovada
+    // chega aqui. Entra como qualquer outra fonte de extensão: o portão, os nomes repetidos e as
+    // dependências são conferidos pelas mesmas funções, e é isso que dispensa uma segunda régua.
+    const packaged = packagedFunctionsPath(root);
+    if (await exists(packaged)) {
+        for (const entry of (await readdir(packaged, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            found.push(await readFunctionSource(join(packaged, entry.name), packagedLabel(entry.name), entry.name, false));
         }
     }
     return found;

package/lib/console/deploy.js

@@ -1,6 +1,7 @@
 import { writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { flagValue, hasFlag, requiredFlag } from '../shared/args.js';
+import { parseApprovals } from './packagedSources.js';
 import { run } from '../shared/run.js';
 import { blank, bullets, failure, heading, info, step, success, warn } from '../shared/ui.js';
 import { ENVIRONMENT_FILE, readEnvironment, writeEnvironment } from './environment.js';
@@ -305,6 +306,8 @@ export const deploy = async (args) => {
             refreshedStamps,
             environmentFile: file,
             environment: applied,
+            approvals: parseApprovals(flagValue(args, 'approve')),
+            interactive: process.stdin.isTTY === true,
         });
         if (provisioned.failed.length > 0) {
             failures.push(`${provisioned.failed.length} extension function(s): ${provisioned.failed.join(', ')}`);

package/lib/console/environment.d.ts

@@ -73,6 +73,28 @@ export interface Environment {
 export declare const ENVIRONMENT_FILE = "microteia.yaml";
 export declare const parseEnvironment: (source: string) => Environment;
 export declare const serializeEnvironment: (environment: Environment) => string;
+/**
+ * O Console que deixou esta instalação como ela está, quando ele é MAIS NOVO que o que está rodando.
+ *
+ * O sinal é o topo do `CONSOLE-VERSIONS.md` da raiz, que o `unpack` sobrepõe com o histórico do próprio
+ * binário — é, portanto, o último Console que trocou o kernel ali. Nenhum campo novo foi inventado para
+ * isso, e é deliberado: um Console antigo apagaria o campo que ele não conhece, que é o defeito inteiro.
+ *
+ * Sem o arquivo (instalação anterior a ele, ou apagado) não há o que comparar, e nada é recusado.
+ */
+export declare const newerConsoleThanThis: (root: string) => Promise<string | null>;
+/**
+ * Lê o `microteia.yaml` — e RECUSA quando um Console mais novo já passou por aqui.
+ *
+ * Um Console antigo reescreve este arquivo só com as seções que conhece, e sobrepõe o
+ * `CONSOLE-VERSIONS.md` e o `MICROTEIA.md` com os textos dele. Nada disso falha: a configuração que ele
+ * não conhece some, e o histórico volta meses, em silêncio. Foi o que aconteceu quando uma cópia
+ * esquecida do Console, numa pasta da instalação, rodou o `unpack` — o bloco `login:` desapareceu, e o
+ * histórico do Console perdeu trinta versões.
+ *
+ * A recusa fica aqui porque este é o primeiro passo de todo comando que AGE sobre a instalação, antes de
+ * qualquer escrita. O `--version` lê o arquivo por outro caminho, e continua respondendo.
+ */
 export declare const readEnvironment: (path: string) => Promise<Environment>;
 export declare const writeEnvironment: (path: string, environment: Environment) => Promise<void>;
 export declare const slug: (value: string) => string;

package/lib/console/environment.js

@@ -1,4 +1,8 @@
 import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { compareVersions } from '../kernel/manifest.js';
+import { CLI_VERSION } from '../shared/paths.js';
+import { CONSOLE_CHANGELOG, changelogVersions } from '../vendor/changelogs.js';
 export const ENVIRONMENT_FILE = 'microteia.yaml';
 /**
  * O YAML aqui é um SUBCONJUNTO deliberado: mapas de dois níveis com valores escalares, que é a forma
@@ -140,9 +144,36 @@ login:
   # To USE an extension inside the organization, install it from the Extensions screen instead.
   extensions: ${quote(environment.login.extensions)}
 `;
+/**
+ * O Console que deixou esta instalação como ela está, quando ele é MAIS NOVO que o que está rodando.
+ *
+ * O sinal é o topo do `CONSOLE-VERSIONS.md` da raiz, que o `unpack` sobrepõe com o histórico do próprio
+ * binário — é, portanto, o último Console que trocou o kernel ali. Nenhum campo novo foi inventado para
+ * isso, e é deliberado: um Console antigo apagaria o campo que ele não conhece, que é o defeito inteiro.
+ *
+ * Sem o arquivo (instalação anterior a ele, ou apagado) não há o que comparar, e nada é recusado.
+ */
+export const newerConsoleThanThis = async (root) => {
+    const contents = await readFile(join(root, CONSOLE_CHANGELOG), 'utf8').catch(() => null);
+    const latest = contents === null ? undefined : changelogVersions(contents)[0];
+    return latest !== undefined && compareVersions(latest, CLI_VERSION) > 0 ? latest : null;
+};
+/**
+ * Lê o `microteia.yaml` — e RECUSA quando um Console mais novo já passou por aqui.
+ *
+ * Um Console antigo reescreve este arquivo só com as seções que conhece, e sobrepõe o
+ * `CONSOLE-VERSIONS.md` e o `MICROTEIA.md` com os textos dele. Nada disso falha: a configuração que ele
+ * não conhece some, e o histórico volta meses, em silêncio. Foi o que aconteceu quando uma cópia
+ * esquecida do Console, numa pasta da instalação, rodou o `unpack` — o bloco `login:` desapareceu, e o
+ * histórico do Console perdeu trinta versões.
+ *
+ * A recusa fica aqui porque este é o primeiro passo de todo comando que AGE sobre a instalação, antes de
+ * qualquer escrita. O `--version` lê o arquivo por outro caminho, e continua respondendo.
+ */
 export const readEnvironment = async (path) => {
+    let environment;
     try {
-        return parseEnvironment(await readFile(path, 'utf8'));
+        environment = parseEnvironment(await readFile(path, 'utf8'));
     }
     catch (error) {
         if (error.code === 'ENOENT') {
@@ -150,6 +181,14 @@ export const readEnvironment = async (path) => {
         }
         throw error;
     }
+    const newer = await newerConsoleThanThis(dirname(path));
+    if (newer !== null) {
+        throw new Error(`This installation was last updated by Microteia Console ${newer}, and this is ${CLI_VERSION}.\n`
+            + `An older Console rewrites ${ENVIRONMENT_FILE} without the settings it does not know, and replaces\n`
+            + `${CONSOLE_CHANGELOG} with an older history, so it stops here. Update it with "npm i -g @microteia/console",\n`
+            + 'and check that the "microteia" you ran is that one, not a copy left in a folder.');
+    }
+    return environment;
 };
 export const writeEnvironment = async (path, environment) => {
     await writeFile(path, serializeEnvironment(environment));

package/lib/console/firestoreRest.d.ts

@@ -3,6 +3,12 @@ export interface FirestoreDocument {
     fields: Record<string, unknown>;
 }
 export declare const accessToken: () => Promise<string>;
+/**
+ * A conta do `gcloud` que está agindo — é quem fica registrado como tendo aprovado o código de uma
+ * extensão. Vazio vira "unknown" em vez de recusa: a aprovação já aconteceu, e perdê-la por não saber
+ * dizer o nome seria pior que gravá-la sem ele.
+ */
+export declare const activeAccount: () => Promise<string>;
 /** Um valor tipado da REST virando valor de JavaScript. Timestamp vira string ISO, que é o que basta. */
 export declare const decodeValue: (value: unknown) => unknown;
 export declare const decodeFields: (fields: Record<string, unknown>) => Record<string, unknown>;
@@ -30,6 +36,8 @@ export type FirestoreTypedValue = {
     mapValue: {
         fields: Record<string, FirestoreTypedValue>;
     };
+} | {
+    nullValue: null;
 };
 export declare const asString: (value: string) => FirestoreTypedValue;
 /**
@@ -49,6 +57,8 @@ export declare const asMap: (fields: Record<string, FirestoreTypedValue>) => Fir
  * também o que permite ordenar e comparar o campo no banco. A REST exige RFC 3339 em UTC, que é
  * exatamente o que `toISOString` devolve.
  */
+/** O campo continua no documento, valendo nulo — é o que o lado do kernel lê como "nada a dizer". */
+export declare const asNull: () => FirestoreTypedValue;
 export declare const asTimestamp: (value: Date) => FirestoreTypedValue;
 /**
  * Grava UM campo de mapa, com `updateMask` — o resto do documento não é tocado. É o que permite o

package/lib/console/firestoreRest.js

@@ -27,6 +27,20 @@ export const accessToken = async () => {
         throw new Error('gcloud returned an empty access token. Run: gcloud auth login');
     return cachedToken;
 };
+/**
+ * A conta do `gcloud` que está agindo — é quem fica registrado como tendo aprovado o código de uma
+ * extensão. Vazio vira "unknown" em vez de recusa: a aprovação já aconteceu, e perdê-la por não saber
+ * dizer o nome seria pior que gravá-la sem ele.
+ */
+export const activeAccount = async () => {
+    try {
+        const account = (await captureOrThrow(GCLOUD_BIN, ['config', 'get-value', 'account'])).trim();
+        return account === '' || account === '(unset)' ? 'unknown' : account;
+    }
+    catch {
+        return 'unknown';
+    }
+};
 /**
  * `X-Goog-User-Project` diz de qual projeto é a cota. Sem ele, uma credencial de usuário é recusada
  * com uma mensagem sobre "quota project" que não menciona o que fazer.
@@ -125,6 +139,8 @@ export const asMap = (fields) => ({ mapValue: { fields } });
  * também o que permite ordenar e comparar o campo no banco. A REST exige RFC 3339 em UTC, que é
  * exatamente o que `toISOString` devolve.
  */
+/** O campo continua no documento, valendo nulo — é o que o lado do kernel lê como "nada a dizer". */
+export const asNull = () => ({ nullValue: null });
 export const asTimestamp = (value) => ({ timestampValue: value.toISOString() });
 /**
  * Grava UM campo de mapa, com `updateMask` — o resto do documento não é tocado. É o que permite o

package/lib/console/packagedApproval.d.ts

@@ -0,0 +1,27 @@
+import type { PackagedClaim } from './packagedSources.js';
+export type HeldReason = 'awaiting-approval' | 'source-invalid';
+export interface PackagedSettlement {
+    /** As que não sobem nesta execução, e por quê — vira o motivo que a tela da extensão mostra. */
+    held: Map<string, HeldReason>;
+    /** Quem aprovou, para as aprovadas AGORA. As já aprovadas antes guardam o aprovador que tinham. */
+    approvedNow: Map<string, string>;
+    /** Quantas fontes foram extraídas para `.microteia/packaged-functions/`. */
+    extracted: number;
+}
+/**
+ * Decide, extrai e — quando ninguém respondeu antes — pergunta. Só a fonte APROVADA fica no disco
+ * quando esta função devolve, e é por isso que o resto do `provision` pode lê-la como qualquer outra:
+ * `findFunctionSources` só encontra o que passou por aqui.
+ *
+ * Fora de um terminal não há pergunta: a extensão fica pendente e o comando diz a linha exata que a
+ * aprova. Um `--yes` genérico foi recusado de propósito — ele aprovaria também a versão que chegar
+ * amanhã, sem ninguém ter lido.
+ */
+export declare const settlePackagedSources: (input: {
+    root: string;
+    projectId: string;
+    claims: PackagedClaim[];
+    provided: ReadonlySet<string>;
+    flags: ReadonlyMap<string, string>;
+    interactive: boolean;
+}) => Promise<PackagedSettlement>;

package/lib/console/packagedApproval.js

@@ -0,0 +1,109 @@
+import { relative } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { blank, bullets, failure, info, success, warn } from '../shared/ui.js';
+import { readFunctionSource } from './customFunctions.js';
+import { activeAccount } from './firestoreRest.js';
+import { packagedLabel, packagedSlug } from './packagedPaths.js';
+import { approvalFlag, declaredDependencies, decideWithoutAsking, writePackagedSource, } from './packagedSources.js';
+const kb = (text) => `${Math.max(1, Math.round(Buffer.byteLength(text, 'utf8') / 1024))} KB`;
+/**
+ * O que quem aprova precisa ver ANTES de dizer sim — e é a lista inteira, não um resumo: o que vai ao
+ * ar, com que dependência, e de que tipo é cada function. O tipo importa porque muda o alcance: uma
+ * callable responde a quem a chama; um gatilho age sozinho sobre os dados; uma agendada age sobre todos
+ * os escritórios do projeto.
+ */
+const describe = async (root, projectId, claim, path) => {
+    const slug = packagedSlug(claim.pluginId);
+    const source = await readFunctionSource(path, packagedLabel(slug), slug, false);
+    const kindOf = (name) => {
+        if (source.callables.includes(name))
+            return 'callable — answers whoever calls it';
+        const trigger = source.triggers.find((entry) => entry.name === name);
+        if (trigger !== undefined)
+            return `${trigger.trigger} — acts on its own when data changes`;
+        const unscoped = source.unscoped.find((entry) => entry.name === name);
+        if (unscoped !== undefined)
+            return `${unscoped.trigger} — acts on its own, for every organization`;
+        return 'not exported by its index.ts';
+    };
+    const dependencies = Object.entries(declaredDependencies(claim.source));
+    blank();
+    warn(`${claim.name} ${claim.version} (${claim.pluginId}) brings the source of its own Cloud Functions.`);
+    info(`  They run on the server with full access to every organization in ${projectId}.`);
+    info(`  sha-256: ${claim.source.hash}`);
+    info(`  read it in: ${relative(root, path)}/`);
+    info('  files:');
+    bullets(Object.keys(claim.source.files).sort().map((file) => `${file} (${kb(claim.source.files[file] ?? '')})`));
+    info('  npm dependencies it adds:');
+    bullets(dependencies.length === 0 ? ['none beyond the platform\'s own'] : dependencies.map(([name, range]) => `${name} ${range}`));
+    info('  functions:');
+    bullets(claim.functions.map((name) => `${name} — ${kindOf(name)}`));
+};
+const ask = async (question) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^(y|yes)$/i.test((await rl.question(question)).trim());
+    }
+    finally {
+        rl.close();
+    }
+};
+/**
+ * Decide, extrai e — quando ninguém respondeu antes — pergunta. Só a fonte APROVADA fica no disco
+ * quando esta função devolve, e é por isso que o resto do `provision` pode lê-la como qualquer outra:
+ * `findFunctionSources` só encontra o que passou por aqui.
+ *
+ * Fora de um terminal não há pergunta: a extensão fica pendente e o comando diz a linha exata que a
+ * aprova. Um `--yes` genérico foi recusado de propósito — ele aprovaria também a versão que chegar
+ * amanhã, sem ninguém ter lido.
+ */
+export const settlePackagedSources = async (input) => {
+    const settlement = { held: new Map(), approvedNow: new Map(), extracted: 0 };
+    let account;
+    const approver = async () => {
+        account ??= await activeAccount();
+        return account;
+    };
+    for (const claim of input.claims) {
+        const decision = decideWithoutAsking(claim, input.provided, input.flags);
+        if (decision?.kind === 'provided') {
+            info(`  ${claim.name}: using the source in this installation, not the copy in its package`);
+            continue;
+        }
+        if (decision?.kind === 'invalid') {
+            failure(`${claim.name}: the server code in its package cannot be used —`);
+            bullets(decision.problems);
+            info('  Install the extension again from a file its author built.');
+            settlement.held.set(claim.pluginId, 'source-invalid');
+            continue;
+        }
+        if (decision?.kind === 'approved') {
+            await writePackagedSource(input.root, claim);
+            settlement.extracted += 1;
+            if (decision.how === 'flag') {
+                settlement.approvedNow.set(claim.pluginId, await approver());
+                success(`${claim.name}: server code approved by --approve`);
+            }
+            continue;
+        }
+        if (decision?.kind === 'held') {
+            warn(`${claim.name}: the hash given to --approve is not the one in its package.`);
+            info(`  the package carries ${claim.source.hash} — read it before approving that one.`);
+            settlement.held.set(claim.pluginId, 'awaiting-approval');
+            continue;
+        }
+        const review = await writePackagedSource(input.root, claim, 'review');
+        await describe(input.root, input.projectId, claim, review);
+        if (input.interactive && await ask(`Approve this exact code for ${input.projectId}? [y/N] `)) {
+            await writePackagedSource(input.root, claim);
+            settlement.extracted += 1;
+            settlement.approvedNow.set(claim.pluginId, await approver());
+            success(`${claim.name}: server code approved`);
+            continue;
+        }
+        settlement.held.set(claim.pluginId, 'awaiting-approval');
+        info('  Not approved — the extension stays pending. To approve it without a prompt:');
+        bullets([`microteia provision ${approvalFlag(claim.pluginId, claim.source.hash)}`]);
+    }
+    return settlement;
+};

package/lib/console/packagedPaths.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Onde o Console extrai a fonte das Cloud Functions que veio DENTRO do pacote de uma extensão.
+ *
+ * Fica em `.microteia/` de propósito, e é a exceção que confirma a regra daquele diretório: nada ali é
+ * digitado por ninguém. É derivado do banco — o pacote instalado está em `installed_extensions` —, então
+ * o `unpack` apagar tudo não perde nada: o próximo `provision` extrai de novo. O que o autor escreve
+ * continua em `extensions/<pasta>/functions/`, e o Console nunca escreve lá.
+ */
+export declare const PACKAGED_FUNCTIONS_DIR = "packaged-functions";
+export declare const packagedFunctionsPath: (root: string) => string;
+/**
+ * Onde fica a cópia para LEITURA da fonte que ainda não foi aprovada. Separada de propósito: o que está
+ * em `packaged-functions/` é montado e sobe; o que está aqui só é lido por quem vai decidir. Uma pasta
+ * só obrigaria a apagar o código justamente quando alguém precisa lê-lo para aprovar com `--approve`.
+ */
+export declare const PACKAGED_REVIEW_DIR = "packaged-review";
+export declare const packagedReviewPath: (root: string) => string;
+export declare const packagedLabel: (slug: string) => string;
+/**
+ * O diretório da extensão. O prefixo impede colisão com `extensions/<pasta>`, que vai para o mesmo
+ * `custom/src/`: as duas origens viram irmãs ali dentro.
+ */
+export declare const packagedSlug: (pluginId: string) => string;

package/lib/console/packagedPaths.js

@@ -0,0 +1,25 @@
+import { join } from 'node:path';
+import { WORKSPACE_DIR } from './workspace.js';
+/**
+ * Onde o Console extrai a fonte das Cloud Functions que veio DENTRO do pacote de uma extensão.
+ *
+ * Fica em `.microteia/` de propósito, e é a exceção que confirma a regra daquele diretório: nada ali é
+ * digitado por ninguém. É derivado do banco — o pacote instalado está em `installed_extensions` —, então
+ * o `unpack` apagar tudo não perde nada: o próximo `provision` extrai de novo. O que o autor escreve
+ * continua em `extensions/<pasta>/functions/`, e o Console nunca escreve lá.
+ */
+export const PACKAGED_FUNCTIONS_DIR = 'packaged-functions';
+export const packagedFunctionsPath = (root) => join(root, WORKSPACE_DIR, PACKAGED_FUNCTIONS_DIR);
+/**
+ * Onde fica a cópia para LEITURA da fonte que ainda não foi aprovada. Separada de propósito: o que está
+ * em `packaged-functions/` é montado e sobe; o que está aqui só é lido por quem vai decidir. Uma pasta
+ * só obrigaria a apagar o código justamente quando alguém precisa lê-lo para aprovar com `--approve`.
+ */
+export const PACKAGED_REVIEW_DIR = 'packaged-review';
+export const packagedReviewPath = (root) => join(root, WORKSPACE_DIR, PACKAGED_REVIEW_DIR);
+export const packagedLabel = (slug) => `${WORKSPACE_DIR}/${PACKAGED_FUNCTIONS_DIR}/${slug}`;
+/**
+ * O diretório da extensão. O prefixo impede colisão com `extensions/<pasta>`, que vai para o mesmo
+ * `custom/src/`: as duas origens viram irmãs ali dentro.
+ */
+export const packagedSlug = (pluginId) => `package-${pluginId.replace(/[^a-zA-Z0-9]+/g, '-')}`;

package/lib/console/packagedSources.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A fonte das Cloud Functions que viaja no pacote — redeclarada do lado do Console pelo mesmo motivo de
+ * `backendShape.ts`: ele é publicado sem o `src/`. `packagedSources.test.ts` confere a serialização e a
+ * regra de caminho contra o kernel; separadas em silêncio, o hash que o build grava nunca conferiria
+ * aqui, e toda extensão com fonte seria recusada como adulterada.
+ */
+export interface PackagedSource {
+    files: Record<string, string>;
+    hash: string;
+}
+export declare const canonicalSource: (files: Record<string, string>) => string;
+export declare const hashSource: (files: Record<string, string>) => string;
+export declare const isSourcePath: (path: string) => boolean;
+/**
+ * A fonte como ela está gravada no pacote instalado. Leniente na LEITURA — a forma é cobrada por
+ * `sourceProblems` —, porque o que veio do banco é dado, e um dado torto tem de virar recusa explicada,
+ * não exceção.
+ */
+export declare const packagedSourceOf: (pkg: unknown) => PackagedSource | undefined;
+/**
+ * O que impede a fonte de ir ao disco. A conferência é feita AQUI, e não só na importação: o pacote
+ * chega ao Console pelo banco, e quem tem `extensions.manage` grava o documento instalado diretamente.
+ * O hash é recalculado sobre o conteúdo que vai ser gravado — é ele que se aprova.
+ */
+export declare const sourceProblems: (source: PackagedSource) => string[];
+/** `--approve id@hash,id@hash`. O hash INTEIRO: aprovar por prefixo é aprovar o que não se leu. */
+export declare const parseApprovals: (value: string | undefined) => Map<string, string>;
+export declare const approvalFlag: (pluginId: string, hash: string) => string;
+/** Uma extensão cuja fonte veio no pacote, com o que o projeto já aprovou dela. */
+export interface PackagedClaim {
+    pluginId: string;
+    name: string;
+    version: string;
+    functions: string[];
+    source: PackagedSource;
+    /** Os hashes aprovados em QUALQUER cópia instalada no projeto — a aprovação é do projeto. */
+    approvedHashes: ReadonlySet<string>;
+}
+export type PackagedDecision = {
+    kind: 'provided';
+} | {
+    kind: 'invalid';
+    problems: string[];
+} | {
+    kind: 'held';
+    flagMismatch: boolean;
+} | {
+    kind: 'approved';
+    how: 'recorded' | 'flag' | 'prompt';
+};
+/**
+ * A decisão que não depende de perguntar a ninguém. `null` é "pergunte": só então a revisão humana
+ * entra, e só para o que nenhuma outra resposta cobre.
+ *
+ * `provided` vem antes de tudo: se o pacote do kernel ou a instalação (`extensions/<pasta>/functions/`)
+ * já exporta um nome que a extensão reivindica, a fonte local vale — é onde o autor desenvolve, e é o
+ * caso da instalação que é a casa da fonte. As duas juntas seriam o mesmo nome exportado duas vezes,
+ * que a montagem recusa.
+ */
+export declare const decideWithoutAsking: (claim: PackagedClaim, provided: ReadonlySet<string>, flags: ReadonlyMap<string, string>) => PackagedDecision | null;
+/**
+ * Grava a fonte no diretório da extensão, dentro de `.microteia/packaged-functions/`.
+ *
+ * Cada caminho é conferido DE NOVO contra o diretório de destino depois de resolvido. `sourceProblems`
+ * já recusou `..` e caminho absoluto, mas é esta a linha que escreve no disco, e a regra dela não pode
+ * depender de alguém lembrar de chamar a outra antes.
+ */
+export declare const writePackagedSource: (root: string, claim: PackagedClaim, purpose?: "deploy" | "review") => Promise<string>;
+/** As duas pastas recomeçam a cada execução: o que vale é o que está instalado AGORA. */
+export declare const clearPackagedSources: (root: string) => Promise<void>;
+/** As dependências npm que a fonte declara — o que a aprovação precisa mostrar além do código. */
+export declare const declaredDependencies: (source: PackagedSource) => Record<string, string>;

package/lib/console/packagedSources.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { packagedFunctionsPath, packagedReviewPath, packagedSlug } from './packagedPaths.js';
+const SEPARATOR = '\u0000';
+export const canonicalSource = (files) => Object.keys(files)
+    .sort()
+    .map((path) => `${path}${SEPARATOR}${files[path]}`)
+    .join(SEPARATOR);
+export const hashSource = (files) => createHash('sha256').update(canonicalSource(files), 'utf8').digest('hex');
+const TEST_FILE = /\.(test|spec)\.ts$/;
+export const isSourcePath = (path) => {
+    if (path === '' || path.startsWith('/') || path.includes('\\'))
+        return false;
+    const segments = path.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..'))
+        return false;
+    if (segments.some((segment) => segment.startsWith('.') || segment === 'node_modules' || segment === '__tests__')) {
+        return false;
+    }
+    const name = segments.at(-1) ?? '';
+    if (TEST_FILE.test(name))
+        return false;
+    return name.endsWith('.ts') || name.endsWith('.json');
+};
+/**
+ * A fonte como ela está gravada no pacote instalado. Leniente na LEITURA — a forma é cobrada por
+ * `sourceProblems` —, porque o que veio do banco é dado, e um dado torto tem de virar recusa explicada,
+ * não exceção.
+ */
+export const packagedSourceOf = (pkg) => {
+    const raw = pkg?.backendSource;
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const { files, hash } = raw;
+    const entries = typeof files === 'object' && files !== null
+        ? Object.entries(files)
+            .filter((entry) => typeof entry[1] === 'string')
+        : [];
+    return { files: Object.fromEntries(entries), hash: typeof hash === 'string' ? hash : '' };
+};
+/**
+ * O que impede a fonte de ir ao disco. A conferência é feita AQUI, e não só na importação: o pacote
+ * chega ao Console pelo banco, e quem tem `extensions.manage` grava o documento instalado diretamente.
+ * O hash é recalculado sobre o conteúdo que vai ser gravado — é ele que se aprova.
+ */
+export const sourceProblems = (source) => {
+    const problems = [];
+    const bad = Object.keys(source.files).filter((path) => !isSourcePath(path));
+    if (bad.length > 0)
+        problems.push(`it names files that cannot be written: ${bad.join(', ')}`);
+    if (source.files['index.ts'] === undefined)
+        problems.push('it has no index.ts');
+    if (hashSource(source.files) !== source.hash) {
+        problems.push('its checksum does not match its content — it was changed after it was built');
+    }
+    return problems;
+};
+/** `--approve id@hash,id@hash`. O hash INTEIRO: aprovar por prefixo é aprovar o que não se leu. */
+export const parseApprovals = (value) => {
+    const approvals = new Map();
+    for (const part of (value ?? '').split(',').map((item) => item.trim()).filter(Boolean)) {
+        const at = part.lastIndexOf('@');
+        if (at <= 0 || at === part.length - 1) {
+            throw new Error(`--approve takes <extension id>@<sha-256>, and "${part}" is not that.`);
+        }
+        approvals.set(part.slice(0, at), part.slice(at + 1));
+    }
+    return approvals;
+};
+export const approvalFlag = (pluginId, hash) => `--approve ${pluginId}@${hash}`;
+/**
+ * A decisão que não depende de perguntar a ninguém. `null` é "pergunte": só então a revisão humana
+ * entra, e só para o que nenhuma outra resposta cobre.
+ *
+ * `provided` vem antes de tudo: se o pacote do kernel ou a instalação (`extensions/<pasta>/functions/`)
+ * já exporta um nome que a extensão reivindica, a fonte local vale — é onde o autor desenvolve, e é o
+ * caso da instalação que é a casa da fonte. As duas juntas seriam o mesmo nome exportado duas vezes,
+ * que a montagem recusa.
+ */
+export const decideWithoutAsking = (claim, provided, flags) => {
+    if (claim.functions.some((name) => provided.has(name)))
+        return { kind: 'provided' };
+    const problems = sourceProblems(claim.source);
+    if (problems.length > 0)
+        return { kind: 'invalid', problems };
+    if (claim.approvedHashes.has(claim.source.hash))
+        return { kind: 'approved', how: 'recorded' };
+    const flagged = flags.get(claim.pluginId);
+    if (flagged === claim.source.hash)
+        return { kind: 'approved', how: 'flag' };
+    if (flagged !== undefined)
+        return { kind: 'held', flagMismatch: true };
+    return null;
+};
+/**
+ * Grava a fonte no diretório da extensão, dentro de `.microteia/packaged-functions/`.
+ *
+ * Cada caminho é conferido DE NOVO contra o diretório de destino depois de resolvido. `sourceProblems`
+ * já recusou `..` e caminho absoluto, mas é esta a linha que escreve no disco, e a regra dela não pode
+ * depender de alguém lembrar de chamar a outra antes.
+ */
+export const writePackagedSource = async (root, claim, purpose = 'deploy') => {
+    const base = purpose === 'deploy' ? packagedFunctionsPath(root) : packagedReviewPath(root);
+    const target = join(base, packagedSlug(claim.pluginId));
+    await rm(target, { recursive: true, force: true });
+    for (const [path, content] of Object.entries(claim.source.files)) {
+        const file = resolve(target, path);
+        if (!file.startsWith(`${resolve(target)}${sep}`)) {
+            throw new Error(`${claim.name}: refusing to write "${path}" outside its folder.`);
+        }
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, content);
+    }
+    return target;
+};
+/** As duas pastas recomeçam a cada execução: o que vale é o que está instalado AGORA. */
+export const clearPackagedSources = async (root) => {
+    await rm(packagedFunctionsPath(root), { recursive: true, force: true });
+    await rm(packagedReviewPath(root), { recursive: true, force: true });
+};
+/** As dependências npm que a fonte declara — o que a aprovação precisa mostrar além do código. */
+export const declaredDependencies = (source) => {
+    const manifest = source.files['package.json'];
+    if (manifest === undefined)
+        return {};
+    try {
+        const parsed = JSON.parse(manifest);
+        return Object.fromEntries(Object.entries(parsed.dependencies ?? {})
+            .filter((entry) => typeof entry[1] === 'string'));
+    }
+    catch {
+        return {};
+    }
+};

package/lib/console/provision.d.ts

@@ -2,11 +2,17 @@ import type { ParsedArgs } from '../shared/args.js';
 import type { KernelManifest } from '../kernel/manifest.js';
 import type { BackendClaim } from '../kernel/backendShape.js';
 import type { Environment } from './environment.js';
+import type { PackagedSource } from './packagedSources.js';
 /** Uma exigência, o escritório que a instalou e o documento que carrega o estado dela. */
 export interface InstalledClaim extends BackendClaim {
     tenantId: string;
     documentPath: string;
     applied: boolean;
+    /** A fonte das functions que veio no pacote — ver `PackagedSource`. */
+    source?: PackagedSource;
+    /** O hash aprovado nesta cópia, e por quem. A aprovação é do projeto: vale a de qualquer cópia. */
+    approvedHash?: string;
+    approvedBy?: string;
 }
 /**
  * A varredura inteira, e não só o que ela achou.
@@ -62,6 +68,10 @@ export interface ProvisionOptions {
     refreshedStamps?: Map<string, string>;
     environmentFile: string;
     environment: Environment;
+    /** `--approve id@hash`: aprovação da fonte empacotada sem pergunta. Ver `settlePackagedSources`. */
+    approvals?: ReadonlyMap<string, string>;
+    /** Há um terminal para perguntar. Sem ele, o que não foi aprovado fica pendente. */
+    interactive?: boolean;
 }
 export interface ProvisionOutcome {
     deployed: string[];

package/lib/console/provision.js

@@ -14,7 +14,10 @@ import { deployFunctionsThatChanged } from './functionsUpToDate.js';
 import { clearRegionOrphans, listDeployedFunctions } from './regionOrphans.js';
 import { outdatedByStamp } from './functionsUpToDate.js';
 import { checkCallables, invokerGrantCommand } from './callableAccess.js';
-import { asString, asTimestamp, patchMapField } from './firestoreRest.js';
+import { asArray, asMap, asNull, asString, asTimestamp, patchFields, patchMapField } from './firestoreRest.js';
+import { pendingCauseOf } from './backendPending.js';
+import { settlePackagedSources } from './packagedApproval.js';
+import { clearPackagedSources, packagedSourceOf, parseApprovals } from './packagedSources.js';
 import { writeBackendResidue } from './backendResidue.js';
 import { listTenants, readInstalledExtensions } from './installedExtensions.js';
 import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js';
@@ -42,6 +45,7 @@ export const surveyInstallations = async (projectId) => {
             if (!hasBackendRequirement(backend))
                 continue;
             const state = extension.data.backendState;
+            const source = packagedSourceOf(extension.data.package);
             claims.push({
                 tenantId: extension.tenantId,
                 documentPath: extension.documentPath,
@@ -49,17 +53,32 @@ export const surveyInstallations = async (projectId) => {
                 name: extension.name,
                 version: extension.version,
                 backend: backend,
-                applied: state?.fingerprint === backendFingerprint(backend),
+                applied: state?.fingerprint === backendFingerprint(backend, source?.hash),
+                ...(source !== undefined ? { source } : {}),
+                ...(typeof state?.approvedHash === 'string' ? { approvedHash: state.approvedHash } : {}),
+                ...(typeof state?.approvedBy === 'string' ? { approvedBy: state.approvedBy } : {}),
             });
         }
     }
     return {
         tenants: tenants.length,
         extensions,
-        claims: claims.sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : 0)),
+        // A versão mais nova primeiro, dentro de cada extensão: é ela que `uniqueByPlugin` escolhe quando
+        // dois escritórios do projeto têm versões diferentes — e a function é uma só, do projeto.
+        claims: claims.sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : compareVersions(b.version, a.version))),
         installedIds,
     };
 };
+const compareVersions = (left, right) => {
+    const parts = (value) => value.split(/[.+-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+    const [a, b] = [parts(left), parts(right)];
+    for (let index = 0; index < 3; index += 1) {
+        const difference = (a.at(index) ?? 0) - (b.at(index) ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+};
 const uniqueByPlugin = (claims) => {
     const seen = new Set();
     return claims.filter((claim) => {
@@ -87,11 +106,30 @@ export const provisionBackend = async (options) => {
      * pacote (nem poderia: o kernel não sabe o que o escritório vai escrever), e a extensão inteira era
      * rejeitada com "this kernel package does not contain".
      */
-    const office = await readOfficeFunctions(root);
-    const deployable = [...manifest.functions, ...office.all];
     const survey = await surveyInstallations(projectId);
     const claims = survey.claims;
-    const missing = functionClaimProblems(claims, deployable);
+    /**
+     * A fonte que veio NO PACOTE é decidida antes de qualquer conta: o que for aprovado é extraído para
+     * `.microteia/packaged-functions/` e passa a ser lido como qualquer fonte da instalação. A leitura
+     * local vem antes porque é ela que decide a precedência — o que a instalação já escreve vale mais que
+     * a cópia empacotada.
+     */
+    await clearPackagedSources(root);
+    const local = await readOfficeFunctions(root);
+    const settlement = await settlePackagedSources({
+        root,
+        projectId,
+        claims: packagedClaimsOf(claims),
+        provided: new Set([...manifest.functions, ...local.all]),
+        flags: options.approvals ?? new Map(),
+        interactive: options.interactive === true,
+    });
+    const office = settlement.extracted > 0 ? await readOfficeFunctions(root) : local;
+    const deployable = [...manifest.functions, ...office.all];
+    // A retida não entra em "nowhere to be found": a fonte dela existe, só não foi aprovada — e a
+    // explicação certa já foi dada acima. Ela continua RECUSADA (logo abaixo), e é isso que protege do
+    // `--prune` a function de uma versão anterior que ainda está no ar.
+    const missing = functionClaimProblems(claims.filter((claim) => !settlement.held.has(claim.pluginId)), deployable);
     const overlapping = baselineClaimProblems(claims, manifest.baselineFunctions ?? []);
     // A comum do escritório tem o MESMO desfecho da function da plataforma, e por isso a mesma recusa: o
     // `deploy` a sobe sempre, então reivindicá-la não muda nada — até o dia em que `--prune` a apaga.
@@ -195,7 +233,24 @@ export const provisionBackend = async (options) => {
         for (const entry of misgated)
             rejected.add(entry.owner);
     }
+    for (const pluginId of settlement.held.keys())
+        rejected.add(pluginId);
     const valid = uniqueByPlugin(claims.filter((claim) => !rejected.has(claim.pluginId)));
+    /**
+     * Qual nome derrubou qual reivindicação — é o que vai para a tela da extensão no fim. As mensagens
+     * acima já dizem isto em prosa; o mapa existe porque a tela é lida por quem não tem o terminal.
+     */
+    const refusedClaims = new Map();
+    const baselineNames = new Set(manifest.baselineFunctions ?? []);
+    const sharedNames = new Set(office.shared);
+    for (const claim of claims) {
+        for (const name of claim.backend.functions ?? []) {
+            if (baselineNames.has(name) || sharedNames.has(name))
+                refusedClaims.set(name, claim.pluginId);
+        }
+    }
+    for (const entry of misgated)
+        refusedClaims.set(entry.name, entry.owner);
     /**
      * O nome que uma reivindicação RECUSADA carrega. Ele não entra em `wantedFunctions` — não há como
      * deployá-lo —, mas também não pode virar órfão: a extensão que o pede continua instalada, e o que
@@ -450,14 +505,30 @@ export const provisionBackend = async (options) => {
     // o mesmo que estar satisfeito. Deixá-lo de fora manteria a extensão "pendente" para sempre numa
     // instalação em que não falta nada.
     const deployedNow = new Set([...appliedNames, ...outcome.deployed, ...skippedNow]);
-    for (const claim of valid) {
-        const satisfied = (claim.backend.functions ?? []).every((name) => deployedNow.has(name));
-        if (satisfied) {
-            await stampApplied(projectId, claims, claim);
+    const validIds = new Set(valid.map((claim) => claim.pluginId));
+    const pendingInputs = {
+        held: settlement.held,
+        deployable: new Set(deployable),
+        refusedClaims,
+        ungated: new Set(refused),
+        satisfied: deployedNow,
+    };
+    // As RECUSADAS entram aqui também: nunca foram carimbadas, e eram justamente as que a tela mandava
+    // "rodar o provision" sem dizer que ele já tinha rodado e recusado.
+    for (const claim of uniqueByPlugin(claims)) {
+        const isValid = validIds.has(claim.pluginId);
+        // A regra do carimbo é a de sempre — tudo o que ela pede está no ar —, e vem ANTES do motivo: uma
+        // function que já estava aplicada continua satisfazendo a extensão mesmo que o portão dela tenha
+        // saído da fila nesta execução.
+        if (isValid && (claim.backend.functions ?? []).every((name) => deployedNow.has(name))) {
+            await stampApplied(projectId, claims, claim, settlement.approvedNow.get(claim.pluginId));
+            continue;
         }
-        else {
+        if (isValid)
             outcome.pending.push(claim);
-        }
+        const cause = pendingCauseOf(claim, pendingInputs);
+        if (cause !== null)
+            await recordPending(projectId, claims, claim, cause);
     }
     /**
      * O que o PROJETO roda, cruzado com o que esta instalação consegue justificar.
@@ -609,19 +680,76 @@ const checkNewCallables = async (known, deployed, projectId, region) => {
  * existe, existe para todo escritório que o instalou, e não só para aquele cuja cópia foi lida por
  * último.
  */
-const stampApplied = async (projectId, all, claim) => {
-    const fingerprint = backendFingerprint(claim.backend);
+const stampApplied = async (projectId, all, claim, approvedNowBy) => {
+    const fingerprint = claimFingerprint(claim);
     const appliedAt = new Date();
+    /**
+     * A aprovação vai junto do carimbo quando a fonte veio no pacote. Aprovada agora, o aprovador é quem
+     * rodou o comando; aprovada antes, é quem a aprovou numa das cópias — e é isso que a PROPAGA para a
+     * cópia nova de um escritório que reinstalou, sem perguntar de novo pelo código que já roda.
+     */
+    const hash = claim.source?.hash;
+    const approval = hash === undefined
+        ? {}
+        : {
+            approvedHash: asString(hash),
+            approvedBy: asString(approvedNowBy
+                ?? all.find((entry) => entry.pluginId === claim.pluginId && entry.approvedHash === hash)?.approvedBy
+                ?? 'unknown'),
+            approvedAt: asTimestamp(appliedAt),
+        };
     for (const copy of all.filter((entry) => entry.pluginId === claim.pluginId)) {
-        if (backendFingerprint(copy.backend) !== fingerprint)
+        if (claimFingerprint(copy) !== fingerprint)
             continue;
-        await patchMapField(projectId, copy.documentPath, 'backendState', {
-            fingerprint: asString(fingerprint),
-            appliedAt: asTimestamp(appliedAt),
+        // O motivo de uma recusa anterior sai na MESMA escrita: duas escritas abririam uma janela em que a
+        // tela mostra a extensão no ar e, ao mesmo tempo, por que ela não estava.
+        await patchFields(projectId, copy.documentPath, {
+            backendState: asMap({
+                fingerprint: asString(fingerprint),
+                appliedAt: asTimestamp(appliedAt),
+                ...approval,
+            }),
+            backendPending: asNull(),
         });
     }
     success(`${claim.name} is ready in ${projectId}`);
 };
+/** O fingerprint que a cópia exige — o mesmo que a tela calcula, com o hash da fonte quando ela existe. */
+const claimFingerprint = (claim) => backendFingerprint(claim.backend, claim.source?.hash);
+/**
+ * As extensões cuja fonte veio no pacote, uma por id — a escolhida por `uniqueByPlugin`, a versão mais
+ * nova —, com todos os hashes que QUALQUER cópia do projeto já aprovou.
+ */
+const packagedClaimsOf = (claims) => uniqueByPlugin(claims).flatMap((claim) => (claim.source === undefined ? [] : [{
+        pluginId: claim.pluginId,
+        name: claim.name,
+        version: claim.version,
+        functions: claim.backend.functions ?? [],
+        source: claim.source,
+        approvedHashes: new Set(claims
+            .filter((entry) => entry.pluginId === claim.pluginId && entry.approvedHash !== undefined)
+            .map((entry) => entry.approvedHash)),
+    }]));
+/**
+ * Grava na instalação POR QUE ela continua pendente — o que até aqui só o terminal sabia.
+ *
+ * Vai para toda cópia daquela extensão com a mesma exigência, pelo mesmo motivo do carimbo: a recusa é
+ * do projeto. A cópia já carimbada fica de fora: ela está no ar, e um motivo nela só confundiria.
+ */
+const recordPending = async (projectId, all, claim, cause) => {
+    const fingerprint = claimFingerprint(claim);
+    const recordedAt = new Date();
+    for (const copy of all.filter((entry) => entry.pluginId === claim.pluginId)) {
+        if (copy.applied || claimFingerprint(copy) !== fingerprint)
+            continue;
+        await patchMapField(projectId, copy.documentPath, 'backendPending', {
+            fingerprint: asString(fingerprint),
+            reason: asString(cause.reason),
+            functions: asArray(cause.functions.map(asString)),
+            recordedAt: asTimestamp(recordedAt),
+        });
+    }
+};
 /**
  * O que ninguém exige e mesmo assim NÃO é órfã.
  *
@@ -847,6 +975,8 @@ export const provision = async (args) => {
         all: hasFlag(args, 'all'),
         environmentFile: file,
         environment,
+        approvals: parseApprovals(flagValue(args, 'approve')),
+        interactive: process.stdin.isTTY === true,
     });
     blank();
     if (outcome.failed.length > 0) {

package/lib/console/versions.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { CLI_VERSION } from '../shared/paths.js';
-import { ENVIRONMENT_FILE, parseEnvironment } from './environment.js';
+import { ENVIRONMENT_FILE, newerConsoleThanThis, parseEnvironment } from './environment.js';
 import { installPath } from './unpack.js';
 /**
  * O que `microteia --version` responde.
@@ -59,6 +59,15 @@ export const versionReport = async (directory, newer) => {
         lines.push('');
         lines.push(`${inPlace} is in place and ${deployed} is what the project runs. "microteia deploy" publishes it.`);
     }
+    /**
+     * É a pergunta que se faz quando um comando recusa por isto — e a resposta tem de estar aqui, porque
+     * o `--version` é o único que continua rodando com o Console velho.
+     */
+    const newerConsole = await newerConsoleThanThis(directory);
+    if (newerConsole !== null) {
+        lines.push('');
+        lines.push(`Console ${newerConsole} last updated this installation. This one is older and will not act on it.`);
+    }
     /**
      * E o que o canal oferece, quando há canal alcançável. Vem por último porque é a única linha que
      * depende de rede: se ela faltar, tudo acima continua sendo a resposta inteira.

package/lib/kernel/backendShape.d.ts

@@ -33,7 +33,10 @@ export interface BackendClaim {
     backend: PluginBackendRequirement;
 }
 /** Cópia byte a byte de `domain/schema/plugin/backendRequirement.ts`. Ver o teste de paridade. */
-export declare const backendFingerprint: (backend?: PluginBackendRequirement) => string;
+export declare const backendFingerprint: (backend?: PluginBackendRequirement, sourceHash?: string) => string;
+/** Ver `BACKEND_PENDING_REASONS` no kernel — a paridade é cobrada por `backendShape.test.ts`. */
+export declare const BACKEND_PENDING_REASONS: readonly ["function-source-missing", "function-claim-refused", "gate-missing", "deploy-failed", "awaiting-approval", "source-invalid"];
+export type BackendPendingReason = typeof BACKEND_PENDING_REASONS[number];
 export declare const hasBackendRequirement: (backend?: PluginBackendRequirement) => boolean;
 /** Chave de identidade de um índice, para deduplicar e para casar reivindicação com a raiz. */
 export declare const indexKey: (index: FirestoreIndexSpec) => string;

package/lib/kernel/backendShape.js

@@ -4,11 +4,21 @@ const canonicalIndex = (index) => JSON.stringify([
     index.fields.map((field) => [field.fieldPath, field.order ?? '', field.arrayConfig ?? '']),
 ]);
 /** Cópia byte a byte de `domain/schema/plugin/backendRequirement.ts`. Ver o teste de paridade. */
-export const backendFingerprint = (backend) => JSON.stringify({
+export const backendFingerprint = (backend, sourceHash) => JSON.stringify({
     functions: [...(backend?.functions ?? [])].sort(),
     indexes: [...(backend?.indexes ?? [])].map(canonicalIndex).sort(),
     parameters: [...(backend?.parameters ?? [])].sort(),
+    ...(sourceHash !== undefined ? { code: sourceHash } : {}),
 });
+/** Ver `BACKEND_PENDING_REASONS` no kernel — a paridade é cobrada por `backendShape.test.ts`. */
+export const BACKEND_PENDING_REASONS = [
+    'function-source-missing',
+    'function-claim-refused',
+    'gate-missing',
+    'deploy-failed',
+    'awaiting-approval',
+    'source-invalid',
+];
 export const hasBackendRequirement = (backend) => (backend?.functions?.length ?? 0) > 0
     || (backend?.indexes?.length ?? 0) > 0
     || (backend?.parameters?.length ?? 0) > 0;

package/lib/shared/paths.d.ts

@@ -87,4 +87,4 @@ export declare const consoleRoot: string;
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export declare const CLI_VERSION = "2.35.0";
+export declare const CLI_VERSION = "2.38.0";

package/lib/shared/paths.js

@@ -94,4 +94,4 @@ export const consoleRoot = resolve(here, '..', '..');
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export const CLI_VERSION = '2.35.0';
+export const CLI_VERSION = '2.38.0';

package/lib/vendor/publish.js

@@ -247,6 +247,13 @@ const publishKernel = async (root, version, repo, dryRun) => {
                 'release', 'upload', tagOf(version), tarball, manifestPath,
                 '--repo', repo, '--clobber',
             ]);
+            /**
+             * O `gh release create` com arquivos cria o release como RASCUNHO, sobe os arquivos e só então o
+             * publica. Interrompido no meio — foi um 502 do GitHub —, sobra o rascunho, e o arquivo de um
+             * rascunho não se baixa sem credencial: retomar só subindo os arquivos gravava no catálogo um
+             * `latest` que nenhum escritório consegue instalar. Em release já publicado, isto não muda nada.
+             */
+            await run('gh', ['release', 'edit', tagOf(version), '--repo', repo, '--draft=false']);
         }
         else {
             pending(`creating ${tagOf(version)} in ${repo}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microteia/console",
-  "version": "2.35.0",
+  "version": "2.38.0",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",