@orkastery/cli 0.2.0 → 0.3.0

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,17 @@ 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 |
+| `bin/ork-objective-status.sh` | Lê o ticket canônico compartilhado com o Kanban |
+| `bin/ork-objective-message.sh` | Grava a mensagem do canal no histórico do ticket |
+
+## Continuidade com o Kanban
+
+Quando uma conversa mencionar um `obj-*`, use `ork_objective_status` para retomar o estado
+canônico e `ork_objective_message` para preservar a mensagem do Telegram. O Kanban relê o
+mesmo `messages.jsonl`, então o dono pode trocar de canal sem duplicar a demanda. O identificador
+do autor deve vir do gateway autenticado. Mensagens de conversa não aprovam gates: decisões
+continuam passando pelos comandos HITL correlacionados.
 
 ## O encolhimento, que e o ponto
 
@@ -29,6 +65,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 +104,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 "$@"

package/adapters/hermes/bin/ork-master-enviar.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Entrega uma página de digest com escolhas que chegam ao Hermes como texto humano."""
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+import re
+import sys
+
+
+def validar(payload, target):
+    if not re.fullmatch(r'telegram:-?\d+(?::\d+)?', target):
+        raise ValueError('destino Telegram explícito obrigatório')
+    if not isinstance(payload, dict) or payload.get('contrato') != 'ork.master-digest-page/v1':
+        raise ValueError('contrato de página inválido')
+    texto = payload.get('texto')
+    if not isinstance(texto, str) or not texto.strip() or len(texto.encode('utf-16-le')) // 2 > 3900:
+        raise ValueError('texto ausente ou maior que uma página')
+    opcoes = payload.get('opcoes')
+    if not isinstance(opcoes, list) or len(opcoes) > 12:
+        raise ValueError('opções inválidas')
+    if any(not isinstance(opcao, str) or not opcao.strip() or len(opcao) > 200 for opcao in opcoes):
+        raise ValueError('opção inválida')
+    partes = target.split(':')
+    return partes[1], int(partes[2]) if len(partes) == 3 else None
+
+
+async def entregar(payload, target, bot):
+    chat, topico = validar(payload, target)
+    # Teclado de texto usa o fluxo humano já autenticado pelo gateway do Hermes.
+    # Não depende de um callback desconhecido nem executa comando ao enviar o digest.
+    argumentos = {'chat_id': chat, 'text': payload['texto']}
+    if topico is not None:
+        argumentos['message_thread_id'] = topico
+    if payload['opcoes']:
+        argumentos['reply_markup'] = {
+            'keyboard': [[{'text': opcao}] for opcao in payload['opcoes']],
+            'resize_keyboard': True,
+            'one_time_keyboard': True,
+            'input_field_placeholder': 'Escolha a classe para ratificar a proposta',
+        }
+    resposta = await bot.send_message(**argumentos)
+    recibo = getattr(resposta, 'message_id', None)
+    if not isinstance(recibo, int) or recibo <= 0:
+        raise ValueError('Telegram não confirmou a mensagem')
+    return {'success': True, 'message_id': recibo, 'platform': 'telegram'}
+
+
+async def enviar_pelo_hermes(payload, target):
+    validar(payload, target)
+    home = Path(os.environ.get('HERMES_HOME', Path.home() / '.hermes'))
+    agent = Path(os.environ.get('HERMES_AGENT_DIR', home / 'hermes-agent'))
+    sys.path.insert(0, str(agent))
+    from dotenv import load_dotenv
+    load_dotenv(home / '.env', override=False)
+    from gateway.config import load_gateway_config, Platform
+    from telegram import Bot
+    config = load_gateway_config().platforms.get(Platform.TELEGRAM)
+    if not config or not config.enabled or not config.token:
+        raise ValueError('Telegram não configurado no Hermes')
+    async with Bot(token=config.token) as bot:
+        return await entregar(payload, target, bot)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--target', required=True)
+    args = parser.parse_args()
+    try:
+        bruto = sys.stdin.read(65537)
+        if len(bruto.encode('utf-8')) > 65536:
+            raise ValueError('payload excede o limite')
+        recibo = asyncio.run(enviar_pelo_hermes(json.loads(bruto), args.target))
+        print(json.dumps(recibo))
+        return 0
+    except Exception as exc:
+        # Configuração, credenciais e resposta bruta nunca entram no erro de transporte.
+        print(json.dumps({'success': False, 'erro': type(exc).__name__}))
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/adapters/hermes/bin/ork-objective-message.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+# Acrescenta uma mensagem do canal ao mesmo histórico durável visto no Kanban.
+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 3 ]; then
+  echo "uso: ork-objective-message.sh <objective-id> <autor-do-canal> <texto>" >&2
+  exit 2
+fi
+
+OBJECTIVE="$1"
+AUTHOR="$2"
+shift 2
+
+exec "${ORK_BIN:-ork}" objective message "$OBJECTIVE" \
+  --text "$*" --por "$AUTHOR" --role human

package/adapters/hermes/bin/ork-objective-status.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env sh
+# Lê o ticket canônico para que o Hermes continue a conversa iniciada no Kanban.
+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 [ "$#" -ne 1 ]; then
+  echo "uso: ork-objective-status.sh <objective-id>" >&2
+  exit 2
+fi
+
+exec "${ORK_BIN:-ork}" objective status "$1" --json

package/adapters/hermes/bin/ork-pulse-enviar.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Transporte de texto do pulse pela API de mensagem do Hermes, sem inferência."""
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import sys
+
+
+def texto_seguro(message):
+    message = re.sub(r'(?i)MEDIA\s*:', 'MEDIA [texto]:', message)
+    return re.sub(r'(?i)\[\[(?:audio_as_voice|as_document)\]\]', '[diretiva em texto]', message)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--target', required=True, help='Destino explícito: telegram:chat_id[:topic_id]')
+    parser.add_argument('--message', required=True)
+    args = parser.parse_args()
+    if not re.fullmatch(r'telegram:-?\d+(?::\d+)?', args.target):
+        parser.error('use identificador explícito do chat Telegram autorizado')
+    home = Path(os.environ.get('HERMES_HOME', Path.home() / '.hermes'))
+    agent = Path(os.environ.get('HERMES_AGENT_DIR', home / 'hermes-agent'))
+    sys.path.insert(0, str(agent))
+    try:
+        from dotenv import load_dotenv
+        load_dotenv(home / '.env', override=False)
+        from tools.send_message_tool import send_message_tool
+        # Conteúdo do runtime é texto. Não pode pedir ao host que anexe arquivo local.
+        message = texto_seguro(args.message)
+        result = send_message_tool({'action': 'send', 'target': args.target, 'message': message})
+        data = json.loads(result) if isinstance(result, str) else result
+        if (not isinstance(data, dict) or data.get('success') is not True or data.get('skipped')
+                or not (data.get('message_id') or data.get('message_ids'))):
+            print(json.dumps({'success': False, 'erro': 'Hermes não confirmou a entrega'}))
+            return 1
+        print(json.dumps({k: data[k] for k in ['success', 'message_id', 'message_ids', 'platform'] if k in data}))
+        return 0
+    except Exception as exc:
+        # Não imprimir configuração, credencial ou resposta bruta de uma API.
+        print(json.dumps({'success': False, 'erro': type(exc).__name__}))
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/adapters/hermes/hermes.plugin.json

