@orkastery/cli 0.5.3 → 0.5.6

package/adapters/claude-code/README.md

@@ -151,6 +151,164 @@ Sem `tool_use_id`, cada invocação do hook recebe uma identidade de ocorrência
 do transcript não identifica uma ocorrência; eventos de um novo episódio de permissão
 podem chegar sem alteração do arquivo. Replays com `tool_use_id` continuam idempotentes.
 
+## Mods nas sessões de fase (RM-059)
+
+Mod é plugin de *function hooks* do Claude Code 2.1.287 ou mais novo. Cada mod do Orkastery mora
+em `adapters/claude-code/mods/<mod>/`, com o próprio `.claude-plugin/plugin.json`, e declara o
+papel em `orkastery-mod.json`:
+
+```json
+{"formato":"ork.mod/v1","papeis":["fase"],"claudeCodeMinimo":"2.1.287"}
+```
+
+O papel `dono` roda na sessão de quem conduz; o papel `fase`, nas sessões de fase que o `ork`
+despacha. O `ork adapter install claude-code` copia os mods com o resto do adaptador e grava cada
+arquivo deles no `INSTALADO.json`. No despacho `claude-bg`, cada mod de papel `fase` entra com o
+próprio `--plugin-dir`, logo depois do plugin do Orkastery, quando:
+
+- a pasta instalada do mod tem exatamente os arquivos do recibo, com os mesmos bytes e sem link;
+  os tipos que o próprio Claude Code escreve em `.claude-plugin/types/` (`*.d.ts` e
+  `tsconfig.json`) ficam fora da conta;
+- o `claude --version` atende o `claudeCodeMinimo` do mod e o 2.1.287 da API de mods.
+
+Mod que pede versão mais nova fica fora do comando, e o despacho segue: o núcleo não depende de
+mod. Mod cuja dependência ficou de fora (pela versão, ou por ser só de papel `dono`) também fica.
+Declaração inválida, manifesto fora do recibo ou arquivo a mais na pasta recusa o despacho com
+`runtime.context.installation`, como um byte divergente. Arquivo de mod que saiu do catálogo sai da
+cópia na reinstalação: o `ork adapter install claude-code` tira o que ele mesmo instalou e ninguém
+editou. Arquivo editado ou acrescentado à mão fica, e a recusa diz o caminho para apagar. A dependência (`dependencies` do
+`plugin.json` do mod) entra antes de quem depende; o resto segue o nome. Os mods que foram ficam no
+comando gravado no evento `phase_dispatch` do ledger da thread.
+
+O arquivo comum da raiz de `mods/`, como a lista de autoridade que a ponte lê em `../autoridade.json`
+antes da própria pasta, segue a mesma regra quando há mod de fase no despacho: fora do recibo, link
+ou arquivo especial recusam, e o que saiu do catálogo sai da cópia na reinstalação.
+
+Para tirar um mod das sessões de fase, mude o papel no `orkastery-mod.json` do catálogo, ou tire o
+mod, e rode `ork adapter install claude-code` de novo.
+
+O mod de papel `dono` não vai ao despacho: ele roda na sessão de quem conduz. Num projeto com o
+adaptador instalado, a cópia dele já está em `.claude/plugins/orkastery/mods/<mod>`, com cada
+arquivo registrado no `INSTALADO.json` e os arquivos comuns da raiz de `mods/` ao lado. Nesse
+carregamento ninguém confere os bytes: a conferência contra o recibo roda no despacho, para mod de
+fase. Carregue-a na sessão com:
+
+```bash
+claude --plugin-dir .claude/plugins/orkastery/mods/<mod>
+```
+
+Sem o adaptador local, cada mod tem uma entrada no marketplace próprio do repositório
+(`.claude-plugin/marketplace.json`, gerado por `node core/scripts/gerar-marketplaces.cjs`), que aponta
+para uma cópia gerada em `marketplaces/claude-code/mods/<mod>/`. Instalado pelo marketplace, o plugin
+é só a própria pasta, então o arquivo comum da raiz de `adapters/claude-code/mods/` (a lista de
+autoridade da ponte, por exemplo) vai dentro de cada cópia. A instalação é no escopo do projeto:
+
+```bash
+claude plugin marketplace add orkastery/orkastery
+claude plugin install <mod>@orkastery --scope project
+```
+
+Os dois marketplaces se chamam `orkastery`, e o local, registrado na instalação acima a partir de
+`.claude/plugins/orkastery`, não lista os mods. Não troque um pelo outro num projeto que usa o
+plugin do adaptador: remover um marketplace desinstala os plugins que vieram dele (medido no
+Claude Code 2.1.296), e o plugin do marketplace do repositório não traz o guard `PreToolUse` nem o
+MCP do adaptador.
+
+### Freio de Lote (`ork-freio`)
+
+O primeiro mod de papel `fase`. Na sessão de fase, depois de cada lote de ferramentas, ele:
+
+- acha os arquivos que o lote mexeu: os caminhos de `Edit`, `Write`, `MultiEdit` e `NotebookEdit` e a
+  diferença do `git status` entre um lote e outro, que pega também a edição feita por `Bash`;
+- acha as claims da thread que citam esses arquivos, pelo `arquivo` ou pelo texto do comando, e avisa
+  quando o lote mexeu fora dos `touch_paths` do plano;
+- pede ao núcleo, em segundo plano, a conferência dessas claims com
+  `ork claims conferir <thread> --claims ... --json`, no sandbox do verify, uma rodada por vez;
+- devolve ao modelo, no lote seguinte do laço principal, o que quebrou: o id da claim, o comando e o
+  fim da saída. Lote sem claim afetada passa sem texto, e a linha de status mostra as claims em risco.
+  O lote de um subagente conta os arquivos tocados, mas não leva a entrega nem o aviso.
+
+O Freio nunca roda o comando de uma claim, nunca grava estado de claim e nunca para o laço: quem
+verifica de verdade continua sendo o `ork verify`. Ele lê o papel e a thread pelo `$.ork` da ponte, e
+as claims e o plano pelas ferramentas de leitura `ork_claims_list` e `ork_artifact_read`, nunca do
+disco em `.orkastery/`. Precisa de um `ork` com `ork claims conferir` no `PATH` da sessão; sem ele, ou
+sem o sandbox do verify, avisa uma vez que a conferência está indisponível e segue. Teste que cria
+processo pode reprovar no sandbox e passar no `ork verify`, e o aviso diz isso junto da falha. O
+resultado chega no lote seguinte: se a sessão terminar antes dele, a última conferência fica sem
+entrega. Falha de claim cujo arquivo foi tocado de novo durante a conferência não é entregue, porque
+uma conferência nova já foi pedida. Um `Edit` que falhou também conta como toque e pode pedir uma
+conferência a mais.
+
+### Portão de Tarefas (`ork-portao`)
+
+O segundo mod de papel `fase`. Os portões do quadro agem só na sessão de fase cujo bloco atual tem o GO
+(pelo slug do bloco no retrato do núcleo) e cuja thread tem plano com ao menos uma tarefa `T<n>` que
+serve ao quadro: com `touch_paths` (caminhos entre crases, com barra, ponto ou curinga) e um verify com um
+comando só entre crases, a regra do `ork claims conferir --tarefa`. Plano sem nenhuma tarefa assim não
+ganha portão, para não travar o quadro do GO. Com o portão ligado:
+
+- **criação:** `TaskCreated` recusa a tarefa cujo assunto não traz o id de uma tarefa do plano
+  (`T2.1 ...`), ou cuja tarefa do plano não serve ao quadro. A recusa volta ao modelo com o motivo e as
+  tarefas do plano que servem;
+- **conclusão:** `TaskCompleted` da tarefa registrada na criação, ou da que cita no assunto uma tarefa do
+  plano que serve, pede ao núcleo `ork claims conferir <thread> --tarefa T2.1 --prazo 540 --json`, no
+  sandbox do verify, e só deixa a tarefa fechar com o item aprovado. Reprovação volta com o comando, o
+  código e o fim da saída; sem veredito, recusa tipada, outra condução na thread, conferência que não roda
+  ou falha do próprio Portão também bloqueiam, sempre com a saída: corrigir e concluir de novo, ou devolver
+  a tarefa para `pending` e seguir. A tarefa registrada continua conferida mesmo com o plano ilegível na
+  hora, porque o núcleo lê o plano por conta própria. Uma conferência por vez: a conclusão que chega no
+  meio de outra é recusada na hora. Da terceira reprovação igual em diante, o texto manda deixar a tarefa
+  aberta;
+- **teammate ocioso:** com agent teams no piloto (abaixo), `TeammateIdle` entrega ao teammate a próxima
+  tarefa do plano que serve, não fechou nesta sessão e cuja região está livre: nenhum lease `path:` ativo,
+  de nenhuma thread, cruza os `touch_paths` dela e ela não cruza as tarefas dos outros teammates. Os leases
+  vêm do retrato de todas as threads pela consulta `maestro` da ponte
+  (`ork maestro --json --section leases --offset N`), seguindo o `nextOffset` das páginas que o teto de
+  bytes do retrato corta, até 10 páginas, porque o servidor MCP da sessão de fase só mostra os da própria
+  thread. O Portão não toma nem solta lease: o `ork_git_commit` toma o `path:` de cada arquivo na hora do
+  commit e recusa o commit com qualquer lease no caminho. Quem fica ocioso sem concluir devolve a tarefa,
+  que sai da distribuição automática desta sessão. Sem a lista de leases inteira (seção indisponível,
+  lacuna, retrato em conflito ou mais de 10 páginas), no teto de custo ou sem tarefa livre, o teammate
+  fica ocioso.
+
+O Portão nunca roda o verify por conta própria: quem verifica de verdade continua sendo o `ork verify`.
+Ele lê o papel pelo `$.ork.contexto` da ponte, o estado e o bloco pelo `$.ork.retrato`, os leases pela
+consulta `maestro` da ponte e o plano pelo `ork_artifact_read`, nunca do disco em `.orkastery/`. Teste que
+cria processo pode reprovar no sandbox e passar no `ork verify`, e o bloqueio diz isso.
+
+Agent teams na sessão de fase só rodam no piloto, desligado por padrão. Quem conduz liga no manifesto da
+raiz:
+
+```yaml
+runtime:
+  agent_teams:
+    ligado: true
+    teammates: 2   # teto de teammates vivos, de 1 a 8
+    custo_usd: 10  # teto do custo da sessão, como o /cost soma, até 500
+```
+
+Com a chave ligada, o GO no bloco da fase atual e o Portão entre os mods que vão à sessão, o despacho
+`claude-bg` acrescenta ao `--settings` a variável `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`, os dois tetos
+(`ORK_AGENT_TEAMS_TEAMMATES` e `ORK_AGENT_TEAMS_CUSTO_USD`) e `teammateMode` `in-process`, porque a sessão
+de fundo não tem `tmux`. Teto inválido vira aviso do manifesto e deixa desligado. Em toda sessão de fase,
+com ou sem o portão do quadro, o Portão recusa o nascimento de teammate sem os tetos, no teto de teammates
+vivos ou com o custo da sessão no teto, e no teto de custo não entrega tarefa nova.
+
+Limites conhecidos:
+
+- o quadro do Portão vale para a sessão: numa sessão de GO redespachada, tarefa fechada na anterior pode
+  ser entregue de novo ao teammate, que a encontra pronta no quadro e no git;
+- o líder não recebe aviso quando um teammate devolve uma tarefa; ele a vê aberta no quadro;
+- a conferência do Freio, em segundo plano, e a do Portão, na conclusão, podem rodar ao mesmo tempo na
+  mesma worktree; cada mod só serializa as próprias;
+- os tetos dependem de o Portão carregar de verdade: o despacho decide pelo `--plugin-dir`, e se o mod não
+  registrar na sessão, agent teams fica ligado sem ninguém aplicando os tetos;
+- se o turno for interrompido no meio da conferência, o Claude Code segue sem a resposta do gancho;
+- nome de lease que o retrato redige (caminho absoluto ou texto com cara de segredo) chega irreconhecível e
+  não cruza nenhuma região;
+- o comportamento desses eventos numa sessão `claude --bg` real com agent teams ainda não foi medido; os
+  testes do kit e do núcleo cobrem o mod e o despacho.
+
 ## A #TAG de conducao
 
 O comando `/goal` extrai o modo do proprio pedido, sem reimplementar nada:

