@orkastery/cli 0.5.3 → 0.6.0

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-mensageiro/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "ork-mensageiro",
+  "version": "0.1.0",
+  "description": "Mensageiro de Sessões do Orkastery no Claude Code: leva a resposta que o dono deu pelo diálogo nativo à sessão de fase claude-bg que parou esperando por ele, como mensagem entre sessões, e na sessão de fase só deixa chegar ao modelo a mensagem que o núcleo confirmou como aquela resposta. Nunca responde nem aprova pelo dono.",
+  "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-mensageiro/hooks/caixa.ts

@@ -0,0 +1,215 @@
+// O lado do dono do Mensageiro de Sessoes (RM-059, fatia F9, T9.2), em funcoes puras. A sessao do dono que recebeu a
+// resposta pelo dialogo nativo tem a mensagem na caixa de saida do servidor MCP dela (`ork_session_outbox`), so na
+// memoria; o Mensageiro a leva a sessao de fase por `$.session.send`, sem mexer no texto, e anota o envio no nucleo.
+// O que segue incerto noutra sessao do dono sai do retrato da ponte (secao `hitl`). Nada daqui guarda o texto da
+// resposta no estado (D12 da thread ork-rm059mensag). So importa tipos.
+import type { MensageiroDono, MensageiroEntrega, MensageiroEstadoDaEntrega, MensageiroIncerta } from '../types'
+
+export const SERVIDOR = 'orkastery'
+/** A ferramenta da caixa de saida, so no servidor do dono do Claude Code (T9.1). */
+export const FERRAMENTA_DA_CAIXA = 'ork_session_outbox'
+/** O contrato da entrega no nucleo (`core/src/entrega-por-mod.ts`), conferido pelo teste do nucleo. */
+export const CONTRATO_DA_ENTREGA = 'ork.session-delivery/v1'
+/** D10: o envio que nao entrou na fila volta depois do recuo; o que entrou e nao foi reservado, depois da espera. */
+export const RECUO_DO_ENVIO_MS = 30000
+export const ESPERA_DA_RESERVA_MS = 60000
+export const MAXIMO_DE_ENVIOS = 10
+/** D21: a reserva sem recibo por este tempo deixa de ser "confirmando" e pede o dono. */
+export const ESPERA_DO_RECIBO_MS = 5 * 60000
+/** A faixa diz "entregue" por este tempo; o painel guarda o que terminou por este outro. */
+export const FAIXA_DA_ENTREGA_MS = 10 * 60000
+export const GUARDA_DO_TERMINADO_MS = 30 * 60000
+export const MAXIMO_DE_ENTREGAS = 50
+export const DONO_VAZIO: MensageiroDono = { entregas: [], incertas: [], lidoEm: null, erro: null }
+
+const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+const VIVOS: readonly MensageiroEstadoDaEntrega[] = ['na-fila', 'a-caminho', 'reservada', 'nao-chegou']
+
+/** Uma entrega da caixa de saida como o nucleo a lista, com o ultimo envio em ms. */
+export type EntradaDaCaixa = {
+  thread: string; pedidoId: string; envioId: string; sessionId: string
+  /** A mensagem inteira, com o cabecalho do nucleo: vai ao `$.session.send` como esta e nunca ao estado. */
+  mensagem: string
+  tentativas: number
+  ultimoEnvio: { em: number; entregue: boolean; motivo: string | null } | null
+  reservada: boolean
+  /** Quando a entrega entrou na caixa (ms desde a epoca); conta o sem-recibo quando o envio nao foi anotado. */
+  criadaEm: number | null
+}
+
+const objeto = (v: unknown): v is Record<string, any> => !!v && typeof v === 'object' && !Array.isArray(v)
+const uuid = (v: unknown): v is string => typeof v === 'string' && UUID.test(v)
+
+/** Uma linha so, sem caractere de controle e com teto: o que vem do nucleo ou de um erro nunca quebra a tela. */
+export function umaLinha(v: unknown, teto = 200): string {
+  const s = typeof v === 'string' ? v : v instanceof Error ? v.message : String(v)
+  return Array.from(s.replace(/\p{Cc}/gu, ' ').replace(/\s+/g, ' ').trim()).slice(0, teto).join('')
+}
+
+/** O JSON que uma ferramenta do nucleo devolveu; a recusa vira erro com o motivo dela. */
+export function jsonDoMcp(r: unknown, ferramenta: string): unknown {
+  const o = objeto(r) ? r : {}
+  const conteudo = Array.isArray(o.content) ? o.content : []
+  const texto = conteudo.filter(c => objeto(c) && c.type === 'text' && typeof c.text === 'string').map(c => c.text).join('')
+  let dados: unknown
+  try { dados = JSON.parse(texto) } catch { throw new Error(`${ferramenta} respondeu fora do JSON`) }
+  if (o.isError === true) throw new Error(`${ferramenta} recusou: ${umaLinha(objeto(dados) && typeof dados.erro === 'string' ? dados.erro : texto)}`)
+  return dados
+}
+
+function lerEntrada(e: unknown): EntradaDaCaixa[] {
+  if (!objeto(e) || typeof e.thread !== 'string' || !ID_DE_THREAD.test(e.thread) || !uuid(e.pedidoId) || !uuid(e.envioId) ||
+      !uuid(e.sessionId) || typeof e.mensagem !== 'string' ||
+      !e.mensagem.startsWith(`[${CONTRATO_DA_ENTREGA} pedido=${e.pedidoId} entrega=${e.envioId}] `)) return []
+  const u = objeto(e.ultimoEnvio) ? e.ultimoEnvio : null
+  const em = u && typeof u.em === 'string' ? Date.parse(u.em) : NaN
+  const criadaEm = typeof e.criadaEm === 'string' ? Date.parse(e.criadaEm) : NaN
+  return [{ thread: e.thread, pedidoId: e.pedidoId, envioId: e.envioId, sessionId: e.sessionId, mensagem: e.mensagem,
+    tentativas: Number.isSafeInteger(e.tentativas) && e.tentativas > 0 ? e.tentativas : 0,
+    ultimoEnvio: u && Number.isFinite(em) ? { em, entregue: u.entregue === true, motivo: typeof u.motivo === 'string' ? umaLinha(u.motivo) : null } : null,
+    reservada: e.reservada === true, criadaEm: Number.isFinite(criadaEm) ? criadaEm : null }]
+}
+
+/** A caixa de saida do `listar`; o que nao bate com o contrato fica de fora, e a resposta fora do contrato e erro. */
+export function lerCaixa(dados: unknown): EntradaDaCaixa[] {
+  if (!objeto(dados) || dados.contrato !== CONTRATO_DA_ENTREGA || !Array.isArray(dados.entregas)) {
+    throw new Error('a caixa de saída respondeu fora do contrato ork.session-delivery/v1')
+  }
+  return dados.entregas.flatMap(lerEntrada)
+}
+
+/** A entrega que o `enviada` devolveu, com a reserva que ela tinha na lista (o nucleo so a le no `listar`). */
+export function entradaAnotada(dados: unknown, reservada: boolean): EntradaDaCaixa | null {
+  const lida = objeto(dados) && dados.contrato === CONTRATO_DA_ENTREGA ? lerEntrada({ ...(objeto(dados.entrega) ? dados.entrega : {}), reservada }) : []
+  return lida[0] ?? null
+}
+
+/** D10: envia o que nunca foi, o que nao entrou na fila depois do recuo e o que entrou e ninguem reservou depois da espera. */
+export function deveEnviar(e: EntradaDaCaixa, agora: number): boolean {
+  if (e.reservada || e.tentativas >= MAXIMO_DE_ENVIOS) return false
+  if (!e.ultimoEnvio) return true
+  return agora - e.ultimoEnvio.em >= (e.ultimoEnvio.entregue ? ESPERA_DA_RESERVA_MS : RECUO_DO_ENVIO_MS)
+}
+
+/** O argumento do `$.session.send`: a sessao do pedido e a mensagem do nucleo, sem mexer em nada. */
+export function argsDoEnvio(e: EntradaDaCaixa): { to: { sessionId: string }; text: string } {
+  return { to: { sessionId: e.sessionId }, text: e.mensagem }
+}
+
+/** O resultado do `$.session.send` como o nucleo o anota. */
+export function resultadoDoEnvio(r: unknown): { entregue: boolean; motivo: string | null } {
+  if (objeto(r) && r.isDelivered === true) return { entregue: true, motivo: null }
+  return { entregue: false, motivo: umaLinha(objeto(r) && typeof r.reason === 'string' && r.reason ? r.reason : 'a sessão não recebeu a mensagem') }
+}
+
+export function argsDaAnotacao(e: EntradaDaCaixa, r: { entregue: boolean; motivo: string | null }): Record<string, unknown> {
+  return { operacao: 'enviada', threadId: e.thread, envioId: e.envioId, entregue: r.entregue, ...(r.motivo ? { motivo: r.motivo } : {}) }
+}
+
+/** A secao `hitl` do retrato, quando ela veio lida (disponivel ou vazia); `null` quando nao da para concluir nada. */
+function secaoHitl(retrato: unknown): Record<string, any>[] | null {
+  const secoes = objeto(retrato) && objeto(retrato.sections) ? retrato.sections : {}
+  const hitl = objeto(secoes.hitl) ? secoes.hitl : null
+  if (!hitl || (hitl.state !== 'available' && hitl.state !== 'empty')) return null
+  return Array.isArray(hitl.items) ? hitl.items.filter(objeto) : []
+}
+
+const threadDoItem = (i: Record<string, any>): string | null => {
+  const ref = Array.isArray(i.refs) ? i.refs.find((r: unknown) => objeto(r) && r.kind === 'thread' && typeof r.id === 'string') : null
+  return ref && ID_DE_THREAD.test(ref.id) ? ref.id : null
+}
+
+/** Os pedidos abertos que o retrato mostra (respondido sai da secao); `null` quando a secao nao veio lida. */
+export function pedidosNoRetrato(retrato: unknown): Set<string> | null {
+  const itens = secaoHitl(retrato)
+  return itens === null ? null : new Set(itens.flatMap(i => (typeof i.id === 'string' ? [i.id] : [])))
+}
+
+/** Os pedidos de sessao com a entrega incerta no retrato (`delivery.uncertain`): a entrega segue em alguma sessao do dono. */
+export function incertasDoRetrato(retrato: unknown): MensageiroIncerta[] {
+  return (secaoHitl(retrato) ?? []).flatMap(i => {
+    const thread = threadDoItem(i)
+    return i.status === 'delivery.uncertain' && objeto(i.facts) && i.facts.target === 'session' && uuid(i.id) && thread
+      ? [{ thread, pedidoId: i.id }] : []
+  })
+}
+
+/** O estado de uma entrega que esta na caixa, agora. */
+export function estadoDaEntrada(e: EntradaDaCaixa, agora: number): MensageiroEstadoDaEntrega {
+  if (e.reservada) {
+    const desde = e.ultimoEnvio?.em ?? e.criadaEm
+    return typeof desde === 'number' && agora - desde >= ESPERA_DO_RECIBO_MS ? 'sem-recibo' : 'reservada'
+  }
+  if (!e.ultimoEnvio) return 'na-fila'
+  if (e.tentativas >= MAXIMO_DE_ENVIOS) return 'desistiu'
+  return e.ultimoEnvio.entregue ? 'a-caminho' : 'nao-chegou'
+}
+
+function motivoDaEntrada(e: EntradaDaCaixa, estado: MensageiroEstadoDaEntrega): string | null {
+  if (estado === 'sem-recibo') return 'a sessão de fase reservou a entrega e não gravou o recibo em 5 min'
+  if (estado === 'desistiu') {
+    return e.ultimoEnvio?.entregue
+      ? `a sessão de fase não confirmou a entrega depois de ${e.tentativas} envios`
+      : e.ultimoEnvio?.motivo ?? `a mensagem não entrou na fila da sessão em ${e.tentativas} envios`
+  }
+  return estado === 'nao-chegou' ? e.ultimoEnvio?.motivo ?? null : null
+}
+
+/**
+ * As entregas desta sessao depois de uma leitura da caixa. A que saiu da caixa terminou: entregue, quando o retrato
+ * nao mostra mais o pedido (respondido); "saiu da caixa", quando o pedido segue aberto. Sem o retrato, nada se conclui.
+ */
+export function atualizarEntregas(anteriores: readonly MensageiroEntrega[], caixa: readonly EntradaDaCaixa[],
+  noRetrato: Set<string> | null, agora: number): MensageiroEntrega[] {
+  const restantes = new Map(anteriores.map(e => [e.envioId, e]))
+  const saida: MensageiroEntrega[] = []
+  for (const c of caixa) {
+    const estado = estadoDaEntrada(c, agora)
+    const antes = restantes.get(c.envioId)
+    restantes.delete(c.envioId)
+    saida.push({ thread: c.thread, pedidoId: c.pedidoId, envioId: c.envioId, sessionId: c.sessionId, estado, tentativas: c.tentativas,
+      motivo: motivoDaEntrada(c, estado), em: antes && antes.estado === estado ? antes.em : agora })
+  }
+  for (const e of restantes.values()) {
+    if (!VIVOS.includes(e.estado) && e.estado !== 'desistiu' && e.estado !== 'sem-recibo') {
+      if (agora - e.em <= GUARDA_DO_TERMINADO_MS) saida.push(e)
+      continue
+    }
+    if (noRetrato === null) { saida.push(e); continue }
+    const aberto = noRetrato.has(e.pedidoId)
+    saida.push({ ...e, estado: aberto ? 'saiu-da-caixa' : 'entregue', em: agora,
+      motivo: aberto ? 'a caixa de saída soltou a entrega sem recibo; responda pelo claude attach' : null })
+  }
+  return saida.slice(-MAXIMO_DE_ENTREGAS)
+}
+
+/** A thread do ledger que mudou, pelos caminhos que a ponte vigia (`.orkastery/threads/<thread>/ledger.jsonl`). */
+export function threadDoLedger(caminho: unknown): string | null {
+  if (typeof caminho !== 'string') return null
+  const m = /\.orkastery\/threads\/([^/]+)\/ledger\.jsonl$/.exec(caminho)
+  return m && ID_DE_THREAD.test(m[1]) ? m[1] : null
+}
+
+function daThread(entregas: readonly MensageiroEntrega[], um: string, varios: (n: number) => string): string {
+  return entregas.length === 1 ? `${um} ${entregas[0].thread}` : varios(entregas.length)
+}
+
+/**
+ * A linha da faixa (D7 do plano dos mods): o que nao chegou e precisa do dono vem primeiro; depois o que esta a caminho;
+ * depois o que acabou de ser entregue. Sem nada disso, a linha sai da faixa.
+ */
+export function textoDaFaixa(dono: MensageiroDono, agora: number): string | undefined {
+  const falhas = dono.entregas.filter(e => e.estado === 'desistiu' || e.estado === 'saiu-da-caixa')
+  if (falhas.length) return falhas.length === 1
+    ? `a resposta para a ${falhas[0].thread} não chegou; responda pelo claude attach` : `${falhas.length} respostas não chegaram; abra /mensageiro`
+  // Sem recibo, a resposta pode ter entrado na conversa: o dono confere antes de responder de novo.
+  const semRecibo = dono.entregas.filter(e => e.estado === 'sem-recibo')
+  if (semRecibo.length) return semRecibo.length === 1
+    ? `a resposta para a ${semRecibo[0].thread} ficou sem recibo; confira pelo claude attach` : `${semRecibo.length} respostas sem recibo; abra /mensageiro`
+  const vivas = dono.entregas.filter(e => VIVOS.includes(e.estado))
+  if (vivas.length) return daThread(vivas, 'resposta a caminho da', n => `${n} respostas a caminho das sessões de fase`)
+  const entregues = dono.entregas.filter(e => e.estado === 'entregue' && agora - e.em <= FAIXA_DA_ENTREGA_MS)
+  if (entregues.length) return daThread(entregues, 'resposta entregue à', n => `${n} respostas entregues às sessões de fase`)
+  return undefined
+}

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

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

