@orkastery/cli 0.5.1 → 0.5.6

package/adapters/claude-code/mods/ork-sentinela/hooks/vigia.ts

@@ -0,0 +1,186 @@
+// A leitura da condução pela Sentinela (RM-059, fatia F6, T6.1). Módulo puro: o argv do status e da batida, a
+// leitura do contrato `ork.conducao-sentinela/v1`, a thread de um ledger que mudou, o diário, as chaves guardadas e
+// a linha da faixa. As chamadas ao `$` ficam no register.ts.
+import type { SentinelaEntrada, SentinelaPasso, SentinelaPresenca, SentinelaResumo } from '../types'
+
+export const MOD = 'ork-sentinela'
+export const CONTRATO = 'ork.conducao-sentinela/v1'
+/** A batida da presença e a rodada de reserva: a mesma cadência do núcleo (`BATIDA_DA_SENTINELA_MS`). */
+export const BATIDA_MS = 60000
+/** Um ledger que muda acorda a rodada depois deste intervalo, para juntar as linhas do mesmo evento. */
+export const ESPERA_DO_LEDGER_MS = 1500
+/** O status lê todas as threads abertas: até 20 s, com folga sobre o que se mede (1 a 4 s). */
+export const PRAZO_DO_STATUS_MS = 20000
+export const PRAZO_DA_BATIDA_MS = 10000
+export const TETO_DO_DIARIO = 50
+export const TETO_DE_CHAVES = 200
+export const ACOES: readonly string[] = ['despachar', 'retomar', 'avisar', 'nada']
+export const FASES: readonly string[] = ['GOAL', 'PLAN', 'GO', 'CHECK', 'SHIP', 'MASTER']
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+const SESSAO = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/
+const LEDGER = /\/\.orkastery\/threads\/([a-zA-Z0-9][a-zA-Z0-9._-]{0,79})\/ledger\.jsonl$/
+
+export function idDeThreadValido(t: unknown): t is string {
+  return typeof t === 'string' && ID_DE_THREAD.test(t)
+}
+
+export function sessaoValida(s: unknown): s is string {
+  return typeof s === 'string' && SESSAO.test(s)
+}
+
+function exigirSessao(sessao: unknown): string {
+  if (!sessaoValida(sessao)) throw new Error('ork-sentinela: id de sessao invalido')
+  return sessao
+}
+
+/** O status do núcleo: a presença desta máquina e o passo do condutor em cada thread aberta. */
+export function argvDoStatus(): string[] {
+  return ['ork', 'conducao', 'sentinela', 'status', '--json']
+}
+
+/** A batida da presença desta sessão. */
+export function argvDaBatida(sessao: string): string[] {
+  return ['ork', 'conducao', 'sentinela', 'bater', '--sessao', exigirSessao(sessao), '--json']
+}
+
+/** Tira a presença desta sessão (pausa e fim da sessão). */
+export function argvDoDesligar(sessao: string): string[] {
+  return ['ork', 'conducao', 'sentinela', 'desligar', '--sessao', exigirSessao(sessao), '--json']
+}
+
+type Saida = { exitCode: number; stdout: string; stderr: string }
+
+function ultimaLinha(texto: unknown): string {
+  return String(texto ?? '').trim().split('\n').filter(l => l.trim() !== '').slice(-1)[0]?.trim().slice(0, 200) ?? ''
+}
+
+function texto(v: unknown): string | null {
+  return typeof v === 'string' ? v : null
+}
+
+/** Um passo do contrato, ou `null` quando ele não tem a forma: passo torto nunca vira despacho. */
+export function lerPasso(bruto: unknown): SentinelaPasso | null {
+  const p = bruto as Record<string, unknown> | null
+  if (!p || typeof p !== 'object' || !idDeThreadValido(p.thread) || typeof p.acao !== 'string' || !ACOES.includes(p.acao)) return null
+  const fase = texto(p.fase)
+  if (p.acao === 'despachar' && (fase === null || !FASES.includes(fase))) return null
+  const b = p.bloqueio as { motivo?: unknown; em?: unknown } | null | undefined
+  return {
+    thread: p.thread, modo: texto(p.modo) ?? '', faseAtual: texto(p.faseAtual) ?? '', conduzida: p.conduzida === true,
+    acao: p.acao as SentinelaPasso['acao'], fase: fase && FASES.includes(fase) ? fase : null,
+    caso: texto(p.caso), proximoPasso: texto(p.proximoPasso), porque: texto(p.porque) ?? '', desdeEm: texto(p.desdeEm),
+    bloqueio: b && typeof b.motivo === 'string' && typeof b.em === 'string' ? { motivo: b.motivo, em: b.em } : null,
+    pedidoGuardado: p.pedidoGuardado === true,
+  }
+}
+
+/** A leitura do `status --json`: recusa o que não for o contrato; a presença diz de quem é, frente a esta sessão. */
+export function lerStatus(r: Saida, sessao: string | null): { presenca: SentinelaPresenca; passos: SentinelaPasso[] } {
+  if (r.exitCode !== 0) throw new Error(`o status do nucleo saiu ${r.exitCode}${ultimaLinha(r.stderr) ? `: ${ultimaLinha(r.stderr)}` : ''}`)
+  let s: { contrato?: unknown; presenca?: { ativa?: unknown; sessao?: unknown } | null; threads?: unknown }
+  try { s = JSON.parse(r.stdout) } catch { throw new Error('o status do nucleo nao e JSON') }
+  if (!s || s.contrato !== CONTRATO || !Array.isArray(s.threads)) throw new Error(`o status do nucleo nao e o contrato ${CONTRATO}`)
+  const p = s.presenca
+  const presenca: SentinelaPresenca = !p || p.ativa !== true ? 'nenhuma' : p.sessao === sessao ? 'minha' : 'outra'
+  const passos = s.threads.map(lerPasso).filter((x): x is SentinelaPasso => x !== null)
+  return { presenca, passos }
+}
+
+/** A batida: `minha` com saída 0 e `ok`; `outra` com saída 3 (outra sessão viva nesta máquina); o resto é erro. */
+export function lerBatida(r: Saida): SentinelaPresenca {
+  let ok: unknown
+  try { ok = (JSON.parse(r.stdout) as { ok?: unknown }).ok } catch { ok = undefined }
+  if (r.exitCode === 0 && ok === true) return 'minha'
+  if (r.exitCode === 3 && ok === false) return 'outra'
+  throw new Error(`a batida da presenca saiu ${r.exitCode}${ultimaLinha(r.stderr) ? `: ${ultimaLinha(r.stderr)}` : ''}`)
+}
+
+/** A thread de um ledger que mudou (`.../.orkastery/threads/<id>/ledger.jsonl`), ou `null`. */
+export function threadDoLedger(caminho: unknown): string | null {
+  const m = typeof caminho === 'string' ? LEDGER.exec(caminho) : null
+  return m ? (m[1] as string) : null
+}
+
+/** Acrescenta no fim e corta os mais velhos acima do teto. */
+export function acrescentar<T>(lista: readonly T[] | undefined, item: T, teto: number): T[] {
+  return [...(lista ?? []), item].slice(-teto)
+}
+
+/** Guarda uma chave sem repetir, com teto: as mais velhas saem primeiro. */
+export function guardarChave(chaves: readonly string[] | undefined, chave: string, teto = TETO_DE_CHAVES): string[] {
+  const resto = (chaves ?? []).filter(c => c !== chave)
+  return [...resto, chave].slice(-teto)
+}
+
+export function entrada(em: number, tipo: SentinelaEntrada['tipo'], thread: string | null, texto: string): SentinelaEntrada {
+  return { em, tipo, thread, texto: texto.replace(/\s+/g, ' ').trim().slice(0, 300) }
+}
+
+function minutosDesde(iso: string | null, agora: number): number | null {
+  const t = iso ? Date.parse(iso) : NaN
+  return Number.isFinite(t) ? Math.max(0, Math.floor((agora - t) / 60000)) : null
+}
+
+function contar(n: number, um: string, varios: string): string {
+  return `${n} ${n === 1 ? um : varios}`
+}
+
+/**
+ * Há quanto tempo, em degraus (mais de 15, 30 ou 45 min, depois horas inteiras): a linha da faixa não muda a cada
+ * minuto, e o registro do mostrado não ganha uma linha nova por minuto. Antes de 15 min, nada.
+ */
+export function haQuantoTempo(minutos: number): string {
+  if (minutos < 15) return ''
+  if (minutos < 60) return `há mais de ${Math.floor(minutos / 15) * 15} min`
+  return `há mais de ${Math.floor(minutos / 60)} h`
+}
+
+/**
+ * A linha da faixa: quantas threads andam, quantas estão paradas e há quanto tempo a mais antiga, quantas estão na vez
+ * da Sentinela e quantos avisos do pulse esperam o dono. Pausada, ou com outra sessão conduzindo, diz isso. Sem nada a
+ * dizer, a linha sai.
+ */
+export function textoDaFaixa(r: SentinelaResumo, pausada: boolean, agora: number, avisos = 0): string | undefined {
+  if (pausada) return 'pausada; o condutor externo conduz'
+  if (r.presenca === 'outra') return 'outra sessão conduz nesta máquina; esta só olha'
+  if (r.lidoEm === null) return r.erro ? `sem leitura do núcleo (${r.erro})` : undefined
+  const andando = r.passos.filter(p => p.conduzida).length
+  const paradas = r.passos.filter(p => !p.conduzida && p.acao === 'avisar')
+  const naVez = r.passos.filter(p => !p.conduzida && (p.acao === 'despachar' || p.acao === 'retomar')).length
+  if (andando === 0 && paradas.length === 0 && naVez === 0 && avisos === 0) return r.erro ? `sem leitura do núcleo (${r.erro})` : undefined
+  const partes = [contar(andando, 'thread andando', 'threads andando')]
+  if (paradas.length > 0) {
+    const ha = haQuantoTempo(Math.max(...paradas.map(p => minutosDesde(p.desdeEm, agora) ?? 0)))
+    partes.push(`${contar(paradas.length, 'parada', 'paradas')}${ha ? ` ${ha}` : ''}`)
+  }
+  if (naVez > 0) partes.push(`${naVez} na vez da Sentinela`)
+  if (avisos > 0) partes.push(contar(avisos, 'aviso para você', 'avisos para você'))
+  return partes.join(', ')
+}
+
+const ROTULO: Record<string, string> = { despachar: 'despachar', retomar: 'retomar', avisar: 'parada', nada: 'nada' }
+
+/** O `/sentinela`: o estado, o passo de cada thread e o diário mais recente. */
+export function textoDoDiario(r: SentinelaResumo, diario: readonly SentinelaEntrada[], pausada: boolean, agora: number): string {
+  const linhas: string[] = []
+  linhas.push(pausada ? 'Sentinela pausada: o condutor externo conduz. Para voltar: /sentinela retomar.'
+    : r.presenca === 'outra' ? 'Outra sessão conduz pela Sentinela nesta máquina; esta só olha.'
+    : r.presenca === 'minha' ? 'Sentinela conduzindo nesta máquina: o condutor externo cede o despacho e o retry.'
+    : 'Sentinela ligada, sem a presença confirmada pelo núcleo ainda.')
+  if (r.erro) linhas.push(`Última leitura do núcleo falhou: ${r.erro}`)
+  if (r.passos.length > 0) {
+    linhas.push('', 'Threads abertas:')
+    for (const p of r.passos) {
+      const acao = p.conduzida ? 'andando' : p.acao === 'despachar' ? `despachar ${p.fase}` : ROTULO[p.acao] ?? p.acao
+      const desde = !p.conduzida && p.acao === 'avisar' ? minutosDesde(p.desdeEm, agora) : null
+      linhas.push(`  ${p.thread}: ${acao}${desde ? ` há ${desde} min` : ''}${p.proximoPasso && p.acao === 'avisar' ? `; ${p.proximoPasso}` : ''}`)
+    }
+  }
+  const recentes = diario.slice(-10)
+  linhas.push('', recentes.length ? 'Diário (mais recente por último):' : 'Diário vazio: nada despachado nesta sessão.')
+  for (const e of recentes) {
+    const ha = Math.max(0, Math.floor((agora - e.em) / 60000))
+    linhas.push(`  ${ha === 0 ? 'agora' : `há ${ha} min`} ${e.tipo}${e.thread ? ` ${e.thread}` : ''}: ${e.texto}`)
+  }
+  return linhas.join('\n')
+}

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

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

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

