@orkastery/cli 0.2.0 → 0.4.1

package/adapters/hermes/skills/orkastery-devmaster/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orkastery-devmaster
-description: "Roteador do Orkastery no Hermes: le a #TAG de conducao do pedido do builder, chama o `ork` para abrir e conduzir a thread pelas 6 fases, e apresenta os gates ao humano. Zero regra de negocio: quem decide e o humano, quem verifica e o `ork`."
+description: "Reconhece orkastery maestro no Hermes: consulta panorama pelo ork_maestro, conduz demandas autorizadas e apresenta HITL na conversa."
 bucket: hermes
 roteia: "ork modos --do-pedido | ork thread new | ork phase run | ork ship | ork master"
 license: MIT
@@ -8,6 +8,20 @@ license: MIT
 
 # Orkastery no Hermes
 
+Mensagem literal `orkastery maestro`: use `ork_maestro` (wrapper de `ork maestro --json`)
+para consultar panorama do projeto atual. Não abra thread por essa consulta. Apresente
+fontes/lacunas e próximas ações; ausência/ambiguidade de projeto exige contexto permitido.
+Em sessão de fase já despachada, siga o bloco recebido sem abrir outra orquestração.
+Ações usam os comandos tipados do núcleo com precondições e readback.
+
+Usabilidade HITL tem prioridade máxima: tópicos, recomendação e opções claras, UUID
+interno. Telegram é opcional. Só anuncie ingresso humano disponível quando o callback
+do host estiver homologado e configurado; texto de tool não é identidade humana.
+Sem ingresso no canal escolhido, conserve o pedido pendente e explique o motivo.
+Não altere runtime, provider, perfil filho ou sandbox para contornar falha.
+Horário para o dono sai no fuso dele (`owner.timezone`): use `prazoLocal` e os fatos
+`*Local` do JSON (ex.: `19/09 15:16 (horário de Brasília)`), nunca o ISO em UTC.
+
 ## O que esta skill e
 
 O roteador do Orkastery dentro do Hermes, e **so isso**. Ela nao conduz fase por conta propria,
@@ -23,30 +37,47 @@ mora no `ork`; aqui ficou o roteador.**
 
 Sempre que o builder pedir trabalho de produto num repositorio que tem `orkastery.yaml`.
 
+## Onboarding do projeto
+
+Quando o builder pedir onboarding, execute `ork onboarding` para obter a pauta do núcleo.
+Consulte `ork onboarding show --json` para retomar as etapas pendentes. Conduza a conversa
+pela pauta devolvida e grave cada resposta pública com `ork onboarding set <etapa>
+--conteudo <JSON> --por <quem>`, transportando argumentos como dados. A pauta e a validação
+pertencem ao núcleo; não mantenha lista de etapas no host nem invente respostas.
+Credenciais são somente nomes de variáveis; valores secretos ficam em `~/.hermes/.env`.
+Use `ork onboarding reset [etapa]` quando solicitado e `ork onboarding sync --json` para
+publicação opcional. Apresente o motivo tipado de degradação quando a memória não publicar.
+Onboarding não exige criar thread de produto. Ao concluir, apresente `ork onboarding show --json`.
+
 ## Passo 1: o modo sai do pedido, nao de configuracao
 
 ```bash
 MODO=$(ork modos --do-pedido "<pedido inteiro do builder>")
 ```
 
-O comando usa a mesma funcao do nucleo que reconhece `#Look`, `#Ork`, `#Classic`, `#Maestro` e
-`#Auto`. Sem tag no texto vale o `conduction.default_mode` do manifesto. **Nao reimplemente esse
-parse aqui**, e nao valide o modo: `conduction.allowed_modes` e conferido dentro do
-`ork thread new`, que recusa com erro tipado quando o projeto nao permite o modo pedido.
+O comando usa a mesma funcao do nucleo que reconhece `#Classic`, `#Maestro`, `#Auto` e `#Fast`.
+Sem tag no texto vale o `conduction.default_mode` do manifesto. **Nao reimplemente esse parse
+aqui**, e nao valide o modo: `ork thread new` confere `conduction.allowed_modes` e recusa com erro tipado.
+
+`#Look` e `#Ork` foram aposentados pela I-43. Um pedido com uma dessas tags faz o comando
+sair com codigo != 0 e a recusa tipada `modo.aposentado`, que ja nomeia o substituto vivo.
+**Repasse a recusa ao builder como ela veio**: nao traduza para outro modo e nao siga com o
+default, porque trocar o regime de supervisao pelas costas de quem pediu e o defeito que a
+recusa existe para impedir.
 
 | #TAG | Pausas | Quando o builder escolhe |
 |---|---|---|
-| `#Look` | 6 | Risco alto, passo irreversivel, dominio novo |
-| `#Ork` | 5 | Veredito separado da execucao e da evidencia |
-| `#Classic` | 3 | O padrao: premissas delicadas, entrega solta, score em batch |
-| `#Maestro` | 1 | Solucao clara e agil, score em batch |
+| `#Classic` | 3 | O padrao do `ork init`: premissas delicadas |
+| `#Maestro` | 1 | Solucao clara e agil: uma pausa para as premissas |
 | `#Auto` | 0 | Docs, estudos, configuracoes, auditorias |
