primocode 7.7.0 → 7.9.0

package/README.md

@@ -1,13 +1,17 @@
-# PrimoCode v7.7.0
+# PrimoCode v7.9.0
 
 Agente de engenharia brasileiro para o terminal, no estilo Claude Code.
 Cria arquivos de verdade, roda comandos, **controla o navegador e o desktop** —
 e lembra do que fez entre uma sessão e outra.
 
+**Grátis, sem chave de API sua e sem teto de gasto.** Os modelos são os grátis do
+OpenRouter, e cada apelido (`top`/`main`/`fast`) é uma **corrente**: se um modelo
+está no limite de pedidos, o próximo atende. Você não vê o erro, e não paga nada.
+
 ```
- ▐▛███▜▌   Primo Code v7.7.0
+ ▐▛███▜▌   Primo Code v7.9.0
 ▝▜█████▛▘  Bem-vindo de volta, Joel
-  ▘▘ ▝▝    ~/projetos/jogo-de-carro
+  ▘▘ ▝▝    ~/primocode  · /dir <pasta> muda
 ```
 
 Personalize o mascote (`primo`, `fox`, `cat`) e o nome com que ele te chama —
@@ -119,12 +123,27 @@ para o agente custa token e pode escrever arquivo que ninguém pediu.
 
 ## Onde ele trabalha
 
+**Por padrão, sempre `~/primocode`** — não importa de onde você abriu o
+PrimoCode. Antes ele adotava a pasta atual do terminal, e o mesmo "crie um site"
+caía num lugar diferente a cada vez; quem digitava não tinha como saber onde ia
+parar. Agora o começo é sempre o mesmo, e o cabeçalho avisa em amber qual é.
+
+Para trabalhar em outra pasta, três caminhos:
+
 | Situação | Pasta de trabalho |
 |---|---|
-| Abriu o PrimoCode dentro de uma pasta | é ali que ele trabalha |
+| **Falar o nome dela no pedido** — "crie o index.html na pasta loja-do-joao" | ele procura no seu computador (`~/primocode`, Downloads, Documentos, Desktop, projetos…) e muda sozinho |
 | `/dir ~/meus-projetos/site` | a pasta que **você** escolher, onde ela estiver |
 | `/project loja` | cria `~/primocode/loja`, com memória própria |
 
+A busca por nome é conservadora de propósito: se achar duas pastas com o mesmo
+nome, ela **lista e espera** o `/dir` em vez de escolher — heurística não deve
+decidir onde um agente escreve arquivo. E nome de arquivo nunca é confundido com
+pasta: "edita o `src/app.js`" não muda pasta nenhuma.
+
+**Pasta de projeto nova só nasce quando ele vai mexer em arquivo.** Pedir "abre o
+Chrome" não cria projeto — antes criava, e `~/primocode` enchia de pasta vazia.
+
 `/dir` sem argumento mostra a pasta ativa e de onde ela veio. Caminho relativo
 resolve contra a pasta ativa, então depois de um `/dir` o `/dir src` entra na
 subpasta. Se a pasta não existir, ele pergunta antes de criar; se for a sua home
@@ -241,9 +260,10 @@ primocode -f app.js "onde está o bug?" # com arquivo anexado
 | `/dir <caminho>` | Trabalha numa pasta que já existe, onde você quiser |
 | `/project` | Lista projetos. `/project <nome>` cria em `~/primocode` |
 | `/mode primocode\|chat\|auto` | Alterna o modo (fica guardado) |
-| `/model top\|main\|fast` | top = Opus 5, main = Sonnet 5 (padrão), fast = Haiku 4.5. Aceita qualquer ID do OpenRouter |
+| `/model top\|main\|fast` | **Todos grátis.** top = o mais capaz (550B, 1M de contexto), main = agente de código (padrão), fast = o mais rápido. Aceita qualquer ID do OpenRouter |
 | `/attach <arquivo>` | Anexa arquivo ao próximo pedido |
 | `/detach` · `/files` | Remove / lista anexos |
+| `/tudo` | Lista as 30 ferramentas que ele sabe usar, por grupo |
 | `/tree [n]` | Árvore do projeto atual |
 | `/read <arquivo>` | Mostra um arquivo do projeto |
 | `/run <comando>` | Executa no shell, dentro da pasta do projeto |

package/bin/primocode.js

@@ -20,6 +20,13 @@ const api = require('../lib/api');
 const tools = require('../lib/tools');
 const cfg = require('../lib/config');
 const { runAct } = require('../lib/act');
+const pasta = require('../lib/pasta');
+const catalogo = require('../lib/catalogo');
+
+// A pasta de onde o comando foi dado. Não é mais onde ele trabalha (o padrão é
+// ~/primocode), mas continua servindo de ponto de partida para achar pasta que
+// o usuário mencionar por nome relativo.
+const CWD_INICIAL = process.cwd();
 
 const VERSION = pkg.version;
 
@@ -32,7 +39,7 @@ const state = {
     lastResponse: '',
     currentProject: null,
     workDir: null,     // pasta onde o agente trabalha nesta sessão
-    workDirOrigem: null, // 'cwd' | '/dir' | 'projeto' — para o /dir explicar
+    workDirOrigem: null, // 'padrao' | '/dir' | 'detectada' | 'projeto' — para o /dir explicar
 };
 
 const HELP = `
@@ -43,6 +50,7 @@ ${c.bold('Comandos')}
   ${c.brand('/model')}                /model top|main|fast — ou um ID do OpenRouter
   ${c.brand('/attach')} <arquivo>     anexa arquivo ao próximo pedido
   ${c.brand('/files')}                lista anexos   ${c.brand('/detach')} remove
+  ${c.brand('/tudo')}                 lista tudo que ele sabe fazer
   ${c.brand('/tree')} [n]             árvore do projeto
   ${c.brand('/read')} <arquivo>       mostra um arquivo
   ${c.brand('/run')} <comando>        executa no shell do projeto
@@ -61,8 +69,11 @@ ${c.bold('Modos')}
   ${c.brand('Auto')}        ${c.muted('Escolhe por pedido: conversa vai pro chat, tarefa vai pro agente')}
 
 ${c.bold('Onde ele trabalha')}
-  ${c.muted('Abriu dentro de uma pasta? É ali. Senão, /dir aponta para qualquer')}
-  ${c.muted('pasta sua, e /project cria uma nova em ~/primocode.')}
+  ${c.muted('Sempre em')} ${c.warn('~/primocode')}${c.muted(', não importa de onde você abriu o PrimoCode.')}
+  ${c.muted('Para outra pasta, dois caminhos:')}
+  ${c.muted('  ·')} ${c.brand('/dir <caminho>')} ${c.muted('aponta para qualquer pasta sua')}
+  ${c.muted('  ·')} ${c.muted('falar o nome dela no pedido — ele procura no seu computador')}
+  ${c.dim('Pasta de projeto nova só nasce quando ele vai mexer em arquivo.')}
 `;
 
 let rl = null;
@@ -120,26 +131,34 @@ function deriveProjectName(text) {
     return picked || 'projeto';
 }
 