@@ -0,0 +1,65 @@
+// Contrato do estado da Sentinela do Condutor (`ork-sentinela`, RM-059, fatia F6). O motor exige que cada chave de
+// `$.state` do mod esteja declarada aqui, em `PluginState`. A Sentinela não acrescenta noun ao `$`: lê o núcleo pelo
+// `$.ork` da `ork-ponte` (que o plugin.json lista em `dependencies`) e pelo `ork`, e despacha só pelo `ork phase run`.
+// Sem import nem referência.
+
+/** O que o núcleo diz que o condutor faz numa thread (contrato `ork.conducao-sentinela/v1`). */
+export type SentinelaAcao = 'despachar' | 'retomar' | 'avisar' | 'nada'
+
+/** O passo do condutor numa thread aberta, como o `ork conducao sentinela status --json` o devolve. */
+export type SentinelaPasso = {
+  thread: string
+  modo: string
+  faseAtual: string
+  conduzida: boolean
+  acao: SentinelaAcao
+  /** A fase do despacho, só com `acao: despachar`. */
+  fase: string | null
+  caso: string | null
+  proximoPasso: string | null
+  porque: string
+  /** O fim do turno (ou o bloqueio): a chave do despacho. */
+  desdeEm: string | null
+  bloqueio: { motivo: string; em: string } | null
+  pedidoGuardado: boolean
+}
+
+/** De quem é a presença da Sentinela nesta máquina, pela última batida. */
+export type SentinelaPresenca = 'minha' | 'outra' | 'nenhuma' | 'desconhecida'
+
+/** A última leitura do status do núcleo, para a faixa e o `/sentinela`. */
+export type SentinelaResumo = {
+  /** Quando a leitura terminou, em ms desde a época; null antes da primeira. */
+  lidoEm: number | null
+  presenca: SentinelaPresenca
+  passos: SentinelaPasso[]
+  /** Por que a última leitura falhou, quando falhou. */
+  erro: string | null
+}
+
+/** Uma linha do diário do `/sentinela`. */
+export type SentinelaEntrada = {
+  em: number
+  tipo: 'despacho' | 'cedeu' | 'retomada' | 'aviso' | 'erro' | 'pausa'
+  thread: string | null
+  texto: string
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'ork-sentinela': {
+      /** O diário do que a Sentinela fez, do mais velho ao mais novo, com teto. */
+      diario: SentinelaEntrada[]
+      /** O dono pausou a Sentinela pelo `/sentinela pausar`: nada é despachado e a presença sai. */
+      pausada: boolean
+      /** As chaves `thread|fase|fim do turno` já despachadas: o mesmo turno nunca sai duas vezes. */
+      despachados: string[]
+      /** As chaves `thread|bloqueio` já levadas ao `ork retry plan`. */
+      retomados: string[]
+      /** As chaves dos avisos já mostrados, com o texto: o mesmo aviso não se repete. */
+      avisados: string[]
+      /** A última leitura do status do núcleo. */
+      resumo: SentinelaResumo
+    }
+  }
+}

