@orkastery/cli 0.2.0 → 0.4.1

package/adapters/claude-code/commands/ork.md

@@ -1,37 +1,109 @@
 ---
-description: Painel do Orkastery: estado das threads, escalonador, modos e o que a maquina permite agora.
-argument-hint: "[board|plan|doctor|modos]"
-allowed-tools: Bash(ork:*), Read
+description: Reconhece orkastery maestro e conduz pedidos, retomadas e status na conversa com o Maestro/Builder.
+argument-hint: "[pedido em linguagem natural|thread|status|board|plan|doctor|modos]"
+allowed-tools: Bash(ork:*), Read, mcp__orkastery__ork_thread_status, mcp__orkastery__ork_phase_list, mcp__orkastery__ork_hitl_pending, mcp__orkastery__ork_observe, mcp__orkastery__ork_artifact_read, mcp__orkastery__ork_claims_list, mcp__orkastery__ork_git_status, mcp__orkastery__ork_thread_new, mcp__orkastery__ork_phase_run, mcp__orkastery__ork_preflight
 ---
 
-# /ork
+# /orkastery:ork
 
-Entrada geral do adaptador. Nao conduz fase nenhuma: mostra o estado e diz qual comando responde
-pela intencao do builder.
+Entrada nativa do plugin ativado no projeto: `/orkastery:ork`. A copia dos arquivos pelo
+instalador ainda exige ativacao nativa; `/ork` sozinho nao e um alias garantido.
 
-## O que este comando faz
+Esta entrada ja esta carregada pela invocacao do dono. Nao invoque `Skill(orkastery:ork)`
+nem outro comando para recarregar estas instrucoes. Conduza o pedido com as ferramentas
+ja permitidas.
+As oito consultas MCP e criar/despachar thread desta entrada valem no turno da invocacao;
+nao persistem por si nas proximas mensagens. Criar/despachar exige demanda e escopo autorizados
+pelo dono, modo resolvido e preflight do nucleo. Nao recarregue a skill para obter permissoes.
+Esses grants nao ativam MCP, nao autorizam outras mutacoes nem aprovam gates ou respostas humanas.
+
+Leia o contrato comum com `Read`, sem chamar `Skill` para carregar o bootstrap:
+@${CLAUDE_PLUGIN_ROOT}/skills/core/orkastery-bootstrap/SKILL.md
+
+Se o contrato ja estiver no contexto, use-o sem reler. Se o arquivo estiver ausente,
+informe instalacao incompleta; nao invente outro fluxo.
+
+Entrada conversacional do Orkastery. Use o contrato comum para conduzir a intencao do dono pelo nucleo. Nao limite um pedido de execucao a indicar outro
+slash command. Se recebeu um pedido e possui as ferramentas necessarias, execute o roteamento.
+Os comandos de fase continuam disponiveis como atalhos; o dono nao precisa conhece-los.
+
+## Reconhecer a intencao
+
+A frase literal `orkastery maestro`, em sessão limpa, pede leitura do panorama.
+Descubra a ferramenta com `ToolSearch` em `select:mcp__orkastery__ork_maestro`,
+então consulte o projeto fixado. Não abre thread nem despacho por consulta.
+Projeto ausente/ambíguo exige resolver o contexto permitido pelo núcleo.
+Se já recebeu fase/thread/worktree, execute o bloco recebido, sem recursão.
+MCP ausente ou autenticação negada permanece impedimento; não troque runtime,
+provider ou sandbox. A consulta CLI `ork maestro --json` não concede mutações.
+
+Usabilidade HITL é prioridade máxima: tópicos, recomendação e opções rotuladas,
+UUID interno e cancelamento preservado. A condutora usa
+`mcp__orkastery__ork_request_decision`; o filho nunca responde em nome do dono.
+
+| Pedido do dono | Acao do agente |
+|---|---|
+| Demanda nova | Resolva o modo pelo nucleo, confira o preflight e abra/despache a thread correspondente. |
+| "Continue" ou thread/roadmap existente | Leia o estado e o ultimo resultado; retome o proximo passo autorizado, sem duplicar despacho. |
+| "Como esta?" ou status | Consulte a thread conhecida; apresente progresso comprovado, impedimento e proximo passo. |
+| Decisao ou resposta | Correlacione com o pedido/gate apresentado, transporte pelo caminho suportado e confira o resultado. |
+| Onboarding | Use a pauta de `ork onboarding` e retome as etapas existentes. |
+| board, plan, doctor ou modos | Execute a consulta correspondente e interprete o resultado para a intencao do dono. |
+
+## Fontes do nucleo
+
+Priorize as ferramentas MCP do Orkastery quando descobertas nesta sessao, com o projeto
+fixado pelo servidor. No Claude, o servidor instalado `orkastery` expoe nomes completos como
+`mcp__orkastery__ork_thread_status`. Se houver ferramentas adiadas, use `ToolSearch` com
+`select:mcp__orkastery__ork_thread_status,mcp__orkastery__ork_artifact_read` para essas leituras;
+para outra operacao, selecione seu nome completo realmente exposto. Nao tente `select:ork_thread_status`
+nem adivinhe outro namespace. Ativacao inicial do MCP e consentimento do dono continuam nativos. `ork_thread_status`, `ork_phase_list` e `ork_hitl_pending` leem
+estado; `ork_thread_new` e `ork_phase_run` abrem/despacham; `ork_observe` consulta a sessao
+nativa despachada. Quando pausa/escalacao real permitir e faltar pedido, use
+`ork_gate_request(threadId, motivo?)`; nunca crie pedido para uma consulta de status.
+`ork_request_decision(threadId, pedidoId)` apresenta o dialogo ao dono:
+a resposta vem pelo host, nunca por argumento de resposta ou identidade inventada pelo modelo.
+
+As consultas CLI abaixo continuam uteis quando a ferramenta correspondente nao esta disponivel:
 
 ```bash
-ork doctor       # o que vale nesta maquina agora (sai != 0 se bloqueado)
-ork board        # todas as threads em uma visao
-ork board plan   # quem avanca agora, quem espera e por que
-ork modos        # a tabela dos 5 modos de conducao por #TAG
-ork master --batch  # o que fechou e ainda espera score humano
+ork thread status <thread>
+ork phase list <thread>
+ork pulse --json
+ork board plan
+ork doctor
+ork modos
+ork master
 ```
 
