@orkastery/cli 0.5.1 → 0.5.6

package/adapters/claude-code/mods/ork-clima/hooks/previsao.ts

@@ -0,0 +1,393 @@
+// O Clima de Cota (RM-059, onda 1, F4; T4.1): a serie das janelas de limite da conta desta sessao e a
+// previsao de quando cada uma acaba no ritmo atual (D4 a D6 e D12 a D15 da thread). Modulo puro: so dados
+// entram e saem, para o teste do nucleo transpila-lo sem o Claude Code. Nenhum `$` passa por aqui, e o
+// fuso chega explicito: quem chama decide qual e.
+import type { ClimaEstado, ClimaJanela, ClimaPonto, ClimaPrevisao, ClimaProblema, ClimaSerie } from '../types'
+
+export const FORMATO_DA_SERIE = 'ork.clima-serie/v1'
+/** A chave da serie no `$.store` do mod, que dura entre sessoes. */
+export const CHAVE_DA_SERIE = 'serie'
+export const TETO_DE_PONTOS = 120
+export const TETO_DE_JANELAS = 8
+/** Diferenca de `resetsAt` que ainda e a mesma janela. */
+export const TOLERANCIA_DA_RENOVACAO_MS = 60 * 1000
+/** Dentro da janela o uso so cresce: uma queda deste tamanho so acontece quando ela renova. */
+export const QUEDA_QUE_RENOVA = 1
+/** O ritmo sai deste intervalo recente, proporcional a janela de cota (D4). */
+export const INTERVALO_DO_RITMO_MS: Readonly<Record<string, number>> = {
+  five_hour: 60 * 60 * 1000,
+  seven_day: 24 * 60 * 60 * 1000,
+}
+export const INTERVALO_PADRAO_DO_RITMO_MS = 60 * 60 * 1000
+/**
+ * Serie mais nova que o intervalo so tem ritmo com esta fracao dele entre a primeira e a ultima leitura: 10 min
+ * na janela de 5 h e 4 h na de 7 d (D13).
+ */
+export const FRACAO_MINIMA_DO_INTERVALO = 6
+/**
+ * Nestas janelas, a serie mais nova que o intervalo so preve o esgotamento ate a distancia que ela ja observou:
+ * o ritmo de quatro horas de dia util nao vale pela madrugada (D14), e a serie nova no meio da semana ainda
+ * avisa quando o fim esta perto (D15).
+ */
+export const JANELAS_COM_HORIZONTE: readonly string[] = ['seven_day']
+/** A partir deste percentual a faixa avisa mesmo sem ritmo (D5). */
+export const LIMIAR_DE_ATENCAO = 90
+/** Na faixa, o percentual vai em degraus e a hora de acabar vai arredondada, para o texto nao mudar a cada ponto (D13). */
+export const DEGRAU_DO_PERCENTUAL = 10
+export const PASSO_DA_HORA_NA_FAIXA_MS = 15 * 60 * 1000
+/** O texto da faixa nunca passa disto, o mesmo teto da ponte. */
+export const TETO_DA_FAIXA = 200
+/** Quantas threads que nao cabem a faixa nomeia antes do `e mais N`. */
+export const TETO_NA_FAIXA = 3
+export const AVISO_DE_AUTORIDADE = 'O Clima só lê e avisa: troca de conta, de runtime ou de modelo fica com o núcleo e com você.'
+
+const KIND = /^[a-z0-9][a-z0-9_.-]{0,63}$/i
+const ORDEM_DOS_KINDS = ['five_hour', 'seven_day']
+const ROTULOS: Readonly<Record<string, string>> = { five_hour: '5 h', seven_day: '7 d', spend_limit: 'gasto' }
+const GRAVIDADE: Readonly<Record<ClimaEstado, number>> = { 'esgotada': 0, 'acaba-antes': 1, 'folga': 2, 'sem-ritmo': 3 }
+
+function numero(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v)
+}
+
+/** `5 h`, `7 d`, `gasto` ou o proprio `kind`. */
+export function rotuloDaJanela(kind: string): string {
+  return Object.prototype.hasOwnProperty.call(ROTULOS, kind) ? (ROTULOS[kind] as string) : kind
+}
+
+function ordemDoKind(kind: string): number {
+  const i = ORDEM_DOS_KINDS.indexOf(kind)
+  return i < 0 ? ORDEM_DOS_KINDS.length : i
+}
+
+function porKind(a: { kind: string }, b: { kind: string }): number {
+  return ordemDoKind(a.kind) - ordemDoKind(b.kind) || (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0)
+}
+
+/** O intervalo recente do ritmo de uma janela. */
+export function intervaloDoRitmo(kind: string): number {
+  return Object.prototype.hasOwnProperty.call(INTERVALO_DO_RITMO_MS, kind) ? (INTERVALO_DO_RITMO_MS[kind] as number)
+    : INTERVALO_PADRAO_DO_RITMO_MS
+}
+
+/** Quanto de serie a janela precisa antes de ter ritmo, enquanto e mais nova que o intervalo. */
+export function minimoDaSerieJovem(kind: string): number {
+  return intervaloDoRitmo(kind) / FRACAO_MINIMA_DO_INTERVALO
+}
+
+/**
+ * Ate onde a serie jovem preve, nas janelas com horizonte: o tempo entre a primeira e a ultima leitura. `null`
+ * quando a serie ja cobre o intervalo inteiro ou a janela nao tem horizonte (D15).
+ */
+export function horizonteDaSerie(j: Pick<ClimaJanela, 'kind' | 'pontos'>): number | null {
+  const ultimo = j.pontos[j.pontos.length - 1]
+  const primeiro = j.pontos[0]
+  if (ultimo === undefined || primeiro === undefined || !JANELAS_COM_HORIZONTE.includes(j.kind)) return null
+  return primeiro.em >= ultimo.em - intervaloDoRitmo(j.kind) ? ultimo.em - primeiro.em : null
+}
+
+/** A leitura conferida, ou `null` quando ela nao serve (kind estranho, percentual que nao e numero, data ruim). */
+export function conferirLeitura(bruta: unknown): { kind: string; pct: number; renovaEm: number | null } | null {
+  const l = (bruta ?? {}) as Record<string, unknown>
+  if (typeof l.kind !== 'string' || !KIND.test(l.kind)) return null
+  if (!numero(l.percentUsed) || l.percentUsed < 0 || l.percentUsed > 1000) return null
+  let renovaEm: number | null = null
+  if (l.resetsAt !== undefined && l.resetsAt !== null) {
+    const t = typeof l.resetsAt === 'string' ? Date.parse(l.resetsAt) : NaN
+    if (!Number.isFinite(t)) return null
+    renovaEm = t
+  }
+  return { kind: l.kind, pct: Math.round(l.percentUsed * 10) / 10, renovaEm }
+}
+
+/** A serie guardada, ou uma vazia quando o que esta no store nao e deste formato. */
+export function lerSerie(guardado: unknown): ClimaSerie {
+  const s = guardado as Partial<ClimaSerie> | null | undefined
+  const janelas: ClimaJanela[] = []
+  if (s && s.formato === FORMATO_DA_SERIE && Array.isArray(s.janelas)) {
+    for (const bruta of s.janelas) {
+      const j = (bruta ?? {}) as Partial<ClimaJanela>
+      if (typeof j.kind !== 'string' || !KIND.test(j.kind) || janelas.some(x => x.kind === j.kind)) continue
+      if (!(j.renovaEm === null || numero(j.renovaEm))) continue
+      const pontos = (Array.isArray(j.pontos) ? j.pontos : [])
+        .filter((p): p is ClimaPonto => !!p && numero(p.em) && numero(p.pct))
+        .map(p => ({ em: p.em, pct: p.pct }))
+        .sort((a, b) => a.em - b.em)
+      if (pontos.length > 0) janelas.push({ kind: j.kind, renovaEm: j.renovaEm, pontos: pontos.slice(-TETO_DE_PONTOS) })
+    }
+  }
+  return { formato: FORMATO_DA_SERIE, janelas: janelas.sort(porKind).slice(0, TETO_DE_JANELAS) }
+}
+
+/** A janela ja renovou: a ultima leitura dela nao diz mais nada. */
+export function vencida(j: Pick<ClimaJanela, 'renovaEm'>, agora: number): boolean {
+  return j.renovaEm !== null && j.renovaEm + TOLERANCIA_DA_RENOVACAO_MS <= agora
+}
+
+/** Acrescenta o ponto em ordem de tempo; numa corrida plana ficam so o primeiro e o ultimo ponto. */
+function acrescentar(pontos: readonly ClimaPonto[], novo: ClimaPonto): ClimaPonto[] {
+  const ordenados = [...pontos.filter(p => p.em !== novo.em), novo].sort((a, b) => a.em - b.em)
+  const saida: ClimaPonto[] = []
+  for (const p of ordenados) {
+    const ultimo = saida[saida.length - 1]
+    const penultimo = saida[saida.length - 2]
+    if (ultimo !== undefined && penultimo !== undefined && ultimo.pct === p.pct && penultimo.pct === p.pct) saida[saida.length - 1] = p
+    else saida.push(p)
+  }
+  return saida.slice(-TETO_DE_PONTOS)
+}
+
+/**
+ * O que a medicao trouxe fora do formato, numa frase, ou `null` quando tudo serviu: a lista de janelas que nem e
+ * lista, ou as janelas que `conferirLeitura` descarta. Sem isso, um campo renomeado no motor apagaria o Clima
+ * calado (D15).
+ */
+export function problemaDaLeitura(leituras: unknown): string | null {
+  if (!Array.isArray(leituras)) return 'a medição avisou leitura nova sem a lista de janelas'
+  const descartadas = leituras.filter(l => conferirLeitura(l) === null).length
+  if (descartadas === 0) return null
+  return `a leitura trouxe ${descartadas === 1 ? '1 janela' : `${descartadas} janelas`} num formato que o Clima não conhece`
+}
+
+/**
+ * Grava as leituras de uma medicao em que as janelas mudaram: uma serie por `kind`, serie nova quando a
+ * janela renova (o `resetsAt` muda ou o percentual cai), tetos de pontos e de janelas (D4). A medicao traz
+ * todas as janelas da conta, entao a janela vencida e a que saiu da leitura deixam a serie (D13). Com janela
+ * fora do formato a leitura nao esta completa, e as outras janelas guardadas ficam (D15).
+ */
+export function registrarLeituras(guardado: unknown, leituras: readonly unknown[] | undefined, agora: number): ClimaSerie {
+  const brutas = leituras ?? []
+  const lidas = brutas.map(conferirLeitura).filter((l): l is NonNullable<ReturnType<typeof conferirLeitura>> => l !== null)
+  const anteriores = lerSerie(guardado).janelas.filter(j => !vencida(j, agora))
+  const janelas: ClimaJanela[] = lidas.length === brutas.length ? [] : anteriores.filter(a => !lidas.some(l => l.kind === a.kind))
+  for (const l of lidas) {
+    if (janelas.some(j => j.kind === l.kind)) continue
+    const anterior = anteriores.find(j => j.kind === l.kind)
+    const ultimo = anterior?.pontos[anterior.pontos.length - 1]
+    const renovou = anterior !== undefined && (
+      (anterior.renovaEm !== null && l.renovaEm !== null && Math.abs(anterior.renovaEm - l.renovaEm) > TOLERANCIA_DA_RENOVACAO_MS)
+      || (ultimo !== undefined && ultimo.pct - l.pct >= QUEDA_QUE_RENOVA))
+    const ponto = { em: agora, pct: l.pct }
+    janelas.push(anterior === undefined || renovou
+      ? { kind: l.kind, renovaEm: l.renovaEm, pontos: [ponto] }
+      : { kind: l.kind, renovaEm: l.renovaEm ?? anterior.renovaEm, pontos: acrescentar(anterior.pontos, ponto) })
+  }
+  return { formato: FORMATO_DA_SERIE, janelas: janelas.sort(porKind).slice(0, TETO_DE_JANELAS) }
+}
+
+/**
+ * O ritmo da janela, em pontos por ms, no intervalo recente (D13). Como o uso so cresce, o valor no inicio do
+ * intervalo sai dos pontos que o cercam: exato quando o ultimo antes e o primeiro dentro sao iguais, e por
+ * interpolacao quando nao sao; com leitura esparsa (D12), isso da a inclinacao desde o ultimo ponto antes do
+ * intervalo. Serie mais nova que o intervalo precisa de `minimoDaSerieJovem` entre a primeira e a ultima
+ * leitura; antes disso, nao ha ritmo.
+ */
+export function ritmoDaJanela(j: Pick<ClimaJanela, 'kind' | 'pontos'>): number | null {
+  const ultimo = j.pontos[j.pontos.length - 1]
+  const primeiro = j.pontos[0]
+  if (ultimo === undefined || primeiro === undefined) return null
+  const intervalo = intervaloDoRitmo(j.kind)
+  const inicio = ultimo.em - intervalo
+  const antes = [...j.pontos].reverse().find(p => p.em < inicio)
+  const dentro = j.pontos.find(p => p.em >= inicio)
+  if (antes !== undefined && dentro !== undefined) {
+    const noInicio = antes.pct === dentro.pct ? antes.pct
+      : antes.pct + (dentro.pct - antes.pct) * (inicio - antes.em) / (dentro.em - antes.em)
+    return (ultimo.pct - noInicio) / intervalo
+  }
+  if (ultimo.em - primeiro.em < minimoDaSerieJovem(j.kind)) return null
+  return (ultimo.pct - primeiro.pct) / (ultimo.em - primeiro.em)
+}
+
+/** Pontos por hora com uma casa, ou duas abaixo de 1, para o ritmo lento da semana nao virar zero (D14). */
+function arredondarRitmo(porHora: number): number {
+  return Math.abs(porHora) < 1 ? Math.round(porHora * 100) / 100 : Math.round(porHora * 10) / 10
+}
+
+/** A previsao de cada janela que ainda nao renovou, da mais urgente para a mais calma. */
+export function prever(guardado: unknown, agora: number): ClimaPrevisao[] {
+  const previsoes: ClimaPrevisao[] = []
+  for (const j of lerSerie(guardado).janelas) {
+    const ultimo = j.pontos[j.pontos.length - 1]
+    if (ultimo === undefined || vencida(j, agora)) continue
+    const ritmoPorMs = ritmoDaJanela(j)
+    let estado: ClimaEstado
+    let acabaEm: number | null = null
+    if (ultimo.pct >= 100) estado = 'esgotada'
+    else if (ritmoPorMs === null) estado = 'sem-ritmo'
+    else if (ritmoPorMs <= 0) estado = 'folga'
+    else {
+      acabaEm = Math.round(ultimo.em + (100 - ultimo.pct) / ritmoPorMs)
+      const horizonte = horizonteDaSerie(j)
+      if (j.renovaEm !== null && acabaEm >= j.renovaEm) estado = 'folga'
+      else if (horizonte !== null && acabaEm - ultimo.em > horizonte) {
+        // A serie jovem nao preve alem do que ja observou (D15).
+        estado = 'sem-ritmo'
+        acabaEm = null
+      } else estado = 'acaba-antes'
+    }
+    previsoes.push({
+      kind: j.kind, rotulo: rotuloDaJanela(j.kind), pct: ultimo.pct, lidaEm: ultimo.em, renovaEm: j.renovaEm,
+      ritmoPorHora: ritmoPorMs === null ? null : arredondarRitmo(ritmoPorMs * 3600 * 1000), acabaEm, estado,
+    })
+  }
+  return previsoes.sort((a, b) => GRAVIDADE[a.estado] - GRAVIDADE[b.estado] || porKind(a, b))
+}
+
+/** A janela ja se esgotou ou acaba antes de renovar no ritmo atual. */
+export function emAlerta(p: ClimaPrevisao): boolean {
+  return p.estado === 'esgotada' || p.estado === 'acaba-antes'
+}
+
+/** A janela pede atencao na faixa: em alerta, ou no limiar mesmo sem ritmo (D5). */
+export function pedeAtencao(p: ClimaPrevisao): boolean {
+  return emAlerta(p) || p.pct >= LIMIAR_DE_ATENCAO
+}
+
+type Partes = { ano: string; mes: string; dia: string; hora: string; minuto: string }
+
+function partesLocais(ms: number, fuso: string): Partes {
+  let f: Intl.DateTimeFormat
+  try {
+    f = new Intl.DateTimeFormat('en-US', { timeZone: fuso, year: 'numeric', month: '2-digit', day: '2-digit',
+      hour: '2-digit', minute: '2-digit', hourCycle: 'h23' })
+  } catch {
+    f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC', year: 'numeric', month: '2-digit', day: '2-digit',
+      hour: '2-digit', minute: '2-digit', hourCycle: 'h23' })
+  }
+  const p: Record<string, string> = {}
+  for (const parte of f.formatToParts(new Date(ms))) p[parte.type] = parte.value
+  return { ano: p.year ?? '', mes: p.month ?? '', dia: p.day ?? '', hora: p.hour ?? '', minuto: p.minute ?? '' }
+}
+
+/**
+ * A hora no fuso, com o minuto truncado como o nucleo escreve: `16:40` no mesmo dia de `agora`, `13/10 09:00`
+ * em outro dia e `13/10/2027 09:00` em outro ano.
+ */
+export function formatarHora(ms: number, fuso: string, agora: number): string {
+  const p = partesLocais(ms, fuso)
+  const a = partesLocais(agora, fuso)
+  if (p.ano === a.ano && p.mes === a.mes && p.dia === a.dia) return `${p.hora}:${p.minuto}`
+  return `${p.dia}/${p.mes}${p.ano !== a.ano ? `/${p.ano}` : ''} ${p.hora}:${p.minuto}`
+}
+
+/** `45min`, `1h30`, `2d 05h`, como o nucleo escreve; abaixo de 1 min, `menos de 1 min`. */
+export function duracao(ms: number): string {
+  const minutos = Math.floor(Math.abs(ms) / 60000)
+  if (minutos < 1) return 'menos de 1 min'
+  if (minutos < 60) return `${minutos}min`
+  const horas = Math.floor(minutos / 60)
+  if (horas < 24) return `${horas}h${String(minutos % 60).padStart(2, '0')}`
+  return `${Math.floor(horas / 24)}d ${String(horas % 24).padStart(2, '0')}h`
+}
+
+/** `em 1h30` ou `há 10min`, relativo a `agora`. */
+export function distancia(ms: number, agora: number): string {
+  return ms >= agora ? `em ${duracao(ms - agora)}` : `há ${duracao(agora - ms)}`
+}
+
+/** O numero com virgula decimal e no maximo `casas` casas. */
+export function numeroBr(n: number, casas = 1): string {
+  const fator = 10 ** casas
+  return String(Math.round(n * fator) / fator).replace('.', ',')
+}
+
+/** O percentual da faixa em degraus: `70% ou mais`, ou `menos de 10%` (D13). */
+export function percentualEmDegrau(pct: number): string {
+  const degrau = Math.floor(pct / DEGRAU_DO_PERCENTUAL) * DEGRAU_DO_PERCENTUAL
+  return degrau <= 0 ? `menos de ${DEGRAU_DO_PERCENTUAL}%` : `${degrau}% ou mais`
+}
+
+/**
+ * O trecho de uma janela na faixa: percentual em degraus e hora de acabar arredondada para baixo ao quarto de
+ * hora (D13), que assim nunca passa da renovacao (D14). A hora que nao fica depois da leitura vira `acaba em
+ * instantes` (D15).
+ */
+function trechoDaFaixa(p: ClimaPrevisao, fuso: string, agora: number): string {
+  const renova = p.renovaEm === null ? '' : `, renova ${formatarHora(p.renovaEm, fuso, agora)}`
+  if (p.estado === 'esgotada') return `${p.rotulo} esgotou${renova}`
+  if (p.estado === 'acaba-antes' && p.acabaEm !== null) {
+    const acaba = Math.floor(p.acabaEm / PASSO_DA_HORA_NA_FAIXA_MS) * PASSO_DA_HORA_NA_FAIXA_MS
+    const quando = acaba > p.lidaEm ? `acaba ~${formatarHora(acaba, fuso, agora)}` : 'acaba em instantes'
+    return `${p.rotulo} com ${percentualEmDegrau(p.pct)}, ${quando}${renova}`
+  }
+  return `${p.rotulo} com ${percentualEmDegrau(p.pct)}${renova}`
+}
+
+function cortar(texto: string, teto: number): string {
+  return texto.length <= teto ? texto : texto.slice(0, teto - 1) + '…'
+}
+
+/**
+ * A linha do Clima na faixa da ponte, ou `null` quando nenhuma janela pede atencao (a linha sai). As threads
+ * que nao cabem vem primeiro, porque a faixa corta o fim da linha (D13).
+ */
+export function textoDaFaixa(previsoes: readonly ClimaPrevisao[], fuso: string, agora: number, naoCabem: readonly string[] = []): string | null {
+  const trechos = previsoes.filter(pedeAtencao).map(p => trechoDaFaixa(p, fuso, agora))
+  if (trechos.length === 0) return null
+  const nomeadas = naoCabem.slice(0, TETO_NA_FAIXA)
+  const mais = naoCabem.length > nomeadas.length ? ` e mais ${naoCabem.length - nomeadas.length}` : ''
+  const inicio = nomeadas.length > 0 ? `não cabe: ${nomeadas.join(', ')}${mais}; ` : ''
+  return cortar(inicio + trechos.join(' · '), TETO_DA_FAIXA)
+}
+
+/** `às 14:30` hoje, `em 11/10 14:30` em outro dia. */
+function quandoLida(ms: number, fuso: string, agora: number): string {
+  const hora = formatarHora(ms, fuso, agora)
+  return hora.includes('/') ? `em ${hora}` : `às ${hora}`
+}
+
+/** Uma janela no `/clima`, com o ritmo, a previsao, a renovacao, as distancias e a hora da leitura. */
+export function linhaDaJanela(p: ClimaPrevisao, fuso: string, agora: number): string {
+  const ritmo = p.ritmoPorHora === null ? 'ritmo ainda sem leituras suficientes'
+    : `ritmo de ${numeroBr(p.ritmoPorHora, Math.abs(p.ritmoPorHora) < 1 ? 2 : 1)} pontos por hora`
+  let previsao: string
+  if (p.estado === 'esgotada') previsao = 'esgotou'
+  else if (p.estado === 'acaba-antes' && p.acabaEm !== null) {
+    previsao = `acaba ~${formatarHora(p.acabaEm, fuso, agora)} (${distancia(p.acabaEm, agora)}), antes de renovar`
+  } else if (p.estado === 'folga') previsao = 'folga no ritmo atual'
+  else previsao = 'sem previsão ainda'
+  const renova = p.renovaEm === null ? 'sem hora de renovação' : `renova ${formatarHora(p.renovaEm, fuso, agora)} (${distancia(p.renovaEm, agora)})`
+  return `- ${p.rotulo}: ${numeroBr(p.pct)}%, ${ritmo}, ${previsao}, ${renova}. Lida ${quandoLida(p.lidaEm, fuso, agora)}.`
+}
+
+/** O problema da ultima medicao numa linha: `A medicao falhou (...) as 14:30.` (D15). */
+export function textoDoProblema(p: ClimaProblema, fuso: string, agora: number): string {
+  const quando = p.em === null ? '' : ` ${quandoLida(p.em, fuso, agora)}`
+  return `${p.motivo.charAt(0).toUpperCase()}${p.motivo.slice(1)}${quando}.`
+}
+
+/**
+ * O texto do `/clima`: as janelas da conta desta sessao, o problema da ultima medicao, o que vier depois e o aviso
+ * de autoridade. Com problema guardado, a falta de leitura nao e atribuida a conta (D15).
+ */
+export function textoDoClima(previsoes: readonly ClimaPrevisao[], fuso: string, agora: number, extras: readonly string[] = [],
+  problema: ClimaProblema | null = null): string {
+  const linhas = ['Clima de cota da conta desta sessão']
+  if (previsoes.length > 0) {
+    for (const p of previsoes) linhas.push(linhaDaJanela(p, fuso, agora))
+  } else if (problema === null) {
+    linhas.push('Sem leitura de cota ainda. A leitura chega na medição depois de uma resposta da API desta sessão, e só existe em conta de assinatura.')
+  } else {
+    linhas.push('Sem leitura de cota guardada.')
+  }
+  if (problema !== null) linhas.push(textoDoProblema(problema, fuso, agora))
+  return [...linhas, ...extras, AVISO_DE_AUTORIDADE].join('\n')
+}
+
+/** O `/clima` fora da sessao do dono: o Clima so roda nela (D3). */
+export function textoForaDoDono(papel: string): string {
+  const base = `O Clima de Cota só roda na sessão do dono de um projeto do Orkastery; o papel desta sessão é ${papel}.`
+  return papel === 'dormente' ? `${base} Se o servidor orkastery ainda está conectando, tente de novo em instantes.` : base
+}
+
+/** O `/clima` sem a ponte, de quem o Clima depende para tudo; o erro interno nao vai ao dono (D13). */
+export const TEXTO_SEM_PONTE = 'O Clima de Cota depende da ponte ork-ponte, que não respondeu nesta sessão; confira se ela está instalada e carregada.'
+/** O mesmo motivo, como problema da medicao (D15). */
+export const MOTIVO_SEM_PONTE = 'a ponte ork-ponte não respondeu; confira se ela está instalada e carregada'
+
+/** O motivo de um erro em uma linha curta. */
+export function motivoDoErro(erro: unknown): string {
+  const texto = erro instanceof Error ? erro.message : String(erro)
+  return texto.replace(/\s+/g, ' ').trim().slice(0, 200)
+}

