@orkastery/cli 0.5.1 → 0.5.6

package/adapters/claude-code/mods/ork-pista/hooks/acoes.ts

@@ -0,0 +1,71 @@
+// Os botoes da Pista (RM-059, fatia F7, T7.3; D6 da thread ork-rm059pista). Modulo puro: o botao que o nucleo declara
+// para cada pista, o argv dos dois comandos que um botao chama e a leitura do resultado de cada um. Botao so existe
+// quando o nucleo declara a acao com `disponivel`, e o argv sai sempre daqui, nunca do texto que veio no JSON: a Pista
+// so publica pelo `ork ship publicar` (que so age em #Auto e #Maestro) e so registra pelo `ork ship registrar-pr`.
+import type { PistaAcao, PistaLinha } from '../types'
+import { exigirThread, jsonDaSaida, umaLinha } from './pista'
+import type { SaidaDoProcesso } from './pista'
+
+export type AcaoDoBotao = PistaAcao['acao']
+
+/** O rotulo de cada botao no painel. */
+export const ROTULO_DO_BOTAO: Readonly<Record<AcaoDoBotao, string>> = { publicar: 'Publicar', registrar: 'Registrar a entrega' }
+
+/** O argv do `ork ship publicar`, sem flag de autorizacao: quem decide se o modo autoriza o push e o nucleo. */
+export function argvDoPublicar(thread: string): string[] {
+  return ['ork', 'ship', 'publicar', exigirThread(thread), '--json']
+}
+
+/** O argv do `ork ship registrar-pr` da thread: o nucleo confere o merge na base e o CI antes de gravar o `ship_done`. */
+export function argvDoRegistro(thread: string): string[] {
+  return ['ork', 'ship', 'registrar-pr', exigirThread(thread), '--json']
+}
+
+/**
+ * O botao da pista (D6): so `publicar`, no modo que ja autoriza o push, e `registrar`, e so quando o nucleo os declara
+ * disponiveis. Fora disso, nenhum botao: o proximo passo fica como texto, com o comando para o dono.
+ */
+export function botaoDaPista(l: PistaLinha): AcaoDoBotao | null {
+  if (!l.proximo.disponivel) return null
+  if (l.proximo.acao === 'publicar') return l.publicavel ? 'publicar' : null
+  if (l.proximo.acao === 'registrar') return 'registrar'
+  return null
+}
+
+export type ResultadoDoBotao = { estado: 'feita' | 'recusada' | 'falhou'; texto: string }
+
+const curto = (sha: unknown) => (typeof sha === 'string' && /^[0-9a-f]{7,40}$/.test(sha) ? sha.slice(0, 7) : '-')
+const texto = (v: unknown, teto = 300) => (typeof v === 'string' ? umaLinha(v, teto) : '')
+
+/** O resultado do `ork ship publicar --json` (`ork.ship-publicar/v1`), numa linha para o painel. */
+export function lerPublicacao(saida: SaidaDoProcesso): ResultadoDoBotao {
+  const r = jsonDaSaida(saida, 'ork ship publicar') as Record<string, unknown> | null
+  if (!r || typeof r !== 'object' || r.contrato !== 'ork.ship-publicar/v1') {
+    return { estado: 'falhou', texto: 'a saída do ork ship publicar não é o contrato ork.ship-publicar/v1' }
+  }
+  const pr = (r.pr ?? null) as { numero?: unknown; criado?: unknown } | null
+  const numero = pr && Number.isSafeInteger(pr.numero) ? `PR #${pr.numero as number}` : 'sem PR'
+  if (r.acao === 'publicou') {
+    return { estado: 'feita', texto: `publicada no HEAD ${curto(r.head)}, push provado pelo ls-remote; ${numero} ${pr?.criado === true ? 'aberto agora' : 'reaproveitado'}` }
+  }
+  if (r.acao === 'ja-publicada') {
+    return { estado: 'feita', texto: `já estava publicada no HEAD ${curto(r.head)}; ${numero}${texto(r.correcao) ? `; ${texto(r.correcao)}` : ''}` }
+  }
+  if (r.acao === 'recusada') {
+    const correcao = texto(r.correcao, 400)
+    return { estado: 'recusada', texto: `recusada (${texto(r.motivo, 60) || 'sem motivo'}): ${texto(r.detalhe) || 'sem detalhe'}${correcao ? `; ${correcao}` : ''}` }
+  }
+  return { estado: 'falhou', texto: `o ork ship publicar respondeu ${texto(r.acao, 40) || 'sem ação'}` }
+}
+
+/** O resultado do `ork ship registrar-pr <thread> --json` (uma lista de entregas), numa linha para o painel. */
+export function lerRegistro(saida: SaidaDoProcesso, thread: string): ResultadoDoBotao {
+  const lista = jsonDaSaida(saida, 'ork ship registrar-pr')
+  const item = Array.isArray(lista) ? (lista as Array<Record<string, unknown> | null>).find(x => x?.thread === thread) : undefined
+  if (!item) return { estado: 'falhou', texto: `o ork ship registrar-pr não respondeu pela thread ${thread}` }
+  const motivo = texto(item.motivo) || 'sem motivo'
+  if (item.acao === 'registrou') return { estado: 'feita', texto: `ship_done registrado: ${motivo}` }
+  if (item.acao === 'ja-registrada') return { estado: 'feita', texto: `a entrega já estava registrada: ${motivo}` }
+  if (item.acao === 'sem-merge' || item.acao === 'recusada') return { estado: 'recusada', texto: `${String(item.acao)}: ${motivo}` }
+  return { estado: 'falhou', texto: `o ork ship registrar-pr respondeu ${texto(item.acao, 40) || 'sem ação'}` }
+}