package/adapters/claude-code/mods/ork-torre/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "ork-torre",
+  "version": "0.1.0",
+  "description": "Torre de Controle do Orkastery no Claude Code: a fábrica num painel, cada thread aberta numa linha com a fase, quem conduz, o bloqueio e a ação que o estado dela pede. Só lê; ação com efeito vai ao mod dono dela ou aparece como o comando do ork.",
+  "author": {
+    "name": "Orkastery contributors",
+    "url": "https://github.com/orkastery"
+  },
+  "homepage": "https://orkastery.com/",
+  "repository": "https://github.com/orkastery/orkastery",
+  "license": "MIT",
+  "types": "./types/index.d.ts",
+  "dependencies": ["ork-ponte"]
+}

package/adapters/claude-code/mods/ork-torre/hooks/agenda.ts

@@ -0,0 +1,60 @@
+// Quando a Torre rele o nucleo (RM-059, Torre de Controle; D7 da thread). O ledger de uma thread ativa muda
+// a cada batida do sensor, e cada retrato custa um passeio pelo servidor MCP do dono: a Torre junta os
+// eventos de arquivo num lote so, rele cada thread no maximo a cada 10 s e confere a lista das abertas a
+// cada minuto. Modulo puro: so dados entram e saem; os relogios ficam no register.tsx.
+
+/** Espera entre o primeiro evento de arquivo e a leitura do lote. */
+export const ESPERA_DO_LOTE_MS = 2000
+/** Intervalo minimo entre duas leituras da mesma thread. */
+export const INTERVALO_POR_THREAD_MS = 10000
+/** Periodo do tique: confere a lista das abertas e o que ficou velho. */
+export const PERIODO_DO_TIQUE_MS = 60000
+/** Linha lida ha mais que isto volta a ser lida no tique, mesmo sem evento de arquivo. */
+export const IDADE_MAXIMA_MS = 300000
+/**
+ * Com o painel escondido so a faixa le o quadro: o intervalo por thread e a idade maxima se espacam, porque
+ * cada retrato roda a observacao nativa no servidor do dono (D16).
+ */
+export const INTERVALO_ESCONDIDO_MS = 60000
+export const IDADE_MAXIMA_ESCONDIDO_MS = 900000
+
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+
+export type MarcaDoArquivo = { tipo: 'thread'; thread: string } | { tipo: 'lista' }
+
+/**
+ * O que um evento de arquivo marca: o ledger de uma thread marca a thread; a pasta das threads marca a
+ * lista das abertas (thread nova ou fechada). Outro caminho nao marca nada.
+ */
+export function marcaDoArquivo(caminho: unknown): MarcaDoArquivo | null {
+  if (typeof caminho !== 'string') return null
+  const c = caminho.replace(/\\/g, '/').replace(/\/+$/, '')
+  const m = /(?:^|\/)\.orkastery\/threads\/([^/]+)\/ledger\.jsonl$/.exec(c)
+  if (m) return ID_DE_THREAD.test(m[1] as string) ? { tipo: 'thread', thread: m[1] as string } : null
+  return /(?:^|\/)\.orkastery\/threads$/.test(c) ? { tipo: 'lista' } : null
+}
+
+/**
+ * Das threads marcadas, as que podem ser lidas agora (fora do intervalo minimo) e as que ficam para depois,
+ * com o instante mais cedo em que a primeira adiada pode ser lida.
+ */
+export function escolher(marcadas: Iterable<string>, lidaEm: Readonly<Record<string, number>>, agora: number,
+  intervalo = INTERVALO_POR_THREAD_MS): { ler: string[]; adiadas: string[]; proximaEm: number | null } {
+  const ler: string[] = []
+  const adiadas: string[] = []
+  let proximaEm: number | null = null
+  for (const t of [...new Set(marcadas)].sort()) {
+    const ultima = lidaEm[t]
+    if (typeof ultima !== 'number' || agora - ultima >= intervalo) { ler.push(t); continue }
+    adiadas.push(t)
+    const quando = ultima + intervalo
+    if (proximaEm === null || quando < proximaEm) proximaEm = quando
+  }
+  return { ler, adiadas, proximaEm }
+}
+
+/** No tique: as threads abertas que nunca foram lidas ou foram lidas ha mais que a idade maxima. */
+export function vencidas(abertas: readonly string[], lidaEm: Readonly<Record<string, number>>, agora: number,
+  idade = IDADE_MAXIMA_MS): string[] {
+  return abertas.filter(t => typeof lidaEm[t] !== 'number' || agora - (lidaEm[t] as number) > idade)
+}

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

