@orkastery/cli 0.5.1 → 0.5.6

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

@@ -6,14 +6,20 @@ license: MIT
 
 # Orkastery no Codex
 
-Consulte `ork experiencia show --json` no projeto da sessão. Quando `experience` for true,
+Ao receber literalmente `orkastery maestro`, a primeira ação é a ferramenta `ork_maestro` do
+servidor MCP `orkastery`, descoberta no namespace efetivamente exposto: ela consulta o projeto
+fixado. Com a ferramenta exposta, não rode `ork maestro`, `ork doctor`, `ork onboarding` nem
+`ork experiencia show` no shell antes nem no lugar dela: o CLI resolve o projeto pelo diretório da sessão, e é essa a
+classe de erro que a frase evita (prova de ativação do Codex, RM-032).
+
+Só depois da `ork_maestro` (ou, sem MCP, do `ork maestro --json`), consulte `ork experiencia show --json`
+no projeto da sessão. Quando `experience` for true,
 leia `../core/<skill>/SKILL.md`, usando o nome devolvido em `skill` pelo núcleo:
 `orchestration-experience-pt-br` ou `orchestration-experience`. Idioma, fuso e profundidade
 vêm da mesma consulta. Se false, não ative o pacote. O bloco próprio de AGENTS.md também
 aponta para esse catálogo; instalação não altera permissões nativas.
 
-Ao receber literalmente `orkastery maestro`, descubra `ork_maestro` no namespace
-efetivamente exposto e consulte o projeto fixado pelo MCP. A frase pede panorama,
+Depois de `ork_maestro`, a frase `orkastery maestro` continua pedindo só panorama,
 sem abrir trabalho. Sem projeto nomeado, ofereça também o panorama da rede
 (`ork_network_roadmap`, ou `ork network roadmap` no CLI), com fontes, frescor e lacunas.
 Siga a seleção de contexto e os limites do bootstrap comum.
@@ -26,6 +32,13 @@ com rótulos claros; UUID interno. Use `ork_request_decision` na condutora e pre
 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.
 
+HITL de condução é seleção (RM-057): de 3 a 5 alternativas, exatamente uma com o selo
+"Recomendação". Nunca peça ao dono um "confirmo" em texto livre nem que ele cole texto; o pedido
+que ele colou com autorização explícita vale como instrução dele, dentro dessa autorização.
+Dúvida dentro da autorização vira `ork decisao registrar` e a thread segue. Texto só quando a
+fábrica não consegue seguir sozinha e o dono precisa rodar um comando no terminal: mostre o
+comando exato.
+
 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,
@@ -42,6 +55,8 @@ e `ork_request_decision(threadId, pedidoId)`. Use o namespace efetivamente expos
 - Status do roadmap: use `ork_network_roadmap` (ou `ork network roadmap --projeto <nome>`) e mostre o
   texto como vem, com as threads de todas as maquinas, as fontes e as lacunas; `ork_roadmap_status` e
   so desta maquina. Nao escreva relatorio proprio de roadmap: lacuna nunca e roadmap vazio.
+- Maquinas da pessoa (RM-053): use `ork_network_status` (ou `ork network status`) e mostre o texto como
+  vem, com a batida de cada maquina, a fonte e as lacunas; lacuna nunca e "nenhuma maquina".
 - 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.

package/adapters/hermes/README.md

