auroq-os 2.8.0 → 2.8.2

package/lib/onepassword.js

@@ -3,18 +3,25 @@
 /**
  * Auroq OS — Conexao 1Password CLI
  *
- * Fluxo seguro: o aluno copia o token de Service Account (ops_...) e roda
- * `npx auroq-os conectar-1password`. O token e lido direto da area de
- * transferencia, validado online e gravado de forma persistente — nunca e
- * digitado, impresso ou passado por argumento de linha de comando.
+ * Fluxo padrao (automatico): o aluno cria a conta do 1Password, instala o app, liga
+ * "Integrate with 1Password CLI" nas configuracoes do app e aprova UMA vez com a digital
+ * (Touch ID / Windows Hello). O resto e daqui: cria o cofre "Claude", cria a conta de
+ * servico "Auroq" com acesso so a esse cofre, grava o token no computador e confere.
+ * O token nasce e e gravado dentro deste processo: este comando nunca o imprime nem o passa por
+ * argumento de linha de comando. (Depois de gravado ele e uma variavel de ambiente do aluno: quem
+ * rodar `env` ou abrir o arquivo de ambiente o ve, por isso o Ops nunca faz isso.)
+ *
+ * Modo manual (escondido, `--manual`): o aluno copia o token de uma conta de servico que ele
+ * mesmo criou (ops_...) e o comando le da area de transferencia, valida e grava.
  *
  * @module auroq-os/onepassword
  */
 
 const os = require('os');
+const crypto = require('crypto');
 const path = require('path');
 const fs = require('fs-extra');
-const { execSync, execFileSync } = require('child_process');
+const { execSync, execFileSync, spawn, spawnSync } = require('child_process');
 
 const PURPLE = '\x1b[38;2;120;80;200m';
 const GOLD = '\x1b[38;2;245;158;11m';
@@ -80,18 +87,19 @@ function opVersion() {
   }
 }
 
-function installOp() {
+function installOp({ upgrade = false } = {}) {
   if (process.platform === 'darwin') {
     if (!hasCommand('brew')) {
       err('Homebrew nao encontrado. Instale em https://brew.sh e rode este comando de novo.');
       return false;
     }
-    log(`${DIM}Instalando via Homebrew (pode levar um minuto)...${RESET}`);
+    log(`${DIM}${upgrade ? 'Atualizando' : 'Instalando'} via Homebrew (pode levar um minuto)...${RESET}`);
+    const brewCmd = upgrade ? 'brew upgrade --cask 1password-cli' : 'brew install --cask 1password-cli';
     try {
-      execSync('brew install --cask 1password-cli', { stdio: 'pipe', maxBuffer: 64 * 1024 * 1024 });
+      execSync(brewCmd, { stdio: 'pipe', maxBuffer: 64 * 1024 * 1024, env: opEnv() });
       return true;
     } catch {
-      err('Instalacao via Homebrew falhou. Tente manualmente: brew install --cask 1password-cli');
+      err(`${upgrade ? 'Atualizacao' : 'Instalacao'} via Homebrew falhou. Tente manualmente: ${brewCmd}`);
       return false;
     }
   }
@@ -102,12 +110,13 @@ function installOp() {
       err('https://developer.1password.com/docs/cli/get-started/');
       return false;
     }
-    log(`${DIM}Instalando via winget (pode levar um minuto)...${RESET}`);
+    log(`${DIM}${upgrade ? 'Atualizando' : 'Instalando'} via winget (pode levar um minuto)...${RESET}`);
+    const verb = upgrade ? 'upgrade' : 'install';
     try {
-      execSync('winget install --id AgileBits.1Password.CLI --accept-source-agreements --accept-package-agreements', { stdio: 'pipe', maxBuffer: 64 * 1024 * 1024 });
+      execSync(`winget ${verb} --id AgileBits.1Password.CLI --accept-source-agreements --accept-package-agreements`, { stdio: 'pipe', maxBuffer: 64 * 1024 * 1024, env: opEnv() });
       return true;
     } catch {
-      err('Instalacao via winget falhou. Tente manualmente: winget install AgileBits.1Password.CLI');
+      err(`${upgrade ? 'Atualizacao' : 'Instalacao'} via winget falhou. Tente manualmente: winget ${verb} AgileBits.1Password.CLI`);
       return false;
     }
   }
@@ -141,6 +150,27 @@ function readClipboard() {
   }
 }
 
