@orkastery/cli 0.5.1 → 0.5.6

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

@@ -0,0 +1,127 @@
+// Contrato de tipos do Freio de Lote (RM-059, fatia F2). O Freio nao acrescenta noun ao `$`: este arquivo
+// declara o estado dele (`PluginState['ork-freio']`) e os tipos que os modulos puros e os testes usam.
+// Sem import nem referencia, como o motor exige de um contrato.
+
+/** Uma claim ativa da thread, como o Freio a usa: o id, o arquivo e os comandos de verificacao. */
+export type FreioClaim = {
+  id: string
+  arquivo: string | null
+  comandos: string[]
+}
+
+/** O que a carga leu do nucleo (T2.1). */
+export type FreioCarga = {
+  /** A thread do despacho, do contexto da ponte. */
+  thread: string
+  /** O status da thread no retrato do nucleo; `fechada` deixa o Freio dormente. */
+  statusDaThread: string | null
+  /** As claims nao retiradas; `null` enquanto o nucleo nao respondeu. */
+  claims: FreioClaim[] | null
+  /** Quando as claims foram lidas, em ms desde a epoca. */
+  claimsEm: number
+  /** O maior numero de claim da thread na leitura, retiradas incluidas (falta na carga gravada antes dele). */
+  maiorClaim?: number
+  /** A uniao dos `touch_paths` das tarefas do plano; `null` sem plano ou sem nenhum. */
+  touchPaths: string[] | null
+  /** O plano ja foi lido (com ou sem `touch_paths`). */
+  planoLido: boolean
+  /** Quando o plano foi lido, em ms desde a epoca. */
+  planoEm: number
+  /** O que falhou na ultima carga, para a linha de status e o teste. */
+  erros: string[]
+}
+
+/** A foto do `git status` da worktree: o HEAD e a assinatura de cada caminho sujo. */
+export type FreioFoto = {
+  head: string | null
+  /** Caminho relativo a raiz da sessao para `XY|tamanho|mtimeMs` (ou `XY|ausente`). */
+  caminhos: Record<string, string>
+}
+
+/** Uma claim afetada pelo lote, na fila da conferencia (T2.2). */
+export type FreioPedido = {
+  id: string
+  /** 3 pelo `arquivo`, 2 pelo caminho citado no comando, 1 pelo nome-base citado (D5). */
+  forca: number
+  /** Os caminhos tocados que a afetaram. */
+  caminhos: string[]
+}
+
+/** O que o Freio vigia entre os lotes. */
+export type FreioVigia = {
+  thread: string
+  /** A ultima foto do `git status`; `null` antes da primeira. */
+  foto: FreioFoto | null
+  /** O numero do lote, que marca quando cada caminho foi tocado. */
+  seq: number
+  /** O ultimo lote que tocou cada caminho. */
+  toques: Record<string, number>
+  /** As claims afetadas que esperam conferencia. */
+  fila: FreioPedido[]
+  /** Os caminhos fora dos `touch_paths` ja avisados nesta sessao. */
+  avisadosFora: string[]
+  // Os campos da conferencia (T2.3) faltam na vigia gravada antes deles; `comConferencia` os preenche.
+  /** A rodada em curso no nucleo, ou `null`. */
+  rodada?: FreioRodada | null
+  /** O que o lote seguinte devolve ao modelo. */
+  entrega?: FreioEntrega
+  /** As claims cuja ultima conferencia reprovou. */
+  emRisco?: string[]
+  /** Ate quando o Freio nao pede conferencia (depois de uma indisponivel), em ms desde a epoca. */
+  pausaAte?: number
+  /** Por que a ultima conferencia ficou indisponivel, ou `null`. */
+  indisponivel?: string | null
+  /** O modelo ja foi avisado da conferencia indisponivel nesta sessao. */
+  avisouIndisponivel?: boolean
+  /** Caminhos fora dos `touch_paths` que o laco principal ainda nao recebeu (lote de subagente nao recebe aviso). */
+  foraPendentes?: string[]
+  /** As claims cuja falha o modelo ja recebeu: so elas voltam como recuperadas quando passam. */
+  avisadas?: string[]
+}
+
+/** Uma rodada de conferencia: as claims, os caminhos que afetaram cada uma e o lote em que ela comecou (T2.3). */
+export type FreioRodada = {
+  ids: string[]
+  caminhos: Record<string, string[]>
+  /** A forca de cada claim, para ela voltar a fila no mesmo lugar (recusa por claim, conducao alheia). */
+  forcas?: Record<string, number>
+  /** O numero do lote no inicio; toque mais novo deixa o resultado da claim velho (D6). */
+  inicio: number
+}
+
+/** Uma claim que a conferencia reprovou (`claims.failed`), como volta ao modelo. */
+export type FreioFalha = {
+  id: string
+  alegacao: string
+  arquivo: string | null
+  comando: string
+  codigo: number | null
+  /** O fim da saida, ja redigido pelo nucleo. */
+  fim: string
+}
+
+/** Uma claim cuja conferencia terminou sem veredito (prazo, comando que nao rodou). */
+export type FreioSemVeredito = {
+  id: string
+  motivo: string
+}
+
+/** O que o lote seguinte devolve ao modelo. */
+export type FreioEntrega = {
+  falhas: FreioFalha[]
+  semVeredito: FreioSemVeredito[]
+  recuperadas: string[]
+  /** O motivo da conferencia indisponivel, so na primeira vez da sessao. */
+  indisponivel: string | null
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'ork-freio': {
+      /** O que a carga leu do nucleo. */
+      carga: FreioCarga
+      /** O que o Freio vigia entre os lotes. */
+      vigia: FreioVigia
+    }
+  }
+}

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

