terminal-smart-cli 0.98.0 → 0.99.0

package/hub/relay-conexao.js

@@ -0,0 +1,200 @@
+'use strict';
+// Conexão WSS de SAÍDA do nó com o relay (PROTOCOLO.md §7). Nenhuma porta é aberta no nó.
+//
+// Ciclo: abre <relay>/ws → recebe relay.desafio → confere que é o relay esperado e responde
+// relay.auth (papel "no") → relay.ok → "conectado". Cai = recuo exponencial com variação
+// aleatória (1 s, 2 s, 4 s … até 60 s) e tenta de novo; zera o recuo ao autenticar.
+// Usa o WebSocket nativo do Node 22 (TLS validado), sem dependência nova.
+
+const { EventEmitter } = require('events');
+const P = require('./proto/ts-proto.js');
+
+function ehHostLocal(h) {
+  const x = String(h).toLowerCase();
+  return x === 'localhost' || x === '127.0.0.1' || x === '[::1]' || x.endsWith('.localhost');
+}
+
+/**
+ * Aceita "https://host", "wss://host" e, só para host local, "http://" / "ws://".
+ * Devolve { origem: "wss://host[:porta]", urlWs: origem + "/ws", local }.
+ */
+function normalizarRelay(entrada) {
+  let u;
+  try { u = new URL(String(entrada)); } catch (_) { throw new Error('endereço do relay inválido'); }
+  const local = ehHostLocal(u.hostname);
+  let esquema;
+  if (u.protocol === 'https:' || u.protocol === 'wss:') esquema = 'wss:';
+  else if ((u.protocol === 'http:' || u.protocol === 'ws:') && local) esquema = 'ws:';
+  else throw new Error('o relay precisa ser https:// (http:// só para localhost em teste)');
+  if (u.username || u.password || u.search || u.hash || (u.pathname !== '/' && u.pathname !== '' && u.pathname !== '/ws')) {
+    throw new Error('o endereço do relay deve ser só a origem (sem caminho, consulta ou credenciais)');
+  }
+  const porta = u.port && !((esquema === 'wss:' && u.port === '443') || (esquema === 'ws:' && u.port === '80')) ? ':' + u.port : '';
+  const origem = esquema + '//' + u.hostname.toLowerCase() + porta;
+  return { origem, urlWs: origem + '/ws', local };
+}
+
+class ConexaoRelay extends EventEmitter {
+  /**
+   * opcoes: { relay (origem ws), urlWs, identidade, permitirLocal, recuoMinMs, recuoMaxMs,
+   *           pingMs, silencioMs, authMs, log, WebSocket }
+   */
+  constructor(opcoes) {
+    super();
+    const o = opcoes || {};
+    this.origem = o.relay;
+    this.urlWs = o.urlWs;
+    this.identidade = o.identidade;
+    this.recuoMinMs = o.recuoMinMs || 1000;
+    this.recuoMaxMs = o.recuoMaxMs || 60000;
+    this.pingMs = o.pingMs || 25000;
+    this.silencioMs = o.silencioMs || 70000;
+    this.authMs = o.authMs || 15000;
+    this.log = o.log || (() => {});
+    this._WS = o.WebSocket || globalThis.WebSocket;
+    this.estado = 'parado';
+    this.tentativas = 0;
+    this.conexoes = 0;          // autenticações bem-sucedidas (útil para status e testes)
+    this._ativo = false;
+    this._ger = 0;
+    this._ws = null;
+    this._timers = new Set();
+    this._ultimoRecebido = 0;
+  }
+
+  get conectado() { return this.estado === 'conectado'; }
+
+  iniciar() {
+    if (this._ativo) return;
+    if (typeof this._WS !== 'function') throw new Error('WebSocket indisponível neste Node (precisa do Node 22)');
+    this._ativo = true;
+    this._conectar();
+  }
+
+  parar() {
+    this._ativo = false;
+    this._derrubar(false);
+    this.estado = 'parado';
+  }
+
+  /** Envia um quadro de controle. Devolve false se não está conectado. */
+  enviar(obj) {
+    if (!this.conectado || !this._ws) return false;
+    const texto = JSON.stringify(obj);
+    try { P.verificarTamanhoQuadro(texto); } catch (_) { this.log('quadro grande demais descartado (E_TAMANHO)'); return false; }
+    try { this._ws.send(texto); return true; } catch (_) { return false; }
+  }
+
+  /** Força a queda (testes e "silêncio" do relay). Reconecta se ainda ativo. */
+  derrubar() { this._derrubar(true); }
+
+  _timer(fn, ms, repetir) {
+    const t = repetir ? setInterval(fn, ms) : setTimeout(() => { this._timers.delete(t); fn(); }, ms);
+    this._timers.add(t);
+    return t;
+  }
+  _limparTimers() {
+    for (const t of this._timers) { clearTimeout(t); clearInterval(t); }
+    this._timers.clear();
+  }
+
+  _conectar() {
+    if (!this._ativo) return;
+    const ger = ++this._ger;
+    this.estado = 'conectando';
+    let ws;
+    try { ws = new this._WS(this.urlWs); } catch (_) { this._caiu(ger); return; }
+    this._ws = ws;
+    // O prazo conta desde a tentativa, não desde o onopen: uma abertura que nunca termina (o
+    // relay caiu no meio do upgrade, rede presa) também é derrubada e tentada de novo.
+    this._timer(() => { if (ger === this._ger && !this.conectado) { this.log('relay não conectou/autenticou a tempo'); this._derrubar(true); } }, this.authMs);
+    ws.onopen = () => {
+      if (ger !== this._ger) return;
+      this.estado = 'autenticando';
+      this._ultimoRecebido = Date.now();
+    };
+    ws.onmessage = ev => {
+      if (ger !== this._ger) return;
+      this._ultimoRecebido = Date.now();
+      this._receber(ger, ev.data);
+    };
+    ws.onerror = () => {};
+    ws.onclose = () => { if (ger === this._ger) this._caiu(ger); };
+  }
+
+  async _receber(ger, texto) {
+    if (typeof texto !== 'string') return this._derrubar(true);   // o relay só fala texto
+    let q;
+    try { q = P.lerQuadroRelay(texto, 'do-relay'); } catch (e) {
+      this.log('quadro do relay recusado (' + (e.codigo || 'E_FORMATO') + ')');
+      return;
+    }
+    if (this.estado === 'autenticando') {
+      if (q.t === 'relay.desafio') {
+        let resp;
+        try {
+          resp = await P.clienteResponderDesafio({ identidade: this.identidade, quadro: q, relayEsperado: this.origem });
+        } catch (e) {
+          this.log('desafio do relay recusado (' + (e.codigo || 'E_DESAFIO') + ')');
+          return this._derrubar(true);
+        }
+        if (ger !== this._ger) return;
+        try { this._ws.send(JSON.stringify(resp)); } catch (_) {}
+        return;
+      }
+      if (q.t === 'relay.ok') {
+        if (q.papel !== 'no' || q.id !== this.identidade.id) return this._derrubar(true);
+        this.estado = 'conectado';
+        this.tentativas = 0;
+        this.conexoes++;
+        this._timer(() => this._pingar(ger), this.pingMs, true);
+        this.emit('conectado');
+        return;
+      }
+      if (q.t === 'relay.erro') {
+        this.log('relay recusou a autenticação (' + q.codigo + ')');
+        return this._derrubar(true);
+      }
+      return;
+    }
+    if (this.estado !== 'conectado') return;
+    if (q.t === 'relay.pong') return;
+    this.emit('quadro', q);
+  }
+
+  _pingar(ger) {
+    if (ger !== this._ger || !this.conectado) return;
+    if (Date.now() - this._ultimoRecebido > this.silencioMs) {
+      this.log('relay em silêncio; reconectando');
+      return this._derrubar(true);
+    }
+    this.enviar({ t: 'relay.ping' });
+  }
+
+  _derrubar(reconectar) {
+    const ws = this._ws;
+    const estavaConectado = this.conectado;
+    this._ger++;
+    this._ws = null;
+    this._limparTimers();
+    if (ws) { try { ws.close(); } catch (_) {} }
+    this.estado = 'desconectado';
+    if (estavaConectado) this.emit('desconectado');
+    if (reconectar && this._ativo) this._agendar();
+  }
+
+  _caiu(ger) {
+    if (ger !== this._ger) return;
+    this._derrubar(true);
+  }
+
+  _agendar() {
+    const base = Math.min(this.recuoMaxMs, this.recuoMinMs * Math.pow(2, Math.min(this.tentativas, 20)));
+    const atraso = Math.round(base * (0.5 + Math.random() * 0.5));
+    this.tentativas++;
+    this.log('reconectando ao relay em ' + Math.max(1, Math.round(atraso / 1000)) + ' s');
+    this._timer(() => this._conectar(), atraso);
+  }
+}
+
+module.exports = { ConexaoRelay, normalizarRelay, ehHostLocal };

