@orkastery/cli 0.5.6 → 0.6.0

package/adapters/claude-code/mods/ork-ritual/hooks/replay.tsx

@@ -0,0 +1,271 @@
+// O painel do Ritual do MASTER (RM-059, fatia F8, T8.2): a lista das entregas que esperam a nota do dono e o replay da
+// prova de uma delas, uma claim por vez, como o replay-theater percorre edicoes. Modulo puro: monta as linhas e a
+// arvore com os elementos que a superficie resolveu; o `$` fica no register.tsx. Estado sempre com rotulo e glifo,
+// nunca so cor; "espera sua nota" e o ponto de HITL do cartao; numero vem com o comando que o prova (Partitura).
+import type { RitualEntrega, RitualMostrado, RitualNota, RitualProva, RitualQuadro, RitualReserva } from '../types'
+import { pedeReserva } from './nota'
+import { JANELA_DIAS, numero, plural } from './ritual'
+
+/** Os botoes de uma entrega, na linha de acoes do cartao. */
+export type BotaoDoCartao = 'prova' | 'nota' | 'telegram'
+
+/** Uma linha do painel: o tipo decide o elemento; `mostrado` e o que o registro da ponte guarda (M5). */
+export type LinhaDoPainel = {
+  tipo: 'placar' | 'aviso' | 'feita' | 'vazio' | 'cabecalho' | 'situacao' | 'indice' | 'postmortem' | 'acoes' | 'nota' | 'reserva'
+    | 'prova-placar' | 'claim' | 'alegacao' | 'comando' | 'navegacao'
+  texto: string
+  thread?: string
+  /** So na linha de acoes: os botoes que ela tem, na ordem. */
+  botoes?: BotaoDoCartao[]
+  mostrado?: RitualMostrado
+}
+
+/** Os rotulos dos botoes do cartao. */
+export const ROTULO_DO_BOTAO: Readonly<Record<BotaoDoCartao, string>> = { prova: 'Ver a prova', nota: 'Dar a nota', telegram: 'Pelo Telegram' }
+
+/** O glifo e o rotulo de cada estado de claim que o nucleo registra. */
+export const ESTADO_DA_CLAIM: Readonly<Record<string, { glifo: string; rotulo: string }>> = {
+  verificado: { glifo: '✓', rotulo: 'verificada' },
+  reprovado: { glifo: '×', rotulo: 'reprovada' },
+  pendente: { glifo: '·', rotulo: 'pendente' },
+  'nao-verificavel': { glifo: '?', rotulo: 'não verificável' },
+}
+
+/** Quanto tempo faz a leitura, em palavras curtas. */
+export function haQuanto(desde: number | null, agora: number): string {
+  if (desde === null) return 'ainda não lido'
+  const s = Math.max(0, Math.round((agora - desde) / 1000))
+  if (s < 60) return `lido há ${s} s`
+  const min = Math.round(s / 60)
+  return min < 60 ? `lido há ${min} min` : `lido há ${Math.round(min / 60)} h`
+}
+
+/** A situacao da nota na entrega, em uma linha. */
+export function situacaoDaEntrega(e: RitualEntrega): string {
+  if (e.status === 'recorded') return `aceita por omissão${e.score === null ? '' : ` com ${e.score}/5`}; a sua nota sobrescreve`
+  if (e.status === 'ratificacao-pendente') return 'proposta da fábrica esperando a sua nota'
+  return 'sem nota: sem a sua, o MASTER fecha por omissão'
+}
+
+/** O cartao de uma entrega: cabecalho, situacao, indice e POSTMORTEM. */
+export function linhasDaEntrega(e: RitualEntrega): LinhaDoPainel[] {
+  const quando = e.entregueEmLocal ?? e.entregueEm
+  const merge = e.merge ? ` · merge ${e.merge.slice(0, 8)}` : e.artefato ? ` · artefato ${e.artefato}` : ''
+  const indice = e.indice === null ? 'índice derivado do ledger: lacuna (ork master)'
+    : `índice derivado do ledger: ${numero(e.indice)} de 5 (${e.parcelas || 'sem desconto'}) · ork master`
+  const reprovacoes = plural(e.reprovacoes, 'reprovação tipada', 'reprovações tipadas')
+  return [
+    { tipo: 'cabecalho', thread: e.thread, texto: `● espera sua nota · ${e.thread} · entregue ${quando}${merge}` },
+    { tipo: 'situacao', thread: e.thread, texto: `  ${situacaoDaEntrega(e)}` },
+    { tipo: 'indice', thread: e.thread, texto: `  ${indice}`,
+      mostrado: { chave: `nota:${e.thread}`, thread: e.thread,
+        texto: `${e.thread}: entregue, espera sua nota${e.indice === null ? '' : ` (índice ${numero(e.indice)} de 5)`}` } },
+    // Na proposta, as classes sao as que a fabrica propos; a nota do dono grava as que o nucleo infere dos gates, como
+    // no terminal e no Telegram (D14).
+    { tipo: 'postmortem', thread: e.thread, texto: e.classes
+      ? `  POSTMORTEM${e.status === 'ratificacao-pendente' ? ' da proposta' : ''}: classes ${e.classes} · ${reprovacoes}`
+      : `  POSTMORTEM: nasce no fechamento · ${reprovacoes}` },
+  ]
+}
+
+/**
+ * A linha de acoes e o resultado do "Dar a nota" e da reserva de uma entrega (T8.3). O "Dar a nota" some com o dialogo
+ * aberto e com a nota ja registrada; a reserva pelo Telegram so aparece quando o dialogo nao serviu (D7).
+ */
+export function linhasDaNota(thread: string, opcoes: { comProva: boolean; nota?: RitualNota; reserva?: RitualReserva }): LinhaDoPainel[] {
+  const { nota, reserva } = opcoes
+  const botoes: BotaoDoCartao[] = []
+  if (opcoes.comProva) botoes.push('prova')
+  if (!nota || !['abrindo', 'registrada', 'repetida'].includes(nota.estado)) botoes.push('nota')
+  if (pedeReserva(nota) && reserva?.estado !== 'pedindo') botoes.push('telegram')
+  const saida: LinhaDoPainel[] = []
+  if (botoes.length) saida.push({ tipo: 'acoes', thread, botoes, texto: botoes.map(b => ROTULO_DO_BOTAO[b]).join(' | ') })
+  if (nota) saida.push({ tipo: 'nota', thread, texto: `  ${nota.estado === 'abrindo' ? 'diálogo da nota aberto no Claude Code: responda lá' : nota.texto}` })
+  if (reserva) {
+    saida.push({ tipo: 'reserva', thread, texto: `  ${reserva.estado === 'pedindo' ? 'pedindo o código ao núcleo...' : reserva.texto}`,
+      ...(reserva.estado === 'pronta' && reserva.codigo
+        ? { mostrado: { chave: `nota:${thread}`, thread, texto: `${thread}: pelo Telegram, responda ${reserva.codigo} <0 a 5> <porquê>` } } : {}) })
+  }
+  return saida
+}
+
+/** As notas desta sessao que ja sairam da lista (registradas ou ja dadas), as mais novas primeiro, no maximo tres. */
+export function notasFeitas(q: RitualQuadro, notas: Readonly<Record<string, RitualNota>>): LinhaDoPainel[] {
+  const naLista = new Set(q.entregas.map(e => e.thread))
+  return Object.entries(notas).filter(([t, n]) => (n.estado === 'registrada' || n.estado === 'repetida') && !naLista.has(t))
+    .sort((a, b) => b[1].em - a[1].em).slice(0, 3)
+    .map(([thread, n]) => ({ tipo: 'feita' as const, thread, texto: `✓ ${n.texto}` }))
+}
+
+/** As linhas do replay: a claim do passo, com estado, arquivo, alegacao e comandos; nunca a saida do comando (D6). */
+export function linhasDaProva(foco: string, prova: RitualProva | null, passo: number): LinhaDoPainel[] {
+  if (!prova || prova.thread !== foco || (prova.lidoEm === null && !prova.erro)) return [{ tipo: 'vazio', thread: foco, texto: 'lendo as claims no núcleo...' }]
+  const saida: LinhaDoPainel[] = []
+  if (prova.erro) saida.push({ tipo: 'aviso', thread: foco, texto: `as claims não vieram: ${prova.erro}` })
+  if (!prova.claims.length) {
+    if (!prova.erro) saida.push({ tipo: 'vazio', thread: foco, texto: `Nenhuma claim ativa registrada na ${foco}.` })
+    return saida
+  }
+  const i = Math.min(Math.max(0, passo), prova.claims.length - 1)
+  const c = prova.claims[i]!
+  const estado = ESTADO_DA_CLAIM[c.estado] ?? { glifo: '?', rotulo: c.estado }
+  const retiradas = prova.retiradas ? ` · ${plural(prova.retiradas, 'retirada fora', 'retiradas fora')}` : ''
+  saida.push({ tipo: 'prova-placar', thread: foco, texto: `  claim ${i + 1} de ${prova.claims.length}${retiradas} · ork claims list ${foco}` })
+  saida.push({ tipo: 'claim', thread: foco, texto: `  ${estado.glifo} ${c.id} · ${estado.rotulo}${c.arquivo ? ` · ${c.arquivo}` : ''}` })
+  if (c.alegacao) saida.push({ tipo: 'alegacao', thread: foco, texto: `  ${c.alegacao}` })
+  for (const comando of c.comandos) saida.push({ tipo: 'comando', thread: foco, texto: `  $ ${comando}` })
+  if (!c.comandos.length) saida.push({ tipo: 'comando', thread: foco, texto: '  sem comando registrado' })
+  saida.push({ tipo: 'navegacao', thread: foco, texto: `${i > 0 ? 'anterior' : ''}|${i < prova.claims.length - 1 ? 'proxima' : ''}` })
+  return saida
+}
+
+/**
+ * As linhas do painel, na ordem do desenho. Sem foco: o placar, os avisos e um cartao por entrega com "Ver a prova".
+ * Com foco (`/nota <thread>` ou "Ver a prova"): o placar do replay, o cartao da thread e a claim do passo.
+ */
+export function linhasDoPainel(q: RitualQuadro, opcoes: { agora: number; foco?: string | null; prova?: RitualProva | null; passo?: number;
+  notas?: Readonly<Record<string, RitualNota>>; reservas?: Readonly<Record<string, RitualReserva>> }): LinhaDoPainel[] {
+  const saida: LinhaDoPainel[] = []
+  const foco = opcoes.foco ?? null
+  const notas = opcoes.notas ?? {}
+  const reservas = opcoes.reservas ?? {}
+  const quantas = q.semLeitura && !q.entregas.length ? `o retrato não leu ${plural(q.semLeitura, 'thread', 'threads')}`
+    : `${q.semLeitura ? 'pelo menos ' : ''}${plural(q.entregas.length, 'entrega espera', 'entregas esperam')} a sua nota`
+  saida.push({ tipo: 'placar', texto: foco ? `Ritual do MASTER · prova da ${foco}` : `Ritual do MASTER · ${quantas} · ${haQuanto(q.lidoEm, opcoes.agora)}` })
+  if (q.erro) saida.push({ tipo: 'aviso', texto: `a última leitura falhou: ${q.erro}` })
+  for (const aviso of q.avisos) saida.push({ tipo: 'aviso', texto: aviso })
+  saida.push(...notasFeitas(q, notas))
+  if (foco) {
+    const e = q.entregas.find(x => x.thread === foco)
+    if (e) saida.push(...linhasDaEntrega(e), ...linhasDaNota(foco, { comProva: false, nota: notas[foco], reserva: reservas[foco] }))
+    else if (q.lidoEm !== null) saida.push({ tipo: 'aviso', thread: foco, texto: `a ${foco} não está entre as entregas dos últimos ${JANELA_DIAS} dias que esperam a sua nota` })
+    saida.push(...linhasDaProva(foco, opcoes.prova ?? null, opcoes.passo ?? 0))
+    return saida
+  }
+  if (q.foraDaJanela) {
+    saida.push({ tipo: 'aviso', texto: `${plural(q.foraDaJanela, 'entrega sem a sua nota ficou', 'entregas sem a sua nota ficaram')} fora da janela de ${JANELA_DIAS} dias (ork master)` })
+  }
+  if (!q.entregas.length) {
+    saida.push({ tipo: 'vazio', texto: q.lidoEm === null ? 'lendo as entregas no núcleo...'
+      : q.semLeitura ? `Nenhuma das entregas que o retrato leu espera a sua nota nos últimos ${JANELA_DIAS} dias; ork master lista as das threads que ele não leu.`
+        : `Nada espera a sua nota nos últimos ${JANELA_DIAS} dias.` })
+    return saida
+  }
+  for (const e of q.entregas) {
+    saida.push(...linhasDaEntrega(e), ...linhasDaNota(e.thread, { comProva: true, nota: notas[e.thread], reserva: reservas[e.thread] }))
+  }
+  return saida
+}
+
+/**
+ * As linhas da tela que um texto com `wrap="wrap"` ocupa em `colunas` celulas: quebra por palavra, e a palavra maior que
+ * a linha quebra no meio. A `folga` tira colunas da conta: com ela a estimativa sobra.
+ */
+export function linhasDaTela(texto: string, colunas: number | undefined, folga = 1): number {
+  if (typeof colunas !== 'number' || !(colunas > folga)) return 1
+  const largura = colunas - folga
+  let linhas = 1
+  let usadas = 0
+  texto.split(' ').forEach((palavra, i) => {
+    let tamanho = Array.from(palavra).length
+    const espaco = i === 0 ? 0 : 1
+    if (usadas + espaco + tamanho <= largura) {
+      usadas += espaco + tamanho
+      return
+    }
+    if (usadas > 0) {
+      linhas++
+      usadas = 0
+    }
+    while (tamanho > largura) {
+      linhas++
+      tamanho -= largura
+    }
+    usadas = tamanho
+  })
+  return linhas
+}
+
+/** A altura de uma linha do painel na tela, sem e com a folga: so a alegacao quebra; as outras truncam numa so. */
+function alturasNaTela(l: { tipo?: string; texto?: string }, colunas: number | undefined): [number, number] {
+  if (l.tipo !== 'alegacao') return [1, 1]
+  return [linhasDaTela(l.texto ?? '', colunas, 0), linhasDaTela(l.texto ?? '', colunas, 1)]
+}
+
+/**
+ * O que esta inteiro dentro da janela de rolagem do painel: so isso conta como mostrado ao dono (M5). A linha que quebra
+ * tem o topo mais cedo (sem folga) e o mais tarde (com folga): ela so conta com os dois dentro da janela.
+ */
+export function mostradosVisiveis(linhas: ReadonlyArray<{ tipo?: string; texto?: string; mostrado?: RitualMostrado }>,
+  janela: { offset: number; bodyRows: number } | undefined, colunas?: number): RitualMostrado[] {
+  if (!janela || !(janela.bodyRows > 0)) return []
+  const fim = janela.offset + janela.bodyRows
+  const vistos: RitualMostrado[] = []
+  let cedo = 0
+  let tarde = 0
+  for (const l of linhas) {
+    const [menor, maior] = alturasNaTela(l, colunas)
+    if (l.mostrado && cedo >= janela.offset && tarde + maior <= fim) vistos.push(l.mostrado)
+    cedo += menor
+    tarde += maior
+  }
+  return vistos
+}
+
+/** Os gestos do painel: reler, abrir e fechar o replay, andar entre as claims, pedir a nota e a reserva. */
+export type Gestos = {
+  atualizar?: () => void
+  verProva?: (thread: string) => void
+  voltar?: () => void
+  anterior?: () => void
+  proxima?: () => void
+  darNota?: (thread: string) => void
+  telegram?: (thread: string) => void
+}
+
+/**
+ * A arvore do painel com os elementos que a superficie resolveu (no register.tsx), uma linha da tela por elemento: so
+ * `Box`, `Text` e `Button`, no terminal e no desktop.
+ */
+export function desenharRitual(el: { Box: any; Text: any; Button: any }, linhas: readonly LinhaDoPainel[], opcoes: { foco?: string | null } & Gestos) {
+  const { Box, Text, Button } = el
+  return (
+    <Box flexDirection="column">
+      {linhas.map((l, i) => {
+        if (l.tipo === 'placar') {
+          return (
+            <Box key="placar" flexDirection="row">
+              <Text key="placar-texto" bold wrap="truncate">{l.texto}</Text>
+              {opcoes.foco ? <Button key="voltar" label="Voltar" onPress={() => opcoes.voltar?.()} /> : null}
+              <Button key="atualizar" label="Atualizar" onPress={() => opcoes.atualizar?.()} />
+            </Box>
+          )
+        }
+        if (l.tipo === 'cabecalho') return <Text key={`cabecalho:${l.thread}`} bold wrap="truncate">{l.texto}</Text>
+        if (l.tipo === 'acoes' && l.thread) {
+          const thread = l.thread
+          const gesto: Record<BotaoDoCartao, ((t: string) => void) | undefined> = { prova: opcoes.verProva, nota: opcoes.darNota, telegram: opcoes.telegram }
+          return (
+            <Box key={`acoes:${thread}`} flexDirection="row">
+              {(l.botoes ?? []).map(b => <Button key={`${b}:${thread}`} label={ROTULO_DO_BOTAO[b]} onPress={() => gesto[b]?.(thread)} />)}
+            </Box>
+          )
+        }
+        if (l.tipo === 'feita') return <Text key={`feita:${l.thread}`} wrap="truncate">{l.texto}</Text>
+        if (l.tipo === 'navegacao') {
+          const [anterior, proxima] = l.texto.split('|')
+          return (
+            <Box key="navegacao" flexDirection="row">
+              {anterior ? <Button key="anterior" label="Anterior" onPress={() => opcoes.anterior?.()} /> : null}
+              {proxima ? <Button key="proxima" label="Próxima" onPress={() => opcoes.proxima?.()} /> : null}
+            </Box>
+          )
+        }
+        if (l.tipo === 'claim') return <Text key="claim" bold wrap="truncate">{l.texto}</Text>
+        if (l.tipo === 'alegacao') return <Text key="alegacao" wrap="wrap">{l.texto}</Text>
+        if (l.tipo === 'aviso') return <Text key={`aviso:${i}`} color="warning" wrap="truncate">{l.texto}</Text>
+        return <Text key={`${l.tipo}:${l.thread ?? ''}:${i}`} dimColor={l.tipo !== 'comando'} wrap="truncate">{l.texto}</Text>
+      })}
+    </Box>
+  )
+}