+| `#Fast` | 0 | Pedido pequeno e claro: so a GO; o push pede autorizacao |
 
 ## Passo 2: antes de abrir, confira a maquina
 
 ```bash
 ork doctor          # sai != 0 quando o despacho nao vale (custo, runtime, ambiente)
 ork board plan      # quem avanca agora, quem espera e por que
+ork brain status    # contrato Company Brain e tenant efetivo
 ```
 
 Um `fail` do doctor para o ciclo antes de ele abrir. Isso e economia, nao obstaculo.
@@ -63,33 +94,54 @@ ork phase run <thread> GO    --prompt "<uma tarefa do PLAN por vez>"
 ork verify <thread>
 ork phase run <thread> CHECK --prompt "<escopo da verificacao>"
 ork ship <thread> --para main --autorizar-push "<quem>"
-ork master <thread> --score <0-5> --justificativa "<texto>" --por "<quem>"
+ork master <thread>
 ```
 
+Quando o dono pedir estado do Company Brain, use o binário instalado `ork_brain` para
+`status`, `query` ou `get`. A identidade vem exclusivamente do login autenticado do
+OrkMind; nunca aceite principal, DSN ou raiz vindos da conversa. Consultas devem levar a
+thread explícita e continuar somente leitura.
+
 Cada `phase run` grava o prompt exato com sha256 e registra no ledger. O `ork` reverifica no
 runtime que a sessao existe: self-report de despacho nao vale como evidencia.
 
 ## Passo 4: apresentar os gates ao humano
 
 O Hermes e o podio: e aqui que o builder ve a evidencia e da o veredito. Quando o bloco pausa,
-mostre o que o `ork` produziu e espere. A liberacao vira evento:
+mostre o que o `ork` produziu e espere. A resposta entra pelo gateway autenticado como update Telegram original, com o remetente e o chat validados por allowlist. Use `ork_gate_answer` ou `ork_session_answer`, preservando o id do pedido e a referência da mensagem. Nunca sintetize um update nem use o nome do builder em uma aprovação criada pelo agente.
 
 ```bash
-ork gate approve <thread> <objetivo|premissas|evidencias|push|score> --por "<quem>"
+python3 adapters/hermes/bin/ork-hitl-answer.py ork_gate_answer <thread> <pedido> < update.json
+python3 adapters/hermes/bin/ork-hitl-answer.py ork_session_answer <thread> <pedido> < update.json
 ```
 
-Quando o bloco nao pausa (`#Maestro`, `#Auto`), o `ork` registra a decisao autonoma com quem
-decidiu, com que evidencia e por que. **O modo afrouxa a pausa, NUNCA a verificacao.**
+`ORK_HITL_TELEGRAM_USERS` e `ORK_HITL_TELEGRAM_CHATS` contêm os ids permitidos, separados por vírgula. Sem configuração o comando recusa. A profundidade já vem do núcleo. Expiração só espera ou escala, nunca aprova. Push e score não são delegáveis.
 
-## Passo 5: o score
+### Atencao em camadas (I-41) e os formatos que o ingresso aceita
 
-O score de 0 a 5 e humano em todos os modos. Nos modos sem pausa de MASTER, ele vai para a fila:
+O nucleo monta e o Hermes so transporta: (1) UM resumo recorrente com as contagens e
+`Posso te mandar as perguntas agora?`; (2) o dono responde com o codigo e a letra (`K7QX a`);
+(3) com o sim, ate cinco objetivas a–d com uma recomendada, respondidas numa linha (`1a 2c 3b`).
+Decisao obvia chega tomada e informada no resumo (`ork decisao registrar`). Cadencia (I-50): so a tag na mensagem (`#OrkPulseOff` 8h, `#OrkPulseOn` 2h, `#OrkPulseOn-15m`, `-30m`, `-60m`); pedida no meio da frase, devolva a tag exata para o dono mandar sozinha.
 
-```bash
-ork master --batch
-```
+O plugin `orkastery-hitl` so registra esses tres formatos e `/ork gate|session <thread> <pedido> <resposta>`,
+em texto puro, da allowlist, com menos de 60 s. "1. Aprovado" em conversa **nao registra nada**:
+devolva na hora a linha exata, com o id atual de `ork gate request <thread>` (o id muda a cada
+renovacao). **Voce nunca responde pelo dono**: `ork gate answer` do terminal falha com
+`proveniencia em argv diverge do envelope`, e essa e a defesa funcionando.
+
+Quando o bloco nao pausa (`#Maestro`, `#Auto`, `#Fast`), o `ork` registra a decisao autonoma com quem
+decidiu, com que evidencia e por que. **O modo afrouxa a pausa, NUNCA a verificacao.**
+
+## Passo 5: a entrega e o MASTER
+
+O MASTER fecha com POSTMORTEM tipado e indice derivado do ledger; ninguem digita nota para a fila
+andar. `ork master` mostra as entregas; `ork master --aceitar-omissao` aceita as pendentes com
+registro; a nota humana sobrescreve. `ork master --batch` saiu na I-43 (`master.fila-aposentada`).
 
