primocode 10.5.0 → 10.6.0

package/lib/outra-pasta.js

@@ -0,0 +1,161 @@
+/**
+ * outra-pasta.js — a pessoa falou de OUTRA pasta: olhar lá, e trocar só com o sim dela.
+ *
+ *   "Quando a IA perceber que eu perguntei sobre algo de outra pasta, ela
+ *    tem que ir procurar lá. E se ela estiver aberta numa pasta e eu estiver
+ *    trabalhando em outra, ela muda de pasta — com permissão, claro."
+ *    (11/10/2026)
+ *
+ * Duas coisas diferentes, de propósito:
+ *
+ *   · LER lá não pede licença: foi a própria pessoa que citou a pasta. O
+ *     agente ganha leitura (read_file, list_dir, grep, glob) naquela pasta,
+ *     sem sair de onde está. Escrever continua só na pasta de trabalho.
+ *   · TRABALHAR lá é trocar a pasta da sessão — e isso SEMPRE pergunta. Ela
+ *     muda onde os arquivos nascem, e o "sim" é da pessoa, não da heurística.
+ *
+ * Antes, citar "pasta loja" trocava sozinho (lib/pasta.js), e um projeto só
+ * era achado com a palavra "pasta" na frente. Agora "olha o landing-padaria"
+ * também acha — pelo nome dos projetos em ~/primocode e das pastas recentes.
+ *
+ * `detectar` e `pedirTroca` são puros (quem toca disco e terminal entra por
+ * parâmetro), para o teste medir a regra sem disco e sem ninguém digitando.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const pasta = require('./pasta.js');
+
+// Nome que é palavra comum: "app", "site", "teste" aparecem em qualquer
+// frase e não querem dizer a pasta de mesmo nome.
+const COMUNS = new Set(['app', 'site', 'teste', 'test', 'projeto', 'project', 'src', 'docs', 'novo',
+    'video', 'videos', 'web', 'api', 'lib', 'dist', 'build', 'public', 'assets', 'dados', 'data', 'tmp']);
+
+function semAcento(s) { return String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase(); }
+
+function ehPasta(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+
+/**
+ * As pastas que a pessoa conhece pelo NOME: os projetos de ~/primocode e as
+ * recentes (projeto-ativo.json). Mesmo nome em dois lugares: fica a recente.
+ */
+function conhecidas({ raiz, recentes = [] } = {}) {
+    const lista = [];
+    const vistos = new Set();
+    const incluir = (caminho) => {
+        const abs = path.resolve(caminho);
+        if (vistos.has(abs) || !ehPasta(abs)) return;
+        vistos.add(abs);
+        lista.push({ nome: path.basename(abs), caminho: abs });
+    };
+    for (const r of recentes) incluir(r);
+    if (raiz) {
+        try {
+            for (const d of fs.readdirSync(raiz, { withFileTypes: true })) {
+                if (d.isDirectory() && !d.name.startsWith('.')) incluir(path.join(raiz, d.name));
+            }
+        } catch { /* sem raiz ainda */ }
+    }
+    return lista;
+}
+
+/**
+ * O pedido cita uma pasta conhecida pelo nome?
+ *
+ * Só nome com PELO MENOS DUAS palavras (`landing-padaria`, `jogo_carro`) casa
+ * solto na frase — escrito com hífen, sublinhado ou espaço. Nome de uma
+ * palavra só ("loja") casaria com "faz uma loja" e trocaria de pasta por
+ * acaso; para ele vale a marca explícita do lib/pasta.js ("pasta loja").
+ */
+function porNome(texto, lista) {
+    const t = ` ${semAcento(texto).replace(/[^a-z0-9]+/g, ' ').trim()} `;
+    const achados = [];
+    for (const p of lista || []) {
+        const partes = semAcento(p.nome).split(/[^a-z0-9]+/).filter(Boolean);
+        if (partes.length < 2 || COMUNS.has(partes.join('-'))) continue;
+        if (partes.join('').length < 6) continue;
+        if (t.includes(` ${partes.join(' ')} `)) achados.push({ ...p, como: 'nome' });
+    }
+    // O nome mais comprido primeiro: "jogo-carro-mundo-aberto" ganha de "jogo-carro".
+    return achados.sort((a, b) => b.nome.length - a.nome.length);
+}
+
+/**
+ * As pastas que o pedido cita, fora a atual. Caminho escrito vem primeiro
+ * (é o mais certo); depois os nomes conhecidos.
+ *
+ * `resolver(candidato)` → `{ caminho }` | `{ ambiguo }` | null é o
+ * `pasta.resolverPasta` no programa, e um falso no teste.
+ */
+function detectar(texto, { conhecidas: lista = [], atual = '', resolver = null } = {}) {
+    const fora = (c) => !atual || path.resolve(c) !== path.resolve(atual);
+    const saida = [];
+    const candidato = pasta.detectarPasta(texto);
+    if (candidato && resolver) {
+        const achado = resolver(candidato);
+        if (achado && achado.ambiguo) return { ambiguo: achado.ambiguo, candidato };
+        if (achado && achado.caminho && fora(achado.caminho)) {
+            saida.push({ caminho: path.resolve(achado.caminho), nome: candidato, como: 'caminho' });
+        }
+    }
+    for (const p of porNome(texto, lista)) {
+        if (fora(p.caminho) && !saida.some((s) => s.caminho === p.caminho)) saida.push(p);
+    }
+    return { pastas: saida };
+}
+
+/**
+ * A linha que vai junto do pedido quando a pessoa citou outra pasta e o
+ * agente continua onde está. Ela diz as duas portas: ler lá agora, ou pedir
+ * para trabalhar lá.
+ */
+function notaDeConsulta(caminho, atual) {
+    return `[outra pasta] O usuário citou ${caminho}. Você pode LER e PROCURAR lá sem sair de ${atual}: `
+        + `read_file e list_dir com o caminho absoluto; glob com o padrão absoluto ("${caminho}/**/*.js"); `
+        + `grep com glob absoluto ("${caminho}/**"). `
+        + 'Para TRABALHAR lá (criar ou mudar arquivo), chame mudar_pasta — o usuário confirma antes.';
+}
+
+/**
+ * O pedido de troca do modelo (tool mudar_pasta). Só troca com o SIM.
+ *
+ * @param {object} args     { caminho, motivo }
+ * @param {object} ctx      { atual, subagent, trocar, resolver }
+ *   trocar(info) → Promise<{ ok, caminho, memoria? , error? }>: quem PERGUNTA
+ *   ao usuário e, com o sim, troca a sessão. Sem ele, ninguém pode dizer sim.
+ */
+async function pedirTroca(args, { atual = '', subagent = false, trocar = null, resolver = null } = {}) {
+    const bruto = String((args && (args.caminho || args.path || args.pasta)) || '').trim();
+    const motivo = String((args && args.motivo) || '').trim();
+    if (!bruto) return { ok: false, error: 'faltou o caminho da pasta (caminho).' };
+    if (subagent) return { ok: false, error: 'subagente não troca a pasta da sessão — devolva ao agente principal o que achou.' };
+
+    const resolve = resolver || ((c) => pasta.resolverPasta(c, { cwd: atual || process.cwd() }));
+    const achado = resolve(bruto);
+    if (!achado) return { ok: false, error: `não achei a pasta "${bruto}". Confira o caminho (list_dir) ou peça ao usuário.` };
+    if (achado.ambiguo) {
+        return { ok: false, error: `há mais de uma pasta "${bruto}"; chame de novo com o caminho completo.`,
+            opcoes: achado.ambiguo.map((a) => a.caminho) };
+    }
+    const destino = path.resolve(achado.caminho);
+    if (atual && destino === path.resolve(atual)) return { ok: true, caminho: destino, aviso: 'já está nesta pasta.' };
+    if (destino === path.resolve(os.homedir()) || destino === path.parse(destino).root) {
+        return { ok: false, error: 'a home e a raiz do disco não são pasta de trabalho. Escolha a pasta do projeto.' };
+    }
+    if (typeof trocar !== 'function') {
+        return { ok: false, error: 'trocar de pasta precisa do sim do usuário, e não há ninguém para responder neste modo. '
+            + 'Leia lá se precisar e diga a ele o caminho para usar /dir.' };
+    }
+    const r = await trocar({ caminho: destino, motivo });
+    if (!r || !r.ok) {
+        return { ok: false, recusado: true,
+            error: (r && r.error) || 'o usuário NÃO quis trocar de pasta. Continue na atual; ler a outra continua liberado.' };
+    }
+    return { ok: true, caminho: r.caminho || destino, ...(r.memoria ? { memoria: r.memoria } : {}),
+        comoUsar: 'a pasta de trabalho agora é esta: caminhos relativos valem a partir dela.' };
+}
+
+module.exports = { conhecidas, porNome, detectar, notaDeConsulta, pedirTroca, COMUNS };