package/adapters/claude-code/mods/ork-ritual/hooks/ritual.ts

@@ -0,0 +1,218 @@
+// O que o Ritual do MASTER le do nucleo (RM-059, fatia F8; ficha M8 do plano dos mods), em funcoes puras: as entregas
+// que esperam a nota do dono, saidas da secao `master` do retrato da ponte (D2 da thread ork-rm059ritual), a
+// linha da faixa e as claims do replay, saidas do `ork_claims_list`. Nada aqui le `.orkastery/` nem chama o `$`: as
+// chamadas ficam no register.tsx. So importa tipos.
+import type { RitualClaim, RitualEntrega, RitualNota, RitualQuadro } from '../types'
+
+/** D1: a entrega dos ultimos 7 dias sem nota humana (sem MASTER, com proposta ou aceita por omissao). */
+export const JANELA_DIAS = 7
+/** A secao `master` vem em paginas de ate 50 itens; mais que isso e retrato quebrado, nao fila. */
+export const TETO_DE_PAGINAS = 20
+/** O painel mostra no maximo isto; o resto vira aviso com a contagem. */
+export const TETO_DE_ENTREGAS = 40
+export const TETO_DE_TEXTO = 200
+export const SERVIDOR = 'orkastery'
+export const QUADRO_VAZIO: RitualQuadro = { entregas: [], lidoEm: null, erro: null, avisos: [], foraDaJanela: 0, semLeitura: 0 }
+
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+const DIA_MS = 86400000
+
+/** Uma linha so, sem caractere de controle e com teto. */
+export function umaLinha(v: unknown, teto = TETO_DE_TEXTO): 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('')
+}
+
+export function plural(n: number, um: string, varios: string): string {
+  return `${n} ${n === 1 ? um : varios}`
+}
+
+export function exigirThread(thread: unknown): string {
+  if (typeof thread !== 'string' || !ID_DE_THREAD.test(thread)) throw new Error('ork-ritual: id de thread invalido')
+  return thread
+}
+
+/** O numero com virgula, como o dono le: 3.75 vira "3,75". */
+export function numero(n: number): string {
+  return String(n).replace('.', ',')
+}
+
+/** O JSON do primeiro bloco de texto de uma resposta MCP; a resposta com erro vira erro com o motivo do nucleo. */
+export function jsonDoMcp(r: { content?: ReadonlyArray<{ type?: string; text?: string }>; isError?: boolean } | null | undefined): unknown {
+  const texto = (r?.content ?? []).find(c => c.type === 'text' && typeof c.text === 'string')?.text
+  if (!r || r.isError) {
+    let motivo = 'o núcleo respondeu com erro'
+    try {
+      const corpo = JSON.parse(texto ?? '') as { erro?: unknown }
+      if (typeof corpo.erro === 'string' && corpo.erro.trim()) motivo = umaLinha(corpo.erro)
+    } catch {
+      // Sem JSON no corpo do erro: fica o motivo generico.
+    }
+    throw new Error(motivo)
+  }
+  if (texto === undefined) throw new Error('o núcleo não devolveu texto')
+  return JSON.parse(texto)
+}
+
+/** Uma pagina da secao `master` do retrato: os itens, a proxima pagina e as lacunas. */
+export function paginaDoMaster(r: unknown): { itens: unknown[]; proxima: number | null; lacunas: string[] } {
+  const secao = (r as { retrato?: { sections?: { master?: unknown } } } | null)?.retrato?.sections?.master as
+    { items?: unknown; gaps?: unknown; coverage?: { nextOffset?: unknown } } | undefined
+  if (!secao || !Array.isArray(secao.items)) throw new Error('o retrato do núcleo não trouxe a seção master')
+  const proxima = secao.coverage?.nextOffset
+  return {
+    itens: secao.items as unknown[],
+    proxima: typeof proxima === 'number' && Number.isInteger(proxima) && proxima >= 0 ? proxima : null,
+    lacunas: Array.isArray(secao.gaps) ? (secao.gaps as unknown[]).filter((g): g is string => typeof g === 'string').map(g => umaLinha(g, 120)) : [],
+  }
+}
+
+const textoOuNulo = (v: unknown, teto = TETO_DE_TEXTO): string | null => (typeof v === 'string' && v.trim() ? umaLinha(v, teto) : null)
+const numeroOuNulo = (v: unknown): number | null => (typeof v === 'number' && Number.isFinite(v) ? v : null)
+
+/**
+ * A entrega de um item da secao `master`, quando ela espera a nota do dono: sem MASTER (`pending`), com proposta
+ * (`ratificacao-pendente`) ou aceita por omissao (`recorded` com regime `omissao`), entregue por `ship_done` ou por
+ * artefato. Nota humana registrada, item sem entrega ou fora do contrato devolvem null.
+ */
+export function entregaDoItem(item: unknown): RitualEntrega | null {
+  const i = (item ?? {}) as { id?: unknown; status?: unknown; facts?: Record<string, unknown> }
+  const m = typeof i.id === 'string' ? /^master:(.+)$/.exec(i.id) : null
+  const thread = m && ID_DE_THREAD.test(m[1] as string) ? m[1] as string : null
+  const f = i.facts ?? {}
+  if (!thread || (i.status !== 'pending' && i.status !== 'ratificacao-pendente' && i.status !== 'recorded')) return null
+  if (i.status === 'recorded' && f.regime !== 'omissao') return null
+  const entregueEm = typeof f.deliveredAt === 'string' && Number.isFinite(Date.parse(f.deliveredAt)) ? f.deliveredAt : null
+  if (!entregueEm) return null
+  return {
+    thread, status: i.status, regime: textoOuNulo(f.regime, 40), score: numeroOuNulo(f.score), indice: numeroOuNulo(f.index),
+    parcelas: textoOuNulo(f.indexDetail) ?? '', reprovacoes: numeroOuNulo(f.reprovals) ?? 0, classes: textoOuNulo(f.classes),
+    entregueEm, entregueEmLocal: textoOuNulo(f.deliveredAtLocal, 80),
+    merge: typeof f.deliveredSha === 'string' && /^[a-f0-9]{40}$/.test(f.deliveredSha) ? f.deliveredSha : null,
+    artefato: textoOuNulo(f.deliveredArtifact, 160),
+  }
+}
+
+/** As entregas da janela, a mais nova primeiro, com o teto do painel; e quantas ficaram fora da janela. */
+export function entregasDaJanela(itens: readonly unknown[], agora: number, dias = JANELA_DIAS): { entregas: RitualEntrega[]; fora: number; alemDoTeto: number } {
+  const todas = itens.map(entregaDoItem).filter((e): e is RitualEntrega => e !== null)
+  const desde = agora - dias * DIA_MS
+  const dentro = todas.filter(e => Date.parse(e.entregueEm) >= desde)
+    .sort((a, b) => Date.parse(b.entregueEm) - Date.parse(a.entregueEm) || (a.thread < b.thread ? -1 : 1))
+  return { entregas: dentro.slice(0, TETO_DE_ENTREGAS), fora: todas.length - dentro.length, alemDoTeto: Math.max(0, dentro.length - TETO_DE_ENTREGAS) }
+}
+
+/** A lacuna que nao falta nada: o corte da pagina por bytes (a proxima pagina traz o resto, e o Ritual le todas). */
+const SO_PAGINACAO = new Set(['maestro.page.byte_limit'])
+const OMITIDAS = /^maestro\.messages\.omitted:(\d+)$/
+const SEM_LEITURA = /^(?:ledger\.unavailable|master\.invalid):([a-zA-Z0-9][a-zA-Z0-9._-]{0,79})$/
+
+/**
+ * As lacunas da secao `master`, somadas de todas as paginas (cada pagina repete as da secao): as threads que o retrato
+ * nao leu (o ledger passou do teto de leitura do Maestro, ou o MASTER log nao vale), quantas lacunas o retrato omitiu
+ * alem das quatro que publica (na secao `master` elas sao por thread) e as outras. O corte da pagina por bytes nao
+ * falta nada.
+ */
+export function lacunasDoMaster(lacunas: readonly string[]): { semLeitura: string[]; omitidas: number; outras: string[] } {
+  const semLeitura: string[] = []
+  const outras: string[] = []
+  let omitidas = 0
+  for (const lacuna of new Set(lacunas)) {
+    if (SO_PAGINACAO.has(lacuna)) continue
+    const omitida = OMITIDAS.exec(lacuna)
+    if (omitida) {
+      omitidas = Math.max(omitidas, Number(omitida[1]))
+      continue
+    }
+    const thread = SEM_LEITURA.exec(lacuna)?.[1]
+    if (thread) {
+      if (!semLeitura.includes(thread)) semLeitura.push(thread)
+      continue
+    }
+    outras.push(lacuna)
+  }
+  return { semLeitura, omitidas, outras }
+}
+
+/** Quantas threads o retrato nao leu: as nomeadas nas lacunas e as omitidas. */
+export function threadsSemLeitura(lacunas: readonly string[]): number {
+  const { semLeitura, omitidas } = lacunasDoMaster(lacunas)
+  return semLeitura.length + omitidas
+}
+
+/** Os avisos da secao que veio incompleta, uma linha cada: as threads que o retrato nao leu e as outras lacunas. */
+export function avisosDasLacunas(lacunas: readonly string[]): string[] {
+  const { semLeitura, omitidas, outras } = lacunasDoMaster(lacunas)
+  const avisos: string[] = []
+  const sem = semLeitura.length + omitidas
+  if (sem) {
+    const nomes = semLeitura.slice(0, 3)
+    const resto = sem - nomes.length
+    const quais = nomes.length ? ` (${nomes.join(', ')}${resto > 0 ? ` e +${resto}` : ''})` : ''
+    avisos.push(`o retrato não leu ${plural(sem, 'thread', 'threads')}${quais}: a lista pode estar incompleta; ork master lista todas`)
+  }
+  if (outras.length) {
+    avisos.push(`o retrato do MASTER veio incompleto: ${plural(outras.length, 'lacuna', 'lacunas')} (${outras.slice(0, 3).join(', ')}${outras.length > 3 ? ', ...' : ''})`)
+  }
+  return avisos
+}
+
+/**
+ * A entrega cuja nota o nucleo registrou nesta sessao (ou que ja tinha nota humana) sai da lista na hora: a pagina que a
+ * ponte guarda por ate 60 s ainda pode lista-la. A entrega mais nova que a nota volta a esperar.
+ */
+export function semNotaDada(entregas: readonly RitualEntrega[], notas: Readonly<Record<string, RitualNota>>): RitualEntrega[] {
+  return entregas.filter(e => {
+    const n = notas[e.thread]
+    return !n || (n.estado !== 'registrada' && n.estado !== 'repetida') || n.em < Date.parse(e.entregueEm)
+  })
+}
+
+/**
+ * A linha da faixa: quantas entregas esperam a nota e quais; sem nenhuma (ou antes da primeira leitura), sem linha. Com
+ * thread que o retrato nao leu, a contagem e "pelo menos", e sem entrega visivel a linha aponta o `ork master`.
+ */
+export function textoDaFaixa(q: RitualQuadro): string | undefined {
+  if (q.lidoEm === null) return undefined
+  if (!q.entregas.length) {
+    return q.semLeitura ? `o retrato não leu ${plural(q.semLeitura, 'thread', 'threads')}: ork master lista as entregas que esperam a sua nota · /nota` : undefined
+  }
+  const nomes = q.entregas.slice(0, 3).map(e => e.thread)
+  const resto = q.entregas.length - nomes.length
+  return `${q.semLeitura ? 'pelo menos ' : ''}${plural(q.entregas.length, 'entrega espera', 'entregas esperam')} a sua nota: ${nomes.join(', ')}${resto > 0 ? ` e +${resto}` : ''} · /nota`
+}
+
+/** A thread do ledger que mudou (`classic.FileChanged`), quando o caminho e o ledger de uma thread. */
+export function threadDoLedger(caminho: unknown): string | null {
+  if (typeof caminho !== 'string') return null
+  const m = /\/\.orkastery\/threads\/([a-zA-Z0-9][a-zA-Z0-9._-]{0,79})\/ledger\.jsonl$/.exec(caminho)
+  return m ? m[1] as string : null
+}
+
+/** Os argumentos do `ork_claims_list`: so o id da thread. */
+export function argsDasClaims(thread: string): { threadId: string } {
+  return { threadId: exigirThread(thread) }
+}
+
+const numeroDoId = (id: string) => { const m = /^C(\d+)$/.exec(id); return m ? Number(m[1]) : Number.POSITIVE_INFINITY }
+
+/**
+ * As claims do `ork_claims_list` (o arquivo e so de acrescimo: a retirada e uma linha nova): o ultimo registro de cada
+ * id, as retiradas contadas a parte, na ordem dos ids. Registro fora do contrato fica de fora. Nunca a saida do comando:
+ * o nucleo nao a devolve aqui, e o replay nao a mostra (D6).
+ */
+export function claimsDaProva(resposta: unknown): { claims: RitualClaim[]; retiradas: number } {
+  if (!Array.isArray(resposta)) throw new Error('o ork_claims_list não devolveu a lista de claims')
+  const ultimas = new Map<string, RitualClaim>()
+  for (const bruto of resposta as unknown[]) {
+    const c = (bruto ?? {}) as Record<string, unknown>
+    if (typeof c.id !== 'string' || !/^C\d+$/.test(c.id) || typeof c.estado !== 'string') continue
+    ultimas.set(c.id, {
+      id: c.id, estado: umaLinha(c.estado, 40), arquivo: typeof c.arquivo === 'string' ? umaLinha(c.arquivo, 300) : '',
+      alegacao: typeof c.alegacao === 'string' ? umaLinha(c.alegacao, 1200) : '',
+      comandos: Array.isArray(c.verificar) ? (c.verificar as unknown[]).filter((v): v is string => typeof v === 'string').map(v => umaLinha(v, 600)) : [],
+    })
+  }
+  const todas = [...ultimas.values()].sort((a, b) => numeroDoId(a.id) - numeroDoId(b.id) || (a.id < b.id ? -1 : 1))
+  return { claims: todas.filter(c => c.estado !== 'retirada'), retiradas: todas.filter(c => c.estado === 'retirada').length }
+}

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

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

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