@@ -0,0 +1,14 @@
+{
+  "name": "ork-mesa",
+  "version": "0.1.0",
+  "description": "Mesa do Dono do Orkastery no Claude Code: tudo que espera o dono num painel, um cartão por pedido com a recomendação na frente e a decisão pelo diálogo nativo do host. Só decide pelo dono pela decisão autônoma do núcleo, quando a decisão é óbvia, e nunca responde um pedido.",
+  "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-mesa/hooks/cartoes.tsx

@@ -0,0 +1,246 @@
+// Os cartoes da Mesa do Dono (RM-059 F5; D4 da thread ork-rm059mesa), em funcoes puras: a fila vira linhas da tela,
+// uma por elemento, e as linhas viram a arvore do painel com os elementos que a superficie resolveu. Cada pergunta
+// traz a recomendada primeiro, com o porque, depois as outras alternativas com a consequencia; a decisao que a
+// fabrica (ou a Mesa) tomou pelo dono traz o que, o porque, como mudar e o custo de reverter. O unico botao com
+// efeito e o Decidir, que so pede ao nucleo o dialogo nativo do pedido. So importa tipos e modulos puros da Mesa.
+import type { MesaDecidindo, MesaDecisao, MesaFila, MesaObvia, MesaOutro, MesaPergunta } from '../types'
+import { duracao, esperamODono, MAXIMO_DE_DECISOES, MAXIMO_DE_OUTROS, TAMANHO_DO_LOTE } from './fila'
+import { FALHA_DA_CONDICAO, testeDaObvia } from './obvia'
+
+export type MesaMostrado = { chave: string; thread: string | null; texto: string }
+
+export type LinhaDaMesa = {
+  tipo: 'titulo' | 'aviso' | 'foco' | 'secao' | 'cabecalho' | 'texto' | 'dim' | 'decidir' | 'nav'
+  chave: string
+  texto: string
+  /** O pedido do botao Decidir. */
+  pedidoId?: string
+  /** O que vai ao registro do mostrado da ponte quando a linha esta na janela de rolagem do painel a vista. */
+  mostrado?: MesaMostrado
+}
+
+export type EstadoDaMesa = {
+  fila: MesaFila
+  foco: string | null
+  pagina: number
+  decidindo: Readonly<Record<string, MesaDecidindo>>
+  obvias: Readonly<Record<string, MesaObvia>>
+}
+
+function plural(n: number, um: string, varios: string): string {
+  return `${n} ${n === 1 ? um : varios}`
+}
+
+/** O prazo como o dono le: o horario local que o nucleo mandou, ou quanto falta. */
+function textoDoPrazo(p: MesaPergunta, agora: number): string | null {
+  if (p.prazoLocal) return `prazo ${p.prazoLocal}`
+  const t = Date.parse(p.prazo ?? '')
+  if (!Number.isFinite(t)) return null
+  return t > agora ? `vence em ${duracao(t - agora)}` : `venceu há ${duracao(agora - t)}`
+}
+
+/** As paginas do lote de perguntas, e a pagina pedida dentro delas. */
+export function paginaDoLote(total: number, pagina: number): { pagina: number; paginas: number } {
+  const paginas = Math.max(1, Math.ceil(total / TAMANHO_DO_LOTE))
+  return { pagina: Math.min(Math.max(0, Math.floor(pagina) || 0), paginas - 1), paginas }
+}
+
+/** O cartao de uma pergunta. */
+export function linhasDaPergunta(p: MesaPergunta, e: EstadoDaMesa, agora: number): LinhaDaMesa[] {
+  const k = (s: string) => `${p.pedidoId}:${s}`
+  const obvia = e.obvias[p.pedidoId]
+  const decidida = obvia?.estado === 'registrada'
+  const decidindo = e.decidindo[p.pedidoId]
+  const cabecalho = [p.thread, p.fase, p.codigo ? `código ${p.codigo}` : null, textoDoPrazo(p, agora)].filter(Boolean).join(' · ')
+  const linhas: LinhaDaMesa[] = [{
+    tipo: 'cabecalho', chave: k('cabecalho'), texto: `${decidida ? '✓' : '?'} ${cabecalho}`,
+    mostrado: { chave: `hitl:${p.pedidoId}`, thread: p.thread, texto: `${p.thread}: espera você: ${p.pergunta}` },
+  }]
+  linhas.push({ tipo: 'texto', chave: k('pergunta'), texto: `  ${p.pergunta}` })
+  if (decidida) {
+    linhas.push({ tipo: 'texto', chave: k('obvia'), texto: `  decidido sem te chamar: segue a recomendada no prazo; ${comoMudarDaObvia(p, agora)}` })
+  } else if (obvia?.estado === 'incerta') {
+    linhas.push({ tipo: 'dim', chave: k('obvia'), texto: '  a Mesa pediu ao núcleo a decisão óbvia e confere na próxima leitura se ela foi gravada' })
+  } else if (obvia?.estado === 'recusada') {
+    linhas.push({ tipo: 'aviso', chave: k('obvia'), texto: `  a Mesa não decidiu: ${obvia.texto}` })
+  } else if (!p.conferida) {
+    linhas.push({ tipo: 'dim', chave: k('porque-pergunta'), texto: '  não conferido no núcleo agora: sem Decidir e sem decisão óbvia; use a reserva' })
+  } else {
+    // Sem criterio escrito e o caso de todo gate que espera o dono: dizer isso em cada cartao so repetiria a regra.
+    const teste = testeDaObvia(p, agora)
+    const motivo = teste.obvia ? undefined : teste.falhou[0]
+    if (motivo && motivo !== 'criterio') linhas.push({ tipo: 'dim', chave: k('porque-pergunta'), texto: `  pergunta: ${FALHA_DA_CONDICAO[motivo]}` })
+  }
+  const recomendada = p.alternativas.find(a => a.recomendada)
+  if (recomendada) {
+    linhas.push({ tipo: 'texto', chave: k('recomendada'), texto: `  Recomendada: ${recomendada.chave}) ${recomendada.texto}` })
+    if (recomendada.porque) linhas.push({ tipo: 'dim', chave: k('porque'), texto: `    porque: ${recomendada.porque}` })
+    if (recomendada.consequencia) linhas.push({ tipo: 'dim', chave: k('consequencia'), texto: `    se escolher: ${recomendada.consequencia}` })
+  } else if (p.recomendacao) {
+    linhas.push({ tipo: 'texto', chave: k('recomendada'), texto: `  Recomendação: ${p.recomendacao}` })
+  }
+  for (const a of p.alternativas) {
+    if (a.recomendada) continue
+    linhas.push({ tipo: 'dim', chave: k(`alt:${a.chave}`), texto: `  ${a.chave}) ${a.texto}${a.consequencia ? `: ${a.consequencia}` : ''}` })
+  }
+  if (p.irreversivel) linhas.push({ tipo: 'aviso', chave: k('sem-volta'), texto: `  sem volta: ${p.ato ?? 'ato irreversível'}` })
+  if (decidindo?.estado === 'abrindo') {
+    linhas.push({ tipo: 'texto', chave: k('decidindo'), texto: '  diálogo pedido: responda na janela do Claude Code' })
+  } else {
+    if (decidindo) linhas.push({ tipo: decidindo.estado === 'erro' ? 'aviso' : 'dim', chave: k('decidindo'), texto: `  ${decidindo.texto}` })
+    if (p.canalClaudeCode === 'disponivel') linhas.push({ tipo: 'decidir', chave: `decidir:${p.pedidoId}`, texto: 'Decidir', pedidoId: p.pedidoId })
+  }
+  if (p.reserva) {
+    const telegram = p.contrato === 'ork.hitl/v2' && p.alvo === 'gate' && p.codigo !== null
+    linhas.push({ tipo: 'dim', chave: k('reserva'), texto: telegram ? `  reserva: ${p.reserva} pelo Telegram` : `  reserva: ${p.reserva}` })
+  }
+  return linhas
+}
+
+/** Como o dono muda a decisao obvia que a Mesa registrou: o Decidir ou a reserva antes do prazo; depois dele, nada. */
+function comoMudarDaObvia(p: MesaPergunta, agora: number): string {
+  const prazo = Date.parse(p.prazo ?? '')
+  if (Number.isFinite(prazo) && prazo <= agora) return 'o prazo passou e a recomendada seguiu'
+  return p.canalClaudeCode === 'disponivel' ? 'para mudar, Decidir antes do prazo' : 'para mudar, use a reserva antes do prazo'
+}
+
+/** O cartao de uma decisao que a fabrica (ou a Mesa) tomou sem chamar o dono. */
+export function linhasDaDecisao(d: MesaDecisao, agora: number): LinhaDaMesa[] {
+  const k = (s: string) => `${d.id}:${s}`
+  const em = Date.parse(d.em)
+  const quando = Number.isFinite(em) ? ` · há ${duracao(agora - em)}` : ''
+  const marca = d.revertidaPor ? ' · revertida' : d.nova ? ' · nova' : ''
+  return [
+    { tipo: 'cabecalho', chave: k('cabecalho'), texto: `${d.revertidaPor ? '↺' : '✓'} ${d.thread} · ${d.fase}${quando}${marca}`,
+      mostrado: { chave: `decisao:${d.id}`, thread: d.thread || null, texto: `${d.thread}: decidido sem te chamar: ${d.decidido}` } },
+    { tipo: 'texto', chave: k('decidido'), texto: `  ${d.decidido}` },
+    ...(d.revertidaPor ? [{ tipo: 'aviso' as const, chave: k('revertida'), texto: `  desfeita pela decisão ${d.revertidaPor.slice(0, 8)}` }] : []),
+    ...(d.reverte ? [{ tipo: 'dim' as const, chave: k('reverte'), texto: `  desfaz a decisão ${d.reverte.slice(0, 8)}` }] : []),
+    { tipo: 'dim', chave: k('porque'), texto: `  porque: ${d.porque}` },
+    { tipo: 'dim', chave: k('como-mudar'), texto: `  como mudar: ${d.comoMudar}` },
+    { tipo: 'dim', chave: k('custo'), texto: `  reverter: agora, ${d.custoAgora}; depois, ${d.custoDepois}` },
+    { tipo: 'dim', chave: k('quem'), texto: `  quem decidiu: ${d.quemDecidiu}` },
+  ]
+}
+
+/** O cartao de uma parada sem pedido ou de um impedimento: so leitura, com a recomendacao e o comando. */
+export function linhasDoOutro(o: MesaOutro, agora: number): LinhaDaMesa[] {
+  const k = (s: string) => `${o.chave}:${s}`
+  const desde = Date.parse(o.desdeEm ?? '')
+  const partes = [o.thread ?? 'sem thread', o.fase, o.motivo, Number.isFinite(desde) ? `há ${duracao(agora - desde)}` : null,
+    o.impedimento ? 'só você resolve' : null].filter(Boolean)
+  const linhas: LinhaDaMesa[] = [{
+    tipo: 'cabecalho', chave: k('cabecalho'), texto: `! ${partes.join(' · ')}`,
+    mostrado: { chave: `parada:${o.chave}`, thread: o.thread, texto: `${o.thread ?? 'sem thread'}: ${o.motivo}: ${o.texto}` },
+  }]
+  if (o.texto) linhas.push({ tipo: 'texto', chave: k('texto'), texto: `  ${o.texto}` })
+  if (o.recomendacao) linhas.push({ tipo: 'dim', chave: k('recomendacao'), texto: `  recomendação: ${o.recomendacao}` })
+  if (o.comando && o.comando !== o.recomendacao) linhas.push({ tipo: 'dim', chave: k('comando'), texto: `  comando: ${o.comando}` })
+  return linhas
+}
+
+/** As linhas do painel: o placar, o foco, as perguntas do lote, as decisoes por voce e as paradas. */
+export function linhasDaMesa(e: EstadoDaMesa, opcoes: { agora: number }): LinhaDaMesa[] {
+  const { fila, foco } = e
+  const agora = opcoes.agora
+  const daThread = <T extends { thread: string | null }>(xs: readonly T[]): T[] => (foco ? xs.filter(x => x.thread === foco) : [...xs])
+  const perguntas = daThread(fila.perguntas)
+  const decisoes = daThread(fila.decisoes)
+  const outros = daThread(fila.outros)
+  const esperam = esperamODono({ ...fila, perguntas }, e.obvias)
+  const desde = esperam.map(p => Date.parse(p.desdeEm ?? '')).filter(Number.isFinite)
+  const novas = decisoes.filter(d => d.nova).length
+  const placar = [
+    `${plural(esperam.length, 'espera', 'esperam')} você${desde.length ? ` (a mais antiga há ${duracao(agora - Math.min(...desde))})` : ''}`,
+    `${plural(decisoes.length, 'decidida', 'decididas')} sem te chamar${novas ? ` (${plural(novas, 'nova', 'novas')})` : ''}`,
+    plural(outros.length, 'parada', 'paradas'),
+    fila.lidoEm === null ? 'ainda não li a fila' : `lido há ${duracao(agora - fila.lidoEm)}`,
+  ]
+  const linhas: LinhaDaMesa[] = [{ tipo: 'titulo', chave: 'titulo', texto: placar.join(' · ') }]
+  if (fila.erro) linhas.push({ tipo: 'aviso', chave: 'erro', texto: `não reli a fila: ${fila.erro}` })
+  fila.avisos.forEach((a, i) => linhas.push({ tipo: 'aviso', chave: `aviso:${i}`, texto: a }))
+  if (foco) linhas.push({ tipo: 'foco', chave: 'foco', texto: `só ${foco}` })
+
+  // A secao lista todo pedido aberto; o placar conta so os que esperam o dono (a decisao obvia nao espera).
+  linhas.push({ tipo: 'secao', chave: 'secao-perguntas', texto: 'Pedidos abertos' })
+  if (!perguntas.length) linhas.push({ tipo: 'dim', chave: 'sem-perguntas', texto: '  nenhum pedido aberto agora' })
+  const { pagina, paginas } = paginaDoLote(perguntas.length, e.pagina)
+  for (const p of perguntas.slice(pagina * TAMANHO_DO_LOTE, (pagina + 1) * TAMANHO_DO_LOTE)) linhas.push(...linhasDaPergunta(p, e, agora))
+  if (paginas > 1) linhas.push({ tipo: 'nav', chave: 'nav', texto: `lote ${pagina + 1} de ${paginas}` })
+
+  linhas.push({ tipo: 'secao', chave: 'secao-decisoes', texto: 'Decididas sem te chamar' })
+  if (!decisoes.length) linhas.push({ tipo: 'dim', chave: 'sem-decisoes', texto: '  nenhuma decisão tomada sem te chamar na janela do pulse' })
+  for (const d of decisoes.slice(0, MAXIMO_DE_DECISOES)) linhas.push(...linhasDaDecisao(d, agora))
+  if (decisoes.length > MAXIMO_DE_DECISOES) {
+    linhas.push({ tipo: 'dim', chave: 'mais-decisoes', texto: `  e mais ${decisoes.length - MAXIMO_DE_DECISOES} na janela do pulse (7 dias)` })
+  }
+
+  if (outros.length) {
+    linhas.push({ tipo: 'secao', chave: 'secao-outros', texto: 'Paradas e impedimentos' })
+    for (const o of outros.slice(0, MAXIMO_DE_OUTROS)) linhas.push(...linhasDoOutro(o, agora))
+    if (outros.length > MAXIMO_DE_OUTROS) linhas.push({ tipo: 'dim', chave: 'mais-outros', texto: `  e mais ${outros.length - MAXIMO_DE_OUTROS}` })
+  }
+  return linhas
+}
+
+/**
+ * O que o desenho poe na janela de rolagem e vai ao registro do mostrado: so linha com `mostrado` cuja posicao esta
+ * entre `offset` e `offset + bodyRows`. Sem janela, nada: o que nao estava na tela nao conta como visto.
+ */
+export function mostradosVisiveis(linhas: readonly LinhaDaMesa[], janela: { offset: number; bodyRows: number } | undefined): MesaMostrado[] {
+  if (!janela || !(janela.bodyRows > 0)) return []
+  const fim = janela.offset + janela.bodyRows
+  return linhas.flatMap((l, i) => (l.mostrado && i >= janela.offset && i < fim ? [l.mostrado] : []))
+}
+
+export type AcoesDaMesa = {
+  decidir?: (pedidoId: string) => void
+  atualizar?: () => void
+  verTodas?: () => void
+  anteriores?: () => void
+  proximas?: () => void
+}
+
+/** A arvore do painel com os elementos que a superficie resolveu (`$.ui.resolve(e)` no register.tsx). */
+export function desenharMesa(el: { Box: any; Text: any; Button: any }, linhas: readonly LinhaDaMesa[], acoes: AcoesDaMesa) {
+  const { Box, Text, Button } = el
+  return (
+    <Box flexDirection="column">
+      {linhas.map(l => {
+        if (l.tipo === 'titulo') {
+          return (
+            <Box key="titulo" flexDirection="row">
+              <Text key="placar" bold wrap="truncate">{l.texto}</Text>
+              <Button key="atualizar" label="Atualizar" onPress={() => acoes.atualizar?.()} />
+            </Box>
+          )
+        }
+        if (l.tipo === 'foco') {
+          return (
+            <Box key="foco" flexDirection="row">
+              <Text key="foco-texto" dimColor wrap="truncate">{l.texto}</Text>
+              <Button key="ver-todas" label="Ver todas" onPress={() => acoes.verTodas?.()} />
+            </Box>
+          )
+        }
+        if (l.tipo === 'nav') {
+          return (
+            <Box key="nav" flexDirection="row">
+              <Button key="anteriores" label="Anteriores" onPress={() => acoes.anteriores?.()} />
+              <Text key="nav-texto" dimColor wrap="truncate">{l.texto}</Text>
+              <Button key="proximas" label="Próximas" onPress={() => acoes.proximas?.()} />
+            </Box>
+          )
+        }
+        if (l.tipo === 'decidir') {
+          const pedidoId = l.pedidoId ?? ''
+          return <Button key={l.chave} label="Decidir" onPress={() => acoes.decidir?.(pedidoId)} />
+        }
+        if (l.tipo === 'secao' || l.tipo === 'cabecalho') return <Text key={l.chave} bold wrap="truncate">{l.texto}</Text>
+        if (l.tipo === 'aviso') return <Text key={l.chave} color="warning" wrap="truncate">{l.texto}</Text>
+        if (l.tipo === 'dim') return <Text key={l.chave} dimColor wrap="truncate">{l.texto}</Text>
+        return <Text key={l.chave} wrap="truncate">{l.texto}</Text>
+      })}
+    </Box>
+  )
+}

package/adapters/claude-code/mods/ork-mesa/hooks/decidir.ts

@@ -0,0 +1,110 @@
+// O que a Mesa do Dono manda ao nucleo (RM-059 F5; D6 e D7 da thread ork-rm059mesa), em funcoes puras. Sao so duas
+// ferramentas com efeito e uma de leitura, todas no servidor `orkastery`:
+//  - `ork_request_decision` recebe exatamente `threadId` e `pedidoId`: o nucleo abre o dialogo nativo do host e grava
+//    a resposta que o dono der, com o recibo do ingresso local. A Mesa nunca manda opcao, letra nem texto.
+//  - `ork_decision_record` registra a decisao obvia (teste das quatro condicoes) como decisao autonoma do nucleo,
+//    com criterio, evidencia, como mudar e o custo de reverter. Nao responde o pedido.
+//  - `ork_hitl_pending` le os pedidos abertos de uma thread.
+// So importa tipos.
+import type { MesaDecidindo, MesaDecisao, MesaPergunta } from '../types'
+
+export const SERVIDOR = 'orkastery'
+/** A lista fechada de ferramentas do nucleo que a Mesa chama (D2 e D7). */
+export const FERRAMENTAS_DA_MESA: readonly string[] = ['ork_hitl_pending', 'ork_request_decision', 'ork_decision_record']
+/** Quem decidiu, no rastro do nucleo: a Mesa, nunca o dono (o nucleo recusa rastro que comeca pelo dono). */
+export const QUEM_DECIDIU = 'mod ork-mesa na sessão do dono, pelo teste das quatro condições'
+/** Os tetos do nucleo para a decisao informada (`TETOS_HITL_V2` e o esquema do `ork_decision_record`). */
+export const TETO_DO_CAMPO = 200
+export const TETO_DO_CUSTO = 140
+export const TETO_DA_REFERENCIA = 300
+
+/** Uma linha so, cortada no teto, para caber no contrato do nucleo. */
+export function linhaNoTeto(v: string, teto: number): string {
+  const t = v.replace(/\s+/g, ' ').trim()
+  return t.length <= teto ? t : `${t.slice(0, teto - 1).trimEnd()}…`
+}
+
+/** Os argumentos do Decidir: so os dois ids, nada que seja resposta. */
+export function argsDoDecidir(p: Pick<MesaPergunta, 'thread' | 'pedidoId'>): { threadId: string; pedidoId: string } {
+  return { threadId: p.thread, pedidoId: p.pedidoId }
+}
+
+/** A marca do pedido no texto da decisao obvia: e por ela que a Mesa sabe que ja decidiu este pedido. */
+export function marcaDoPedido(pedidoId: string): string {
+  return `(${pedidoId.slice(0, 8)})`
+}
+
+/** Ja existe, na janela do pulse, a decisao obvia que a Mesa registrou para este pedido. */
+export function jaDecidida(decisoes: readonly MesaDecisao[], p: Pick<MesaPergunta, 'thread' | 'pedidoId'>): boolean {
+  const marca = marcaDoPedido(p.pedidoId)
+  return decisoes.some(d => d.thread === p.thread && d.quemDecidiu.startsWith('mod ork-mesa') && d.decidido.includes(marca))
+}
+
+export type ArgsDaDecisaoObvia = {
+  threadId: string
+  decidido: string
+  porque: string
+  comoMudar: string
+  custoAgora: string
+  custoDepois: string
+  criterio: { tipo: 'medicao'; referencia: string }
+  quemDecidiu: string
+  evidencia: string
+}
+
+/**
+ * Os argumentos do `ork_decision_record` para uma decisao obvia: o que, o porque, como mudar, o custo de reverter
+ * antes e depois do prazo, o criterio (a medicao que mostra o pedido declarando `seguir-recomendada`) e a evidencia
+ * (a leitura do `ork_hitl_pending`). Cada campo cabe nos tetos do nucleo, numa linha.
+ */
+export function argsDaDecisaoObvia(p: MesaPergunta, recomendada: { chave: string; texto: string }, referencia: string,
+  lidoEmIso: string): ArgsDaDecisaoObvia {
+  const pedido = p.codigo ?? p.pedidoId.slice(0, 8)
+  const prazo = p.prazoLocal ?? p.prazo ?? 'no prazo do pedido'
+  const reserva = p.reserva ? ` ou ${p.reserva} pelo Telegram` : ''
+  return {
+    threadId: p.thread,
+    decidido: linhaNoTeto(`Sem te chamar: o pedido ${pedido} ${marcaDoPedido(p.pedidoId)} da ${p.thread} segue a recomendada ` +
+      `${recomendada.chave} (${recomendada.texto}) no prazo ${prazo}`, TETO_DO_CAMPO),
+    porque: linhaNoTeto('O pedido declara que segue a recomendada no prazo, é reversível antes da entrega e passou nas quatro ' +
+      'condições da decisão óbvia (M4)', TETO_DO_CAMPO),
+    comoMudar: linhaNoTeto(`Na Mesa, Decidir no cartão do pedido ${pedido} antes do prazo${reserva}`, TETO_DO_CAMPO),
+    custoAgora: linhaNoTeto('Nenhum: o pedido segue aberto até o prazo e o dono escolhe outra alternativa no diálogo', TETO_DO_CUSTO),
+    custoDepois: linhaNoTeto('Depois do prazo a recomendada já seguiu; mudar pede nova decisão na thread', TETO_DO_CUSTO),
+    criterio: { tipo: 'medicao', referencia: linhaNoTeto(referencia, TETO_DA_REFERENCIA) },
+    quemDecidiu: QUEM_DECIDIU,
+    evidencia: linhaNoTeto(`ork_hitl_pending ${p.thread} lido em ${lidoEmIso}: pedido ${p.pedidoId}, estado ${p.estado}, ` +
+      `acaoPadraoAoExpirar ${p.acaoAoExpirar ?? '-'}, irreversivel ${String(p.irreversivel)}, fase ${p.fase ?? '-'}`, 4096),
+  }
+}
+
+/**
+ * Depois de uma recarga do modulo nenhum Decidir esta em curso: o que ficou `abrindo` no estado vira `sem-resposta`,
+ * e o cartao volta a ter o botao.
+ */
+export function soltarAbrindo(decidindo: Readonly<Record<string, MesaDecidindo>>): Record<string, MesaDecidindo> {
+  return Object.fromEntries(Object.entries(decidindo).map(([id, v]) => [id, v.estado === 'abrindo'
+    ? { estado: 'sem-resposta' as const, texto: 'o diálogo ficou sem resposta (a Mesa recarregou); o pedido segue aberto', em: v.em } : v]))
+}
+
+/** Por que a notificacao do sistema nao saiu, em pt-BR (o motor manda o codigo em ingles). */
+export function motivoDaNotificacao(reason: unknown): string {
+  const motivos: Record<string, string> = {
+    'no-channel': 'nenhum canal de notificação configurado',
+    'no-surface': 'nenhuma superfície para mostrar',
+    refused: 'o terminal recusou a notificação',
+    disabled: 'as notificações estão desligadas',
+  }
+  return `a notificação do sistema não saiu (${motivos[String(reason)] ?? String(reason)})`
+}
+
+/** O que o cartao diz do Decidir, a partir do que o nucleo devolveu (`{ ok, pedidoId, estado, repetida }`). */
+export function resultadoDoDecidir(resposta: unknown, agora: number): MesaDecidindo {
+  const r = (resposta && typeof resposta === 'object' ? resposta : {}) as { ok?: unknown; estado?: unknown; repetida?: unknown }
+  const estado = typeof r.estado === 'string' ? r.estado : ''
+  if (r.ok === true) {
+    if (r.repetida === true) return { estado: 'respondido', texto: `o pedido já estava respondido no núcleo: ${estado || 'registrado'}`, em: agora }
+    return { estado: 'respondido', texto: `respondido pelo diálogo: ${estado || 'registrado'}`, em: agora }
+  }
+  return { estado: 'sem-resposta', texto: 'o diálogo fechou sem resposta; o pedido segue aberto', em: agora }
+}