-Fila que ninguem passa e score que nao existe. Traga a fila ao builder.
+Memoria "degradada" tem dois portoes: a variavel da DSN no ambiente do processo
+(`memory_degraded` com `dsn.env-ausente`) e a ativacao de escrita com aceite humano
+(`write.activation.disabled`). Diagnostico: `ork memory status` e `ork doctor`.
 
 ## Racionalizacoes comuns
 
@@ -99,7 +151,8 @@ Fila que ninguem passa e score que nao existe. Traga a fila ao builder.
 | "Guardo as regras da metodologia nesta skill" | Metodologia em prosa e metodologia que ninguem verifica. Ela mora no `ork`; aqui fica o roteamento. |
 | "Valido o modo antes de chamar o `ork`" | Validacao duplicada e validacao que vai divergir. `conduction.allowed_modes` e do nucleo. |
 | "O builder confia, pulo o gate desta vez" | Gate pulado e gate que nao existe. Se o modo nao pausa, o `ork` registra a decisao autonoma; se pausa, ele espera. |
-| "Score eu estimo pelo resultado" | O score e do humano em todos os modos. Estimar nota destroi a unica metrica de conducao do produto. |
+| "Score eu estimo pelo resultado" | O indice sai do ledger e a nota, quando existe, e do humano. Estimar nota destroi a metrica de conducao. |
+| "O dono respondeu na conversa, eu registro" | So o ingresso registra, com prova HMAC do update. Devolva a linha exata para ele mandar. |
 
 ## Bandeiras vermelhas
 
@@ -107,7 +160,7 @@ Fila que ninguem passa e score que nao existe. Traga a fila ao builder.
 - Chamada de `git` direta em vez de `ork ship`.
 - Modo escolhido por configuracao do host, e nao pela #TAG do pedido.
 - Thread aberta com `ork doctor` em `fail`.
-- Fila de `ork master --batch` crescendo sem ninguem passar nela.
+- Resposta do dono "registrada" pelo agente, sem o update autenticado do canal.
 
 ## Verificacao antes de responder ao builder
 

package/adapters/openclaw/README.md

@@ -1,18 +1,48 @@
 # Adaptador OpenClaw
 
-O OpenClaw recebe o Orkastery como um conjunto de **tools `ork_*`**: cada tool e uma chamada de CLI
-declarada em `openclaw.plugin.json`, sem codigo de cola e sem regra de negocio no host.
+O OpenClaw recebe o Orkastery como uma **extensao** no formato 2026.7.1: um pacote com
+`package.json` (`openclaw.extensions: ["./dist/index.js"]`), um entry JS que registra as
+**21 tools `ork_*`** via `defineToolPlugin` do SDK do proprio OpenClaw, e o manifesto
+`openclaw.plugin.json` gerado (`id`, `activation`, `contracts.tools`). Cada tool e uma
+chamada de CLI do `ork`, sem regra de negocio no host.
+
+## Estrutura do pacote
+
+| Arquivo | Papel |
+|---|---|
+| `package.json` | `openclaw.extensions` aponta o entry; sem dependencia de runtime |
+| `dist/index.js` | Entry construido; unico arquivo com o placeholder `{{ork_bin}}` |
+| `openclaw.plugin.json` | Manifesto GERADO por `openclaw plugins build` (nao editar na mao) |
+| `src/index.ts` | Fonte TS; `construir.sh` compila com o tsc do core |
+| `bin/ork-abrir-thread.sh` | Atalho de abertura de thread sem reimplementar o parse da #TAG |
+
+O entry importa `openclaw/plugin-sdk/tool-plugin`, que o loader do OpenClaw resolve por
+alias: o pacote nao precisa de `node_modules` no destino. Os parametros das tools sao JSON
+Schema literal (sem typebox). Se uma versao futura do `openclaw plugins validate` exigir
+typebox, adicione-o em `dependencies` e rode `npm install` no destino.
 
 ## Instalacao
 
 ```bash
-ork adapter install openclaw                     # instala em <projeto>/.openclaw
-ork adapter install openclaw --dir ~/.openclaw   # instala para a maquina
+ork adapter install openclaw                     # instala em <projeto>/.openclaw/extensions/orkastery
+ork adapter install openclaw --dir ~/.openclaw   # instala para a maquina, no source root global
 ork adapter install openclaw --dry-run           # lista o que seria escrito
 ```
 
-O instalador renderiza `{{ork_bin}}` com o caminho absoluto do `ork` desta maquina e grava
-`INSTALADO.json` com a origem e o sha256 de cada arquivo.
+O instalador renderiza `{{ork_bin}}` no `dist/index.js` com o caminho absoluto do `ork`
+desta maquina e grava `INSTALADO.json` com a origem e o sha256 de cada arquivo.
+
+**Registro no OpenClaw.** Com `--dir ~/.openclaw`, o destino
+`~/.openclaw/extensions/orkastery` ja e o source root `global` que o
+`openclaw plugins list` varre: reinicie o gateway e confira. Alternativas equivalentes:
+
+```bash
+openclaw plugins install ~/.openclaw/extensions/orkastery   # registra explicitamente
+# ou aponte plugins.load.paths para o diretorio instalado na config do OpenClaw
+```
+
+Se a copia nao passou pelo instalador (placeholder nao renderizado), o entry cai no
+fallback: usa `ORK_BIN` do ambiente ou o `ork` do PATH.
 
 ## As tools
 