+/** Apaga a area de transferencia (melhor esforco): o token copiado nao deve ficar la nem no historico de copias. */
+function clearClipboard() {
+  const opts = { stdio: ['pipe', 'ignore', 'ignore'], input: '' };
+  try {
+    if (process.platform === 'darwin') {
+      execFileSync('pbcopy', [], opts);
+    } else if (process.platform === 'win32') {
+      execFileSync('powershell', ['-NoProfile', '-Command', 'Set-Clipboard -Value $null'], { stdio: 'ignore' });
+    } else if (hasCommand('xclip')) {
+      execFileSync('xclip', ['-selection', 'clipboard', '-i'], opts);
+    } else if (hasCommand('xsel')) {
+      execFileSync('xsel', ['--clipboard', '--clear'], { stdio: 'ignore' });
+    } else {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ─── Validacao online e persistencia ─────────────────────
 
 function testToken(token) {
@@ -177,18 +207,174 @@ function persistToken(token) {
     return 'variavel de ambiente do usuario (Windows)';
   }
 
-  // macOS: sempre ~/.zshenv (zsh e o shell padrao do sistema).
-  // Linux: ~/.bashrc se o shell for bash, senao ~/.zshenv.
-  const shell = process.env.SHELL || '';
-  const envFile = (process.platform !== 'darwin' && shell.includes('bash'))
-    ? path.join(os.homedir(), '.bashrc')
-    : path.join(os.homedir(), '.zshenv');
-
+  const envFile = envFilePath();
+  const problem = envFileProblem();
+  if (problem) throw new Error(problem);
   const existing = fs.existsSync(envFile) ? fs.readFileSync(envFile, 'utf8') : '';
-  fs.writeFileSync(envFile, upsertEnvFileContent(existing, token), { mode: 0o600 });
+  writeFileAtomic(envFile, upsertEnvFileContent(existing, token));
   return envFile.replace(os.homedir(), '~');
 }
 
+/** O arquivo esta no git? Alem do repositorio normal, olha os de dotfiles "bare" mais comuns (~/.cfg, yadm...). */
+function isTrackedByGit(file) {
+  const name = path.basename(file);
+  const home = os.homedir();
+  const attempts = [['-C', path.dirname(file), 'ls-files', '--error-unmatch', '--', name]];
+  if (path.dirname(file) === home) {
+    const bare = [process.env.GIT_DIR, ...['.cfg', '.dotfiles', '.dotfiles.git', '.local/share/yadm/repo.git', '.config/yadm/repo.git'].map((p) => path.join(home, p))];
+    for (const dir of bare.filter(Boolean)) {
+      try {
+        if (fs.statSync(dir).isDirectory()) attempts.push([`--git-dir=${dir}`, `--work-tree=${home}`, 'ls-files', '--error-unmatch', '--', name]);
+      } catch { /* nao existe */ }
+    }
+  }
+  return attempts.some((args) => {
+    try {
+      execFileSync('git', args, { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false; // git ausente, fora de repositorio ou arquivo nao rastreado
+    }
+  });
+}
+
+/** Linha do aluno que define a variavel de outro jeito (ex.: busca no Keychain): o valor nao e um token. */
+function hasDynamicTokenDefinition(content) {
+  return String(content || '').split('\n').some((line) => {
+    const m = line.match(/^\s*(?:export\s+)?OP_SERVICE_ACCOUNT_TOKEN=(.*)$/);
+    if (!m) return false;
+    const value = m[1].trim().replace(/^(['"])(.*)\1$/, '$2');
+    return value !== '' && !isValidToken(value);
+  });
+}
+
+/**
+ * Por que NAO da para gravar a chave no arquivo de ambiente (ou null se da). Roda ANTES de criar o cofre
+ * e a conta de servico, porque depois que a chave nasce ela so aparece uma vez:
+ *  - atalho (link) para outro lugar ou arquivo no git (dotfiles): um `git push` mandaria a chave, que
+ *    escreve no cofre Claude, para o GitHub;
+ *  - linha do aluno que ja define a variavel de outro jeito: sobrescrever apagaria o mecanismo dele;
+ *  - sem permissao de escrita.
+ * No Windows a chave vai para a variavel do usuario: nao se aplica.
+ */
+function envFileProblem() {
+  if (process.platform === 'win32') return null;
+  const file = envFilePath();
+  const name = path.basename(file);
+  let st = null;
+  try { st = fs.lstatSync(file); } catch { /* ainda nao existe: tudo bem */ }
+  if (st && st.isSymbolicLink()) {
+    return `${name} e um atalho (link) para outro lugar; nao gravo a chave nele para ela nao ir parar num repositorio`;
+  }
+  if (st && isTrackedByGit(file)) {
+    return `${name} esta versionado no git; nao gravo a chave nele para ela nao ir parar no GitHub`;
+  }
+  if (st) {
+    let content = '';
+    try { content = fs.readFileSync(file, 'utf8'); } catch { return `${name} nao pode ser lido`; }
+    if (hasDynamicTokenDefinition(content)) {
+      return `${name} ja define OP_SERVICE_ACCOUNT_TOKEN de outro jeito (uma linha sua que busca o valor em outro lugar); nao vou apagar a sua linha`;
+    }
+  }
+  try {
+    fs.accessSync(st ? file : path.dirname(file), fs.constants.W_OK);
+  } catch {
+    return `${name} (ou a pasta dele) nao aceita escrita`;
+  }
+  return null;
+}
+
+/**
+ * Escreve por arquivo temporario criado ja com permissao 0600 na mesma pasta + rename: o token nunca
+ * fica legivel por outros, e uma falha no meio (disco cheio) nao trunca o arquivo que o aluno ja tinha.
+ */
+function writeFileAtomic(file, content) {
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.auroq-${process.pid}.tmp`);
+  let fd = null;
+  try {
+    fd = fs.openSync(tmp, 'wx', 0o600);
+    fs.writeSync(fd, content);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    if (fd !== null) { try { fs.closeSync(fd); } catch { /* ja fechado */ } }
+    try { fs.unlinkSync(tmp); } catch { /* nao chegou a existir */ }
+    throw e;
+  }
+}
+
+// Qual shell o aluno usa (SHELL; reserva: o shell de login do usuario): 'zsh' | 'bash' | 'outro'.
+function shellKind() {
+  let shell = process.env.SHELL || '';
+  if (!shell) {
+    try { shell = os.userInfo().shell || ''; } catch { shell = ''; }
+  }
+  const base = path.basename(shell).toLowerCase();
+  if (base.includes('zsh')) return 'zsh';
+  if (base.includes('bash')) return 'bash';
+  return 'outro';
+}
+
+// Arquivo que o terminal NOVO do aluno le sozinho:
+//   macOS: ~/.zshenv (zsh e o padrao do sistema); com bash, ~/.bash_profile.
+//   Linux: ~/.bashrc (bash), ~/.zshenv (zsh) ou ~/.profile (sh/dash/ksh).
+function envFilePath() {
+  const kind = shellKind();
+  const home = os.homedir();
+  if (process.platform === 'darwin') return path.join(home, kind === 'bash' ? '.bash_profile' : '.zshenv');
+  if (kind === 'bash') return path.join(home, '.bashrc');
+  if (kind === 'zsh') return path.join(home, '.zshenv');
+  return path.join(home, '.profile');
+}
+
+// Como abrir um shell NOVO que leia exatamente o arquivo acima.
+function freshShellFor(file) {
+  const name = path.basename(file);
+  if (name === '.zshenv') return { bin: 'zsh', flag: '-c' };
+  if (name === '.bashrc') return { bin: 'bash', flag: '-ic' };
+  if (name === '.bash_profile') return { bin: 'bash', flag: '-lc' };
+  return { bin: 'sh', flag: '-lc' };
+}
+
+/**
+ * Le o token da LINHA que o Auroq grava no arquivo de ambiente (ultima definicao vence).
+ * Devolve null se nao ha linha. Aceita aspas simples, duplas ou nenhuma.
+ */
+function parseEnvFileToken(content) {
+  let found = null;
+  for (const line of String(content || '').split('\n')) {
+    const m = line.match(/^\s*(?:export\s+)?OP_SERVICE_ACCOUNT_TOKEN=(.*)$/);
+    if (!m) continue;
+    found = m[1].trim().replace(/^(['"])(.*)\1$/, '$2');
+  }
+  return found || null;
+}
+
+/** O que um terminal NOVO vai enxergar: arquivo de ambiente (Mac/Linux) ou variavel do usuario (Windows). */
+function readPersistedToken() {
+  if (process.platform === 'win32') {
+    const run = (script) => {
+      try {
+        return execFileSync('powershell', ['-NoProfile', '-Command', script], { stdio: 'pipe', encoding: 'utf8' }).trim();
+      } catch {
+        return '';
+      }
+    };
+    const viaDotNet = run(`[Environment]::GetEnvironmentVariable('${TOKEN_VAR}', 'User')`);
+    if (viaDotNet) return viaDotNet;
+    // Modo restrito (Constrained Language): le do registro, par do fallback do persistToken.
+    return run(`(Get-ItemProperty -Path 'HKCU:\\Environment' -Name '${TOKEN_VAR}' -ErrorAction SilentlyContinue).${TOKEN_VAR}`) || null;
+  }
+  try {
+    const file = envFilePath();
+    return fs.existsSync(file) ? parseEnvFileToken(fs.readFileSync(file, 'utf8')) : null;
+  } catch {
+    return null;
+  }
+}
+
 // ─── Comando principal ───────────────────────────────────
 
 // Orientacao de escopo: o token fica salvo no computador e qualquer programa do
@@ -204,8 +390,8 @@ function accessTips() {
   log(`  ${DIM}  com o cofre dedicado, um vazamento so alcanca o que esta nele.${RESET}`);
 }
 
-async function connect() {
-  console.log(`\n${PURPLE}${BOLD}  Conectar 1Password — Auroq OS${RESET}`);
+async function connectManual() {
+  console.log(`\n${PURPLE}${BOLD}  Conectar 1Password — Auroq OS (modo manual)${RESET}`);
 
   // 1. Garantir que o op existe
   step('Verificando 1Password CLI...');
@@ -258,6 +444,8 @@ async function connect() {
   step('Salvando conexao...');
   const where = persistToken(token);
   ok(`Token salvo em ${where}`);
+  if (clearClipboard()) ok('Area de transferencia limpa (o token nao fica copiado)');
+  else warn('Nao consegui limpar a area de transferencia: copie outra coisa por cima (no Windows, apague tambem o historico com Win + V).');
 
   // 5. Resultado
   const restartHint = process.platform === 'win32'
@@ -277,9 +465,1114 @@ ${restartHint}
   log('');
 }
 
+// ─── Fluxo automatico (conta de servico criada pela sessao do aluno) ──────
+
+const VAULT_NAME = 'Claude';
+const SERVICE_ACCOUNT_NAME = 'Auroq';
+// `op service-account create` so existe desde a 2.26.0 e `op whoami` so diz QUEM esta falando (conta de
+// servico ou pessoa) desde a 2.30.0; o teste final precisa dessa resposta, entao o minimo e a 2.30.0.
+const MIN_OP_VERSION = '2.30.0';
+const INTEGRATION_URL = 'onepassword://settings/developers'; // abre o app direto em Configuracoes > Desenvolvedor
+const BACKUP_TITLE = 'Auroq OS - token da conta de servico';
+const BACKUP_TAG = 'auroq-os';
+// Contas pessoais (Individual e Families) entram em my.1password.<regiao>; Teams e Business em <time>.1password.*.
+const PERSONAL_ACCOUNT_URL = /^my\.1password\.(com|eu|ca)$/;
+const LOCK_STALE_MS = 2 * 60 * 60 * 1000;
+const MAX_WAIT_SECONDS = 30 * 60; // espera da chave do app nunca passa disso (a trava de instancia vale 2 h)
+// "Aguardando" (falta uma acao do aluno) e uma ETAPA do fluxo, nao falha: sai com 0 e a linha
+// AUROQ_RESULTADO diz o que falta. Sair com erro faria a telemetria do instalador registrar
+// INSTALL_FAILED para todo aluno que ainda nao ligou a chave no app.
+const EXIT_CODE = { ok: 0, aguardando: 0, erro: 1 };
+
+// ─── Helpers puros (testaveis) ───────────────────────────
+
+function parseVersion(text) {
+  const m = String(text || '').match(/(\d+)\.(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+function isVersionAtLeast(version, min = MIN_OP_VERSION) {
+  const have = parseVersion(version);
+  const need = parseVersion(min);
+  if (!have || !need) return false;
+  for (let i = 0; i < 3; i++) {
+    if (have[i] !== need[i]) return have[i] > need[i];
+  }
+  return true;
+}
+
+/** Tira qualquer coisa com cara de token de um texto antes de mostrar. */
+function redact(text) {
+  return String(text || '').replace(/ops_[A-Za-z0-9_=+/.-]{10,}/g, 'ops_[oculto]');
+}
+
+/**
+ * Uma linha so, sem token e sem o prefixo "[ERROR] data hora" do op. Normaliza ANTES de redigir:
+ * um token cortado por codigo de cor ou quebra de linha precisa voltar a ser uma peca so para ser pego.
+ */
+function oneLine(text, max = 300) {
+  const flat = String(text || '')
+    .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, '') // OSC (titulo de janela, area de transferencia...)
+    .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '') // cores e movimento de cursor
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, '') // controle sem efeito visivel
+    .replace(/[\n\r\u0085\u2028\u2029\t]+/g, ' ');
+  return redact(flat)
+    .replace(/\[(ERROR|WARNING)\]\s+\d{4}\/\d{2}\/\d{2}\s+\d{2}:\d{2}:\d{2}\s*/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+/** Pega o token (ops_...) de dentro da saida de `--raw`, ignorando qualquer outra linha. */
+function extractToken(stdout) {
+  for (const piece of String(stdout || '').split(/\s+/)) {
+    if (isValidToken(piece)) return piece;
+  }
+  return null;
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    // Shell interativo (.bashrc que escreve na tela): fica so com o trecho entre colchetes/chaves.
+    const t = String(text || '');
+    for (const [open, close] of [['[', ']'], ['{', '}']]) {
+      const a = t.indexOf(open);
+      const b = t.lastIndexOf(close);
+      if (a !== -1 && b > a) {
+        try {
+          return JSON.parse(t.slice(a, b + 1));
+        } catch {
+          /* tenta o proximo formato */
+        }
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * Ambiente do `op` filho. Sem token: sessao do aluno (app). Com token: so a conta de servico.
+ * O token do ambiente atual, a conexao do Connect e o modo debug SEMPRE saem: o primeiro faria o
+ * `op` ignorar o app, o segundo tem prioridade sobre tudo e o terceiro escreve detalhes na tela.
+ * `isolate` (so com token) desliga tambem a integracao com o app, para o teste valer so pelo token.
+ */
+function opEnv(token, { isolate = false } = {}) {
+  const env = { ...process.env };
+  const drop = new Set([TOKEN_VAR, 'OP_CONNECT_HOST', 'OP_CONNECT_TOKEN', 'OP_BIOMETRIC_UNLOCK_ENABLED', 'OP_DEBUG', 'OP_FORMAT']);
+  for (const k of Object.keys(env)) {
+    if (drop.has(k.toUpperCase())) delete env[k];
+  }
+  if (token) {
+    env[TOKEN_VAR] = token;
+    if (isolate) env.OP_BIOMETRIC_UNLOCK_ENABLED = 'false';
+  }
+  return env;
+}
+
+/** Classifica a falha de um comando do `op` pelo texto de erro (o `op` fala ingles). */
+function classifyFailure(r) {
+  if (r && r.timedOut) return 'tempo';
+  const text = String((r && r.stderr) || '').toLowerCase();
+  if (/(429|too many requests|rate.?limit)/.test(text)) return 'limite';
+  if (/(dial tcp|no such host|network|connection refused|connection reset|timed out|timeout|offline|tls handshake|certificate)/.test(text)) return 'rede';
+  if (/(no active session|not signed in|no accounts? configured|no account found)/.test(text)) return 'sem-sessao';
+  if (/(forbidden|not authorized|unauthorized|permission|not allowed|insufficient|denied|only .*owner|administrator)/.test(text)) return 'permissao';
+  if (/(authoriz|locked|biometric|integration|sign in|signin)/.test(text)) return 'sessao';
+  return 'falha';
+}
+
+/**
+ * Falha de um comando feito COM o token da conta de servico. So "token-invalido" (recusa de
+ * autenticacao clara do 1Password) prova que o token morreu; limite de uso, rede, tempo, resposta de
+ * proxy, erro de disco ou qualquer texto desconhecido sao inconclusivos e NUNCA podem levar a criar
+ * outra conta de servico nem a arquivar a copia que ainda pode estar boa.
+ */
+const TOKEN_DEAD_RE = /(not authorized|\(401\)|\bunauthori[sz]ed\b|\brevoked\b|token\b[^.\n]{0,40}\b(?:invalid|expired|deleted|disabled)\b|\binvalid\b[^.\n]{0,30}\btoken\b|service account\b[^.\n]{0,40}\b(?:deleted|disabled)\b)/i;
+
+function classifyTokenFailure(r) {
+  const c = classifyFailure(r);
+  if (c === 'tempo' || c === 'rede' || c === 'limite') return c;
+  return TOKEN_DEAD_RE.test(String((r && r.stderr) || '')) ? 'token-invalido' : 'falha';
+}
+
+const WHY = {
+  limite: 'o 1Password limitou os acessos por enquanto (limite de uso)',
+  rede: 'sem conexao com o 1Password',
+  tempo: 'o 1Password demorou demais para responder',
+  falha: 'resposta inesperada do 1Password',
+  'resposta-estranha': 'resposta inesperada do 1Password',
+};
+
+function normalizeAddress(value) {
+  return String(value || '').trim().toLowerCase().replace(/^https?:\/\//, '').replace(/\/+$/, '');
+}
+
+function accountLabel(a) {
+  return `${a.email || 'conta sem e-mail'} (${a.url || 'endereco desconhecido'})`;
+}
+
+function accountKey(a) {
+  return a.account_uuid || a.user_uuid || a.shorthand || a.url;
+}
+
+function isPersonalAccount(a) {
+  return PERSONAL_ACCOUNT_URL.test(normalizeAddress(a && a.url));
+}
+
+/**
+ * Escolhe a conta do app. Com varias contas NAO adivinha: criar a chave na conta errada
+ * (a da empresa, por exemplo) seria pior que perguntar.
+ * Devolve { conta } ou { erro: 'nenhuma' | 'varias' | 'nao-achou' | 'ambigua' }.
+ */
+function pickAccount(accounts, wanted) {
+  const list = Array.isArray(accounts) ? accounts : [];
+  if (!list.length) return { erro: 'nenhuma' };
+  if (wanted) {
+    const w = normalizeAddress(wanted);
+    const hit = list.filter((a) => [a.email, a.url, a.account_uuid, a.user_uuid, a.shorthand]
+      .some((v) => v && normalizeAddress(v) === w));
+    if (hit.length === 1) return { conta: hit[0] };
+    return { erro: hit.length ? 'ambigua' : 'nao-achou' };
+  }
+  return list.length === 1 ? { conta: list[0] } : { erro: 'varias' };
+}
+
+/** Argumentos de `auroq-os conectar-1password [...]`. */
+function parseArgs(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  const opts = { manual: false, rotacionar: false, agente: false, estado: false, conta: null, esperar: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--manual') opts.manual = true;
+    else if (a === '--rotacionar') opts.rotacionar = true;
+    else if (a === '--agente') opts.agente = true;
+    else if (a === '--estado') opts.estado = true;
+    else if (a === '--conta' && args[i + 1] && !args[i + 1].startsWith('--')) opts.conta = args[++i];
+    else if (a.startsWith('--conta=')) opts.conta = a.slice('--conta='.length) || null;
+    else if (a === '--esperar' && args[i + 1] && !args[i + 1].startsWith('--')) opts.esperar = Number(args[++i]);
+    else if (a.startsWith('--esperar=')) opts.esperar = Number(a.slice('--esperar='.length));
+  }
+  if (opts.esperar !== null && (!Number.isFinite(opts.esperar) || opts.esperar < 0)) opts.esperar = null;
+  return opts;
+}
+
+/** Receita de bolo para ligar a chave no app (o que o aluno faz uma vez so). */
+function enableIntegrationSteps(platform) {
+  const abrir = platform === 'darwin'
+    ? 'Abra as Configuracoes: no menu de cima do Mac, 1Password > Configuracoes (ou Cmd + virgula). Se eu ja abri a tela de Desenvolvedor pra voce, pule pro passo 3.'
+    : 'Abra as Configuracoes: clique no nome da sua conta (canto de cima, a esquerda) > Configuracoes. Se eu ja abri a tela de Desenvolvedor pra voce, pule pro passo 3.';
+  const digital = platform === 'darwin'
+    ? 'Para aprovar com a digital: Configuracoes > Seguranca > "Desbloquear com Touch ID". Sem isso o app pede a senha do Mac.'
+    : 'Para aprovar com o Windows Hello: Configuracoes > Seguranca > "Desbloquear com Windows Hello". Sem isso o app pede a senha.';
+  return [
+    'Abra o app do 1Password, entre na sua conta e deixe o app aberto.',
+    abrir,
+    'Clique em "Desenvolvedor" (Developer) e marque "Integrar com a CLI do 1Password" (Integrate with 1Password CLI).',
+    digital,
+  ];
+}
+
+// ─── Dependencias reais (trocaveis nos testes) ───────────
+
+/**
+ * Roda o `op`. Nunca lanca. A saida pode ter segredo (token): quem chama decide o que mostrar.
+ * O token NUNCA vai em `args`: so por `env` ou por `input` (stdin).
+ */
+function runOp(args, { env, input, timeoutMs = 120000 } = {}) {
+  // Sem texto para mandar e com terminal de verdade: o `op` herda o terminal, como se o aluno
+  // tivesse digitado (a aprovacao do app e amarrada ao terminal; com pipe nao ha terminal).
+  const useTerminal = input === undefined && Boolean(process.stdin.isTTY);
+  const r = spawnSync('op', args, {
+    encoding: 'utf8',
+    env: env || opEnv(),
+    ...(useTerminal ? { stdio: ['inherit', 'pipe', 'pipe'] } : { input: input === undefined ? '' : input }),
+    timeout: timeoutMs,
+    maxBuffer: 16 * 1024 * 1024,
+    windowsHide: true,
+  });
+  return {
+    ok: !r.error && r.status === 0,
+    status: r.status,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+    timedOut: !!(r.error && r.error.code === 'ETIMEDOUT'),
+    missing: !!(r.error && r.error.code === 'ENOENT'),
+  };
+}
+
+/**
+ * "Terminal novo": no Mac/Linux abre um shell de verdade, que le sozinho o arquivo de ambiente
+ * (o token do processo atual sai do ambiente, entao so o arquivo conta). No Windows um processo
+ * filho herda o ambiente deste, entao usa o valor que um terminal novo leria (variavel do usuario).
+ */
+function runOpInFreshShell(args) {
+  if (process.platform === 'win32') {
+    const persisted = readPersistedToken();
+    return runOp(args, { env: opEnv(persisted || undefined) });
+  }
+  const { bin, flag } = freshShellFor(envFilePath());
+  const quoted = ['op', ...args].map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(' ');
+  const r = spawnSync(bin, [flag, quoted], {
+    encoding: 'utf8',
+    env: opEnv(),
+    input: '',
+    timeout: 60000,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  return {
+    ok: !r.error && r.status === 0,
+    status: r.status,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+    timedOut: !!(r.error && r.error.code === 'ETIMEDOUT'),
+    missing: !!(r.error && r.error.code === 'ENOENT'),
+  };
+}
+
+/**
+ * Abre um endereco no programa certo do sistema (aqui, a tela do app). Melhor esforco: nunca lanca.
+ * `AUROQ_NAO_ABRIR_APP=1` (usado nos testes) desliga. O filho nao herda o token do ambiente.
+ */
+function openUrl(url) {
+  if (process.env.AUROQ_NAO_ABRIR_APP) return;
+  try {
+    const [cmd, args] = process.platform === 'darwin'
+      ? ['open', [url]]
+      : (process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]]);
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true, env: opEnv() });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    /* sem problema: a receita escrita continua valendo */
+  }
+}
+
+/**
+ * Windows: o winget so muda o PATH no registro, nao no processo que ja esta rodando. Recompoe o
+ * PATH deste processo (maquina + usuario + pasta de links do winget) para achar o `op` recem-instalado.
+ */
+function refreshWindowsPath() {
+  if (process.platform !== 'win32') return;
+  const parts = [];
+  for (const scope of ['Machine', 'User']) {
+    try {
+      const v = execFileSync('powershell', ['-NoProfile', '-Command', `[Environment]::GetEnvironmentVariable('Path','${scope}')`], { stdio: 'pipe', encoding: 'utf8' }).trim();
+      if (v) parts.push(v);
+    } catch { /* modo restrito: segue com o que tem */ }
+  }
+  const links = process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, 'Microsoft', 'WinGet', 'Links') : null;
+  if (links && fs.existsSync(links)) parts.push(links);
+  if (parts.length) process.env.PATH = [...parts, process.env.PATH || ''].join(';');
+}
+
+// Pasta do aluno fora do git, a mesma onde ficam as credenciais do Auroq (~/.arcane). Aqui vivem a trava de
+// instancia unica e o estado das etapas (nenhum segredo).
+function auroqDir() {
+  const dir = path.join(os.homedir(), '.arcane');
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* sem pasta: quem usa trata */ }
+  return dir;
+}
+
+/**
+ * Trava de instancia unica: duas execucoes juntas criariam dois cofres e duas contas de servico.
+ * O arquivo guarda pid, hora e um codigo aleatorio; so quem tem o codigo apaga. A trava e velha se o dono
+ * morreu (Ctrl+C, terminal fechado), se o conteudo esta estragado ou se passou de 2 h (pid reaproveitado).
+ */
+function makeLock(name = '1password.lock') {
+  const lockPath = () => path.join(auroqDir(), name); // calculado so quando usa: criar o objeto nao toca no disco
+  const nonce = crypto.randomBytes(8).toString('hex');
+  let held = false;
+  const readInfo = () => {
+    try { return JSON.parse(fs.readFileSync(lockPath(), 'utf8')); } catch { return null; }
+  };
+  const stale = () => {
+    const info = readInfo();
+    if (!info || !Number.isInteger(info.pid) || info.pid <= 0 || !Number.isFinite(info.at)) return true;
+    const age = Date.now() - info.at;
+    if (age < -60000 || age > LOCK_STALE_MS) return true;
+    try {
+      process.kill(info.pid, 0);
+      return false;
+    } catch (e) {
+      return e.code === 'ESRCH'; // dono morreu
+    }
+  };
+  return {
+    acquire() {
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const file = lockPath();
+        try {
+          const fd = fs.openSync(file, 'wx', 0o600);
+          fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: Date.now(), nonce }));
+          fs.closeSync(fd);
+          held = true;
+          return true;
+        } catch (e) {
+          if (e.code !== 'EEXIST') return true; // sem como travar (permissao, disco): segue sem trava
+          if (!stale()) return false;
+          // toma a trava velha por rename atomico: dois processos vendo a mesma trava velha nao apagam um ao outro
+          try { fs.renameSync(file, `${file}.velha-${process.pid}-${attempt}`); fs.unlinkSync(`${file}.velha-${process.pid}-${attempt}`); } catch { /* outro pegou antes */ }
+        }
+      }
+      return false;
+    },
+    release() {
+      if (!held) return;
+      held = false;
+      const info = readInfo();
+      if (info && info.nonce === nonce) {
+        try { fs.unlinkSync(lockPath()); } catch { /* ja foi */ }
+      }
+    },
+  };
+}
+
+// ─── Estado das etapas (retomada) ────────────────────────
+//
+// O pipeline tem 8 etapas. O arquivo guarda so o que ja foi conferido e onde parou: nenhum segredo, nada
+// de e-mail. A fonte da verdade e sempre a conferencia ao vivo; o arquivo so deixa o Ops/Companion saber
+// em que etapa o aluno esta quando ele volta dias depois (ou em outro dia, em outra conversa).
+const ETAPAS = ['conta', 'app', 'op', 'aprovacao', 'cofre', 'chave', 'teste', 'pronto'];
+const ETAPA_NOME = {
+  conta: 'conta e plano do 1Password',
+  app: 'app instalado e chave "Integrar com a CLI" ligada',
+  op: 'ferramenta op instalada',
+  aprovacao: 'aprovacao com a digital',
+  cofre: 'cofre Claude',
+  chave: 'chave do agente (conta de servico) criada e guardada',
+  teste: 'teste em terminal novo',
+  pronto: 'pronto',
+};
+
+function stateFile() {
+  return path.join(auroqDir(), '1password-etapas.json');
+}
+
+function emptyEtapas() {
+  return Object.fromEntries(ETAPAS.map((e) => [e, 'pendente']));
+}
+
+/** Estado salvo (ou vazio). Nunca lanca: arquivo ausente ou estragado = comeca do zero. */
+function readState() {
+  try {
+    const data = JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
+    if (!data || typeof data !== 'object' || data.versao !== 1 || !data.etapas) return null;
+    const etapas = emptyEtapas();
+    for (const e of ETAPAS) if (data.etapas[e] === 'feito') etapas[e] = 'feito';
+    return { versao: 1, etapas, ultimo: data.ultimo || null, atualizado_em: data.atualizado_em || null };
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state) {
+  try {
+    writeFileAtomic(stateFile(), `${JSON.stringify(state, null, 2)}\n`);
+  } catch {
+    /* o estado e conforto, nunca motivo para falhar a conexao */
+  }
+}
+
+function nextStage(etapas) {
+  return ETAPAS.find((e) => etapas[e] !== 'feito') || null;
+}
+
+/** Acompanha as etapas durante uma execucao e grava o estado no fim. So avanca; recua so no que foi provado quebrado. */
+function makeProgress(d) {
+  const prev = d.state.read();
+  const etapas = prev ? { ...prev.etapas } : emptyEtapas();
+  return {
+    etapas,
+    mark(...stages) { for (const e of stages) etapas[e] = 'feito'; },
+    reset(...stages) { for (const e of stages) etapas[e] = 'pendente'; },
+    all() { this.mark(...ETAPAS); },
+    save(result) {
+      d.state.write({
+        versao: 1,
+        atualizado_em: new Date(d.now()).toISOString(),
+        etapas: { ...etapas },
+        proxima: nextStage(etapas),
+        ultimo: result ? { status: result.status, codigo: result.codigo } : null,
+      });
+    },
+  };
+}
+
+function makeDefaultDeps() {
+  return {
+    platform: process.platform,
+    openUrl,
+    refreshPath: refreshWindowsPath,
+    lock: makeLock(),
+    state: { read: readState, write: writeState },
+    envFileProblem,
+    op: runOp,
+    opInFreshShell: runOpInFreshShell,
+    opVersion,
+    installOp,
+    persistToken,
+    readPersistedToken,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    isTTY: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    env: process.env,
+    out: { log, step, ok, warn, err, tick: () => process.stdout.write('.') },
+  };
+}
+
+// ─── Etapas ──────────────────────────────────────────────
+
+function listAccounts(d) {
+  const r = d.op(['account', 'list', '--format', 'json'], { env: opEnv() });
+  const data = r.ok ? parseJson(r.stdout) : null;
+  return Array.isArray(data) ? data : [];
+}
+
+/**
+ * O que o token enxerga: precisa listar o cofre Claude e quem fala tem de ser a conta de servico
+ * (um token morto com o app aberto poderia "passar" pela sessao do aluno). Nunca mostra o token.
+ * `isolate`: desliga a integracao com o app no teste, para valer so pelo token.
+ * `expectAccount`: o token tem de ser da conta escolhida (nao adota token de outra conta).
+ * Falha: `motivo` 'token-invalido' = morreu; 'limite' | 'rede' | 'tempo' | 'falha' = inconclusivo.
+ */
+function checkToken(d, token, { runner, isolate = false, expectAccount = null } = {}) {
+  const run = runner || ((args) => d.op(args, { env: opEnv(token, { isolate }) }));
+  const r = run(['vault', 'list', '--format', 'json']);
+  if (!r.ok) return { ok: false, motivo: classifyTokenFailure(r), detalhe: oneLine(r.stderr) };
+  const data = parseJson(r.stdout);
+  if (!Array.isArray(data)) return { ok: false, motivo: 'resposta-estranha', detalhe: '' };
+  const who = run(['whoami', '--format', 'json']);
+  if (!who.ok) return { ok: false, motivo: classifyTokenFailure(who), detalhe: oneLine(who.stderr) };
+  const me = parseJson(who.stdout);
+  if (!me || me.user_type !== 'SERVICE_ACCOUNT') return { ok: false, motivo: 'app-tem-prioridade', detalhe: '' };
+  if (expectAccount) {
+    // O token tem de ser da conta escolhida. Sem identificador comparavel NAO adota (falha fechada).
+    if (expectAccount.account_uuid && me.account_uuid) {
+      if (String(me.account_uuid).toLowerCase() !== String(expectAccount.account_uuid).toLowerCase()) return { ok: false, motivo: 'conta-diferente', detalhe: '' };
+    } else if (expectAccount.url && me.url) {
+      if (normalizeAddress(me.url) !== normalizeAddress(expectAccount.url)) return { ok: false, motivo: 'conta-diferente', detalhe: '' };
+    } else {
+      return { ok: false, motivo: 'conta-nao-confirmada', detalhe: '' };
+    }
+  }
+  const nomes = data.map((v) => String((v && v.name) || '').trim());
+  const same = (n) => n.toLowerCase() === VAULT_NAME.toLowerCase();
+  return { ok: true, temClaude: nomes.some(same), nomes, extras: nomes.filter((n) => !same(n)) };
+}
+
+// Resultados em que repetir o teste nao muda nada.
+const NO_RETRY = new Set(['app-tem-prioridade', 'conta-diferente', 'conta-nao-confirmada']);
+
+/**
+ * Repete o teste so quando repetir pode mudar o resultado. `retryInvalid`: logo depois de criar a conta
+ * de servico, "token invalido" e "ainda sem o cofre" podem ser so atraso do 1Password.
+ */
+async function checkTokenWithRetry(d, token, options = {}, tries = 8) {
+  let last = null;
+  for (let i = 0; i < tries; i++) {
+    last = checkToken(d, token, options);
+    if (last.ok && last.temClaude) return last;
+    if (NO_RETRY.has(last.motivo)) return last; // repetir nao muda
+    if (!options.retryInvalid && (last.ok || last.motivo === 'token-invalido')) return last;
+    if (i < tries - 1) await d.sleep(Math.min(1500 * (i + 1), 6000));
+  }
+  return last;
+}
+
+function checkItems(d, runner) {
+  const run = runner || ((args) => d.op(args, { env: opEnv() }));
+  const r = run(['item', 'list', '--vault', VAULT_NAME, '--format', 'json']);
+  return r.ok && Array.isArray(parseJson(r.stdout));
+}
+
+// Molde "API Credential" (o que `op item template get "API Credential"` devolve na 2.38). O 1Password
+// recomenda partir do molde completo; so title, notas e credential recebem valor.
+function backupItemTemplate(token) {
+  const empty = (id, type, label, extra = {}) => ({ id, type, label, value: '', ...extra });
+  return {
+    title: BACKUP_TITLE,
+    category: 'API_CREDENTIAL',
+    fields: [
+      {
+        id: 'notesPlain',
+        type: 'STRING',
+        purpose: 'NOTES',
+        label: 'notesPlain',
+        value: `Token da conta de servico "${SERVICE_ACCOUNT_NAME}" (enxerga so o cofre ${VAULT_NAME}). Criado pelo Auroq OS. Nao apague: os outros computadores seus reaproveitam este token em vez de criar outro.`,
+      },
+      empty('username', 'STRING', 'username'),
+      { id: 'credential', type: 'CONCEALED', label: 'credential', value: token },
+      empty('type', 'MENU', 'type'),
+      empty('filename', 'STRING', 'filename'),
+      empty('validFrom', 'DATE', 'valid from'),
+      empty('expires', 'DATE', 'expires'),
+      empty('hostname', 'STRING', 'hostname'),
+    ],
+  };
+}
+
+/** Guarda uma copia do token no cofre pessoal do aluno (a conta de servico nao enxerga esse cofre). */
+function saveBackup(d, account, token) {
+  // Sem --vault: o `op` guarda no cofre pessoal da conta, que se chama Personal, Private ou Employee
+  // conforme o plano (e pode vir traduzido), por isso nunca se usa o nome.
+  const r = d.op(
+    ['item', 'create', '-', '--tags', BACKUP_TAG, '--account', accountKey(account), '--format', 'json'],
+    { env: opEnv(), input: JSON.stringify(backupItemTemplate(token)) },
+  );
+  return r.ok ? { ok: true } : { ok: false, detalhe: oneLine(r.stderr) };
+}
+
+/**
+ * Copias do token ja guardadas (mais nova primeiro). `ok:false` = nao deu para ler a lista.
+ * A busca pega todos os cofres a que a conta tem acesso; quem adota uma copia confere que o token e
+ * da MESMA conta (checkToken com `expectAccount`), entao item plantado em cofre compartilhado nao serve.
+ */
+function findBackups(d, account) {
+  const r = d.op(['item', 'list', '--tags', BACKUP_TAG, '--account', accountKey(account), '--format', 'json'], { env: opEnv() });
+  const list = r.ok ? parseJson(r.stdout) : null;
+  if (!Array.isArray(list)) return { ok: false, itens: [] };
+  return {
+    ok: true,
+    itens: list
+      .filter((i) => i && i.id && i.title === BACKUP_TITLE)
+      .sort((a, b) => String(b.updated_at || '').localeCompare(String(a.updated_at || '')))
+      .map((i) => ({ id: i.id, vaultId: i.vault && i.vault.id ? i.vault.id : null })),
+  };
+}
+
+const FIELD_MISSING_RE = /(isn't a field|is not a field|no field|field[^.\n]{0,30}not found|could not be found|isn't an item|not found)/i;
+
+/**
+ * Le o token da copia: `op read` (a via documentada para um valor so), com `item get` de reserva.
+ * Devolve { token } | {} (o item nao tem token valido: nao e nosso, ignora) | { erro: true } (nao deu para
+ * ler agora; `incerto` = motivo desconhecido, que pode ser permanente).
+ */
+function readBackupToken(d, account, backup) {
+  const acct = accountKey(account);
+  if (backup.vaultId) {
+    const r = d.op(['read', `op://${backup.vaultId}/${backup.id}/credential`, '--account', acct], { env: opEnv() });
+    const value = r.ok ? r.stdout.trim() : '';
+    if (isValidToken(value)) return { token: value };
+  }
+  const g = d.op(['item', 'get', backup.id, '--fields', 'label=credential', '--reveal', '--account', acct, '--format', 'json'], { env: opEnv() });
+  if (!g.ok) {
+    if (FIELD_MISSING_RE.test(String(g.stderr || ''))) return {};
+    return { erro: true, incerto: classifyFailure(g) === 'falha' };
+  }
+  const data = parseJson(g.stdout);
+  const field = Array.isArray(data) ? data[0] : data;
+  const value = String(typeof field === 'string' ? field : (field && typeof field.value === 'string' ? field.value : g.stdout)).trim();
+  return isValidToken(value) ? { token: value } : {};
+}
+
+function archiveBackups(d, account, ids) {
+  for (const id of ids) {
+    d.op(['item', 'delete', id, '--archive', '--account', accountKey(account)], { env: opEnv() });
+  }
+}
+
+function fim(status, codigo, mensagem, extra = {}) {
+  return { status, codigo, mensagem, ...extra };
+}
+
+function showIntegrationHelp(d, out) {
+  out.warn('O app do 1Password ainda nao esta ligado ao terminal. Falta uma chave, uma vez so:');
+  d.openUrl(INTEGRATION_URL); // leva o app direto para Configuracoes > Desenvolvedor
+  enableIntegrationSteps(d.platform).forEach((line, i) => out.log(`  ${i + 1}. ${line}`));
+  out.log('');
+}
+
+const APP_PRIORITY_MSG = 'O 1Password continua respondendo pelo app (pedindo digital) em vez de usar a chave. Sem isso o agente nao fica sem pedir digital. Nao criei nada novo; peca ajuda ao Arcano com este codigo: app-tem-prioridade.';
+const NET_STRONG_RE = /(dial tcp|no such host|tls handshake|network is unreachable|no route to host|i\/o timeout)/i;
+
+// Erros que o aluno (ou o plano dele) resolve: a linha AUROQ_RESULTADO ja diz o que fazer. Saem com 1 mas a
+// telemetria do instalador nao os conta como instalacao quebrada.
+const STUDENT_ACTIONABLE = new Set(['sem-op', 'op-antigo', 'rede', 'conta-nao-encontrada', 'conta-ambigua', 'cofre-duplicado', 'sem-permissao', 'token-indisponivel', 'arquivo-ambiente']);
+
+function isStudentActionable(codigo) {
+  return STUDENT_ACTIONABLE.has(codigo);
+}
+
+/**
+ * Conecta o 1Password ao Auroq sem o aluno tocar em token.
+ *
+ * @param {object} opts   { rotacionar, conta, esperar (segundos), agente }
+ * @param {object} deps   so para teste: troca o `op`, o disco, o relogio e a tela
+ * @returns {Promise<{status:'ok'|'aguardando'|'erro', codigo:string, mensagem:string, contas?:string[]}>}
+ */
+async function connectAutomatic(opts = {}, deps = {}) {
+  const d = { ...makeDefaultDeps(), ...deps };
+  if (!d.lock.acquire()) {
+    return fim('aguardando', 'outra-execucao', 'Ja tem outra execucao do conectar-1password em andamento neste computador. Espere ela terminar (ate uns 15 minutos) e rode de novo; nao abri nada em duplicidade.');
+  }
+  const prog = makeProgress(d);
+  let result = null;
+  try {
+    result = await runConnect(opts, d, prog);
+    return result;
+  } catch (e) {
+    result = fim('erro', 'falha', `Falha inesperada: ${oneLine(e && e.message)}`);
+    throw e;
+  } finally {
+    prog.save(result);
+    d.lock.release();
+  }
+}
+
+async function runConnect(opts, d, prog) {
+  const out = d.out;
+  const waitSeconds = Math.min(MAX_WAIT_SECONDS, opts.esperar !== null && opts.esperar !== undefined
+    ? opts.esperar
+    : (opts.agente || !d.isTTY() ? 0 : 300));
+
+  out.step('Verificando 1Password CLI...');
+  d.refreshPath(); // Windows: o winget (do Ops ou do aluno) so muda o PATH no registro, nao neste processo
+  let version = d.opVersion();
+  if (!version) {
+    out.warn('1Password CLI (op) nao encontrado — instalando...');
+    if (!d.installOp()) return fim('erro', 'sem-op', 'Nao consegui instalar o 1Password CLI (op).');
+    d.refreshPath();
+    version = d.opVersion();
+    if (!version) {
+      return fim('erro', 'sem-op', 'O op foi instalado mas nao aparece no PATH. Feche e abra o terminal (ou o programa inteiro) e rode de novo.');
+    }
+  }
+  if (!isVersionAtLeast(version)) {
+    out.warn(`1Password CLI v${version} e antigo (precisa da ${MIN_OP_VERSION} ou mais) — atualizando...`);
+    if (d.installOp({ upgrade: true })) {
+      d.refreshPath();
+      version = d.opVersion() || version;
+    }
+    if (!isVersionAtLeast(version)) {
+      return fim('erro', 'op-antigo', `O 1Password CLI v${version} e antigo (precisa da ${MIN_OP_VERSION} ou mais) e nao consegui atualizar sozinho.`);
+    }
+  }
+  prog.mark('op');
+  out.ok(`1Password CLI v${version}`);
+
+  // 1. Ja esta conectado? (token deste processo ou o gravado no computador)
+  if (opts.rotacionar) {
+    prog.reset('chave', 'teste', 'pronto');
+  } else {
+    const persisted = d.readPersistedToken();
+    const candidates = [d.env[TOKEN_VAR], persisted].filter((t, i, all) => t && isValidToken(t) && all.indexOf(t) === i);
+    let broken = false;
+    let foreign = false;
+    for (const token of candidates) {
+      const check = await checkTokenWithRetry(d, token, {}, 3);
+      if (check.ok && check.temClaude) {
+        if (token === persisted) {
+          // "Conectado" so vale se um terminal NOVO tambem enxerga a chave (outro shell pode ler outro arquivo)
+          const fresh = checkToken(d, null, { runner: (args) => d.opInFreshShell(args) });
+          if ((!fresh.ok && fresh.motivo === 'app-tem-prioridade') || (fresh.ok && !fresh.temClaude)) {
+            return fim('erro', 'nao-gravou', 'A chave esta gravada neste computador, mas um terminal novo nao a enxerga (o seu terminal parece ler outro arquivo de configuracao). Peca ajuda ao Arcano com o codigo nao-gravou; nao criei nada novo.');
+          }
+        }
+        out.ok(`Ja conectado: o token deste computador enxerga o cofre ${VAULT_NAME}.`);
+        if (check.extras.length) {
+          out.warn(`Esse token tambem enxerga ${check.extras.length} outro(s) cofre(s). Para deixar so o ${VAULT_NAME}, rode de novo com --rotacionar.`);
+        }
+        prog.all();
+        return fim('ok', 'ja-conectado', `Ja conectado: o token enxerga o cofre ${VAULT_NAME}.`, check.extras.length ? { aviso: 'cofres-extras' } : {});
+      }
+      if (!check.ok && check.motivo === 'app-tem-prioridade') return fim('erro', 'app-tem-prioridade', APP_PRIORITY_MSG);
+      if (!check.ok && check.motivo !== 'token-invalido') {
+        // Nao deu para conferir agora (limite de uso, rede, resposta estranha...): NAO e prova de token morto.
+        // Criar outra conta de servico aqui duplicaria a chave a cada tentativa.
+        return fim('erro', 'token-indisponivel', `Nao consegui conferir a chave deste computador agora (${WHY[check.motivo] || WHY.falha}). Nao criei nada novo, para nao duplicar. Tente de novo em alguns minutos; se continuar assim por mais de uma hora, a chave pode ter sido revogada: rode com --rotacionar.`);
+      }
+      if (check.ok) foreign = true;
+      else broken = true;
+    }
+    if (broken || foreign) prog.reset('chave', 'teste', 'pronto');
+    if (broken) {
+      out.warn('O token que estava salvo neste computador nao funciona mais (revogado, vencido ou o endereco de login da conta mudou). Vou gerar um novo.');
+    } else if (foreign) {
+      out.warn(`O token salvo neste computador e de outra conta de servico (nao enxerga o cofre ${VAULT_NAME}). O Auroq vai passar a usar o proprio.`);
+    }
+  }
+
+  // Antes de criar QUALQUER coisa: a chave so aparece uma vez, entao tem de haver onde guarda-la.
+  const envProblem = d.envFileProblem();
+  if (envProblem) {
+    return fim('erro', 'arquivo-ambiente', `Nao criei nada. ${envProblem}. Peca ajuda ao Arcano com o codigo arquivo-ambiente.`);
+  }
+
+  // 2. Sessao do aluno: o app do 1Password com a chave "Integrate with 1Password CLI" ligada
+  out.step('Procurando a sua conta no app do 1Password...');
+  let accounts = listAccounts(d);
+  if (!accounts.length) {
+    showIntegrationHelp(d, out);
+    if (waitSeconds > 0) {
+      out.log(`${DIM}Fico esperando ate ${Math.round(waitSeconds / 60) || 1} min. Pode ligar agora.${RESET}`);
+      const start = d.now();
+      while (!accounts.length && d.now() - start < waitSeconds * 1000) {
+        await d.sleep(3000);
+        out.tick();
+        accounts = listAccounts(d);
+      }
+      out.log('');
+    }
+    if (!accounts.length) {
+      prog.reset('app');
+      return fim('aguardando', 'ligar-integracao', 'Falta ligar "Integrate with 1Password CLI" nas configuracoes do app do 1Password (Configuracoes > Desenvolvedor). Depois e so rodar de novo.');
+    }
+  }
+  prog.mark('conta', 'app');
+
+  const labels = accounts.map(accountLabel);
+  const picked = pickAccount(accounts, opts.conta);
+  if (picked.erro === 'varias') {
+    out.warn('Tem mais de uma conta no app. Escolha em qual vai ficar o cofre do Auroq:');
+    labels.forEach((l) => out.log(`  - ${l}`));
+    return fim('aguardando', 'escolher-conta', 'Tem mais de uma conta no app do 1Password. Diga qual usar e rode de novo com --conta "<e-mail>" (se dois e-mails forem iguais, use o endereco de login, ex.: --conta "my.1password.com").', { contas: labels });
+  }
+  if (picked.erro === 'ambigua') {
+    return fim('erro', 'conta-ambigua', `Mais de uma conta combina com "${opts.conta}". Use o endereco de login da conta, ex.: --conta "my.1password.com".`, { contas: labels });
+  }
+  if (picked.erro === 'nao-achou') {
+    return fim('erro', 'conta-nao-encontrada', `Nao achei a conta "${opts.conta}" no app do 1Password.`, { contas: labels });
+  }
+  const account = picked.conta;
+  if (!opts.conta && !isPersonalAccount(account)) {
+    return fim('aguardando', 'confirmar-conta', `A conta ${accountLabel(account)} parece ser de empresa (Teams/Business). O cofre do Auroq deve ficar na SUA conta pessoal, nao na da empresa. Se for esta mesmo, confirme rodando de novo com --conta "${account.email || account.url}".`, { contas: labels });
+  }
+  out.ok(`Conta: ${accountLabel(account)}`);
+
+  out.step('Pedindo sua aprovacao ao app do 1Password...');
+  out.log(`${BOLD}Vai abrir uma janela do 1Password pedindo a sua digital (Touch ID / Windows Hello) ou a senha. Aprove. Se ela aparecer mais de uma vez, e so aprovar de novo.${RESET}`);
+  const auth = d.op(['whoami', '--account', accountKey(account), '--format', 'json'], { env: opEnv(), timeoutMs: 180000 });
+  if (!auth.ok) {
+    const text = String(auth.stderr || '');
+    if (NET_STRONG_RE.test(text)) return fim('erro', 'rede', `Sem conexao com o 1Password. ${oneLine(text)}`.trim());
+    if (!auth.timedOut && classifyFailure(auth) === 'sem-sessao') {
+      // Conta so adicionada na mao (`op account add`): aparece na lista mas sem sessao; falta a chave do app.
+      showIntegrationHelp(d, out);
+      return fim('aguardando', 'ligar-integracao', 'Falta ligar "Integrate with 1Password CLI" nas configuracoes do app do 1Password (Configuracoes > Desenvolvedor). Depois e so rodar de novo.');
+    }
+    const detail = oneLine(text, 160);
+    return fim('aguardando', 'aprovar-no-app', `Nao consegui entrar na conta${auth.timedOut ? ': a janela da digital nao foi aprovada a tempo' : ''}. Confira se o app do 1Password esta aberto e desbloqueado, aprove a janela da digital e rode de novo.${detail ? ` (O 1Password disse: ${detail})` : ''}`);
+  }
+  prog.mark('aprovacao');
+  out.ok('Aprovado');
+
+  // 3. Copias do token no cofre pessoal: segunda maquina reaproveita; rotacao e chave morta arquivam
+  const found = findBackups(d, account);
+  if (!found.ok) {
+    return fim('erro', 'token-indisponivel', 'Nao consegui ler a lista de copias da chave no seu cofre pessoal agora. Nao criei nada novo, para nao duplicar. Tente de novo em alguns minutos.');
+  }
+  const stale = []; // copias velhas (chave morta, ou trocada na rotacao) que vao pro arquivo depois que a nova estiver salva
+  for (const b of found.itens) {
+    const read = readBackupToken(d, account, b);
+    if (read.erro) {
+      if (opts.rotacionar) continue; // pediu chave nova de proposito: copia ilegivel nao bloqueia
+      return fim('erro', 'token-indisponivel', `Achei a copia da chave no seu cofre pessoal mas nao consegui le-la agora. Nao criei nada novo, para nao duplicar. Tente de novo em alguns minutos${read.incerto ? '; se continuar assim por mais de uma hora, a copia pode estar estragada: rode com --rotacionar' : ''}.`);
+    }
+    if (!read.token) continue; // item com esse nome mas sem chave valida: nao e nosso, nao mexe
+    const check = await checkTokenWithRetry(d, read.token, { isolate: true, expectAccount: account }, 2);
+    if (check.ok && check.temClaude) {
+      if (opts.rotacionar) {
+        stale.push(b);
+      } else if (check.extras.length) {
+        out.warn(`A copia guardada no seu cofre pessoal enxerga mais do que o cofre ${VAULT_NAME}; nao vou usar essa. Vou criar uma chave so do ${VAULT_NAME}.`);
+      } else {
+        out.step('Achei a chave do Auroq guardada no seu cofre pessoal — vou reaproveitar (nao crio outra).');
+        prog.mark('cofre');
+        return finishWithToken(d, out, account, read.token, prog, { reaproveitada: true, oldBackups: [] });
+      }
+    } else if (!check.ok && check.motivo === 'token-invalido') {
+      stale.push(b);
+    } else if (!check.ok && !NO_RETRY.has(check.motivo)) {
+      return fim('erro', 'token-indisponivel', `Nao consegui conferir a copia da chave agora (${WHY[check.motivo] || WHY.falha}). Nao criei nada novo, para nao duplicar. Tente de novo em alguns minutos.`);
+    }
+    // conta-diferente / conta-nao-confirmada (token de outra conta) ou valido sem o cofre Claude: nao e nosso, fica como esta
+  }
+
+  // 4. Cofre Claude
+  out.step(`Preparando o cofre ${VAULT_NAME}...`);
+  const vaultList = d.op(['vault', 'list', '--account', accountKey(account), '--format', 'json'], { env: opEnv() });
+  const vaults = vaultList.ok ? parseJson(vaultList.stdout) : null;
+  if (!Array.isArray(vaults)) {
+    return fim('erro', 'sem-cofre', `Nao consegui ler os cofres da conta. ${oneLine(vaultList.stderr)}`.trim());
+  }
+  const sameName = vaults.filter((v) => String((v && v.name) || '').trim().toLowerCase() === VAULT_NAME.toLowerCase());
+  if (sameName.length > 1) {
+    return fim('erro', 'cofre-duplicado', `Tem ${sameName.length} cofres chamados ${VAULT_NAME} na sua conta. Apague ou renomeie os que sobram no app do 1Password e rode de novo (nao criei nada).`);
+  }
+  let createdVault = false;
+  if (sameName.length === 1) {
+    out.ok(`Cofre ${VAULT_NAME} ja existe — vou usar ele (nada do que esta nele muda).`);
+  } else {
+    const created = d.op(
+      ['vault', 'create', VAULT_NAME, '--description', 'Cofre do Auroq OS: chaves e tokens dos servicos conectados', '--account', accountKey(account)],
+      { env: opEnv() },
+    );
+    if (!created.ok) {
+      const motivo = classifyFailure(created);
+      return fim('erro', motivo === 'permissao' ? 'sem-permissao' : 'sem-cofre', `Nao consegui criar o cofre ${VAULT_NAME}. ${oneLine(created.stderr)}`.trim());
+    }
+    createdVault = true;
+    out.ok(`Cofre ${VAULT_NAME} criado`);
+  }
+  prog.mark('cofre');
+
+  // 5. Conta de servico: o token nasce aqui dentro e nunca e impresso
+  out.step('Criando a chave do agente (conta de servico, sem validade, so no cofre Claude)...');
+  const sa = d.op(
+    ['service-account', 'create', SERVICE_ACCOUNT_NAME, '--vault', `${VAULT_NAME}:read_items,write_items`, '--raw', '--account', accountKey(account)],
+    { env: opEnv(), timeoutMs: 120000 },
+  );
+  // Mesmo que o `op` tenha saido com erro, se o token veio na saida ele e a unica copia: segue com ele.
+  const token = extractToken(sa.stdout);
+  if (!token) {
+    const motivo = classifyFailure(sa);
+    const orphan = ' O 1Password so mostra a chave uma vez: se a conta de servico "Auroq" foi criada agora ha pouco (veja a data em 1password.com > Developer > Service accounts), revogue essa e rode de novo.';
+    if (sa.ok) {
+      return fim('erro', 'falha-criar', `A conta de servico foi criada mas o 1Password nao devolveu um token valido.${orphan}`);
+    }
+    if (motivo === 'permissao') {
+      const vazio = createdVault ? ` O cofre ${VAULT_NAME} que acabei de criar ficou vazio nesta conta; pode apagar no app.` : '';
+      return fim('erro', 'sem-permissao', `Nao consegui criar a conta de servico. ${oneLine(sa.stderr)} (Em conta de empresa so o dono ou administrador cria; no plano individual, quem criou a conta consegue.)${vazio}`.trim());
+    }
+    if (motivo === 'rede') return fim('erro', 'rede', `Sem conexao com o 1Password ao criar a chave. ${oneLine(sa.stderr)}${orphan}`.trim());
+    const incerto = sa.timedOut || sa.status === null || sa.status === undefined ? orphan : '';
+    return fim('erro', 'falha-criar', `Nao consegui criar a conta de servico. ${oneLine(sa.stderr)}${incerto}`.trim());
+  }
+  if (!sa.ok) out.warn('O 1Password avisou de um problema ao criar a chave, mas ela veio na resposta; sigo com ela.');
+  out.ok('Chave criada (nao aparece na tela)');
+
+  return finishWithToken(d, out, account, token, prog, { reaproveitada: false, oldBackups: stale });
+}
+
+/**
+ * Daqui em diante o token ja existe e so aparece UMA vez: grava no computador e na copia pessoal
+ * ANTES de testar (se o teste falhar, o token nao se perde), depois confere como um terminal novo.
+ */
+async function finishWithToken(d, out, account, token, prog, { reaproveitada, oldBackups }) {
+  out.step('Salvando a conexao neste computador...');
+  let where = null;
+  let persistError = null;
+  try {
+    where = d.persistToken(token);
+    out.ok(`Chave salva em ${where}`);
+  } catch (e) {
+    persistError = oneLine(e && e.message);
+  }
+
+  let backupOk = reaproveitada; // reaproveitar = a copia ja existe
+  if (!reaproveitada) {
+    const backup = saveBackup(d, account, token);
+    backupOk = backup.ok;
+    if (backup.ok) {
+      out.ok(`Copia guardada no seu cofre pessoal (item "${BACKUP_TITLE}"). Outro computador seu reaproveita essa chave.`);
+      if (oldBackups && oldBackups.length) archiveBackups(d, account, oldBackups.map((b) => b.id));
+    } else {
+      out.warn(`Nao consegui guardar a copia no cofre pessoal. ${backup.detalhe}`.trim());
+    }
+  }
+
+  if (persistError) {
+    if (backupOk) {
+      prog.mark('chave');
+      return fim('erro', 'nao-gravou', `Nao consegui salvar a chave neste computador (${persistError}), mas deixei uma copia no seu cofre pessoal. Resolva isso e rode de novo (sem --rotacionar): ele reaproveita a copia.`);
+    }
+    return fim('erro', 'nao-gravou', `A conta de servico "Auroq" foi criada mas a chave nao foi salva em lugar nenhum (${persistError}). Revogue a conta de servico criada agora (veja a data) em 1password.com > Developer > Service accounts e rode de novo.`);
+  }
+  prog.mark('chave');
+
+  out.step('Testando como um terminal novo...');
+  const persisted = d.readPersistedToken();
+  if (persisted !== token) {
+    return fim('erro', 'nao-gravou', 'A chave foi gravada mas um terminal novo nao a enxerga. Feche e abra o terminal (no Windows, o programa inteiro) e rode de novo (sem --rotacionar) para conferir.');
+  }
+  const fresh = (args) => d.opInFreshShell(args);
+  const check = await checkTokenWithRetry(d, null, { runner: fresh, retryInvalid: true });
+  if (check && !check.ok && check.motivo === 'app-tem-prioridade') {
+    return fim('erro', 'app-tem-prioridade', APP_PRIORITY_MSG.replace('Nao criei nada novo;', 'A chave ja esta salva;'));
+  }
+  if (!check || !check.ok) {
+    return fim('erro', 'token-recusado', `A chave foi salva mas o teste falhou (${check ? (WHY[check.motivo] || check.motivo) : 'sem resposta'}). ${check && check.detalhe ? check.detalhe : ''} Rode de novo (sem --rotacionar) para conferir.`.trim());
+  }
+  if (!check.temClaude) {
+    return fim('erro', 'token-recusado', `A chave foi salva mas nao enxerga o cofre ${VAULT_NAME}. Espere um minuto e rode de novo (sem --rotacionar).`);
+  }
+  if (check.extras.length) {
+    return fim('erro', 'cofres-extras', `A chave foi salva mas enxerga mais do que o cofre ${VAULT_NAME} (${check.extras.length} outro(s)). O combinado e so o ${VAULT_NAME}: rode de novo com --rotacionar.`);
+  }
+  out.ok(`Cofres que a chave enxerga: ${check.nomes.join(', ')}`);
+  if (!checkItems(d, (args) => d.opInFreshShell(args))) {
+    return fim('erro', 'token-recusado', `A chave enxerga o cofre ${VAULT_NAME} mas nao conseguiu listar os itens dele. Rode de novo (sem --rotacionar) para conferir.`);
+  }
+  out.ok(`Itens do cofre ${VAULT_NAME}: leitura funcionando`);
+  prog.mark('teste', 'pronto');
+
+  const restart = d.platform === 'win32'
+    ? 'Feche TODAS as janelas do terminal (se usa VS Code ou Windows Terminal, feche o programa inteiro) e abra de novo, para eles enxergarem a conexao nova.'
+    : 'Feche e abra de novo o terminal (e o Claude/Codex), para eles enxergarem a conexao nova.';
+  out.log('');
+  out.ok(`${BOLD}1Password conectado.${RESET} O agente usa so a chave: nao pede mais digital.`);
+  out.log(`${DIM}${restart}${RESET}`);
+  out.log(`${DIM}Limite do plano individual/Familia: 1.000 leituras e 100 escritas por hora, 1.000 chamadas por dia. O Auroq guarda o que le, para nao gastar a cota.${RESET}`);
+  if (!backupOk) out.log(`${DIM}Sem copia no cofre pessoal: se perder este computador, e so rodar de novo com --rotacionar.${RESET}`);
+  if (oldBackups && oldBackups.length && !reaproveitada) {
+    out.log(`${DIM}A chave antiga continua valendo ate voce revogar a conta de servico antiga (a mais velha chamada "Auroq") em 1password.com > Developer > Service accounts.${RESET}`);
+  }
+  return fim('ok', reaproveitada ? 'reaproveitada' : 'criada', `1Password conectado. O token enxerga so o cofre ${VAULT_NAME}.`);
+}
+
+/**
+ * Onde o aluno esta no pipeline, SEM falar com o 1Password (nao gasta a cota): estado salvo + o que da para
+ * ver no proprio computador. `conferido=nao`: so rodar o comando principal prova que a chave funciona.
+ */
+function describeState(d) {
+  const saved = d.state.read();
+  const etapas = saved ? { ...saved.etapas } : emptyEtapas();
+  const version = d.opVersion();
+  const opOk = Boolean(version && isVersionAtLeast(version));
+  etapas.op = opOk ? 'feito' : 'pendente';
+  const accounts = opOk ? listAccounts(d) : [];
+  if (accounts.length) {
+    etapas.conta = 'feito';
+    etapas.app = 'feito';
+  }
+  const hasToken = [d.env[TOKEN_VAR], d.readPersistedToken()].some((t) => t && isValidToken(t));
+  if (!hasToken) {
+    // chave apagada, computador novo ou arquivo de ambiente trocado: o que dependia dela volta a ficar pendente
+    for (const e of ['chave', 'teste', 'pronto']) etapas[e] = 'pendente';
+  } else if (!saved) {
+    etapas.chave = 'feito'; // ha uma chave no computador (modo antigo ou outra execucao); ainda nao provada
+  }
+  if (etapas.chave !== 'feito' || etapas.teste !== 'feito') etapas.pronto = 'pendente';
+  const feitas = ETAPAS.filter((e) => etapas[e] === 'feito');
+  const proxima = nextStage(etapas);
+  const resumo = !proxima ? 'pronto' : (feitas.length || saved ? 'em-andamento' : 'nao-iniciado');
+  return {
+    resumo,
+    proxima,
+    feitas,
+    etapas,
+    token: hasToken ? 'configurado' : 'ausente',
+    ultimo: saved && saved.ultimo ? saved.ultimo.codigo : null,
+    atualizado_em: saved ? saved.atualizado_em : null,
+  };
+}
+
+function buildStateLine(st) {
+  return `AUROQ_ESTADO 1password=${st.resumo} proxima=${st.proxima || 'nenhuma'} feitas=${st.feitas.join(',') || 'nenhuma'} token=${st.token} ultimo=${st.ultimo || 'nenhum'} conferido=nao`;
+}
+
+/** Linha que o Ops le (mesmo padrao da manutencao). */
+function buildResultLine(result) {
+  const msg = oneLine(result.mensagem, 400).replace(/"/g, "'");
+  const contas = result.contas && result.contas.length ? ` contas="${result.contas.map((c) => oneLine(c, 120).replace(/"/g, "'")).join('|')}"` : '';
+  const aviso = result.aviso ? ` aviso=${result.aviso}` : '';
+  return `AUROQ_RESULTADO 1password=${result.status} codigo=${result.codigo}${aviso}${contas} mensagem="${msg}"`;
+}
+
+function showState(st) {
+  console.log(`\n${PURPLE}${BOLD}  1Password — onde voce esta${RESET}`);
+  for (const e of ETAPAS.filter((x) => x !== 'pronto')) {
+    const feito = st.etapas[e] === 'feito';
+    console.log(`  ${feito ? `${GREEN}✓${RESET}` : `${GOLD}·${RESET}`} ${ETAPA_NOME[e]}`);
+  }
+  log('');
+  if (st.resumo === 'pronto') log(`${GREEN}${BOLD}Tudo pronto.${RESET} ${DIM}(Nao conferi com o 1Password agora: rode sem --estado para provar.)${RESET}`);
+  else log(`Proxima etapa: ${BOLD}${ETAPA_NOME[st.proxima]}${RESET}. Rode ${CYAN}npx auroq-os conectar-1password${RESET} para continuar de onde parou.`);
+  log('');
+}
+
+// ─── Entrada do comando ──────────────────────────────────
+
+/**
+ * `auroq-os conectar-1password [--agente] [--conta X] [--rotacionar] [--esperar N] [--manual]`
+ * Codigo de saida: 0 conectado OU falta uma acao do aluno (ligar a chave no app, escolher conta: a
+ * linha AUROQ_RESULTADO diz qual), 1 erro.
+ */
+async function connect(options = {}) {
+  const opts = options.argv ? parseArgs(options.argv) : { ...parseArgs([]), ...options };
+  if (opts.manual) return connectManual();
+  if (opts.estado) {
+    const st = describeState({ ...makeDefaultDeps(), ...(options.deps || {}) });
+    if (opts.agente) console.log(buildStateLine(st));
+    else showState(st);
+    return st;
+  }
+
+  if (!opts.agente) console.log(`\n${PURPLE}${BOLD}  Conectar 1Password — Auroq OS${RESET}`);
+  let result;
+  try {
+    result = await connectAutomatic(opts);
+  } catch (e) {
+    // Excecao inesperada: o Ops sempre recebe a linha de resultado (e a mensagem nunca leva token).
+    result = fim('erro', 'falha', `Falha inesperada: ${oneLine(e && e.message)}`);
+  }
+  if (result.status === 'aguardando') {
+    warn(result.mensagem);
+  } else if (result.status === 'erro') {
+    err(result.mensagem);
+    if (['sem-permissao', 'falha-criar', 'sem-cofre'].includes(result.codigo)) {
+      log(`${DIM}Plano B (so se o automatico nao for possivel nesta conta): npx auroq-os conectar-1password --manual${RESET}`);
+    }
+  }
+  if (opts.agente) console.log(buildResultLine(result));
+  process.exitCode = EXIT_CODE[result.status] ?? 1;
+  return result;
+}
+
 module.exports = {
   connect,
+  connectAutomatic,
+  connectManual,
   // exportados para testes
   isValidToken,
   upsertEnvFileContent,
+  parseEnvFileToken,
+  envFilePath,
+  persistToken,
+  readPersistedToken,
+  parseVersion,
+  isVersionAtLeast,
+  redact,
+  oneLine,
+  extractToken,
+  pickAccount,
+  parseArgs,
+  enableIntegrationSteps,
+  buildResultLine,
+  classifyFailure,
+  classifyTokenFailure,
+  isStudentActionable,
+  describeState,
+  buildStateLine,
+  readState,
+  writeState,
+  stateFile,
+  nextStage,
+  envFileProblem,
+  isTrackedByGit,
+  hasDynamicTokenDefinition,
+  shellKind,
+  freshShellFor,
+  clearClipboard,
+  ETAPAS,
+  makeLock,
+  isPersonalAccount,
+  normalizeAddress,
+  opEnv,
+  // reaproveitados pela rota do Infisical (lib/infisical.js) e pela camada comum (lib/cofre.js)
+  hasCommand,
+  parseJson,
+  writeFileAtomic,
+  auroqDir,
+  openUrl,
+  refreshWindowsPath,
+  runOp,
+  TOKEN_VAR,
+  MIN_OP_VERSION,
+  VAULT_NAME,
+  SERVICE_ACCOUNT_NAME,
+  BACKUP_TITLE,
+  BACKUP_TAG,
 };