-## Roteamento
+Use apenas as consultas necessarias. Nao rode todas a cada mensagem. O preflight pertence ao
+inicio de despacho ou a uma mudanca relevante de ambiente; uma pergunta de status nao reinicia
+onboarding nem trabalho. Se a thread estiver ambigua, esclareca antes de alterar seu estado.
+Pausas listadas nos blocos do modo sao previstas. Para dizer que o dono precisa responder
+agora, identifique uma pendencia atual no estado/ultimo resultado da thread, com gate,
+pedido ou evento correspondente. Uma thread nova sem fase executada nao aguarda premissas
+so porque o bloco f12 do modo preve essa pausa.
 
-| O builder quer | Comando |
-|---|---|
-| abrir demanda nova | `/goal <pedido com #TAG>` |
-| especificar | `/plan <thread>` |
-| implementar | `/go <thread>` |
-| verificar | `/check <thread>` |
-| entregar | `/ship <thread>` |
-| fechar e dar o score | `/master <thread>` |
-
-## Regras do adaptador
-
-- **Zero regra de negocio aqui.** Este comando le e apresenta; quem decide e o humano e quem
-  verifica e o `ork`.
-- Um `fail` do `ork doctor` para o ciclo antes de ele abrir, e isso e economia, nao obstaculo.
+## Continuidade
+
+Preserve modo, decisoes e autorizacoes da thread/sessao. Prossiga com trabalho autorizado em
+vez de encerrar com "posso continuar?". Pergunte quando o modo ou uma ambiguidade real exigir
+intervencao do dono e explique o que a resposta destrava. Nao aprove gates em nome dele.
+
+Com despacho existente, consulte `ork_observe` e trate a espera nativa atual. Nao substitua
+observacao por loops longos de `phase list`, sleeps ou regex de conclusao sobre historico.
+Se faltar MCP e o sandbox impedir `.git`, informe instalacao pendente do transporte nativo;
+nao repita a mutacao negada nem altere o sandbox. Diferencie permissao nativa de gate do Ork.
+
+Antes do despacho, use `ork_preflight({modo})`; alternativa CLI: `ork doctor --modo <modo>`. A sonda segue setup por bloco, sem inventário global, e não comprova autenticação, gates ou entrega.
+Para HEADs e estado Git, consulte `ork_git_status`; nao invente SHAs nem substitua o transporte por Bash Git.
+O perfil filho `worktree` e opt-in da instalacao do projeto; nao o habilite por argumento de ferramenta
+ou edicao de configuracao para contornar bloqueio. Preserve o perfil configurado e as permissoes nativas.
+
+A sessao condutora despacha e acompanha; uma sessao que ja recebeu uma fase executa essa fase,
+sem redespachar a si mesma. O nucleo continua validando fases, evidencias e gates.
+
+Mostre o resultado, o ultimo progresso confirmado e o que acontece agora. Registre checkpoint
+antes de uma retomada futura; nao prometa notificacao fora das capacidades da sessao.
+Conclua com entrega e validacao efetivas, distinguindo o que ainda depende de CHECK, SHIP ou
+score humano. A lista de comandos executados e diagnostico auxiliar, nao a experiencia do dono.