@@ -27,37 +57,116 @@ O instalador renderiza `{{ork_bin}}` com o caminho absoluto do `ork` desta maqui
 | `ork_claims_add` | Registra alegacao verificavel com o comando que a comprova |
 | `ork_verify` / `ork_verify_baseline` | Reexecuta no HEAD real; grava a baseline antes do GO |
 | `ork_worktree_ensure` / `ork_worktree_audit` | Worktree isolada, conferida no proprio git |
-| `ork_gate_approve` | Autorizacao humana registrada no ledger |
+| `ork_objective_status` / `ork_objective_message` | Aposentadas com o `ork objective` na I-43: devolvem a recusa tipada `objective.aposentado` |
+| `ork_portfolio_list` | Lista produtos, projetos e iniciativas canônicos |
+| `ork_gate_answer` | Resposta humana correlacionada a um gate |
+| `ork_session_answer` | Resposta humana correlacionada a uma sessão |
 | `ork_ship` | Merge serializado por lease e push provado contra o remoto |
 | `ork_master` | POSTMORTEM tipado e o score HUMANO de 0 a 5 |
-| `ork_board` / `ork_master_batch` | Escalonador e fila de score |
+| `ork_board` | Escalonador: quem avanca agora e quem espera |
+| `ork_master_batch` | Todas as entregas, com o indice do ledger (`ork master --todas`; a fila de score saiu na I-43) |
 
 ## A #TAG de conducao
 
-`ork_modo_do_pedido` devolve JSON com o modo, a tag, se veio do pedido ou do
-`conduction.default_mode`, e quantas pausas humanas aquele modo tem. O host passa o resultado a
-`ork_thread_new` e **nao decide nada**: `conduction.allowed_modes` e conferido dentro do
-`ork thread new`, que recusa com erro tipado quando o projeto nao permite o modo.
+O manifesto novo do OpenClaw nao tem campo proprio para isso, entao a regra vive aqui e
+nas descricoes das tools: `ork_modo_do_pedido` devolve JSON com o modo, a tag, se veio do
+pedido ou do `conduction.default_mode`, e quantas pausas humanas aquele modo tem. O host
+passa o resultado a `ork_thread_new` e **nao decide nada**: `conduction.allowed_modes` e
+conferido dentro do `ork thread new`, que recusa com erro tipado quando o projeto nao
+permite o modo.
 
 ## Os 3 pitfalls de instalacao
 
-1. **Placeholder `{{ork_bin}}` que fica no arquivo.** O OpenClaw executa o vetor de comando como
-   ele esta: um `{{ork_bin}}` nao renderizado vira "comando nao encontrado" em toda tool, e a
-   sessao so descobre isso quando ja abriu thread na cabeca do agente. O instalador renderiza o
-   caminho absoluto; confira depois com
-   `grep -c '{{' <destino>/openclaw.plugin.json`, que precisa devolver `0`.
+1. **Placeholder `{{ork_bin}}` que fica no arquivo.** O unico placeholder renderizavel
+   vive no `dist/index.js`. Nao renderizado, o entry cai no fallback (`ORK_BIN` ou o `ork`
+   do PATH); sem fallback possivel, toda tool viraria "comando nao encontrado", e a sessao
+   so descobriria depois de ja ter aberto thread na cabeca do agente. Confira com
+   `grep -c '{{' <destino>/extensions/orkastery/dist/index.js`, que precisa devolver `0`.
+
+2. **Argumento com espaco quebrado em varios argumentos.** Cada tool monta o comando como
+   **vetor de argv** e chama o `ork` sem shell, exatamente para que um pedido com espaco,
+   aspas ou quebra de linha chegue inteiro em `--prompt`. Se voce adaptar uma tool,
+   mantenha o vetor: uma string de shell aqui vira injecao de comando com o texto do
+   builder dentro.
+
+3. **Tool que reimplementa regra do nucleo.** A tentacao e criar uma tool "esperta" que
+   decide o modo, monta o prompt ou escolhe a base. Toda tool deste plugin e uma chamada
+   de CLI e nada mais; a decisao que parece faltar aqui ja existe do outro lado, com
+   teste. Tool nova que precisa de logica e sinal de que a logica pertence ao `ork`.
 
-2. **Argumento com espaco quebrado em varios argumentos.** Cada tool declara o comando como
-   **vetor**, nunca como string de shell, exatamente para que um pedido com espaco, aspas ou
-   quebra de linha chegue inteiro em `--prompt`. Se voce adaptar uma tool, mantenha o vetor: uma
-   string de shell aqui vira injecao de comando com o texto do builder dentro.
+## Como reconstruir
+
+```bash
+bash adapters/openclaw/construir.sh                          # tsc do core compila src/ para dist/
+cd adapters/openclaw && openclaw plugins build --entry ./dist/index.js    # regenera o manifesto
+cd adapters/openclaw && openclaw plugins validate --entry ./dist/index.js # Plugin orkastery is valid.
+```
 