package/adapters/claude-code/mods/ork-mensageiro/hooks/painel.tsx

@@ -0,0 +1,165 @@
+// O painel do Mensageiro de Sessoes (RM-059, fatia F9), em funcoes puras: o estado vira linhas da tela, uma por
+// elemento, e as linhas viram a arvore do painel com os elementos que a superficie resolveu (so `Box`, `Text` e
+// `Button`, os mesmos no terminal e no desktop). Todo estado tem rotulo e glifo, nunca so cor (regra da Partitura).
+// O texto da resposta do dono nunca aparece aqui: so a thread, o pedido e o estado da entrega. So importa tipos e
+// modulos puros do Mensageiro.
+import type { MensageiroDono, MensageiroEntrega, MensageiroEstadoDaEntrega, MensageiroEstadoDaRecebida, MensageiroFase, MensageiroMostrado,
+  MensageiroRecebida } from '../types'
+import { umaLinha } from './caixa'
+import { codigoDoMotivo, motivoLegivel } from './recepcao'
+
+export type LinhaDoMensageiro = {
+  tipo: 'titulo' | 'secao' | 'texto' | 'dim' | 'falha' | 'feito'
+  chave: string
+  texto: string
+  /** O que vai ao registro do mostrado da ponte quando a linha esta na janela de rolagem do painel a vista. */
+  mostrado?: MensageiroMostrado
+}
+
+export const ROTULO_DO_ESTADO: Record<MensageiroEstadoDaEntrega, string> = {
+  'na-fila': 'na fila do núcleo',
+  'a-caminho': 'a caminho: na fila da sessão, esperando a conferência',
+  'reservada': 'recebida pela sessão, confirmando',
+  'sem-recibo': 'recebida pela sessão, sem recibo em 5 min: confira pelo claude attach',
+  'nao-chegou': 'não entrou na fila da sessão; nova tentativa em breve',
+  'desistiu': 'não chegou: responda pelo claude attach',
+  'entregue': 'entregue, com o recibo da sessão',
+  'saiu-da-caixa': 'saiu da caixa sem recibo: responda pelo claude attach',
+}
+
+const GLIFO: Record<MensageiroEstadoDaEntrega, string> = {
+  'na-fila': '·', 'a-caminho': '●', 'reservada': '●', 'sem-recibo': '?', 'nao-chegou': '×', 'desistiu': '×', 'entregue': '✓', 'saiu-da-caixa': '?',
+}
+
+const TIPO: Record<MensageiroEstadoDaEntrega, LinhaDoMensageiro['tipo']> = {
+  'na-fila': 'texto', 'a-caminho': 'texto', 'reservada': 'texto', 'sem-recibo': 'falha', 'nao-chegou': 'falha', 'desistiu': 'falha', 'entregue': 'feito', 'saiu-da-caixa': 'falha',
+}
+
+/** Quanto tempo faz, como o dono le. */
+export function idade(ms: number): string {
+  if (!(ms >= 60000)) return 'agora'
+  const min = Math.floor(ms / 60000)
+  return min < 60 ? `há ${min} min` : `há ${Math.floor(min / 60)} h`
+}
+
+const curto = (id: string) => id.slice(0, 8)
+
+function linhasDaEntrega(e: MensageiroEntrega, agora: number): LinhaDoMensageiro[] {
+  const k = (s: string) => `${e.envioId}:${s}`
+  const envios = e.tentativas > 1 ? ` · ${e.tentativas} envios` : ''
+  const texto = `${GLIFO[e.estado]} ${e.thread} · pedido ${curto(e.pedidoId)} · ${ROTULO_DO_ESTADO[e.estado]}${envios} · ${idade(agora - e.em)}`
+  const linhas: LinhaDoMensageiro[] = [{ tipo: TIPO[e.estado], chave: k('estado'), texto: umaLinha(texto, 300),
+    mostrado: { chave: `hitl:${e.pedidoId}`, thread: e.thread, texto: `${e.thread}: resposta do dono ${ROTULO_DO_ESTADO[e.estado]}` } }]
+  if (e.motivo) linhas.push({ tipo: 'dim', chave: k('motivo'), texto: `  ${umaLinha(e.motivo, 200)}` })
+  return linhas
+}
+
+/** As linhas do painel na sessao do dono. */
+export function linhasDoDono(dono: MensageiroDono, agora: number): LinhaDoMensageiro[] {
+  const linhas: LinhaDoMensageiro[] = [
+    { tipo: 'titulo', chave: 'titulo', texto: 'Mensageiro de Sessões' },
+    { tipo: 'dim', chave: 'o-que-faz', texto: 'Leva a resposta que você deu pelo diálogo à sessão de fase que parou esperando por ela.' },
+  ]
+  if (dono.erro) linhas.push({ tipo: 'falha', chave: 'erro', texto: `× ${umaLinha(dono.erro, 200)}` })
+  linhas.push({ tipo: 'secao', chave: 'secao-entregas', texto: 'Respostas desta sessão' })
+  if (!dono.entregas.length) linhas.push({ tipo: 'dim', chave: 'sem-entregas', texto: '  nenhuma resposta a caminho agora' })
+  for (const e of [...dono.entregas].reverse()) linhas.push(...linhasDaEntrega(e, agora))
+  if (dono.incertas.length) {
+    // O retrato so diz que a entrega esta incerta (sem o runtime): ela pode seguir noutra sessao do dono ou noutro canal
+    // (um envio nativo pendente), ou ter se perdido com uma sessao que fechou. O painel nao sabe qual, e diz isso.
+    linhas.push({ tipo: 'secao', chave: 'secao-incertas', texto: 'Fora desta sessão' })
+    for (const i of dono.incertas) {
+      linhas.push({ tipo: 'texto', chave: `incerta:${i.pedidoId}`,
+        texto: `· ${i.thread} · pedido ${curto(i.pedidoId)} · entrega incerta fora desta sessão: noutra sessão do dono, noutro canal ou perdida` })
+    }
+    linhas.push({ tipo: 'dim', chave: 'incertas-limite', texto: '  sem retorno, responda pelo claude attach' })
+  }
+  linhas.push({ tipo: 'dim', chave: 'limite', texto: 'A resposta chega como mensagem de outra sessão: informa a sessão de fase, não autoriza ação que só você aprova. Para isso, claude attach.' })
+  if (dono.lidoEm === null) linhas.push({ tipo: 'dim', chave: 'lido', texto: 'a caixa de saída ainda não foi lida' })
+  else linhas.push({ tipo: 'dim', chave: 'lido', texto: `caixa de saída lida ${idade(agora - dono.lidoEm)}` })
+  return linhas
+}
+
+export const ROTULO_DA_RECEBIDA: Record<MensageiroEstadoDaRecebida, string> = {
+  'consumida': 'consumida antes do modelo',
+  'confirmando': 'entrou na conversa; gravando o recibo no núcleo',
+  'entregue': 'entrou na conversa, com o recibo no núcleo',
+  'sem-recibo': 'entrou na conversa, mas o recibo não foi gravado',
+  'nao-entrou': 'conferida, mas não entrou na conversa',
+}
+
+const GLIFO_DA_RECEBIDA: Record<MensageiroEstadoDaRecebida, string> = {
+  'consumida': '○', 'confirmando': '●', 'entregue': '✓', 'sem-recibo': '?', 'nao-entrou': '×',
+}
+
+const TIPO_DA_RECEBIDA: Record<MensageiroEstadoDaRecebida, LinhaDoMensageiro['tipo']> = {
+  'consumida': 'texto', 'confirmando': 'texto', 'entregue': 'feito', 'sem-recibo': 'falha', 'nao-entrou': 'falha',
+}
+
+function linhasDaRecebida(r: MensageiroRecebida, i: number, agora: number): LinhaDoMensageiro[] {
+  const k = (s: string) => `recebida:${i}:${s}`
+  const quem = r.estado === 'consumida'
+    ? `mensagem de outra sessão (${umaLinha(r.origem, 80)})${r.pedidoId ? ` com a marca do pedido ${curto(r.pedidoId)}` : ''}`
+    : `resposta do dono ao pedido ${r.pedidoId ? curto(r.pedidoId) : '?'}`
+  const linhas: LinhaDoMensageiro[] = [{ tipo: TIPO_DA_RECEBIDA[r.estado], chave: k('estado'),
+    texto: umaLinha(`${GLIFO_DA_RECEBIDA[r.estado]} ${quem} · ${ROTULO_DA_RECEBIDA[r.estado]} · ${idade(agora - r.em)}`, 300) }]
+  if (r.motivo) {
+    const motivo = r.estado === 'consumida' ? `${motivoLegivel(r.motivo)} · ${codigoDoMotivo(r.motivo)}` : r.motivo
+    linhas.push({ tipo: 'dim', chave: k('motivo'), texto: `  ${umaLinha(motivo, 200)}` })
+  }
+  return linhas
+}
+
+/**
+ * As linhas do painel na sessao de fase: o que chegou de outras sessoes, o mais novo primeiro. Sem botao: o estado so
+ * muda quando algo chega, e o painel se redesenha sozinho. O texto de nenhuma mensagem aparece aqui.
+ */
+export function linhasDaFase(fase: MensageiroFase, agora: number): LinhaDoMensageiro[] {
+  const linhas: LinhaDoMensageiro[] = [
+    { tipo: 'secao', chave: 'titulo', texto: 'Mensageiro de Sessões' },
+    { tipo: 'dim', chave: 'o-que-faz', texto: `Nesta sessão de fase${fase.thread ? ` da ${fase.thread}` : ''}, só entra na conversa a resposta do dono que o núcleo conferiu; o resto que chega de outra sessão é consumido.` },
+  ]
+  if (fase.erro) linhas.push({ tipo: 'falha', chave: 'erro', texto: `× ${umaLinha(fase.erro, 200)}` })
+  linhas.push({ tipo: 'secao', chave: 'secao-recebidas', texto: 'O que chegou de outras sessões' })
+  if (!fase.recebidas.length) linhas.push({ tipo: 'dim', chave: 'sem-recebidas', texto: '  nada chegou de outra sessão' })
+  const recebidas = fase.recebidas.map((r, i) => ({ r, i })).reverse()
+  for (const { r, i } of recebidas) linhas.push(...linhasDaRecebida(r, i, agora))
+  linhas.push({ tipo: 'dim', chave: 'limite', texto: 'A resposta do dono informa esta sessão; ação que só o dono aprova continua pedindo o dono.' })
+  return linhas
+}
+
+/**
+ * O que esta inteiro dentro da janela de rolagem do painel: so isso conta como mostrado ao dono (M5). Toda linha do
+ * painel trunca numa linha da tela, e a do titulo divide a linha com o botao.
+ */
+export function mostradosVisiveis(linhas: readonly LinhaDoMensageiro[], janela: { offset: number; bodyRows: number } | undefined): MensageiroMostrado[] {
+  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 Gestos = { atualizar?: () => void }
+
+/** A arvore do painel com os elementos que a superficie resolveu. */
+export function desenharPainel(el: { Box: any; Text: any; Button: any }, linhas: readonly LinhaDoMensageiro[], gestos: Gestos) {
+  const { Box, Text, Button } = el
+  return (
+    <Box flexDirection="column">
+      {linhas.map(l => {
+        if (l.tipo === 'titulo') {
+          return (
+            <Box key="titulo" flexDirection="row">
+              <Text key="titulo-texto" bold wrap="truncate">{l.texto}</Text>
+              <Button key="atualizar" label="Atualizar" onPress={() => gestos.atualizar?.()} />
+            </Box>
+          )
+        }
+        if (l.tipo === 'secao') return <Text key={l.chave} bold wrap="truncate">{l.texto}</Text>
+        if (l.tipo === 'falha') return <Text key={l.chave} color="error" wrap="truncate">{l.texto}</Text>
+        if (l.tipo === 'feito') return <Text key={l.chave} color="success" 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>
+  )
+}