package/adapters/claude-code/hooks/hooks.json

@@ -12,6 +12,11 @@
           }
         ]
       }
-    ]
+    ],
+    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }],
+    "Notification": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }],
+    "Stop": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }],
+    "SubagentStop": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }],
+    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }]
   }
 }

package/adapters/claude-code/hooks/ork-guard.js

@@ -52,7 +52,7 @@ const BLOQUEIOS = [
     nome: 'reset-destrutivo',
     regex: /\bgit\s+(?:reset\s+--hard|clean\s+-[a-zA-Z]*[fd]|checkout\s+--\s+\.)/,
     motivo: 'descarte em massa apaga trabalho nao commitado sem deixar rastro',
-    caminho: 'descarte por arquivo, ou registre a decisao antes: ork gate approve <thread> <sobre> --por <quem>',
+    caminho: 'descarte por arquivo; se o descarte amplo for mesmo necessario, peca a decisao ao dono: ork gate request <thread>',
   },
   {
     nome: 'remocao-recursiva-ampla',

package/adapters/claude-code/hooks/ork-sensor.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict';
+// Sensor passivo: stdout vazio e exit 0 não aprovam nem negam uma ferramenta.
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { createHash, randomUUID } = require('node:crypto');
+
+function executar() {
+  const limite = 1024 * 1024;
+  const buffer = Buffer.alloc(limite + 1);
+  let bytes = 0;
+  while (bytes <= limite) {
+    const n = fs.readSync(0, buffer, bytes, buffer.length - bytes, null);
+    if (!n) break;
+    bytes += n;
+    if (bytes > limite) return;
+  }
+  const h = JSON.parse(buffer.subarray(0, bytes).toString('utf8'));
+  if (!h || typeof h.cwd !== 'string' || !path.isAbsolute(h.cwd) ||
+      typeof h.session_id !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(h.session_id)) return;
+  const tipos = { PermissionRequest: 'permission_request', Notification: 'notification',
+    Stop: 'stop', SubagentStop: 'subagent_stop', PostToolUse: 'heartbeat' };
+  let tipo = tipos[h.hook_event_name];
+  if (!tipo) return;
+  const payload = { observedAt: new Date().toISOString() };
+  if (h.hook_event_name === 'Notification') payload.notificationType = h.notification_type;
+  // tool_use_id identifica replay da mesma ferramenta. Sem id do protocolo,
+  // cada invocação é uma ocorrência; stat do transcript não identifica eventos.
+  payload.eventId = typeof h.tool_use_id === 'string'
+    ? createHash('sha256').update(JSON.stringify([h.hook_event_name, h.tool_use_id, h.agent_id])).digest('hex')
+    : randomUUID();
+  if (h.hook_event_name === 'PostToolUse' && h.tool_name === 'Bash') {
+    const resposta = h.tool_response;
+    if (resposta?.interrupted || (resposta?.exit_code !== undefined && resposta.exit_code !== 0) ||
+        (resposta?.exitCode !== undefined && resposta.exitCode !== 0)) return;
+    const comando = h.tool_input?.command;
+    const saida = typeof resposta === 'string' ? resposta : resposta?.stdout;
+    const shaCurto = typeof saida === 'string' ? /^\[[^\]\n]+ ([a-f0-9]{7,64})\]/m.exec(saida)?.[1] : null;
+    if (typeof comando === 'string' && /(?:^|[;&|\n])\s*git\s+commit(?:\s|$)/.test(comando) && shaCurto) {
+      const git = spawnSync('git', ['log', '-1', '--format=%H'], {
+        cwd: h.cwd, encoding: 'utf8', timeout: 1000, maxBuffer: 4096,
+      });
+      const sha = git.stdout?.trim();
+      if (git.status === 0 && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(sha) && sha.startsWith(shaCurto)) {
+        tipo = 'commit'; payload.commit = sha;
+      }
+    }
+  }
+  const r = spawnSync(process.env.ORK_SENSOR_CLI || 'ork',
+    ['sessions', 'event', '--tipo', tipo, '--sessao', h.session_id], {
+      cwd: h.cwd, input: JSON.stringify(payload), encoding: 'utf8', timeout: 3000,
+      maxBuffer: 32768, windowsHide: true,
+    });
+  if (r.status !== 0) {
+    // Recusa conhecida não identifica o papel da sessão nem comprova ingestão.
+    const semVinculo = r.status === 1 && !r.error && !r.stdout?.trim() &&
+      r.stderr?.trim() === 'evento recusado: sessão desconhecida; confira ork thread status';
+    process.stderr.write(semVinculo
+      ? 'ork sensor: sessão sem fase vinculada; evento não ingerido. Se foi despachada pelo Ork, confira o vínculo com ork thread status.\n'
+      : 'ork sensor: evento não ingerido; confira o CLI e a sessão registrada.\n');
+  }
+}
+try { executar(); }
+catch { process.stderr.write('ork sensor: entrada inválida ou sensor indisponível.\n'); }
+process.exitCode = 0;