-3. **Tool que reimplementa regra do nucleo.** A tentacao e criar uma tool "esperta" que decide o
-   modo, monta o prompt ou escolhe a base. Toda tool deste plugin e uma chamada de CLI e nada
-   mais; a decisao que parece faltar aqui ja existe do outro lado, com teste. Tool nova que precisa
-   de logica e sinal de que a logica pertence ao `ork`.
+O `dist/` fica commitado: o instalador copia arquivos do repositorio, nao roda build.
 
 ## O que este adaptador nao faz
 
-Nao escreve codigo de produto, nao decide gate e nao valida modo. Ele traduz intencao em chamada de
-`ork`, apresenta o resultado ao humano e registra o que o humano decidiu.
+Nao escreve codigo de produto, nao decide gate e nao valida modo. Ele traduz intencao em
+chamada de `ork`, apresenta o resultado ao humano e registra o que o humano decidiu.
+
+## 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).
+
+## Respostas HITL
+
+`ork_gate_answer` e `ork_session_answer` recebem `thread`, `pedido` e `updateTelegram` original do gateway autenticado. Configure `ORK_HITL_TELEGRAM_USERS` e `ORK_HITL_TELEGRAM_CHATS` com os ids permitidos, separados por vírgula. A mensagem responde ao alerta com a linha `ork-hitl <thread> <pedido>`; callback contém `ork:<thread>:<pedido>:<opção>`. Bots, origem não autorizada e correlação incorreta são recusados antes do CLI.
+
+O gateway autenticado é a fronteira de confiança: conteúdo de conversa ou JSON criado por agente não comprova resposta humana. `ork_gate_approve` foi retirado do catálogo; migre o host para os comandos de resposta. Expiração nunca aprova, e delegação não pode aprovar push nem score. O núcleo fornece a profundidade da apresentação.
+
+Verificação: `sh adapters/openclaw/construir.sh && node --test adapters/openclaw/test/hitl-answer.test.mjs`.
+# Entrada Maestro
+
+O callback `inbound_claim` possui ingresso adicional `native` sem Telegram quando
+o SDK comprova `commandAuthorized`, `senderIsOwner`, sessão e identidade do contexto.
+Bindings/chave privados `ORK_HITL_NATIVE_BINDING_OPENCLAW`/`ORK_HITL_NATIVE_KEY_OPENCLAW`
+pertencem ao processo do gateway e ao núcleo, nunca ao modelo. Ausência de campo,
+conta/canal/sessão divergente ou recibo inválido mantém o pedido pendente. A resposta
+usa `/ork gate|session <thread> <pedido> <resposta>` na mesma conversa. Replay não
+reenvia confirmação. A homologação live exige instalação/ativação pós-SHIP.
+
+`orkastery maestro` roteia para `ork_maestro`, consulta JSON do núcleo com argv sem
+shell. O panorama não abre trabalho; fonte indisponível permanece explícita.
+Sessão filha executa o bloco recebido. A apresentação HITL prioriza tópicos,
+recomendação e opções rotuladas, sem UUID exposto. Telegram é opcional; ingresso
+nativo adicional só fica disponível após prova do callback e configuração do host.
+Instalação fixture/SDK simulado não comprova ativação em uma sessão real.
+
+Na callback autenticada, `/ork offer <thread> <pedido>` consulta a pergunta e a
+oferta nativa sem responder ao pedido. O gateway assina uma prova efêmera da
+mensagem e chama `gate context --native-offer-stdin`; só uma prova válida para
+aquele host, sessão e pedido anuncia disponibilidade na conversa. Configuração
+isolada, prova vencida ou texto produzido pelo modelo não demonstram callback.
+
+Antes de executar tools, o helper fixo `ork receipt-verifiers --json` autentica e
+prepara provas públicas dos recibos legados no projeto de `ORK_HITL_ROOT`, definido
+pelo gateway. Os bytes dos recibos e o ledger permanecem preservados. Só os
+verificadores públicos seguem ao executor; variáveis `ORK_HITL_*` são removidas.
+Autoridade presente com projeto, preparação ou verificadores indisponíveis recusa
+a execução da tool (`hitl.receipt.verifiers-unavailable`).

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

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Same Brain API as other hosts; no authority inferred from the launcher.
+set -eu
+exec "{{ork_bin}}" brain "$@"

package/adapters/openclaw/construir.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# Compila o entry TS do plugin para dist/ usando o tsc do core.
+#
+# Script de DESENVOLVIMENTO, rodado no repositorio do Orkastery; o dist/ gerado
+# fica commitado porque o `ork adapter install openclaw` copia arquivos do
+# repo, nao roda build. No diretorio instalado este script nao funciona (nao ha
+# core/ do lado) e nao precisa: o que roda la e o dist/index.js.
+
+set -eu
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+TSC="$DIR/../../core/node_modules/.bin/tsc"
+
+if [ ! -x "$TSC" ]; then
+  echo "tsc nao encontrado em $TSC; rode npm ci em core/ antes" >&2
+  exit 2
+fi
+
+exec "$TSC" -p "$DIR/tsconfig.json"

package/adapters/openclaw/dist/hitl-ingress.js