@@ -0,0 +1,106 @@
+// Contrato do estado do Ritual do MASTER (`ork-ritual`, RM-059, fatia F8; ficha M8 do plano dos mods). O motor exige
+// que cada chave de `$.state` do mod esteja declarada aqui, em `PluginState`. O Ritual nao acrescenta noun ao `$`: le as
+// entregas pelo retrato da `ork-ponte` (`$.ork.retrato`, secao `master`) e as claims pelo `ork_claims_list` do nucleo.
+// Nenhum campo guarda o porque do dono, e a nota so aparece como o texto do que o nucleo registrou: quem recebe e grava
+// a nota e o nucleo, pelo dialogo nativo do host. Sem import nem referencia.
+
+/** Uma entrega que espera a nota do dono, como a secao `master` do retrato do nucleo a da. */
+export type RitualEntrega = {
+  thread: string
+  /** `pending` (sem MASTER), `ratificacao-pendente` (proposta) ou `recorded` (so a aceita por omissao entra aqui). */
+  status: 'pending' | 'ratificacao-pendente' | 'recorded'
+  /** O regime do MASTER log: `omissao` na aceita por omissao; null sem MASTER log. */
+  regime: string | null
+  /** O score que a omissao gravou (o indice arredondado), quando ha. */
+  score: number | null
+  /** O indice derivado do ledger, de 0 a 5, e as parcelas que o descontaram. */
+  indice: number | null
+  parcelas: string
+  /** Os gates que barraram a thread (reprovacoes tipadas), fora os de ensaio. */
+  reprovacoes: number
+  /** As classes de falha do MASTER log (ou da proposta); null quando o POSTMORTEM ainda nao nasceu. */
+  classes: string | null
+  /** A entrega (`ship_done` ou artefato), em ISO e na hora local que o nucleo formatou, e o merge. */
+  entregueEm: string
+  entregueEmLocal: string | null
+  merge: string | null
+  /** O arquivo da entrega por artefato (a thread so de planejamento); ausente no quadro gravado antes deste campo. */
+  artefato?: string | null
+}
+
+/** A ultima leitura das entregas. */
+export type RitualQuadro = {
+  entregas: RitualEntrega[]
+  /** Quando foi lida (ms desde a epoca); null antes da primeira leitura. */
+  lidoEm: number | null
+  /** Por que a ultima leitura falhou, quando falhou (a anterior continua no quadro). */
+  erro: string | null
+  /** O que veio incompleto do retrato (lacunas da secao, paginas que sobraram). */
+  avisos: string[]
+  /** Quantas entregas sem nota humana ficaram fora da janela de dias. */
+  foraDaJanela: number
+  /**
+   * Quantas threads o retrato nao leu (o ledger passou do teto de leitura do Maestro, ou o MASTER log nao vale): com
+   * alguma, a contagem da faixa e "pelo menos". Ausente no quadro gravado antes deste campo.
+   */
+  semLeitura?: number
+}
+
+/** Uma claim no replay: o ultimo registro de cada id, como o `ork_claims_list` a da. Nunca a saida do comando. */
+export type RitualClaim = {
+  id: string
+  estado: string
+  arquivo: string
+  alegacao: string
+  comandos: string[]
+}
+
+/** A prova de uma thread no replay. */
+export type RitualProva = {
+  thread: string
+  /** As claims ativas, na ordem dos ids. */
+  claims: RitualClaim[]
+  retiradas: number
+  lidoEm: number | null
+  erro: string | null
+}
+
+/** O que o painel mostrou ao dono e o Telegram tambem diria: a chave junta o que e a mesma coisa (M5). */
+export type RitualMostrado = { chave: string; thread: string; texto: string }
+
+/**
+ * O "Dar a nota" de uma entrega (T8.3): o dialogo pedido ao nucleo e o que ele devolveu. So o estado e o texto do
+ * resultado; a nota e o porque que o dono deu ficam no nucleo, nunca aqui.
+ */
+export type RitualNota = {
+  estado: 'abrindo' | 'registrada' | 'repetida' | 'pendente' | 'sem-dialogo' | 'erro'
+  texto: string
+  em: number
+}
+
+/** A reserva pelo Telegram (T8.3): o pedido de nota do nucleo e o codigo que o dono responde por la. */
+export type RitualReserva = {
+  estado: 'pedindo' | 'pronta' | 'erro'
+  texto: string
+  codigo: string | null
+  em: number
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'ork-ritual': {
+      /** A ultima leitura das entregas. */
+      quadro: RitualQuadro
+      /** A thread no replay da prova, pedida por "Ver a prova" ou por `/nota <thread>`. */
+      foco: string | null
+      /** A claim que o replay mostra, a partir de 0. */
+      passo: number
+      /** As claims da thread em foco. */
+      prova: RitualProva | null
+      /** O "Dar a nota" de cada entrega, pelo id da thread. */
+      notas: Record<string, RitualNota>
+      /** A reserva pelo Telegram de cada entrega, pelo id da thread. */
+      reservas: Record<string, RitualReserva>
+    }
+  }
+}

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

