primocode 8.0.1 → 8.1.0

package/bin/primocode.js

@@ -20,10 +20,23 @@ const api = require('../lib/api');
 const tools = require('../lib/tools');
 const cfg = require('../lib/config');
 const { runAct, interromper } = require('../lib/act');
+const claudeEngine = require('../lib/claude-engine');
 const pasta = require('../lib/pasta');
 const catalogo = require('../lib/catalogo');
 const effort = require('../lib/effort');
 
+// Rede de segurança de último recurso: sem isto, uma exceção fora de um
+// try/catch (ex.: dentro de um callback de socket, como o parser de SSE) não
+// era pega por ninguém e derrubava o processo INTEIRO em silêncio — o usuário
+// via a resposta parar no meio e cair de volta pro shell, sem mensagem
+// nenhuma. Agora vira um erro visível, e o processo continua de pé.
+process.on('uncaughtException', (e) => {
+    console.log('\n' + c.err(ui.friendlyError(e)));
+});
+process.on('unhandledRejection', (e) => {
+    console.log('\n' + c.err(ui.friendlyError(e instanceof Error ? e : new Error(String(e)))));
+});
+
 // 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.
@@ -41,6 +54,7 @@ const state = {
     currentProject: null,
     workDir: null,     // pasta onde o agente trabalha nesta sessão
     workDirOrigem: null, // 'padrao' | '/dir' | 'detectada' | 'projeto' — para o /dir explicar
+    engine: 'server',   // 'server' (OpenRouter/Groq) | 'claude-code' (/claude)
 };
 
 const HELP = `
@@ -49,6 +63,7 @@ ${c.bold('Comandos')}
   ${c.brand('/project')}              lista projetos ou cria em ~/primocode: /project <nome>
   ${c.brand('/mode')}                 /mode primocode|chat|auto
   ${c.brand('/effort')}               esforço do agente — do rápido ao mais esperto
+  ${c.brand('/claude')}               liga o Claude Code local como motor (sem API paga) · /claude off volta ao padrão
   ${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
@@ -87,6 +102,7 @@ const SLASH_COMANDOS = [
     ['/dir', 'trabalhar numa pasta sua'],
     ['/mode', 'primocode | chat | auto'],
     ['/effort', 'esforço: low → ultracode (←/→ para ajustar)'],
+    ['/claude', 'liga o Claude Code local como motor · /claude off volta ao padrão'],
     ['/attach', 'anexa arquivo ao pedido'],
     ['/detach', 'remove os anexos'],
     ['/files', 'lista os anexos'],
@@ -522,6 +538,7 @@ async function sendPrompt(userText) {
             // 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,
+            motor: state.engine === 'claude-code' ? claudeEngine : api,
         });
         state.history.push({ role: 'user', content: userText });
         state.history.push({ role: 'assistant', content: r.assistantMessage.content });
@@ -670,6 +687,27 @@ async function handleSlash(text) {
             break;
         }
 
+        case 'claude': {
+            if (rest.toLowerCase() === 'off') {
+                if (state.engine !== 'claude-code') { console.log(c.muted('  Já estava no motor padrão.')); break; }
+                state.engine = 'server';
+                console.log(c.ok('  Motor: OpenRouter/Groq (padrão)'));
+                break;
+            }
+            console.log(c.dim('  Checando Claude Code e ORCA…'));
+            const r = await claudeEngine.garantirEngine();
+            if (!r.ok) {
+                console.log(c.err(`  ${r.error}`));
+                if (r.comoResolver) console.log(c.muted(`  ${r.comoResolver}`));
+                break;
+            }
+            state.engine = 'claude-code';
+            const onde = r.caminho === 'A' ? 'sessão contínua via ORCA' : 'chamada avulsa (claude -p, sem ORCA)';
+            console.log(c.ok(`  Motor: Claude Code (${onde})`));
+            console.log(c.muted('  /claude off volta pro motor padrão.'));
+            break;
+        }
+
         // O /model virou /effort: você escolhe o ESFORÇO num slider (←/→,
         // Enter confirma, Esc cancela) e o modelo sai daí. Com argumento
         // ("/effort high") aplica direto, para quem já sabe o que quer.

package/lib/act.js

@@ -165,7 +165,7 @@ function buildMemoryContext(projectDir, projectName) {
     const geral = cfg.readGeneralMemory();
     if (geral.trim()) parts.push(`[memory-geral.md]\n${geral}`);
     const projeto = cfg.readProjectMemory(projectDir);
-    if (projeto.trim()) parts.push(`[${projectName}/memory.md]\n${projeto}`);
+    if (projeto.trim()) parts.push(`[${projectName || 'projeto'}/memory.md]\n${projeto}`);
     return parts.join('\n\n');
 }
 
@@ -173,6 +173,7 @@ async function runAct(userPrompt, opts) {
     const {
         server, model, token, history, projectDir, projectName,
         ensureWorkDir, profundidade = 0, subagent = false, effort,
+        motor = api,
     } = opts || {};
 
     // A pasta de projeto só nasce quando o agente for mesmo MEXER EM ARQUIVO.
@@ -209,7 +210,7 @@ async function runAct(userPrompt, opts) {
         let streaming = false;
 
         try {
-            await api.requestAct(server, { messages, model, effort, token, projectDir, projectName, subagent }, (evt) => {
+            await motor.requestAct(server, { messages, model, effort, token, projectDir, projectName, subagent }, (evt) => {
                 if (evt.erro) { streamError = evt.erro; return; }
                 if (evt.tool_call) { toolCalls.push(evt.tool_call); return; }
                 if (evt.delta) {
@@ -282,7 +283,7 @@ async function runAct(userPrompt, opts) {
 
             if (tc.name === 'spawn_agent') {
                 const r = await runSubagent(tc.arguments || {}, {
-                    server, model, token, projectDir: pastaAtual, projectName, profundidade,
+                    server, model, token, projectDir: pastaAtual, projectName, profundidade, motor,
                 });
                 messages.push({ role: 'tool', tool_call_id: tc.id, content: r });
                 continue;
@@ -342,7 +343,12 @@ async function runAct(userPrompt, opts) {
     // 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) {
+    //
+    // `projectName` NÃO entra na condição: ele só rotula a memória no prompt
+    // (buildMemoryContext), e sessão sem projeto nomeado (ex.: primeiro pedido
+    // antes de /project) tem `projectName` undefined mesmo já tendo mexido em
+    // arquivo de verdade — a memória era descartada nesse caso, sempre.
+    if (!subagent && temPasta) {
         cfg.appendProjectMemory(pastaAtual, `**Pedido:** ${userPrompt.slice(0, 300)}\n**Resultado:** ${finalText.slice(0, 500)}`);
     }
 
@@ -353,7 +359,7 @@ async function runAct(userPrompt, opts) {
 }
 
 async function runSubagent(args, ctx) {
-    const { server, model, token, projectDir, projectName, profundidade } = ctx;
+    const { server, model, token, projectDir, projectName, profundidade, motor } = ctx;
     const descricao = args.description || 'sub-tarefa';
 
     if (profundidade + 1 >= MAX_PROFUNDIDADE) {
@@ -368,6 +374,7 @@ async function runSubagent(args, ctx) {
         history: [],
         profundidade: profundidade + 1,
         subagent: true,
+        motor,
     });
 
     const resumo = r.assistantMessage.content || 'sem resultado';

package/lib/api.js

@@ -90,7 +90,19 @@ function requestStream(serverUrl, endpoint, payload, onEvent, token) {
                     if (!line.startsWith('data: ')) continue;
                     let evt;
                     try { evt = JSON.parse(line.slice(6)); } catch { continue; }
-                    onEvent(evt);
+                    // onEvent roda dentro de um callback de socket, fora de
+                    // qualquer try/catch de quem chamou requestStream. Uma
+                    // exceção aqui não seria pega por ninguém — sem process.on
+                    // ('uncaughtException') no CLI, isso derrubava o processo
+                    // inteiro em silêncio (era o "cai fora" sem mensagem
+                    // nenhuma). Agora vira rejeição normal da Promise.
+                    try {
+                        onEvent(evt);
+                    } catch (e) {
+                        settled = true;
+                        reject(e);
+                        return;
+                    }
                     if (evt.done) finish();
                 }
             });

package/lib/catalogo.js

@@ -20,80 +20,121 @@ 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' },
+            { tool: 'write_file', escreve: true,  faz: 'cria arquivo, ou reescreve inteiro',
+              args: 'path: caminho relativo, ex "src/app.js". content: conteúdo completo do arquivo.' },
+            { tool: 'edit_file',  escreve: true,  faz: 'troca um trecho exato, sem reescrever o resto',
+              args: 'path. old_string: trecho exato a substituir, precisa ser único no arquivo. new_string: texto que entra no lugar. replace_all (opcional, bool, padrão false): troca todas as ocorrências.' },
+            { tool: 'multi_edit', escreve: true,  faz: 'várias trocas no mesmo arquivo, tudo ou nada',
+              args: 'path. edits: lista de {old_string, new_string, replace_all (opcional)}, aplicadas em ordem.' },
+            { tool: 'read_file',  escreve: false, faz: 'lê arquivo, inteiro ou por pedaço',
+              args: 'path. offset (opcional, número): primeira linha a ler. limit (opcional, número): quantas linhas.' },
+            { tool: 'list_dir',   escreve: false, faz: 'mostra a árvore de pastas',
+              args: 'path (opcional, padrão "."). depth (opcional, número, padrão 2).' },
+            { tool: 'glob',       escreve: false, faz: 'acha arquivo pelo nome (**/*.js)',
+              args: 'pattern: padrão de nome, ex "**/*.js" ou "src/**/*.{ts,tsx}".' },
+            { tool: 'grep',       escreve: false, faz: 'acha texto dentro dos arquivos',
+              args: 'pattern: expressão regular. glob (opcional): restringe aos arquivos que casam. ignoreCase (opcional, bool). contexto (opcional, número): linhas ao redor do achado.' },
         ],
     },
     {
         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)' },
+            { tool: 'run_shell',           escreve: false, faz: 'roda comando e devolve a saída',
+              args: 'command. timeout_ms (opcional, número, padrão 60000).' },
+            { tool: 'run_in_new_terminal', escreve: false, faz: 'abre outro terminal para o que fica de pé (servidor, watch)',
+              args: 'command. cwd (opcional): pasta onde rodar.' },
         ],
     },
     {
         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' },
+            { tool: 'browser_open',       escreve: false, faz: 'abre uma página ou um arquivo seu',
+              args: 'url: http(s) ou caminho de arquivo do projeto.' },
+            { tool: 'browser_click',      escreve: false, faz: 'clica por texto, por seletor ou por coordenada',
+              args: 'text (opcional): texto visível do elemento. selector (opcional): seletor CSS. x, y (opcional, número): último recurso.' },
+            { tool: 'browser_type',       escreve: false, faz: 'digita num campo',
+              args: 'text. selector (opcional): foca esse campo antes de digitar. clear (opcional, bool, padrão true).' },
+            { tool: 'browser_key',        escreve: false, faz: 'aperta tecla (Enter, Tab, Escape)',
+              args: 'key: nome da tecla (Enter, Tab, Escape, ArrowDown, ArrowUp, ArrowLeft, ArrowRight, Backspace).' },
+            { tool: 'browser_read',       escreve: false, faz: 'lê o texto da página para conferir o resultado',
+              args: 'selector (opcional): lê só esse elemento; sem isso, a página inteira.' },
+            { tool: 'browser_screenshot', escreve: true,  faz: 'tira foto da página',
+              args: 'path (opcional): onde salvar, ex "print.png". Sem path, usa um nome padrão.' },
+            { tool: 'browser_scroll',     escreve: false, faz: 'rola a página',
+              args: 'dy (opcional, número, padrão 600).' },
+            { tool: 'browser_wait',       escreve: false, faz: 'espera um elemento aparecer',
+              args: 'selector: seletor CSS a esperar. timeout_ms (opcional, número, padrão 15000).' },
+            { tool: 'browser_eval',       escreve: false, faz: 'roda JavaScript na página',
+              args: 'js: trecho de JavaScript a rodar na página, devolve o resultado.' },
+            { tool: 'open_in_browser',    escreve: false, faz: 'abre no seu navegador normal, sem controlar',
+              args: 'target: arquivo do projeto ou URL.' },
         ],
     },
     {
         nome: 'Estúdio',
         resumo: 'a suíte de criação do PrimoCode — sobe sozinha, não precisa de app externo',
         itens: [
-            { tool: 'studio_manual',    escreve: false, faz: 'lê o manual do estúdio e as seis ferramentas' },
-            { tool: 'studio_spec',      escreve: false, faz: 'lê a spec de uma ferramenta (prisma, tela, prosa…)' },
-            { tool: 'studio_criar',     escreve: false, faz: 'cria slides, arte, documento, planilha, vídeo ou diagrama' },
-            { tool: 'studio_ler',       escreve: false, faz: 'lê algo que já foi criado' },
-            { tool: 'studio_atualizar', escreve: false, faz: 'ajusta o que já existe, sem refazer do zero' },
-            { tool: 'studio_listar',    escreve: false, faz: 'lista o que já existe no estúdio' },
+            { tool: 'studio_manual',    escreve: false, faz: 'lê o manual do estúdio e as seis ferramentas', args: null },
+            { tool: 'studio_spec',      escreve: false, faz: 'lê a spec de uma ferramenta (prisma, tela, prosa…)',
+              args: 'ferramenta: prisma | tela | prosa | grade | corte | traco.' },
+            { tool: 'studio_criar',     escreve: false, faz: 'cria slides, arte, documento, planilha, vídeo ou diagrama',
+              args: 'ferramenta: prisma | tela | prosa | grade | corte | traco. titulo. doc: objeto no formato que studio_spec daquela ferramenta descreve.' },
+            { tool: 'studio_ler',       escreve: false, faz: 'lê algo que já foi criado', args: 'id.' },
+            { tool: 'studio_atualizar', escreve: false, faz: 'ajusta o que já existe, sem refazer do zero',
+              args: 'id. titulo (opcional). doc (opcional).' },
+            { tool: 'studio_listar',    escreve: false, faz: 'lista o que já existe no estúdio', args: null },
         ],
     },
     {
         nome: 'Computador',
         resumo: 'janelas, botões, mouse e teclado — age em qualquer programa e na área de trabalho',
         itens: [
-            { tool: 'desktop_open_app',      escreve: false, faz: 'abre um programa pelo nome (Chrome, Bloco de Notas…)' },
-            { tool: 'desktop_windows',       escreve: false, faz: 'lista as janelas abertas, com título' },
-            { tool: 'desktop_focus',         escreve: false, faz: 'traz uma janela para a frente, pelo título' },
-            { tool: 'desktop_elements',      escreve: false, faz: 'lê os botões, campos e ícones da janela, com posição' },
-            { tool: 'desktop_click_element', escreve: false, faz: 'clica num botão ou ícone pelo NOME, sem coordenada' },
-            { tool: 'desktop_click',         escreve: false, faz: 'clica na tela por coordenada' },
-            { tool: 'desktop_double_click',  escreve: false, faz: 'clique duplo — abre ícone da área de trabalho' },
-            { 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 (Enter, ctrl+c, alt+tab)' },
-            { tool: 'desktop_scroll',        escreve: false, faz: 'rola a tela' },
-            { tool: 'desktop_size',          escreve: false, faz: 'mede a tela, para se orientar antes de clicar' },
-            { tool: 'desktop_screenshot',    escreve: true,  faz: 'tira foto da sua tela' },
+            { tool: 'desktop_open_app',      escreve: false, faz: 'abre um programa pelo nome (Chrome, Bloco de Notas…)',
+              args: 'app: nome do programa, como o usuário fala.' },
+            { tool: 'desktop_windows',       escreve: false, faz: 'lista as janelas abertas, com título', args: null },
+            { tool: 'desktop_focus',         escreve: false, faz: 'traz uma janela para a frente, pelo título',
+              args: 'window: título (ou pedaço único) da janela.' },
+            { tool: 'desktop_elements',      escreve: false, faz: 'lê os botões, campos e ícones da janela, com posição',
+              args: 'window (opcional): título da janela alvo; sem isso, a janela em foco. No Windows, "Program Manager" é a área de trabalho.' },
+            { tool: 'desktop_click_element', escreve: false, faz: 'clica num botão ou ícone pelo NOME, sem coordenada',
+              args: 'name: nome (ou pedaço) do botão/campo/ícone. window (opcional). double (opcional, bool, padrão false): clique duplo.' },
+            { tool: 'desktop_click',         escreve: false, faz: 'clica na tela por coordenada',
+              args: 'x, y (número). button (opcional: left|right, padrão left).' },
+            { tool: 'desktop_double_click',  escreve: false, faz: 'clique duplo — abre ícone da área de trabalho',
+              args: 'x, y (número).' },
+            { tool: 'desktop_move',          escreve: false, faz: 'move o mouse', args: 'x, y (número).' },
+            { tool: 'desktop_drag',          escreve: false, faz: 'arrasta de um ponto a outro',
+              args: 'from_x, from_y, to_x, to_y (número).' },
+            { tool: 'desktop_type',          escreve: false, faz: 'digita no programa que está na frente', args: 'text.' },
+            { tool: 'desktop_key',           escreve: false, faz: 'aperta tecla ou atalho (Enter, ctrl+c, alt+tab)',
+              args: 'key: tecla ou atalho, ex "Enter", "ctrl+c", "ctrl+shift+t", "alt+tab", "win".' },
+            { tool: 'desktop_scroll',        escreve: false, faz: 'rola a tela', args: 'dy (opcional, número, padrão 300).' },
+            { tool: 'desktop_size',          escreve: false, faz: 'mede a tela, para se orientar antes de clicar', args: null },
+            { tool: 'desktop_screenshot',    escreve: true,  faz: 'tira foto da sua tela',
+              args: 'path (opcional): onde salvar. Sem path, usa um nome padrão.' },
         ],
     },
     {
         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' },
-            { tool: 'pesquisar_referencia', escreve: false, faz: 'lê docs e exemplos antes de escrever — sobe a qualidade' },
+            { tool: 'write_todos', escreve: false, faz: 'monta o plano e vai marcando o que terminou',
+              args: 'todos: lista de {content: a tarefa curta no imperativo, status: pending|in_progress|completed}. Reescreve a lista inteira a cada chamada; só uma "in_progress" por vez.' },
+            { tool: 'pesquisar_referencia', escreve: false, faz: 'lê docs e exemplos antes de escrever — sobe a qualidade',
+              args: 'consulta: o que pesquisar, de preferência em inglês. paginas (opcional, número, padrão 3, máximo 5).' },
+            // Vai para memory-geral.md, FORA da pasta do projeto — por isso não
+            // é write_file/edit_file (a sandbox de resolveInProject bloqueia
+            // qualquer caminho fora do projeto, e é assim mesmo que tem que
+            // ser para os outros casos). Esta tool é a única porta pra lá.
+            { tool: 'remember_general', escreve: false, faz: 'grava algo sobre o usuário que vale para todo projeto (memory-geral.md)',
+              args: 'fato: o que lembrar, em uma frase.' },
             // 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 },
+            { tool: 'spawn_agent', escreve: false, faz: 'chama um subagente para uma parte da tarefa', noLoop: true,
+              args: 'description: 3 a 5 palavras, aparece na tela do usuário. prompt: instrução completa e autossuficiente — o subagente não vê esta conversa.' },
+            { tool: 'finish',      escreve: false, faz: 'encerra dizendo o que fez', noLoop: true,
+              args: 'summary (opcional): uma frase do que foi feito.' },
         ],
     },
 ];

package/lib/claude-engine.js

@@ -0,0 +1,354 @@
+/**
+ * claude-engine.js — motor alternativo do agente: Claude Code local em vez
+ * de OpenRouter/Groq via primocode-server.
+ *
+ * Implementa a MESMA forma que lib/api.js (requestAct(server, payload,
+ * onEvent)) — é o que permite lib/act.js trocar de motor sem saber disso.
+ * Ver docs/superpowers/specs/2026-08-15-claude-engine-design.md.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync, execFileSync } = require('child_process');
+
+const MARCA_INICIO = '<<<PRIMOCODE>>>';
+const MARCA_FIM = '<<<FIM>>>';
+
+/**
+ * Acha o ÚLTIMO bloco marcado no texto (pode vir ruído de terminal — prompt
+ * ANSI, texto solto — antes e depois) e devolve o JSON de dentro dele.
+ * null quando não achou bloco válido: quem chama decide o que fazer.
+ */
+function extrairDecisao(texto) {
+    const t = String(texto || '');
+    const inicio = t.lastIndexOf(MARCA_INICIO);
+    if (inicio === -1) return null;
+    const fim = t.indexOf(MARCA_FIM, inicio);
+    if (fim === -1) return null;
+    const bloco = t.slice(inicio + MARCA_INICIO.length, fim).trim();
+    try {
+        return JSON.parse(bloco);
+    } catch {
+        return null;
+    }
+}
+
+const catalogo = require('./catalogo');
+
+/** Serializa lib/catalogo.js em texto — única fonte de verdade, sem
+ * duplicar a lista de ferramentas num arquivo separado. */
+function catalogoParaTexto() {
+    const linhas = [];
+    for (const grupo of catalogo.GRUPOS) {
+        linhas.push(`## ${grupo.nome} — ${grupo.resumo}`);
+        for (const item of grupo.itens) {
+            const args = item.args ? ` | args: ${item.args}` : ' | sem args';
+            linhas.push(`- ${item.tool}: ${item.faz}${args}`);
+        }
+        linhas.push('');
+    }
+    return linhas.join('\n').trim();
+}
+
+/** Texto completo que ensina o Claude Code a se comportar como motor do
+ * PrimoCode. Vira o conteúdo de ~/.claude/skills/primocode-engine/SKILL.md
+ * (Task 4) e é referenciado na primeira mensagem de cada sessão. */
+function textoBootstrap() {
+    return `---
+name: primocode-engine
+description: Skill instalada pelo PrimoCode para o modo /claude — motor de decisão do agente, não um agente autônomo.
+---
+
+# PrimoCode — modo motor
+
+Você está sendo usado como o "cérebro" do PrimoCode, um CLI que executa
+tarefas de engenharia. Não use suas próprias ferramentas nativas (Read,
+Write, Edit, Bash, Glob, Grep, WebFetch, etc.) — quem executa é o
+PrimoCode, não você. Sua única saída é dizer QUAL ferramenta do PrimoCode
+chamar, com quais argumentos, ou a resposta final.
+
+## Ferramentas disponíveis
+
+${catalogoParaTexto()}
+
+## Formato de resposta — obrigatório
+
+Termine toda resposta com exatamente um bloco, sem nada depois dele.
+
+Para chamar uma ferramenta:
+
+${MARCA_INICIO}
+{"tool_call": {"name": "write_file", "arguments": {"path": "index.html", "content": "..."}}}
+${MARCA_FIM}
+
+Para terminar a tarefa (sem mais ferramenta pra chamar):
+
+${MARCA_INICIO}
+{"assistant_message": "frase curta do que foi feito"}
+${MARCA_FIM}
+
+Nunca omita o bloco. Nunca escreva mais de um bloco por resposta.`;
+}
+
+const SKILL_DIR = () => path.join(os.homedir(), '.claude', 'skills', 'primocode-engine');
+const SKILL_PATH = () => path.join(SKILL_DIR(), 'SKILL.md');
+
+/** Grava (ou regrava) a skill em ~/.claude/skills/primocode-engine/SKILL.md.
+ * Sempre reescreve com o texto atual — barato, e garante que uma versão
+ * nova do PrimoCode (com ferramenta nova em catalogo.js) atualiza a skill
+ * sozinha na próxima vez que /claude ligar. */
+function garantirSkill() {
+    const dir = SKILL_DIR();
+    fs.mkdirSync(dir, { recursive: true });
+    const caminho = SKILL_PATH();
+    fs.writeFileSync(caminho, textoBootstrap(), 'utf-8');
+    return { ok: true, caminho };
+}
+
+/** executor(cmd) roda um comando e devolve a saída, ou lança. Default:
+ * execSync de verdade. Testes injetam uma função fake — sem mock framework. */
+function temClaudeCode(executor = (cmd) => execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] })) {
+    try { executor('claude --version'); return true; }
+    catch { return false; }
+}
+
+function temOrca(executor = (cmd) => execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] })) {
+    try { executor('orca --version'); return true; }
+    catch { return false; }
+}
+
+/** executor aqui devolve TEXTO (o JSON cru de `orca status --json`), não
+ * só "roda ou lança" — por isso um default diferente do de cima. */
+function orcaAlcancavel(executor = (cmd) => execSync(cmd, { encoding: 'utf-8' })) {
+    try {
+        const saida = executor('orca status --json');
+        const j = JSON.parse(saida);
+        return !!(j && j.result && j.result.runtime && j.result.runtime.reachable);
+    } catch {
+        return false;
+    }
+}
+
+/** Função pura — nenhum I/O aqui, só decide. */
+function escolherCaminho({ temClaude, temOrcaCli, orcaOk }) {
+    if (!temClaude) return 'sem-claude';
+    if (temOrcaCli && orcaOk) return 'A';
+    return 'B';
+}
+
+// Handle do terminal ORCA desta execução do processo — sessão contínua
+// enquanto o CLI ficar de pé. Cursor de leitura por handle, pra "terminal
+// read --cursor" trazer só o que é novo desde o turno anterior.
+let sessao = { handle: null, cursor: '0', bootstrapEnviado: false };
+
+function rodarOrca(args, opts = {}) {
+    return execFileSync('orca', args, { encoding: 'utf-8', timeout: opts.timeout || 15000 });
+}
+
+let contadorId = 0;
+/** Id sintético pro tool_call — o bloco marcado do Claude Code não traz um
+ * (só existe UM tool_call por resposta, pela própria regra do bootstrap),
+ * mas lib/act.js precisa de tc.id pra parear com a mensagem role:'tool' que
+ * vem depois. Único dentro do processo já basta. */
+function proximoId() {
+    contadorId += 1;
+    return `claude-engine-${contadorId}`;
+}
+
+// Caminho A (sessão contínua via ORCA) tem um problema arquitetural real,
+// achado rodando de verdade na verificação manual (Task 9 do plano): o
+// Claude Code interativo desenha a TUI em tela alternada, e
+// `orca terminal read` (scrollback linha a linha) nunca enxerga esse
+// conteúdo — o tail fica preso no eco do comando de lançamento. `orca
+// terminal show`'s preview mostra a tela renderizada de verdade, mas é só
+// um recorte das últimas linhas visíveis, sem garantia de conter o bloco
+// marcado inteiro numa resposta mais longa que o painel. Até esse
+// mecanismo de leitura ser resolvido, o Caminho B (testado de ponta a
+// ponta, funciona) é o único confiável — força ele sempre, mesmo com ORCA
+// disponível. O código do Caminho A fica pronto pra quando isso for
+// resolvido, só não é escolhido.
+const CAMINHO_A_HABILITADO = false;
+
+async function garantirEngine() {
+    // execFileSync('claude', …) no caminho headless não resolve o shim
+    // .cmd/.bat do Windows sem shell:true — quebraria em EVERY turno, mesmo
+    // com a detecção acima (que usa execSync com shell) passando. Recusa
+    // antes de instalar a skill: honesto e seguro, em vez de "sucesso" que
+    // quebra na primeira mensagem real.
+    if (process.platform === 'win32') {
+        return {
+            ok: false,
+            error: 'O motor Claude Code ainda não funciona no Windows.',
+            comoResolver: 'Aguarde uma próxima versão, ou use o motor padrão (OpenRouter/Groq).',
+        };
+    }
+    if (!temClaudeCode()) {
+        return {
+            ok: false,
+            error: 'Claude Code não está instalado nesta máquina.',
+            comoResolver: 'Instale o Claude Code (veja https://docs.claude.com/claude-code) e rode /claude de novo.',
+        };
+    }
+    garantirSkill();
+    const orcaCli = CAMINHO_A_HABILITADO && temOrca();
+    const caminho = escolherCaminho({
+        temClaude: true,
+        temOrcaCli: orcaCli,
+        orcaOk: orcaCli ? orcaAlcancavel() : false,
+    });
+    return { ok: true, caminho };
+}
+
+function abrirTerminalOrca() {
+    // --dangerously-skip-permissions aqui não dá poder novo ao Claude Code:
+    // a skill (textoBootstrap) já instrui ele a nunca usar suas próprias
+    // ferramentas nativas. A flag só pula os PRÓPRIOS prompts de permissão
+    // dele, que travariam a sessão sem ninguém pra responder.
+    const saida = rodarOrca(['terminal', 'create', '--command', 'claude --dangerously-skip-permissions', '--title', 'PrimoCode', '--json']);
+    const r = JSON.parse(saida);
+    // `orca terminal create --json` aninha o handle em result.terminal.handle,
+    // não em result.handle — confirmado rodando o comando de verdade (Task 9).
+    return r.result.terminal.handle;
+}
+
+function esperarIdleOrca(handle, timeoutMs) {
+    rodarOrca(['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(timeoutMs)], { timeout: timeoutMs + 5000 });
+}
+
+function ultimaMensagem(messages) {
+    const m = (messages || [])[messages.length - 1];
+    return m && m.content ? String(m.content) : '';
+}
+
+/** Devolve a decisão pro onEvent — tool_call, ou assistant_message (com
+ * degradação pra texto puro quando o bloco marcado não veio, em vez de
+ * travar o turno em silêncio). */
+function emitirDecisao(textoLido, onEvent) {
+    const decisao = extrairDecisao(textoLido);
+    if (!decisao) {
+        onEvent({ assistant_message: { content: String(textoLido || '').trim() } });
+        return;
+    }
+    if (decisao.tool_call) {
+        // lib/act.js usa tc.id pra parear a mensagem role:'tool' com este
+        // tool_call (messages.push({ tool_call_id: tc.id, ... })) — sem id
+        // aqui, esse pareamento quebra.
+        onEvent({ tool_call: { id: proximoId(), name: decisao.tool_call.name, arguments: decisao.tool_call.arguments || {} } });
+    }
+    else if (decisao.assistant_message) {
+        // O modelo pode confundir a forma com a do tool_call (que É um
+        // objeto) e emitir {"assistant_message": {"content": "..."}} em vez
+        // de string pura. Sem essa coerção, `content` vira um objeto
+        // aninhado e lib/act.js quebra com TypeError no `.trim()` — a
+        // travessia direta que este arquivo inteiro existe pra evitar.
+        const am = decisao.assistant_message;
+        const conteudo = typeof am === 'string'
+            ? am
+            : (am && typeof am.content === 'string' ? am.content : JSON.stringify(am));
+        onEvent({ assistant_message: { content: conteudo } });
+    }
+    else onEvent({ assistant_message: { content: JSON.stringify(decisao) } });
+}
+
+async function requestActViaOrca(payload, onEvent) {
+    if (!sessao.handle) {
+        try {
+            sessao.handle = abrirTerminalOrca();
+            sessao.cursor = '0';
+            sessao.bootstrapEnviado = false;
+            esperarIdleOrca(sessao.handle, 30000);
+        } catch (e) {
+            // Mesmo tratamento do try/catch abaixo: se o terminal não
+            // chegou a ficar pronto (timeout do tui-idle, por exemplo), o
+            // handle nunca foi confirmado usável — zera pra próxima
+            // chamada abrir um terminal novo do zero, em vez de deixar
+            // sessao.handle setado com algo que nunca funcionou.
+            sessao.handle = null;
+            throw e;
+        }
+    }
+    let texto = ultimaMensagem(payload.messages);
+    if (!sessao.bootstrapEnviado) {
+        texto = 'Use a skill primocode-engine para esta sessão inteira — ela está em ~/.claude/skills/primocode-engine/SKILL.md.\n\n' + texto;
+        sessao.bootstrapEnviado = true;
+    }
+    try {
+        rodarOrca(['terminal', 'send', '--terminal', sessao.handle, '--text', texto, '--enter']);
+        esperarIdleOrca(sessao.handle, 120000);
+        const lida = rodarOrca(['terminal', 'read', '--terminal', sessao.handle, '--cursor', sessao.cursor, '--json']);
+        const leitura = JSON.parse(lida);
+        // Mesma correção do handle: `terminal read --json` também aninha em
+        // result.terminal — e o texto vem como ARRAY de linhas (`tail`), não
+        // uma string única (`text`). Confirmado rodando de verdade (Task 9).
+        const t = leitura.result.terminal || {};
+        sessao.cursor = t.nextCursor != null ? String(t.nextCursor) : sessao.cursor;
+        emitirDecisao((t.tail || []).join('\n'), onEvent);
+    } catch (e) {
+        // Handle obsoleto (terminal fechado, ORCA reiniciou) — documentado
+        // pelo próprio `orca agent-context` como terminal_handle_stale. Zera
+        // a sessão: a PRÓXIMA chamada abre um terminal novo do zero. Esta
+        // chamada ainda falha (o usuário vê o erro e pode só pedir de novo).
+        sessao.handle = null;
+        throw e;
+    }
+}
+
+/** Sem sessão viva (caminho B), o histórico inteiro vira texto a cada
+ * chamada — mas `content` sozinho perde a mensagem quando é um turno de
+ * tool_calls (content vem null ali, o que importa está em tool_calls) ou
+ * uma resposta de ferramenta (role:'tool'). Reconstrói os dois casos em
+ * vez de deixar "assistant: null" no texto. */
+function linhaDoHistorico(m) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+        const chamadas = m.tool_calls
+            .map((tc) => `chamou ${tc.function.name} com ${tc.function.arguments}`)
+            .join('; ');
+        return `assistant: ${chamadas}`;
+    }
+    if (m.role === 'tool') return `resultado da ferramenta (${m.tool_call_id}): ${m.content}`;
+    return `${m.role}: ${m.content}`;
+}
+
+async function requestActViaHeadless(payload, onEvent) {
+    const historico = (payload.messages || []).map(linhaDoHistorico).join('\n\n');
+    const prompt = 'Use a skill primocode-engine para esta chamada.\n\n' + historico;
+    // --dangerously-skip-permissions: mesma razão do caminho ORCA acima —
+    // a skill já proíbe o Claude Code de usar suas próprias ferramentas
+    // nativas; a flag só evita que ele pare pedindo permissão pra si mesmo
+    // numa chamada headless sem ninguém pra responder.
+    const saida = execFileSync('claude', [
+        '-p', prompt,
+        '--output-format', 'json',
+        '--dangerously-skip-permissions',
+    ], { encoding: 'utf-8', timeout: 180000 });
+    const r = JSON.parse(saida);
+    emitirDecisao(r.result || '', onEvent);
+}
+
+/** Mesma forma de api.requestAct(server, payload, onEvent) — `server` não
+ * é usado aqui (não existe servidor neste motor), fica só pra manter a
+ * assinatura uniforme com o outro lado da escolha em lib/act.js. */
+async function requestAct(server, payload, onEvent) {
+    try {
+        const engineInfo = await garantirEngine();
+        if (!engineInfo.ok) {
+            onEvent({ erro: `${engineInfo.error} ${engineInfo.comoResolver || ''}`.trim() });
+            return;
+        }
+        if (engineInfo.caminho === 'A') await requestActViaOrca(payload, onEvent);
+        else await requestActViaHeadless(payload, onEvent);
+    } catch (e) {
+        onEvent({ erro: e.message });
+    }
+}
+
+module.exports = {
+    MARCA_INICIO, MARCA_FIM, extrairDecisao,
+    catalogoParaTexto, textoBootstrap,
+    SKILL_DIR, SKILL_PATH, garantirSkill,
+    temClaudeCode, temOrca, orcaAlcancavel, escolherCaminho,
+    garantirEngine, requestAct, emitirDecisao,
+};