package/hub/telas-arquivo.js

@@ -0,0 +1,130 @@
+'use strict';
+// Provedor de terminais "telas em arquivo": o hub só LÊ instantâneos de um diretório
+// (TS_HUB_TELAS_DIR). Quem grava é o `ts hub exportar-telas`, rodando como o usuário dos
+// agentes (não como o hub): assim o hub não precisa de acesso ao tmux nem a nada dos agentes.
+//
+//   <TS_HUB_TELAS_DIR>/
+//     indice.json          { v:1, geradoEm, terminais:[{ terminalId, titulo, ativo, colunas, linhas }] }
+//     tela-<id>.json       { v:1, terminalId, colunas, linhas, historico, geradoEm, tela }
+//
+// O conteúdo vem de outro usuário: tudo é conferido de novo (formato, tamanho, ID) e a tela
+// passa pela sanitização e pela máscara no hub. Nada de seguir link: o diretório não pode ser
+// link e os arquivos são abertos com O_NOFOLLOW (POSIX) e conferidos com fstat (regular e
+// dentro do tamanho). Índice velho (exportador parado) = lista vazia.
+
+const fs = require('fs');
+const path = require('path');
+const P = require('./proto/ts-proto.js');
+
+const INDICE = 'indice.json';
+const RX_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;   // vira nome de arquivo: sem ".", ":" ou "/"
+const INDICE_MAX = 256 * 1024;
+const TELA_ARQUIVO_MAX = 1024 * 1024;
+const TERMINAIS_MAX = 100;
+const VALIDADE_PADRAO_MS = 30000;
+
+function erroCodigo(codigo) { return Object.assign(new Error(codigo), { codigo }); }
+
+function arquivoTela(terminalId) { return 'tela-' + terminalId + '.json'; }
+
+/** Lê um arquivo regular sem seguir link e sem passar de `max` bytes. Devolve texto ou null. */
+function lerSeguro(arq, max) {
+  const c = fs.constants;
+  let fd;
+  try {
+    if (!c.O_NOFOLLOW) {
+      // Windows: sem O_NOFOLLOW; confere antes (link simbólico lá exige privilégio).
+      const l = fs.lstatSync(arq);
+      if (l.isSymbolicLink() || !l.isFile()) return null;
+    }
+    fd = fs.openSync(arq, c.O_RDONLY | (c.O_NOFOLLOW || 0) | (c.O_NONBLOCK || 0));
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.size > max) return null;
+    const buf = Buffer.alloc(st.size);
+    let lidos = 0;
+    while (lidos < st.size) {
+      const n = fs.readSync(fd, buf, lidos, st.size - lidos, lidos);
+      if (n <= 0) break;
+      lidos += n;
+    }
+    return buf.subarray(0, lidos).toString('utf8');
+  } catch (_) {
+    return null;
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch (_) {} }
+  }
+}
+
+function inteiro(n, min, max) { return Number.isSafeInteger(n) && n >= min && n <= max; }
+
+function limparTitulo(s) {
+  return String(s).replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/g, ' ')
+    .replace(/\s+/g, ' ').trim().slice(0, 80);
+}
+
+/**
+ * opcoes: { dir, validadeMs (30 s), agora }
+ */
+function criarProvedorTelas(opcoes) {
+  const o = opcoes || {};
+  const dir = path.resolve(String(o.dir));
+  const validadeMs = o.validadeMs || VALIDADE_PADRAO_MS;
+  const agora = o.agora || Date.now;
+
+  function dirOk() {
+    try { const st = fs.lstatSync(dir); return st.isDirectory() && !st.isSymbolicLink(); } catch (_) { return false; }
+  }
+
+  function lerIndice() {
+    if (!dirOk()) return [];
+    const texto = lerSeguro(path.join(dir, INDICE), INDICE_MAX);
+    if (texto === null) return [];
+    let j;
+    try { j = JSON.parse(texto); } catch (_) { return []; }
+    if (!j || j.v !== 1 || !Number.isSafeInteger(j.geradoEm) || !Array.isArray(j.terminais)) return [];
+    const idade = agora() - j.geradoEm;
+    if (idade > validadeMs || idade < -validadeMs) return [];   // exportador parado (ou relógio absurdo)
+    const out = [];
+    const vistos = new Set();
+    for (const t of j.terminais) {
+      if (out.length >= TERMINAIS_MAX) break;
+      if (!t || typeof t.terminalId !== 'string' || !RX_ID.test(t.terminalId) || vistos.has(t.terminalId)) continue;
+      if (!inteiro(t.colunas, 1, 1000) || !inteiro(t.linhas, 1, 1000)) continue;
+      vistos.add(t.terminalId);
+      out.push({
+        terminalId: t.terminalId,
+        titulo: limparTitulo(typeof t.titulo === 'string' ? t.titulo : t.terminalId) || t.terminalId,
+        ativo: t.ativo === true,
+        colunas: t.colunas,
+        linhas: t.linhas,
+      });
+    }
+    return out;
+  }
+
+  return {
+    nome: 'arquivo',
+    dir,
+    async listar() { return lerIndice(); },
+    /** Tela visível + até `historico` linhas anteriores (o instantâneo tem no máximo 200). */
+    async capturar(terminalId, historico) {
+      if (typeof terminalId !== 'string' || !RX_ID.test(terminalId)) throw erroCodigo('E_PARAMS');
+      const h = historico === undefined ? 0 : historico;
+      if (!inteiro(h, 0, P.LIMITES.HISTORICO_MAX)) throw erroCodigo('E_PARAMS');
+      if (!dirOk()) throw erroCodigo('E_TERMINAL_INEXISTENTE');
+      const texto = lerSeguro(path.join(dir, arquivoTela(terminalId)), TELA_ARQUIVO_MAX);
+      if (texto === null) throw erroCodigo('E_TERMINAL_INEXISTENTE');
+      let j;
+      try { j = JSON.parse(texto); } catch (_) { throw erroCodigo('E_TERMINAL_INEXISTENTE'); }
+      if (!j || j.v !== 1 || j.terminalId !== terminalId || typeof j.tela !== 'string' || !inteiro(j.linhas, 1, 1000)) {
+        throw erroCodigo('E_TERMINAL_INEXISTENTE');
+      }
+      const linhas = j.tela.split('\n');
+      const final = linhas.length && linhas[linhas.length - 1] === '' ? 1 : 0;
+      const manter = j.linhas + h + final;
+      return linhas.length > manter ? linhas.slice(linhas.length - manter).join('\n') : j.tela;
+    },
+  };
+}
+
+module.exports = { criarProvedorTelas, lerSeguro, arquivoTela, INDICE, RX_ID, TELA_ARQUIVO_MAX, INDICE_MAX };