package/adapters/codex/skills/ork/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ork
+description: "Reconhece orkastery maestro em sessão limpa: consulta panorama, retoma threads e apresenta decisões nativas na conversa Codex com o Maestro/Builder."
+license: MIT
+---
+
+# Orkastery no Codex
+
+Ao receber literalmente `orkastery maestro`, descubra `ork_maestro` no namespace
+efetivamente exposto e consulte o projeto fixado pelo MCP. A frase pede panorama,
+sem abrir trabalho. Siga a seleção de contexto e os limites do bootstrap comum.
+Sem MCP, a consulta `ork maestro --json` continua somente leitura se o CLI estiver
+disponível; mutações sem transporte nativo permanecem pendentes. Nunca use Bash Git
+ou mudança de sandbox como substitutos. Sessão filha continua a fase recebida.
+
+HITL tem prioridade máxima na apresentação: tópicos curtos, recomendação e opções
+com rótulos claros; UUID interno. Use `ork_request_decision` na condutora e preserve
+a resposta literal/cancelamento da elicitation. Não use pergunta genérica do agente
+como aprovação de gate nem texto em toolargs como identidade humana.
+
+Use a skill `orkastery-bootstrap` do mesmo catalogo instalado para conduzir o pedido.
+O dono conversa sobre o objetivo; voce opera o nucleo `ork` e apresenta o resultado e o proximo
+passo. Preserve o modo e as autorizacoes da thread. Se ja recebeu uma fase do Orkastery,
+execute essa fase no escopo recebido, sem redespachar a si mesmo.
+
+Quando descobertas, prefira as ferramentas MCP vinculadas ao projeto pelo servidor:
+`ork_thread_status`, `ork_phase_list`, `ork_hitl_pending`, `ork_thread_new(nome, modo)`,
+`ork_phase_run(threadId, fase, prompt, runtime?, model?, effort?, dryRun?)`, `ork_observe(threadId)`
+e `ork_request_decision(threadId, pedidoId)`. Use o namespace efetivamente exposto, sem supor outro projeto.
+
+- Pedido novo: resolva o modo pelo `ork`, confira preflight e abra/despache a thread.
+- Retomada: leia `ork thread status <thread>` e o ultimo resultado em `ork phase list <thread>`;
+  continue o trabalho autorizado sem repetir onboarding, aprovacao ou implementacao.
+- Status: apresente a evidencia da thread; `ork pulse --json` mostra quem precisa agir.
+  As pausas dos blocos do modo sao previstas: so diga "aguardando voce" com pendencia
+  humana atual comprovada no estado/ultimo resultado, identificando gate, pedido ou evento.
+  Uma thread nova sem fase executada nem pedido aberto ainda nao aguarda veredito.
+- Despacho existente: consulte `ork_observe` para progresso ou bloqueio nativo atual;
+  nao espere conclusao com loops longos de `phase list`, sleeps ou regex sobre historico.
+- Decisao: se pausa/escalacao real permitir e faltar pedido, use `ork_gate_request(threadId, motivo?)`;
+  nunca crie pedido por status. Correlacione thread/pedido e use `ork_request_decision` para apresentar
+  o dialogo nativo. A resposta e fornecida pelo dono ao host; nunca invente identidade humana
+  nem passe resposta como argumento do modelo. Permissao nativa nao aprova outro gate.
+- Entrega: distinga o que foi implementado, validado, publicado e o que ainda esta pendente.
+
+As fases, verificacoes e gates pertencem ao nucleo. As skills de fase e as checklists do
+catalogo acompanham esta entrada. Se a skill comum estiver ausente, informe instalacao
+incompleta em vez de inventar outra metodologia.
+
+Use o executavel `ork` do projeto. Se nao estiver no PATH da sessao, o instalador registrou
+este caminho: `{{ork_bin}}`. Nao altere configuracao global para resolver o PATH.
+
+Sem MCP e com `.git` protegido pelo sandbox, informe instalacao pendente do transporte
+nativo; nao repita a mutacao negada, nao crie a thread por fora e nao amplie o sandbox.
+
+Nao ha monitor em segundo plano criado por esta skill. Acompanhe enquanto a sessao estiver
+ativa e deixe checkpoint para a retomada, com ultimo resultado e proximo passo comprovados.