package/lib/config.js

@@ -151,6 +151,18 @@ function appendProjectMemory(dir, entry) {
     } catch {}
 }
 
+// A contraparte de appendProjectMemory, para o que vale em TODOS os projetos
+// (nome do usuário, preferência, decisão de longo prazo). Existia a promessa
+// no prompt — "escreve aqui o que descobrir sobre você" — mas nenhuma função
+// gravava de fato: só ensureStructure() criava o template uma vez.
+function appendGeneralMemory(entry) {
+    if (!entry) return;
+    try {
+        ensureStructure();
+        fs.appendFileSync(GENERAL_MEMORY, `\n### ${today()}\n${entry}\n`, 'utf-8');
+    } catch {}
+}
+
 function loadConfig() {
     ensureStructure();
     let file = {};
@@ -198,5 +210,5 @@ module.exports = {
     CONFIG_DIR, CONFIG_FILE, HISTORY_FILE, ROOT_DIR, GENERAL_MEMORY,
     ensureStructure, slugify,
     createProjectDir, getProjectDir, listProjects, findSimilarProject,
-    readGeneralMemory, readProjectMemory, appendProjectMemory,
+    readGeneralMemory, readProjectMemory, appendProjectMemory, appendGeneralMemory,
 };

package/lib/modo.js

@@ -37,6 +37,13 @@ const VERBOS = [
 ];
 const RE_VERBO = new RegExp(`(^|\\s)(${VERBOS.join('|')})\\b`, 'i');
 
+// Pedido sem verbo de comando, só desejo: "quero um jogo da velha", "preciso
+// de uma landing page". Muito comum em português — e sem isto caía direto no
+// "sem pista de tarefa" porque não tem 'criar'/'fazer' escrito. A diferença
+// para RE_CONCEITUAL é que aqui não vem pergunta ("como", "por que", "o que
+// é") — só o pedido do que a pessoa quer que exista.
+const RE_DESEJO = /\b(quero|queria|querendo|gostaria de|necessito de|precis[ao] de|precisava de)\b/i;
+
 // Coisas que só existem quando há trabalho de arquivo/máquina envolvido.
 const RE_ARTEFATO = /\.(js|ts|tsx|jsx|html|css|json|md|py|sh|yml|yaml|txt|csv|env)\b|[\w-]+\/[\w-]/i;
 const RE_FERRAMENTA = /\b(navegador|browser|desktop|terminal|shell|git|npm|node|deploy|servidor|localhost|porta \d+|screenshot|print da tela|mouse|teclado|janela|[áa]rea de trabalho|aplicativo|[íi]cone)\b/i;
@@ -65,6 +72,7 @@ function escolherModo(texto) {
 
     if (RE_ARTEFATO.test(t)) return { modo: 'primocode', motivo: 'cita arquivo ou caminho' };
     if (RE_VERBO.test(t)) return { modo: 'primocode', motivo: 'pede uma ação' };
+    if (RE_DESEJO.test(t)) return { modo: 'primocode', motivo: 'expressa o que quer que exista' };
     if (RE_FERRAMENTA.test(t)) return { modo: 'primocode', motivo: 'menciona ferramenta ou máquina' };
     if (RE_PASTA.test(t)) return { modo: 'primocode', motivo: 'fala de arquivo ou projeto' };
 

package/lib/tools.js

@@ -15,6 +15,7 @@ const browser = require('./browser');
 const desktop = require('./desktop');
 const referencia = require('./referencia');
 const studio = require('./studio');
+const cfg = require('./config');
 
 const IGNORAR = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache', 'vendor']);
 const MAX_ARQUIVOS_VARREDURA = 5000;
@@ -399,6 +400,16 @@ async function despachar(name, args, ctx) {
                     paginas: Math.max(1, Math.min(5, Number(args.paginas) || 3)),
                 });
 
+            // memory-geral.md fica FORA da pasta do projeto — write_file/edit_file
+            // não alcançam por design (resolveInProject bloqueia ../ de propósito).
+            // Esta é a única porta para lá, sem reabrir a sandbox.
+            case 'remember_general': {
+                const entry = String(args.fato || args.entry || '').trim();
+                if (!entry) return { ok: false, error: 'Diga o que lembrar (fato).' };
+                cfg.appendGeneralMemory(entry);
+                return { ok: true, gravado: entry };
+            }
+
             // ── Navegador controlado (CDP) — o agente age numa página real ──
             case 'browser_open': {
                 const alvo = /^https?:\/\//i.test(args.url || '')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primocode",
-  "version": "8.0.1",
+  "version": "8.1.0",
   "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Modelos grátis. Cria arquivos, roda comandos, controla navegador e desktop: abre apps, clica em botões e ícones pelo nome, digita e usa atalhos.",
   "main": "bin/primocode.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/primocode.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 && node test/desktop.test.js && node test/effort.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 && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js"
   },
   "engines": {
     "node": ">=18.17.0"