@@ -47,6 +47,7 @@ ork adapter install hermes --dry-run             # lista o que seria escrito
 | `bin/ork-maestro.sh` | `ork_maestro`: o panorama Maestro do projeto pedido (`ork maestro --json`) |
 | `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) |
 
 ## Tickets `obj-*` aposentados
 

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

@@ -0,0 +1,10 @@
+#!/bin/sh
+# RM-054 (fatia 3): as maquinas da pessoa na Orkastery Network (RM-053), montadas pelo nucleo
+# (`ork network status`): a casa, a batida de cada maquina, forjas, runtimes, hosts e projetos, a
+# fonte e as lacunas. Somente leitura; o Hermes transporta o texto como vem. Argumentos continuam dados.
+set -eu
+export ORK_CANAL="${ORK_CANAL:-hermes}"
+# RM-052 (D3): o cwd do gateway nao e projeto. Com ORK_PROJETO_EXPLICITO=1 o nucleo nao le o projeto
+# do diretorio do gateway; a rede vem da casa, do registro e dos retratos. ORK_PROJETO_EXPLICITO=0 desliga.
+export ORK_PROJETO_EXPLICITO="${ORK_PROJETO_EXPLICITO:-1}"
+exec "${ORK_BIN:-{{ork_bin}}}" network status "$@"

package/adapters/hermes/hermes.plugin.json

@@ -12,6 +12,7 @@
     "ork_maestro": "./bin/ork-maestro.sh",
     "ork_roadmap_status": "./bin/ork-roadmap-status.sh",
     "ork_network_roadmap": "./bin/ork-network-roadmap.sh",
+    "ork_network_status": "./bin/ork-network-status.sh",
     "ork-abrir-thread": "./bin/ork-abrir-thread.sh",
     "ork_brain": "./bin/ork-brain.sh",
     "ork_gate_answer": "./bin/ork-hitl-answer.py",

package/adapters/hermes/hitl-ingress/__init__.py

@@ -32,8 +32,8 @@ PULSE_CADENCIA = re.compile(r'^[ \t]*#OrkPulse(?:On(?:-(?:15|30|60)m)?|Off)[ \t]
 # ("1. B, 2. aprovo") e interceptada sempre; `livre` ("sim", "aprovo", "a") so enquanto a janela
 # de escuta do nucleo estiver aberta: fora dela, a palavra vai ao assistente, como sempre foi. A
 # janela e dica de rota, nao prova: a mensagem ainda passa pela assinatura e pela regra do nucleo.
-PULSE_LISTA = re.compile(r'^[ \t]*[0-9]{1,2}(?:[ \t]*[.):-])?[ \t]*(?:[a-d]|pode seguir|pode ir|pode|sim|s|ok|aprovo|aprovado|aprovada|aprovar|aprova|segue|siga|seguir|manda|confirmo|confirmado|de acordo|agora n[aã]o|n[aã]o|n|recuso|recusado|recusar|reprovo|reprovado|revisar|revis[aã]o|refazer|volta|voltar|esperar|espera|aguardar|aguarda|aguarde|depois|mais tarde|detalhes?|evid[eê]ncias?)(?:[ \t\r\n,;]*[0-9]{1,2}(?:[ \t]*[.):-])?[ \t]*(?:[a-d]|pode seguir|pode ir|pode|sim|s|ok|aprovo|aprovado|aprovada|aprovar|aprova|segue|siga|seguir|manda|confirmo|confirmado|de acordo|agora n[aã]o|n[aã]o|n|recuso|recusado|recusar|reprovo|reprovado|revisar|revis[aã]o|refazer|volta|voltar|esperar|espera|aguardar|aguarda|aguarde|depois|mais tarde|detalhes?|evid[eê]ncias?))*[ \t]*(?:[.!][ \t]*)?$', re.IGNORECASE)
-PULSE_LIVRE = re.compile(r'^[ \t]*(?:[1-4]|(?:[a-d]|pode seguir|pode ir|pode|sim|s|ok|aprovo|aprovado|aprovada|aprovar|aprova|segue|siga|seguir|manda|confirmo|confirmado|de acordo|agora n[aã]o|n[aã]o|n|recuso|recusado|recusar|reprovo|reprovado|revisar|revis[aã]o|refazer|volta|voltar|esperar|espera|aguardar|aguarda|aguarde|depois|mais tarde|detalhes?|evid[eê]ncias?))[ \t]*(?:[.!]+[ \t]*)?$', re.IGNORECASE)
+PULSE_LISTA = re.compile(r'^[ \t]*[0-9]{1,2}(?:[ \t]*[.):-])?[ \t]*(?:[a-e]|pode seguir|pode ir|pode|sim|s|ok|aprovo|aprovado|aprovada|aprovar|aprova|segue|siga|seguir|manda|confirmo|confirmado|de acordo|agora n[aã]o|n[aã]o|n|recuso|recusado|recusar|reprovo|reprovado|revisar|revis[aã]o|refazer|volta|voltar|esperar|espera|aguardar|aguarda|aguarde|depois|mais tarde|detalhes?|evid[eê]ncias?)(?:[ \t\r\n,;]*[0-9]{1,2}(?:[ \t]*[.):-])?[ \t]*(?:[a-e]|pode seguir|pode ir|pode|sim|s|ok|aprovo|aprovado|aprovada|aprovar|aprova|segue|siga|seguir|manda|confirmo|confirmado|de acordo|agora n[aã]o|n[aã]o|n|recuso|recusado|recusar|reprovo|reprovado|revisar|revis[aã]o|refazer|volta|voltar|esperar|espera|aguardar|aguarda|aguarde|depois|mais tarde|detalhes?|evid[eê]ncias?))*[ \t]*(?:[.!][ \t]*)?$', re.IGNORECASE)
+PULSE_LIVRE = re.compile(r'^[ \t]*(?:[1-5]|(?:[a-e]|pode seguir|pode ir|pode|sim|s|ok|aprovo|aprovado|aprovada|aprovar|aprova|segue|siga|seguir|manda|confirmo|confirmado|de acordo|agora n[aã]o|n[aã]o|n|recuso|recusado|recusar|reprovo|reprovado|revisar|revis[aã]o|refazer|volta|voltar|esperar|espera|aguardar|aguarda|aguarde|depois|mais tarde|detalhes?|evid[eê]ncias?))[ \t]*(?:[.!]+[ \t]*)?$', re.IGNORECASE)
 # RM-048 (item 8): a linha do teclado do digest ("ratificar <thread> <assinatura> <classe>") vai ao
 # nucleo pelo mesmo endereco assinado; o agente nao escreve mais `--por` em nome do dono.
 PULSE_RATIFICACAO = re.compile(r'^[ \t]*ratificar(?:-lote)?(?:[ \t]+[A-Za-z0-9._-]{1,80}){2,3}[ \t]*$', re.IGNORECASE)