package/adapters/hermes/README.md

@@ -1,5 +1,30 @@
 # Adaptador Hermes
 
+Na callback Discord autenticada, `/ork offer <thread> <pedido>` apresenta a
+pergunta e a oferta nativa sem responder. O gateway assina uma prova efêmera de
+host, sessão, identidade e mensagem e consulta `gate context --native-offer-stdin`.
+Somente a prova aceita pelo núcleo anuncia o canal nativo disponível naquela
+conversa, sem exigir Telegram. Chave/binding isolados ou payload do modelo não
+comprovam callback. Testes simulados não substituem homologação live pós-SHIP.
+
+## Transporte determinístico do pulse
+
+`bin/ork-pulse-enviar.py` chama a API `send_message_tool` do Hermes instalado e retorna
+código 0 somente com `success: true`. Não abre chat nem chama modelo. Use o Python do
+venv do Hermes e um destino explícito `telegram:chat_id[:topic_id]`:
+
+```json
+{
+  "executavel": "/caminho/hermes-agent/venv/bin/python3",
+  "argumentos": ["/repo/adapters/hermes/bin/ork-pulse-enviar.py", "--target", "telegram:CHAT_ID", "--message", "{{mensagem}}"]
+}
+```
+
+Grave a configuração em `.orkastery/monitor/pulse-host.json`. `HERMES_HOME` e
+`HERMES_AGENT_DIR` permitem localizar outra instalação; por padrão usa `~/.hermes`.
+O adaptador carrega o ambiente do host internamente, sem imprimir credenciais. Marcadores
+`MEDIA:` presentes no texto do runtime são neutralizados para não anexar arquivos locais.
+
 O Hermes vira **podio** do Orkastery: uma skill roteadora fina, um plugin que a declara e um script
 que abre thread a partir do pedido cru do builder.
 
@@ -18,6 +43,15 @@ ork adapter install hermes --dry-run             # lista o que seria escrito
 | `skills/orkastery-devmaster/SKILL.md` | O roteador: le a #TAG, chama o `ork`, apresenta os gates |
 | `hermes.plugin.json` | Declara a skill, o binario do `ork` e as tags de conducao |
 | `bin/ork-abrir-thread.sh` | Abre a thread com o modo lido do pedido, em um comando |
+| `bin/ork-brain.sh` | Consulta o Company Brain pelo contrato e identidade autenticada do OrkMind |
+
+## Tickets `obj-*` aposentados
+
+`ork_objective_status` e `ork_objective_message` sairam com o `ork objective` na I-43: o nucleo
+recusa qualquer subcomando com `objective.aposentado` e saida != 0. O estado de uma entrega vem de
+`ork thread status <thread>`; os ciclos ligados a um produto, projeto ou iniciativa, de
+`ork portfolio inspect <id> --json`. Mensagem de conversa continua sem aprovar gate: a decisao do
+dono passa pelo `/ork gate <thread> <pedido> <resposta>` correlacionado.
 
 ## O encolhimento, que e o ponto
 
@@ -29,6 +63,31 @@ real roda antes e depois; o que mudou e quem garante.
 Se esta skill comecar a crescer de novo com metodologia, isso e bandeira vermelha: a regra nova
 pertence ao nucleo, com teste, e nao a esta prosa.
 
+## Contas por runtime (I-33)
+
+Este host tem superfície CLI, e a paridade com os hosts MCP vem pelos mesmos comandos do
+núcleo; a superfície MCP de `accounts` não existe neste ciclo (o `add` é interativo e local, e
+a leitura de estado já sai de `ork_observe`).
+
+```bash
+ork accounts list [--json]                          # perfis por runtime, sem segredo
+ork accounts add <id> --runtime claude-bg|codex --dir <diretorio>
+ork accounts check [<id>]                           # confere o login pelo proprio CLI
+ork accounts remove <id>                            # desativa; diretorio e login ficam
+ork setup <modo> --bloco N --fallback codex:<modelo>
+```
+
+O login roda no terminal do operador, pelo próprio CLI do runtime com o env do perfil; o
+adaptador nunca recebe, guarda ou repassa credencial, e a conversa nunca é canal de login.
+Quando uma conta esgota a cota, o crédito ou o limite do plano, ou perde o login, o
+`ork retry run` rotaciona e grava `runtime_profile_rotated`; o host só apresenta o evento e a
+pendência humana quando houver. A troca para outro perfil do mesmo runtime por esgotamento vem
+ligada por padrão desde a decisão do dono de 19/09/2026
+(`runtime_profiles.rotate_same_runtime_on_quota: true`; `false` desliga), vale só para perfis
+que o operador cadastrou e autenticou pelo CLI oficial, para contas que ele tem direito de usar
+sob os termos do provedor, e nunca acontece no rate limit comum, que espera a janela na fila
+(ver `SECURITY.md` e `docs/guias/verificacao.md` na raiz do repositório).
+
 ## Os 3 pitfalls de instalacao
 
 1. **`ork` fora do PATH do Hermes.** O host costuma rodar com um ambiente mais enxuto que o do
