@orkastery/cli 0.5.3 → 0.5.6

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

@@ -0,0 +1,156 @@
+// O despacho da fase seguinte pela Sentinela (RM-059, fatia F6, T6.2). Módulo puro: quais passos do núcleo despachar
+// ou retomar, uma vez por turno, o argv do render, do despacho e da retomada, e a leitura de cada resultado. A
+// Sentinela só despacha pelo `ork phase run`, que toma a condução da thread sob a trava do kernel e é idempotente; a
+// fase vem do núcleo (`ork conducao sentinela status`), nunca de uma regra daqui, e ela nunca assume a condução.
+import type { SentinelaPasso } from '../types'
+
+export const PRAZO_DO_RENDER_MS = 30000
+/** O mesmo teto que o condutor externo dá ao `ork phase run`, com folga. */
+export const PRAZO_DO_DESPACHO_MS = 200000
+export const PRAZO_DA_RETOMADA_MS = 200000
+/**
+ * A recusa que passa (outro condutor, projeto sem vaga, pedido aberto, falha) não queima o turno: a chave volta e o
+ * passo é tentado de novo depois disto. A batida e o adiamento são da Sentinela; quem diz se sai é sempre o núcleo.
+ */
+export const ADIAMENTO_MS = 3 * 60 * 1000
+/** A mesma recusa de novo dobra o adiamento, até este teto: falha que não passa não vira despacho a cada 3 min. */
+export const TETO_DO_ADIAMENTO_MS = 30 * 60 * 1000
+
+/** O adiamento da n-ésima recusa seguida do mesmo turno: 3, 6, 12 e 24 min, depois 30. */
+export function adiamentoDa(vez: number): number {
+  return Math.min(TETO_DO_ADIAMENTO_MS, ADIAMENTO_MS * 2 ** Math.max(0, Math.floor(vez) - 1))
+}
+/** A linha que o `ork prompt render` imprime quando usa o pedido guardado na criação da thread (T6.0). */
+export const MARCA_DO_PEDIDO = '# pedido guardado na criacao da thread'
+/** O teto do prompt que o despacho aceita (o mesmo do `ork_phase_run`). */
+export const TETO_DO_PROMPT = 65536
+export const CANAL = 'claude-code'
+/** O `ork retry run` não lê `--canal`: o canal da retomada vai pelo ambiente, como o núcleo o declara (D3). */
+export const AMBIENTE_DA_RETOMADA: Readonly<Record<string, string>> = { ORK_CANAL: CANAL }
+const FASES: readonly string[] = ['GOAL', 'PLAN', 'GO', 'CHECK', 'SHIP', 'MASTER']
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+const SESSAO = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/
+/** Os estados de pedido HITL que ainda esperam o dono no retrato do Maestro. */
+const PEDIDO_ABERTO: readonly string[] = ['aberto', 'delivery.uncertain']
+
+type Saida = { exitCode: number; stdout: string; stderr: string }
+
+function exigirThread(thread: unknown): string {
+  if (typeof thread !== 'string' || !ID_DE_THREAD.test(thread)) throw new Error('ork-sentinela: id de thread invalido')
+  return thread
+}
+
+function exigirFase(fase: unknown): string {
+  if (typeof fase !== 'string' || !FASES.includes(fase)) throw new Error('ork-sentinela: fase fora do ciclo')
+  return fase
+}
+
+function ultimaLinha(texto: unknown): string {
+  return String(texto ?? '').trim().split('\n').filter(l => l.trim() !== '').slice(-1)[0]?.trim().slice(0, 200) ?? ''
+}
+
+function primeiraLinha(texto: unknown): string {
+  return String(texto ?? '').trim().split('\n').find(l => l.trim() !== '')?.trim().slice(0, 200) ?? ''
+}
+
+/** A chave de um despacho: a thread, a fase e o fim do turno que o pediu. O mesmo turno nunca sai duas vezes. */
+export function chaveDoDespacho(p: SentinelaPasso): string | null {
+  return p.acao === 'despachar' && p.fase && p.desdeEm ? `${p.thread}|${p.fase}|${p.desdeEm}` : null
+}
+
+/** A chave de uma retomada: a thread e o bloqueio. O mesmo bloqueio vai ao `retry plan` uma vez. */
+export function chaveDaRetomada(p: SentinelaPasso): string | null {
+  return p.acao === 'retomar' && p.bloqueio ? `${p.thread}|${p.bloqueio.motivo}|${p.bloqueio.em}` : null
+}
+
+/** Os passos a despachar agora: #Auto, sem condução, com fase do ciclo e turno ainda não despachado. */
+export function paraDespachar(passos: readonly SentinelaPasso[], feitos: readonly string[]): SentinelaPasso[] {
+  return passos.filter(p => {
+    const chave = chaveDoDespacho(p)
+    return chave !== null && !p.conduzida && p.modo === 'auto' && ID_DE_THREAD.test(p.thread) && FASES.includes(p.fase as string)
+      && !feitos.includes(chave)
+  })
+}
+
+/** Os passos a levar ao `retry plan` agora: #Auto, sem condução e bloqueio ainda não consultado. */
+export function paraRetomar(passos: readonly SentinelaPasso[], feitos: readonly string[]): SentinelaPasso[] {
+  return passos.filter(p => {
+    const chave = chaveDaRetomada(p)
+    return chave !== null && !p.conduzida && p.modo === 'auto' && ID_DE_THREAD.test(p.thread) && !feitos.includes(chave)
+  })
+}
+
+/** Ninguém conduz a thread: o `ork conducao status --json` (pela ponte) diz `conducao: null`. */
+export function conducaoLivre(status: unknown): boolean {
+  return !!status && typeof status === 'object' && 'conducao' in status && (status as { conducao: unknown }).conducao === null
+}
+
+/** O retrato da thread tem pedido ao dono ainda sem resposta (seção `hitl` do `ork.maestro-snapshot/v1`). */
+export function pedidoAbertoNoRetrato(retrato: unknown, thread: string): boolean {
+  const itens = (retrato as { sections?: { hitl?: { items?: unknown } } } | null)?.sections?.hitl?.items
+  if (!Array.isArray(itens)) return false
+  return itens.some(bruto => {
+    const i = bruto as { status?: unknown; refs?: unknown; facts?: { target?: unknown } } | null
+    if (!i || !PEDIDO_ABERTO.includes(String(i.status)) || i.facts?.target === 'decidido') return false
+    return Array.isArray(i.refs) && i.refs.some(r => (r as { kind?: unknown; id?: unknown })?.kind === 'thread' && (r as { id?: unknown }).id === thread)
+  })
+}
+
+/** O render do prompt da fase com o pedido guardado: sem `--pedido`, o núcleo usa o da criação da thread. */
+export function argvDoRender(thread: string, fase: string): string[] {
+  return ['ork', 'prompt', 'render', exigirThread(thread), exigirFase(fase)]
+}
+
+/** O prompt do render; sem a linha do pedido guardado ele seria o texto de exemplo, e não serve. */
+export function promptDoRender(r: Saida): { prompt: string } | { motivo: string } {
+  if (r.exitCode !== 0) return { motivo: `o render do prompt saiu ${r.exitCode}${ultimaLinha(r.stderr) ? `: ${ultimaLinha(r.stderr)}` : ''}` }
+  if (!r.stdout.split('\n').some(l => l.startsWith(MARCA_DO_PEDIDO))) {
+    return { motivo: 'a thread não tem o pedido guardado na criação (ork thread new --pedido): o render cairia no texto de exemplo' }
+  }
+  const prompt = r.stdout.trimEnd()
+  if (prompt.length > TETO_DO_PROMPT) return { motivo: `o prompt tem ${prompt.length} caracteres, acima do teto de ${TETO_DO_PROMPT}` }
+  return { prompt }
+}
+
+/** O despacho pelo núcleo, com o canal da Sentinela e a correlação que a marca no ledger (D3). */
+export function argvDoDespacho(thread: string, fase: string, prompt: string, sessao: string): string[] {
+  if (typeof prompt !== 'string' || prompt.trim() === '') throw new Error('ork-sentinela: prompt vazio')
+  if (typeof sessao !== 'string' || !SESSAO.test(sessao)) throw new Error('ork-sentinela: id de sessao invalido')
+  return ['ork', 'phase', 'run', exigirThread(thread), exigirFase(fase), '--prompt', prompt, '--canal', CANAL, '--correlacao', `sentinela:${sessao}`]
+}
+
+export type ResultadoDoDespacho = { resultado: 'despachada' | 'repetida' | 'ocupada' | 'falhou'; detalhe: string }
+
+/**
+ * O que o `ork phase run` disse. Saída 3: outro condutor conduz a thread, ou o projeto está sem vaga. Saída 1 com
+ * `HITL ocupado`: outro despacho tomou a trava do kernel no mesmo instante. Pedido repetido: a sessão de quem já
+ * conduz atende. Nenhum desses abre sessão nova, e nenhum é repetido pela Sentinela.
+ */
+export function lerDespacho(r: Saida): ResultadoDoDespacho {
+  if (r.exitCode === 0 && /Pedido ja em andamento|Request already in progress/.test(r.stdout)) {
+    return { resultado: 'repetida', detalhe: primeiraLinha(r.stdout) }
+  }
+  if (r.exitCode === 0) {
+    const sessao = /sessionId\s*:\s*([0-9a-f-]{8,})/.exec(r.stdout)?.[1]
+    return { resultado: 'despachada', detalhe: sessao ? `sessão ${sessao.slice(0, 8)}` : primeiraLinha(r.stdout) }
+  }
+  if (r.exitCode === 3) return { resultado: 'ocupada', detalhe: primeiraLinha(r.stdout) || ultimaLinha(r.stderr) }
+  if (r.exitCode === 1 && /HITL ocupado/.test(r.stderr)) return { resultado: 'ocupada', detalhe: 'outro despacho tomou a vez no mesmo instante' }
+  return { resultado: 'falhou', detalhe: `o despacho saiu ${r.exitCode}${ultimaLinha(r.stderr) ? `: ${ultimaLinha(r.stderr)}` : ''}` }
+}
+
+/** O plano do retry declara a retomada automática, sem bloqueio: só ela a Sentinela executa. */
+export function retomadaAutomatica(plano: unknown): boolean {
+  const p = plano as { automatica?: unknown; bloqueio?: unknown } | null
+  return !!p && p.automatica === true && (p.bloqueio === null || p.bloqueio === undefined)
+}
+
+/** A retomada pelo núcleo, sem `--por`: no #Auto o retry automático não pede autorização. */
+export function argvDaRetomada(thread: string): string[] {
+  return ['ork', 'retry', 'run', exigirThread(thread)]
+}
+
+export function lerRetomada(r: Saida): { resultado: 'retomada' | 'recusada'; detalhe: string } {
+  return r.exitCode === 0 ? { resultado: 'retomada', detalhe: primeiraLinha(r.stdout) }
+    : { resultado: 'recusada', detalhe: `o retry saiu ${r.exitCode}${ultimaLinha(r.stderr || r.stdout) ? `: ${ultimaLinha(r.stderr || r.stdout)}` : ''}` }
+}

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

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

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