package/adapters/claude-code/mods/autoridade.json

@@ -0,0 +1,56 @@
+{
+  "formato": "ork.mods-autoridade/v1",
+  "regra": "Nenhum mod aprova gate, permissão, nota do MASTER, push ou tag pelo dono, nem fala como o dono (D5 do plano dos mods, com o nome que o dono deu a ela). A decisão autônoma registrada pelo núcleo não entra nesta lista: está em permitidos.",
+  "leitores": [
+    "core/scripts/checar-mods.cjs",
+    "adapters/claude-code/mods/ork-ponte/hooks/register.ts"
+  ],
+  "ganchosProibidos": [
+    { "id": "elicitation", "evento": "classic.Elicitation", "porque": "responderia o diálogo nativo do MCP no lugar do dono" },
+    { "id": "elicitation-result", "evento": "classic.ElicitationResult", "porque": "trocaria a resposta que o dono deu no diálogo nativo" },
+    { "id": "permission-request", "evento": "classic.PermissionRequest", "porque": "aprovaria permissão pelo dono" },
+    { "id": "ask-user-question", "evento": "ui.render", "componente": "AskUserQuestion", "porque": "redesenharia a pergunta feita ao dono" }
+  ],
+  "decisoesProibidas": [
+    { "id": "tool-check-allow", "evento": "tool.check", "decisao": "allow", "porque": "aprovaria uma chamada de ferramenta pelo dono" }
+  ],
+  "chamadasProibidas": [
+    { "id": "prompt-submit", "chamada": "prompt.submit", "porque": "manda texto como se fosse o dono" },
+    { "id": "session-append-usuario", "chamada": "session.append", "tipo": "user", "porque": "grava linha de usuário que o modelo lê como palavra do dono" }
+  ],
+  "argvProibido": [
+    { "id": "gate-answer", "sequencia": ["gate", "answer"], "porque": "responde gate pelo dono" },
+    { "id": "sessions-answer", "sequencia": ["sessions", "answer"], "porque": "entrega resposta a uma sessão como se fosse do dono" },
+    { "id": "pulse-responder", "sequencia": ["pulse", "responder"], "porque": "responde o resumo pelo dono" },
+    { "id": "master-nota", "sequencia": ["master"], "opcao": "--score", "porque": "dá ou propõe a nota do MASTER" },
+    { "id": "master-batch", "sequencia": ["master", "batch"], "porque": "aceita MASTER em lote pelo dono" },
+    { "id": "master-digest-responder", "sequencia": ["master", "digest", "responder"], "porque": "responde o digest pelo dono" },
+    { "id": "retry-run-por", "sequencia": ["retry", "run"], "opcao": "--por", "porque": "autoriza o retry quando o modo pausa" },
+    { "id": "ship-autorizar-push", "sequencia": ["ship"], "opcao": "--autorizar-push", "porque": "autoriza push pelo dono" },
+    { "id": "git-push", "programa": "git", "subcomando": "push", "porque": "publica sem a prova do núcleo" },
+    { "id": "git-tag", "programa": "git", "subcomando": "tag", "porque": "tag é ato do dono; listar tags sai por outro comando de leitura" },
+    { "id": "gh", "programa": "gh", "porque": "PR, merge e release ficam com o núcleo e o dono" }
+  ],
+  "ambienteProibido": [
+    { "id": "hitl-env", "prefixo": "ORK_HITL_", "porque": "credenciais e verificadores do ingresso humano" }
+  ],
+  "caminhosProibidos": [
+    { "id": "hermes-env", "trecho": ".hermes/.env", "porque": "segredos do canal do dono" }
+  ],
+  "reservadosAPonte": [
+    { "id": "processos", "evento": "process.*", "porque": "a guarda da ponte vigia os processos" },
+    { "id": "ambiente", "evento": "env.*", "porque": "a guarda vigia o ambiente, e o papel da sessão sai dele" },
+    { "id": "arquivos", "evento": "fs.*", "porque": "a guarda vigia leituras, e a lista de autoridade sai do disco" },
+    { "id": "mcp", "evento": "mcp.*", "porque": "o retrato do núcleo sai do MCP" },
+    { "id": "store", "evento": "store.*", "porque": "o registro do que foi mostrado ao dono fica no store da ponte" },
+    { "id": "estado", "evento": "state.*", "porque": "a faixa, os caminhos vigiados e o cache ficam no estado da ponte" },
+    { "id": "ferramentas", "evento": "tool.list", "porque": "o papel dono sai da lista de ferramentas" },
+    { "id": "raiz", "evento": "session.root", "porque": "o papel e a raiz do estado saem da raiz da sessão" },
+    { "id": "registro", "evento": "plugin.register", "porque": "só a ponte confere os mods que carregam" },
+    { "id": "prompt", "evento": "prompt.submit", "porque": "só a ponte decide sobre texto enviado por mod" },
+    { "id": "transcript", "evento": "session.append", "porque": "só a ponte decide sobre linha anexada por mod" }
+  ],
+  "permitidos": [
+    { "id": "decisao-autonoma", "sequencia": ["decisao", "registrar"], "porque": "decisão autônoma registrada pelo núcleo, com critério e evidência, que vai ao dono no lote seguinte com o custo de reverter (M4)" }
+  ]
+}