@@ -43,3 +102,105 @@ pertence ao nucleo, com teste, e nao a esta prosa.
 3. **Validar `allowed_modes` no host.** Um host que recusa o modo antes de chamar o `ork` recusa
    com a regra que ele tem em cache, nao com a do manifesto do projeto. Deixe o
    `ork thread new` recusar: o erro vem tipado, com a lista permitida do projeto certo.
+
+## Transporte do digest MASTER
+
+`bin/ork-master-enviar.py --target telegram:<chat_id>[:<topico>]` recebe no stdin uma
+página JSON `ork.master-digest-page/v1`, com `texto` e `opcoes`. Usa a configuração Telegram
+do Hermes e só devolve `success: true` quando recebe `message_id`. Um erro não imprime
+credencial nem resposta bruta da API. O transporte não executa comandos do Ork.
+
+As opções são um teclado de respostas: o toque envia o texto escolhido como mensagem do
+humano pelo gateway já autenticado. Não há callback privado para o host interpretar.
+O núcleo gera o texto com thread, classe e identificador da proposta, e o host encaminha
+a resposta ao comando de ratificação com o nome do humano autenticado. Enviar a página
+não ratifica nada. Cada página oferece no máximo doze opções e cabe em 3.900 unidades UTF-16.
+
+Contrato do teclado: [Telegram ReplyKeyboardMarkup](https://core.telegram.org/bots/api#replykeyboardmarkup).
+Prova local: `python3 -m unittest discover -s adapters/hermes/test -p master_transport_test.py`.
+
+## Respostas HITL no Telegram
+
+O gateway autenticado entrega o update original por stdin a `bin/ork-hitl-answer.py ork_gate_answer <thread> <pedido>` ou `ork_session_answer`. Configure `ORK_BIN`, `ORK_HITL_TELEGRAM_USERS` e `ORK_HITL_TELEGRAM_CHATS` com os ids permitidos. Responda ao alerta que contém a linha `ork-hitl <thread> <pedido>`; botões usam `ork:<thread>:<pedido>:<número>`. O transporte recusa bots, chat/usuário não autorizado e resposta sem correlação. O núcleo decide sobre prazo, modo e validade do pedido.
+
+O script deve receber eventos diretamente do gateway, cuja autenticação do Telegram é a fronteira de confiança. JSON criado por um agente não é evidência humana. O canário usa um transporte controlado; ele não mede a rede Telegram real. Para aposentar `ork-watchdog-5min`, desative o job no agendador do host e guarde o recibo; nenhum watchdog deve chamar aprovação em nome do builder.
+
+Verificação: `python3 -m unittest discover -s adapters/hermes/test -p hitl_answer_test.py -v`.
+
+## Confirmação pelo plugin nativo HITL
+
+O plugin `hitl-ingress/` recebe `/ork gate <thread> <pedido> <resposta>` e
+`/ork session <thread> <pedido> <resposta>` em `pre_gateway_dispatch`. Esse hook
+instalado é **síncrono e anterior à autenticação do gateway**: o callback valida
+`MessageEvent`/`telegram.Message`, a autorização do host, usuário, chat, bot,
+texto/id coincidentes, encaminhamento, data de até 60 s e configuração HMAC.
+Todo comando `/ork ` é consumido com `action: skip`, inclusive quando recusado.
+Sem loop ativo, ele recusa; não cria outro loop para o cliente HTTP do bot.
+
+O callback reserva a mensagem e agenda o trabalho no loop do gateway. O CLI recebe
+o envelope HMAC por stdin UTF-8, sem shell, em executor, com timeout de 10 s
+(11 s incluindo espera pelo executor). Somente `ok: true`, `pedidoId` coincidente,
+`estado` compatível e `repetida` booleano permitem confirmar o efeito. Sessão exige
+também `sessionId`. A correlação de thread e mensagem vem da invocação CLI exata
+e do envelope validado pelo núcleo; o recibo atual do CLI não ecoa esses campos.
+A prova dirigida simula esse núcleo e não substitui seu CHECK integrado.
+
+`Message.reply_text` usa o bot e chat do objeto autenticado no mesmo loop. Os únicos
+textos são “Orkastery: resposta ao gate registrada pelo núcleo.” e “Orkastery:
+resposta entregue à sessão pelo núcleo.” Não há quote da resposta humana,
+parse mode, stdout ou exceção no conteúdo. Recusa de gate também é uma resposta
+registrada; a mensagem não diz que houve aprovação. A confirmação tem orçamento
+total de 3 s e os quatro timeouts do PTB explícitos. Sucesso exige um `Message`
+nativo retornado, id positivo e bot/chat/texto correspondentes.
+
+Retorno do hook e logs distinguem `effect` de `confirmation`:
+
+| Situação | effect | confirmation |
+|---|---|---|
+| Validação recusada, sem loop ou limite atingido | unconfirmed | not_attempted |
+| Trabalho agendado | pending | not_attempted |
+| CLI iniciado sem recibo válido, timeout ou cancelamento | unknown | not_attempted |
+| Recibo do núcleo válido; confirmação falhou ou ficou ambígua | confirmed | unknown |
+| Recibo do núcleo e recibo Telegram válidos | confirmed | sent |
+
+O retorno inicial é um retrato do agendamento; o log de conclusão registra o
+resultado final com referência opaca derivada da identidade da mensagem. Não é
+um ledger durável de entrega. Há no máximo 16 trabalhos pendentes e 1.024 reservas;
+reservas concluídas podem ser removidas após 61 s, e mensagens com data vencida são
+recusadas. O cache guarda apenas metadados, sem resposta humana, chave ou stdout.
+
+Replay idêntico no mesmo processo apenas consulta o estado: não chama o CLI nem
+repete a confirmação. Reutilizar a mesma mensagem com operação, resposta, usuário,
+thread ou pedido divergente é recusado. Após restart/perda do cache, a idempotência
+durável é do núcleo: `repetida: true` confirma o efeito, mas deixa o canal como
+`unknown` e suprime novo envio. Timeout do CLI pode ocorrer depois do efeito;
+timeout do Telegram pode ocorrer depois da entrega. Não há rollback do efeito,
+retry automático ou garantia de entrega/leitura exatamente uma vez. Em particular,
+um crash entre efeito e confirmação pode deixar o remetente sem confirmação.
+
+Prova dirigida com ambiente removido antes dos imports, casas temporárias, bloqueio
+de rede no verificador e transportes **SIMULADOS**. Exercita as classes, o loader,
+a descoberta opt-in/cache e `invoke_hook` do Hermes instalado, além das regressões
+Python deste adaptador. Não inicia gateway, não usa chaves operacionais nem API real:
+
+```sh
+env -i HOME="$HOME" PATH=/usr/bin:/bin PYTHONDONTWRITEBYTECODE=1 "$HOME/.hermes/hermes-agent/venv/bin/python" adapters/hermes/test/verify_hitl_confirmation.py
+```
+
+O comando imprime contagem, falhas, limites e hashes das fontes instaladas; falha
+se faltar o contrato local, houver teste ignorado ou tentativa bloqueada de ler
+segredo operacional/rede. Não exige build de core. O plano de instalação revisável,
+hashes do pacote e preservação/rollback do agente Hermes instalado pertencem ao
+checkpoint de instalação; instalação e aceite Telegram real são etapas posteriores.
+# HITL nativo e Maestro
+
+`orkastery maestro` consulta panorama por `ork_maestro`. Prioridade máxima da
+conversa: tópicos, recomendação e escolhas claras, preservando resposta e cancelamento.
+Telegram é opcional. O callback instalado `pre_gateway_dispatch` pode receber
+Discord sem Telegram, com `discord.Message`, usuário autorizado, sessão existente
+e binding privado `ORK_HITL_NATIVE_BINDING_HERMES`/`ORK_HITL_NATIVE_KEY_HERMES`.
+Chaves e bindings nunca são publicados ao modelo ou herdados pela sessão filha.
+Terminal/ACP sem callback de identidade homologado permanece indisponível; hooks de
+aprovação de comando são observadores e não aprovam gates Orkastery.
+O plugin lê o pedido pelo CLI do núcleo e responde na mesma conversa só após recibo.
+Loader fixture não prova homologação live; instalação e sessão nova pós-SHIP são pendentes.

package/adapters/hermes/bin/ork-abrir-thread.sh

@@ -8,6 +8,8 @@
 # Uso: ork-abrir-thread.sh "<nome curto>" "<pedido inteiro do builder>" [--worktree auto]
 
 set -eu
+# I-36 (D6): o adaptador declara o canal de conducao do Hermes; descreve a porta, nao da autoridade.
+export ORK_CANAL="${ORK_CANAL:-hermes}"
 
 if [ "$#" -lt 2 ]; then
   echo "uso: ork-abrir-thread.sh \"<nome curto>\" \"<pedido do builder>\" [argumentos extras]" >&2

package/adapters/hermes/bin/ork-brain.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Host routing only. Authenticated principal and grants belong to the transport.
+set -eu
+exec "{{ork_bin}}" brain "$@"

package/adapters/hermes/bin/ork-hitl-answer.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Responde HITL a partir de um update Telegram entregue pelo gateway autenticado."""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+def lista_permitida(nome):
+    return {v.strip() for v in os.environ.get(nome, '').split(',') if v.strip()}
+
+
+def argumentos(update, operacao, thread, pedido):
+    if operacao not in ('ork_gate_answer', 'ork_session_answer'):
+        raise ValueError('comando HITL inválido')
+    if not re.fullmatch(r'[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}', thread):
+        raise ValueError('thread inválida')
+    if not re.fullmatch(r'[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}', pedido):
+        raise ValueError('pedido inválido')
+    callback = update.get('callback_query')
+    mensagem = callback.get('message', {}) if callback else update.get('message', {})
+    remetente = callback.get('from', {}) if callback else mensagem.get('from', {})
+    usuario = str(remetente.get('id', ''))
+    chat = str(mensagem.get('chat', {}).get('id', ''))
+    if (not usuario or not chat or remetente.get('is_bot') is not False
+            or usuario not in lista_permitida('ORK_HITL_TELEGRAM_USERS')
+            or chat not in lista_permitida('ORK_HITL_TELEGRAM_CHATS')
+            or mensagem.get('forward_origin')):
+        raise ValueError('origem humana não autorizada pelo gateway')
+    marker = f'ork-hitl {thread} {pedido}'
+    if callback:
+        prefixo = f'ork:{thread}:{pedido}:'
+        dado = callback.get('data', '')
+        if not isinstance(dado, str) or not dado.startswith(prefixo):
+            raise ValueError('callback não corresponde ao pedido')
+        resposta = dado[len(prefixo):]
+        if not re.fullmatch(r'[1-9][0-9]?', resposta):
+            raise ValueError('opção de callback inválida')
+        referencia = callback.get('id')
+    else:
+        origem = mensagem.get('reply_to_message', {}).get('text', '')
+        if marker not in origem.splitlines():
+            raise ValueError('responda à mensagem do pedido HITL')
+        resposta = mensagem.get('text', '')
+        referencia = mensagem.get('message_id')
+    if (not isinstance(resposta, str) or not resposta.strip() or len(resposta) > 4096
+            or '\x00' in resposta or not referencia):
+        raise ValueError('resposta ou referência de mensagem inválida')
+    return ['gate' if operacao == 'ork_gate_answer' else 'sessions', 'answer', thread, pedido,
+            '--resposta-stdin', '--por', f'telegram:{usuario}',
+            '--mensagem', f'telegram:{chat}:{referencia}', '--origem', 'telegram'], resposta
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('comando', choices=['ork_gate_answer', 'ork_session_answer'])
+    parser.add_argument('thread')
+    parser.add_argument('pedido')
+    args = parser.parse_args()
+    try:
+        # O gateway fornece o update original por stdin, nunca uma descrição criada por LLM.
+        bruto = sys.stdin.read(65537)
+        if len(bruto) > 65536:
+            raise ValueError('update excede limite')
+        argv, resposta = argumentos(json.loads(bruto), args.comando, args.thread, args.pedido)
+        result = subprocess.run([os.environ.get('ORK_BIN', 'ork'), *argv],
+                                input=resposta, text=True, capture_output=True, timeout=55, check=False)
+        # O núcleo devolve um recibo sem repetir a resposta nem credenciais.
+        if result.returncode != 0:
+            print(json.dumps({'ok': False, 'erro': 'núcleo recusou a resposta', 'codigo': result.returncode}))
+            return 1
+        print(result.stdout.strip())
+        return 0
+    except (ValueError, TypeError, AttributeError, OSError, subprocess.TimeoutExpired):
+        print(json.dumps({'ok': False, 'erro': 'resposta HITL não confirmada'}))
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/adapters/hermes/bin/ork-maestro.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Somente leitura; cwd é o projeto do host. Argumentos continuam dados.
+set -eu
+# I-36 (D6): o adaptador declara o canal de conducao do Hermes; descreve a porta, nao da autoridade.
+export ORK_CANAL="${ORK_CANAL:-hermes}"
+exec "${ORK_BIN:-{{ork_bin}}}" maestro --json "$@"