package/adapters/claude-code/mods/ork-pista/hooks/ci.ts

@@ -0,0 +1,117 @@
+// O CI de cada pista (RM-059, fatia F7, T7.4; D7 da thread ork-rm059pista). Modulo puro: o argv da consulta ao nucleo
+// (`ork ci status --sha <sha> --json`, contrato `ork.ci-status/v1`), a leitura dela, as pistas que um evento do GitHub
+// cita, as que o relogio de reserva consulta e a etapa de CI que o painel mostra com a leitura mais nova. O evento so
+// dispara a consulta: o conteudo dele nunca vira estado, e quem diz o CI e o check do nucleo no sha exato.
+import type { PistaCi, PistaEstadoDaEtapa, PistaLinha, PistaQuadro } from '../types'
+import { jsonDaSaida, umaLinha } from './pista'
+import type { SaidaDoProcesso } from './pista'
+
+/** A reserva sem evento: a cada 2 min com o painel a vista, a cada 10 min escondido. */
+export const INTERVALO_DO_CI_A_VISTA_MS = 2 * 60000
+export const INTERVALO_DO_CI_ESCONDIDO_MS = 10 * 60000
+const SHA = /^[0-9a-f]{40}$/
+const ESTADOS: readonly PistaCi['estado'][] = ['success', 'pending', 'failure', 'missing', 'unavailable', 'disabled']
+
+/** O argv da consulta do CI no sha exato do head do PR, nunca por ref nem prefixo. */
+export function argvDoCi(sha: string): string[] {
+  if (typeof sha !== 'string' || !SHA.test(sha)) throw new Error('ork-pista: sha invalido para o ork ci status')
+  return ['ork', 'ci', 'status', '--sha', sha, '--json']
+}
+
+/**
+ * A saida do `ork ci status --sha <sha> --json`: o comando sai 0 so com o check verde, e o JSON vem nos dois casos.
+ * Leitura de outro sha nao vale para a pista.
+ */
+export function lerCi(saida: SaidaDoProcesso, sha: string, agora: number, motivo: PistaCi['motivo']): PistaCi {
+  const r = jsonDaSaida(saida, 'ork ci status') as Record<string, unknown> | null
+  if (!r || typeof r !== 'object' || r.schema !== 'ork.ci-status/v1' || !ESTADOS.includes(r.state as PistaCi['estado'])) {
+    throw new Error('a saída do ork ci status não é o contrato ork.ci-status/v1')
+  }
+  if (r.sha !== sha) throw new Error(`o ork ci status respondeu pelo commit ${umaLinha(r.sha, 40)}, e não pelo head ${sha.slice(0, 7)}`)
+  const estado = r.state as PistaCi['estado']
+  const contexto = typeof r.context === 'string' && r.context ? umaLinha(r.context, 60) : 'ork-verify'
+  const curto = sha.slice(0, 7)
+  const texto = estado === 'success' ? `check ${contexto} verde no head ${curto}`
+    : estado === 'failure' ? `check ${contexto} vermelho no head ${curto}`
+    : estado === 'pending' ? `check ${contexto} em andamento no head ${curto}`
+    : estado === 'missing' ? `o check ${contexto} ainda não apareceu no head ${curto}`
+    : estado === 'disabled' ? 'CI não exigido pelo manifesto'
+    : `o CI não foi lido: ${umaLinha(r.detail, 160) || 'sem detalhe'}`
+  const url = typeof r.url === 'string' && /^https:\/\/\S+$/.test(r.url) ? umaLinha(r.url, 300) : null
+  return { sha, estado, texto, url, lidoEm: agora, motivo }
+}
+
+/** A pista com PR aberto cujo CI a leitura da pista ainda nao fechou (nem verde nem vermelho). */
+export function precisaDoCi(l: PistaLinha): boolean {
+  const etapa = l.etapas.find(e => e.id === 'ci')
+  return l.pr?.estado === 'aberto' && SHA.test(l.pr.head) && (etapa?.estado === 'pendente' || etapa?.estado === 'nao-lida')
+}
+
+/** As pistas que o relogio de reserva consulta agora: as que precisam, sem leitura do head atual dentro do intervalo. */
+export function vencidasDoCi(linhas: readonly PistaLinha[], ci: Readonly<Record<string, PistaCi>>, agora: number, intervalo: number): string[] {
+  return linhas.filter(l => {
+    if (!precisaDoCi(l)) return false
+    const lido = ci[l.thread]
+    return !lido || lido.sha !== l.pr?.head || agora - lido.lidoEm >= intervalo
+  }).map(l => l.thread)
+}
+
+/**
+ * As pistas que um evento do GitHub cita, so pelos campos que o servidor assere (fora de `untrustedKeys`): o PR (o
+ * numero, ou `dono/repo#N`), a branch ou o sha. Evento de outra fonte, ou que nao cita pista nenhuma, nao consulta nada.
+ */
+export function pistasDoEvento(evento: unknown, linhas: readonly PistaLinha[]): string[] {
+  if (!evento || typeof evento !== 'object') return []
+  const e = evento as { source?: unknown; data?: unknown; untrustedKeys?: unknown }
+  if (e.source !== 'github' || !e.data || typeof e.data !== 'object') return []
+  const deTerceiros = new Set(Array.isArray(e.untrustedKeys) ? e.untrustedKeys.map(String) : [])
+  const numeros = new Set<number>()
+  const textos = new Set<string>()
+  for (const [chave, valor] of Object.entries(e.data as Record<string, unknown>)) {
+    if (deTerceiros.has(chave)) continue
+    if (typeof valor === 'number' && Number.isSafeInteger(valor) && valor > 0 && /^(pr|number|pull_request|pull)$/i.test(chave)) numeros.add(valor)
+    if (typeof valor !== 'string') continue
+    const pr = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+#(\d{1,9})$/.exec(valor.trim()) ?? (/^(pr|number|pull_request|pull)$/i.test(chave) ? /^#?(\d{1,9})$/.exec(valor.trim()) : null)
+    if (pr) numeros.add(Number(pr[1]))
+    textos.add(valor.trim())
+  }
+  return linhas.filter(l => (l.pr && numeros.has(l.pr.numero)) || textos.has(l.branch) || (!!l.head && textos.has(l.head)) ||
+    (!!l.pr && textos.has(l.pr.head))).map(l => l.thread)
+}
+
+const ETAPA_DO_CI: Readonly<Record<PistaCi['estado'], PistaEstadoDaEtapa>> = {
+  success: 'feita', failure: 'falhou', pending: 'pendente', missing: 'pendente', unavailable: 'nao-lida', disabled: 'nao-se-aplica',
+}
+
+/** A consulta leu o check no head: `unavailable` (a consulta falhou) e `disabled` (o CI nao e exigido) nao leram nada. */
+function leuOCheck(lido: PistaCi): boolean {
+  return lido.estado !== 'unavailable' && lido.estado !== 'disabled'
+}
+
+/**
+ * A pista com a leitura do CI mais nova por cima da etapa da leitura da pista, so quando ela e do head do PR aberto. A
+ * consulta que nao leu nada nunca apaga o que o nucleo ja leu: a etapa fica como o nucleo disse, com a falha ao lado.
+ */
+export function comCi(q: PistaQuadro, ci: Readonly<Record<string, PistaCi>>): PistaQuadro {
+  return {
+    ...q,
+    linhas: q.linhas.map(l => {
+      const lido = ci[l.thread]
+      if (!lido || l.pr?.estado !== 'aberto' || lido.sha !== l.pr.head) return l
+      if (!leuOCheck(lido)) {
+        return { ...l, etapas: l.etapas.map(e => (e.id === 'ci' ? { ...e, texto: `${e.texto} (consulta: ${lido.texto})` } : e)) }
+      }
+      const origem = lido.motivo === 'evento' ? ' (pelo evento do GitHub)' : ''
+      return { ...l, etapas: l.etapas.map(e => (e.id === 'ci' ? { id: 'ci', estado: ETAPA_DO_CI[lido.estado], texto: `${lido.texto}${origem}` } : e)) }
+    }),
+  }
+}
+
+/**
+ * A leitura nova diz do CI outra coisa que a etapa da pista: o CI fechou, ou mudou depois de uma rodada nova. O proximo
+ * passo do nucleo muda com ele, e a pista inteira e relida. A consulta que nao leu nada nao muda nada.
+ */
+export function mudouOCi(l: PistaLinha, lido: PistaCi): boolean {
+  if (!leuOCheck(lido) || l.pr?.estado !== 'aberto' || lido.sha !== l.pr.head) return false
+  return l.etapas.find(e => e.id === 'ci')?.estado !== ETAPA_DO_CI[lido.estado]
+}

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

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

