primocode 11.0.0 → 11.2.0

package/lib/provider/local/provedor.js

@@ -0,0 +1,169 @@
+/**
+ * provedor.js — a chave da própria pessoa, e com qual IA ela fala.
+ *
+ *   "Fica batendo no limite. Coloca um comando /provider onde você seleciona
+ *    se é Gemini, ChatGPT etc., cola a key e ela roda local com a key
+ *    configurada." (23/09/2026)
+ *
+ * Com um provedor configurado (/api), o agente fala DIRETO com a API dele, daqui da
+ * máquina (lib/provider/local/motor.js). O servidor e a cota compartilhada saem do
+ * caminho: o limite passa a ser o da conta da pessoa.
+ *
+ * ── ONDE A CHAVE MORA ────────────────────────────────────────────────────
+ * Em `~/.primocode/provedor.json`, permissão 600. Não no config.json: esse é
+ * o arquivo que alguém abre para conferir um ajuste ou cola num chamado.
+ *
+ * ── O QUE NUNCA APARECE ──────────────────────────────────────────────────
+ * A chave inteira — nem ao listar, nem num erro. Mostra-se o começo e o fim,
+ * o bastante para reconhecer qual é.
+ *
+ * Todos falam o formato de chat da OpenAI (/chat/completions, tools, stream):
+ * é o que Gemini, Claude, Groq, OpenRouter e DeepSeek aceitam também. Um
+ * cliente só, e o provedor é só o endereço, o modelo e a chave.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ARQUIVO = () => path.join(os.homedir(), '.primocode', 'provedor.json');
+
+/* A ordem é a do menu. `modelos` é a preferência: ao colar a chave, fica o
+   primeiro que a conta da pessoa de fato tem (a lista vem da própria API). */
+const PROVEDORES = {
+    /* Sem chave: a assinatura que a pessoa já tem na ferramenta de fora, que
+       roda escondida como cérebro (lib/provider/local/motor-cli.js). */
+    'claude-code': {
+        nome: 'Claude Code',
+        cli: true,
+        modelos: ['opus'],
+        onde: 'https://docs.claude.com/claude-code',
+        dica: 'sua assinatura do Claude, sem chave',
+    },
+    codex: {
+        nome: 'Codex',
+        cli: true,
+        modelos: [''],
+        onde: 'https://github.com/openai/codex',
+        dica: 'sua assinatura do ChatGPT, sem chave',
+    },
+    gemini: {
+        nome: 'Gemini (Google)',
+        base: 'https://generativelanguage.googleapis.com/v1beta/openai',
+        modelos: ['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.0-flash'],
+        onde: 'https://aistudio.google.com/apikey',
+        dica: 'tem plano grátis',
+    },
+    chatgpt: {
+        nome: 'ChatGPT (OpenAI)',
+        base: 'https://api.openai.com/v1',
+        modelos: ['gpt-5-mini', 'gpt-5', 'gpt-4.1-mini', 'gpt-4o-mini'],
+        onde: 'https://platform.openai.com/api-keys',
+        dica: 'pago por uso',
+    },
+    claude: {
+        nome: 'Claude (Anthropic)',
+        base: 'https://api.anthropic.com/v1',
+        modelos: ['claude-sonnet-5', 'claude-haiku-4-5-20251001', 'claude-opus-5-5'],
+        onde: 'https://console.anthropic.com/settings/keys',
+        dica: 'pago por uso',
+    },
+    groq: {
+        nome: 'Groq',
+        base: 'https://api.groq.com/openai/v1',
+        modelos: ['openai/gpt-oss-120b', 'llama-3.3-70b-versatile', 'openai/gpt-oss-20b'],
+        onde: 'https://console.groq.com/keys',
+        dica: 'tem plano grátis, muito rápido',
+    },
+    openrouter: {
+        nome: 'OpenRouter',
+        base: 'https://openrouter.ai/api/v1',
+        modelos: ['openai/gpt-oss-120b', 'google/gemini-2.5-flash', 'anthropic/claude-sonnet-5'],
+        onde: 'https://openrouter.ai/keys',
+        dica: 'vários modelos numa chave só',
+    },
+    deepseek: {
+        nome: 'DeepSeek',
+        base: 'https://api.deepseek.com/v1',
+        modelos: ['deepseek-chat'],
+        onde: 'https://platform.deepseek.com/api_keys',
+        dica: 'barato',
+    },
+};
+
+/** A chave, irreconhecível para quem olha por cima do ombro. */
+function mascarar(chave) {
+    const k = String(chave || '');
+    if (k.length <= 10) return '••••';
+    return `${k.slice(0, 4)}…${k.slice(-4)}`;
+}
+
+let cache = null;
+let cacheMtime = 0;
+
+/** O provedor configurado, ou null (= segue pelo servidor, como sempre). */
+function atual() {
+    if (process.env.PRIMOCODE_SEM_PROVEDOR === '1') return null;
+    let st;
+    try { st = fs.statSync(ARQUIVO()); } catch { cache = null; return null; }
+    if (cache && st.mtimeMs === cacheMtime) return cache;
+    try {
+        const j = JSON.parse(fs.readFileSync(ARQUIVO(), 'utf8'));
+        const p = PROVEDORES[j.provedor];
+        cache = p && (j.chave || p.cli)
+            ? { id: j.provedor, nome: p.nome, cli: !!p.cli, base: j.base || p.base, modelo: j.modelo || p.modelos[0], chave: j.chave || '' }
+            : null;
+    } catch { cache = null; }
+    cacheMtime = st.mtimeMs;
+    return cache;
+}
+
+function salvar({ provedor, chave, modelo }) {
+    if (!PROVEDORES[provedor]) throw new Error(`provedor desconhecido: ${provedor}`);
+    const arq = ARQUIVO();
+    fs.mkdirSync(path.dirname(arq), { recursive: true });
+    fs.writeFileSync(arq, JSON.stringify({ provedor, chave: String(chave || '').trim(), modelo }, null, 2), { mode: 0o600 });
+    try { fs.chmodSync(arq, 0o600); } catch { /* Windows */ }
+    cache = null;
+    return atual();
+}
+
+function trocarModelo(modelo) {
+    const a = atual();
+    if (!a) return null;
+    return salvar({ provedor: a.id, chave: a.chave, modelo });
+}
+
+function desligar() {
+    try { fs.unlinkSync(ARQUIVO()); } catch { /* já não havia */ }
+    cache = null;
+}
+
+/** A chave colada serve? Pergunta a lista de modelos à própria API. */
+async function conferir(provedor, chave, { buscar = fetch } = {}) {
+    const p = PROVEDORES[provedor];
+    let r;
+    try {
+        r = await buscar(`${p.base}/models`, {
+            headers: { Authorization: `Bearer ${String(chave).trim()}` },
+            signal: AbortSignal.timeout(15000),
+        });
+    } catch (e) {
+        return { ok: false, error: `não consegui falar com ${p.nome}: ${e.message}` };
+    }
+    if (r.status === 401 || r.status === 403) return { ok: false, error: `${p.nome} recusou a chave (${r.status}). Confira se copiou inteira.` };
+    if (!r.ok) return { ok: false, error: `${p.nome} respondeu ${r.status} ao conferir a chave.` };
+    let lista = [];
+    try {
+        const j = await r.json();
+        lista = (j.data || j.models || []).map((m) => String(m.id || m.name || '').replace(/^models\//, '')).filter(Boolean);
+    } catch { /* sem lista: fica a preferência */ }
+    // Nenhum da preferência na lista (ou lista vazia): fica o primeiro dela, e
+    // `/api modelo <nome>` troca.
+    const modelo = p.modelos.find((m) => lista.includes(m)) || p.modelos[0];
+    return { ok: true, modelo, disponiveis: lista };
+}
+
+module.exports = { PROVEDORES, ARQUIVO, mascarar, atual, salvar, trocarModelo, desligar, conferir };

package/lib/publicar.js

@@ -17,7 +17,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
-const protecao = require('./protecao.js');
+const protecao = require('./permission/protecao.js');
 
 const SERVIDORES = /^(express|fastify|koa|hono|@hono\/node-server|restify|hapi|@hapi\/hapi)$/;
 const PULAR = new Set(['node_modules', '.git', '.vercel', '.next', '.primocode']);
@@ -36,7 +36,7 @@ function detectar(dir) {
     return { tipo: 'outro', pasta: '.', quem: 'um projeto que não consigo publicar sozinho' };
 }
 
-/** Quantos arquivos e bytes subiriam (sem o que a lib/protecao.js chama de segredo). */
+/** Quantos arquivos e bytes subiriam (sem o que a lib/permission/protecao.js chama de segredo). */
 function arquivosDoEnvio(dir) {
     let total = 0, bytes = 0;
     const andar = (d) => {

package/lib/qr.js

@@ -0,0 +1,209 @@
+// Gerador de QR code mínimo, sem dependência: modo byte (UTF-8), correção L ou M, versões 1 a 10
+// (até 213 bytes no M, 271 no L). Serve para o pareamento do celular (docs/estrutura.md, seção 15).
+// Algoritmo da ISO/IEC 18004: Reed-Solomon em GF(256), 8 máscaras, escolhe a de menor penalidade.
+'use strict';
+
+const ECC_POR_BLOCO = { L: [7, 10, 15, 20, 26, 18, 20, 24, 30, 18], M: [10, 16, 26, 18, 24, 16, 18, 22, 22, 26] };
+const NUM_BLOCOS = { L: [1, 1, 1, 1, 1, 2, 2, 2, 2, 4], M: [1, 1, 1, 2, 2, 4, 4, 4, 5, 5] };
+const FORMATO_ECC = { L: 1, M: 0 };
+const VERSAO_MAX = 10;
+
+/* Módulos que sobram para dados + correção, descontados padrões de função. */
+function modulosBrutos(v) {
+    let r = (16 * v + 128) * v + 64;
+    if (v >= 2) {
+        const n = Math.floor(v / 7) + 2;
+        r -= (25 * n - 10) * n - 55;
+        if (v >= 7) r -= 36;
+    }
+    return r;
+}
+const dadosCodewords = (v, ecc) => Math.floor(modulosBrutos(v) / 8) - ECC_POR_BLOCO[ecc][v - 1] * NUM_BLOCOS[ecc][v - 1];
+
+/* GF(256) com o polinômio 0x11D. */
+function multiplicar(x, y) {
+    let z = 0;
+    for (let i = 7; i >= 0; i--) { z = (z << 1) ^ ((z >>> 7) * 0x11D); z ^= ((y >>> i) & 1) * x; }
+    return z;
+}
+function divisor(grau) {
+    const r = new Array(grau).fill(0);
+    r[grau - 1] = 1;
+    let raiz = 1;
+    for (let i = 0; i < grau; i++) {
+        for (let j = 0; j < r.length; j++) { r[j] = multiplicar(r[j], raiz); if (j + 1 < r.length) r[j] ^= r[j + 1]; }
+        raiz = multiplicar(raiz, 2);
+    }
+    return r;
+}
+function resto(dados, div) {
+    const r = new Array(div.length).fill(0);
+    for (const b of dados) {
+        const f = b ^ r.shift();
+        r.push(0);
+        div.forEach((c, i) => { r[i] ^= multiplicar(c, f); });
+    }
+    return r;
+}
+
+function bitsDoTexto(bytes, v, ecc) {
+    const bits = [];
+    const poe = (valor, n) => { for (let i = n - 1; i >= 0; i--) bits.push((valor >>> i) & 1); };
+    poe(0b0100, 4);
+    poe(bytes.length, v <= 9 ? 8 : 16);
+    for (const b of bytes) poe(b, 8);
+    const cap = dadosCodewords(v, ecc) * 8;
+    poe(0, Math.min(4, cap - bits.length));
+    poe(0, (8 - (bits.length % 8)) % 8);
+    for (let pad = 0xEC; bits.length < cap; pad ^= 0xEC ^ 0x11) poe(pad, 8);
+    const cw = [];
+    for (let i = 0; i < bits.length; i += 8) cw.push(parseInt(bits.slice(i, i + 8).join(''), 2));
+    return cw;
+}
+
+/* Divide em blocos, calcula a correção e intercala. */
+function intercalar(dados, v, ecc) {
+    const nb = NUM_BLOCOS[ecc][v - 1];
+    const eb = ECC_POR_BLOCO[ecc][v - 1];
+    const total = Math.floor(modulosBrutos(v) / 8);
+    const curtos = nb - (total % nb);
+    const lenCurto = Math.floor(total / nb) - eb;
+    const div = divisor(eb);
+    const blocos = [];
+    for (let i = 0, k = 0; i < nb; i++) {
+        const dat = dados.slice(k, k + lenCurto + (i < curtos ? 0 : 1));
+        k += dat.length;
+        blocos.push({ dat, ecc: resto(dat, div) });
+    }
+    const out = [];
+    for (let i = 0; i <= lenCurto; i++) for (const b of blocos) if (i < b.dat.length) out.push(b.dat[i]);
+    for (let i = 0; i < eb; i++) for (const b of blocos) out.push(b.ecc[i]);
+    return out;
+}
+
+function criarMatriz(v) {
+    const n = v * 4 + 17;
+    return { n, m: Array.from({ length: n }, () => new Array(n).fill(false)), f: Array.from({ length: n }, () => new Array(n).fill(false)) };
+}
+function posAlinhamento(v) {
+    if (v === 1) return [];
+    const n = Math.floor(v / 7) + 2;
+    const passo = v === 32 ? 26 : Math.ceil((v * 4 + 4) / (n * 2 - 2)) * 2;
+    const r = [6];
+    for (let p = v * 4 + 10; r.length < n; p -= passo) r.splice(1, 0, p);
+    return r;
+}
+function desenharFuncoes(Q, v, ecc) {
+    const { n, m, f } = Q;
+    const set = (x, y, cor) => { if (x >= 0 && x < n && y >= 0 && y < n) { m[y][x] = cor; f[y][x] = true; } };
+    for (let i = 0; i < n; i++) { set(6, i, i % 2 === 0); set(i, 6, i % 2 === 0); }
+    const busca = (cx, cy) => { for (let dy = -4; dy <= 4; dy++) for (let dx = -4; dx <= 4; dx++) { const d = Math.max(Math.abs(dx), Math.abs(dy)); set(cx + dx, cy + dy, d !== 2 && d !== 4); } };
+    busca(3, 3); busca(n - 4, 3); busca(3, n - 4);
+    const al = posAlinhamento(v);
+    for (let i = 0; i < al.length; i++) for (let j = 0; j < al.length; j++) {
+        if ((i === 0 && j === 0) || (i === 0 && j === al.length - 1) || (i === al.length - 1 && j === 0)) continue;
+        for (let dy = -2; dy <= 2; dy++) for (let dx = -2; dx <= 2; dx++) set(al[i] + dx, al[j] + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+    }
+    desenharFormato(Q, ecc, 0);
+    if (v >= 7) {
+        let r = v;
+        for (let i = 0; i < 12; i++) r = (r << 1) ^ ((r >>> 11) * 0x1F25);
+        const bits = (v << 12) | r;
+        for (let i = 0; i < 18; i++) {
+            const cor = ((bits >>> i) & 1) !== 0;
+            const a = n - 11 + (i % 3);
+            const b = Math.floor(i / 3);
+            set(a, b, cor); set(b, a, cor);
+        }
+    }
+}
+function desenharFormato(Q, ecc, mascara) {
+    const { n, m, f } = Q;
+    const dados = (FORMATO_ECC[ecc] << 3) | mascara;
+    let r = dados;
+    for (let i = 0; i < 10; i++) r = (r << 1) ^ ((r >>> 9) * 0x537);
+    const bits = ((dados << 10) | r) ^ 0x5412;
+    const bit = (i) => ((bits >>> i) & 1) !== 0;
+    const set = (x, y, cor) => { m[y][x] = cor; f[y][x] = true; };
+    for (let i = 0; i <= 5; i++) set(8, i, bit(i));
+    set(8, 7, bit(6)); set(8, 8, bit(7)); set(7, 8, bit(8));
+    for (let i = 9; i < 15; i++) set(14 - i, 8, bit(i));
+    for (let i = 0; i < 8; i++) set(n - 1 - i, 8, bit(i));
+    for (let i = 8; i < 15; i++) set(8, n - 15 + i, bit(i));
+    set(8, n - 8, true);
+}
+function colocarDados(Q, cw) {
+    const { n, m, f } = Q;
+    let i = 0;
+    for (let direita = n - 1; direita >= 1; direita -= 2) {
+        if (direita === 6) direita = 5;
+        for (let vert = 0; vert < n; vert++) for (let j = 0; j < 2; j++) {
+            const x = direita - j;
+            const y = ((direita + 1) & 2) === 0 ? n - 1 - vert : vert;
+            if (!f[y][x] && i < cw.length * 8) { m[y][x] = ((cw[i >>> 3] >>> (7 - (i & 7))) & 1) !== 0; i++; }
+        }
+    }
+}
+const MASCARAS = [
+    (x, y) => (x + y) % 2 === 0, (x, y) => y % 2 === 0, (x) => x % 3 === 0, (x, y) => (x + y) % 3 === 0,
+    (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0, (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+    (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0, (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,
+];
+function aplicarMascara(Q, k) {
+    for (let y = 0; y < Q.n; y++) for (let x = 0; x < Q.n; x++) if (!Q.f[y][x] && MASCARAS[k](x, y)) Q.m[y][x] = !Q.m[y][x];
+}
+function penalidade(Q) {
+    const { n, m } = Q;
+    let p = 0;
+    const corrida = (linha) => {
+        let s = 0; let run = 1;
+        for (let i = 1; i <= linha.length; i++) {
+            if (i < linha.length && linha[i] === linha[i - 1]) run++;
+            else { if (run >= 5) s += run - 2; run = 1; }
+        }
+        const str = linha.map((b) => (b ? 1 : 0)).join('');
+        for (const pad of ['10111010000', '00001011101']) { let at = str.indexOf(pad); while (at >= 0) { s += 40; at = str.indexOf(pad, at + 1); } }
+        return s;
+    };
+    for (let y = 0; y < n; y++) p += corrida(m[y]);
+    for (let x = 0; x < n; x++) p += corrida(m.map((l) => l[x]));
+    for (let y = 0; y < n - 1; y++) for (let x = 0; x < n - 1; x++) if (m[y][x] === m[y][x + 1] && m[y][x] === m[y + 1][x] && m[y][x] === m[y + 1][x + 1]) p += 3;
+    const escuros = m.reduce((a, l) => a + l.filter(Boolean).length, 0);
+    p += (Math.ceil(Math.abs(escuros * 20 - n * n * 10) / (n * n)) - 1) * 10;
+    return p;
+}
+
+/* Devolve { tamanho, modulos: boolean[][], versao }. Lança se o texto não cabe. */
+function gerarQR(texto, { ecc = 'M' } = {}) {
+    if (!ECC_POR_BLOCO[ecc]) throw new Error('ecc deve ser L ou M');
+    const bytes = Buffer.from(String(texto), 'utf8');
+    let v = 1;
+    for (; v <= VERSAO_MAX; v++) {
+        const bitsLen = 4 + (v <= 9 ? 8 : 16) + bytes.length * 8;
+        if (bitsLen <= dadosCodewords(v, ecc) * 8) break;
+    }
+    if (v > VERSAO_MAX) throw new Error(`texto grande demais para o QR (${bytes.length} bytes; máximo ${dadosCodewords(VERSAO_MAX, ecc) - 3})`);
+    const cw = intercalar(bitsDoTexto(bytes, v, ecc), v, ecc);
+    let melhor = null;
+    for (let k = 0; k < 8; k++) {
+        const Q = criarMatriz(v);
+        desenharFuncoes(Q, v, ecc);
+        colocarDados(Q, cw);
+        aplicarMascara(Q, k);
+        desenharFormato(Q, ecc, k);
+        const pen = penalidade(Q);
+        if (!melhor || pen < melhor.pen) melhor = { pen, Q };
+    }
+    return { tamanho: melhor.Q.n, modulos: melhor.Q.m, versao: v };
+}
+
+/* SVG pronto (módulos escuros em `cor`, fundo em `fundo`, com a zona de silêncio de 4 módulos). */
+function qrSvg(texto, { ecc = 'M', cor = '#000', fundo = '#fff' } = {}) {
+    const { tamanho, modulos } = gerarQR(texto, { ecc });
+    const t = tamanho + 8;
+    let d = '';
+    for (let y = 0; y < tamanho; y++) for (let x = 0; x < tamanho; x++) if (modulos[y][x]) d += `M${x + 4} ${y + 4}h1v1h-1z`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${t} ${t}" shape-rendering="crispEdges" role="img" aria-label="QR code de pareamento"><rect width="${t}" height="${t}" fill="${fundo}"/><path d="${d}" fill="${cor}"/></svg>`;
+}
+
+module.exports = { gerarQR, qrSvg };

package/lib/registro.js

@@ -32,7 +32,7 @@
 
 'use strict';
 
-const { c, truncate, padRight } = require('./ui.js');
+const { c, truncate, padRight } = require('./tui/ui.js');
 
 /* Comando que é teste. Deliberadamente restrito: `npm run build` não é
    teste, e chamar de teste o que não é seria pior que não contar nada. */
@@ -231,7 +231,7 @@ function resumo(reg, { colunas = 80 } = {}) {
     return out.join('\n');
 }
 
-/** O teste que o PrimoCode rodou sozinho no fim da tarefa (lib/act.js conferirTestes): entra na mesma seção de prova
+/** O teste que o PrimoCode rodou sozinho no fim da tarefa (lib/session/runner/act.js conferirTestes): entra na mesma seção de prova
     do balanço, marcado, pra a pessoa ver que foi conferido mesmo quando o agente não rodou nada. */
 function anotarTeste(reg, { comando, ok, code, saida } = {}) {
     if (!reg || !comando || reg.testes.length >= 20) return reg;

package/lib/repeticao.js

@@ -145,7 +145,7 @@ function executou(registro, nome, args) {
 /**
  * O `ver` sem registrar nada: a chamada SERIA repetição? E a chave dela.
  *
- * Quem usa é o lote de leituras em paralelo (lib/act.js): ele roda antes do
+ * Quem usa é o lote de leituras em paralelo (lib/session/runner/act.js): ele roda antes do
  * laço, e o que o laço depois recusasse como repetido já teria rodado — e o
  * livro (lib/auditoria.js) anotava "recusada" para algo que aconteceu.
  */
@@ -195,7 +195,7 @@ function ver(registro, nome, args) {
 
     registro.vistos.set(chave, vezes);
     // `chave` volta para quem chamou guardar o resultado da leitura pela
-    // mesma época em que ela foi vista (lib/act.js, RELEITURA).
+    // mesma época em que ela foi vista (lib/session/runner/act.js, RELEITURA).
     if (vezes === 1) return { repetida: false, vezes, aviso: null, chave };
 
     return { repetida: true, vezes, aviso: aviso(nome, vezes, parecidaCom), chave };

package/lib/segredos.js

@@ -8,7 +8,7 @@
  * "Chave" é a senha que um serviço te dá (OpenAI, Stripe, banco de dados…). Quem escreve
  * isso no código e sobe pro GitHub perde a chave em minutos. Por isso o valor só entra pelo
  * teclado, escondido, e só vai para o `.env`; a tela mostra nome e nada mais.
- * O agente escrevendo no .env continua passando pelo portão de sempre (lib/perigo.js): este
+ * O agente escrevendo no .env continua passando pelo portão de sempre (lib/permission/perigo.js): este
  * módulo só serve ao /secrets, não abre porta nenhuma para ele.
  */
 
@@ -16,7 +16,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const protecao = require('./protecao.js');
+const protecao = require('./permission/protecao.js');
 
 const IGNORAR = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.primocode', '.venv', '__pycache__']);
 const CODIGO = /\.(m?js|cjs|jsx|tsx?|py|rb|php|go|html|vue|svelte)$/i;

package/lib/session/checkpoint-git.js

@@ -0,0 +1,221 @@
+/**
+ * checkpoint-git.js — a foto do projeto inteiro, num git que a pessoa não vê.
+ *
+ * O checkpoint por arquivo (lib/session/checkpoint.js) só enxerga o que passa por
+ * write_file/edit_file/multi_edit. Um `rm`, um `mv`, um `sed -i` ou um
+ * `npm run build` pelo run_shell mudam o disco sem avisar ninguém — e é
+ * justamente aí que "ele apagou meu site" acontece. A saída (a mesma ideia do
+ * Cline, escrita aqui do zero) é tirar uma foto do projeto INTEIRO no começo
+ * de cada pedido, num repositório git "sombra":
+ *
+ *   ~/.primocode/checkpoints/<projeto>-<hash>/git   ← GIT_DIR
+ *   a pasta do projeto                              ← GIT_WORK_TREE
+ *
+ * Por que um git à parte e não o .git do projeto: o repositório da pessoa é
+ * dela. Branch, index, stash e HEAD não podem mudar porque o agente tirou uma
+ * foto. Por isso TODO comando daqui passa --git-dir e --work-tree explícitos
+ * E as variáveis GIT_DIR/GIT_WORK_TREE — nunca há descoberta de repositório
+ * a partir da pasta, que acharia o .git da pessoa.
+ *
+ * Por que a config global fica de fora (GIT_CONFIG_GLOBAL=/dev/null): quem
+ * tem commit.gpgsign=true ou um core.hooksPath global veria o PrimoCode pedir
+ * a senha da chave GPG ou rodar hooks a cada pedido.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/** Maior que isso não entra na foto: vídeo exportado, dump de banco, zip.
+    A foto é de código e texto; binário grande encheria o disco da pessoa. */
+const LIMITE_BYTES = 20 * 1024 * 1024;
+/** Pasta com mais arquivos novos que isso na primeira foto provavelmente não
+    é um projeto (é Documentos, Downloads…). Aí fica o checkpoint por arquivo. */
+const MAX_ARQUIVOS = 20000;
+/** O pedido não pode ficar parado esperando a foto. */
+const TEMPO_MAXIMO_MS = 20000;
+
+/** O que nunca entra na foto, além do .gitignore do próprio projeto. São
+    coisas que se regeneram (npm install, build) ou que não são da pessoa. */
+const IGNORAR_SEMPRE = [
+    'node_modules/', '.git/', 'dist/', 'build/', '.next/', '.nuxt/', '.turbo/',
+    '.cache/', 'coverage/', '__pycache__/', '.venv/', 'venv/', '*.log', '.DS_Store',
+    // a cópia do banco e as travas do /lock moram na pasta: voltar a foto não pode levá-las embora
+    '.primocode/backup/', '.primocode/travados.json',
+];
+
+let _temGit = null;
+/** Detectado uma vez por processo; o teste zera com _reiniciar(). */
+function temGit() {
+    if (process.env.PRIMOCODE_SEM_GIT === '1') return false;
+    if (_temGit === null) {
+        try {
+            const r = spawnSync('git', ['--version'], { encoding: 'utf8', timeout: 5000, windowsHide: true });
+            _temGit = r.status === 0 && /git version/.test(r.stdout || '');
+        } catch { _temGit = false; }
+    }
+    return _temGit;
+}
+function _reiniciar() { _temGit = null; }
+
+/** O ambiente limpo: nenhuma variável GIT_* herdada (um hook que chamou o
+    PrimoCode deixaria GIT_INDEX_FILE apontando para o index da pessoa). */
+function ambiente(gitDir, workTree) {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env)) if (!/^GIT_/.test(k)) env[k] = v;
+    env.GIT_DIR = gitDir;
+    env.GIT_WORK_TREE = workTree;
+    env.GIT_CONFIG_NOSYSTEM = '1';
+    env.GIT_CONFIG_GLOBAL = os.devNull;
+    env.GIT_TERMINAL_PROMPT = '0';
+    env.GIT_OPTIONAL_LOCKS = '0';
+    return env;
+}
+
+function git(gitDir, workTree, args, { input } = {}) {
+    const r = spawnSync('git', [
+        `--git-dir=${gitDir}`, `--work-tree=${workTree}`, '--literal-pathspecs',
+        '-c', 'core.autocrlf=false', '-c', 'core.quotepath=false', '-c', 'core.fsmonitor=false',
+        '-c', 'commit.gpgsign=false', '-c', `core.hooksPath=${path.join(gitDir, 'sem-hooks')}`,
+        '-c', 'user.name=PrimoCode', '-c', 'user.email=desfazer@primocode.local',
+        '-c', 'advice.addEmbeddedRepo=false', '-c', 'core.safecrlf=false',
+        ...args,
+    ], { cwd: workTree, env: ambiente(gitDir, workTree), encoding: 'utf8', input,
+        timeout: TEMPO_MAXIMO_MS, maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+    if (r.error) throw r.error;
+    if (r.status !== 0) throw new Error((r.stderr || '').trim() || `git ${args[0]} saiu com ${r.status}`);
+    return r.stdout;
+}
+
+/** Um processo morto no meio (timeout, Ctrl+C) deixa o index.lock para trás,
+    e dali em diante TODA foto falharia. Lock velho é lixo: sai. */
+function destravar(gitDir) {
+    const lock = path.join(gitDir, 'index.lock');
+    try { if (Date.now() - fs.statSync(lock).mtimeMs > 60000) fs.rmSync(lock, { force: true }); } catch {}
+}
+
+/** Cria o repositório sombra na primeira vez. Devolve false quando a pasta
+    não serve para foto (grande demais). */
+function preparar(gitDir, workTree) {
+    if (fs.existsSync(path.join(gitDir, 'HEAD'))) return true;
+    fs.mkdirSync(gitDir, { recursive: true });
+    git(gitDir, workTree, ['init', '-q']);
+    fs.mkdirSync(path.join(gitDir, 'info'), { recursive: true });
+    fs.writeFileSync(path.join(gitDir, 'info', 'exclude'),
+        '# o que o /undo nunca fotografa (o .gitignore do projeto vale também)\n'
+        + IGNORAR_SEMPRE.join('\n') + '\n');
+    // Os hooks de exemplo do template não rodam, mas não precisam ficar lá.
+    fs.rmSync(path.join(gitDir, 'hooks'), { recursive: true, force: true });
+    return true;
+}
+
+/** Arquivo novo grande demais vai para o exclude ANTES do add: o git não
+    sabe ignorar por tamanho, então listamos os não rastreados e medimos. */
+function excluirGrandes(gitDir, workTree, { primeira } = {}) {
+    const novos = git(gitDir, workTree, ['ls-files', '-z', '--others', '--exclude-standard']).split('\0').filter(Boolean);
+    if (primeira && novos.length > MAX_ARQUIVOS) return false;
+    const grandes = [];
+    for (const rel of novos) {
+        try { if (fs.statSync(path.join(workTree, rel)).size > LIMITE_BYTES) grandes.push(rel); } catch {}
+    }
+    if (grandes.length) {
+        // Âncora com "/" e caracteres especiais escapados: o padrão pega só ESTE arquivo.
+        const linhas = grandes.map((r) => '/' + r.replace(/([\\*?[\]!# ])/g, '\\$1'));
+        fs.appendFileSync(path.join(gitDir, 'info', 'exclude'), linhas.join('\n') + '\n');
+    }
+    return true;
+}
+
+/** Põe o estado atual do disco no index da sombra (só no dela). */
+function registrarEstado(gitDir, workTree, opcoes) {
+    destravar(gitDir);
+    if (excluirGrandes(gitDir, workTree, opcoes) === false) return false;
+    git(gitDir, workTree, ['add', '-A', '--ignore-errors', '--', '.']);
+    return true;
+}
+
+/** A foto do começo do pedido. Devolve o sha, ou null quando não deu (sem
+    git, pasta grande demais, erro) — quem chama cai no checkpoint por arquivo. */
+function fotografar(gitDir, workTree, mensagem) {
+    const primeira = !fs.existsSync(path.join(gitDir, 'HEAD'));
+    if (!preparar(gitDir, workTree)) return null;
+    if (!registrarEstado(gitDir, workTree, { primeira })) {
+        // Não é projeto: a sombra criada agora não serve e não pode ficar.
+        if (primeira) fs.rmSync(gitDir, { recursive: true, force: true });
+        return null;
+    }
+    git(gitDir, workTree, ['commit', '-q', '--allow-empty', '--no-verify', '-m', String(mensagem || 'pedido').slice(0, 500) || 'pedido']);
+    return git(gitDir, workTree, ['rev-parse', 'HEAD']).trim();
+}
+
+/** O que mudou da foto `sha` até o disco de agora: [{ rel, status }] com
+    status A (nasceu depois), M (mudou) ou D (sumiu). Renomear aparece como
+    D + A de propósito (--no-renames): desfazer é recriar um e apagar o outro. */
+function mudancas(gitDir, workTree, sha) {
+    registrarEstado(gitDir, workTree);
+    const saida = git(gitDir, workTree, ['diff', '--cached', '--no-renames', '--name-status', '-z', sha, '--']);
+    const partes = saida.split('\0').filter(Boolean);
+    const lista = [];
+    for (let i = 0; i + 1 < partes.length; i += 2) {
+        const status = partes[i][0] === 'T' ? 'M' : partes[i][0];
+        lista.push({ rel: partes[i + 1], status });
+    }
+    return lista;
+}
+
+/** Tira pastas que ficaram vazias depois de apagar o que nasceu no pedido
+    (quem criou `css/novo.css` espera que `css/` suma junto). Para na raiz. */
+function podarVazias(workTree, rel) {
+    let d = path.dirname(path.join(workTree, rel));
+    const raiz = path.resolve(workTree);
+    while (d.startsWith(raiz + path.sep)) {
+        try { if (fs.readdirSync(d).length) break; fs.rmdirSync(d); } catch { break; }
+        d = path.dirname(d);
+    }
+}
+
+/** Volta o disco para a foto `sha`: o que mudou ou sumiu volta, o que nasceu
+    depois sai. Só se apaga o que a sombra VIU nascer — arquivo ignorado
+    (node_modules, .gitignore, grande demais) nunca entra no index, então nunca
+    aparece como A, então nunca é apagado. Com `so`, volta só aqueles. */
+function restaurar(gitDir, workTree, sha, { so = null } = {}) {
+    const feitos = [];
+    // `so`: só estes caminhos relativos (o "/desfazer fora": o resto do pedido fica)
+    const lista = mudancas(gitDir, workTree, sha).filter((m) => !so || so.has(m.rel));
+    const statusDe = new Map(lista.map((m) => [m.rel, m.status]));
+    const voltar = lista.filter((m) => m.status !== 'A').map((m) => m.rel);
+    // Em lotes: um projeto com milhares de mudanças estouraria a linha de comando.
+    for (let i = 0; i < voltar.length; i += 200) {
+        const lote = voltar.slice(i, i + 200);
+        try {
+            git(gitDir, workTree, ['checkout', sha, '--', ...lote]);
+            for (const rel of lote) feitos.push({ rel, acao: statusDe.get(rel) === 'D' ? 'recriado' : 'restaurado' });
+        } catch (e) { for (const rel of lote) feitos.push({ rel, acao: 'falhou', erro: e.message }); }
+    }
+    for (const m of lista.filter((x) => x.status === 'A')) {
+        try {
+            fs.rmSync(path.join(workTree, m.rel), { force: true });
+            podarVazias(workTree, m.rel);
+            feitos.push({ rel: m.rel, acao: 'apagado' });
+        } catch (e) { feitos.push({ rel: m.rel, acao: 'falhou', erro: e.message }); }
+    }
+    // O index da sombra volta a espelhar o disco, para a próxima comparação.
+    try { registrarEstado(gitDir, workTree); } catch {}
+    return feitos;
+}
+
+/** O arquivo está fora da foto (ignorado pelas regras)? Aí o checkpoint por
+    arquivo cobre — editar `dist/app.js` continua tendo volta. */
+function ignorado(gitDir, workTree, abs) {
+    const rel = path.relative(workTree, abs);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return true;
+    const r = spawnSync('git', [`--git-dir=${gitDir}`, `--work-tree=${workTree}`, 'check-ignore', '-q', '--no-index', '--', rel],
+        { cwd: workTree, env: ambiente(gitDir, workTree), timeout: 5000, windowsHide: true });
+    return r.status === 0;
+}
+
+module.exports = { IGNORAR_SEMPRE, LIMITE_BYTES, MAX_ARQUIVOS, temGit, _reiniciar,
+    fotografar, mudancas, restaurar, ignorado };