@orkastery/cli 0.5.3 → 0.6.0

package/adapters/claude-code/mods/ork-torre/hooks/register.tsx

@@ -0,0 +1,437 @@
+// A Torre de Controle do Orkastery (RM-059, fatia F1; ficha M3 do plano dos mods). Na sessao do dono, um painel
+// com a fabrica inteira: uma linha por thread aberta desta maquina, lida do nucleo pela ponte (`$.ork.retrato`
+// e a lista fechada do `$.ork.ler`), nunca de `.orkastery/` por conta propria. A Torre so le: nenhum caminho
+// daqui age pelo dono. A logica fica nos modulos puros ao lado; aqui so os ganchos e as chamadas ao `$`,
+// sempre escritas como `x.noun.metodo(...)`, como o validador exige.
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+import type { TorreDetalhe, TorreLeitura, TorreLinha, TorreMostrado, TorreQuadro, TorreRede } from '../types'
+import {
+  escolher, ESPERA_DO_LOTE_MS, IDADE_MAXIMA_ESCONDIDO_MS, IDADE_MAXIMA_MS, INTERVALO_ESCONDIDO_MS, INTERVALO_POR_THREAD_MS,
+  marcaDoArquivo, PERIODO_DO_TIQUE_MS, vencidas,
+} from './agenda'
+import type { Dono } from './detalhe'
+import {
+  desenharDetalhe, donosCarregados, jsonDoMcp, leituraFalha, leituraFeita, linhasDaObservacao, linhasDasClaims, linhasDoDetalhe,
+  linhasDoEstado, linhasDoGit, linhasDosEventos,
+} from './detalhe'
+import {
+  abertasDaLista, desenharPainel, linhaDaThread, linhasDoPainel, mostradosDoQuadro, mostradosVisiveis, ordenarLinhas,
+} from './painel'
+import { PERIODO_DA_REDE_MS, redeComErro, redeDoPanorama, textoDaFaixa } from './rede'
+
+const MOD = 'ork-torre'
+const PAINEL = 'torre'
+const TITULO = 'Torre'
+const QUADRO_VAZIO: TorreQuadro = { linhas: [], omitidas: 0, lidoEm: null, erro: null }
+const quadro = atom({ plugin: 'ork-torre', key: 'quadro' } as const, QUADRO_VAZIO)
+const aberta = atom({ plugin: 'ork-torre', key: 'aberta' } as const, null as string | null)
+const detalhes = atom({ plugin: 'ork-torre', key: 'detalhes' } as const, {} as Record<string, TorreDetalhe>)
+const donos = atom({ plugin: 'ork-torre', key: 'donos' } as const, {} as Record<string, string>)
+const rede = atom({ plugin: 'ork-torre', key: 'rede' } as const, null as TorreRede | null)
+const fechado = atom({ plugin: 'ork-torre', key: 'fechado' } as const, false)
+const DETALHE_VAZIO: TorreDetalhe = { eventos: null, claims: null, leituras: {} }
+/** O servidor do nucleo pode conectar depois do inicio da sessao: o papel e conferido de novo nestas esperas. */
+const ESPERAS_DO_PAPEL_MS = [3000, 10000, 30000]
+/** Depois delas, enquanto dormente, a cada 5 min: o servidor pode conectar tarde ou ser reconectado. */
+const ESPERA_LONGA_DO_PAPEL_MS = 300000
+/** Teto de cada leitura do nucleo: leitura que nao volta nao trava o laco de leitura (o retrato tem teto de 10 s). */
+const PRAZO_DA_LEITURA_MS = 20000
+
+// O que o modulo guarda entre ganchos e nao desenha. Uma recarga do modulo zera tudo, e o `session.start`
+// dispara de novo nela; o estado em `$.state` (o quadro, o detalhe, o painel fechado) fica.
+let ativa = false
+let desistiu = false
+let abriuSozinho = false
+let ciclo: { cancel: () => void } | undefined
+let lote: { cancel: () => void } | undefined
+let lendo: Promise<void> | undefined
+let pendente = false
+let tudoPedido = false
+let listaPedida = true
+let listaLidaEm: number | null = null
+const marcadas = new Set<string>()
+/** Threads que o dono mandou reler agora (o Atualizar do detalhe): passam pelo laco unico, sem o intervalo. */
+const forcadas = new Set<string>()
+const threadLidaEm: Record<string, number> = {}
+/** O que o desenho poe na janela de rolagem e ainda nao foi ao registro da ponte (D10). */
+const vistosNoDesenho = new Map<string, TorreMostrado>()
+/** O que ja foi ao registro nesta sessao, por chave e texto; sai quando o item some do quadro. */
+const jaMostrado = new Set<string>()
+/** A ultima tentativa de ler a rede (comeca na ativacao: nunca no inicio da sessao, D11). */
+let redeTentadaEm = 0
+/** O ultimo texto publicado na faixa; null antes da primeira publicacao. */
+let ultimaFaixa: string | undefined | null = null
+
+function mensagem(erro: unknown): string {
+  return (erro instanceof Error ? erro.message : String(erro)).replace(/\s+/g, ' ').trim().slice(0, 200)
+}
+
+/** A leitura com teto proprio: o relogio da sessao recusa a espera que passar dele. */
+function comPrazo<T>($: EngineInterface, leitura: Promise<T>, ms = PRAZO_DA_LEITURA_MS): Promise<T> {
+  return new Promise<T>((resolver, recusar) => {
+    const prazo = $.clock.after(ms, () => recusar(new Error(`a leitura passou de ${Math.round(ms / 1000)} s`)))
+    leitura.then(v => { prazo.cancel(); resolver(v) }, e => { prazo.cancel(); recusar(e) })
+  })
+}
+
+/**
+ * O papel pela ponte. `null` so quando o `$.ork` nao existe (a ponte nao carregou: a chamada nem acontece);
+ * uma falha da propria ponte conta como dormente e o papel e conferido de novo depois.
+ */
+async function papelDaSessao($: EngineInterface): Promise<string | null> {
+  try {
+    return String(await $.ork.papel())
+  } catch (erro) {
+    return erro instanceof TypeError ? null : 'dormente'
+  }
+}
+
+/** Liga a Torre na sessao do dono (D12): o `/torre`, o tique e a primeira leitura. */
+async function ativar($: EngineInterface): Promise<void> {
+  if (ativa) return
+  ativa = true
+  redeTentadaEm = await $.clock.now()
+  await $.command.register({ name: 'torre', description: 'Abre a Torre de Controle: a fábrica do Orkastery num painel', immediate: true })
+  ciclo?.cancel()
+  ciclo = $.clock.every(PERIODO_DO_TIQUE_MS, () => { void tique($) })
+  agendar($, 1)
+}
+
+/** Confere o papel: liga no dono, desiste na fase ou sem a ponte, e tenta de novo enquanto dormente. */
+async function conferirPapel($: EngineInterface, tentativa: number): Promise<void> {
+  if (ativa || desistiu) return
+  const papel = await papelDaSessao($)
+  if (papel === 'dono') return ativar($)
+  if (papel === 'fase' || papel === null) {
+    desistiu = true
+    if (papel === null) $.ui.toast('torre: a ponte ork-ponte não carregou; a Torre de Controle fica desligada nesta sessão')
+    return
+  }
+  const espera = ESPERAS_DO_PAPEL_MS[tentativa] ?? ESPERA_LONGA_DO_PAPEL_MS
+  $.clock.after(espera, () => { void conferirPapel($, tentativa + 1) })
+}
+
+/** Um lote de leitura daqui a pouco, um por vez: os eventos de arquivo se juntam nele (D7). */
+function agendar($: EngineInterface, ms = ESPERA_DO_LOTE_MS): void {
+  if (lote) return
+  lote = $.clock.after(Math.max(1, ms), () => {
+    lote = undefined
+    void atualizar($)
+  })
+}
+
+/** O painel da Torre esta posto e a vista do dono. */
+async function painelAVista($: EngineInterface): Promise<boolean> {
+  const paineis = await $.ui.panes().catch(() => [])
+  return paineis.some(p => p.id === PAINEL && p.isPlaced && p.isShown)
+}
+
+/** O tique do minuto: a lista das abertas, as linhas que ficaram velhas e, com o painel a vista, a rede. */
+async function tique($: EngineInterface): Promise<void> {
+  if (!ativa) return
+  const agora = await $.clock.now()
+  const aVista = await painelAVista($)
+  listaPedida = true
+  const idade = aVista ? IDADE_MAXIMA_MS : IDADE_MAXIMA_ESCONDIDO_MS
+  for (const t of vencidas((await read($, quadro)).linhas.map(l => l.thread), threadLidaEm, agora, idade)) marcadas.add(t)
+  await atualizar($)
+  if (aVista && agora - redeTentadaEm >= PERIODO_DA_REDE_MS) await lerRede($)
+  await registrarMostrados($)
+}
+
+/** A rede pelo panorama do nucleo (D11): pelo botao, ou no tique com o painel a vista, no maximo a cada 10 min. */
+async function lerRede($: EngineInterface): Promise<void> {
+  const agora = await $.clock.now()
+  redeTentadaEm = agora
+  const locais = (await read($, quadro)).linhas.map(l => l.thread)
+  try {
+    const nova = redeDoPanorama(jsonDoMcp(await comPrazo($, $.mcp.call('orkastery', 'ork_network_roadmap', {}))), locais, agora)
+    await update($, rede, () => nova)
+  } catch (erro) {
+    const motivo = mensagem(erro)
+    await update($, rede, anterior => redeComErro(anterior, motivo))
+  }
+  await publicarFaixa($)
+}
+
+/** A linha da faixa pela ponte (D9), so quando o texto muda; sem quadro lido, a linha sai da faixa. */
+async function publicarFaixa($: EngineInterface): Promise<void> {
+  const texto = textoDaFaixa(await read($, quadro), await read($, rede))
+  if (texto === ultimaFaixa) return
+  try {
+    if (texto === undefined) await $.ork.faixa({ mod: MOD })
+    else await $.ork.faixa({ mod: MOD, texto })
+    ultimaFaixa = texto
+  } catch {
+    // A ponte recusou ou falhou: a proxima leitura tenta de novo.
+  }
+}
+
+/** Uma leitura por vez; pedido que chega no meio volta a rodar logo depois, e quem pediu espera as duas. */
+async function atualizar($: EngineInterface, tudo = false): Promise<void> {
+  if (!ativa) return
+  if (tudo) { tudoPedido = true; listaPedida = true }
+  if (lendo) {
+    pendente = true
+    return lendo
+  }
+  lendo = (async () => {
+    try {
+      do {
+        pendente = false
+        await lerUmaVez($)
+      } while (pendente)
+    } finally {
+      lendo = undefined
+    }
+  })()
+  return lendo
+}
+
+/** O retrato de uma thread pela ponte; a linha so conta como lida quando o retrato veio (S2 da revisao). */
+async function lerThread($: EngineInterface, thread: string, agora: number): Promise<TorreLinha> {
+  try {
+    const r = await comPrazo($, $.ork.retrato({ thread }))
+    threadLidaEm[thread] = agora
+    return linhaDaThread(thread, r.retrato, { fonte: r.fonte, lidoEm: r.lidoEm })
+  } catch (erro) {
+    return linhaDaThread(thread, null, { fonte: null, lidoEm: null, erro: mensagem(erro) })
+  }
+}
+
+async function lerUmaVez($: EngineInterface): Promise<void> {
+  const tudo = tudoPedido
+  tudoPedido = false
+  const agora = await $.clock.now()
+  const atual = await read($, quadro)
+  let abertas = atual.linhas.map(l => l.thread)
+  let omitidas = atual.omitidas
+  let lidoEm = atual.lidoEm
+  let erro = atual.erro
+  if (listaPedida || listaLidaEm === null || agora - listaLidaEm >= PERIODO_DO_TIQUE_MS) {
+    listaPedida = false
+    try {
+      const lista = abertasDaLista(await comPrazo($, $.ork.ler({ consulta: 'thread.list' })))
+      abertas = lista.ids
+      omitidas = lista.omitidas
+      listaLidaEm = agora
+      lidoEm = agora
+      erro = null
+    } catch (e) {
+      erro = mensagem(e)
+    }
+  }
+  const conhecidas = new Set(atual.linhas.map(l => l.thread))
+  const agoraForcadas = abertas.filter(t => forcadas.has(t))
+  forcadas.clear()
+  const pedidas = tudo ? abertas : abertas.filter(t => (marcadas.has(t) || !conhecidas.has(t)) && !agoraForcadas.includes(t))
+  const intervalo = (await painelAVista($)) ? INTERVALO_POR_THREAD_MS : INTERVALO_ESCONDIDO_MS
+  const escolha = tudo ? { ler: pedidas, adiadas: [] as string[], proximaEm: null } : escolher(pedidas, threadLidaEm, agora, intervalo)
+  for (const t of [...marcadas]) if (pedidas.includes(t) || agoraForcadas.includes(t) || !abertas.includes(t)) marcadas.delete(t)
+  for (const t of escolha.adiadas) marcadas.add(t)
+  const novas = new Map<string, TorreLinha>()
+  for (const t of tudo ? escolha.ler : [...agoraForcadas, ...escolha.ler]) novas.set(t, await lerThread($, t, agora))
+  await update($, quadro, anterior => {
+    const antigas = new Map(anterior.linhas.map(l => [l.thread, l]))
+    const linhas = abertas.map(t => novas.get(t) ?? antigas.get(t) ??
+      linhaDaThread(t, null, { fonte: null, lidoEm: null, erro: 'ainda não lida' }))
+    return { linhas: ordenarLinhas(linhas), omitidas, lidoEm, erro }
+  })
+  if (escolha.proximaEm !== null) agendar($, escolha.proximaEm - agora)
+  await publicarFaixa($)
+  await registrarMostrados($)
+}
+
+/**
+ * So a thread do detalhe, pelo Atualizar dele (D16): ela entra no proximo passo do laco unico de leitura, sem o
+ * intervalo, e o resto do quadro fica como esta. Pelo laco, nenhuma leitura mais velha grava por cima dela.
+ */
+async function releerThread($: EngineInterface, thread: string): Promise<void> {
+  forcadas.add(thread)
+  await atualizar($)
+}
+
+/**
+ * O que o desenho pos na janela de rolagem do painel posto e a vista vai ao registro da ponte (M5 do dono,
+ * D10), uma vez por chave e texto enquanto o item existir no quadro: o Telegram nao repete o que o dono ja viu
+ * no terminal, e nada que nao estava na tela entra.
+ */
+async function registrarMostrados($: EngineInterface): Promise<void> {
+  const existentes = new Set(mostradosDoQuadro(await read($, quadro)).map(m => `${m.chave}|${m.texto}`))
+  for (const vista of [...jaMostrado]) if (!existentes.has(vista)) jaMostrado.delete(vista)
+  for (const vista of [...vistosNoDesenho.keys()]) if (!existentes.has(vista)) vistosNoDesenho.delete(vista)
+  if (vistosNoDesenho.size === 0) return
+  // Com o painel escondido, o que foi anotado e descartado: o proximo desenho a vista anota de novo (A-1).
+  if (!await painelAVista($)) { vistosNoDesenho.clear(); return }
+  for (const [vista, m] of [...vistosNoDesenho]) {
+    vistosNoDesenho.delete(vista)
+    if (jaMostrado.has(vista)) continue
+    try {
+      await $.ork.mostrado({ mod: MOD, canal: 'painel', chave: m.chave, thread: m.thread, texto: m.texto })
+      jaMostrado.add(vista)
+    } catch {
+      // A ponte recusou ou falhou: volta para a proxima vez.
+      vistosNoDesenho.set(vista, m)
+    }
+  }
+}
+
+/** O desenho anota o que pos na janela; quem registra e o laco de leitura, fora do desenho. */
+function anotarVistos(vistos: readonly TorreMostrado[]): void {
+  for (const m of vistos) vistosNoDesenho.set(`${m.chave}|${m.texto}`, m)
+}
+
+/**
+ * Grava o que o detalhe leu de uma thread, so se ela ainda e a aberta: leitura atrasada nao apaga a de outra.
+ * O mapa guarda so o detalhe aberto (o `abrir` o recomeca).
+ */
+async function gravarDetalhe($: EngineInterface, thread: string, mudar: (d: TorreDetalhe) => TorreDetalhe): Promise<void> {
+  if ((await read($, aberta)) !== thread) return
+  await update($, detalhes, todos => ({ ...todos, [thread]: mudar(todos[thread] ?? DETALHE_VAZIO) }))
+}
+
+/** Os comandos dos mods donos carregados agora, pelo plugin que registrou cada um (D4). */
+async function lerDonos($: EngineInterface): Promise<Record<string, string>> {
+  const carregados = donosCarregados(await $.command.list().catch(() => []))
+  await update($, donos, () => carregados)
+  return carregados
+}
+
+/** Ao abrir o detalhe: os donos das acoes, os ultimos eventos e as claims com estado da thread. */
+async function carregarDetalhe($: EngineInterface, thread: string): Promise<void> {
+  await lerDonos($)
+  const agora = await $.clock.now()
+  let eventos: TorreLeitura
+  try {
+    eventos = leituraFeita(linhasDosEventos(jsonDoMcp(await comPrazo($, $.mcp.call('orkastery', 'ork_phase_list', { threadId: thread }))), agora), agora)
+  } catch (erro) {
+    eventos = leituraFalha(mensagem(erro), agora)
+  }
+  let claims: TorreLeitura
+  try {
+    claims = leituraFeita(linhasDasClaims(jsonDoMcp(await comPrazo($, $.mcp.call('orkastery', 'ork_claims_list', { threadId: thread })))), agora)
+  } catch (erro) {
+    claims = leituraFalha(mensagem(erro), agora)
+  }
+  await gravarDetalhe($, thread, d => ({ ...d, eventos, claims }))
+}
+
+async function abrir($: EngineInterface, thread: string): Promise<void> {
+  await update($, aberta, () => thread)
+  await update($, detalhes, () => ({ [thread]: DETALHE_VAZIO }))
+  await carregarDetalhe($, thread)
+  await registrarMostrados($)
+}
+
+async function recarregar($: EngineInterface, thread: string): Promise<void> {
+  await releerThread($, thread)
+  await carregarDetalhe($, thread)
+  await registrarMostrados($)
+}
+
+/** As tres acoes de leitura do retrato (D4): o resultado vai para o detalhe, e nada mais roda. */
+async function lerAcao($: EngineInterface, thread: string, operacao: string): Promise<void> {
+  const agora = await $.clock.now()
+  let leitura: TorreLeitura
+  try {
+    if (operacao === 'thread.status') {
+      leitura = leituraFeita(linhasDoEstado(await comPrazo($, $.ork.ler({ consulta: 'thread.status', thread })), agora), agora)
+    } else if (operacao === 'thread.observe') {
+      leitura = leituraFeita(linhasDaObservacao(jsonDoMcp(await comPrazo($, $.mcp.call('orkastery', 'ork_observe', { threadId: thread })))), agora)
+    } else if (operacao === 'git.status') {
+      leitura = leituraFeita(linhasDoGit(jsonDoMcp(await comPrazo($, $.mcp.call('orkastery', 'ork_git_status', { threadId: thread })))), agora)
+    } else return
+  } catch (erro) {
+    leitura = leituraFalha(mensagem(erro), agora)
+  }
+  await gravarDetalhe($, thread, d => ({ ...d, leituras: { ...d.leituras, [operacao]: leitura } }))
+  await registrarMostrados($)
+}
+
+/**
+ * A acao com efeito vai ao mod dono dela (D4): o comando dele roda como se o dono o digitasse, com o id da
+ * thread, so se a lista de comandos agora o mostra registrado pelo plugin esperado. Senao, o detalhe redesenha
+ * com o comando do `ork` em texto, e nada roda.
+ */
+async function abrirMod($: EngineInterface, thread: string, dono: Dono): Promise<void> {
+  const carregados = await lerDonos($)
+  if (carregados[dono.comando] !== dono.plugin) return
+  await $.command.run({ command: dono.comando, args: thread }).catch(() => undefined)
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    if (e.isInteractive) await conferirPapel($, 0)
+    return next(e)
+  })
+
+  // `/torre` abre o painel em qualquer largura e rele tudo; o dono pediu, entao o painel volta a poder abrir
+  // sozinho. O comando so existe com a Torre ligada; a conferencia do papel aqui so cobre o caso raro de o
+  // comando ter sobrado de uma carga anterior.
+  on('command.run', { command: 'torre' }, async $ => {
+    if (!ativa && !desistiu) await conferirPapel($, ESPERAS_DO_PAPEL_MS.length)
+    if (!ativa) return { text: 'A Torre de Controle só abre na sessão do dono de um projeto do Orkastery.' }
+    await update($, fechado, () => false)
+    const aberto = await $.ui.open({ id: PAINEL, title: TITULO })
+    await atualizar($, true)
+    return { text: aberto.isPlaced ? 'Torre de Controle aberta.' : `Torre de Controle aberta, à espera de lugar: ${aberto.reason}` }
+  })
+
+  // O dono fechou o painel (a Torre nunca fecha o proprio): ele nao abre mais sozinho nesta sessao, nem depois
+  // de uma recarga do modulo. O fechamento segue sempre.
+  on('ui.close', { id: PAINEL }, async ($, e, next) => {
+    if (e.origin.kind !== 'unload') await update($, fechado, () => true)
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  // O ledger de uma thread ou a pasta das threads mudou: a releitura entra no proximo lote (D7). Os caminhos
+  // vigiados sao os que a ponte pede para o papel dono; a Torre nao pede outros.
+  on('classic.FileChanged', async ($, e, next) => {
+    if (ativa) {
+      const marca = marcaDoArquivo(e.file_path)
+      if (marca?.tipo === 'thread') marcadas.add(marca.thread)
+      if (marca?.tipo === 'lista') listaPedida = true
+      if (marca) agendar($)
+    }
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  // D8: sozinho, o painel so abre no fullscreen, uma vez, e nunca depois que o dono o fechou. A linha de dicas
+  // e desenhada em toda sessao do terminal e do desktop e traz o viewport; este gancho nao desenha nada e
+  // devolve a linha intacta.
+  on('ui.render', { component: 'PromptHint' }, async ($, e, next) => {
+    if (ativa && !abriuSozinho && e.viewport?.isFullscreen === true && !(await read($, fechado))) {
+      abriuSozinho = true
+      void $.ui.open({ id: PAINEL, title: TITULO }).catch(() => undefined)
+    }
+    return next(e)
+  })
+
+  // O painel: a lista das threads, ou o detalhe da thread aberta (T1.2). O desenho nunca escreve: so anota o
+  // que pos na janela de rolagem, para o registro do mostrado (D10). Os gestos mudam o estado da Torre e leem o
+  // nucleo.
+  on('ui.render', { component: 'Pane', requestId: PAINEL }, async ($, e) => {
+    const { Box, Text, Button } = $.ui.resolve(e)
+    const q = await read($, quadro)
+    const agora = await $.clock.now()
+    const id = await read($, aberta)
+    const linha = id === null ? undefined : q.linhas.find(l => l.thread === id)
+    if (linha) {
+      const detalhe = (await read($, detalhes))[linha.thread]
+      anotarVistos(mostradosVisiveis(linhasDoDetalhe(linha, detalhe, agora), 1, e.props.scroll))
+      return desenharDetalhe({ Box, Text, Button }, linha, detalhe, await read($, donos), {
+        agora,
+        voltar: () => update($, aberta, () => null),
+        atualizar: () => recarregar($, linha.thread),
+        ler: operacao => lerAcao($, linha.thread, operacao),
+        abrirMod: dono => abrirMod($, linha.thread, dono),
+      })
+    }
+    const daRede = await read($, rede)
+    anotarVistos(mostradosVisiveis(linhasDoPainel(q, { agora, rede: daRede }), 0, e.props.scroll))
+    return desenharPainel({ Box, Text, Button }, q, {
+      agora, largura: e.props.bodyColumns, abrir: thread => abrir($, thread), rede: daRede, lerRede: () => lerRede($),
+    })
+  })
+}

package/adapters/claude-code/mods/ork-torre/orkastery-mod.json

@@ -0,0 +1,5 @@
+{
+  "formato": "ork.mod/v1",
+  "papeis": ["dono"],
+  "claudeCodeMinimo": "2.1.287"
+}

package/adapters/claude-code/mods/ork-torre/types/index.d.ts

@@ -0,0 +1,108 @@
+// Contrato do estado da Torre de Controle (`ork-torre`, RM-059, fatia F1). O motor exige que cada chave de
+// `$.state` do mod esteja declarada aqui, em `PluginState`. A Torre nao acrescenta noun ao `$`: le o nucleo
+// pelo `$.ork` da `ork-ponte`, que o plugin.json lista em `dependencies`. Sem import nem referencia.
+
+/** As seis fases do ciclo, na ordem do trilho. */
+export type TorreFase = 'GOAL' | 'PLAN' | 'GO' | 'CHECK' | 'SHIP' | 'MASTER'
+
+/** O estado da linha (D6 da thread): o que pede acao vem primeiro. */
+export type TorreEstado = 'espera-voce' | 'parada' | 'andando' | 'quieta' | 'sem-leitura'
+
+/** Uma acao que o retrato do nucleo declara disponivel para a thread (`available: true`). */
+export type TorreAcao = { operacao: string }
+
+/** Um pedido HITL aberto da thread, como o retrato o mostra. */
+export type TorrePedido = { id: string; texto: string; prazo: string; recomendacao: string }
+
+/** Uma sessao da thread: o rotulo (`runtime · fase`), o estado nativo e se e ela quem conduz. */
+export type TorreSessao = { id: string; rotulo: string; estado: string; conduz: boolean; confirmada: boolean }
+
+/** Uma thread aberta desta maquina, como o retrato dela (`ork.maestro-snapshot/v1`) a mostra. */
+export type TorreLinha = {
+  thread: string
+  fase: string | null
+  modo: string | null
+  /** O texto de quem conduz e desde quando, como o nucleo o escreve. */
+  conducao: string | null
+  bloqueio: { motivo: string; frase: string } | null
+  pedidos: TorrePedido[]
+  sessoes: TorreSessao[]
+  /** O estado da entrega (`delivered`, `incomplete`) e do MASTER (`pending`, `recorded`), quando ha. */
+  entrega: string | null
+  master: string | null
+  acoes: TorreAcao[]
+  estado: TorreEstado
+  /** De onde veio o retrato (MCP, CLI ou cache da ponte), e quando a ponte o leu. */
+  fonte: 'mcp' | 'cli' | 'cache' | null
+  lidoEm: number | null
+  /** Secoes do retrato que nao vieram inteiras, ou o motivo de a leitura ter falhado. */
+  lacunas: string[]
+}
+
+/** O que o painel mostrou ao dono e o Telegram tambem avisaria: a chave junta o que e a mesma coisa (D10). */
+export type TorreMostrado = { chave: string; thread: string; texto: string }
+
+/** O quadro da fabrica: uma linha por thread aberta, na ordem do estado. */
+export type TorreQuadro = {
+  linhas: TorreLinha[]
+  /** Quantas threads abertas ficaram de fora pelo teto da Torre. */
+  omitidas: number
+  /** Quando a lista das abertas foi lida (ms desde a epoca); null antes da primeira leitura. */
+  lidoEm: number | null
+  /** Por que a lista das abertas nao foi lida, quando nao foi. */
+  erro: string | null
+}
+
+/** O resultado de uma leitura do detalhe: as linhas a mostrar, ou o motivo de nao ter lido. */
+export type TorreLeitura = { lidoEm: number; linhas: string[]; erro: string | null }
+
+/** O que o detalhe de uma thread leu: os ultimos eventos, as claims e cada acao de leitura pedida. */
+export type TorreDetalhe = {
+  eventos: TorreLeitura | null
+  claims: TorreLeitura | null
+  /** Por operacao de leitura do retrato (`thread.status`, `thread.observe`, `git.status`). */
+  leituras: Record<string, TorreLeitura>
+}
+
+/** Uma thread ativa de outra maquina, como o panorama da rede (`ork.network-roadmap/v1`) a mostra. */
+export type TorreLinhaDaRede = {
+  thread: string
+  maquina: string
+  fase: string
+  /** A #TAG do modo, como o retrato da maquina a escreve. */
+  modo: string
+  esperaVoce: boolean
+  pergunta: string | null
+  /** Minutos desde a batida da maquina, na hora em que a rede foi lida; null quando a batida e ilegivel. */
+  idadeMin: number | null
+  semBatida: boolean
+}
+
+/** A ultima leitura da rede: as threads das outras maquinas, quantas maquinas e lacunas, e o erro da ultima tentativa. */
+export type TorreRede = {
+  /** Quando a rede foi lida com sucesso pela ultima vez; null se nunca foi. */
+  lidoEm: number | null
+  linhas: TorreLinhaDaRede[]
+  maquinas: number
+  lacunas: number
+  erro: string | null
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'ork-torre': {
+      /** O quadro que o painel desenha. */
+      quadro: TorreQuadro
+      /** A ultima leitura da rede, ou null antes da primeira. */
+      rede: TorreRede | null
+      /** A thread com o detalhe aberto no painel, ou null para a lista. */
+      aberta: string | null
+      /** O que o detalhe leu, por thread. */
+      detalhes: Record<string, TorreDetalhe>
+      /** Os comandos dos mods donos das acoes carregados nesta sessao, com o plugin que registrou cada um. */
+      donos: Record<string, string>
+      /** O dono fechou o painel nesta sessao: ele nao abre mais sozinho, nem depois de uma recarga do modulo. */
+      fechado: boolean
+    }
+  }
+}

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

@@ -44,6 +44,8 @@ O dono conversa sobre o objetivo; voce opera o nucleo `ork` e apresenta o result
 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.
 
+- Esperas: nunca dispare verify, build ou suite com `&` dentro do comando, porque o processo se perde e a sessao espera um aviso que nunca vem; rode o `ork verify` em primeiro plano, com `timeout` (ele espera a vez na fila de recursos pesados), ou use a execucao em segundo plano do host, que avisa quando termina; nunca espere com `pgrep -f` cujo padrao aparece no proprio comando, porque o laco acha a si mesmo e nao termina: espere pelo arquivo de saida com prazo, ou pelo PID guardado.
+
 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)`

package/adapters/hermes/README.md

@@ -20,7 +20,8 @@ venv do Hermes e um destino explícito `telegram:chat_id[:topic_id]`:
 }
 ```
 
-Grave a configuração em `.orkastery/monitor/pulse-host.json`. `HERMES_HOME` e
+Grave a configuração em `.orkastery/monitor/pulse-host.json` (o `ork onboarding` já a grava
+pronta; veja a RM-063 abaixo). `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.
@@ -48,6 +49,19 @@ ork adapter install hermes --dry-run             # lista o que seria escrito
 | `bin/ork-roadmap-status.sh` | `ork_roadmap_status`: o status report do roadmap so desta maquina (`ork roadmap status`) |
 | `bin/ork-network-roadmap.sh` | `ork_network_roadmap`: o roadmap da rede (`ork network roadmap`), com as threads de todas as maquinas, fonte, hora e lacunas; a fonte do status do roadmap e o panorama da frase `orkastery maestro` sem projeto (RM-054) |
 | `bin/ork-network-status.sh` | `ork_network_status`: as maquinas da pessoa na Orkastery Network (`ork network status`), com a batida, as forjas, os runtimes, os hosts, a fonte e as lacunas; sem projeto (RM-054, fatia 3) |
+| `bin/ork-vigia-batida.py` | A batida do host (RM-063): roda `ork doctor --json` a cada 30 min e avisa o dono quando a batida da fabrica passou de 30 min, sem LLM |
+| `bin/ork-conhecimento-listar.sh`, `-mostrar.sh`, `-colecoes.sh` e `-verificar.sh` | `ork_conhecimento_listar`, `ork_conhecimento_mostrar`, `ork_conhecimento_colecoes` e `ork_conhecimento_verificar`: o conhecimento escrito do projeto (`ork conhecimento <consulta> --json`), as mesmas tools do MCP e do OpenClaw (RM-026 K7, fatia 3) |
+
+## Conhecimento escrito (RM-026 K7)
+
+Os quatro wrappers `bin/ork-conhecimento-*.sh` sao as tools MCP do conhecimento escrito com os mesmos nomes no
+manifesto: cada um chama `ork conhecimento <consulta> "$@" --json`, com `ORK_PROJETO_EXPLICITO=1` e
+`ORK_CANAL=hermes`, e devolve o JSON do nucleo e a saida dele como vem (saida 1 e a consulta que nao respondeu, com as
+lacunas dizendo por que). O `--json` vai no fim, depois do `<doc-id>` do `mostrar`. A skill manda citar o documento
+pela versao e pela fonte e mostrar cada lacuna como lacuna, nunca como resposta, com a mesma frase das descricoes do
+OpenClaw ([contrato](../../docs/referencia/contratos/conhecimento-rm026.md)).
+
+Verificacao: `python3 -m unittest discover -s adapters/hermes/test -p conhecimento_test.py -v`.
 
 ## Tickets `obj-*` aposentados
 
@@ -123,6 +137,41 @@ não ratifica nada. Cada página oferece no máximo doze opções e cabe em 3.90
 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`.
 
+## Batida do host e retomada pelo canal (RM-063)
+
+**H1, a batida do host.** A cada 30 min, `bin/ork-vigia-batida.py` roda `ork doctor --json`. Se a
+batida da fábrica passou de 30 min, manda ao dono o aviso pronto do núcleo; `ork` ausente ou com
+falha vira alerta; o resto não manda nada. Com `--target`, envia pela mesma API do
+`ork-pulse-enviar.py` (sai 1 se a entrega falha); sem ele, só imprime. Rode pelo cron ou por um
+timer do systemd (ou pelo agendador do Hermes, num job que roda o script sem LLM):
+
+```text
+*/30 * * * * PATH=<dir do node>:/usr/bin:/bin ORK_BIN=<caminho do ork> <hermes-agent>/venv/bin/python3 <hermes>/bin/ork-vigia-batida.py --projeto <projeto> --target telegram:<chat>
+```
+
+Nunca um cron LLM com `deliver=origin`. O cron não carrega o perfil do shell: o `ORK_BIN` e o
+`PATH` com o `node` vão na própria linha.
+
+**H2, retomada pelo canal.** `#OrkRetomar` ou `#OrkFabrica`, sozinhos na mensagem do chat Telegram
+autorizado, passam pelo mesmo ingresso assinado do pulse (`pre_gateway_dispatch`). `#OrkRetomar`
+responde na hora e roda a batida da condução nesta máquina; o que voltou a andar chega logo depois,
+pelo transporte do pulse. `#OrkFabrica` responde o `ork fabrica`. No meio de uma frase, a tag vai ao assistente.
+
+**H3, transporte gravado no onboarding.**
+`ork onboarding set maestro --conteudo '{"canal":{"host":"hermes","destino":"telegram:<chat>"}}' --por <dono>`
+(ou `telegram:<chat>:<topico>`) grava o canal e o `.orkastery/monitor/pulse-host.json` pronto, fora
+do git: a máquina nunca fica sem transporte. O Python vem de `HERMES_AGENT_DIR` (ou
+`$HERMES_HOME/hermes-agent`) e o script, de `$HERMES_HOME/bin/ork-pulse-enviar.py`; `executavel` e
+`script` (absolutos) trocam os dois. O JSON de "Transporte determinístico do pulse" mostra, por
+dentro, o que é gravado.
+
+**H4, o outro host.** Com o canal gravado para os dois hosts, o último vira o principal e o outro, o
+alternativo. Se a entrega falha, o transporte tenta o outro host; cada entrega vai ao
+`.orkastery/monitor/transporte.log`, e o `ork doctor` mostra o check "transporte do pulse": aviso
+quando caiu no alternativo, falha quando nenhum entregou.
+
+Verificação: `python3 -m unittest discover -s adapters/hermes/test -p conducao_canal_test.py -v`.
+
 ## 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.
@@ -131,6 +180,20 @@ O script deve receber eventos diretamente do gateway, cuja autenticação do Tel
 
 Verificação: `python3 -m unittest discover -s adapters/hermes/test -p hitl_answer_test.py -v`.
 
+## Arco #Noctum pelo Telegram (RM-058)
+
+O mesmo plugin `hitl-ingress/` recebe `/ork noctum <arco> autorizar <sha256>` e `/ork noctum <arco> revogar`, com as mesmas conferências do `/ork gate` (autorização do host, usuário, chat, bot, mensagem de até 60 s e a chave `ORK_HITL_INGRESS_KEY_HERMES`). O envelope é assinado no endereço `noctum` / `arco:<arco>`, que nenhum `/ork gate` alcança, e vai pela entrada a `ork noctum responder <arco>`. Só o recibo tipado `ork.noctum-ingresso/v1` do mesmo arco confirma ao dono, e o ato que já valia não ganha segunda confirmação. A proposta do envelope é `ork noctum propor --arquivo <envelope.json>`, e ela não autoriza nada. A gramática mora no núcleo (`GRAMATICA_DO_NOCTUM`), e o teste `noctum-gateways` do núcleo confere a cópia daqui. Desde a RM-057, a proposta chega ao dono como pergunta com código curto, e ele a responde como está na seção seguinte; o `/ork noctum <arco> autorizar <sha256>` segue aceito, mas não é mais o caminho ensinado.
+
+Verificação: `python3 -m unittest discover -s adapters/hermes/test -p hitl_noctum_test.py -v`.
+
+## A resposta curta à pergunta (RM-057)
+
+A pergunta ao dono (a do arco #Noctum e a mensagem curta de um gate) chega com código curto e alternativas e termina em "Responda a, b ou c". Pelo mesmo ingresso assinado do pulse (`ork pulse responder`), o dono responde com o código e a letra (`K7QX a`) de qualquer chat autorizado, com o número da pergunta e a letra (`1a`), ou em reply à mensagem da pergunta do arco só com a letra ou a palavra (`a`, `sim`, `autorizo`). O reply só vale para a mensagem em que a pergunta foi entregue: o transporte (`bin/ork-pulse-enviar.py`) devolve o id dela, e o núcleo o guarda com a pergunta. O plugin tira a referência só da mensagem do próprio bot (`ORK_HITL_TELEGRAM_BOT_ID`) cuja primeira linha é o título da pergunta do arco (`🔔 N. arco <arco> · <código>`), e só quando o texto do dono é uma resposta (a palavra, o código com a resposta ou o número com a letra); assina o envelope no endereço `resposta:<código>:<id>`, com o id da mensagem respondida, e manda `--em-resposta-a <código>:<id>` ao núcleo; a resposta em reply vale mesmo com a janela da palavra solta fechada. A confirmação do "b", a recusa e qualquer outra mensagem não dão referência, e o reply à mensagem curta de um gate não vale (o gate segue pelo número e pelo código). A palavra solta em reply a qualquer mensagem que não é a pergunta do arco (a confirmação de um gate, a mensagem de outra pessoa do grupo, a do assistente) nunca vira palavra solta: com a janela aberta, o plugin a assina no endereço `resposta:outra` e manda `--em-resposta-a outra`, e o núcleo a recusa dizendo por onde responder, sem gravar nada; com a janela fechada, ela segue ao assistente. O código e o número em reply a outra mensagem valem como sem reply, porque dizem a pergunta. A abertura do tópico do fórum, que o Telegram põe em toda mensagem do tópico, não conta como reply. Sem reply, a palavra solta só vale com uma pergunta esperando no chat em que ela saiu, e nunca com a mensagem de antes de ela sair; com duas, o núcleo pergunta qual. Conversa comum, mesmo em reply, segue ao assistente. Quem decide é o núcleo: a pergunta de agora, o prazo, a mensagem repetida (uma mensagem responde a uma pergunta só, em qualquer arco) e, no reply, o id da entrega e o chat em que ela saiu; o código digitado vale de qualquer chat autorizado.
+
+As recusas na borda do plugin saem caladas, de propósito: a mensagem de usuário ou de chat fora da lista, a de mais de 60 s (contados da mensagem original, também na edição) e a mensagem já recebida que volta com outro texto (o cache de reentrega a recusa) nem chegam ao núcleo, e o bot não responde a elas, para nunca conversar com quem não é o dono nem responder a uma mensagem atrasada. Só as recusas do núcleo voltam ao dono com o porquê.
+
+Verificação: `python3 -m unittest discover -s adapters/hermes/test -p hitl_resposta_curta_test.py -v`.
+
 ## Confirmação pelo plugin nativo HITL
 
 O plugin `hitl-ingress/` recebe `/ork gate <thread> <pedido> <resposta>` e