package/hub/tmux.js

@@ -0,0 +1,189 @@
+'use strict';
+// Leitura do servidor tmux dedicado (`tmux -L ts`), só leitura.
+//
+// Uso normal: `ts hub exportar-telas` (rodando como o usuário dos agentes) usa estas funções
+// para gravar instantâneos que o hub lê de um diretório (hub/telas-arquivo.js). O hub em si
+// NÃO fala com o tmux. O provedor direto (criarProvedorTmux no hub) é só para desenvolvimento
+// e testes, ligado com TS_HUB_TMUX_DIRETO=1.
+//
+// - Sem shell: tudo por execFile('tmux', [...]). O executor é injetável (testes usam um tmux
+//   falso).
+// - terminalId = "p<N>" para o painel "%N" do tmux. O ID é validado duas vezes: pelo
+//   protocolo (validarParametros) e aqui (/^p\d{1,9}$/), e só vira alvo `-t %N` depois disso.
+// - No Windows, ou sem tmux / sem servidor `-L ts` no ar, a lista é vazia.
+
+const { execFile } = require('child_process');
+const P = require('./proto/ts-proto.js');
+
+const SOCKET_TMUX = 'ts';
+const RX_TERMINAL_TMUX = /^p\d{1,9}$/;
+const TITULO_MAX = 80;
+// A tela vai inteira num quadro de sessão: o limite real é o texto claro do quadro (32 KiB,
+// PROTOCOLO §5), conferido em hub.js; isto é só o teto bruto antes da conta do JSON.
+const TELA_MAX_BYTES = 32 * 1024;
+
+// Campos fixos primeiro; os de texto livre (sessão e janela) no fim, para tabulação dentro do
+// nome não bagunçar os numéricos.
+const FORMATO = [
+  '#{pane_id}', '#{window_index}', '#{pane_index}', '#{window_panes}',
+  '#{pane_active}', '#{window_active}', '#{pane_width}', '#{pane_height}',
+  '#{session_name}', '#{window_name}',
+].join('\t');
+
+function executorPadrao(arquivo, args) {
+  return new Promise((resolve, reject) => {
+    execFile(arquivo, args, { timeout: 5000, maxBuffer: 8 * 1024 * 1024, windowsHide: true, encoding: 'utf8' },
+      (err, stdout, stderr) => {
+        if (err) { err.stderr = String(stderr || ''); return reject(err); }
+        resolve(String(stdout));
+      });
+  });
+}
+
+function limparTexto(s, max) {
+  return String(s)
+    .replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+function analisarLista(stdout) {
+  const terminais = [];
+  const vistos = new Set();
+  for (const linha of String(stdout).split('\n')) {
+    if (!linha) continue;
+    const c = linha.split('\t');
+    if (c.length < 10) continue;
+    const m = /^%(\d{1,9})$/.exec(c[0]);
+    if (!m) continue;
+    const terminalId = 'p' + m[1];
+    if (vistos.has(terminalId)) continue;
+    const nums = c.slice(1, 8).map(x => (/^\d{1,6}$/.test(x) ? Number(x) : NaN));
+    if (nums.some(n => !Number.isSafeInteger(n))) continue;
+    const [janela, painel, paineis, painelAtivo, janelaAtiva, colunas, linhas] = nums;
+    const sessao = c[8];
+    const nomeJanela = c.slice(9).join(' ');
+    let titulo = limparTexto(sessao, 40) + ':' + janela + (nomeJanela ? ' ' + limparTexto(nomeJanela, 40) : '');
+    if (paineis > 1) titulo += ' [' + painel + ']';
+    vistos.add(terminalId);
+    terminais.push({
+      terminalId,
+      titulo: titulo.slice(0, TITULO_MAX),
+      ativo: painelAtivo === 1 && janelaAtiva === 1,
+      colunas,
+      linhas,
+      // Nomes crus (só para a lista de janelas permitidas do exportar-telas; não vão ao celular).
+      sessao,
+      janela: nomeJanela,
+    });
+  }
+  return terminais;
+}
+
+/**
+ * Mantém só escapes SGR (cor/estilo: ESC [ ... m). Tira os demais escapes (movimento de
+ * cursor, OSC, títulos, hiperlinks) e caracteres de controle, exceto \n e \t.
+ */
+function sanitizarTela(texto) {
+  const partes = String(texto).replace(/\r\n?/g, '\n').split(/(\x1b\[[0-9;:]{0,64}m)/);
+  let out = '';
+  for (let i = 0; i < partes.length; i++) {
+    if (i % 2 === 1) { out += partes[i]; continue; }
+    out += partes[i]
+      .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, '')
+      .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
+      .replace(/\x1b[ -/]*[0-~]/g, '')          // ESC ( B, ESC =, ESC 7 … (charset, modos)
+      .replace(/\x1b[\s\S]?/g, '')
+      .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, '');
+  }
+  return out;
+}
+
+/**
+ * Corta o histórico mais antigo (linhas do começo) até `cabe(tela)` ser verdade.
+ * Se nem a última linha couber, guarda o fim dela.
+ */
+function cortarTela(tela, cabe) {
+  if (cabe(tela)) return tela;
+  const linhas = tela.split('\n');
+  // Busca binária: maior quantidade de linhas finais que cabe.
+  let lo = 0, hi = linhas.length;
+  while (lo < hi) {
+    const meio = Math.ceil((lo + hi) / 2);
+    if (cabe(linhas.slice(linhas.length - meio).join('\n'))) lo = meio; else hi = meio - 1;
+  }
+  if (lo > 0) return linhas.slice(linhas.length - lo).join('\n');
+  let ultima = linhas[linhas.length - 1];
+  let a = 0, b = ultima.length;
+  while (a < b) {
+    const meio = Math.ceil((a + b) / 2);
+    if (cabe(ultima.slice(ultima.length - meio))) a = meio; else b = meio - 1;
+  }
+  return ultima.slice(ultima.length - a);
+}
+
+function ehSemServidor(err) {
+  if (!err) return false;
+  if (err.code === 'ENOENT') return true;
+  const s = String(err.stderr || err.message || '');
+  return /no server running|error connecting|no such file|server exited|failed to connect/i.test(s);
+}
+
+/**
+ * opcoes.executar(arquivo, args) → Promise<stdout>   (padrão: execFile, sem shell)
+ * opcoes.plataforma                                  (padrão: process.platform)
+ */
+function criarProvedorTmux(opcoes) {
+  const o = opcoes || {};
+  const plataforma = o.plataforma || process.platform;
+  if (!o.executar && plataforma === 'win32') return provedorVazio();
+  const executar = o.executar || executorPadrao;
+  const tmux = args => executar('tmux', ['-u', '-L', SOCKET_TMUX].concat(args));
+
+  return {
+    nome: 'tmux',
+    async listar() {
+      let out;
+      try { out = await tmux(['list-panes', '-a', '-F', FORMATO]); } catch (err) {
+        if (ehSemServidor(err)) return [];
+        return [];
+      }
+      return analisarLista(out);
+    },
+    async capturar(terminalId, historico) {
+      if (typeof terminalId !== 'string' || !RX_TERMINAL_TMUX.test(terminalId)) {
+        throw Object.assign(new Error('terminalId inválido'), { codigo: 'E_PARAMS' });
+      }
+      const h = historico === undefined ? 0 : historico;
+      if (!Number.isSafeInteger(h) || h < 0 || h > P.LIMITES.HISTORICO_MAX) throw Object.assign(new Error('histórico inválido'), { codigo: 'E_PARAMS' });
+      const alvo = '%' + terminalId.slice(1);
+      try {
+        return await tmux(['capture-pane', '-p', '-e', '-J', '-t', alvo, '-S', '-' + h]);
+      } catch (_) {
+        throw Object.assign(new Error('terminal indisponível'), { codigo: 'E_TERMINAL_INEXISTENTE' });
+      }
+    },
+  };
+}
+
+function provedorVazio() {
+  return {
+    nome: 'vazio',
+    async listar() { return []; },
+    async capturar() { throw Object.assign(new Error('sem terminais'), { codigo: 'E_TERMINAL_INEXISTENTE' }); },
+  };
+}
+
+module.exports = {
+  criarProvedorTmux,
+  executorPadrao,
+  SOCKET_TMUX,
+  provedorVazio,
+  analisarLista,
+  sanitizarTela,
+  cortarTela,
+  FORMATO,
+  RX_TERMINAL_TMUX,
+  TELA_MAX_BYTES,
+};