@@ -5,17 +5,39 @@
   "description": "Conducao de looping threads em 6 fases pelo nucleo `ork`. O Hermes vira podio: le a #TAG do pedido, chama o `ork` e apresenta os gates ao humano.",
   "license": "MIT",
   "kind": "skill-router",
-  "skills": ["./skills/orkastery-devmaster"],
+  "skills": [
+    "./skills/orkastery-devmaster"
+  ],
   "bin": {
-    "ork-abrir-thread": "./bin/ork-abrir-thread.sh"
+    "ork_maestro": "./bin/ork-maestro.sh",
+    "ork-abrir-thread": "./bin/ork-abrir-thread.sh",
+    "ork_brain": "./bin/ork-brain.sh",
+    "ork_objective_status": "./bin/ork-objective-status.sh",
+    "ork_objective_message": "./bin/ork-objective-message.sh",
+    "ork_gate_answer": "./bin/ork-hitl-answer.py",
+    "ork_session_answer": "./bin/ork-hitl-answer.py"
   },
   "requires": {
     "ork": ">=0.1.0",
     "comando": "{{ork_bin}}"
   },
   "conduction": {
-    "tags": ["#Look", "#Ork", "#Classic", "#Maestro", "#Auto"],
+    "tags": [
+      "#Classic",
+      "#Maestro",
+      "#Auto",
+      "#Fast"
+    ],
+    "aposentadas": [
+      "#Look",
+      "#Ork"
+    ],
     "parse": "ork modos --do-pedido \"<pedido>\"",
-    "nota": "O host transporta a tag. A validacao contra conduction.allowed_modes e do nucleo."
+    "nota": "O host transporta a tag. A validacao contra conduction.allowed_modes e do nucleo. Uma #TAG aposentada recebe recusa tipada modo.aposentado do nucleo, com saida != 0; o host nao a traduz nem a ignora."
+  },
+  "onboarding": {
+    "pauta": "ork onboarding",
+    "estado": "ork onboarding show --json",
+    "nota": "Etapas e validação são do núcleo; valores secretos somente em ~/.hermes/.env."
   }
 }