primocode 9.8.0-beta.2 → 9.8.0-beta.21

package/lib/browser.js

@@ -177,6 +177,16 @@ function httpPutJson(url, timeoutMs = 3000) {
 
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 
+/* O Chrome NUNCA mexe no Keychain do Mac (nem no cofre de senhas do Linux).
+ *   "Para de fazer coisas de tentar armazenar chave no Chrome, eu apaguei o
+ *    Chrome." (24/09/2026)
+ * Cada perfil novo do PrimoCode (o do agente, o revisor escondido, a janela
+ * do /rc e do /ide) fazia o Chrome pedir o "Chrome Safe Storage" ao sistema —
+ * uma janela de senha do Mac, do nada, várias vezes. O PrimoCode não guarda
+ * senha em navegador nenhum: estas duas flags fazem o Chrome usar um cofre de
+ * mentira e texto simples no próprio perfil, sem tocar no do sistema. */
+const SEM_KEYCHAIN = ['--use-mock-keychain', '--password-store=basic'];
+
 // ---- WebSocket client mínimo (RFC 6455) para CDP ----------------
 // Suficiente pra CDP (mensagens curtas, texto UTF-8, um cliente por página).
 class MiniWebSocket {
@@ -393,6 +403,7 @@ async function ensureChromeRunning() {
     const args = [
         `--remote-debugging-port=${DEBUG_PORT}`,
         `--user-data-dir=${PROFILE_DIR}`,
+        ...SEM_KEYCHAIN,
         '--no-first-run',
         '--no-default-browser-check',
         '--disable-features=Translate',
@@ -810,6 +821,7 @@ function close() {
 let PORTA_REVISOR = Number(process.env.PRIMOCODE_CDP_PORT_REVISOR || 0);
 let perfilRevisor = null;
 let revisorChild = null;
+let saidaRegistrada = false;
 
 function lerPortaDoPerfil(perfil) {
     try {
@@ -819,7 +831,20 @@ function lerPortaDoPerfil(perfil) {
     } catch { return 0; }
 }
 
-async function subirRevisor() {
+/* Quem está subindo o revisor AGORA. O agente liga o navegador escondido
+   adiantado, quando escreve a primeira página (lib/act.js), e a conferência
+   do "pronto" chama isto de novo — às vezes com o primeiro ainda subindo.
+   Sem esta promessa em comum, a segunda chamada via PORTA_REVISOR zerada e
+   lançava um SEGUNDO Chrome, que ficava órfão. */
+let subindoRevisor = null;
+
+function subirRevisor() {
+    if (subindoRevisor) return subindoRevisor;
+    subindoRevisor = _subirRevisor().finally(() => { subindoRevisor = null; });
+    return subindoRevisor;
+}
+
+async function _subirRevisor() {
     if (PORTA_REVISOR) {
         try {
             const v = await httpGetJson(`http://127.0.0.1:${PORTA_REVISOR}/json/version`, 800);
@@ -839,6 +864,7 @@ async function subirRevisor() {
         // Zero: o Chrome escolhe uma porta livre e escreve qual no perfil.
         `--remote-debugging-port=${process.env.PRIMOCODE_CDP_PORT_REVISOR || 0}`,
         `--user-data-dir=${perfilRevisor}`,
+        ...SEM_KEYCHAIN,
         // Sempre invisível: é o pedido, e é o que separa este do navegador da
         // pessoa. Não há variável para ligar a janela aqui de propósito.
         '--headless=new', '--disable-gpu', '--disable-dev-shm-usage',
@@ -868,6 +894,17 @@ async function subirRevisor() {
     revisorChild = spawn(chrome, args, { detached: true, stdio: 'ignore' });
     revisorChild.on('error', () => {});
     revisorChild.unref();
+    /* O REVISOR MORRE COM O PROCESSO. Ele é `detached` + `unref` para não
+       segurar o CLI de pé — e por isso mesmo sobrevivia a ele: só o pipeline
+       (construir_app) chamava fecharRevisor, e toda sessão que conferiu uma
+       página deixava um Chrome invisível para trás. Medido em 24/09 nesta
+       máquina: 7 revisores órfãos somando ~2 GB de memória, um deles com 3
+       minutos de CPU. É o tipo de lentidão que a pessoa sente no computador
+       inteiro e não liga ao PrimoCode. */
+    if (!saidaRegistrada) {
+        saidaRegistrada = true;
+        process.on('exit', () => { try { fecharRevisor(); } catch { /* saindo */ } });
+    }
 
     const prazo = Date.now() + 15000;
     while (Date.now() < prazo) {
@@ -1098,6 +1135,44 @@ async function abrirEscondido(url) {
 /* O revisor é ferramenta de uma tarefa, não um processo que fica. Deixá-lo de
    pé come memória até a pessoa desligar o computador, e ele não é o navegador
    dela — ninguém sentiria falta nem saberia que existe para fechar. */
+/* LIGAR O REVISOR ANTES DA HORA — e não só ligar: navegar uma vez.
+ *
+ * Medido em 24/09, cada fase da conferência num Chrome recém-aberto:
+ * subir 313ms · abrir aba 24ms · canal 29ms · PRIMEIRA navegação 3.019ms ·
+ * assentar 1.200ms. Na segunda página, no mesmo Chrome, a navegação levou
+ * 4ms. O caro não é o processo, é a primeira ida à rede (o Chrome sobe o
+ * serviço de rede e o primeiro renderizador nela) — navegar para about:blank
+ * ou data: não aquece isso (a conferência seguinte continuou em ~2,1s);
+ * navegar para um http local aquece (caiu para 1.240ms, que é o assentar).
+ *
+ * Por isso isto abre uma aba num servidor de uma linha, em 127.0.0.1, e fecha.
+ * Uma vez por navegador: depois da primeira, não há o que aquecer. Nunca
+ * rejeita — aquecer é atalho, e quem confere de verdade tenta de novo e diz
+ * o que houve. */
+let aquecido = null;   // a porta do revisor que já foi aquecido
+let aquecendo = null;
+function aquecerRevisor() {
+    if (aquecendo) return aquecendo;
+    aquecendo = (async () => {
+        await subirRevisor();
+        if (aquecido && aquecido === PORTA_REVISOR) return true;
+        const srv = http.createServer((req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end('<!doctype html><title>.</title>');
+        });
+        try {
+            await new Promise((ok, falhou) => { srv.once('error', falhou); srv.listen(0, '127.0.0.1', ok); });
+            const aba = await abaEscondida(`http://127.0.0.1:${srv.address().port}/`, { assentar: 0, prazoLoad: 10000 });
+            await aba.fechar();
+            aquecido = PORTA_REVISOR;
+            return true;
+        } finally {
+            try { srv.close(); } catch { /* já fechou */ }
+        }
+    })().catch(() => false).finally(() => { aquecendo = null; });
+    return aquecendo;
+}
+
 function fecharRevisor() {
     if (revisorChild && revisorChild.pid) {
         try { process.kill(-revisorChild.pid); } catch {
@@ -1116,8 +1191,9 @@ function fecharRevisor() {
 }
 
 module.exports = {
-    scriptDaSeta, verSeta,
+    SEM_KEYCHAIN,
+    scriptDaSeta, verSeta, findChrome,
     open, click, clickText, clickSelector, type, typeInSelector,
     key, screenshot, evaluate, waitFor, wait, scroll, close,
-    inspecionarEscondido, rodarEscondido, abrirEscondido, fecharRevisor,
+    inspecionarEscondido, rodarEscondido, abrirEscondido, fecharRevisor, subirRevisor, aquecerRevisor,
 };

package/lib/catalogo.js

@@ -84,7 +84,11 @@ const GRUPOS = [
                 + 'SEMPRE procure antes de criar quando o pedido falar de algo que já existe.' },
 
             { tool: 'estudio_plano', escreve: true, faz: 'escreve ou ajusta o que o vídeo É — cenas, elementos, animação, câmera, áudio',
-              args: 'id. plano: {formato:{largura,altura,fps}, cenas:[…], audio:{…}} — ou cenas direto. '
+              args: 'id. PREFIRA roteiro: {marca:{cores:{fundo,destaque,tinta},fontes:{titulo,texto},logo}, proporcao, '
+                + 'partes:[{tipo, fala, …}]} — o PrimoCode faz o layout, a voz com entonação, os ícones, a música e os sons. '
+                + 'Tipos: abertura{titulo,sub} titulo{titulo,sub} numero{valor,rotulo,sub} lista{titulo,itens} passos{titulo,itens} '
+                + 'contraste{nao,sim} citacao{texto,autor} imagem{busca,titulo,sub} grafico{titulo,barras:[{rotulo,valor}]} cta{titulo,link}. '
+                + 'voz (thalita|antonio|francisca). Ajuste fino: plano: {formato:{largura,altura,fps}, cenas:[…], audio:{…}} — ou cenas direto. '
                 + 'cena (opcional): o número de UMA cena para trocar só ela, sem reescrever o resto. '
                 + 'motivo (opcional): fica no caderno. voltarPara (opcional): nome de uma versão. '
                 + 'Sem plano nem cenas, LÊ o plano atual. '
@@ -104,7 +108,10 @@ const GRUPOS = [
                 + 'Use os tempos que voltam para a duração das cenas — estimar por número de palavras erra em segundos.' },
 
             { tool: 'estudio_video', escreve: true, faz: 'o que se faz com a gravação do usuário: importar, medir, cortar silêncio, transcrever, recortar a pessoa',
-              args: 'id. acao: importar | medir | silencio | cortar-silencio | quadro | legendas | recortar-pessoa. '
+              args: 'id. acao: editar | importar | medir | silencio | cortar-silencio | quadro | legendas | recortar-pessoa. '
+                + 'editar: FAZ A EDIÇÃO INTEIRA sozinho — corta o silêncio, transcreve palavra por palavra e monta o plano '
+                + '(legenda animada, ícone na hora da palavra, zoom de corte, pop e whoosh). estilo: viral (padrão) | limpo. '
+                + 'Com gravação do usuário, é o PRIMEIRO passo depois de importar; depois só estudio_render. '
                 + 'arquivo: caminho (em "importar", de fora; nas outras, o relativo dentro do projeto). '
                 + 'cortar-silencio: minimoParaCortar (padrão 0.6s), respiro (padrão 0.18s) — os dois existem para o corte não soar robótico. '
                 + 'legendas: devolve os trechos com tempo, para virarem elemento "legenda". '
@@ -119,7 +126,8 @@ const GRUPOS = [
 
             { tool: 'estudio_site', escreve: false, faz: 'lê a identidade visual de uma marca: cores, fontes, logo e o que ela diz de si',
               args: 'url — OU marca: o nome da empresa, quando não há link ("faça um vídeo para a Paris Group"). '
-                + 'id (opcional): anota no caderno do projeto. '
+                + 'id (opcional): anota no caderno do projeto — e com id traz o ACERVO da marca: as fotos e os vídeos '
+                + 'reais do site (que entram sozinhos no vídeo) e os FATOS das páginas (datas, local, números), para o roteiro. '
                 + 'Devolve FATOS medidos, não um roteiro — o roteiro é seu. '
                 + 'Use SEMPRE que o pedido citar uma empresa de verdade: inventar a cor de uma marca que existe '
                 + 'é erro que sai pronto no vídeo entregue. '

package/lib/checkpoint-git.js

@@ -0,0 +1,218 @@
+/**
+ * checkpoint-git.js — a foto do projeto inteiro, num git que a pessoa não vê.
+ *
+ * O checkpoint por arquivo (lib/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',
+];
+
+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 /desfazer 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. */
+function restaurar(gitDir, workTree, sha) {
+    const feitos = [];
+    const lista = mudancas(gitDir, workTree, sha);
+    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 };

package/lib/checkpoint.js

@@ -0,0 +1,249 @@
+/**
+ * checkpoint.js — toda mudança do agente num arquivo tem volta.
+ *
+ * Quem usa o PrimoCode quase nunca sabe git. Uma edição ruim ("ele apagou
+ * metade do meu site") não pode ser o fim da história: antes de o agente
+ * escrever, editar ou apagar um arquivo, guardamos o conteúdo ORIGINAL dele,
+ * uma vez por pedido. O `/desfazer` devolve tudo como estava.
+ *
+ * Por que o checkpoint é do PEDIDO e não do passo: um pedido vira vários
+ * runAct (passos do plano, continuações, subagentes). Para a pessoa, "desfaz"
+ * quer dizer "desfaz o que eu pedi", não "desfaz o terceiro passo interno".
+ * Por isso o CLI chama `iniciar(pedido)` antes do laço de passos, e o loop do
+ * agente só avisa `antesDeMudar(arquivo, pasta)` — o estado fica aqui, no
+ * módulo, e o subagente (mesmo processo) cai no mesmo checkpoint.
+ *
+ * Dois jeitos de guardar, o melhor que a máquina permitir:
+ *   COM git  — no `iniciar`, uma foto do projeto INTEIRO num git sombra
+ *              (lib/checkpoint-git.js). Cobre o que o run_shell apaga, move ou
+ *              gera, que a tool de arquivo nunca vê.
+ *   SEM git  — o de antes: a cópia de cada arquivo que as tools de arquivo
+ *              vão mexer. Também cobre, com git, o que a foto não pega
+ *              (arquivo ignorado, como dist/, e pasta fora do projeto).
+ *
+ * Onde fica: ~/.primocode/checkpoints/<projeto>-<hash>/
+ *   git/            o repositório sombra (só com git)
+ *   <id>/manifest.json   o pedido, a hora, o sha da foto e os arquivos
+ *   <id>/0, 1, 2…        a cópia original de cada arquivo guardado um a um
+ * Só os últimos MAXIMO por projeto: é rede de segurança, não arquivo morto.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const foto = require('./checkpoint-git');
+
+const MAXIMO = 20;
+/** As tools de arquivo que mudam o disco. run_shell fica de fora: não dá para
+    saber, antes de rodar, que arquivos um comando vai tocar — quem cobre o
+    run_shell é a foto do projeto inteiro, tirada antes do pedido. */
+const MUDAM_ARQUIVO = new Set(['write_file', 'edit_file', 'multi_edit']);
+
+/* O pedido em andamento:
+     { pedido, git: { projectDir, gitDir, dir, manifest } | null,
+               arq: { dir, manifest } | null }
+   `git` é o checkpoint com foto; `arq` é o por arquivo, para o que cai fora
+   da foto (ou para tudo, quando não há git). */
+let atual = null;
+
+/* os.homedir() lido na hora, não no require: o teste troca o HOME. */
+function raiz() { return path.join(os.homedir(), '.primocode', 'checkpoints'); }
+
+/** Uma pasta por projeto: o nome para a pessoa reconhecer, o hash para dois
+    projetos "site" em lugares diferentes não se misturarem. */
+function pastaDoProjeto(projectDir) {
+    const abs = path.resolve(projectDir);
+    const nome = path.basename(abs).replace(/[^\w.-]+/g, '-').slice(0, 40) || 'raiz';
+    const hash = crypto.createHash('sha1').update(abs).digest('hex').slice(0, 8);
+    return path.join(raiz(), `${nome}-${hash}`);
+}
+
+/** Pasta que merece foto. A casa da pessoa e o ~/primocode sem projeto
+    ficam de fora: fotografar o disco inteiro a cada pedido seria lento,
+    encheria o ~/.primocode e desfaria coisas que não são do pedido. */
+function podeFotografar(projectDir) {
+    if (!projectDir || !foto.temGit()) return false;
+    const abs = path.resolve(projectDir);
+    const casa = path.resolve(os.homedir());
+    if (abs === casa || abs === path.join(casa, 'primocode') || abs === path.parse(abs).root) return false;
+    try { return fs.statSync(abs).isDirectory(); } catch { return false; }
+}
+
+/** Uma pasta de checkpoint nova. O id é sempre maior que o anterior: a
+    ordem dos ids É a ordem dos pedidos. */
+function novoCheckpoint(projectDir, extra) {
+    const base = pastaDoProjeto(projectDir);
+    fs.mkdirSync(base, { recursive: true });
+    const ultimo = fs.readdirSync(base).filter((n) => /^\d+$/.test(n)).reduce((m, n) => Math.max(m, Number(n)), 0);
+    const dir = path.join(base, String(Math.max(Date.now(), ultimo + 1)));
+    fs.mkdirSync(dir);
+    const manifest = { pedido: atual.pedido, quando: new Date().toISOString(),
+        projectDir: path.resolve(projectDir), ...extra, arquivos: [] };
+    const cp = { dir, manifest };
+    gravarManifest(cp);
+    podar(base);
+    return cp;
+}
+
+function gravarManifest(cp) {
+    fs.writeFileSync(path.join(cp.dir, 'manifest.json'), JSON.stringify(cp.manifest, null, 2));
+}
+
+/** Começa o checkpoint de um pedido. Com git e uma pasta de projeto, a foto
+    é tirada AGORA — antes de qualquer tool rodar. Sem git (ou sem pasta),
+    nada vai ao disco ainda: pedido que não mexe em arquivo não deixa rastro. */
+function iniciar(pedido, projectDir) {
+    atual = { pedido: String(pedido || '').replace(/\s+/g, ' ').trim(), git: null, arq: null };
+    if (!podeFotografar(projectDir)) return;
+    try {
+        const abs = path.resolve(projectDir);
+        const gitDir = path.join(pastaDoProjeto(abs), 'git');
+        const sha = foto.fotografar(gitDir, abs, atual.pedido);
+        if (sha) atual.git = { projectDir: abs, gitDir, ...novoCheckpoint(abs, { git: { sha } }) };
+    } catch { /* sem foto, o checkpoint por arquivo segura o pedido */ }
+}
+
+/** Fecha o pedido. Com foto, anota o que mudou (é o que o `/desfazer lista`
+    mostra) — e, se nada mudou, o checkpoint some: uma pergunta não pode
+    ocupar o lugar de um pedido que o /desfazer deveria voltar. */
+function encerrar() {
+    const g = atual && atual.git;
+    atual = null;
+    if (!g) return;
+    try {
+        const m = foto.mudancas(g.gitDir, g.projectDir, g.manifest.git.sha);
+        if (!m.length && !g.manifest.arquivos.length) { fs.rmSync(g.dir, { recursive: true, force: true }); return; }
+        g.manifest.mudancas = m;
+        gravarManifest(g);
+    } catch { /* sem a conta, a lista calcula na hora */ }
+}
+
+/** Guarda o original de um arquivo no checkpoint `cp`, uma vez só: a segunda
+    edição do mesmo arquivo não pode sobrescrever o original já editado. */
+function guardarOriginal(cp, abs) {
+    if (cp.manifest.arquivos.some((a) => a.caminho === abs)) return;
+    const existia = fs.existsSync(abs) && fs.statSync(abs).isFile();
+    const item = { caminho: abs, existia };
+    if (existia) {
+        item.copia = String(cp.manifest.arquivos.length);
+        fs.copyFileSync(abs, path.join(cp.dir, item.copia));
+    }
+    cp.manifest.arquivos.push(item);
+    gravarManifest(cp);
+}
+
+/** Chamado pelo loop ANTES de uma tool de arquivo rodar. Se a foto do pedido
+    já cobre o arquivo, não há o que fazer; senão, guarda o original. */
+function antesDeMudar(caminhoAbs, projectDir) {
+    if (!atual || !caminhoAbs) return;
+    try {
+        const abs = path.resolve(caminhoAbs);
+        const g = atual.git;
+        if (g && (abs + path.sep).startsWith(g.projectDir + path.sep)) {
+            if (!foto.ignorado(g.gitDir, g.projectDir, abs)) return;
+            guardarOriginal(g, abs);   // dist/, .gitignore: fora da foto, mas com volta
+            return;
+        }
+        if (!atual.arq) atual.arq = novoCheckpoint(projectDir || path.dirname(abs), {});
+        guardarOriginal(atual.arq, abs);
+    } catch { /* checkpoint nunca derruba o trabalho do agente */ }
+}
+
+function podar(base) {
+    const ids = fs.readdirSync(base).filter((n) => /^\d+$/.test(n)).sort((a, b) => Number(b) - Number(a));
+    for (const velho of ids.slice(MAXIMO)) fs.rmSync(path.join(base, velho), { recursive: true, force: true });
+}
+
+const ACAO_DA_FOTO = { A: 'criado', M: 'mudou', D: 'apagado' };
+
+/** O que o pedido mudou, num formato só para os dois jeitos de guardar. */
+function mudancasDe(cp) {
+    const vistos = new Map();
+    let daFoto = cp.mudancas;
+    if (cp.git && !daFoto) {
+        // Pedido interrompido (ou o que está rodando): a conta é feita agora.
+        try { daFoto = foto.mudancas(path.join(path.dirname(cp.dir), 'git'), cp.projectDir, cp.git.sha); } catch { daFoto = []; }
+    }
+    for (const m of daFoto || []) vistos.set(path.join(cp.projectDir, m.rel), ACAO_DA_FOTO[m.status] || 'mudou');
+    for (const a of cp.arquivos || []) if (!vistos.has(a.caminho)) vistos.set(a.caminho, a.existia ? 'mudou' : 'criado');
+    return [...vistos].map(([caminho, acao]) => ({ caminho, acao }));
+}
+
+/** Os checkpoints do projeto, o mais novo primeiro. Cada um traz `mudou`:
+    os arquivos que o pedido criou, mudou ou apagou. */
+function lista(projectDir) {
+    const base = pastaDoProjeto(projectDir);
+    let ids = [];
+    try { ids = fs.readdirSync(base).filter((n) => /^\d+$/.test(n)); } catch { return []; }
+    return ids.sort((a, b) => Number(b) - Number(a)).map((id) => {
+        try {
+            const m = JSON.parse(fs.readFileSync(path.join(base, id, 'manifest.json'), 'utf8'));
+            const cp = { id, dir: path.join(base, id), ...m };
+            cp.mudou = mudancasDe(cp);
+            return cp;
+        } catch { return null; }
+    }).filter(Boolean);
+}
+
+/** O que o /desfazer N vai fazer, para a pessoa ler ANTES de confirmar.
+    Com foto, a conta é contra o disco de agora (inclui o que mudou depois do
+    pedido, que a restauração também volta). */
+function previa(projectDir, n = 1) {
+    const cps = lista(projectDir).slice(0, Math.max(1, n));
+    const vistos = new Map();
+    const maisVelhoComFoto = [...cps].reverse().find((cp) => cp.git);
+    if (maisVelhoComFoto) {
+        try {
+            for (const m of foto.mudancas(path.join(path.dirname(maisVelhoComFoto.dir), 'git'),
+                maisVelhoComFoto.projectDir, maisVelhoComFoto.git.sha)) {
+                vistos.set(path.join(maisVelhoComFoto.projectDir, m.rel), m.status === 'A' ? 'apaga (é novo)' : m.status === 'D' ? 'recria (tinha sumido)' : 'volta ao original');
+            }
+        } catch {}
+    }
+    for (const cp of cps) for (const a of cp.arquivos || []) {
+        if (!vistos.has(a.caminho)) vistos.set(a.caminho, a.existia ? 'volta ao original' : 'apaga (era novo)');
+    }
+    return [...vistos].map(([caminho, acao]) => ({ caminho, acao }));
+}
+
+/** Desfaz os N pedidos mais recentes, do mais novo para o mais velho — assim,
+    se dois pedidos mexeram no mesmo arquivo, o que sobra é o original do mais
+    antigo. Cada checkpoint desfeito é apagado: o próximo /desfazer volta mais
+    um pedido, em vez de repetir o mesmo. */
+function desfazer(projectDir, n = 1) {
+    const feitos = new Map();   // um arquivo, uma linha: vale a última ação
+    const anotar = (caminho, acao, erro) => { feitos.delete(caminho); feitos.set(caminho, erro ? { caminho, acao, erro } : { caminho, acao }); };
+    for (const cp of lista(projectDir).slice(0, Math.max(1, n))) {
+        if (cp.git) {
+            try {
+                for (const f of foto.restaurar(path.join(path.dirname(cp.dir), 'git'), cp.projectDir, cp.git.sha)) {
+                    anotar(path.join(cp.projectDir, f.rel), f.acao, f.erro);
+                }
+            } catch (e) { anotar(cp.projectDir, 'falhou', e.message); }
+        }
+        for (const a of cp.arquivos) {
+            try {
+                if (a.existia) {
+                    fs.mkdirSync(path.dirname(a.caminho), { recursive: true });
+                    fs.copyFileSync(path.join(cp.dir, a.copia), a.caminho);
+                    anotar(a.caminho, 'restaurado');
+                } else {
+                    fs.rmSync(a.caminho, { force: true });
+                    anotar(a.caminho, 'apagado');
+                }
+            } catch (e) { anotar(a.caminho, 'falhou', e.message); }
+        }
+        fs.rmSync(cp.dir, { recursive: true, force: true });
+        if (atual && atual.git && atual.git.dir === cp.dir) atual.git = null;
+        if (atual && atual.arq && atual.arq.dir === cp.dir) atual.arq = null;
+    }
+    return [...feitos.values()];
+}
+
+/** Qual jeito de guardar vale nesta pasta — o /desfazer lista conta à pessoa. */
+function modo(projectDir) { return podeFotografar(projectDir) ? 'foto' : 'arquivo'; }
+
+module.exports = { MAXIMO, MUDAM_ARQUIVO, iniciar, encerrar, antesDeMudar, lista, previa, desfazer, modo, pastaDoProjeto };