@orkastery/cli 0.5.6 → 0.6.1

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>
+  )
+}

package/adapters/claude-code/mods/ork-mensageiro/hooks/recepcao.ts

@@ -0,0 +1,256 @@
+// O lado da sessao de fase do Mensageiro de Sessoes (RM-059, fatia F9, T9.3), em funcoes puras. Na sessao de fase,
+// a mensagem que chega de outra sessao so entra na conversa do modelo depois que o nucleo confirma, pela
+// `ork_session_inbox` do servidor preso ao despacho, que ela e a resposta do dono reservada para esta sessao, com o
+// mesmo texto. O nome do plugin remetente (`origin.plugin`) e so o que o remetente declara: entra no registro, nunca
+// na decisao. Nada daqui guarda o texto da mensagem no estado (D12 da thread ork-rm059mensag). So importa tipos e o
+// modulo puro da caixa.
+import type { MensageiroEstadoDaRecebida, MensageiroFase, MensageiroRecebida } from '../types'
+import { CONTRATO_DA_ENTREGA, umaLinha } from './caixa'
+
+/** A ferramenta da conferencia no receptor, so no servidor preso ao despacho (T9.1). */
+export const FERRAMENTA_DA_CONFERENCIA = 'ork_session_inbox'
+/** A maior mensagem que vai a conferencia, o mesmo teto do nucleo (`LIMITE_DA_MENSAGEM` de `entrega-por-mod.ts`). */
+export const LIMITE_DA_MENSAGEM = 8192
+export const MAXIMO_DE_RECEBIDAS = 30
+/** O recibo que nao foi gravado volta nestas esperas; depois delas, a linha fica sem recibo. */
+export const ESPERAS_DA_CONFIRMACAO_MS = [5000, 30000, 120000]
+/**
+ * D21: o prazo que a conferencia leva ao nucleo (`ate`), bem antes do teto de 20 s da chamada no mod. O nucleo nao
+ * reserva depois dele: a conferencia atrasada nao deixa reserva sem ninguem para confirma-la.
+ */
+export const PRAZO_DA_CONFERENCIA_MS = 15000
+export const FASE_VAZIA: MensageiroFase = { thread: null, recebidas: [], erro: null }
+
+const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/
+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)
+const curto = (id: string) => id.slice(0, 8)
+
+/**
+ * As origens que nao trazem texto de outra sessao (G4, D22 da thread ork-rm059mensag): o Remote Control do dono
+ * (`bridge`), a notificacao de tarefa, o agendamento e o canal. A lista e fechada: tipo novo ou desconhecido conta
+ * como outra sessao ate entrar aqui.
+ */
+const EXTERNAS = ['bridge', 'task-notification', 'scheduled-trigger', 'slack-ping']
+/** Entre a conversa principal e os agentes desta sessao: so com o `agentId` do agente de destino. */
+const ENTRE_AGENTES = ['peer', 'coordinator']
+
+export type ClasseDaOrigem = 'outra-sessao' | 'da-propria-sessao' | 'externa'
+
+/**
+ * Classifica uma entrega que chegou: externa (a lista fechada acima), da propria sessao (para um agente desta sessao,
+ * ou de teammate que o harness verificou) ou de outra sessao, que so entra confirmada pelo nucleo. Conta como outra
+ * sessao o mailbox que o harness nao verificou (`isVerified` diferente de `true`, D17: o despacho roda os teammates no
+ * mesmo processo, e ali a entrada sem verificacao e uma que nenhum membro mandou), `peer` e `coordinator` sem agente
+ * desta sessao como destino, inclusive a mensagem de um agente desta sessao para a conversa principal, que chega sem
+ * `agentId` e nao se distingue da de outra sessao (D22), e todo tipo desconhecido ou origem malformada.
+ */
+export function classificarOrigem(origem: unknown, agentId: unknown): ClasseDaOrigem {
+  const o = objeto(origem) ? origem : {}
+  if ('teammate' in o || 'isVerified' in o) return o.isVerified === true ? 'da-propria-sessao' : 'outra-sessao'
+  const kind = typeof o.kind === 'string' ? o.kind : ''
+  if (EXTERNAS.includes(kind)) return 'externa'
+  if (ENTRE_AGENTES.includes(kind) && typeof agentId === 'string' && agentId !== '') return 'da-propria-sessao'
+  return 'outra-sessao'
+}
+
+/** A origem para o registro e o painel, numa linha curta: o tipo e o plugin que o remetente diz ser. */
+export function nomeDaOrigem(origem: unknown): string {
+  const o = objeto(origem) ? origem : {}
+  const kind = typeof o.kind === 'string' && /^[a-z-]{1,40}$/.test(o.kind) ? o.kind : 'desconhecida'
+  const plugin = typeof o.plugin === 'string' && /^[a-zA-Z0-9._-]{1,64}$/.test(o.plugin) ? `, plugin declarado ${o.plugin}` : ''
+  return `${kind}${'teammate' in o || 'isVerified' in o ? ' do mailbox' : ''}${plugin}`
+}
+
+/** O cabecalho que o nucleo compoe (`cabecalhoDaEntrega` de `entrega-por-mod.ts`), conferido pelo teste do nucleo. */
+export function cabecalhoDaEntrega(pedidoId: string, envioId: string): string {
+  return `[${CONTRATO_DA_ENTREGA} pedido=${pedidoId} entrega=${envioId}] Resposta do dono à pergunta deste turno, conferida pelo núcleo do Orkastery:`
+}
+
+/** O rotulo visual da entrega confirmada (`rotuloDaEntrega` do nucleo). */
+export function rotuloDaEntrega(pedidoId: string): string {
+  return `Resposta do dono ao pedido ${curto(pedidoId)}, conferida pelo núcleo`
+}
+
+/** A mensagem traz a marca da entrega do nucleo: so essa vai a conferencia (D13); quem decide e o nucleo. */
+export function temMarca(texto: unknown): boolean {
+  return typeof texto === 'string' && texto.length <= LIMITE_DA_MENSAGEM && texto.includes(`[${CONTRATO_DA_ENTREGA} pedido=`)
+}
+
+/** Os ids que a marca diz ter, sem conferir nada: so para o registro de quem chegou. */
+export function idsDaMarca(texto: unknown): { pedidoId: string | null; envioId: string | null } {
+  const m = typeof texto === 'string' ? /\[ork\.session-delivery\/v1 pedido=([0-9a-f-]{36}) entrega=([0-9a-f-]{36})\]/.exec(texto) : null
+  return { pedidoId: m && uuid(m[1]) ? m[1] : null, envioId: m && uuid(m[2]) ? m[2] : null }
+}
+
+/** O argumento do `conferir`, com o prazo (`ate`) contado do relogio da sessao. */
+export function argsDaConferencia(thread: string, texto: string, agora: number): Record<string, unknown> {
+  return { threadId: thread, operacao: 'conferir', texto, ate: new Date(agora + PRAZO_DA_CONFERENCIA_MS).toISOString() }
+}
+
+export function argsDaConfirmacao(thread: string, envioId: string, texto: string): Record<string, unknown> {
+  return { threadId: thread, operacao: 'confirmar', envioId, texto }
+}
+
+export type Conferencia = { confirmada: true; pedidoId: string; envioId: string } | { confirmada: false; motivo: string }
+
+/** A resposta do `conferir`: so `confirmada: true` com os dois ids passa; o resto e recusa, com o motivo do nucleo. */
+export function lerConferencia(dados: unknown): Conferencia {
+  if (objeto(dados) && dados.confirmada === true && uuid(dados.pedidoId) && uuid(dados.envioId)) {
+    return { confirmada: true, pedidoId: dados.pedidoId, envioId: dados.envioId }
+  }
+  const motivo = objeto(dados) && dados.confirmada === false && typeof dados.motivo === 'string' && /^entrega\.[a-z-]{1,40}$/.test(dados.motivo)
+    ? dados.motivo : 'entrega.fora-do-contrato'
+  return { confirmada: false, motivo }
+}
+
+/** A resposta do `confirmar`: entregue com o recibo; a recusa do nucleo e definitiva; o resto volta a tentar. */
+export function lerConfirmacao(dados: unknown): { ok: boolean; definitiva: boolean; motivo: string | null } {
+  if (objeto(dados) && dados.ok === true && dados.estado === 'entregue') return { ok: true, definitiva: true, motivo: null }
+  const recusada = objeto(dados) && dados.estado === 'recusada'
+  const motivo = objeto(dados) && typeof dados.motivo === 'string' ? dados.motivo
+    : objeto(dados) && typeof dados.estado === 'string' ? `o núcleo respondeu ${dados.estado}` : 'a confirmação respondeu fora do contrato'
+  return { ok: false, definitiva: recusada, motivo: umaLinha(motivo, 120) }
+}
+
+/** O que cada motivo quer dizer, para o painel e para o registro. Os do nucleo sao os de `MotivoDoReceptor`. */
+export const MOTIVO_LEGIVEL: Record<string, string> = {
+  'entrega.sem-marca': 'sem a marca da entrega do núcleo',
+  'entrega.grande': 'maior que qualquer entrega do núcleo',
+  'entrega.formato': 'fora do formato da entrega',
+  'entrega.despacho': 'o despacho desta sessão não confere no núcleo',
+  'entrega.desconhecida': 'o núcleo não tem essa entrega',
+  'entrega.outra-sessao': 'a entrega é de outra sessão',
+  'entrega.texto-diferente': 'o texto não é o da resposta do dono',
+  'entrega.respondida': 'o pedido já foi respondido',
+  'entrega.reservada': 'cópia de uma entrega que já entrou',
+  'entrega.turno-mudou': 'a sessão já saiu do turno do pedido',
+  'entrega.sem-reserva': 'a entrega não foi reservada por esta sessão',
+  'entrega.prazo': 'a conferência chegou ao núcleo depois do prazo',
+  'entrega.fora-do-contrato': 'a conferência respondeu fora do contrato',
+  'entrega.conferencia-falhou': 'a conferência no núcleo falhou',
+  'entrega.sem-ponte': 'a ponte do Orkastery não carregou nesta sessão',
+  'entrega.sem-papel': 'a ponte não disse o papel desta sessão',
+}
+
+/** O codigo de um motivo (`entrega.x`, ou `entrega.x: detalhe`). */
+export function codigoDoMotivo(motivo: string): string {
+  const i = motivo.indexOf(': ')
+  return i < 0 ? motivo : motivo.slice(0, i)
+}
+
+/** O motivo como o dono le, com o detalhe entre parenteses quando ha. */
+export function motivoLegivel(motivo: string): string {
+  const codigo = codigoDoMotivo(motivo)
+  const base = MOTIVO_LEGIVEL[codigo]
+  if (!base) return umaLinha(motivo, 120)
+  return codigo === motivo ? base : `${base} (${umaLinha(motivo.slice(codigo.length + 2), 120)})`
+}
+
+/** O motivo que vai ao `{ consumed }`: o Claude Code o registra com o nome do plugin. */
+export function motivoDoConsumo(motivo: string): string {
+  const codigo = codigoDoMotivo(motivo)
+  return `mensagem de outra sessão sem entrega confirmada pelo núcleo do Orkastery (${MOTIVO_LEGIVEL[codigo] ?? 'motivo desconhecido'}; ${umaLinha(codigo, 60)})`
+}
+
+/** A linha do transcript (dim, fora do modelo) para o que nao entrou na conversa como devia. */
+export function registroDaRecebida(r: MensageiroRecebida): string | null {
+  const pedido = r.pedidoId ? curto(r.pedidoId) : null
+  if (r.estado === 'consumida') return `Mensageiro de Sessões: mensagem de outra sessão (${r.origem}) consumida antes do modelo: ${motivoLegivel(r.motivo ?? '')}.`
+  if (r.estado === 'nao-entrou') return `Mensageiro de Sessões: a resposta do dono ao pedido ${pedido}, conferida pelo núcleo, não entrou na conversa: ${r.motivo ?? 'consumida abaixo do Mensageiro'}.`
+  if (r.estado === 'sem-recibo') return `Mensageiro de Sessões: a resposta do dono ao pedido ${pedido} entrou na conversa, mas o recibo não foi gravado no núcleo (${r.motivo ?? 'sem motivo'}); a entrega segue incerta para o dono.`
+  return null
+}
+
+/** O remetente do envelope fixo com que o receptor entrega a resposta conferida ao modelo (D23). */
+export const REMETENTE_DO_MENSAGEIRO = 'ork-mensageiro'
+
+/**
+ * O texto que a sessao de fase le (D23): a mensagem que o nucleo conferiu, no envelope fixo do Mensageiro. O envelope
+ * que chegou sai inteiro, com os rotulos que o remetente escolhe (o nome da sessao, o plugin, o endereco), e o
+ * enquadramento de mensagem de outra sessao fica. O `from-plugin` vai no proprio envelope: sem ele, o motor
+ * acrescentaria o plugin que o remetente declara na apresentacao. Do remetente, nada passa deste gancho; o anexo de
+ * arquivo do `SendFile`, que o motor poe no envelope depois dos ganchos, e limite dito no guia.
+ */
+export function textoParaOModelo(mensagem: string): string {
+  return `<cross-session-message from="${REMETENTE_DO_MENSAGEIRO}" from-plugin="${REMETENTE_DO_MENSAGEIRO}">\n${mensagem}\n</cross-session-message>`
+}
+
+export type DecisaoNaFalha = { acao: 'passa' } | { acao: 'conferida'; texto: string } | { acao: 'consome' }
+
+/**
+ * O que o `.catch` do receptor faz quando o gancho falha antes de chamar `next` (D18): a entrega que nao e de outra
+ * sessao passa como chegou, como na sessao que nao e de fase; a de outra sessao que o nucleo ja confirmou e reservou
+ * (em voo) segue no envelope do Mensageiro, como no caminho normal; o resto e consumido. Papel desconhecido conta como
+ * fase.
+ */
+export function decisaoNaFalha(f: { origem: unknown; agentId: unknown; texto: unknown; papel: string | null;
+  emVoo: ReadonlyMap<string, string> }): DecisaoNaFalha {
+  if (classificarOrigem(f.origem, f.agentId) !== 'outra-sessao') return { acao: 'passa' }
+  if (f.papel !== null && f.papel !== 'fase') return { acao: 'passa' }
+  const conferida = typeof f.texto === 'string' ? f.emVoo.get(f.texto) : undefined
+  return conferida !== undefined ? { acao: 'conferida', texto: conferida } : { acao: 'consome' }
+}
+
+/** Um valor de atributo do envelope do motor: uma linha so, sem aspas nem sinal de tag (o mesmo do nucleo). */
+const VALOR_DE_LINHA = '[^"<>\\n\\r\\v\\f\\u0085\\u2028\\u2029]{1,200}'
+/** O envelope do Claude Code na forma que o motor escreve, o mesmo que o nucleo aceita (`entrega-por-mod.ts`). */
+const ENVELOPE_DO_MOTOR = new RegExp('^<cross-session-message' +
+  '(?: from="[^"<>\\s]{1,300}")?' +
+  '(?: from-session="[A-Za-z0-9_-]{1,80}")?' +
+  '(?: hop-chain="[0-9a-f]{24}(?:,[0-9a-f]{24}){0,31}")?' +
+  `(?: from-name="${VALOR_DE_LINHA}")?` +
+  '(?: from-mode="[A-Za-z-]{1,40}")?' +
+  `(?: from-plugin="${VALOR_DE_LINHA}")?` +
+  '>\\n([\\s\\S]*)\\n</cross-session-message>$')
+
+/** A mensagem sem o envelope do motor, como a linha da conversa a mostra; o texto como veio quando nao ha envelope. */
+export function mensagemSemEnvelope(texto: string): string | null {
+  const t = texto.replace(/\r\n?/g, '\n')
+  if (!t.startsWith('<')) return t
+  const m = ENVELOPE_DO_MOTOR.exec(t)
+  return m ? m[1] : null
+}
+
+/**
+ * A impressao do texto de uma mensagem (FNV-1a de 32 bits do texto normalizado, com o tamanho): so diz se a linha da
+ * conversa e a mensagem que o nucleo confirmou, sem guardar o texto (D12). Nao e prova: o que prova e a conferencia.
+ */
+export function impressaoDoTexto(texto: string): string {
+  const t = texto.replace(/\r\n?/g, '\n').replace(/\s+$/, '')
+  let h = 0x811c9dc5
+  for (let i = 0; i < t.length; i++) {
+    h ^= t.charCodeAt(i)
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return `${t.length.toString(16)}-${h.toString(16).padStart(8, '0')}`
+}
+
+/** Guarda o que chegou, o mais novo por ultimo e com teto, sem o texto da mensagem. */
+export function comRecebida(fase: MensageiroFase, r: MensageiroRecebida): MensageiroFase {
+  return { ...fase, recebidas: [...fase.recebidas, r].slice(-MAXIMO_DE_RECEBIDAS) }
+}
+
+/** Muda a recebida de uma entrega confirmada (pelo `envioId`); sem ela, a fase fica como estava. */
+export function mudarRecebida(fase: MensageiroFase, envioId: string, estado: MensageiroEstadoDaRecebida, motivo: string | null, em: number): MensageiroFase {
+  if (!fase.recebidas.some(r => r.envioId === envioId && r.estado !== 'consumida')) return fase
+  return { ...fase, recebidas: fase.recebidas.map(r => (r.envioId === envioId && r.estado !== 'consumida' ? { ...r, estado, motivo, em } : r)) }
+}
+
+/** As entregas que o nucleo confirmou nesta sessao, com a impressao do texto: so a linha de uma delas ganha o rotulo. */
+export function confirmadasDaFase(fase: MensageiroFase | null | undefined): Map<string, string> {
+  return new Map((fase?.recebidas ?? []).flatMap(r =>
+    (r.envioId && r.impressao && r.estado !== 'consumida' && r.estado !== 'nao-entrou' ? [[r.envioId, r.impressao] as [string, string]] : [])))
+}
+
+/**
+ * O texto da linha da mensagem com o rotulo no lugar do cabecalho, so para a entrega que o nucleo confirmou nesta
+ * sessao e com o mesmo texto (a impressao); `null` deixa a linha como o Claude Code a desenha. So visual: o que fica
+ * guardado e o que o modelo le nao mudam.
+ */
+export function textoComRotulo(texto: unknown, confirmadas: ReadonlyMap<string, string>): string | null {
+  const { pedidoId, envioId } = idsDaMarca(texto)
+  if (typeof texto !== 'string' || !pedidoId || !envioId || confirmadas.get(envioId) !== impressaoDoTexto(texto)) return null
+  const cabecalho = `${cabecalhoDaEntrega(pedidoId, envioId)}\n`
+  return texto.startsWith(cabecalho) ? `${rotuloDaEntrega(pedidoId)}\n${texto.slice(cabecalho.length)}` : null
+}