@@ -165,7 +165,7 @@ export function textoDoDiario(r: SentinelaResumo, diario: readonly SentinelaEntr
   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.'
+    : r.presenca === 'minha' ? 'Sentinela conduzindo nesta máquina: o condutor externo cede o despacho e o retry, menos a retomada por cota.'
     : '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) {

package/adapters/codex/skills/ork/SKILL.md

@@ -44,6 +44,8 @@ O dono conversa sobre o objetivo; voce opera o nucleo `ork` e apresenta o result
 passo. Preserve o modo e as autorizacoes da thread. Se ja recebeu uma fase do Orkastery,
 execute essa fase no escopo recebido, sem redespachar a si mesmo.
 
+- Esperas: nunca dispare verify, build ou suite com `&` dentro do comando, porque o processo se perde e a sessao espera um aviso que nunca vem; rode o `ork verify` em primeiro plano, com `timeout` (ele espera a vez na fila de recursos pesados), ou use a execucao em segundo plano do host, que avisa quando termina; nunca espere com `pgrep -f` cujo padrao aparece no proprio comando, porque o laco acha a si mesmo e nao termina: espere pelo arquivo de saida com prazo, ou pelo PID guardado.
+
 Quando descobertas, prefira as ferramentas MCP vinculadas ao projeto pelo servidor:
 `ork_thread_status`, `ork_phase_list`, `ork_hitl_pending`, `ork_thread_new(nome, modo)`,
 `ork_phase_run(threadId, fase, prompt, runtime?, model?, effort?, dryRun?)`, `ork_observe(threadId)`