package/hub/vps/README.md

@@ -0,0 +1,109 @@
+# Exemplos para a VPS dos agentes (NÃO aplicados)
+
+Arquivos de referência para a implantação (etapa 7, com aprovação). Nada aqui foi instalado.
+Caminhos e nomes de usuário (`tshub`, `agentes`) são os do plano; ajuste antes de usar.
+
+## 1. "Parar tudo" com confirmação real
+
+O hub roda como `tshub`, sem privilégio. Ele **não** para nada sozinho:
+
+1. o celular manda `hub.stopAll {confirmar:true}`;
+2. o hub cria `pedidos/parar-<carimbo ms>-<16 hex>.pedido` em `TS_HUB_PARAR_DIR`, com
+   `O_CREAT|O_EXCL|O_NOFOLLOW` (não sobrescreve, não segue link) e espera até 10 s;
+3. a unidade `ts-hub-parar.path` (root) vê o diretório não vazio e dispara
+   `ts-hub-parar.service`, que roda `ts-hub-parar-consumir`:
+   - **não lê** o conteúdo de nenhum pedido; só valida o nome
+     (`^parar-[0-9]{13}-[0-9a-f]{16}\.pedido$`, arquivo regular, não link);
+   - renomeia cada entrada de `pedidos/` para `consumidos/` (as inválidas como
+     `invalido-...`): o diretório fica vazio e o `.path` não dispara de novo (sem laço);
+   - roda `/usr/local/sbin/ts-parar-tudo "celular"` **uma vez** por lote;
+   - grava `confirmacoes/<base>.ok` (ou `.falhou`), atômico (`mktemp` + `mv`), 0644;
+4. o hub vê a confirmação **do dono certo** (uid 0, arquivo regular, não link) e só então
+   responde `{parado:true}`. Sem confirmação em 10 s (ou com `.falhou`):
+   `E_PARAR_SEM_CONFIRMACAO`, e o celular mostra "não confirmado".
+
+`hub.status`/`hub.estado` dizem `parado:true` só se existir uma confirmação `.ok` válida — o
+pedido sozinho não conta. **Religar** = o root apagar as confirmações (depois de religar os
+agentes):
+
+```sh
+rm -f /var/lib/ts-hub-parar/confirmacoes/*.ok
+```
+
+Nó sem `TS_HUB_PARAR_DIR` (ou com os diretórios fora do lugar, com dono ou modo errados)
+anuncia `pararDisponivel:false` em `hub.status` e a PWA desabilita o botão para ele; um
+`hub.stopAll` assim recebe `E_PARAR_INDISPONIVEL`. É o caso do PC na entrega 1.
+
+### Arquivos
+
+| Arquivo | Destino | Dono/modo |
+|---|---|---|
+| `ts-hub-parar.tmpfiles.conf` | `/etc/tmpfiles.d/ts-hub-parar.conf` | root, 0644 |
+| `ts-hub-parar.path` | `/etc/systemd/system/` | root, 0644 |
+| `ts-hub-parar.service` | `/etc/systemd/system/` | root, 0644 |
+| `ts-hub-parar-consumir` | `/usr/local/sbin/` | root, 0755 |
+
+Diretórios (criados pelo tmpfiles):
+
+| Diretório | Dono | Modo | Quem escreve |
+|---|---|---|---|
+| `/var/lib/ts-hub-parar` | root | 0755 | ninguém |
+| `pedidos/` | tshub | 0700 | só o hub |
+| `confirmacoes/` | root | 0755 | só o root (o hub lê) |
+| `consumidos/` | root | 0700 | só o root (limpo após 30 dias) |
+
+O hub confere isso a cada uso: `pedidos/` do próprio usuário e `confirmacoes/` de root, os
+dois sem escrita para grupo/outros e sem link. Assim nem um agente (outro usuário) nem o
+próprio processo do hub conseguem forjar uma confirmação.
+
+### Instalação (quando aprovada)
+
+```sh
+install -o root -g root -m 0644 ts-hub-parar.tmpfiles.conf /etc/tmpfiles.d/ts-hub-parar.conf
+systemd-tmpfiles --create /etc/tmpfiles.d/ts-hub-parar.conf
+install -o root -g root -m 0755 ts-hub-parar-consumir /usr/local/sbin/ts-hub-parar-consumir
+install -o root -g root -m 0644 ts-hub-parar.path ts-hub-parar.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now ts-hub-parar.path
+# no ambiente do serviço do hub (usuário tshub):
+#   TS_HUB_PARAR_DIR=/var/lib/ts-hub-parar
+```
+
+Teste manual (sem o celular): como `tshub`, `touch /var/lib/ts-hub-parar/pedidos/parar-0000000000000-0000000000000000.pedido`
+e confira `confirmacoes/` e `journalctl -u ts-hub-parar.service`.
+
+## 2. Telas dos terminais sem privilégio no hub
+
+O hub não fala com o tmux. Quem lê o tmux é `ts hub exportar-telas`, rodando como o
+**usuário dos agentes** (que já tem o `tmux -L ts`), e grava instantâneos em
+`TS_HUB_TELAS_DIR`; o hub só lê esse diretório (grupo `ts-telas`, modo 0750/0640).
+
+- Só janelas da lista `TS_HUB_TELAS_PERMITIDAS` (`sessao:janela` ou `sessao:*`); sem lista,
+  nada é exportado.
+- Histórico de no máximo 200 linhas; só cores (SGR) sobrevivem; segredos conhecidos são
+  mascarados (`sk-…`, `sk-ant-…`, `ghp_…`/`gho_…`/`github_pat_…`, `AKIA…`, `xox…`, JWT,
+  `-----BEGIN … PRIVATE KEY-----`, `usuario:senha@` em URL). A máscara é rede de segurança,
+  não garantia: escolha as janelas exportadas com cuidado.
+- Gravação atômica; índice velho (exportador parado há mais de 30 s) = lista vazia no hub.
+
+Exemplo: `ts-hub-exportar-telas.service` (ajuste `User=`, a lista e o caminho do `ts`).
+Diretório: `install -d -o tsagentes -g ts-telas -m 2750 /var/lib/ts-hub-telas` e
+`usermod -aG ts-telas tshub`. **Não** ponha o `tsagentes` no grupo `ts-telas`: o `Group=` do
+serviço já vale para o processo, e o `ts-vigia` aciona o Parar tudo se a conta dos agentes
+ganhar grupo. O exportador roda sem `PrivateTmp` (o socket do tmux fica em `/tmp/tmux-<uid>/`). No serviço
+do hub: `TS_HUB_TELAS_DIR=/var/lib/ts-hub-telas`.
+
+## 2b. O tmux dos agentes
+
+`ts-tmux.service` (unidade de usuário de root em `/etc/systemd/user/`, só para o `tsagentes`) com
+`tmux-agentes.conf` (`default-shell /bin/sh`: a conta é `nologin`). Crie as janelas sempre com
+`-c <pasta acessível>` (ex.: `%h`): o tmux herda a pasta do cliente, e `/home` é inacessível para os
+agentes — o painel morreria com status 1.
+
+## 3. O hub
+
+`ts-hub.service` (exemplo): usuário `tshub`, instalação mínima em `/opt/ts-hub` (só `hub/`,
+`package.json` e `node_modules/qrcode-terminal`; o hub usa o WebSocket nativo do Node 22),
+entrada `hub/principal.js`. Parear pela própria VPS: `sudo -u tshub env TS_HUB_DIR=/var/lib/tshub/hub node /opt/ts-hub/hub/principal.js parear` (a confirmação é digitada ali mesmo).
+
+O provedor que lê o tmux direto do hub (`TS_HUB_TMUX_DIRETO=1`) é só para desenvolvimento.