package/adapters/claude-code/mods/ork-clima/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "ork-clima",
+  "version": "0.1.0",
+  "description": "Clima de Cota do Orkastery no Claude Code: prevê quando a cota da conta acaba no ritmo atual, avisa na faixa antes de a fase morrer no meio e diz qual retomada não cabe. Só lê e avisa.",
+  "author": {
+    "name": "Orkastery contributors",
+    "url": "https://github.com/orkastery"
+  },
+  "homepage": "https://orkastery.com/",
+  "repository": "https://github.com/orkastery/orkastery",
+  "license": "MIT",
+  "types": "./types/index.d.ts",
+  "dependencies": ["ork-ponte"]
+}

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

@@ -0,0 +1,283 @@
+// O cruzamento do Clima de Cota (RM-059, onda 1, F4; T4.2): a previsao das janelas da conta desta sessao
+// contra os despachos que dependem de cota (a fila de retomada inteira, de `ork retry list --json`, e as
+// threads abertas paradas por cota, no retrato do nucleo) e contra as marcas de esgotamento por conta do
+// registro compartilhado (RM-040). D7, D8 e D13 a D15 da thread. Modulo puro: le o que a ponte trouxe, classifica
+// e escreve; nenhum `$` passa por aqui.
+import type { ClimaEstado, ClimaNaoCabe, ClimaPrevisao } from '../types'
+import { duracao, emAlerta, formatarHora, rotuloDaJanela, textoDaFaixa } from './previsao'
+
+/** Uma retomada da fila do nucleo que ainda vai despachar. */
+export type ClimaRetomada = {
+  id: string
+  thread: string
+  /** Quando a fila libera, em ms desde a epoca; `null` quando a fila nao disse. */
+  liberaEm: number | null
+  tentativas: number | null
+}
+
+/** Uma thread aberta cujo ultimo gate reprovado foi por cota. */
+export type ClimaParada = { thread: string; motivo: string }
+
+/**
+ * O que o retrato trouxe dos bloqueios: as paradas, se a pagina veio cortada e quantas threads ficaram sem ledger
+ * (`lacunasCortadas` quando o retrato cortou a lista de lacunas e o numero e um piso).
+ */
+export type ClimaParadas = { itens: ClimaParada[]; paginaCortada: boolean; lacunas: number; lacunasCortadas: boolean }
+
+/** Uma marca do registro compartilhado de contas (`ork.esgotamentos/v1`), com a conta opaca. */
+export type ClimaMarca = {
+  conta: string
+  runtime: string
+  estado: string
+  motivo: string
+  esgotadoAte: number | null
+  projeto: string
+}
+
+export type ClimaClasse = 'nao-cabe' | 'cabe' | 'depois-de-renovar'
+
+export type ClimaDespacho = {
+  retomada: ClimaRetomada
+  /** Quando a retomada despacha: a hora de liberar, ou agora se ja liberou. */
+  quando: number
+  classe: ClimaClasse
+  /** A janela que decide a classe; `null` sem janela em alerta. */
+  janela: string | null
+  estadoDaJanela: ClimaEstado | null
+  acabaEm: number | null
+  renovaEm: number | null
+  /** Na classe `cabe`, a cota que sobra no ritmo atual ate o primeiro esgotamento. */
+  folgaMs: number | null
+}
+
+/** O que o `/clima` cruzou: `null` onde a leitura falhou, com o motivo ao lado. */
+export type ClimaCruzamento = {
+  despachos: ClimaDespacho[] | null
+  erroDaFila: string | null
+  paradas: ClimaParadas | null
+  erroDoRetrato: string | null
+  marcas: ClimaMarca[] | null
+  erroDoRegistro: string | null
+}
+
+/** Os motivos de gate que sao de cota: a politica do nucleo espera a janela ou roda o perfil (D7). */
+export const MOTIVOS_DE_COTA: readonly string[] = ['runtime.quota-exhausted', 'runtime.rate-limited']
+export const CONTRATO_DOS_ESGOTAMENTOS = 'ork.esgotamentos/v1'
+/** O que o nucleo ja sabe fazer, com os comandos da propria politica dele; o Clima nunca executa (D7). */
+export const SUGESTOES: readonly string[] = [
+  'esperar a janela: a retomada fica na fila até renovar, e ork retry list mostra a fila;',
+  'seguir em outro perfil: ork accounts list mostra os perfis e quem está esgotado, e ork retry run <thread> segue no próximo perfil do rodízio;',
+  'adiar a fase: segurar o despacho da fase seguinte até a janela renovar.',
+]
+
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+const ID_DE_RETOMADA = /^R[1-9][0-9]{0,8}$/
+const CONTA_OPACA = /^[a-f0-9]{12}$/
+const NAO_REGISTRADO = 'nao registrado'
+const ORDEM_DA_CLASSE: Readonly<Record<ClimaClasse, number>> = { 'nao-cabe': 0, 'cabe': 1, 'depois-de-renovar': 2 }
+
+type Bruto = Record<string, unknown>
+
+function objeto(v: unknown): Bruto | null {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Bruto) : null
+}
+
+function texto(v: unknown, teto: number): string | null {
+  return typeof v === 'string' && v.trim() !== '' ? v.replace(/\s+/g, ' ').trim().slice(0, teto) : null
+}
+
+function instante(v: unknown): number | null {
+  const t = typeof v === 'string' ? Date.parse(v) : NaN
+  return Number.isFinite(t) ? t : null
+}
+
+/**
+ * As retomadas que ainda vao despachar, da fila inteira (`ork retry list --json`, D13): a fila e um JSONL so de
+ * acrescimo, entao a ultima gravacao de um id vence, e so o estado `aguardando` conta. `null` fora do formato.
+ */
+export function retomadasDaFila(fila: unknown): ClimaRetomada[] | null {
+  if (!Array.isArray(fila)) return null
+  const porId = new Map<string, Bruto>()
+  for (const bruto of fila) {
+    const p = objeto(bruto)
+    if (p !== null && typeof p.id === 'string' && ID_DE_RETOMADA.test(p.id)) porId.set(p.id, p)
+  }
+  const itens: ClimaRetomada[] = []
+  for (const p of porId.values()) {
+    if (p.estado !== 'aguardando' || typeof p.thread !== 'string' || !ID_DE_THREAD.test(p.thread)) continue
+    const tentativas = p.tentativas
+    itens.push({
+      id: p.id as string, thread: p.thread, liberaEm: instante(p.liberaEm),
+      tentativas: typeof tentativas === 'number' && Number.isInteger(tentativas) && tentativas >= 0 ? tentativas : null,
+    })
+  }
+  return itens
+}
+
+/** As threads abertas, de `ork thread list --json` (que sem `--todas` so lista as nao fechadas); `null` fora do formato. */
+export function threadsAbertas(lista: unknown): string[] | null {
+  const threads = objeto(lista)?.threads
+  if (!Array.isArray(threads)) return null
+  return threads.map(objeto).filter((t): t is Bruto => t !== null && typeof t.id === 'string' && t.status !== 'fechada')
+    .map(t => t.id as string)
+}
+
+function threadDasRefs(refs: unknown): string | null {
+  for (const r of Array.isArray(refs) ? refs : []) {
+    const o = objeto(r)
+    if (o?.kind === 'thread' && typeof o.id === 'string' && ID_DE_THREAD.test(o.id)) return o.id
+  }
+  return null
+}
+
+/**
+ * As threads paradas por cota, da secao `blockers` do retrato (D7), so as abertas quando a lista delas veio
+ * (o retrato tambem traz thread fechada). A pagina cortada e a lacuna de ledger sao ditas a parte (D13).
+ */
+export function paradasDoRetrato(retrato: unknown, abertas: readonly string[] | null): ClimaParadas {
+  const s = objeto(objeto(objeto(retrato)?.sections)?.blockers)
+  const itens: ClimaParada[] = []
+  const lista = s?.items
+  for (const bruto of Array.isArray(lista) ? lista : []) {
+    const i = objeto(bruto)
+    const motivo = objeto(i?.facts)?.reason
+    if (i === null || typeof motivo !== 'string' || !MOTIVOS_DE_COTA.includes(motivo)) continue
+    const thread = threadDasRefs(i.refs)
+    if (thread === null || (abertas !== null && !abertas.includes(thread)) || itens.some(p => p.thread === thread)) continue
+    itens.push({ thread, motivo })
+  }
+  const proxima = objeto(s?.coverage)?.nextOffset
+  const gaps = Array.isArray(s?.gaps) ? (s?.gaps as unknown[]).filter((g): g is string => typeof g === 'string') : []
+  const lacunas = gaps.filter(g => g.startsWith('ledger.unavailable:')).length
+  // O retrato guarda so as primeiras lacunas e conta o resto em `maestro.messages.omitted:N` (D14).
+  return { itens, paginaCortada: typeof proxima === 'number', lacunas, lacunasCortadas: gaps.some(g => g.startsWith('maestro.messages.omitted:')) }
+}
+
+/** As marcas do registro de contas; `null` quando o relatorio nao e do contrato `ork.esgotamentos/v1`. */
+export function marcasDoRelatorio(relatorio: unknown): ClimaMarca[] | null {
+  const r = objeto(relatorio)
+  if (r === null || r.contrato !== CONTRATO_DOS_ESGOTAMENTOS || !Array.isArray(r.marcas)) return null
+  const marcas: ClimaMarca[] = []
+  for (const bruta of r.marcas) {
+    const m = objeto(bruta)
+    if (m === null || typeof m.conta !== 'string' || !CONTA_OPACA.test(m.conta)) continue
+    const runtime = texto(m.runtime, 40)
+    const estado = texto(m.estado, 40)
+    if (runtime === null || estado === null) continue
+    marcas.push({
+      conta: m.conta, runtime, estado, motivo: texto(m.motivo, 80) ?? 'sem motivo',
+      esgotadoAte: instante(m.esgotadoAte), projeto: texto(m.projeto, 80) ?? NAO_REGISTRADO,
+    })
+  }
+  return marcas
+}
+
+/** O trecho sem cota de uma janela em alerta: do esgotamento (ou da leitura, se ja esgotou) ate renovar. */
+function trechoSemCota(p: ClimaPrevisao): { p: ClimaPrevisao; inicio: number; fim: number } | null {
+  if (!emAlerta(p)) return null
+  const inicio = p.estado === 'esgotada' ? p.lidaEm : p.acabaEm
+  if (inicio === null) return null
+  return { p, inicio, fim: p.renovaEm ?? Number.POSITIVE_INFINITY }
+}
+
+/**
+ * Cada retomada contra os trechos sem cota das janelas em alerta (D7): `nao-cabe` quando despacha dentro de
+ * um deles (na hora exata da renovacao a janela ja renovou); `cabe`, com a folga ate o primeiro esgotamento,
+ * quando despacha antes; `depois-de-renovar` quando todos ja renovaram. Sem janela em alerta, `cabe` sem folga.
+ */
+export function cruzar(previsoes: readonly ClimaPrevisao[], retomadas: readonly ClimaRetomada[], agora: number): ClimaDespacho[] {
+  const trechos = previsoes.map(trechoSemCota).filter((t): t is NonNullable<ReturnType<typeof trechoSemCota>> => t !== null)
+  const despacho = (r: ClimaRetomada, quando: number, classe: ClimaClasse, t: (typeof trechos)[number] | undefined,
+    folgaMs: number | null): ClimaDespacho => ({
+    retomada: r, quando, classe, janela: t?.p.kind ?? null, estadoDaJanela: t?.p.estado ?? null,
+    acabaEm: t?.inicio ?? null, renovaEm: t?.p.renovaEm ?? null, folgaMs,
+  })
+  return retomadas.map(r => {
+    const quando = Math.max(agora, r.liberaEm ?? agora)
+    const dentro = trechos.filter(t => quando >= t.inicio && quando < t.fim)
+    if (dentro.length > 0) return despacho(r, quando, 'nao-cabe', dentro.reduce((a, b) => (b.fim > a.fim ? b : a)), null)
+    const antes = trechos.filter(t => quando < t.inicio)
+    if (antes.length > 0) {
+      const primeiro = antes.reduce((a, b) => (b.inicio < a.inicio ? b : a))
+      return despacho(r, quando, 'cabe', primeiro, primeiro.inicio - quando)
+    }
+    if (trechos.length > 0) return despacho(r, quando, 'depois-de-renovar', trechos.reduce((a, b) => (b.fim > a.fim ? b : a)), null)
+    return despacho(r, quando, 'cabe', undefined, null)
+  }).sort((a, b) => ORDEM_DA_CLASSE[a.classe] - ORDEM_DA_CLASSE[b.classe] || a.quando - b.quando)
+}
+
+/** As threads das retomadas que nao cabem, sem repetir, na ordem do cruzamento. */
+export function threadsQueNaoCabem(despachos: readonly ClimaDespacho[]): string[] {
+  const threads: string[] = []
+  for (const d of despachos) if (d.classe === 'nao-cabe' && !threads.includes(d.retomada.thread)) threads.push(d.retomada.thread)
+  return threads
+}
+
+/** Uma retomada no `/clima`. */
+export function textoDoDespacho(d: ClimaDespacho, fuso: string, agora: number): string {
+  const volta = d.quando <= agora ? 'volta agora' : `volta ${formatarHora(d.quando, fuso, agora)}`
+  const quem = `${d.retomada.id} da ${d.retomada.thread} ${volta}`
+  const janela = d.janela === null ? 'a janela' : `a janela de ${rotuloDaJanela(d.janela)}`
+  if (d.classe === 'nao-cabe') {
+    const acaba = d.estadoDaJanela === 'esgotada' || d.acabaEm === null ? 'já esgotou' : `acaba ~${formatarHora(d.acabaEm, fuso, agora)}`
+    const renova = d.renovaEm === null ? 'não tem hora de renovar' : `renova ${formatarHora(d.renovaEm, fuso, agora)}`
+    return `${quem} e não cabe: ${janela} ${acaba} e ${renova}.`
+  }
+  if (d.classe === 'depois-de-renovar') return `${quem}, depois de ${janela} renovar.`
+  if (d.folgaMs !== null) return `${quem}, com ~${duracao(d.folgaMs)} de cota no ritmo atual.`
+  return `${quem}.`
+}
+
+/** As retomadas que nao cabiam, como o estado guardou; a entrada fora do formato fica de fora (D15). */
+export function naoCabemGuardados(valor: unknown): ClimaNaoCabe[] {
+  if (!Array.isArray(valor)) return []
+  return valor.filter((n): n is ClimaNaoCabe => !!n && typeof n.id === 'string' && typeof n.thread === 'string'
+    && typeof n.texto === 'string' && typeof n.registrada === 'boolean')
+}
+
+/** O que vai ao registro do mostrado por retomada que nao cabe: so o que nao muda a cada leitura (D13). */
+export function textoDoNaoCabe(d: ClimaDespacho, fuso: string, agora: number): string {
+  const janela = d.janela === null ? 'na janela' : `na janela de ${rotuloDaJanela(d.janela)}`
+  const renova = d.renovaEm === null ? ', que não tem hora de renovar' : `, que renova ${formatarHora(d.renovaEm, fuso, agora)}`
+  return `${d.retomada.id} da ${d.retomada.thread} não cabe ${janela}${renova}.`
+}
+
+/** O resumo que o `/clima` registra como mostrado (D8): a linha da faixa, ou que nada pede atencao. */
+export function resumoDoClima(previsoes: readonly ClimaPrevisao[], naoCabem: readonly string[], fuso: string, agora: number): string {
+  return textoDaFaixa(previsoes, fuso, agora, naoCabem) ?? 'nenhuma janela pede atenção'
+}
+
+export function textoDaParada(p: ClimaParada): string {
+  return `${p.thread} parada por ${p.motivo}.`
+}
+
+export function textoDaMarca(m: ClimaMarca, fuso: string, agora: number): string {
+  const prazo = m.esgotadoAte === null ? 'sem prazo' : `até ${formatarHora(m.esgotadoAte, fuso, agora)}`
+  const onde = m.projeto === NAO_REGISTRADO ? 'em projeto não registrado' : `em ${m.projeto}`
+  return `conta ${m.conta} (${m.runtime}): ${m.estado} ${prazo}, visto ${onde} (${m.motivo}).`
+}
+
+/** As linhas do cruzamento no `/clima`: fila, paradas, contas do registro e, se algo aperta, as sugestoes. */
+export function linhasDoCruzamento(c: ClimaCruzamento, previsoes: readonly ClimaPrevisao[], fuso: string, agora: number): string[] {
+  const linhas = ['Despachos que dependem da cota (fila de retomada do núcleo):']
+  if (c.despachos === null) linhas.push(`- Fila de retomada indisponível (${c.erroDaFila ?? 'fora do formato'}).`)
+  else if (c.despachos.length === 0) linhas.push('- Nenhuma retomada na fila.')
+  else for (const d of c.despachos) linhas.push(`- ${textoDoDespacho(d, fuso, agora)}`)
+  linhas.push('Threads abertas paradas por cota (retrato do núcleo):')
+  if (c.paradas === null) linhas.push(`- Não deu para conferir as paradas (${c.erroDoRetrato ?? 'sem resposta'}).`)
+  else {
+    if (c.paradas.itens.length === 0) linhas.push('- Nenhuma.')
+    for (const p of c.paradas.itens) linhas.push(`- ${textoDaParada(p)}`)
+    if (c.paradas.paginaCortada) linhas.push('- Os bloqueios vieram em mais de uma página; o Clima leu a primeira.')
+    if (c.paradas.lacunas > 0) {
+      linhas.push(`- O retrato não leu o ledger de ${c.paradas.lacunasCortadas ? 'pelo menos ' : ''}${c.paradas.lacunas} thread(s).`)
+    }
+  }
+  linhas.push('Contas no registro do núcleo (ork accounts esgotamentos):')
+  if (c.marcas === null) linhas.push(`- Registro de contas indisponível (${c.erroDoRegistro ?? 'fora do contrato ork.esgotamentos/v1'}).`)
+  else if (c.marcas.length === 0) linhas.push('- Nenhuma conta marcada no registro.')
+  else for (const m of c.marcas) linhas.push(`- ${textoDaMarca(m, fuso, agora)}`)
+  const aperta = previsoes.some(emAlerta) || (c.despachos ?? []).some(d => d.classe === 'nao-cabe') || (c.paradas?.itens.length ?? 0) > 0
+  if (aperta) linhas.push('O que o núcleo já sabe fazer:', ...SUGESTOES.map(s => `- ${s}`))
+  return linhas
+}

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

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