package/adapters/claude-code/mods/ork-pista/hooks/pista.tsx

@@ -0,0 +1,356 @@
+// A pista de entrega (RM-059, fatia F7; ficha M7 do plano dos mods). Modulo puro: o argv da leitura do nucleo
+// (`ork ship pista --json`, contrato `ork.ship-pista/v1`), a conferencia da saida campo a campo, a ordem das pistas, a
+// linha da faixa, as linhas do painel com o que cada uma mostra ao dono e o desenho. Quem calcula as etapas e o
+// proximo passo e o nucleo (D4 da thread ork-rm059pista); aqui so se le, se ordena e se desenha. O `$` fica no
+// register.tsx, e o desenho recebe a tabela de elementos que a superficie resolveu.
+import type { PistaAcao, PistaEstadoDaEtapa, PistaEtapa, PistaIdDaEtapa, PistaLinha, PistaMostrado, PistaPr, PistaProximo, PistaQuadro } from '../types'
+
+export const ETAPAS: readonly PistaIdDaEtapa[] = ['check', 'verify', 'bundle', 'branch', 'pr', 'ci', 'conflito', 'entrega']
+const ESTADOS: readonly PistaEstadoDaEtapa[] = ['feita', 'pendente', 'falhou', 'nao-lida', 'nao-se-aplica']
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+const SHA = /^[0-9a-f]{40}$/
+/** O nome curto de cada etapa no painel. */
+export const NOME_DA_ETAPA: Readonly<Record<PistaIdDaEtapa, string>> = {
+  check: 'CHECK', verify: 'verify', bundle: 'bundle', branch: 'branch', pr: 'PR', ci: 'CI', conflito: 'conflito', entrega: 'entrega',
+}
+/** A marca de cada estado de etapa: o que falta e o que falhou saltam aos olhos. */
+export const MARCA_DA_ETAPA: Readonly<Record<PistaEstadoDaEtapa, string>> = {
+  'feita': '✓', 'pendente': '·', 'falhou': '✗', 'nao-lida': '?', 'nao-se-aplica': '-',
+}
+/** Teto de pistas no quadro: cada uma ocupa umas cinco linhas do painel. */
+export const TETO_DE_PISTAS = 30
+const TETO_DE_TEXTO = 300
+
+export type SaidaDoProcesso = { exitCode: number; stdout: string; stderr: string }
+
+/** Uma linha so, sem caractere de controle, com teto: texto que vem do nucleo e vai para a tela. */
+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 exigirThread(thread: unknown): string {
+  if (typeof thread !== 'string' || !ID_DE_THREAD.test(thread)) throw new Error('ork-pista: id de thread invalido')
+  return thread
+}
+
+/** O argv da leitura da pista, de todas as threads ou de uma: o unico jeito de a Pista ler as etapas. */
+export function argvDaPista(thread?: string): string[] {
+  return thread === undefined ? ['ork', 'ship', 'pista', '--json'] : ['ork', 'ship', 'pista', exigirThread(thread), '--json']
+}
+
+/** A saida de um comando `--json` do nucleo, ou o motivo de nao ter sido lida (o CLI sem o subcomando incluso). */
+export function jsonDaSaida(saida: SaidaDoProcesso, comando: string): unknown {
+  if (saida.exitCode === 2 && /(subcomando desconhecido|uso: ork ship|usage: ork ship|comando desconhecido)/i.test(`${saida.stderr}\n${saida.stdout}`)) {
+    throw new Error(`o ork deste PATH não tem ${comando}: atualize o CLI do Orkastery`)
+  }
+  try {
+    return JSON.parse(saida.stdout)
+  } catch {
+    const motivo = umaLinha(saida.stderr || saida.stdout, 160) || `saída ${saida.exitCode}`
+    throw new Error(`${comando} não devolveu JSON (saída ${saida.exitCode}): ${motivo}`)
+  }
+}
+
+const texto = (v: unknown, teto = TETO_DE_TEXTO): string | null => (typeof v === 'string' && v.trim() !== '' ? umaLinha(v, teto) : null)
+
+function etapaDe(bruto: unknown, id: PistaIdDaEtapa): PistaEtapa | null {
+  if (!bruto || typeof bruto !== 'object') return null
+  const e = bruto as Record<string, unknown>
+  if (e.id !== id || !ESTADOS.includes(e.estado as PistaEstadoDaEtapa)) return null
+  return { id, estado: e.estado as PistaEstadoDaEtapa, texto: texto(e.texto) ?? '' }
+}
+
+function prDe(bruto: unknown): PistaPr | null | undefined {
+  if (bruto === null) return null
+  if (!bruto || typeof bruto !== 'object') return undefined
+  const p = bruto as Record<string, unknown>
+  if (!Number.isSafeInteger(p.numero) || (p.numero as number) < 1 || !['aberto', 'mesclado', 'fechado'].includes(String(p.estado)) ||
+    typeof p.rascunho !== 'boolean' || typeof p.head !== 'string' || !SHA.test(p.head)) return undefined
+  const url = typeof p.url === 'string' && /^https:\/\/\S+$/.test(p.url) ? umaLinha(p.url, 300) : null
+  return { numero: p.numero as number, url, estado: p.estado as PistaPr['estado'], rascunho: p.rascunho, head: p.head }
+}
+
+function proximoDe(bruto: unknown): PistaProximo | null {
+  if (!bruto || typeof bruto !== 'object') return null
+  const p = bruto as Record<string, unknown>
+  const acao = p.acao === 'publicar' || p.acao === 'registrar' ? p.acao : p.acao === null ? null : undefined
+  if (acao === undefined || typeof p.disponivel !== 'boolean') return null
+  const t = texto(p.texto)
+  if (!t) return null
+  // So uma acao conhecida pode estar disponivel; o resto vira texto.
+  return { acao, disponivel: acao !== null && p.disponivel, texto: t, comando: texto(p.comando, 600) }
+}
+
+/** Uma pista do nucleo, conferida campo a campo; `null` quando ela nao tem a forma do contrato. */
+export function linhaDaPista(bruto: unknown): PistaLinha | null {
+  if (!bruto || typeof bruto !== 'object') return null
+  const p = bruto as Record<string, unknown>
+  if (typeof p.thread !== 'string' || !ID_DE_THREAD.test(p.thread) || typeof p.publicavel !== 'boolean' || typeof p.conduzida !== 'boolean') return null
+  if (!Array.isArray(p.etapas) || p.etapas.length !== ETAPAS.length) return null
+  const etapas = ETAPAS.map((id, i) => etapaDe((p.etapas as unknown[])[i], id))
+  if (etapas.some(e => e === null)) return null
+  const pr = prDe(p.pr)
+  const proximo = proximoDe(p.proximo)
+  const head = typeof p.head === 'string' && SHA.test(p.head) ? p.head : null
+  if (pr === undefined || !proximo) return null
+  return {
+    thread: p.thread, nome: texto(p.nome, 120) ?? p.thread, tag: texto(p.tag, 20) ?? '', publicavel: p.publicavel, conduzida: p.conduzida,
+    branch: texto(p.branch, 200) ?? '', head, pr, etapas: etapas as PistaEtapa[], proximo,
+  }
+}
+
+/**
+ * A saida do `ork ship pista --json`, conferida: o contrato, uma pista por thread (no maximo `TETO_DE_PISTAS`) e os
+ * avisos do que nao foi lido. Saida que nao e o contrato lanca, e o quadro anterior fica.
+ */
+export function lerPista(saida: SaidaDoProcesso, agora: number): PistaQuadro {
+  const bruto = jsonDaSaida(saida, 'ork ship pista') as Record<string, unknown> | null
+  if (!bruto || typeof bruto !== 'object' || bruto.contrato !== 'ork.ship-pista/v1' || !Array.isArray(bruto.pistas)) {
+    throw new Error('a saída do ork ship pista não é o contrato ork.ship-pista/v1')
+  }
+  const linhas = (bruto.pistas as unknown[]).map(linhaDaPista).filter((l): l is PistaLinha => l !== null)
+  const avisos: string[] = []
+  if (bruto.remotoLido === false) avisos.push(`o remoto ${texto(bruto.remoto, 60) ?? ''} não respondeu ao ls-remote`)
+  if (bruto.prsLidos === false) avisos.push(`os PRs não foram lidos: ${texto(bruto.prsNaoLidos, 200) ?? 'sem motivo'}`)
+  const descartadas = (bruto.pistas as unknown[]).length - linhas.length
+  if (descartadas > 0) avisos.push(`${descartadas} pista(s) fora do contrato ficaram de fora`)
+  if (linhas.length > TETO_DE_PISTAS) avisos.push(`${linhas.length - TETO_DE_PISTAS} pista(s) além do teto ficaram de fora`)
+  return { linhas: ordenarLinhas(linhas).slice(0, TETO_DE_PISTAS), lidoEm: agora, erro: null, avisos }
+}
+
+/**
+ * A assinatura da secao `ship` do retrato do nucleo (o retrato da ponte): muda quando uma entrega anda (`ship_done`,
+ * `ship_started`, `ship_blocked`), e entao a pista e relida antes da idade. `null` quando o retrato nao veio.
+ */
+export function assinaturaDoRetrato(r: unknown): string | null {
+  const secao = (r as { retrato?: { sections?: { ship?: { items?: unknown } } } } | null)?.retrato?.sections?.ship
+  if (!secao || !Array.isArray(secao.items)) return null
+  return (secao.items as unknown[]).map(i => {
+    const x = (i ?? {}) as { id?: unknown; status?: unknown; facts?: { receiptAt?: unknown } }
+    return `${String(x.id)}|${String(x.status)}|${String(x.facts?.receiptAt ?? '')}`
+  }).sort().join(';')
+}
+
+/** O ledger de thread que mudou (`classic.FileChanged`), pelo caminho; `null` para outro arquivo. */
+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
+}
+
+/** O peso de uma pista na ordem: o que tem botao, o que falhou, o que anda, o que ja foi entregue. */
+export function pesoDaPista(l: PistaLinha): number {
+  if (l.proximo.disponivel) return 0
+  if (l.proximo.acao === 'publicar') return 1
+  if (l.etapas.some(e => e.estado === 'falhou')) return 2
+  if (l.etapas.find(e => e.id === 'entrega')?.estado === 'feita') return 4
+  return 3
+}
+
+export function ordenarLinhas(linhas: readonly PistaLinha[]): PistaLinha[] {
+  return [...linhas].sort((a, b) => pesoDaPista(a) - pesoDaPista(b) || a.thread.localeCompare(b.thread))
+}
+
+/** A marca da pista no painel: `!` com botao, `?` pede o dono, `x` falhou, `>` anda, `-` entregue. */
+export function marcaDaPista(l: PistaLinha): string {
+  return ['!', '?', 'x', '>', '-'][pesoDaPista(l)] as string
+}
+
+const plural = (n: number, um: string, varios: string) => `${n} ${n === 1 ? um : varios}`
+
+/**
+ * A linha da faixa (D9): so o que pede o dono, sem repetir o que anda sozinho. Sem nada disso, a linha sai da
+ * faixa. A ponte ja escreve `pista: ` antes dela.
+ */
+export function textoDaFaixa(q: PistaQuadro): string | undefined {
+  const prontas = q.linhas.filter(l => l.proximo.acao === 'publicar' && l.proximo.disponivel).length
+  const doDono = q.linhas.filter(l => l.proximo.acao === 'publicar' && !l.proximo.disponivel).length
+  const registrar = q.linhas.filter(l => l.proximo.acao === 'registrar' && l.proximo.disponivel).length
+  const vermelhas = q.linhas.filter(l => l.etapas.some(e => (e.id === 'ci' || e.id === 'conflito') && e.estado === 'falhou')).length
+  const partes = [
+    prontas ? plural(prontas, 'pronta para publicar', 'prontas para publicar') : null,
+    doDono ? plural(doDono, 'pede o seu push', 'pedem o seu push') : null,
+    registrar ? plural(registrar, 'para registrar', 'para registrar') : null,
+    vermelhas ? plural(vermelhas, 'com CI vermelho ou conflito', 'com CI vermelho ou conflito') : null,
+  ].filter((p): p is string => p !== null)
+  return partes.length ? `${partes.join(' · ')} · /pista` : undefined
+}
+
+/** Quanto tempo faz, em palavras curtas. */
+export function haQuanto(desde: number | null, agora: number): string {
+  if (desde === null) return 'ainda não lida'
+  const s = Math.max(0, Math.round((agora - desde) / 1000))
+  if (s < 60) return `lida há ${s} s`
+  const min = Math.round(s / 60)
+  return min < 60 ? `lida há ${min} min` : `lida há ${Math.round(min / 60)} h`
+}
+
+/** Uma linha do painel, com o tipo que decide o elemento e o que ela mostra ao dono (para o registro da ponte). */
+export type LinhaDoPainel = {
+  tipo: 'placar' | 'aviso' | 'vazio' | 'cabecalho' | 'etapas' | 'etapa' | 'proximo' | 'botao' | 'comando' | 'resultado'
+  texto: string
+  thread?: string
+  /** So na linha do botao: o comando do nucleo que ele chama (T7.3). */
+  acao?: 'publicar' | 'registrar'
+  mostrado?: PistaMostrado
+}
+
+/** O botao que o register.tsx decidiu para uma pista (o nucleo o declara disponivel), com o rotulo. */
+export type BotaoDaPista = { acao: 'publicar' | 'registrar'; rotulo: string }
+
+const linhaDasEtapas = (l: PistaLinha) => l.etapas.map(e => {
+  const nome = e.id === 'pr' && l.pr ? `PR #${l.pr.numero}` : NOME_DA_ETAPA[e.id]
+  return `${nome} ${MARCA_DA_ETAPA[e.estado]}`
+}).join(' · ')
+
+/** O texto do resultado do ultimo botao da thread, quando ha. */
+export function textoDaAcao(a: PistaAcao | undefined): string | null {
+  if (!a) return null
+  const rotulo = a.acao === 'publicar' ? 'publicar' : 'registrar'
+  if (a.estado === 'rodando') return `${rotulo}: rodando no núcleo...`
+  return `${rotulo}: ${a.texto}`
+}
+
+/**
+ * As linhas do painel, na ordem do desenho. A pista em foco (`/pista <thread>`) vem primeiro. Cada pista: o
+ * cabecalho, as oito etapas numa linha, o texto de cada etapa que nao esta feita, o proximo passo do nucleo, o
+ * comando (para o dono, quando o modo pede o push dele) e o resultado do ultimo botao.
+ */
+export function linhasDoPainel(q: PistaQuadro, opcoes: { agora: number; foco?: string | null; acoes?: Readonly<Record<string, PistaAcao>>;
+  botoes?: Readonly<Record<string, BotaoDaPista>> }): LinhaDoPainel[] {
+  const saida: LinhaDoPainel[] = []
+  const prontas = q.linhas.filter(l => l.proximo.disponivel).length
+  saida.push({ tipo: 'placar', texto: `Pista de Entrega · ${plural(q.linhas.length, 'entrega', 'entregas')}` +
+    `${prontas ? ` · ${plural(prontas, 'com botão', 'com botão')}` : ''} · ${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 })
+  if (!q.linhas.length) {
+    saida.push({ tipo: 'vazio', texto: q.lidoEm === null ? 'lendo a pista do núcleo...'
+      : 'Nenhuma entrega na pista: a thread entra aqui depois do CHECK, com a branch publicada ou com PR.' })
+    return saida
+  }
+  const foco = opcoes.foco ?? null
+  const ordem = foco ? [...q.linhas.filter(l => l.thread === foco), ...q.linhas.filter(l => l.thread !== foco)] : q.linhas
+  for (const l of ordem) {
+    const emFoco = l.thread === foco ? '  (em foco)' : ''
+    saida.push({ tipo: 'cabecalho', thread: l.thread, texto: `${marcaDaPista(l)}  ${l.thread}  ${l.tag}  ${l.branch}${emFoco}` })
+    saida.push({ tipo: 'etapas', thread: l.thread, texto: `  ${linhaDasEtapas(l)}` })
+    for (const e of l.etapas.filter(x => x.estado === 'pendente' || x.estado === 'falhou' || x.estado === 'nao-lida')) {
+      saida.push({ tipo: 'etapa', thread: l.thread, texto: `    ${NOME_DA_ETAPA[e.id]}: ${e.texto}` })
+    }
+    const proximo = `  próximo: ${l.proximo.texto}`
+    saida.push({ tipo: 'proximo', thread: l.thread, texto: proximo,
+      mostrado: { chave: `pista:${l.thread}`, thread: l.thread, texto: `${l.thread}: ${l.proximo.texto}` } })
+    // O botao so aparece com a acao declarada e sem outro clique da mesma thread rodando no nucleo.
+    const botao = opcoes.botoes?.[l.thread]
+    if (botao && opcoes.acoes?.[l.thread]?.estado !== 'rodando') saida.push({ tipo: 'botao', thread: l.thread, acao: botao.acao, texto: botao.rotulo })
+    if (l.proximo.comando && !l.proximo.disponivel) {
+      const quem = l.proximo.acao === 'publicar' ? 'no seu terminal' : 'comando do núcleo'
+      saida.push({ tipo: 'comando', thread: l.thread, texto: `  ${quem}: ${l.proximo.comando}` })
+    }
+    const acao = textoDaAcao(opcoes.acoes?.[l.thread])
+    if (acao) saida.push({ tipo: 'resultado', thread: l.thread, texto: `  ${acao}`,
+      mostrado: { chave: `pista:${l.thread}:acao`, thread: l.thread, texto: `${l.thread}: ${acao}` } })
+  }
+  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` (uma coluna, por padrao) 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: `proximo` e `comando` quebram (`wrap="wrap"`); as outras
+ * truncam numa so.
+ */
+function alturasNaTela(l: { tipo?: string; texto?: string }, colunas: number | undefined): [number, number] {
+  if (l.tipo !== 'proximo' && l.tipo !== 'comando') 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 janela conta
+ * linhas da tela (`offset` e `bodyRows`), e a linha que quebra nas `colunas` do corpo ocupa mais de uma. Como a quebra
+ * do motor e estimada, cada linha tem o topo mais cedo (a conta sem folga) e o mais tarde (com folga): ela so conta com
+ * o mais cedo abaixo do alto da janela e o fim mais tarde acima do pe dela, nas duas bordas.
+ */
+export function mostradosVisiveis(linhas: ReadonlyArray<{ tipo?: string; texto?: string; mostrado?: PistaMostrado }>,
+  janela: { offset: number; bodyRows: number } | undefined, colunas?: number): PistaMostrado[] {
+  if (!janela || !(janela.bodyRows > 0)) return []
+  const fim = janela.offset + janela.bodyRows
+  const vistos: PistaMostrado[] = []
+  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: atualizar a pista e, na T7.3, os botoes que o nucleo declara. */
+export type Gestos = {
+  atualizar?: () => void
+  publicar?: (thread: string) => void
+  registrar?: (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 desenharPista(el: { Box: any; Text: any; Button: any }, q: PistaQuadro,
+  opcoes: { agora: number; foco?: string | null; acoes?: Readonly<Record<string, PistaAcao>>; botoes?: Readonly<Record<string, BotaoDaPista>> } & Gestos) {
+  const { Box, Text, Button } = el
+  return (
+    <Box flexDirection="column">
+      {linhasDoPainel(q, opcoes).map((l, i) => {
+        if (l.tipo === 'placar') {
+          return (
+            <Box key="placar" flexDirection="row">
+              <Text key="placar-texto" bold wrap="truncate">{l.texto}</Text>
+              <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 === 'botao' && l.thread && l.acao) {
+          const thread = l.thread
+          const apertar = l.acao === 'publicar' ? opcoes.publicar : opcoes.registrar
+          return <Button key={`${l.acao}:${thread}`} label={l.texto} onPress={() => apertar?.(thread)} />
+        }
+        if (l.tipo === 'comando') return <Text key={`comando:${l.thread}`} wrap="wrap">{l.texto}</Text>
+        if (l.tipo === 'proximo') return <Text key={`proximo:${l.thread}`} wrap="wrap">{l.texto}</Text>
+        return <Text key={`${l.tipo}:${l.thread ?? ''}:${i}`} dimColor wrap="truncate">{l.texto}</Text>
+      })}
+    </Box>
+  )
+}