package/adapters/claude-code/mods/ork-clima/hooks/register.ts

@@ -0,0 +1,205 @@
+// O Clima de Cota (RM-059, onda 1, F4). Le as janelas de limite da conta desta sessao a cada medicao do
+// motor, guarda a serie no `$.store` do mod, preve quando cada janela acaba no ritmo atual e avisa na faixa
+// da ponte antes de a fase morrer no meio, com as retomadas que nao cabem (T4.2). So na sessao do dono, so
+// le e so avisa: troca de conta, runtime ou modelo fica com o nucleo (rodizio) e com o dono. O `$.ork` vem
+// da `ork-ponte`; a logica fica nos modulos puros ao lado, e aqui so as chamadas ao `$`, sempre escritas
+// pelo nome do noun e do metodo, como o validador exige.
+import type { Register } from 'claude-code'
+import type { ClimaNaoCabe, ClimaProblema } from '../types'
+import {
+  cruzar, linhasDoCruzamento, marcasDoRelatorio, naoCabemGuardados, paradasDoRetrato, resumoDoClima, retomadasDaFila,
+  textoDoNaoCabe, threadsAbertas, threadsQueNaoCabem,
+} from './contas'
+import {
+  CHAVE_DA_SERIE, emAlerta, MOTIVO_SEM_PONTE, motivoDoErro, prever, problemaDaLeitura, registrarLeituras, TEXTO_SEM_PONTE,
+  textoDaFaixa, textoDoClima, textoForaDoDono,
+} from './previsao'
+
+const MOD = 'ork-clima'
+const FAIXA = { plugin: 'ork-clima', key: 'faixa' } as const
+const NAO_CABEM = { plugin: 'ork-clima', key: 'naoCabem' } as const
+const PROBLEMA = { plugin: 'ork-clima', key: 'problema' } as const
+
+/** O fuso da sessao (D6): a ponte nao entrega o `owner.timezone`. */
+function fusoDaSessao(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'
+  } catch {
+    return 'UTC'
+  }
+}
+
+export const register: Register = on => {
+  // O `/clima` fica disponivel fora da sessao de fase (D3), e tambem sem a ponte, para dizer o motivo. A faixa
+  // so sai na primeira medicao: antes de o servidor `orkastery` conectar, a ponte ainda responde `dormente`.
+  // O registro recusado nao segura o inicio da sessao, mas o motivo vai ao transcript (D15).
+  on('session.start', async ($, e, next) => {
+    let papel: string | null = null
+    try {
+      papel = await $.ork.papel()
+    } catch {
+      papel = null
+    }
+    if (papel !== 'fase') {
+      await $.command.register({ name: 'clima', description: 'Previsão da cota da conta desta sessão: quando cada janela acaba no ritmo atual' })
+        .catch(erro => $.ui.log(`Clima de Cota: o /clima não foi registrado (${motivoDoErro(erro)}).`))
+    }
+    return next(e)
+  })
+
+  // Cada medicao: grava a leitura quando as janelas mudaram (D2) e republica a faixa so quando o texto muda (D5).
+  // Com janela em alerta e leitura nova, le a fila inteira de retomada e guarda as que nao cabem (D7, D13); a
+  // medicao sem leitura nova usa o que ficou guardado. So vai ao registro do mostrado o que a faixa mostrou, e o
+  // registro que falhar fica pendente para a medicao seguinte (D15). Fora do papel `dono`, a linha sai (D13).
+  // Uma falha nunca segura a medicao: o motivo novo vai uma vez ao transcript e fica no estado para o `/clima`,
+  // ate uma medicao boa limpa-lo (D15).
+  on('session.measure', async ($, e, next) => {
+    let agora: number | null = null
+    let problema: ClimaProblema | null = null
+    let semLeituraNova = false
+    try {
+      agora = await $.clock.now()
+      let papel: string | null = null
+      try {
+        papel = await $.ork.papel()
+      } catch {
+        papel = null
+      }
+      const anterior = await $.state.get(FAIXA)
+      if (papel === null) {
+        problema = { motivo: MOTIVO_SEM_PONTE, em: agora, daLeitura: false }
+      } else if (papel !== 'dono') {
+        if ((anterior.value ?? null) !== null) {
+          await $.ork.faixa({ mod: MOD })
+          await $.state.set(FAIXA, null, { ifVersion: anterior.version })
+        }
+      } else {
+        const fuso = fusoDaSessao()
+        const leu = e.changed.includes('rateLimits')
+        semLeituraNova = !leu
+        let serie = await $.store.get(CHAVE_DA_SERIE)
+        if (leu) {
+          const motivo = problemaDaLeitura(e.rateLimits)
+          if (motivo !== null) problema = { motivo, em: agora, daLeitura: true }
+          // A medicao sem a lista de janelas nao apaga a serie guardada (D15).
+          if (Array.isArray(e.rateLimits)) {
+            serie = registrarLeituras(serie, e.rateLimits, agora)
+            await $.store.set(CHAVE_DA_SERIE, serie)
+          }
+        }
+        const previsoes = prever(serie, agora)
+        const alerta = previsoes.some(emAlerta)
+        const guardados = await $.state.get(NAO_CABEM)
+        let naoCabem: ClimaNaoCabe[] = alerta ? naoCabemGuardados(guardados.value) : []
+        if (alerta && leu) {
+          try {
+            const fila = retomadasDaFila(await $.ork.ler({ consulta: 'retry.list' }))
+            if (fila !== null) {
+              const antes = naoCabem
+              const lidaEm = agora
+              naoCabem = cruzar(previsoes, fila, lidaEm).filter(d => d.classe === 'nao-cabe').map(d =>
+                antes.find(n => n.id === d.retomada.id)
+                  ?? { id: d.retomada.id, thread: d.retomada.thread, texto: textoDoNaoCabe(d, fuso, lidaEm), registrada: false })
+            }
+          } catch {
+            // Fila indisponivel: vale o que a ultima leitura deixou, e o `/clima` diz o motivo quando le a fila.
+          }
+        }
+        let versao = guardados.version
+        if (JSON.stringify(naoCabem) !== JSON.stringify(guardados.value ?? [])) {
+          versao = (await $.state.set(NAO_CABEM, naoCabem, { ifVersion: guardados.version })).version
+        }
+        const threads = naoCabem.map(n => n.thread).filter((t, i, todas) => todas.indexOf(t) === i)
+        const texto = textoDaFaixa(previsoes, fuso, agora, threads)
+        let mostrada = (anterior.value ?? null) === texto
+        if (!mostrada) {
+          const r = await $.ork.faixa(texto === null ? { mod: MOD } : { mod: MOD, texto })
+          if (texto === null || r.publicada) {
+            await $.state.set(FAIXA, texto, { ifVersion: anterior.version })
+            mostrada = true
+          }
+        }
+        if (mostrada && texto !== null && naoCabem.some(n => !n.registrada)) {
+          const registradas: ClimaNaoCabe[] = []
+          for (const n of naoCabem) {
+            if (n.registrada) {
+              registradas.push(n)
+              continue
+            }
+            try {
+              await $.ork.mostrado({ mod: MOD, canal: 'faixa', chave: `clima:nao-cabe:${n.id}`, thread: n.thread, texto: n.texto })
+              registradas.push({ ...n, registrada: true })
+            } catch (erro) {
+              registradas.push(n)
+              if (problema === null) problema = { motivo: `o registro do mostrado na ponte falhou (${motivoDoErro(erro)})`, em: agora, daLeitura: false }
+            }
+          }
+          naoCabem = registradas
+          await $.state.set(NAO_CABEM, naoCabem, { ifVersion: versao })
+        }
+      }
+    } catch (erro) {
+      problema = { motivo: `a medição falhou (${motivoDoErro(erro)})`, em: agora, daLeitura: false }
+    }
+    try {
+      const guardado = await $.state.get(PROBLEMA)
+      const antes = guardado.value ?? null
+      const depois = problema ?? (semLeituraNova && antes !== null && antes.daLeitura ? antes : null)
+      if (JSON.stringify(depois) !== JSON.stringify(antes)) {
+        await $.state.set(PROBLEMA, depois, { ifVersion: guardado.version })
+        // So o motivo novo vai ao transcript: a falha que se repete a cada medicao nao enche a tela.
+        if (depois !== null && depois.motivo !== antes?.motivo) $.ui.log(`Clima de Cota: ${depois.motivo}. O /clima mostra o que ficou guardado.`)
+      }
+    } catch (erro) {
+      $.ui.log(`Clima de Cota: o problema da medição não foi guardado (${motivoDoErro(erro)}).`, { to: 'debug' })
+    }
+    return next(e)
+  })
+
+  // O `/clima` le a serie guardada e nao grava ponto: o uso pedido na hora repete a ultima resposta, e um ponto
+  // com a hora de agora achataria o ritmo (D2). Le a fila, o retrato, as threads abertas e o registro de contas
+  // ao mesmo tempo (D3, D13); leitura que falha vira aviso no texto, o problema da ultima medicao aparece (D15), e
+  // o que foi mostrado vai ao registro da ponte (D8).
+  on('command.run', { command: 'clima' }, async $ => {
+    const agora = await $.clock.now()
+    const fuso = fusoDaSessao()
+    let papel: string
+    try {
+      papel = await $.ork.papel()
+    } catch {
+      return { text: TEXTO_SEM_PONTE }
+    }
+    if (papel !== 'dono') return { text: textoForaDoDono(papel) }
+    const previsoes = prever(await $.store.get(CHAVE_DA_SERIE), agora)
+    const problema = (await $.state.get(PROBLEMA)).value ?? null
+    const ler = (p: Promise<unknown>) => p.then(valor => ({ ok: true as const, valor }), erro => ({ ok: false as const, erro: motivoDoErro(erro) }))
+    const [fila, retrato, abertas, registro] = await Promise.all([
+      ler($.ork.ler({ consulta: 'retry.list' })),
+      ler($.ork.retrato().then(r => r.retrato)),
+      ler($.ork.ler({ consulta: 'thread.list' })),
+      ler($.ork.ler({ consulta: 'accounts.esgotamentos' })),
+    ])
+    const retomadas = fila.ok ? retomadasDaFila(fila.valor) : null
+    const despachos = retomadas === null ? null : cruzar(previsoes, retomadas, agora)
+    // Sem a lista de threads abertas, as paradas nao sao conferidas: o retrato tambem traz thread fechada (D14).
+    const listaDeAbertas = abertas.ok ? threadsAbertas(abertas.valor) : null
+    const linhas = linhasDoCruzamento({
+      despachos, erroDaFila: fila.ok ? null : fila.erro,
+      paradas: retrato.ok && listaDeAbertas !== null ? paradasDoRetrato(retrato.valor, listaDeAbertas) : null,
+      erroDoRetrato: !retrato.ok ? retrato.erro
+        : listaDeAbertas === null ? `sem a lista de threads abertas: ${abertas.ok ? 'fora do formato' : abertas.erro}` : null,
+      marcas: registro.ok ? marcasDoRelatorio(registro.valor) : null, erroDoRegistro: registro.ok ? null : registro.erro,
+    }, previsoes, fuso, agora)
+    const naoCabem = (despachos ?? []).filter(d => d.classe === 'nao-cabe')
+    try {
+      await $.ork.mostrado({ mod: MOD, canal: 'transcript', chave: 'clima:consulta', texto: resumoDoClima(previsoes, threadsQueNaoCabem(naoCabem), fuso, agora) })
+      for (const d of naoCabem) {
+        await $.ork.mostrado({ mod: MOD, canal: 'transcript', chave: `clima:nao-cabe:${d.retomada.id}`, thread: d.retomada.thread,
+          texto: textoDoNaoCabe(d, fuso, agora) })
+      }
+    } catch {
+      // O registro do mostrado e melhor esforco: o texto chega ao dono de qualquer jeito, e cada `/clima` registra de novo.
+    }
+    return { text: textoDoClima(previsoes, fuso, agora, linhas, problema) }
+  })
+}

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

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