@@ -0,0 +1,236 @@
+// O detalhe de uma thread na Torre de Controle (RM-059, fatia F1, T1.2; D4 da thread). Apertar a linha abre o
+// detalhe: sessoes, bloqueio, pedidos, entrega e MASTER, os ultimos eventos e as claims com estado. Cada acao
+// que o retrato declara disponivel vira um botao de leitura, que mostra o resultado aqui, ou, se tem efeito,
+// o atalho para o mod dono dela (que aplica as proprias regras) ou o comando do `ork` em texto, para o dono
+// rodar. Nenhuma acao com efeito roda pela Torre. Modulo puro: o `$` fica no register.tsx.
+import type { TorreDetalhe, TorreLeitura, TorreLinha } from '../types'
+import type { ItemDoPainel } from './painel'
+import { acoesRelevantes, cabecalhoDaLinha, emPortugues, idade, LEITURAS, ROTULO_DA_ACAO } from './painel'
+
+export type Dono = { plugin: string; comando: string; nome: string }
+export type ClasseDaAcao =
+  | { tipo: 'leitura' }
+  | { tipo: 'efeito'; dono: Dono | null; comando: ((thread: string) => string) | null; nota: string | null }
+
+/**
+ * D4: a classe de cada operacao do retrato (o enum `operation` do nucleo), o mod dono da acao com efeito
+ * (o nome do comando sai das fichas do plano dos mods) e o comando do `ork` que o dono roda sem ele.
+ */
+export const CLASSE_DA_ACAO: Readonly<Record<string, ClasseDaAcao>> = {
+  'thread.status': { tipo: 'leitura' },
+  'thread.observe': { tipo: 'leitura' },
+  'git.status': { tipo: 'leitura' },
+  'hitl.decide': { tipo: 'efeito', dono: { plugin: 'ork-mesa', comando: 'mesa', nome: 'a Mesa do Dono' },
+    comando: () => 'ork sessions hitl', nota: 'a resposta vai pelo Telegram ou pelo diálogo nativo' },
+  'ship': { tipo: 'efeito', dono: { plugin: 'ork-pista', comando: 'pista', nome: 'a Pista de Entrega' },
+    comando: t => `ork ship ${t} --para main`, nota: 'troque main pela branch base do projeto, se for outra' },
+  'phase': { tipo: 'efeito', dono: { plugin: 'ork-sentinela', comando: 'sentinela', nome: 'a Sentinela do Condutor' },
+    comando: t => `ork conducao status ${t}`, nota: 'a fase seguinte sai pelo condutor' },
+  'retry': { tipo: 'efeito', dono: { plugin: 'ork-sentinela', comando: 'sentinela', nome: 'a Sentinela do Condutor' },
+    comando: t => `ork retry plan ${t}`, nota: null },
+  'master': { tipo: 'efeito', dono: { plugin: 'ork-ritual', comando: 'nota', nome: 'o Ritual do MASTER' },
+    comando: t => `ork master pedir ${t}`, nota: null },
+  'verify': { tipo: 'efeito', dono: null, comando: t => `ork verify ${t}`, nota: null },
+  'git.commit': { tipo: 'efeito', dono: null, comando: null, nota: 'o commit é da sessão de GO, pelo ork_git_commit' },
+  'creation': { tipo: 'efeito', dono: null, comando: null, nota: 'não é ação de uma thread' },
+}
+
+/** Os comandos dos mods donos, um por mod: o que a Torre procura na lista de comandos da sessao. */
+export const COMANDOS_DOS_DONOS: readonly Dono[] = Object.values(CLASSE_DA_ACAO)
+  .flatMap(c => (c.tipo === 'efeito' && c.dono ? [c.dono] : []))
+  .filter((d, i, todos) => todos.findIndex(x => x.comando === d.comando) === i)
+
+/** Dos comandos da sessao (`$.command.list()`), os dos mods donos, com o plugin que registrou cada um. */
+export function donosCarregados(comandos: ReadonlyArray<{ name?: unknown; plugin?: unknown }>): Record<string, string> {
+  const saida: Record<string, string> = {}
+  for (const d of COMANDOS_DOS_DONOS) {
+    const achado = comandos.find(c => c.name === d.comando && typeof c.plugin === 'string')
+    if (achado) saida[d.comando] = achado.plugin as string
+  }
+  return saida
+}
+
+export type AcaoNoDetalhe =
+  | { operacao: string; rotulo: string; tipo: 'leitura' }
+  | { operacao: string; rotulo: string; tipo: 'mod'; dono: Dono }
+  | { operacao: string; rotulo: string; tipo: 'texto'; texto: string }
+
+/**
+ * Como cada acao que a Torre oferece aparece no detalhe (D4 e D15): leitura vira botao; efeito pedido pelo
+ * estado abre o mod dono so quando o comando dele esta carregado pelo plugin esperado; senao, o comando do
+ * `ork` (ou a nota) aparece em texto.
+ */
+export function acoesDoDetalhe(linha: TorreLinha, donos: Readonly<Record<string, string>>): AcaoNoDetalhe[] {
+  const saida: AcaoNoDetalhe[] = []
+  for (const { operacao } of acoesRelevantes(linha)) {
+    const classe = Object.prototype.hasOwnProperty.call(CLASSE_DA_ACAO, operacao) ? CLASSE_DA_ACAO[operacao] : undefined
+    if (!classe) continue
+    const rotulo = ROTULO_DA_ACAO[operacao] ?? operacao
+    if (classe.tipo === 'leitura') { saida.push({ operacao, rotulo, tipo: 'leitura' }); continue }
+    if (classe.dono && donos[classe.dono.comando] === classe.dono.plugin) { saida.push({ operacao, rotulo, tipo: 'mod', dono: classe.dono }); continue }
+    const comando = classe.comando ? classe.comando(linha.thread) : null
+    const texto = [comando ? `rode ${comando}` : null, classe.nota].filter((p): p is string => !!p).join('; ')
+    saida.push({ operacao, rotulo, tipo: 'texto', texto: `${rotulo}: ${texto}` })
+  }
+  return saida
+}
+
+/** O JSON do primeiro bloco de texto de uma resposta MCP; resposta com erro vira erro. */
+export function jsonDoMcp(r: { content?: ReadonlyArray<{ type?: string; text?: string }>; isError?: boolean } | null | undefined): unknown {
+  if (!r || r.isError) throw new Error('o núcleo respondeu com erro')
+  const texto = (r.content ?? []).find(c => c.type === 'text' && typeof c.text === 'string')?.text
+  if (texto === undefined) throw new Error('o núcleo não devolveu texto')
+  return JSON.parse(texto)
+}
+
+const curto = (v: unknown, n = 8) => (typeof v === 'string' ? v.slice(0, n) : '?')
+const cortar = (v: unknown, n: number) => {
+  const t = typeof v === 'string' ? v.replace(/\s+/g, ' ').trim() : ''
+  return t.length <= n ? t : `${t.slice(0, n - 1)}…`
+}
+function haQuanto(ts: unknown, agora: number): string {
+  const ms = typeof ts === 'string' ? Date.parse(ts) : NaN
+  return Number.isFinite(ms) ? `há ${idade(agora - ms)}` : 'sem hora'
+}
+
+/** Os ultimos eventos (`ork_phase_list`), do mais novo ao mais velho. */
+export function linhasDosEventos(resultado: unknown, agora: number, teto = 6): string[] {
+  const eventos = (resultado as { phases?: { eventos?: unknown } } | null)?.phases?.eventos
+  if (!Array.isArray(eventos)) throw new Error('a lista de eventos veio sem eventos')
+  if (eventos.length === 0) return ['nenhum evento de fase registrado']
+  return eventos.slice(-teto).reverse().map(e => {
+    const x = (e ?? {}) as Record<string, unknown>
+    return [String(x.tipo ?? '?'), typeof x.fase === 'string' ? x.fase : null, typeof x.classificacao === 'string' ? x.classificacao : null,
+      typeof x.motivo === 'string' ? x.motivo : null, haQuanto(x.ts, agora)].filter(p => p !== null).join(' · ')
+  })
+}
+
+/** As claims com estado (`ork_claims_list`): a conta por estado e as que ainda nao foram verificadas. */
+export function linhasDasClaims(resultado: unknown, teto = 5): string[] {
+  if (!Array.isArray(resultado)) throw new Error('a lista de claims veio em outro formato')
+  if (resultado.length === 0) return ['nenhuma claim registrada']
+  const conta = new Map<string, number>()
+  for (const c of resultado) conta.set(String(c?.estado ?? '?'), (conta.get(String(c?.estado ?? '?')) ?? 0) + 1)
+  const resumo = [...conta.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).map(([e, n]) => `${n} ${e}`).join(', ')
+  const abertas = resultado.filter(c => c?.estado !== 'verificado' && c?.estado !== 'retirada').slice(-teto)
+  return [`${resultado.length} claims: ${resumo}`, ...abertas.map(c => `${String(c?.id ?? '?')} ${String(c?.estado ?? '?')}: ${cortar(c?.alegacao, 90)}`)]
+}
+
+/** O estado da thread (`ork thread status --json`, pela ponte). */
+export function linhasDoEstado(resultado: unknown, agora: number): string[] {
+  const t = (resultado ?? {}) as Record<string, unknown>
+  if (typeof t.id !== 'string') throw new Error('o estado da thread veio sem id')
+  const sessoes = Array.isArray(t.sessoes) ? t.sessoes.length : 0
+  const claims = Array.isArray(t.claims) ? t.claims.length : 0
+  const saida = [`status ${String(t.status ?? '?')} · fase ${String(t.faseAtual ?? '?')} · ${sessoes} sessões · ${claims} claims · atualizada ${haQuanto(t.atualizadaEm, agora)}`]
+  const b = t.baseline as { commit?: unknown; comandos?: Array<{ nome?: unknown; ok?: unknown }> } | null | undefined
+  if (b && Array.isArray(b.comandos)) {
+    saida.push(`baseline em ${curto(b.commit)}: ${b.comandos.map(c => `${String(c.nome ?? '?')} ${c.ok === true ? 'passava' : 'falhava'}`).join(', ')}`)
+  } else saida.push('sem baseline gravada')
+  return saida
+}
+
+/** A observacao da thread (`ork_observe`): os pedidos pendentes e cada sessao nativa. */
+export function linhasDaObservacao(resultado: unknown): string[] {
+  const o = (resultado ?? {}) as { pendencias?: unknown; nativas?: unknown }
+  if (!Array.isArray(o.nativas)) throw new Error('a observação veio sem as sessões nativas')
+  const pendencias = Array.isArray(o.pendencias) ? o.pendencias.length : 0
+  const saida = [pendencias === 0 ? 'nenhum pedido pendente' : pendencias === 1 ? '1 pedido pendente' : `${pendencias} pedidos pendentes`]
+  for (const n of o.nativas as Array<Record<string, unknown>>) {
+    const sessao = (n.sessao ?? {}) as Record<string, unknown>
+    const estado = n.disponivel === true ? String(sessao.estado ?? sessao.state ?? sessao.status ?? 'confirmada') : 'não confirmada'
+    const turno = (n.turno ?? {}) as Record<string, unknown>
+    saida.push(`sessão ${curto(n.sessionId)} ${String(n.runtime ?? '?')}: ${estado}${typeof turno.conclusaoDeFase === 'string' ? ` · ${turno.conclusaoDeFase}` : ''}`)
+  }
+  return saida
+}
+
+/** O estado do git da thread (`ork_git_status`): a branch da thread e a de destino, com os HEADs. */
+export function linhasDoGit(resultado: unknown): string[] {
+  const g = (resultado ?? {}) as { source?: { branch?: unknown; head?: unknown }; destination?: { branch?: unknown; head?: unknown } }
+  if (!g.source || !g.destination) throw new Error('o estado do git veio sem origem e destino')
+  return [`${String(g.source.branch ?? '?')} @ ${curto(g.source.head)}`,
+    `destino ${String(g.destination.branch ?? '?')} @ ${curto(g.destination.head)}${g.source.head === g.destination.head ? ' (iguais)' : ''}`]
+}
+
+export function leituraFeita(linhas: string[], agora: number): TorreLeitura {
+  return { lidoEm: agora, linhas, erro: null }
+}
+export function leituraFalha(erro: string, agora: number): TorreLeitura {
+  return { lidoEm: agora, linhas: [], erro }
+}
+
+/** As linhas de uma secao lida: lendo, o erro, ou o que veio. */
+function linhasDaLeitura(l: TorreLeitura | null | undefined, agora: number): string[] {
+  if (!l) return ['  lendo…']
+  if (l.erro) return [`  não leu: ${l.erro}`]
+  return [...l.linhas.map(x => `  ${x}`), `  (lido há ${idade(agora - l.lidoEm)})`]
+}
+
+/**
+ * O texto do detalhe, linha a linha, na ordem em que aparece, com o que cada linha mostra ao dono (D10).
+ * Thread sem leitura so diz que nao leu e por que: nada de quem conduz nem de acao (D6).
+ */
+export function linhasDoDetalhe(linha: TorreLinha, detalhe: TorreDetalhe | undefined, agora: number): ItemDoPainel[] {
+  const saida: ItemDoPainel[] = [{ texto: cabecalhoDaLinha(linha) }]
+  if (linha.estado === 'sem-leitura') {
+    saida.push({ texto: `não li o retrato: ${linha.lacunas.join('; ')}` })
+  } else {
+    saida.push({ texto: linha.conducao ?? 'ninguém conduz agora' })
+    if (linha.bloqueio) {
+      saida.push({ texto: `bloqueio: ${linha.bloqueio.frase} (${linha.bloqueio.motivo})`,
+        mostrado: { chave: `bloqueio:${linha.thread}:${linha.bloqueio.motivo}`, thread: linha.thread, texto: `${linha.thread}: ${linha.bloqueio.frase}` } })
+    }
+    for (const p of linha.pedidos) {
+      saida.push({ texto: `pedido ${p.id}: ${p.texto}`,
+        mostrado: { chave: `hitl:${p.id}`, thread: linha.thread, texto: `${linha.thread}: espera você: ${p.texto || p.id}` } })
+      const sub = [p.prazo ? `prazo ${p.prazo}` : null, p.recomendacao ? `recomendação: ${p.recomendacao}` : null].filter(Boolean)
+      if (sub.length) saida.push({ texto: `  ${sub.join(' · ')}` })
+    }
+    for (const s of linha.sessoes) {
+      saida.push({ texto: `sessão ${curto(s.id)} ${s.rotulo}: ${emPortugues(s.estado)}${s.conduz ? ' · conduz' : ''}${s.confirmada ? '' : ' · não confirmada'}` })
+    }
+    if (linha.entrega) saida.push({ texto: `entrega: ${emPortugues(linha.entrega)}` })
+    if (linha.master) saida.push({ texto: `MASTER: ${emPortugues(linha.master)}` })
+    if (linha.lacunas.length) saida.push({ texto: `lacuna: ${linha.lacunas.join('; ')}` })
+  }
+  for (const t of ['últimos eventos', ...linhasDaLeitura(detalhe?.eventos, agora), 'claims', ...linhasDaLeitura(detalhe?.claims, agora)]) saida.push({ texto: t })
+  for (const op of LEITURAS) {
+    const l = detalhe?.leituras?.[op]
+    if (l) for (const t of [ROTULO_DA_ACAO[op] ?? op, ...linhasDaLeitura(l, agora)]) saida.push({ texto: t })
+  }
+  return saida
+}
+
+export type Gestos = {
+  voltar?: () => void
+  atualizar?: () => void
+  ler?: (operacao: string) => void
+  abrirMod?: (dono: Dono) => void
+}
+
+/** A arvore do detalhe: os botoes de voltar e atualizar, o texto, e uma linha por acao oferecida. */
+export function desenharDetalhe(el: { Box: any; Text: any; Button: any }, linha: TorreLinha, detalhe: TorreDetalhe | undefined,
+  donos: Readonly<Record<string, string>>, opcoes: { agora: number } & Gestos) {
+  const { Box, Text, Button } = el
+  const acoes = acoesDoDetalhe(linha, donos)
+  const lida = linha.estado !== 'sem-leitura'
+  return (
+    <Box flexDirection="column">
+      <Box key="gestos" flexDirection="row">
+        <Button key="voltar" label="Voltar" onPress={() => opcoes.voltar?.()} />
+        <Button key="atualizar" label="Atualizar" onPress={() => opcoes.atualizar?.()} />
+      </Box>
+      {linhasDoDetalhe(linha, detalhe, opcoes.agora).map((t, i) => (
+        <Text key={`detalhe:${i}`} dimColor={i > 0} wrap="truncate">{t.texto}</Text>
+      ))}
+      {acoes.length > 0 && <Text key="acoes-titulo" bold>ações</Text>}
+      {acoes.map(a => (a.tipo === 'leitura'
+        ? <Button key={`acao:${a.operacao}`} label={a.rotulo} onPress={() => opcoes.ler?.(a.operacao)} />
+        : a.tipo === 'mod'
+          ? <Button key={`acao:${a.operacao}`} label={`${a.rotulo}: abrir ${a.dono.nome}`} onPress={() => opcoes.abrirMod?.(a.dono)} />
+          : <Text key={`acao:${a.operacao}`} wrap="truncate">{a.texto}</Text>))}
+      {lida && acoes.length === 0 && <Text key="sem-acoes" dimColor>nenhuma ação pedida pelo estado desta thread</Text>}
+    </Box>
+  )
+}