@@ -0,0 +1,511 @@
+// A Sentinela do Condutor do Orkastery (RM-059, fatia F6; ficha M2 do plano dos mods). Na sessão do dono, mantém a
+// presença dela nesta máquina pelo núcleo, para o condutor externo ceder o despacho (DD5), relê o passo do condutor
+// de cada thread aberta quando um ledger muda e a cada batida, e despacha a fase seguinte das threads #Auto que o
+// núcleo manda despachar, só pelo `ork phase run` e uma vez por turno (T6.2); e avisa o dono, por notificação e na
+// faixa, do que só ele resolve, com o próximo passo do núcleo (T6.3), registrando pela ponte o que mostrou para o
+// Telegram não repetir. Lê só pelo núcleo (o `ork` e o `$.ork` da ponte), nunca `.orkastery/` por conta própria, e
+// nunca assume a condução de ninguém. A lógica fica nos módulos puros ao lado; aqui só os ganchos e as chamadas ao
+// `$`, escritas como `x.noun.metodo(...)`, como o validador exige.
+import type { EngineInterface, Register } from 'claude-code'
+import type { SentinelaEntrada, SentinelaPasso, SentinelaPresenca, SentinelaResumo } from '../types'
+import {
+  adiamentoDa, AMBIENTE_DA_RETOMADA, argvDaRetomada, argvDoDespacho, argvDoRender, chaveDaRetomada, chaveDoDespacho, conducaoLivre, lerDespacho,
+  lerRetomada, paraDespachar, paraRetomar, pedidoAbertoNoRetrato, PRAZO_DA_RETOMADA_MS, PRAZO_DO_DESPACHO_MS, PRAZO_DO_RENDER_MS,
+  promptDoRender, retomadaAutomatica,
+} from './despacho'
+import type { ResultadoDoDespacho } from './despacho'
+import { avisoDoDespacho, avisosDoPulse, avisosNovos, marcaDoAviso, PERIODO_DO_PULSE_MS, TITULO } from './alertas'
+import type { Aviso } from './alertas'
+import {
+  acrescentar, argvDaBatida, argvDoDesligar, argvDoStatus, BATIDA_MS, entrada, ESPERA_DO_LEDGER_MS, guardarChave, lerBatida, lerStatus, MOD,
+  PRAZO_DA_BATIDA_MS, PRAZO_DO_STATUS_MS, sessaoValida, TETO_DO_DIARIO, textoDaFaixa, textoDoDiario, threadDoLedger,
+} from './vigia'
+
+const RESUMO_VAZIO: SentinelaResumo = { lidoEm: null, presenca: 'desconhecida', passos: [], erro: null }
+const REF_DIARIO = { plugin: 'ork-sentinela', key: 'diario' } as const
+const REF_PAUSADA = { plugin: 'ork-sentinela', key: 'pausada' } as const
+const REF_RESUMO = { plugin: 'ork-sentinela', key: 'resumo' } as const
+const REF_DESPACHADOS = { plugin: 'ork-sentinela', key: 'despachados' } as const
+const REF_RETOMADOS = { plugin: 'ork-sentinela', key: 'retomados' } as const
+const REF_AVISADOS = { plugin: 'ork-sentinela', key: 'avisados' } as const
+
+/**
+ * O estado desta carga. Um despacho do host lê o `$.state` do momento em que começou, e a segunda gravação com
+ * `ifVersion` no mesmo despacho nunca acerta (o `update` do motor ficaria em laço): a fonte da verdade é esta memória
+ * do módulo, carregada do estado uma vez na ativação (depois de uma recarga, o que a carga anterior gravou), e cada
+ * mudança vai ao estado por `$.state.set` sem versão. Os despachos deste módulo rodam um de cada vez no mesmo laço de
+ * eventos, então a memória nunca diverge do que foi gravado por último.
+ */
+const memoria = {
+  diario: [] as SentinelaEntrada[], pausada: false, resumo: RESUMO_VAZIO, despachados: [] as string[], retomados: [] as string[],
+  avisados: [] as string[],
+}
+type Chave = keyof typeof memoria
+/** O servidor do núcleo pode conectar depois do início da sessão: o papel é conferido de novo nestas esperas. */
+const ESPERAS_DO_PAPEL_MS = [3000, 10000, 30000]
+/** Depois delas, enquanto dormente, a cada 5 min. */
+const ESPERA_LONGA_DO_PAPEL_MS = 300000
+/** A primeira rodada sai logo depois da ativação, fora do início da sessão. */
+const ESPERA_DA_PRIMEIRA_MS = 1000
+/** Ledgers mudam o tempo todo com sessões vivas: entre duas rodadas pedidas por arquivo, pelo menos isto. */
+const INTERVALO_MINIMO_MS = 15000
+
+// O que o módulo guarda entre ganchos. Uma recarga do módulo zera tudo, e o `session.start` dispara de novo nela; o
+// diário, a pausa e a última leitura ficam em `$.state`.
+let ativa = false
+let desistiu = false
+/** O id desta sessão do Claude Code, relido a cada batida: um `/clear` continua o processo com outro. */
+let sessao: string | null = null
+let ciclo: { cancel: () => void } | undefined
+let acordar: { cancel: () => void } | undefined
+let rodando: Promise<void> | undefined
+let pendente = false
+let ultimaRodadaEm = 0
+/**
+ * A última linha publicada na faixa. `null` é "não sei": uma carga nova não sabe o que a anterior deixou na faixa
+ * da ponte, então a primeira publicação sempre acontece, inclusive a que tira a linha.
+ */
+let ultimaFaixa: string | undefined | null = null
+/** A falha de uma rodada em segundo plano que nem o diário registrou; o `/sentinela` a mostra. */
+let falhaSemRegistro: string | null = null
+/** Quando o pulse foi lido pela última vez nesta carga, e quantos avisos ele trouxe (a faixa os conta). */
+let ultimoPulseEm = Number.NEGATIVE_INFINITY
+let avisosAtuais = 0
+let batendo: Promise<void> | undefined
+/** O que a última batida disse da presença desta sessão: `outra` segura o despacho e os avisos. */
+let ultimaBatida: SentinelaPresenca = 'desconhecida'
+/**
+ * Os turnos e bloqueios adiados nesta carga, com até quando. Só o despacho feito (ou o pedido repetido de quem já
+ * conduz) e a retomada que o plano declara do dono ficam de vez; a recusa que passa (outro condutor, sem vaga, pedido
+ * aberto, falha) volta depois do adiamento, porque o fim do turno que a chave carrega não muda com ela.
+ */
+const adiados = new Map<string, { ate: number; vezes: number }>()
+/** A sessão acabou (`session.end`): batida que chega depois disso desliga a presença de novo, em vez de refazê-la. */
+let encerrada = false
+
+function emEspera(agora: number): string[] {
+  return [...adiados].filter(([, a]) => a.ate > agora).map(([chave]) => chave)
+}
+
+/** Adia a chave pela vez seguida dela: a mesma recusa dobra a espera até o teto (3 min a 30 min). */
+function adiarChave(chave: string, agora: number): number {
+  const vezes = (adiados.get(chave)?.vezes ?? 0) + 1
+  const espera = adiamentoDa(vezes)
+  adiados.set(chave, { ate: agora + espera, vezes })
+  return espera
+}
+
+/** Tira do adiamento o que o núcleo não pede mais (o turno andou, o bloqueio saiu): o Map não cresce sem fim. */
+function podarAdiados(vivas: ReadonlySet<string>): void {
+  for (const chave of [...adiados.keys()]) if (!vivas.has(chave)) adiados.delete(chave)
+}
+
+function mensagem(erro: unknown): string {
+  return (erro instanceof Error ? erro.message : String(erro)).replace(/\s+/g, ' ').trim().slice(0, 200)
+}
+
+/** Carrega a memória do estado: o que esta sessão (ou a carga anterior do módulo) já gravou. */
+async function carregarMemoria($: EngineInterface): Promise<void> {
+  memoria.diario = (await $.state.get(REF_DIARIO)).value ?? []
+  memoria.pausada = (await $.state.get(REF_PAUSADA)).value ?? false
+  memoria.resumo = (await $.state.get(REF_RESUMO)).value ?? RESUMO_VAZIO
+  memoria.despachados = (await $.state.get(REF_DESPACHADOS)).value ?? []
+  memoria.retomados = (await $.state.get(REF_RETOMADOS)).value ?? []
+  memoria.avisados = (await $.state.get(REF_AVISADOS)).value ?? []
+}
+
+/** Muda uma chave da memória e a grava no estado, sem versão: a memória é a fonte desta carga. */
+async function mudar<K extends Chave>($: EngineInterface, chave: K, mudanca: (atual: (typeof memoria)[K]) => (typeof memoria)[K]): Promise<void> {
+  memoria[chave] = mudanca(memoria[chave])
+  if (chave === 'diario') await $.state.set(REF_DIARIO, memoria.diario)
+  else if (chave === 'pausada') await $.state.set(REF_PAUSADA, memoria.pausada)
+  else if (chave === 'resumo') await $.state.set(REF_RESUMO, memoria.resumo)
+  else if (chave === 'despachados') await $.state.set(REF_DESPACHADOS, memoria.despachados)
+  else if (chave === 'retomados') await $.state.set(REF_RETOMADOS, memoria.retomados)
+  else await $.state.set(REF_AVISADOS, memoria.avisados)
+}
+
+/**
+ * O papel pela ponte. `null` só quando o `$.ork` não existe (a ponte não carregou: a chamada nem acontece); uma falha
+ * da própria ponte conta como dormente e o papel é conferido de novo depois.
+ */
+async function papelDaSessao($: EngineInterface): Promise<string | null> {
+  try {
+    return String(await $.ork.papel())
+  } catch (erro) {
+    return erro instanceof TypeError ? null : 'dormente'
+  }
+}
+
+/** Uma linha no diário, sem repetir a anterior igual (a mesma falha a cada batida vira uma linha só). */
+async function anotar($: EngineInterface, e: SentinelaEntrada): Promise<void> {
+  await mudar($, 'diario', d => {
+    const ultima = d[d.length - 1]
+    if (ultima && ultima.tipo === e.tipo && ultima.thread === e.thread && ultima.texto === e.texto) return d
+    return acrescentar(d, e, TETO_DO_DIARIO)
+  })
+}
+
+/** Liga a Sentinela na sessão do dono: o `/sentinela`, a batida de 60 s e a primeira rodada. Falha deixa tudo desligado. */
+async function ativar($: EngineInterface): Promise<void> {
+  if (ativa) return
+  ativa = true
+  try {
+    await carregarMemoria($)
+    await $.command.register({
+      name: 'sentinela', description: 'Sentinela do Condutor: o passo de cada thread e o diário do que ela despachou, cedeu e avisou; pausar ou retomar',
+      immediate: true,
+    })
+  } catch (erro) {
+    ativa = false
+    falhaSemRegistro = mensagem(erro)
+    $.ui.toast(`sentinela: a Sentinela do Condutor não ligou nesta sessão (${mensagem(erro)})`)
+    return
+  }
+  ciclo?.cancel()
+  ciclo = $.clock.every(BATIDA_MS, () => tique($))
+  $.clock.after(ESPERA_DA_PRIMEIRA_MS, () => tique($))
+}
+
+/**
+ * A batida tem relógio próprio, fora da rodada: um despacho lento (até 200 s) dentro de uma rodada não deixa a presença
+ * vencer (3 min), e o condutor externo não volta a conduzir no meio dela. Uma por vez; pausada, nenhuma.
+ */
+function pedirBatida($: EngineInterface): Promise<void> | undefined {
+  if (!ativa || memoria.pausada || batendo) return undefined
+  const esta = (async () => {
+    try {
+      ultimaBatida = await bater($)
+      // A pausa ou o fim da sessão chegou com a batida no ar: ela refez a presença, que sai de novo.
+      if (memoria.pausada || encerrada) {
+        await desligar($, memoria.pausada ? 'batida que chegou depois da pausa' : 'batida que chegou depois do fim da sessão')
+        ultimaBatida = 'nenhuma'
+      }
+    } catch (erro) {
+      falhaSemRegistro = mensagem(erro)
+    } finally {
+      batendo = undefined
+    }
+  })()
+  batendo = esta
+  return esta
+}
+
+/** O relógio da Sentinela: a batida e, depois dela, uma rodada de reserva. Depois de um `/clear` o processo segue. */
+function tique($: EngineInterface): void {
+  encerrada = false
+  const batida = pedirBatida($)
+  if (batida) void batida.then(() => { void pedirRodada($) })
+  else void pedirRodada($)
+}
+
+/** Confere o papel: liga no dono, desiste na fase ou sem a ponte, e tenta de novo enquanto dormente. */
+async function conferirPapel($: EngineInterface, tentativa: number): Promise<void> {
+  if (ativa || desistiu) return
+  const papel = await papelDaSessao($)
+  if (papel === 'dono') return ativar($)
+  if (papel === 'fase' || papel === null) {
+    desistiu = true
+    if (papel === null) $.ui.toast('sentinela: a ponte ork-ponte não carregou; a Sentinela do Condutor fica desligada nesta sessão')
+    return
+  }
+  const espera = ESPERAS_DO_PAPEL_MS[tentativa] ?? ESPERA_LONGA_DO_PAPEL_MS
+  $.clock.after(espera, () => { void conferirPapel($, tentativa + 1).catch(erro => { falhaSemRegistro = mensagem(erro) }) })
+}
+
+/**
+ * Uma rodada por vez. Com uma em andamento, o pedido só marca que outra deve rodar logo depois e volta sem nada para
+ * esperar: quem pediu nunca espera a rodada de outro despacho, cuja espera contaria no orçamento do gancho. Devolve a
+ * rodada só a quem a começou.
+ */
+function pedirRodada($: EngineInterface): Promise<void> | undefined {
+  if (!ativa) return undefined
+  if (rodando) {
+    pendente = true
+    return undefined
+  }
+  const esta = (async () => {
+    try {
+      do {
+        pendente = false
+        await rodadaUmaVez($)
+      } while (pendente)
+    } catch (erro) {
+      // O `$` pode já não responder (a sessão fechou): o motivo fica numa variável do módulo, sem depender dele.
+      falhaSemRegistro = mensagem(erro)
+    } finally {
+      rodando = undefined
+    }
+  })()
+  rodando = esta
+  return esta
+}
+
+/** Um ledger mudou: a rodada sai depois de juntar as linhas do mesmo evento, e nunca antes do intervalo mínimo. */
+function agendar($: EngineInterface, agora: number): void {
+  if (acordar) return
+  const espera = Math.max(ESPERA_DO_LEDGER_MS, ultimaRodadaEm + INTERVALO_MINIMO_MS - agora)
+  acordar = $.clock.after(espera, () => { acordar = undefined; void pedirRodada($) })
+}
+
+/** A batida da presença desta sessão; falha vira linha do diário e presença desconhecida. */
+async function bater($: EngineInterface): Promise<SentinelaPresenca> {
+  sessao = await $.session.id().catch(() => sessao)
+  if (!sessaoValida(sessao)) return 'desconhecida'
+  try {
+    return lerBatida(await $.process.run(argvDaBatida(sessao), { timeoutMs: PRAZO_DA_BATIDA_MS }))
+  } catch (erro) {
+    await anotar($, entrada(await $.clock.now(), 'erro', null, `a batida da presença falhou: ${mensagem(erro)}`))
+    return 'desconhecida'
+  }
+}
+
+/** A rodada: o status do núcleo, o despacho e os avisos (só com a presença desta sessão) e a linha da faixa. */
+async function rodadaUmaVez($: EngineInterface): Promise<void> {
+  ultimaRodadaEm = await $.clock.now()
+  const pausa = memoria.pausada
+  let lido: ReturnType<typeof lerStatus>
+  try {
+    lido = lerStatus(await $.process.run(argvDoStatus(), { timeoutMs: PRAZO_DO_STATUS_MS }), sessao)
+  } catch (erro) {
+    const motivo = mensagem(erro)
+    await mudar($, 'resumo', r => ({ ...r, erro: motivo }))
+    await anotar($, entrada(await $.clock.now(), 'erro', null, `a leitura do núcleo falhou: ${motivo}`))
+    await publicarFaixa($)
+    return
+  }
+  const presenca: SentinelaPresenca = ultimaBatida === 'outra' ? 'outra' : lido.presenca
+  await mudar($, 'resumo', () => ({ lidoEm: ultimaRodadaEm, presenca, passos: lido.passos, erro: null }))
+  // Uma Sentinela por máquina: só a que tem a presença conduz e avisa, e nunca pausada (aí o condutor externo avisa).
+  if (!pausa && presenca === 'minha') {
+    await conduzir($, lido.passos)
+    await lerAvisos($, lido.passos)
+  } else avisosAtuais = 0
+  await publicarFaixa($)
+}
+
+/**
+ * T6.3: a cada 5 min, o pulse pela ponte vira aviso do que só o dono resolve, com o próximo passo do núcleo. Cada aviso
+ * sai uma vez por texto: notificação do sistema (ou toast, se o canal não escreveu), linha no diário e o registro do
+ * que foi mostrado na ponte, para o Telegram não repetir. Pulse que falha fica no diário e a rodada segue.
+ */
+async function lerAvisos($: EngineInterface, passos: readonly SentinelaPasso[]): Promise<void> {
+  const agora = await $.clock.now()
+  if (agora - ultimoPulseEm < PERIODO_DO_PULSE_MS) return
+  ultimoPulseEm = agora
+  let avisos: Aviso[]
+  try {
+    avisos = avisosDoPulse(await $.ork.ler({ consulta: 'pulse' }), passos)
+  } catch (erro) {
+    return anotar($, entrada(agora, 'erro', null, `os avisos do pulse ficaram indisponíveis nesta rodada (${mensagem(erro)})`))
+  }
+  avisosAtuais = avisos.length
+  for (const a of avisosNovos(avisos, memoria.avisados)) await avisar($, a)
+}
+
+/** Um aviso ao dono, uma vez por texto. */
+async function avisar($: EngineInterface, a: Aviso): Promise<void> {
+  const marca = marcaDoAviso(a)
+  if (memoria.avisados.includes(marca)) return
+  await mudar($, 'avisados', l => guardarChave(l, marca))
+  const enviado = await $.ui.notify(a.texto, { title: TITULO }).then(r => r.isSent, () => false)
+  if (!enviado) $.ui.toast(`sentinela: ${a.texto}`)
+  await anotar($, entrada(await $.clock.now(), 'aviso', a.thread, a.texto))
+  try {
+    await $.ork.mostrado({ mod: MOD, canal: enviado ? 'notificacao' : 'toast', texto: a.texto, chave: a.chave, ...(a.thread ? { thread: a.thread } : {}) })
+  } catch (erro) {
+    await anotar($, entrada(await $.clock.now(), 'erro', a.thread, `o aviso não entrou no registro do mostrado da ponte (${mensagem(erro)})`))
+  }
+}
+
+/** T6.2: o despacho e a retomada que o núcleo manda, cada turno feito uma vez só e o recusado depois do adiamento. */
+async function conduzir($: EngineInterface, passos: readonly SentinelaPasso[]): Promise<void> {
+  if (!sessaoValida(sessao)) return
+  podarAdiados(new Set(passos.flatMap(p => [chaveDoDespacho(p), chaveDaRetomada(p)]).filter((c): c is string => c !== null)))
+  const esperando = emEspera(await $.clock.now())
+  for (const p of paraDespachar(passos, [...memoria.despachados, ...esperando])) await despachar($, p, sessao)
+  for (const p of paraRetomar(passos, [...memoria.retomados, ...esperando])) await retomarThread($, p)
+}
+
+const FRASE_DO_RESULTADO: Record<ResultadoDoDespacho['resultado'], string> = {
+  despachada: 'despachada pelo núcleo', repetida: 'o mesmo pedido já estava em andamento; nada novo',
+  ocupada: 'outro condutor conduz agora; nada despachado', falhou: 'o despacho falhou',
+}
+
+/**
+ * Um despacho: a chave do turno entra antes (uma recarga no meio nunca pede o mesmo turno de novo); a condução e o
+ * pedido aberto ao dono são relidos pelo núcleo logo antes; o prompt sai do render com o pedido guardado; e o
+ * `ork phase run` decide, com o lease e a trava do kernel, se a sessão nova abre. Só o despacho feito e o pedido
+ * repetido ficam de vez; o resto devolve a chave e espera o adiamento, e o diário diz quando volta.
+ */
+async function despachar($: EngineInterface, p: SentinelaPasso, sessaoDoDono: string): Promise<void> {
+  const chave = chaveDoDespacho(p) as string
+  const fase = p.fase as string
+  const anotarAqui = async (tipo: SentinelaEntrada['tipo'], texto: string) => anotar($, entrada(await $.clock.now(), tipo, p.thread, texto))
+  let volta = ''
+  const adiar = async () => {
+    await mudar($, 'despachados', d => d.filter(c => c !== chave))
+    volta = `; tenta de novo em ${Math.round(adiarChave(chave, await $.clock.now()) / 60000)} min`
+  }
+  await mudar($, 'despachados', d => guardarChave(d, chave))
+  try {
+    if (!conducaoLivre(await $.ork.ler({ consulta: 'conducao.status', thread: p.thread }))) {
+      await adiar()
+      return anotarAqui('cedeu', `${fase}: outro condutor já conduz a thread; nada despachado${volta}`)
+    }
+    if (pedidoAbertoNoRetrato((await $.ork.retrato({ thread: p.thread })).retrato, p.thread)) {
+      await adiar()
+      return anotarAqui('cedeu', `${fase}: há pedido aberto ao dono na thread; o despacho espera a resposta${volta}`)
+    }
+  } catch (erro) {
+    await adiar()
+    return anotarAqui('erro', `${fase}: a condução não foi relida (${mensagem(erro)})${volta}`)
+  }
+  let render: ReturnType<typeof promptDoRender>
+  try {
+    render = promptDoRender(await $.process.run(argvDoRender(p.thread, fase), { timeoutMs: PRAZO_DO_RENDER_MS }))
+  } catch (erro) {
+    await adiar()
+    return anotarAqui('erro', `${fase}: o render do prompt falhou (${mensagem(erro)})${volta}`)
+  }
+  if ('motivo' in render) {
+    await adiar()
+    await anotarAqui('erro', `${fase}: não despachada: ${render.motivo}`)
+    return avisar($, avisoDoDespacho(p, render.motivo))
+  }
+  let r: ResultadoDoDespacho
+  try {
+    r = lerDespacho(await $.process.run(argvDoDespacho(p.thread, fase, render.prompt, sessaoDoDono), { timeoutMs: PRAZO_DO_DESPACHO_MS }))
+  } catch (erro) {
+    r = { resultado: 'falhou', detalhe: mensagem(erro) }
+  }
+  const deVez = r.resultado === 'despachada' || r.resultado === 'repetida'
+  if (!deVez) await adiar()
+  const tipo = r.resultado === 'despachada' ? 'despacho' : r.resultado === 'falhou' ? 'erro' : 'cedeu'
+  await anotarAqui(tipo, `${fase}: ${FRASE_DO_RESULTADO[r.resultado]}${r.detalhe ? ` (${r.detalhe})` : ''}${deVez ? '' : volta}`)
+  if (r.resultado === 'falhou') await avisar($, avisoDoDespacho(p, r.detalhe))
+}
+
+/**
+ * Uma retomada: a condução e o pedido aberto ao dono são relidos antes, como no despacho; o `ork retry plan` (pela
+ * ponte) decide, e o `ork retry run` só roda quando ele é automático. O plano que é do dono fica de vez para esse
+ * bloqueio; a recusa que passa espera o adiamento.
+ */
+async function retomarThread($: EngineInterface, p: SentinelaPasso): Promise<void> {
+  const chave = chaveDaRetomada(p) as string
+  const anotarAqui = async (texto: string) => anotar($, entrada(await $.clock.now(), 'retomada', p.thread, texto))
+  let volta = ''
+  const adiar = async () => {
+    await mudar($, 'retomados', d => d.filter(c => c !== chave))
+    volta = `; tenta de novo em ${Math.round(adiarChave(chave, await $.clock.now()) / 60000)} min`
+  }
+  await mudar($, 'retomados', d => guardarChave(d, chave))
+  let plano: unknown
+  try {
+    if (!conducaoLivre(await $.ork.ler({ consulta: 'conducao.status', thread: p.thread }))) {
+      await adiar()
+      return anotarAqui(`bloqueio ${p.bloqueio?.motivo}: outro condutor já conduz a thread${volta}`)
+    }
+    if (pedidoAbertoNoRetrato((await $.ork.retrato({ thread: p.thread })).retrato, p.thread)) {
+      await adiar()
+      return anotarAqui(`bloqueio ${p.bloqueio?.motivo}: há pedido aberto ao dono na thread; a retomada espera a resposta${volta}`)
+    }
+    plano = await $.ork.ler({ consulta: 'retry.plan', thread: p.thread })
+  } catch (erro) {
+    await adiar()
+    return anotarAqui(`a condução ou o retry plan não foram lidos (${mensagem(erro)})${volta}`)
+  }
+  if (!retomadaAutomatica(plano)) {
+    const { bloqueio } = (plano ?? {}) as { bloqueio?: unknown }
+    return anotarAqui(`bloqueio ${p.bloqueio?.motivo}: o retry plan não é automático (${String(bloqueio ?? 'sem plano')}); o passo é do dono`)
+  }
+  let r: ReturnType<typeof lerRetomada>
+  try {
+    r = lerRetomada(await $.process.run(argvDaRetomada(p.thread), { env: { ...AMBIENTE_DA_RETOMADA }, timeoutMs: PRAZO_DA_RETOMADA_MS }))
+  } catch (erro) {
+    r = { resultado: 'recusada', detalhe: mensagem(erro) }
+  }
+  if (r.resultado !== 'retomada') await adiar()
+  await anotarAqui(`bloqueio ${p.bloqueio?.motivo}: ${r.resultado === 'retomada' ? 'retomado pelo núcleo' : 'o núcleo não retomou'}${r.detalhe ? ` (${r.detalhe})` : ''}${r.resultado === 'retomada' ? '' : volta}`)
+}
+
+/** A linha da faixa pela ponte (D7 do plano dos mods), só quando o texto muda. */
+async function publicarFaixa($: EngineInterface): Promise<void> {
+  const texto = textoDaFaixa(memoria.resumo, memoria.pausada, await $.clock.now(), avisosAtuais)
+  if (texto === ultimaFaixa) return
+  try {
+    if (texto === undefined) await $.ork.faixa({ mod: MOD })
+    else await $.ork.faixa({ mod: MOD, texto })
+    ultimaFaixa = texto
+  } catch (erro) {
+    // A linha fica como estava; o motivo vai ao diário, e a próxima rodada tenta de novo.
+    await anotar($, entrada(await $.clock.now(), 'erro', null, `a linha da faixa não foi publicada: ${mensagem(erro)}`))
+  }
+}
+
+/** Tira a presença desta sessão: o condutor externo volta a conduzir. */
+async function desligar($: EngineInterface, motivo: string): Promise<void> {
+  if (!sessaoValida(sessao)) return
+  const r = await $.process.run(argvDoDesligar(sessao), { timeoutMs: PRAZO_DA_BATIDA_MS }).catch((erro: unknown) => erro)
+  if (r instanceof Error || (r as { exitCode?: number }).exitCode !== 0) {
+    await anotar($, entrada(await $.clock.now(), 'erro', null, `a presença não saiu (${motivo}); ela vence sozinha em 3 min`))
+  }
+}
+
+async function pausarSentinela($: EngineInterface): Promise<string> {
+  await mudar($, 'pausada', () => true)
+  await desligar($, 'pausa pelo dono')
+  ultimaBatida = 'nenhuma'
+  await anotar($, entrada(await $.clock.now(), 'pausa', null, 'pausada pelo /sentinela; o condutor externo conduz'))
+  await mudar($, 'resumo', r => ({ ...r, presenca: 'nenhuma' }))
+  await publicarFaixa($)
+  return 'Sentinela pausada: nada é despachado por ela, e o condutor externo volta a conduzir. Para voltar: /sentinela retomar.'
+}
+
+async function retomarSentinela($: EngineInterface): Promise<string> {
+  await mudar($, 'pausada', () => false)
+  await anotar($, entrada(await $.clock.now(), 'pausa', null, 'retomada pelo /sentinela'))
+  const batida = pedirBatida($)
+  if (batida) await batida
+  const propria = pedirRodada($)
+  if (propria) await propria
+  return 'Sentinela retomada: ela volta a conduzir nesta máquina quando a presença for confirmada pelo núcleo.'
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    if (e.isInteractive) await conferirPapel($, 0)
+    return next(e)
+  })
+
+  // Um ledger de thread mudou (a ponte já vigia a pasta das threads e os ledgers recentes no papel dono): a rodada
+  // relê o passo do condutor pelo núcleo.
+  on('classic.FileChanged', async ($, e, next) => {
+    if (ativa && threadDoLedger(e.file_path) !== null) agendar($, await $.clock.now())
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  // A sessão acabou: a presença sai na hora, para o condutor externo não esperar o prazo. Num `/clear` o processo
+  // segue com outro id, e a próxima batida toma a presença com ele.
+  on('session.end', async ($, e, next) => {
+    encerrada = true
+    if (ativa && !memoria.pausada) await desligar($, `fim da sessão (${e.reason})`)
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  // `/sentinela` relê o núcleo e mostra o passo de cada thread e o diário; `pausar` e `retomar` mudam quem conduz.
+  on('command.run', { command: 'sentinela' }, async ($, e) => {
+    if (!ativa && !desistiu) await conferirPapel($, ESPERAS_DO_PAPEL_MS.length)
+    if (!ativa) return { text: 'A Sentinela do Condutor só roda na sessão do dono de um projeto do Orkastery.' }
+    const pedido = String(e.args ?? '').trim()
+    if (pedido === 'pausar') return { text: await pausarSentinela($) }
+    if (pedido === 'retomar') return { text: await retomarSentinela($) }
+    if (pedido !== '') return { text: 'Uso: /sentinela (o passo de cada thread e o diário), /sentinela pausar ou /sentinela retomar.' }
+    const propria = pedirRodada($)
+    if (propria) await propria
+    const texto = textoDoDiario(memoria.resumo, memoria.diario, memoria.pausada, await $.clock.now())
+    const andamento = propria ? '' : '\nUma rodada já estava em andamento: o próximo /sentinela mostra a leitura nova.'
+    const falha = falhaSemRegistro ? `\nÚltima falha em segundo plano: ${falhaSemRegistro}` : ''
+    return { text: texto + andamento + falha }
+  })
+}