package/hub/vps/tmux-agentes.conf

@@ -0,0 +1,5 @@
+# /usr/local/lib/ts/tmux-agentes.conf — tmux dos agentes (servidor -L ts, usuário tsagentes).
+# A conta não tem shell de login (nologin, conferido pelo ts-vigia); sem esta linha toda
+# janela morre na hora com status 1. As janelas rodam com /bin/sh.
+set -g default-shell /bin/sh
+set -g history-limit 5000

package/hub/vps/ts-hub-exportar-telas.service

@@ -0,0 +1,30 @@
+# EXEMPLO — não aplicado. Copiar para /etc/systemd/system/ts-hub-exportar-telas.service.
+# Roda como o USUÁRIO DOS AGENTES (tsagentes) (quem já tem o tmux -L ts), nunca como tshub nem root.
+# O hub (tshub) só lê /var/lib/ts-hub-telas pelo grupo ts-telas. Ver README.md.
+# Group= vale só para este processo: o tsagentes NÃO entra no grupo ts-telas (o ts-vigia
+# aciona o Parar tudo se a conta dos agentes ganhar grupo).
+[Unit]
+Description=Terminal Smart: exporta as telas do tmux dos agentes para o hub (só leitura)
+
+[Service]
+User=tsagentes
+Group=ts-telas
+UMask=0027
+Environment=TS_HUB_TELAS_DIR=/var/lib/ts-hub-telas
+# Só estas janelas saem da máquina (sessao:janela ou sessao:*). Ajustar à VPS.
+Environment=TS_HUB_TELAS_PERMITIDAS=agentes:claude,agentes:codex
+Environment=TS_HUB_TELAS_HISTORICO=200
+ExecStart=/usr/bin/node /opt/ts-hub/hub/principal.js exportar-telas
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=yes
+# Sem PrivateTmp: o socket do tmux dos agentes fica em /tmp/tmux-<uid>/ts.
+PrivateTmp=no
+# Não precisa de rede (o socket do tmux é de arquivo e funciona sem rede).
+PrivateNetwork=yes
+IPAddressDeny=any
+ProtectSystem=strict
+ReadWritePaths=/var/lib/ts-hub-telas
+
+[Install]
+WantedBy=multi-user.target