package/adapters/claude-code/mods/ork-torre/hooks/frases.ts

@@ -0,0 +1,42 @@
+// A frase curta de cada motivo tipado de gate do nucleo (RM-059, Torre de Controle; D5 da thread). O painel
+// mostra o bloqueio ao dono numa frase so, com acento. O teste do nucleo exige as mesmas chaves de
+// `DESCRICAO_DO_MOTIVO` (core/src/gates.ts): motivo novo no nucleo reprova o teste ate ganhar frase. Modulo
+// puro: so dados.
+
+export const FRASE_DO_MOTIVO: Readonly<Record<string, string>> = {
+  'artifact.missing': 'falta um artefato que a fase exige',
+  'claims.failed': 'uma claim reprovou no HEAD',
+  'claims.unverifiable': 'há claim sem comando de verificação',
+  'policy.violation': 'uma policy de bloqueio foi violada',
+  'runtime.autoconferencia': 'o CHECK caiu no mesmo runtime do GO',
+  'verify.regression': 'um teste que passava na baseline caiu',
+  'verify.failed': 'a verificação falhou, sem baseline para comparar',
+  'verify.timeout': 'a verificação estourou o prazo',
+  'verify.sem-veredito': 'a verificação terminou sem veredito',
+  'ci.failed': 'o CI independente não está verde',
+  'runtime.unavailable': 'o runtime não está disponível',
+  'runtime.silencio': 'a sessão parou de dar sinal',
+  'runtime.rate-limited': 'bateu o limite de uso da assinatura',
+  'runtime.quota-exhausted': 'a cota da conta acabou',
+  'runtime.auth-missing': 'a conta do runtime precisa de login',
+  'runtime.model-unavailable': 'o modelo pedido não está disponível',
+  'runtime.profile-invalid': 'o perfil pedido não existe',
+  'runtime.workspace-untrusted': 'o runtime pede que você confie na pasta',
+  'runtime.consent-pending': 'o runtime pede que você aceite os termos',
+  'cost.violation': 'o despacho iria para um provider pago',
+  'tree.blocked': 'a árvore de destino do merge está ocupada',
+  'lease.busy': 'outra thread segura a região',
+  'lease.resume-unavailable': 'a retomada do lease não está disponível',
+  'conducao.em-andamento': 'outra condução já roda nesta thread',
+  'hitl.formato': 'o pedido ao dono saiu fora do formato',
+  'human.pending': 'espera a sua autorização',
+}
+
+/** Os motivos que so o dono resolve (D6): a linha fica em "espera voce", nao em "parada". */
+export const MOTIVOS_DO_DONO: readonly string[] = ['human.pending', 'runtime.workspace-untrusted', 'runtime.consent-pending',
+  'runtime.auth-missing']
+
+/** A frase do motivo; motivo que a tabela nao conhece aparece cru, nunca some. */
+export function fraseDoMotivo(motivo: string): string {
+  return Object.prototype.hasOwnProperty.call(FRASE_DO_MOTIVO, motivo) ? FRASE_DO_MOTIVO[motivo] as string : motivo
+}

package/adapters/claude-code/mods/ork-torre/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "modules": ["./register.tsx"]
+}