-// Como o Claude Code: se você abriu o PrimoCode dentro de uma pasta de
-// trabalho, é ali que ele trabalha. Home e raiz de disco não contam — ninguém
-// quer um agente soltando arquivo no meio de C:\Users\você.
-function isUsableCwd(dir) {
+// Pasta em que é seguro deixar um agente criar e editar arquivo. A home e a raiz
+// do disco não contam — ninguém quer um agente soltando arquivo no meio de
+// C:\Users\você. O ~/primocode ERA recusado aqui, de quando a pasta atual do
+// terminal era adotada; hoje ele é o padrão, então recusá-lo não faz sentido.
+function pastaSegura(dir) {
     const home = os.homedir();
     const resolved = path.resolve(dir);
     if (resolved === path.resolve(home)) return false;
     if (resolved === path.parse(resolved).root) return false;
-    if (resolved.startsWith(path.join(home, 'primocode'))) return false;
     return true;
 }
 
-// Escolhe onde trabalhar SEM criar nada. A pasta só é criada de verdade em
-// createPendingProject(), quando o agente for mexer em arquivo.
+// Escolhe onde trabalhar SEM criar nada.
+//
+// Três casos, nesta ordem:
+//   1. pasta escolhida a dedo (/dir, ou detectada no pedido) — manda, sempre.
+//   2. projeto que JÁ existe e parece com o pedido — entra nele agora, senão a
+//      memory.md dele não carrega neste turno.
+//   3. projeto novo — fica PENDENTE: age em ~/primocode e só cria a pasta se o
+//      agente for mexer em arquivo. Pedir para abrir o Chrome não cria projeto.
 function planWorkDir(userText) {
-    if (state.workDir) return { dir: state.workDir, pending: false };
-    const proposed = deriveProjectName(userText);
-    const similar = cfg.findSimilarProject(proposed);
-    const name = similar ? similar.name : proposed;
-    return { dir: cfg.getProjectDir(name), pending: true, name, similar: !!similar };
+    if (['/dir', 'detectada', 'projeto'].includes(state.workDirOrigem)) {
+        return { dir: state.workDir, pending: false, name: state.currentProject };
+    }
+    const proposto = deriveProjectName(userText);
+    const parecido = cfg.findSimilarProject(proposto);
+    if (parecido) return { dir: parecido.dir, pending: false, name: parecido.name, similar: true };
+    return { dir: cfg.ROOT_DIR, projeto: cfg.getProjectDir(proposto), pending: true, name: proposto };
 }
 
 function createPendingProject(plan) {
@@ -159,6 +178,63 @@ function projectDir() {
 
 // ── Envio ──────────────────────────────────────────────────────────────
 
+/**
+ * Falou de uma pasta? Ele procura no computador e muda para ela.
+ *
+ * Conservador de propósito: só troca quando acha UMA pasta. Com mais de uma,
+ * lista e espera o /dir — heurística não deve escolher onde o agente escreve.
+ */
+function talvezTrocarDePasta(userText) {
+    const candidato = pasta.detectarPasta(userText);
+    if (!candidato) return;
+
+    const achado = pasta.resolverPasta(candidato, { raiz: cfg.ROOT_DIR, cwd: CWD_INICIAL });
+    if (!achado) return;   // não existe no disco: segue onde está, sem barulho
+
+    if (achado.ambiguo) {
+        console.log(c.warn(`  Achei ${achado.ambiguo.length} pastas chamadas "${candidato}":`));
+        achado.ambiguo.forEach((a) => console.log(`   ${c.dim('·')} ${c.white(shortPath(a.caminho))}`));
+        console.log(c.dim('  Escolha com /dir <caminho>.'));
+        return;
+    }
+    if (path.resolve(achado.caminho) === path.resolve(projectDir())) return;  // já está lá
+    if (!pastaSegura(achado.caminho)) return;   // home ou raiz: só por /dir explícito
+
+    state.workDir = achado.caminho;
+    state.currentProject = path.basename(achado.caminho);
+    state.workDirOrigem = 'detectada';
+    console.log(c.ok(`  Trabalhando em ${shortPath(achado.caminho)}`) + c.dim(`  (você falou "${candidato}")`));
+    refreshPrompt();
+}
+
+/**
+ * Decide, de uma vez, onde este pedido vai trabalhar.
+ *
+ * ESTA É A ÚNICA função que decide pasta. Existiam duas cópias — uma no
+ * sendPrompt e outra no modo um-tiro — e a do um-tiro ficou sem a detecção: pedir
+ * `primocode "crie x na pasta loja"` ignorava a pasta e criava projeto novo.
+ * Duas cópias da mesma decisão significam que uma delas está errada.
+ */
+function prepararPasta(userText) {
+    // A pasta é decidida ANTES de o agente começar. Trocar no meio faria as
+    // primeiras tools agirem num lugar e as seguintes em outro.
+    talvezTrocarDePasta(userText);
+
+    const plan = planWorkDir(userText);
+
+    // Projeto que já existe: entra nele AGORA. Se deixasse para depois, o
+    // buildMemoryContext deste turno leria a pasta errada e a memória do projeto
+    // não carregaria.
+    if (!plan.pending && path.resolve(plan.dir) !== path.resolve(projectDir())) {
+        state.workDir = plan.dir;
+        state.currentProject = plan.name || path.basename(plan.dir);
+        state.workDirOrigem = 'projeto';
+        console.log(c.ok(`  Continuando em ${state.currentProject}`) + c.muted(`  (${shortPath(plan.dir)})`));
+        refreshPrompt();
+    }
+    return plan;
+}
+
 async function sendPrompt(userText) {
     let prompt = userText;
     if (state.attachedFiles.length) {
@@ -179,15 +255,17 @@ async function sendPrompt(userText) {
     }
 
     if (modo === 'primocode') {
-        const plan = planWorkDir(userText);
+        const plan = prepararPasta(userText);
+
         const r = await runAct(prompt, {
             server: state.config.server,
             model: state.config.model,
             token: state.config.token,
             history: state.history,
             projectDir: plan.dir,
-            projectName: plan.pending ? plan.name : state.currentProject,
-            // Só chamado se o agente for mesmo mexer em arquivo.
+            projectName: plan.name || state.currentProject,
+            // Só chamado se o agente for mesmo MEXER EM ARQUIVO — abrir o Chrome
+            // não é motivo para criar pasta de projeto.
             ensureWorkDir: plan.pending ? () => createPendingProject(plan) : null,
         });
         state.history.push({ role: 'user', content: userText });
@@ -274,7 +352,12 @@ async function handleSlash(text) {
         case 'cd':
         case 'pasta': {
             if (!rest) {
-                const de = { cwd: 'a pasta onde você abriu o PrimoCode', '/dir': 'você escolheu com /dir', projeto: 'projeto criado pelo PrimoCode' };
+                const de = {
+                    padrao: 'a pasta padrão do PrimoCode',
+                    '/dir': 'você escolheu com /dir',
+                    detectada: 'você falou dela no pedido',
+                    projeto: 'projeto do PrimoCode',
+                };
                 console.log(`  ${c.white(shortPath(projectDir()))}`);
                 console.log(c.muted(`  ${de[state.workDirOrigem] || 'pasta atual do terminal'}`));
                 console.log(c.dim('  /dir <caminho> muda · /project <nome> cria uma nova em ~/primocode'));
@@ -301,7 +384,7 @@ async function handleSlash(text) {
             // A home e a raiz do disco são recusadas por padrão em qualquer
             // lugar do código — aqui o pedido é explícito, então pergunta em vez
             // de recusar, mas pergunta mesmo: é onde um write_file erra feio.
-            if (!isUsableCwd(alvo)) {
+            if (!pastaSegura(alvo)) {
                 console.log(c.warn(`  ${shortPath(alvo)} é a sua home ou a raiz do disco.`));
                 if (!(await confirm('O agente pode criar e editar arquivos aí. Confirma?'))) {
                     console.log(c.muted('  Nada mudou.'));
@@ -334,15 +417,16 @@ async function handleSlash(text) {
 
         case 'model': {
             const m = rest.toLowerCase();
+            // Todos grátis. A lista viva de cada corrente está no /status.
             const nomes = {
-                top: 'Opus 5 — o mais capaz, e o mais caro por pedido',
-                main: 'Sonnet 5 — o padrão: capacidade de topo a 2,5x menos',
-                fast: 'Haiku 4.5 — respostas curtas e baratas',
+                top: 'o mais capaz — 550B, 1 milhão de tokens de contexto',
+                main: 'o padrão — agente de código, o melhor em tarefa de terminal',
+                fast: 'o mais rápido — resposta curta, alta vazão',
             };
             if (nomes[m]) {
                 state.config.model = m;
                 cfg.saveConfig({ model: m });
-                console.log(c.ok(`Modelo: ${m}`) + c.muted(`  ${nomes[m]}`));
+                console.log(c.ok(`Modelo: ${m}`) + c.muted(`  ${nomes[m]}`) + c.dim('  · grátis'));
             } else if (m.includes('/')) {
                 // ID literal do OpenRouter, para quem quer sair dos três.
                 state.config.model = m;
@@ -370,6 +454,25 @@ async function handleSlash(text) {
             else state.attachedFiles.forEach((f) => console.log(`  ${c.brand(f.path)} ${c.muted(tools.fmtBytes(f.content.length))}`));
             break;
 
+        // A lista vem de lib/catalogo.js, e o test/catalogo.test.js cruza aquela
+        // lista com as tools que o tools.execute realmente atende. Ou seja: esta
+        // tela não consegue prometer coisa que o programa não faz.
+        case 'tudo':
+        case 'tools':
+        case 'capacidades': {
+            const cols = Math.max(40, Math.min(process.stdout.columns || 90, 110));
+            console.log('');
+            for (const g of catalogo.GRUPOS) {
+                console.log('  ' + c.bold(c.white(g.nome)) + ' ' + ui.truncate(c.dim('— ' + g.resumo), cols - 4 - ui.visibleWidth(g.nome)));
+                for (const i of g.itens) {
+                    console.log('    ' + c.brand(ui.padRight(i.tool, 21)) + ui.truncate(c.muted(i.faz), cols - 26));
+                }
+                console.log('');
+            }
+            console.log(c.dim(`  ${catalogo.TODAS.length} ferramentas. Você não precisa saber nenhum desses nomes — peça em português.`));
+            break;
+        }
+
         case 'tree': console.log(tools.treeDir(projectDir(), parseInt(rest, 10) || 2)); break;
 
         case 'read': {
@@ -451,7 +554,13 @@ async function handleSlash(text) {
                 sp.stop();
                 console.log(c.ok(`Servidor: ${h.status || 'ok'}`));
                 if (h.version) console.log(c.muted(`  Versão: ${h.version}`));
-                if (h.model) console.log(c.muted(`  Modelo: ${h.model}`));
+                if (h.model) console.log(c.muted(`  Modelo: ${h.model}`) + (h.gratis ? c.dim('  · grátis') : ''));
+                // A corrente inteira: é o que garante que um modelo no limite não
+                // vira erro na sua tela.
+                if (h.correntes && h.correntes[state.config.model || 'main']) {
+                    const fila = h.correntes[state.config.model] || h.correntes.main;
+                    console.log(c.dim(`  Reservas: ${fila.length - 1}`));
+                }
             } catch (e) { sp.stop(); console.log(c.err(`Indisponível: ${e.message}`)); }
             break;
         }
@@ -485,12 +594,12 @@ function shortPath(p) {
 async function main() {
     cfg.ensureStructure();
 
-    // Abriu dentro de uma pasta de trabalho? Então é ali que ele atua.
-    if (isUsableCwd(process.cwd())) {
-        state.workDir = process.cwd();
-        state.currentProject = path.basename(state.workDir);
-        state.workDirOrigem = 'cwd';
-    }
+    // Padrão fixo: ~/primocode, não importa de onde o comando foi dado. Antes ele
+    // adotava a pasta atual do terminal, e o mesmo "crie um site" caía num lugar
+    // diferente a cada vez — quem digitava não tinha como saber onde ia parar.
+    state.workDir = cfg.ROOT_DIR;
+    state.currentProject = null;
+    state.workDirOrigem = 'padrao';
 
     // Modo guardado entre sessões. O padrão é auto: sem ele, um "oi" gasta o
     // mesmo que uma refatoração.
@@ -523,14 +632,16 @@ async function main() {
             } catch { console.log(c.err(`Não consegui ler: ${args[fileFlag + 1]}`)); process.exit(1); }
         }
 
-        const plan = planWorkDir(promptText);
+        // Mesma função do modo interativo: detecta a pasta, adota projeto que já
+        // existe, e só então decide se há projeto novo pendente.
+        const plan = prepararPasta(promptText);
         await runAct(fullPrompt, {
             server: state.config.server,
             model: state.config.model,
             token: state.config.token,
             history: [],
             projectDir: plan.dir,
-            projectName: plan.pending ? plan.name : state.currentProject,
+            projectName: plan.name || state.currentProject,
             ensureWorkDir: plan.pending ? () => createPendingProject(plan) : null,
         });
         process.exit(0);
@@ -540,6 +651,7 @@ async function main() {
         modo: state.mode,
         mascot: state.config.mascot,
         userName: state.config.userName,
+        pastaPadrao: state.workDirOrigem === 'padrao',
     }));
     rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: makePrompt() });
     rl.prompt();

package/lib/act.js

@@ -14,6 +14,7 @@ const { c, actionHeader, Spinner, friendlyError } = require('./ui');
 const tools = require('./tools');
 const api = require('./api');
 const cfg = require('./config');
+const catalogo = require('./catalogo');
 
 const MAX_ITERATIONS = 15;
 const MAX_PROFUNDIDADE = 2; // principal + 1 nível de subagente
@@ -136,9 +137,13 @@ async function runAct(userPrompt, opts) {
         ensureWorkDir, profundidade = 0, subagent = false,
     } = opts || {};
 
-    // A pasta só nasce quando o agente for mesmo mexer em arquivo. Um "oi"
-    // não deve deixar diretório vazio espalhado pelo disco.
-    let workDirReady = !ensureWorkDir;
+    // A pasta de projeto só nasce quando o agente for mesmo MEXER EM ARQUIVO.
+    // Antes ela nascia na primeira tool qualquer — pedir "abre o Chrome" criava
+    // um projeto vazio, e ~/primocode enchia de pasta que não era projeto de
+    // nada. Quem decide é o catálogo: `escreve: true`.
+    let criarPasta = ensureWorkDir || null;
+    let pastaAtual = projectDir;      // onde as tools agem AGORA
+    let temPasta = !criarPasta;       // já é a pasta definitiva?
     const falhasPendentes = [];
     let tentativasDeEncerrar = 0;
 
@@ -235,16 +240,21 @@ async function runAct(userPrompt, opts) {
 
             if (tc.name === 'spawn_agent') {
                 const r = await runSubagent(tc.arguments || {}, {
-                    server, model, token, projectDir, projectName, profundidade,
+                    server, model, token, projectDir: pastaAtual, projectName, profundidade,
                 });
                 messages.push({ role: 'tool', tool_call_id: tc.id, content: r });
                 continue;
             }
 
-            if (!workDirReady) { ensureWorkDir(); workDirReady = true; }
+            if (criarPasta && catalogo.escreveArquivo(tc.name)) {
+                const nova = criarPasta();
+                if (nova) pastaAtual = nova;
+                criarPasta = null;
+                temPasta = true;
+            }
 
             console.log(ident(profundidade) + actionHeader(tc.name, tc.arguments));
-            const result = await tools.execute(tc.name, tc.arguments, { projectDir });
+            const result = await tools.execute(tc.name, tc.arguments, { projectDir: pastaAtual });
             logResult(tc.name, result, profundidade);
 
             // Uma escrita bem-sucedida limpa a dívida: o agente se corrigiu.
@@ -261,11 +271,22 @@ async function runAct(userPrompt, opts) {
         }
     }
 
-    if (!finalText) finalText = 'Cheguei ao limite de passos sem concluir. Refaça o pedido em partes menores.';
+    // Nunca terminar em silêncio. Quando o modelo devolvia resposta vazia sem
+    // chamar tool, o usuário via a tela parar e mais nada — pior que erro, porque
+    // não dá nem para saber que acabou. Medido: um pedido de navegador morria assim
+    // depois de a primeira tentativa de seletor falhar.
+    if (!finalText) {
+        finalText = falhasPendentes.length
+            ? `Parei sem concluir. A última falha foi: ${falhasPendentes[falhasPendentes.length - 1]}`
+            : 'Parei sem concluir e sem explicação do modelo. Tente pedir de novo, em partes menores.';
+        if (!subagent) console.log('\n' + c.warn(finalText));
+    }
 
-    // Nada de arquivo mexido = nada para lembrar.
-    if (!subagent && projectName && workDirReady) {
-        cfg.appendProjectMemory(projectDir, `**Pedido:** ${userPrompt.slice(0, 300)}\n**Resultado:** ${finalText.slice(0, 500)}`);
+    // Nada de arquivo mexido = nada para lembrar. E grava em `pastaAtual`, não em
+    // `projectDir`: quando a pasta do projeto nasceu no meio do caminho, a memória
+    // precisa ir para ela, não para a raiz onde a sessão começou.
+    if (!subagent && projectName && temPasta) {
+        cfg.appendProjectMemory(pastaAtual, `**Pedido:** ${userPrompt.slice(0, 300)}\n**Resultado:** ${finalText.slice(0, 500)}`);
     }
 
     return {

package/lib/browser.js

@@ -36,12 +36,16 @@ function findChrome() {
         '/Applications/Chromium.app/Contents/MacOS/Chromium',
         '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
         '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+        '/Applications/Arc.app/Contents/MacOS/Arc',
+        '/Applications/Vivaldi.app/Contents/MacOS/Vivaldi',
+        '/Applications/Opera.app/Contents/MacOS/Opera',
     ] : platform === 'win32' ? [
         `${process.env['PROGRAMFILES']}\\Google\\Chrome\\Application\\chrome.exe`,
         `${process.env['PROGRAMFILES(X86)']}\\Google\\Chrome\\Application\\chrome.exe`,
         `${process.env['LOCALAPPDATA']}\\Google\\Chrome\\Application\\chrome.exe`,
         `${process.env['PROGRAMFILES(X86)']}\\Microsoft\\Edge\\Application\\msedge.exe`,
         `${process.env['PROGRAMFILES']}\\Microsoft\\Edge\\Application\\msedge.exe`,
+        `${process.env['LOCALAPPDATA']}\\BraveSoftware\\Brave-Browser\\Application\\brave.exe`,
     ] : [
         '/usr/bin/google-chrome',
         '/usr/bin/google-chrome-stable',
@@ -53,6 +57,71 @@ function findChrome() {
     for (const p of candidates) {
         try { if (p && fs.existsSync(p)) return p; } catch {}
     }
+
+    // Último recurso: o navegador pode estar num disco montado ou numa pasta de
+    // aplicativos do usuário. Caso real medido nesta máquina: o Chrome 151 estava
+    // em `/Volumes/Google Chrome/Google Chrome.app` — a JANELA DO INSTALADOR,
+    // ainda montada. O usuário jurava (com razão) que tinha Chrome; a lista de
+    // caminhos padrão jurava que não. Os dois estavam certos.
+    const achado = procurarEmVolumes();
+    if (achado) return achado;
+
+    return null;
+}
+
+// Nomes de app e o binário dentro de cada um. Só Chromium: o Safari não fala o
+// protocolo de depuração que permite controlar a página.
+const APPS_MAC = [
+    ['Google Chrome.app', 'Google Chrome'],
+    ['Google Chrome Beta.app', 'Google Chrome Beta'],
+    ['Google Chrome Canary.app', 'Google Chrome Canary'],
+    ['Chromium.app', 'Chromium'],
+    ['Microsoft Edge.app', 'Microsoft Edge'],
+    ['Brave Browser.app', 'Brave Browser'],
+    ['Arc.app', 'Arc'],
+    ['Vivaldi.app', 'Vivaldi'],
+    ['Opera.app', 'Opera'],
+];
+
+/**
+ * Procura o navegador em `~/Applications` e nos discos montados em `/Volumes`.
+ *
+ * Um app rodando de dentro do `.dmg` funciona, mas é frágil: o disco é
+ * somente-leitura, o macOS o executa por AppTranslocation (caminho temporário
+ * aleatório) e ele desaparece na hora que o disco for ejetado. Achamos e usamos —
+ * e `avisoDeLocal()` diz ao usuário para arrastar o app para Aplicativos.
+ */
+function procurarEmVolumes() {
+    const bases = [];
+    try { bases.push(path.join(os.homedir(), 'Applications')); } catch {}
+    try {
+        for (const vol of fs.readdirSync('/Volumes')) bases.push(path.join('/Volumes', vol));
+    } catch {}
+
+    for (const base of bases) {
+        for (const [app, bin] of APPS_MAC) {
+            const alvo = path.join(base, app, 'Contents', 'MacOS', bin);
+            try { if (fs.existsSync(alvo)) return alvo; } catch {}
+        }
+    }
+    return null;
+}
+
+/**
+ * O navegador achado está num lugar problemático? Devolve o aviso, ou null.
+ *
+ * Não bloqueia nada: o controle funciona de dentro do disco montado. Só avisa,
+ * porque quem ejetar o disco vai ver a ferramenta parar de funcionar sem entender
+ * o motivo.
+ */
+function avisoDeLocal(caminho) {
+    if (!caminho) return null;
+    if (caminho.startsWith('/Volumes/')) {
+        const app = (caminho.match(/\/Volumes\/[^/]+\/([^/]+\.app)/) || [, 'o navegador'])[1];
+        return `${app} está rodando do disco de instalação, não instalado. `
+            + 'Funciona, mas para de funcionar quando você ejetar esse disco — '
+            + 'arraste o app para a pasta Aplicativos.';
+    }
     return null;
 }
 
@@ -100,11 +169,25 @@ class MiniWebSocket {
         this.onClose = () => {};
         this.closed = false;
     }
-    connect(url) {
+    connect(url, timeoutMs = 10000) {
         return new Promise((resolve, reject) => {
+            let pronto = false;
+            const relogio = setTimeout(() => {
+                if (pronto) return;
+                pronto = true;
+                try { if (this.socket) this.socket.destroy(); } catch {}
+                reject(new Error(`o navegador aceitou a conexão mas não completou o aperto de mão em ${Math.round(timeoutMs / 1000)}s`));
+            }, timeoutMs);
+            const terminar = (err) => {
+                if (pronto) return;
+                pronto = true;
+                clearTimeout(relogio);
+                err ? reject(err) : resolve();
+            };
+
             const u = new URL(url);
             const isSecure = u.protocol === 'wss:';
-            if (isSecure) return reject(new Error('wss:// não suportado (CDP local usa ws://)'));
+            if (isSecure) return terminar(new Error('wss:// não suportado (CDP local usa ws://)'));
             const key = crypto.randomBytes(16).toString('base64');
             const port = u.port || 80;
             const path = u.pathname + (u.search || '');
@@ -126,21 +209,26 @@ class MiniWebSocket {
                     const sep = headerBuf.indexOf('\r\n\r\n');
                     if (sep === -1) return;
                     const header = headerBuf.slice(0, sep).toString();
-                    if (!/HTTP\/1\.1 101/.test(header)) return reject(new Error('handshake WS falhou: ' + header.split('\r\n')[0]));
+                    if (!/HTTP\/1\.1 101/.test(header)) return terminar(new Error('handshake WS falhou: ' + header.split('\r\n')[0]));
                     handshaked = true;
                     this.socket = sock;
                     const rest = headerBuf.slice(sep + 4);
                     if (rest.length) this._onData(rest);
-                    resolve();
+                    terminar();
                 } else {
                     this._onData(data);
                 }
             });
             sock.on('error', (err) => {
-                if (!handshaked) reject(err);
+                if (!handshaked) terminar(err);
                 this.closed = true; this.onClose(err);
             });
-            sock.on('close', () => { this.closed = true; this.onClose(); });
+            sock.on('close', () => {
+                // Fechar ANTES do 101 também é falha: sem isto a Promise ficava
+                // pendente quando o Chrome derrubava a conexão calado.
+                if (!handshaked) terminar(new Error('o navegador fechou a conexão antes de aceitar o controle'));
+                this.closed = true; this.onClose();
+            });
         });
     }
     _onData(chunk) {
@@ -271,7 +359,7 @@ async function ensureChromeRunning() {
     } catch {}
 
     const chrome = findChrome();
-    if (!chrome) throw new Error('Google Chrome não encontrado no sistema. Instale o Chrome para usar o controle de navegador.');
+    if (!chrome) throw new Error('Nenhum navegador controlável encontrado. O PrimoCode usa Chrome, Edge, Brave, Arc, Vivaldi ou Chromium — instale qualquer um deles, ou aponte o seu com PRIMOCODE_CHROME=/caminho/do/navegador. (O Safari não serve: não fala o protocolo que permite controlar a página.)');
 
     fs.mkdirSync(PROFILE_DIR, { recursive: true });
 
@@ -318,14 +406,22 @@ async function findOrCreatePageTarget(url) {
     return created;
 }
 
+// Nenhuma etapa do controle de navegador pode pendurar o CLI sem explicação.
+function comTeto(promessa, ms, oQue) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error(`${oQue} não respondeu em ${Math.round(ms / 1000)}s`)), ms);
+        promessa.then((v) => { clearTimeout(t); resolve(v); }, (e) => { clearTimeout(t); reject(e); });
+    });
+}
+
 async function connect(url) {
     await ensureChromeRunning();
-    const target = await findOrCreatePageTarget(url);
+    const target = await comTeto(findOrCreatePageTarget(url), 15000, 'a lista de abas do navegador');
     if (!target || !target.webSocketDebuggerUrl) throw new Error('Não foi possível obter alvo de página do Chrome.');
     if (currentSession) { try { currentSession.close(); } catch {} }
     currentSession = new CDPSession();
     currentSession.targetId = target.id;
-    await currentSession.attach(target.webSocketDebuggerUrl);
+    await comTeto(currentSession.attach(target.webSocketDebuggerUrl), 12000, 'o canal de controle do navegador');
     await currentSession.send('Page.enable');
     await currentSession.send('DOM.enable');
     await currentSession.send('Runtime.enable');
@@ -399,6 +495,74 @@ async function clickText(text) {
     return { ok: true, ...found };
 }
 
+/**
+ * Espera o seletor aparecer por um instante antes de desistir.
+ *
+ * A página quase sempre ainda está montando quando a próxima ferramenta roda.
+ * Sem esta espera curta, "não encontrado" era muitas vezes "ainda não nasceu".
+ */
+async function esperarSeletor(selector, ms = 4000) {
+    const fim = Date.now() + ms;
+    while (Date.now() < fim) {
+        if (await evaluate(`!!document.querySelector(${JSON.stringify(selector)})`)) return true;
+        await sleep(200);
+    }
+    return false;
+}
+
+/**
+ * O que EXISTE na página, para o erro ensinar em vez de só reclamar.
+ *
+ * Mesma ideia do `trechosParecidos` do edit_file: erro seco faz o modelo chutar de
+ * novo. Devolvendo o que está lá, ele acerta na segunda tentativa.
+ *
+ * Caso real: o modelo pediu `input[name="q"]` no Google. A caixa de busca do
+ * Google é `textarea[name="q"]` — o chute era razoável e estava errado, e o erro
+ * antigo não dava nenhuma pista de qual era o certo.
+ */
+async function candidatosNaPagina() {
+    const js = `(function(){
+        // Ordem importa: quem errou um seletor quase sempre queria um CAMPO, e a
+        // lista é cortada em 12. Link de navegação por último, senão o campo de
+        // busca fica de fora justamente no caso em que ele é a resposta.
+        const porPrioridade = [
+            'input:not([type=hidden]),textarea,[contenteditable],[role=textbox]',
+            'button,[role=button],select,input[type=submit]',
+            'a[href]',
+        ];
+        const alvos = [];
+        for (const grupo of porPrioridade) {
+            for (const e of document.querySelectorAll(grupo)) if (!alvos.includes(e)) alvos.push(e);
+        }
+        const vistos = [];
+        for (const e of alvos) {
+            const r = e.getBoundingClientRect();
+            if (r.width < 2 || r.height < 2) continue;          // invisível não serve
+            const tag = e.tagName.toLowerCase();
+            let sel = tag;
+            if (e.id) sel = tag + '#' + e.id;
+            else if (e.name) sel = tag + '[name="' + e.name + '"]';
+            else if (e.getAttribute('aria-label')) sel = tag + '[aria-label="' + e.getAttribute('aria-label') + '"]';
+            else if (e.type) sel = tag + '[type="' + e.type + '"]';
+            const rotulo = (e.getAttribute('aria-label') || e.placeholder || (e.innerText||'').trim().slice(0,30) || '').replace(/\\s+/g,' ');
+            vistos.push(rotulo ? sel + '  (' + rotulo + ')' : sel);
+            if (vistos.length >= 12) break;
+        }
+        return JSON.stringify(vistos);
+    })()`;
+    try { return JSON.parse(await evaluate(js)) || []; } catch { return []; }
+}
+
+async function erroDeSeletor(selector) {
+    const candidatos = await candidatosNaPagina();
+    const err = new Error(
+        `seletor não encontrado: ${selector}`
+        + (candidatos.length ? `. Existem nesta página: ${candidatos.join(' · ')}` : '. A página não tem nenhum elemento clicável visível — ela pode não ter carregado.')
+    );
+    err.candidatos = candidatos;
+    return err;
+}
+
 async function clickSelector(selector) {
     await ensure();
     const js = `(function(){
@@ -408,8 +572,9 @@ async function clickSelector(selector) {
         const r = el.getBoundingClientRect();
         return { x: r.left + r.width/2, y: r.top + r.height/2, tag: el.tagName };
     })()`;
-    const found = await evaluate(js);
-    if (!found) throw new Error(`seletor não encontrado: ${selector}`);
+    let found = await evaluate(js);
+    if (!found && await esperarSeletor(selector)) found = await evaluate(js);
+    if (!found) throw await erroDeSeletor(selector);
     await sleep(200);
     await click(found.x, found.y);
     return { ok: true, selector, ...found };
@@ -426,14 +591,16 @@ async function type(text) {
 
 async function typeInSelector(selector, text, clear = true) {
     await ensure();
-    const focused = await evaluate(`(function(){
+    const focar = () => evaluate(`(function(){
         const el = document.querySelector(${JSON.stringify(selector)});
         if (!el) return false;
         el.focus();
         ${clear ? "if ('value' in el) el.value = '';" : ''}
         return true;
     })()`);
-    if (!focused) throw new Error(`seletor não encontrado: ${selector}`);
+    let focused = await focar();
+    if (!focused && await esperarSeletor(selector)) focused = await focar();
+    if (!focused) throw await erroDeSeletor(selector);
     await type(text);
     // dispara evento input para frameworks reativos
     await evaluate(`(function(){
@@ -504,5 +671,6 @@ function close() {
 module.exports = {
     open, navigate, click, clickText, clickSelector, type, typeInSelector,
     key, screenshot, evaluate, currentUrl, waitFor, wait, scroll, close,
-    _internal: { findChrome, PROFILE_DIR, DEBUG_PORT },
+    avisoDeLocal,
+    _internal: { findChrome, procurarEmVolumes, PROFILE_DIR, DEBUG_PORT },
 };

package/lib/catalogo.js

@@ -0,0 +1,94 @@
+/**
+ * O que o PrimoCode sabe fazer — a lista, em um lugar só.
+ *
+ * Existe porque "o que ele faz" estava espalhado entre o README, o /help, o
+ * prompt do servidor e o switch do `tools.js`, e quatro cópias da mesma verdade
+ * significam que pelo menos uma está mentindo.
+ *
+ * O `test/catalogo.test.js` cruza esta lista com as tools que o `tools.execute`
+ * realmente atende: item aqui que não existe lá derruba o teste, e tool que
+ * existe lá e não está aqui também. A lista não consegue mentir.
+ *
+ * `escreve: true` marca a ferramenta que cria ou muda arquivo. É o que decide
+ * quando nasce uma pasta de projeto — pedir para abrir o Chrome não cria projeto.
+ */
+
+'use strict';
+
+const GRUPOS = [
+    {
+        nome: 'Arquivos',
+        resumo: 'ler, criar e mudar arquivo na pasta de trabalho',
+        itens: [
+            { tool: 'write_file', escreve: true,  faz: 'cria arquivo, ou reescreve inteiro' },
+            { tool: 'edit_file',  escreve: true,  faz: 'troca um trecho exato, sem reescrever o resto' },
+            { tool: 'multi_edit', escreve: true,  faz: 'várias trocas no mesmo arquivo, tudo ou nada' },
+            { tool: 'read_file',  escreve: false, faz: 'lê arquivo, inteiro ou por pedaço' },
+            { tool: 'list_dir',   escreve: false, faz: 'mostra a árvore de pastas' },
+            { tool: 'glob',       escreve: false, faz: 'acha arquivo pelo nome (**/*.js)' },
+            { tool: 'grep',       escreve: false, faz: 'acha texto dentro dos arquivos' },
+        ],
+    },
+    {
+        nome: 'Terminal',
+        resumo: 'rodar comando na sua máquina',
+        itens: [
+            { tool: 'run_shell',           escreve: false, faz: 'roda comando e devolve a saída' },
+            { tool: 'run_in_new_terminal', escreve: false, faz: 'abre outro terminal para o que fica de pé (servidor, watch)' },
+        ],
+    },
+    {
+        nome: 'Navegador',
+        resumo: 'controla um navegador de verdade (Chrome, Edge, Brave, Arc…) — clica, digita, lê, fotografa',
+        itens: [
+            { tool: 'browser_open',       escreve: false, faz: 'abre uma página ou um arquivo seu' },
+            { tool: 'browser_click',      escreve: false, faz: 'clica por texto, por seletor ou por coordenada' },
+            { tool: 'browser_type',       escreve: false, faz: 'digita num campo' },
+            { tool: 'browser_key',        escreve: false, faz: 'aperta tecla (Enter, Tab, Escape)' },
+            { tool: 'browser_read',       escreve: false, faz: 'lê o texto da página para conferir o resultado' },
+            { tool: 'browser_screenshot', escreve: true,  faz: 'tira foto da página' },
+            { tool: 'browser_scroll',     escreve: false, faz: 'rola a página' },
+            { tool: 'browser_wait',       escreve: false, faz: 'espera um elemento aparecer' },
+            { tool: 'browser_eval',       escreve: false, faz: 'roda JavaScript na página' },
+            { tool: 'open_in_browser',    escreve: false, faz: 'abre no seu navegador normal, sem controlar' },
+        ],
+    },
+    {
+        nome: 'Computador',
+        resumo: 'mouse, teclado e tela — age em qualquer programa, não só no navegador',
+        itens: [
+            { tool: 'desktop_screenshot', escreve: true,  faz: 'tira foto da sua tela' },
+            { tool: 'desktop_click',      escreve: false, faz: 'clica na tela' },
+            { tool: 'desktop_move',       escreve: false, faz: 'move o mouse' },
+            { tool: 'desktop_drag',       escreve: false, faz: 'arrasta de um ponto a outro' },
+            { tool: 'desktop_type',       escreve: false, faz: 'digita no programa que está na frente' },
+            { tool: 'desktop_key',        escreve: false, faz: 'aperta tecla ou atalho' },
+            { tool: 'desktop_scroll',     escreve: false, faz: 'rola a tela' },
+            { tool: 'desktop_size',       escreve: false, faz: 'mede a tela, para se orientar antes de clicar' },
+        ],
+    },
+    {
+        nome: 'Organização',
+        resumo: 'como ele se organiza numa tarefa grande',
+        itens: [
+            { tool: 'write_todos', escreve: false, faz: 'monta o plano e vai marcando o que terminou' },
+            // Estas duas o loop do agente atende (lib/act.js), não o tools.execute.
+            { tool: 'spawn_agent', escreve: false, faz: 'chama um subagente para uma parte da tarefa', noLoop: true },
+            { tool: 'finish',      escreve: false, faz: 'encerra dizendo o que fez', noLoop: true },
+        ],
+    },
+];
+
+/** Só as que criam ou mudam arquivo. É o gatilho da pasta de projeto. */
+const ESCREVEM = new Set(
+    GRUPOS.flatMap((g) => g.itens.filter((i) => i.escreve).map((i) => i.tool)),
+);
+
+const TODAS = GRUPOS.flatMap((g) => g.itens.map((i) => i.tool));
+
+/** Esta ferramenta cria ou muda arquivo? */
+function escreveArquivo(tool) {
+    return ESCREVEM.has(tool);
+}
+
+module.exports = { GRUPOS, TODAS, ESCREVEM, escreveArquivo };

package/lib/pasta.js

@@ -0,0 +1,187 @@
+/**
+ * Descobrir em que pasta trabalhar a partir do que a pessoa escreveu.
+ *
+ * A regra do produto: por padrão ele trabalha em `~/primocode`, sempre, não
+ * importa de onde foi aberto. Se você **falar** de uma pasta no pedido, ele
+ * procura essa pasta no seu computador e muda para ela sozinho.
+ *
+ * Duas funções, de propósito: `detectarPasta` é pura (texto → candidato) e
+ * `resolverPasta` toca o disco. Assim a parte que erra feio — decidir que uma
+ * palavra qualquer é nome de pasta — é testável sem criar arquivo nenhum.
+ *
+ * ── POR QUE CONSERVADOR ──────────────────────────────────────────────────
+ * Errar para MENOS custa um `/dir` a mais. Errar para MAIS faz o agente escrever
+ * arquivo dentro de uma pasta que ninguém escolheu. Então: só detecta quando há
+ * marca explícita ("pasta X", "~/x/y") e nunca quando o texto parece nome de
+ * arquivo.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Onde procurar uma pasta pelo nome, na ordem. É onde as pessoas guardam
+// trabalho — não é varredura do disco, que seria lenta e traria lixo.
+const ONDE_PROCURAR = [
+    '',                 // a própria raiz de trabalho (~/primocode)
+    'Downloads',
+    'Documents',
+    'Documentos',
+    'Desktop',
+    'Área de Trabalho',
+    'projetos',
+    'Projetos',
+    'dev',
+    'code',
+    'repos',
+    'git',
+];
+
+// Palavras que vêm depois de "pasta" mas não são nome de pasta nenhuma.
+const NAO_E_NOME = new Set([
+    'do', 'da', 'de', 'dos', 'das', 'no', 'na', 'em', 'o', 'a', 'os', 'as',
+    'projeto', 'atual', 'raiz', 'aqui', 'certa', 'mesma', 'essa', 'esta',
+    'dele', 'minha', 'meu', 'nova', 'novo', 'onde', 'que', 'qual', 'toda',
+]);
+
+// Extensão de arquivo: "index.html" nunca é pasta. Sem isto, "crie o
+// src/index.html" viraria uma troca de pasta para "src/index.html".
+const TEM_EXTENSAO = /\.[a-z0-9]{1,5}$/i;
+
+const CARACTERES_DE_CAMINHO = 'A-Za-z0-9À-ÖØ-öø-ÿ_~./\\\\-';
+
+/**
+ * O texto menciona uma pasta? Devolve o candidato cru, ou null.
+ *
+ * Aceita, em ordem de confiança:
+ *   1. caminho explícito: `~/projetos/loja`, `/Users/joel/x`
+ *   2. marca de pasta: `na pasta loja`, `diretório src/app`
+ *   3. caminho relativo com barra e sem extensão: `Downloads/meu-site`
+ */
+function detectarPasta(texto) {
+    const s = String(texto || '');
+    if (!s.trim()) return null;
+
+    // 1. Caminho explícito — `~/...` ou absoluto com pelo menos dois segmentos.
+    //    Um `/algo` solto não conta: seria confundido com comando (`/dir`).
+    const explicito = s.match(new RegExp(`(?:^|\\s)(~[${CARACTERES_DE_CAMINHO}]*|/[${CARACTERES_DE_CAMINHO}]+/[${CARACTERES_DE_CAMINHO}]*)`));
+    if (explicito) {
+        const bruto = limpar(explicito[1]);
+        if (bruto && !TEM_EXTENSAO.test(bruto)) return bruto;
+    }
+
+    // 2. Marca explícita de pasta.
+    const marcado = s.match(new RegExp(`\\b(?:pasta|diret[óo]rio|dir)\\s+(?:d[eoa]s?\\s+|no\\s+|na\\s+|em\\s+)?["'\`]?([${CARACTERES_DE_CAMINHO}]+)["'\`]?`, 'i'));
+    if (marcado) {
+        const bruto = limpar(marcado[1]);
+        if (bruto && !TEM_EXTENSAO.test(bruto) && !NAO_E_NOME.has(bruto.toLowerCase())) return bruto;
+    }
+
+    // 3. Caminho relativo com barra e sem extensão.
+    // O ponto ENTRA no token de propósito: sem ele, `src/app.js` casaria como
+    // `src/app` e passaria pelo filtro de extensão sem ser visto. Capturando a
+    // extensão junto, o TEM_EXTENSAO abaixo consegue recusar.
+    const relativo = s.match(new RegExp(`(?:^|\\s)([A-Za-zÀ-ÖØ-öø-ÿ0-9_.-]+(?:/[A-Za-zÀ-ÖØ-öø-ÿ0-9_.-]+)+)`));
+    if (relativo) {
+        const bruto = limpar(relativo[1]);
+        if (bruto && !TEM_EXTENSAO.test(bruto)) return bruto;
+    }
+
+    return null;
+}
+
+// Tira pontuação de fim de frase e barra final — "na pasta loja." → "loja".
+function limpar(bruto) {
+    return String(bruto || '').trim().replace(/[.,;:!?)\]}]+$/, '').replace(/\/+$/, '');
+}
+
+/**
+ * Transforma o candidato em pasta de verdade no disco.
+ *
+ * Devolve `{ caminho, ondeAchou }` quando há uma só, `{ ambiguo: [...] }` quando
+ * há mais de uma (aí quem decide é o usuário, não a heurística), e `null` quando
+ * não achou nada.
+ */
+function resolverPasta(candidato, opts = {}) {
+    const bruto = String(candidato || '').trim();
+    if (!bruto) return null;
+
+    const home = opts.home || os.homedir();
+    const raiz = opts.raiz || path.join(home, 'primocode');
+    const cwd = opts.cwd || process.cwd();
+
+    // Caminho que já se explica: `~/x`, `/Users/...`, `./x`, `../x`.
+    if (/^~(?:$|[/\\])/.test(bruto) || path.isAbsolute(bruto) || /^\.\.?[/\\]/.test(bruto)) {
+        const alvo = path.resolve(cwd, bruto.replace(/^~(?=$|[/\\])/, home));
+        return ehPasta(alvo) ? { caminho: alvo, ondeAchou: 'caminho' } : null;
+    }
+
+    // Nome ou caminho relativo: procura nos lugares prováveis, na ordem.
+    const achados = [];
+    const bases = [raiz, cwd, home, ...ONDE_PROCURAR.map((p) => path.join(home, p))];
+    for (const base of bases) {
+        if (!base) continue;
+        const alvo = path.join(base, bruto);
+        if (!ehPasta(alvo)) continue;
+        const real = canonico(alvo);
+        if (achados.some((a) => canonico(a.caminho) === real)) continue;
+        achados.push({ caminho: alvo, ondeAchou: base === raiz ? 'primocode' : base });
+    }
+
+    // Ainda nada? Um nível dentro de cada lugar provável — é onde mora
+    // `~/Downloads/clientes/loja-do-joao`.
+    if (!achados.length) {
+        for (const base of bases) {
+            for (const filho of listarPastas(base)) {
+                const alvo = path.join(base, filho, bruto);
+                if (!ehPasta(alvo)) continue;
+                const real = canonico(alvo);
+                if (achados.some((a) => canonico(a.caminho) === real)) continue;
+                achados.push({ caminho: alvo, ondeAchou: path.join(base, filho) });
+            }
+        }
+    }
+
+    if (!achados.length) return null;
+    if (achados.length === 1) return achados[0];
+    return { ambiguo: achados.slice(0, 5) };
+}
+
+function ehPasta(p) {
+    try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Identidade da pasta no disco — `dispositivo:inode`.
+ *
+ * Necessário porque no macOS e no Windows o sistema de arquivos não diferencia
+ * maiúscula: `~/projetos` e `~/Projetos` são a MESMA pasta, e a lista de lugares
+ * prováveis tem as duas grafias. Sem isto, procurar "duplicado" achava a mesma
+ * pasta duas vezes e virava "ambíguo" sem haver ambiguidade nenhuma.
+ *
+ * Comparar `realpathSync` não resolve: no macOS ele resolve symlink mas **não**
+ * corrige a caixa — medido aqui, `.../Projetos/duplicado` volta com o P maiúsculo.
+ * O inode volta igual (850551 nos dois), então é ele que diz a verdade. Também
+ * pega symlink e hard link de graça, o que é o comportamento certo.
+ */
+function canonico(p) {
+    try {
+        const st = fs.statSync(p);
+        return `${st.dev}:${st.ino}`;
+    } catch {
+        return path.resolve(p);
+    }
+}
+
+function listarPastas(base) {
+    try {
+        return fs.readdirSync(base, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+            .map((e) => e.name)
+            .slice(0, 40);
+    } catch { return []; }
+}
+
+module.exports = { detectarPasta, resolverPasta, ONDE_PROCURAR };

package/lib/tools.js

@@ -317,11 +317,41 @@ function writeTodos({ todos }) {
 }
 function getTodos() { return TODOS; }
 
+/**
+ * Executa uma ferramenta e NUNCA lança.
+ *
+ * O `await` aqui não é enfeite. O despachante abaixo faz `return browser.x(...)`
+ * em vinte casos, e `try { return promessa } catch` **não** pega a rejeição dessa
+ * promessa — só `return await` pega. Sem isto, qualquer falha de navegador ou
+ * desktop subia por cima do loop do agente e derrubava o CLI inteiro com exit 1,
+ * em vez de virar uma ação falhada que o modelo pode corrigir.
+ *
+ * Foi exatamente o que acontecia ao pedir uma pesquisa no Google: o seletor não
+ * batia, a promessa rejeitava, e o programa morria calado no meio da tarefa.
+ */
 async function execute(name, args, ctx) {
+    try {
+        return await despachar(name, args, ctx);
+    } catch (e) {
+        // Erro que sabe o que EXISTE leva a informação junto — mesma ideia do
+        // `trechosParecidos` do edit_file. Erro seco faz o modelo chutar de novo.
+        if (e && Array.isArray(e.candidatos) && e.candidatos.length) {
+            return {
+                ok: false,
+                error: e.message,
+                seletoresDisponiveis: e.candidatos,
+                comoCorrigir: 'Chame a tool de novo com um seletor de "seletoresDisponiveis", copiado LITERALMENTE. O primeiro da lista é o mais provável.',
+            };
+        }
+        return { ok: false, error: e.message || String(e) };
+    }
+}
+
+async function despachar(name, args, ctx) {
     const projectDir = (ctx && ctx.projectDir) || process.cwd();
     args = args || {};
 
-    try {
+    {
         switch (name) {
             case 'write_file': {
                 const filePath = resolveInProject(args.path, projectDir);
@@ -410,8 +440,6 @@ async function execute(name, args, ctx) {
             default:
                 return { ok: false, error: `Tool não implementada: ${name}` };
         }
-    } catch (e) {
-        return { ok: false, error: e.message };
     }
 }
 

package/lib/ui.js

@@ -161,9 +161,9 @@ const TIPS = [
 ];
 
 const NEWS = [
-    'Modo auto: conversa vai pro chat, tarefa vai pro agente — gasta menos',
-    '/dir aponta para qualquer pasta sua, sem criar projeto novo',
-    'Corrigido o 413 que fazia todo pedido do modo primocode falhar',
+    'Modelos grátis, com reserva: um no limite não vira erro na sua tela',
+    'Ele trabalha em ~/primocode. Fale o nome de uma pasta e ele muda sozinho',
+    'Falha de navegador agora diz quais seletores EXISTEM na página',
 ];
 
 // ── Cabeçalho ────────────────────────────────────────────────────────────
@@ -172,7 +172,7 @@ const NEWS = [
 // alinhamento do desenho já dá a borda esquerda de graça.
 
 function welcomeBox(version, contexto, opts = {}) {
-    const { mascot: style, userName, modo } = opts;
+    const { mascot: style, userName, modo, pastaPadrao } = opts;
     const art = mascot(style);
     const cols = Math.max(32, Math.min(process.stdout.columns || 100, 120));
 
@@ -182,10 +182,20 @@ function welcomeBox(version, contexto, opts = {}) {
 
     // As três linhas de identidade — uma por linha do mascote, na ordem em que
     // se lê: quem é, quem chegou, onde estamos.
+    // A pasta é o que mais confundia quem usa, então ela avisa de si mesma — na
+    // MESMA linha de sempre, sem mudar o desenho do cabeçalho. Amber quando é a
+    // pasta padrão (é um aviso, não uma falha: dá para trabalhar em outra), e a
+    // primária quando foi você que escolheu — aí não há nada a avisar.
+    const linhaPasta = !contexto
+        ? c.dim('nenhuma pasta ativa')
+        : pastaPadrao
+            ? `${c.warn(contexto)}${c.dim('  · /dir <pasta> muda')}`
+            : c.brandDim(contexto);
+
     const ident = [
         `${c.bold(c.brand(NOME))} ${c.dim('v' + version)}`,
         saudacao,
-        contexto ? c.brandDim(contexto) : c.dim('nenhuma pasta ativa'),
+        linhaPasta,
     ];
 
     const out = [''];
@@ -331,6 +341,15 @@ function friendlyError(raw) {
             + '. Adicione crédito em openrouter.ai/settings/credits, ou use /model fast'
             + ' para pedidos menores.';
     }
+    // O corte de prompt da conta sem crédito. Mensagem própria porque a cura é
+    // outra: não é encurtar a conversa nem esperar, é trocar de modelo — e os
+    // apelidos padrão já são grátis, então quem cai aqui forçou um modelo pago.
+    if (/prompt tokens limit exceeded/i.test(low)) {
+        const n = s.match(/exceeded:\s*(\d+)\s*>\s*(\d+)/i);
+        return '🆓 Este modelo é pago e a conta não tem crédito, então o provedor corta o pedido'
+            + (n ? ` em ${n[2]} tokens (o seu tem ${n[1]})` : '')
+            + '. Use /model main — os modelos padrão são grátis e não têm esse corte.';
+    }
     // Ordem importa: "grande demais" e "muitos pedidos" chegam os dois como
     // rate_limit_exceeded, e a saída é oposta. Tamanho não se resolve
     // esperando — o pedido vai estourar igual daqui a uma hora.

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "primocode",
-  "version": "7.7.0",
-  "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Modo primocode cria arquivos, controla o desktop e navegador. Modo chat é conversa pura.",
+  "version": "7.9.0",
+  "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Modelos grátis. Cria arquivos, roda comandos, controla navegador e desktop.",
   "main": "bin/primocode.js",
   "bin": {
     "primocode": "bin/primocode.js"
   },
   "scripts": {
     "start": "node bin/primocode.js",
-    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js"
+    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js"
   },
   "engines": {
     "node": ">=18.17.0"