@@ -0,0 +1,199 @@
+/** Native inbound_claim hook only. Never register this callback as a model tool. */
+/** D12: this host is the `openclaw` channel, and the channel is signed, not labelled. */
+import { createHash, createHmac } from 'node:crypto';
+import { execFile } from 'node:child_process';
+/**
+ * I-41 (GO-FIX 1): the two shapes of an answer to the pulse summary, typed with no slash and no
+ * identifier: "P4EJ a" answers the summary and "1a 2c" answers the questions. The SAME sources
+ * live in the core (GRAMATICA_DO_PULSE, core/src/pulse-resposta.ts) and a core test checks they
+ * stay equal. The code starts with a letter and has a digit: ordinary chat never has this shape,
+ * and it never reads as an answer to the batch, which starts with the question number.
+ */
+const PULSE_CONSENT = new RegExp("^[ \\t]*(?=[A-HJKMNP-TV-Z][2-9A-HJKMNP-TV-Z]{0,2}[2-9])[A-HJKMNP-TV-Z][2-9A-HJKMNP-TV-Z]{3}[ \\t]+[^\\r\\n]{1,40}$", 'i');
+const PULSE_LOTE = new RegExp("^[ \\t]*[0-9]{1,2}[ \\t]*[a-zA-Z](?:[ \\t,;]*[0-9]{1,2}[ \\t]*[a-zA-Z])*[ \\t]*[.!]?[ \\t]*$");
+/** I-50 (RM-039): the pulse cadence tag, alone in the message. It starts with '#', so it never reads as the other two. */
+const PULSE_CADENCIA = new RegExp("^[ \\t]*#OrkPulse(?:On(?:-(?:15|30|60)m)?|Off)[ \\t]*[.!]?[ \\t]*$", 'i');
+/** The pulse address inside the signed body: neither a thread nor a request. The core translates. */
+const PULSE_ALVO = 'pulse', PULSE_ENDERECO = 'resposta';
+export function isPulseAnswer(text) {
+    return !text.includes('\0') && (PULSE_CONSENT.test(text) || PULSE_LOTE.test(text) || PULSE_CADENCIA.test(text));
+}
+export function registerHitlIngress(api, bin) {
+    api.on('inbound_claim', async (event, ctx) => {
+        if (typeof event.content !== 'string')
+            return { handled: false };
+        const pulse = !event.content.startsWith('/ork ') && isPulseAnswer(event.content);
+        if (!event.content.startsWith('/ork ') && !pulse)
+            return { handled: false };
+        const denied = { handled: true, reply: { text: 'Resposta HITL não confirmada. Confira ingresso e ledger do pedido.' } };
+        // The pulse summary goes out on Telegram; only there is an answer to it recognized.
+        if (event.channel !== 'telegram')
+            return pulse ? { handled: false } : nativeIngress(event, ctx, bin).catch(() => denied);
+        try {
+            const env = process.env, user = event.senderId ?? '', chat = event.conversationId ?? '', message = event.messageId ?? '';
+            const allowed = (key, value) => (env[key] ?? '').split(',').map(s => s.trim()).filter(Boolean).includes(value);
+            const age = Date.now() - Number(event.timestamp);
+            if (event.channel !== 'telegram' || ctx.channelId !== 'telegram' || event.commandAuthorized !== true ||
+                !env.ORK_HITL_OPENCLAW_ACCOUNT || event.accountId !== env.ORK_HITL_OPENCLAW_ACCOUNT || event.accountId !== ctx.accountId ||
+                !env.ORK_HITL_TELEGRAM_BOT_ID || user === env.ORK_HITL_TELEGRAM_BOT_ID ||
+                !/^\d+$/.test(user) || !/^-?\d+$/.test(chat) || !/^\d+$/.test(message) ||
+                user !== ctx.senderId || chat !== ctx.conversationId || message !== ctx.messageId ||
+                !allowed('ORK_HITL_TELEGRAM_USERS', user) || !allowed('ORK_HITL_TELEGRAM_CHATS', chat) ||
+                !Number.isFinite(age) || age < 0 || age > 60000)
+                return denied;
+            const match = /^\/ork (gate|session) ([a-zA-Z0-9][a-zA-Z0-9._-]{0,79}) ([a-zA-Z0-9][a-zA-Z0-9._-]{0,79}) ([\s\S]{1,4096})$/.exec(event.content);
+            // FX1: this channel signs with ITS OWN key. The shared ORK_HITL_INGRESS_KEY is kept
+            // for the legacy v1 envelope only, which this adapter no longer produces.
+            const key = env.ORK_HITL_INGRESS_KEY_OPENCLAW, root = env.ORK_HITL_ROOT;
+            if ((!pulse && !match) || event.content.includes('\0') || !key || Buffer.byteLength(key) < 32 || !root?.startsWith('/'))
+                return denied;
+            if (pulse)
+                return pulseIngress(event.content, { user, chat, message, key, root, bin, timestamp: Number(event.timestamp) }, denied);
+            const [, operation, thread, pedido, resposta] = match;
+            const canal = 'openclaw';
+            // FX5: the authorized account goes INSIDE the signed body. Checking `accountId` only
+            // here left the durable receipt proving generic telegram transport and nothing else:
+            // nobody reading it later could tell which OpenClaw account the decision came from.
+            const conta = env.ORK_HITL_OPENCLAW_ACCOUNT;
+            const envelope = { resposta, canal, conta, origem: 'telegram', por: `telegram:${user}`, mensagem: `telegram:${chat}:${message}`,
+                recebidoEm: new Date(Number(event.timestamp)).toISOString(), prova: '' };
+            envelope.prova = createHmac('sha256', key).update(JSON.stringify(['ork.hitl-answer/v2', thread, pedido, canal, conta,
+                envelope.origem, envelope.por, envelope.mensagem, envelope.recebidoEm, resposta])).digest('hex');
+            // `gate answer` exige --resposta-stdin; `sessions answer` exige --stdin. A mesma flag
+            // para os dois fazia o CLI recusar toda resposta de sessao antes de conferir qualquer coisa.
+            const args = [operation === 'gate' ? 'gate' : 'sessions', 'answer', thread, pedido,
+                operation === 'gate' ? '--resposta-stdin' : '--stdin',
+                '--origem', 'telegram', '--canal', canal, '--conta', conta, '--por', envelope.por, '--mensagem', envelope.mensagem];
+            // FX5: `ok` alone was never a receipt. The core answers with the typed verdict, and a
+            // reply to the human must only claim what that verdict says: a gate lands in one of
+            // three states, a session answer lands `entregue` with the session it reached, and
+            // `repetida` says whether this call caused the effect or merely found it already done.
+            const estados = operation === 'gate' ? ['aprovado', 'recusado', 'aguardando'] : ['entregue'];
+            const ok = await new Promise(resolve => {
+                const child = execFile(bin, args, { cwd: root, timeout: 10000, maxBuffer: 65536 }, (err, stdout) => {
+                    try {
+                        const r = JSON.parse(stdout);
+                        resolve(!err && r.ok === true && r.pedidoId === pedido && estados.includes(r.estado) &&
+                            typeof r.repetida === 'boolean' &&
+                            (operation === 'gate' || typeof r.sessionId === 'string' && r.sessionId.length > 0));
+                    }
+                    catch {
+                        resolve(false);
+                    }
+                });
+                child.stdin?.on('error', () => resolve(false));
+                child.stdin?.end(JSON.stringify(envelope));
+            });
+            return ok ? { handled: true, reply: { text: `Resposta recebida pelo núcleo para o pedido ${pedido}.` } } : denied;
+        }
+        catch {
+            return denied;
+        }
+    });
+}
+/**
+ * I-41 (GO-FIX 1): the owner answered the pulse summary or its questions. The whole text is the
+ * answer and the signed address is the pulse's; this adapter knows no request and picks nothing.
+ * The reply is the text the core composed, transported as is.
+ */
+async function pulseIngress(texto, m, denied) {
+    const canal = 'openclaw', conta = process.env.ORK_HITL_OPENCLAW_ACCOUNT ?? '';
+    const envelope = { resposta: texto, canal, conta, origem: 'telegram', por: `telegram:${m.user}`,
+        mensagem: `telegram:${m.chat}:${m.message}`, recebidoEm: new Date(m.timestamp).toISOString(), prova: '' };
+    envelope.prova = createHmac('sha256', m.key).update(JSON.stringify(['ork.hitl-answer/v2', PULSE_ALVO, PULSE_ENDERECO, canal, conta,
+        envelope.origem, envelope.por, envelope.mensagem, envelope.recebidoEm, texto])).digest('hex');
+    const args = ['pulse', 'responder', '--resposta-stdin', '--origem', 'telegram', '--canal', canal, '--conta', conta,
+        '--por', envelope.por, '--mensagem', envelope.mensagem];
+    const receipt = await new Promise(resolve => {
+        const child = execFile(m.bin, args, { cwd: m.root, timeout: 10000, maxBuffer: 65536 }, (err, stdout) => {
+            try {
+                resolve(err ? null : JSON.parse(stdout));
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        child.stdin?.on('error', () => resolve(null));
+        child.stdin?.end(JSON.stringify(envelope));
+    });
+    if (!receipt || receipt.ok !== true || receipt.contrato !== 'ork.pulse-resposta/v1' ||
+        typeof receipt.mensagem !== 'string' || !receipt.mensagem || typeof receipt.repetida !== 'boolean')
+        return denied;
+    // Same message already handled: never resend blindly.
+    return receipt.repetida ? { handled: true } : { handled: true, reply: { text: receipt.mensagem } };
+}
+/** SDK instalado: inbound_claim fornece commandAuthorized, senderIsOwner e sessionKey.
+ * Somente esta callback usa a chave privada; nenhuma tool registra nativeIngress. */
+async function nativeIngress(event, ctx, bin) {
+    const denied = { handled: true, reply: { text: 'Ingresso nativo indisponível ou identidade não comprovada. O pedido permanece pendente.' } };
+    const env = process.env, root = env.ORK_HITL_ROOT, key = env.ORK_HITL_NATIVE_KEY_OPENCLAW;
+    const binding = JSON.parse(env.ORK_HITL_NATIVE_BINDING_OPENCLAW ?? 'null');
+    const age = Date.now() - Number(event.timestamp);
+    if (!binding || binding.host !== 'openclaw' || !root?.startsWith('/') || !key || Buffer.byteLength(key) < 32 ||
+        event.commandAuthorized !== true || event.senderIsOwner !== true ||
+        !event.sessionKey || event.sessionKey !== ctx.sessionKey || event.sessionKey !== binding.sessionId ||
+        !event.messageId || event.messageId !== ctx.messageId || !binding.installationId || !binding.connectionId ||
+        event.channel !== ctx.channelId || event.channel !== binding.channelId ||
+        event.accountId !== ctx.accountId || event.accountId !== binding.accountId ||
+        event.senderId !== ctx.senderId || event.senderId !== binding.personId ||
+        event.conversationId !== ctx.conversationId || event.conversationId !== binding.conversationId ||
+        !Number.isFinite(age) || age < 0 || age > 60000)
+        return denied;
+    const match = /^\/ork (offer|gate|session) ([a-zA-Z0-9][a-zA-Z0-9._-]{0,79}) ([a-zA-Z0-9][a-zA-Z0-9._-]{0,79})(?: ([\s\S]{1,4096}))?$/.exec(event.content);
+    if (!match || event.content.includes('\0') || (match[1] === 'offer' ? match[4] !== undefined : !match[4]))
+        return denied;
+    const [, operation, thread, pedido, resposta] = match;
+    const call = (args, input) => new Promise((resolve, reject) => {
+        const child = execFile(bin, args, { cwd: root, timeout: 10000, maxBuffer: 65536 }, (error, stdout) => {
+            if (error) {
+                reject(Error('native.core.unavailable'));
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch {
+                reject(Error('native.core.invalid'));
+            }
+        });
+        child.stdin?.on('error', () => reject(Error('native.core.unavailable')));
+        if (input !== undefined)
+            child.stdin?.end(JSON.stringify(input));
+    });
+    const offer = { native: { ...binding, messageId: event.messageId }, recebidoEm: new Date(Number(event.timestamp)).toISOString(), prova: '' };
+    const b = offer.native;
+    offer.prova = createHmac('sha256', key).update(JSON.stringify(['ork.hitl-native-offer/v1', thread, pedido,
+        b.host, b.installationId, b.connectionId, b.sessionId, b.accountId, b.channelId,
+        b.conversationId, b.personId, b.messageId, offer.recebidoEm])).digest('hex');
+    const view = await call(['gate', 'context', thread, pedido, '--native-offer-stdin'], offer);
+    if (view.pedido?.id !== pedido || view.pedido?.thread !== thread || (operation !== 'offer' && view.pedido?.alvo?.tipo !== operation) ||
+        !view.canais?.some((c) => c.canal === 'openclaw' && c.transporte === 'native' && c.estado === 'disponivel') ||
+        !/^[a-f0-9]{64}$/.test(view.contexto) || !/^[a-f0-9]{64}$/.test(view.pedidoSha256))
+        return denied;
+    if (operation === 'offer') {
+        if (typeof view.apresentacao?.mensagem !== 'string')
+            return denied;
+        // I-35: o prazo chega ao dono no fuso dele; núcleo de outra versão pode não ter posto o
+        // prazo local na mensagem, então o campo local vai junto.
+        const prazo = typeof view.prazoLocal === 'string' && view.prazoLocal && !view.apresentacao.mensagem.includes(view.prazoLocal)
+            ? `\nPrazo (fuso do dono): ${view.prazoLocal}` : '';
+        return { handled: true, reply: { text: view.apresentacao.mensagem + prazo + '\nCanal nativo OpenClaw disponível nesta conversa.' } };
+    }
+    const n = { ...binding, messageId: event.messageId, context: view.contexto,
+        pedidoSha256: view.pedidoSha256, expiresAt: view.pedido.prazo };
+    const message = 'native:' + createHash('sha256').update(JSON.stringify([n.host, n.installationId, n.connectionId,
+        n.sessionId, n.channelId, n.accountId, n.conversationId, n.messageId])).digest('hex');
+    const r = { origem: 'native', canal: 'openclaw', conta: n.accountId, native: n, por: `native:openclaw:${n.personId}`,
+        mensagem: message, recebidoEm: new Date(Number(event.timestamp)).toISOString(), resposta, prova: '' };
+    r.prova = createHmac('sha256', key).update(JSON.stringify(['ork.hitl-native/v1', thread, pedido,
+        n.host, n.installationId, n.connectionId, n.sessionId, n.accountId, n.channelId, n.conversationId, n.personId,
+        n.messageId, n.context, n.pedidoSha256, n.expiresAt, r.origem, r.canal, r.conta, r.por, r.mensagem, r.recebidoEm, resposta])).digest('hex');
+    const receipt = await call([operation === 'gate' ? 'gate' : 'sessions', 'answer', thread, pedido,
+        operation === 'gate' ? '--resposta-stdin' : '--stdin', '--origem', 'native', '--canal', 'openclaw',
+        '--conta', r.conta, '--por', r.por, '--mensagem', message], r);
+    if (receipt.ok !== true || receipt.pedidoId !== pedido || typeof receipt.repetida !== 'boolean' ||
+        !(operation === 'gate' ? ['aprovado', 'recusado', 'aguardando'] : ['entregue']).includes(receipt.estado) ||
+        (operation === 'session' && !receipt.sessionId))
+        return denied;
+    return receipt.repetida ? { handled: true } : { handled: true, reply: { text: 'Resposta nativa confirmada pelo núcleo.' } };
+}