package/lib/perigo.js

@@ -164,14 +164,39 @@ function analisarTrecho(palavras, estado) {
     return null;
 }
 
+/* O LIVRO DE AÇÕES (lib/auditoria.js) mora fora do projeto, e o `rm` nele já
+   pedia licença. Mas `> livro`, `sed -i`, `truncate` e `mv` passavam: o
+   agente podia apagar ou reescrever o registro do que ele mesmo fez (review
+   do #95, item 3). Ler o livro (cat, grep, tail…) segue livre. */
+const LIVRO = path.join(os.homedir(), '.primocode', 'registro');
+const SO_LE = new Set(['cat', 'head', 'tail', 'less', 'more', 'grep', 'rg', 'wc', 'ls', 'jq', 'nl', 'stat', 'file', 'cd']);
+function mexeNoLivro(palavras, cwd) {
+    const p = palavras.filter((x) => !PREFIXOS.has(x) && !/^[A-Za-z_]\w*=/.test(x));
+    if (!p.length) return false;
+    const noLivro = (x) => {
+        const alvo = path.resolve(cwd, expandir(String(x).replace(/^\d?>>?/, '')));
+        return alvo === LIVRO || dentro(LIVRO, alvo);
+    };
+    // Redirecionar para dentro do livro é escrever nele, seja qual for o comando.
+    for (let i = 0; i < p.length; i++) {
+        const redireciona = /^\d?>>?$/.test(p[i]) ? p[i + 1] : /^\d?>>?./.test(p[i]) ? p[i] : /.>>?./.test(p[i]) ? p[i].split(/>>?/).pop() : null;
+        if (redireciona && noLivro(redireciona)) return true;
+    }
+    if (SO_LE.has(path.basename(p[0]))) return false;
+    return p.slice(1).some((x) => !/^-/.test(x) && noLivro(x.split(/>>?/)[0]));
+}
+
 function analisarComando(comando, cwd, projeto) {
     const s = String(comando || '');
     // Baixar e rodar na hora: o que roda é o que o site mandar naquele segundo.
     if (/\b(curl|wget)\b[^;&]*\|\s*(sudo\s+)?(env\s+)?(ba|z|da|k)?sh\b/.test(s)) {
         return 'baixa um script da internet e roda sem ler';
     }
+    // O mesmo que mcp_conectar, pela porta dos fundos: não pula o portão.
+    if (/\bprimocode\s+mcp\s+(conectar|connect|add)\b/.test(s)) return 'instala e roda um servidor MCP de terceiros';
     const estado = { cwd, projeto, pulandoFlags: false };
     for (const t of trechos(s)) {
+        if (mexeNoLivro(t.palavras, estado.cwd)) return 'mexe no livro de ações do PrimoCode (~/.primocode/registro), o registro do que o agente fez';
         const r = analisarTrecho(t.palavras, estado);
         if (r) return r;
     }
@@ -189,6 +214,12 @@ function classificar(nome, args, { projectDir } = {}) {
     if (COMANDOS.has(nome)) {
         const cwd = a.cwd ? path.resolve(projeto, expandir(a.cwd)) : projeto;
         motivo = analisarComando(a.command, cwd, projeto);
+    } else if (nome === 'mcp_conectar') {
+        /* Instala e roda código de terceiro (npx/uvx/docker) com as chaves do
+           usuário: sempre pergunta, como o curl | sh. O motivo leva o comando,
+           então "a sessão inteira" libera AQUELE servidor, não qualquer um. */
+        const cmd = [a.comando || a.command, ...(Array.isArray(a.args) ? a.args : [])].filter(Boolean).join(' ');
+        motivo = `instala e roda o servidor MCP "${a.nome || '?'}"${cmd ? ` (${cmd.slice(0, 80)})` : ''}`;
     } else if (ESCRITAS.has(nome) && a.path) {
         const alvo = path.resolve(projeto, expandir(a.path));
         const rel = path.relative(projeto, alvo);
@@ -216,12 +247,13 @@ async function portao(estado, { modo, nome, args, projectDir, subagent = false,
     const m = normalizarModo(modo);
     if (m === 'livre') return { ok: true };
     const { perigoso, motivo: motivoPerigo } = classificar(nome, args, { projectDir });
-    const tipo = perigoso ? 'perigo' : (m === 'perguntar' && COMANDOS.has(nome)) ? 'comando'
+    const tipo = perigoso ? 'perigo' : (m === 'perguntar' && (COMANDOS.has(nome) || nome === 'mcp_usar')) ? 'comando'
         : (m === 'perguntar' && ESCRITAS.has(nome)) ? 'arquivo' : null;
     if (!tipo) return { ok: true };
 
     const motivo = perigoso ? motivoPerigo
-        : tipo === 'comando' ? `rodar: ${String((args || {}).command || '').slice(0, 80)}`
+        : tipo === 'comando' ? (nome === 'mcp_usar' ? `usar ${(args || {}).servidor}.${(args || {}).ferramenta}`
+            : `rodar: ${String((args || {}).command || '').slice(0, 80)}`)
             : `escrever ${String((args || {}).path || 'um arquivo')}`;
     const recusa = (texto) => ({ ok: false, motivo, error: texto });
 

package/lib/referencia.js

@@ -28,6 +28,7 @@ const http = require('http');
 const net = require('net');
 const tls = require('tls');
 const { URL } = require('url');
+const leitura = require('./leitura');
 
 // Achado de segurança: redirect sem checar destino é SSRF — uma fonte de
 // busca (conteúdo de terceiro, não confiável) pode responder com um Location
@@ -231,6 +232,13 @@ function textoDe(html) {
         .trim();
 }
 
+/* Uma fonte lida, com o passo da cascata que a leu: o terminal mostra, e o
+   modelo sabe se a página veio pela busca simples ou pelo navegador. */
+function fonteLida(cand, trecho, passo, chars) {
+    return { titulo: cand.titulo, url: cand.url, nota: cand.nota, trecho,
+        leitura: { passo, como: passo === 1 ? 'busca simples' : 'navegador', chars, enviados: trecho.length } };
+}
+
 /**
  * ── FONTE ERRADA É PIOR QUE FONTE NENHUMA ────────────────────────────────
  * Pedido real: "pesquise sobre a Paris Group e crie um vídeo para anunciar a
@@ -665,7 +673,7 @@ async function docsConhecidas(consulta) {
  * A pesquisa completa: busca, abre as melhores páginas e devolve o texto
  * delas para o modelo LER. O modelo escreve o código dele com isso na mão.
  */
-async function pesquisar({ consulta, paginas = 3 }) {
+async function pesquisar({ consulta, paginas = 3, navegador } = {}) {
     const termo = String(consulta || '').trim();
     if (!termo) return { ok: false, error: 'diga o que pesquisar' };
 
@@ -742,6 +750,7 @@ async function pesquisar({ consulta, paginas = 3 }) {
     // Os chutes de domínio ficam de lado até o fim: só então dá para saber
     // qual deles fala mais do assunto.
     const chutesLidos = [];
+    const finas = [];
     // As páginas abrem JUNTAS, não uma depois da outra: dez candidatos a 2 s
     // cada eram 20 s de espera antes de ler a primeira linha. Quem não abriu
     // vira null e é pulado na ordem — a ordem de confiança continua valendo.
@@ -752,10 +761,17 @@ async function pesquisar({ consulta, paginas = 3 }) {
         if (lidas.length >= paginas) break;
         const html = paginasAbertas[ic];
         if (!html) continue;
-        const texto = textoDe(html);
+        // Passo 1 da leitura em cascata (lib/leitura.js): a estrutura sai
+        // aqui, local, e o modelo nunca vê o HTML cru.
+        const est = leitura.estruturaDe(html, cand.url);
+        const texto = est.texto;
         // 400, não 200: uma casca de página que carrega tudo por JavaScript
         // deixa 200-300 caracteres de menu, e isso passava como "fonte lida".
-        if (texto.length < 400) continue;
+        // Ela não é descartada: fica pro passo 2 (o navegador), lá embaixo.
+        if (texto.length < leitura.MINIMO) {
+            if (cand.nota !== 'site provável da empresa') finas.push({ cand, html });
+            continue;
+        }
         if (pareceCodigo(texto)) continue;
         // O chute de domínio precisa PROVAR que acertou. "Paris Group" tem
         // parisgroup.com (um grupo de varejo no exterior) e parisgroup.ai (a
@@ -778,15 +794,28 @@ async function pesquisar({ consulta, paginas = 3 }) {
             // Passar não basta: entre dois domínios do MESMO nome, fica o que
             // fala mais do assunto. parisgroup.ai e parisgroup.co os dois
             // "batiam", e o agente recebia as duas empresas como se fossem uma.
-            chutesLidos.push({ nota, item: { titulo: cand.titulo, url: cand.url, nota: cand.nota, trecho: texto.slice(0, MAX_TEXTO) } });
+            chutesLidos.push({ nota, item: fonteLida(cand, leitura.caber(est, MAX_TEXTO).conteudo, 1, texto.length) });
             continue;
         }
-        lidas.push({
-            titulo: cand.titulo,
-            url: cand.url,
-            nota: cand.nota,
-            trecho: texto.slice(0, MAX_TEXTO),
-        });
+        lidas.push(fonteLida(cand, leitura.caber(est, MAX_TEXTO).conteudo, 1, texto.length));
+    }
+
+    // Passo 2: faltou fonte e houve página fina (SPA) — o navegador escondido
+    // renderiza o JavaScript. Só duas, e as duas dividem UM teto de 20 s.
+    // A URL passa pela mesma trava da busca simples antes de o Chrome abrir:
+    // redirect e pedido seguinte continuam travados dentro do htmlEscondido.
+    const prazoPasso2 = Date.now() + 20000;
+    const abrirNoNavegador = navegador === undefined
+        ? (u) => require('./browser').htmlEscondido(u) : navegador;
+    for (const { cand, html } of finas.slice(0, 2)) {
+        if (lidas.length >= paginas || !abrirNoNavegador || Date.now() >= prazoPasso2) break;
+        let host = '';
+        try { host = new URL(cand.url).hostname; } catch { continue; }
+        if (hostBloqueado(host)) continue;
+        const resta = prazoPasso2 - Date.now();
+        const r = await leitura.ler(cand.url, { html, orcamento: MAX_TEXTO,
+            navegador: (u) => Promise.race([abrirNoNavegador(u), new Promise((ok) => setTimeout(ok, resta, null))]) });
+        if (r.ok && r.passo === 2 && !pareceCodigo(r.texto)) lidas.push(fonteLida(cand, r.conteudo, 2, r.chars));
     }
 
     // O melhor chute entra na frente: quando a empresa tem site, ele é a
@@ -820,6 +849,6 @@ async function pesquisar({ consulta, paginas = 3 }) {
     };
 }
 
-module.exports = { pesquisar, buscar, stackoverflow, textoDe, buscarWikipedia, buscarRespostaDDG, pegar,
+module.exports = { pesquisar, buscar, stackoverflow, textoDe, buscarWikipedia, buscarRespostaDDG, pegar, hostBloqueado,
     relevante, quantoBate, palavrasDaConsulta, sitesProvaveis, chutesVivos, pareceCodigo,
     destinoBing, destinoYahoo, buscarBing, buscarYahoo, buscarMDN, docsConhecidas, PRAZO_BUSCADOR };

package/lib/repeticao.js

@@ -142,6 +142,25 @@ function executou(registro, nome, args) {
     registro.olhouDesde = false;
 }
 
+/**
+ * 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
+ * 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.
+ */
+function espiar(registro, nome, args) {
+    const busca = consultaDe(nome, args);
+    const foraDaEpoca = busca !== null || REFERENCIAS.has(nome);
+    const base = assinatura(nome, args);
+    const epoca = (base === registro.ultimaMudanca && !registro.olhouDesde)
+        ? registro.epocaDaMudanca : (registro.epoca || 0);
+    const chave = base + (foraDaEpoca ? '' : `@${epoca}`);
+    const repetida = registro.vistos.has(chave)
+        || (!!busca && registro.buscas.some((b) => semelhanca(b.texto, busca) >= LIMITE_SEMELHANCA));
+    return { repetida, chave };
+}
+
 /**
  * Registra a chamada e diz se ela é repetição.
  *
@@ -251,5 +270,5 @@ function referenciasNaConversa(messages) {
 module.exports = {
     REFERENCIAS, LIMITE_SEMELHANCA,
     normalizar, palavras, semelhanca, assinatura, consultaDe,
-    novo, ver, executou, observa, muda, chamadasPorId, referenciasNaConversa,
+    novo, ver, espiar, executou, observa, muda, chamadasPorId, referenciasNaConversa,
 };

package/lib/tela.js

@@ -221,7 +221,7 @@ function quadro(e) {
         conversa.length = altoConversa;
     }
     if (rolagem > 0) {
-        conversa[0] = ' ' + c.dim(`↑ ${rolagem} linha${rolagem > 1 ? 's' : ''} abaixo · PgDn ou a roda do mouse para voltar`);
+        conversa[0] = ' ' + c.dim(`↑ ${rolagem} linha${rolagem > 1 ? 's' : ''} abaixo · PgDn para voltar`);
     }
 
     const esquerda = [...conversa, ...caixa.linhas].map((l) => caber(l, mainW));

package/lib/tools.js

@@ -94,6 +94,59 @@ function resolveInProject(rawPath, projectDir) {
     return target;
 }
 
+/* ── LER EM OUTRA PASTA ──────────────────────────────────────────────────
+ * A pessoa citou outra pasta ("olha como fiz no landing-padaria"): o agente
+ * pode LER e PROCURAR lá, sem trocar a pasta de trabalho (lib/outra-pasta.js).
+ * Só leitura, e só nas pastas que a própria pessoa citou nesta sessão —
+ * escrever continua preso na pasta de trabalho pelo resolveInProject. */
+const PASTAS_DE_CONSULTA = new Set();
+
+function liberarLeitura(dir) {
+    if (!dir) return;
+    try { if (fs.statSync(dir).isDirectory()) PASTAS_DE_CONSULTA.add(path.resolve(dir)); } catch { /* não existe */ }
+}
+
+function pastasDeConsulta() { return [...PASTAS_DE_CONSULTA]; }
+function esquecerConsultas() { PASTAS_DE_CONSULTA.clear(); }
+
+/** Caminho para LER: dentro do projeto, ou dentro de uma pasta citada. */
+function resolverParaLer(rawPath, projectDir) {
+    try {
+        return resolveInProject(rawPath, projectDir);
+    } catch (e) {
+        const bruto = String(rawPath || '').replace(/^~(?=$|[/\\])/, os.homedir());
+        if (path.isAbsolute(bruto)) {
+            const alvo = path.resolve(bruto);
+            for (const raiz of PASTAS_DE_CONSULTA) {
+                const rel = path.relative(raiz, alvo);
+                if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) return alvo;
+            }
+        }
+        throw new Error(`${e.message}. Ler fora da pasta de trabalho só vale nas pastas que o usuário citou; `
+            + 'para trabalhar em outra pasta, use mudar_pasta.');
+    }
+}
+
+/**
+ * Onde procurar (glob/grep): a pasta de trabalho, ou a pasta citada.
+ *
+ * O schema do servidor não ganhou campo novo (cada token do núcleo conta no
+ * teto do minuto): a outra pasta vem no PADRÃO absoluto —
+ * "/Users/x/site/src/<estrela>.js" vira a raiz "/Users/x/site/src" e o
+ * padrão "<estrela>.js". `pasta` explícito também vale, para quem mandar.
+ */
+function raizDaBusca(padrao, pastaPedida, projectDir) {
+    if (pastaPedida) return { raiz: resolverParaLer(pastaPedida, projectDir), padrao, outra: true };
+    const bruto = String(padrao || '').replace(/^~(?=$|[/\\])/, os.homedir());
+    if (!padrao || !path.isAbsolute(bruto)) return { raiz: projectDir, padrao, outra: false };
+    const partes = bruto.split(/[/\\]/);
+    const i = partes.findIndex((p) => /[*?{[]/.test(p));
+    const fixo = (i === -1 ? partes : partes.slice(0, i)).join('/') || '/';
+    const resto = i === -1 ? '**/*' : partes.slice(i).join('/');
+    const raiz = resolverParaLer(fixo, projectDir);
+    return { raiz, padrao: resto, outra: path.resolve(raiz) !== path.resolve(projectDir) };
+}
+
 function treeDir(dir, maxDepth = 2, currentDepth = 0, prefix = '') {
     if (currentDepth > maxDepth) return '';
     let result = '';
@@ -411,7 +464,7 @@ function editFile({ path: rawPath, old_string, new_string, replace_all }, projec
 }
 
 function readFile({ path: rawPath, offset, limit }, projectDir) {
-    const filePath = resolveInProject(rawPath, projectDir);
+    const filePath = resolverParaLer(rawPath, projectDir);
     const bruto = fs.readFileSync(filePath, 'utf-8');
     const todas = bruto.split('\n');
 
@@ -578,13 +631,20 @@ async function despachar(name, args, ctx) {
             case 'read_file':
                 return readFile(args, projectDir);
             case 'list_dir':
-                return { ok: true, tree: treeDir(resolveInProject(args.path, projectDir), args.depth || 2) };
+                return { ok: true, tree: treeDir(resolverParaLer(args.path, projectDir), args.depth || 2) };
+            /* `pasta` (opcional): procurar numa pasta que o usuário citou, sem
+               trocar a de trabalho. Os caminhos voltam relativos a ELA, e a
+               resposta diz qual é. */
             case 'glob': {
-                const arquivos = globFiles(args.pattern || '**/*', projectDir);
-                return { ok: true, total: arquivos.length, arquivos: arquivos.slice(0, 200) };
+                const b = raizDaBusca(args.pattern || '**/*', args.pasta, projectDir);
+                const arquivos = globFiles(b.padrao || '**/*', b.raiz);
+                return { ok: true, total: arquivos.length, arquivos: arquivos.slice(0, 200), ...(b.outra ? { pasta: b.raiz } : {}) };
+            }
+            case 'grep': {
+                const b = raizDaBusca(args.glob, args.pasta, projectDir);
+                const r = grepFiles({ ...args, glob: b.padrao }, b.raiz);
+                return b.outra && r && r.ok !== false ? { ...r, pasta: b.raiz } : r;
             }
-            case 'grep':
-                return grepFiles(args, projectDir);
             case 'run_shell':
                 return runShell(args.command, args.timeout_ms || 60000, projectDir, ambienteLimpo());
             case 'run_in_new_terminal':
@@ -630,6 +690,15 @@ async function despachar(name, args, ctx) {
                 return { ok: true, gravado: entry };
             }
 
+            // ── MCP: o serviço pela API dele, antes do mouse (lib/mcp.js) ──
+            case 'mcp_procurar':
+                return require('./mcp.js').procurar(args.busca || args.query || args.servico || '');
+            // Roda código de terceiro: o portão (lib/perigo.js) pergunta antes de chegar aqui.
+            case 'mcp_conectar':
+                return require('./mcp.js').conectarNovo({ nome: args.nome, command: args.comando || args.command, args: args.args, env: args.env });
+            case 'mcp_usar':
+                return require('./mcp.js').usar(args.servidor, args.ferramenta, args.argumentos || args.arguments || {}, projectDir);
+
             // ── Navegador controlado (CDP) — o agente age numa página real ──
             /* O navegador fala em REFS (lib/snapshot.js): abrir e clicar já
                devolvem o retrato da página com "@e3 [button] Entrar", e o
@@ -882,4 +951,5 @@ module.exports = {
     fmtBytes, treeDir, runShell, ambienteLimpo, openInBrowser, runInNewTerminal,
     execute, uninstall, resolveInProject, globToRegex, globFiles, grepFiles, editFile,
     multiEdit, writeTodos, getTodos,
+    liberarLeitura, pastasDeConsulta, esquecerConsultas, resolverParaLer,
 };

package/lib/travado.js

@@ -0,0 +1,141 @@
+/**
+ * travado.js — o agente que anda em círculo para antes de comer a cota.
+ *
+ * ── O QUE ACONTECEU DE VERDADE ───────────────────────────────────────────
+ * 01/10: um subagente passou mais de uma hora relendo o mesmo arquivo, em
+ * fatias que se sobrepunham, até acabar a cota grátis. O freio de repetição
+ * (repeticao.js) só pega a chamada IDÊNTICA — a fatia 1-200 e a 150-350 do
+ * mesmo app.js passavam como coisas novas. O único freio era o teto de 20
+ * voltas, e 20 voltas de leitura são muita cota.
+ *
+ * ── A REGRA (do foreman do thruwire: perguntas fechadas, limite em número) ─
+ *   1. a mesma fatia (ou uma que se sobrepõe) do mesmo arquivo, lida
+ *      LIMITE_RELEITURA vezes sem escrita no meio?            → travado
+ *   2. a mesma ferramenta com os mesmos argumentos LIMITE_MESMA_CHAMADA
+ *      vezes sem escrita no meio?                              → travado
+ *   3. VOLTAS_SEM_NOVIDADE voltas seguidas sem escrever nada e sem nenhuma
+ *      chamada que ainda não tinha sido feita?                 → travado
+ * Na primeira vez, um empurrão curto (o que está repetindo, o que fazer). Se
+ * travar de novo depois do empurrão, PARA e diz por quê.
+ *
+ * Puro e determinístico: sem I/O, sem relógio. O teste mede a regra inteira.
+ */
+
+'use strict';
+
+const path = require('path');
+
+const LIMITE_RELEITURA = 3;
+const LIMITE_MESMA_CHAMADA = 4;
+const VOLTAS_SEM_NOVIDADE = 6;
+const ESCRITAS = new Set(['write_file', 'edit_file', 'multi_edit']);
+
+function novo() {
+    return { leituras: new Map(), chamadas: new Map(), vistas: new Set(), novidade: false, voltasSemNovidade: 0, avisos: 0 };
+}
+
+/* A faixa que a leitura cobre. Sem offset nem limit, o read_file devolve o
+   arquivo inteiro. Com offset e sem limit, devolve LEITURA_PADRAO linhas a
+   partir dele (lib/tools.js) — e não "daqui até o fim": era assim, e ler as
+   linhas 1, 201 e 401 em sequência, que é o que a dica da read_file manda
+   fazer, contava como reler a mesma parte (review do #95, item 1). */
+const LEITURA_PADRAO = 200;
+function faixa(args) {
+    const a = args || {};
+    if (a.offset == null && a.limit == null) return [1, Infinity];
+    const ini = Math.max(1, Number(a.offset) || 1);
+    const lim = Number(a.limit) > 0 ? Number(a.limit) : LEITURA_PADRAO;
+    return [ini, ini + lim - 1];
+}
+const sobrepoe = (a, b) => a[0] <= b[1] && b[0] <= a[1];
+
+/* LER PELO SHELL é ler. O agente que leva o empurrão por reler o app.js
+   foge para `cat app.js` ou `sed -n '1,200p' app.js` — e o freio só olhava a
+   read_file (item 2). O comando de leitura simples vira a leitura que ele é. */
+function leituraDoShell(comando) {
+    const s = String(comando || '').trim();
+    const m = /^(?:cd\s+("[^"]+"|'[^']+'|\S+)\s*&&\s*)?(cat|nl|less|more|head|tail|sed)((?:\s+(?:-n\s*)?(?:'[^']*'|"[^"]*"|-\S+|\d+))*)\s+("[^"]+"|'[^']+'|[^\s|;&><'"]+)\s*$/.exec(s);
+    if (!m) return null;
+    const tira = (x) => String(x || '').replace(/^["']|["']$/g, '');
+    const [, cd, cmd, opcoes] = m;
+    const arquivo = cd ? path.join(tira(cd), tira(m[4])) : tira(m[4]);
+    if (cmd === 'sed') {
+        const r = /-n\s*['"]?(\d+)(?:,(\d+))?p['"]?/.exec(opcoes);
+        if (!r) return null;                       // sed que não é "mostra as linhas A a B"
+        const ini = Number(r[1]);
+        return { path: arquivo, offset: ini, limit: (r[2] ? Number(r[2]) : ini) - ini + 1 };
+    }
+    if (cmd === 'head') {
+        const n = /(\d+)/.exec(opcoes || '');
+        return { path: arquivo, offset: 1, limit: n ? Number(n[1]) : 10 };
+    }
+    return { path: arquivo };                      // cat, tail e companhia: o arquivo todo
+}
+
+/* O mesmo arquivo com outro nome é o mesmo arquivo: `app.js`, `./app.js`,
+   `/projeto/app.js` e `src/../app.js` (item 2). Sem a pasta, normaliza só o
+   texto. Puro: path.resolve não abre nada. */
+function caminhoDe(p, pasta) {
+    return pasta ? path.resolve(pasta, String(p)) : path.normalize(String(p));
+}
+
+/** Olha UMA chamada, antes de ela rodar. Devolve o motivo se travou, ou null. */
+function observar(estado, nome, args, pasta) {
+    const a = args || {};
+    const chave = `${nome}:${JSON.stringify(a)}`;
+    if (ESCRITAS.has(nome)) {
+        estado.leituras.clear();
+        estado.chamadas.clear();
+        estado.novidade = true;
+    }
+    if (!estado.vistas.has(chave)) { estado.vistas.add(chave); estado.novidade = true; }
+    const leitura = nome === 'read_file' ? a : nome === 'run_shell' ? leituraDoShell(a.command) : null;
+    if (leitura && leitura.path) {
+        const caminho = caminhoDe(leitura.path, pasta);
+        const f = faixa(leitura);
+        const antes = estado.leituras.get(caminho) || [];
+        antes.push(f);
+        estado.leituras.set(caminho, antes);
+        const vezes = antes.filter((g) => sobrepoe(f, g)).length;
+        if (vezes >= LIMITE_RELEITURA) {
+            const nomeCurto = pasta ? path.relative(pasta, caminho) || caminho : caminho;
+            return `leu ${nomeCurto} ${vezes} vezes (a mesma parte, ou partes que se sobrepõem) sem mudar nada no meio`;
+        }
+    }
+    const n = (estado.chamadas.get(chave) || 0) + 1;
+    estado.chamadas.set(chave, n);
+    if (n >= LIMITE_MESMA_CHAMADA) return `chamou ${nome} com os mesmos argumentos ${n} vezes`;
+    return null;
+}
+
+/** Fecha a volta. Devolve o motivo se já são voltas demais sem nada novo. */
+function fimDaVolta(estado) {
+    estado.voltasSemNovidade = estado.novidade ? 0 : estado.voltasSemNovidade + 1;
+    estado.novidade = false;
+    if (estado.voltasSemNovidade >= VOLTAS_SEM_NOVIDADE) {
+        return `${estado.voltasSemNovidade} voltas seguidas sem escrever nada e sem buscar nada novo`;
+    }
+    return null;
+}
+
+/** Travou: a primeira vez empurra; a segunda para. */
+function decidir(estado, motivo) {
+    if (!motivo) return null;
+    estado.avisos++;
+    if (estado.avisos === 1) {
+        estado.voltasSemNovidade = 0;
+        return {
+            acao: 'empurrar',
+            texto: `VOCÊ ESTÁ ANDANDO EM CÍRCULO: ${motivo}. O que você já leu está na conversa. `
+                + 'Pare de reler. Faça AGORA o próximo passo concreto (edit_file, write_file, rodar o teste) '
+                + 'ou chame finish dizendo o que conseguiu e o que falta. Mais uma volta assim e eu paro você.',
+        };
+    }
+    return {
+        acao: 'parar',
+        texto: `Parei o agente: ele travou (${motivo}), mesmo depois de avisado. `
+            + 'Continuar só gastaria cota. O que já foi feito ficou feito — refaça o pedido com um passo mais específico.',
+    };
+}
+
+module.exports = { LIMITE_RELEITURA, LIMITE_MESMA_CHAMADA, VOLTAS_SEM_NOVIDADE, LEITURA_PADRAO, novo, faixa, leituraDoShell, observar, fimDaVolta, decidir };

package/lib/ui.js

@@ -558,6 +558,7 @@ const ROTULOS = {
         desktop_elements:'Desktop·elementos', desktop_click_element:'Desktop·click',
     estudio_midia:'Estúdio·mídia', construir_app:'Construir',
     remember_general:'Lembrar',
+    mcp_procurar:'MCP·procurar', mcp_conectar:'MCP·conectar', mcp_usar:'MCP',
 };
 
 /* A linha da AÇÃO: `●` na cor da marca e o rótulo em negrito. O resultado