@orkastery/cli 0.5.3 → 0.6.0

package/adapters/claude-code/mods/ork-freio/hooks/lote.ts

@@ -0,0 +1,270 @@
+// Os arquivos tocados num lote e as claims que eles afetam (RM-059, F2, T2.2). Modulo puro: le a saida do
+// `git status`, compara fotos, junta os caminhos das ferramentas de escrita do lote e casa os caminhos com as
+// claims e com os `touch_paths` do plano. As chamadas ao `$` ficam no register.ts.
+import type { FreioClaim, FreioFoto, FreioPedido, FreioVigia } from '../types'
+
+/** O `git status` da foto (D4): HEAD, sem renomeacao (vira saida e entrada) e com cada arquivo novo listado. */
+export const ARGV_DO_STATUS: readonly string[] = ['git', 'status', '--porcelain=v2', '--branch', '-z', '--no-renames', '--untracked-files=all']
+export const TETO_DO_STATUS_MS = 10000
+/** Caminhos sujos com `stat` por foto; acima disso, so o codigo XY entra na assinatura. */
+export const TETO_DE_STAT = 300
+/** Nome-base menor que isto nao casa com comando (D5). */
+export const MINIMO_DO_NOME_BASE = 3
+
+/** As ferramentas que escrevem um arquivo e o campo do caminho no `tool_input`. */
+const ESCRITA: Readonly<Record<string, string>> = { Edit: 'file_path', Write: 'file_path', MultiEdit: 'file_path', NotebookEdit: 'notebook_path' }
+/** Ferramentas que so leem: o lote feito so delas nao roda o `git status` (D4). */
+export const FERRAMENTAS_DE_LEITURA: readonly string[] = [
+  'Read', 'Grep', 'Glob', 'LS', 'NotebookRead', 'WebFetch', 'WebSearch', 'ToolSearch',
+  'TaskCreate', 'TaskGet', 'TaskList', 'TaskUpdate', 'TaskOutput',
+  'mcp__orkastery__ork_thread_status', 'mcp__orkastery__ork_artifact_read', 'mcp__orkastery__ork_claims_list',
+  'mcp__orkastery__ork_git_status', 'mcp__orkastery__ork_phase_list', 'mcp__orkastery__ork_hitl_pending',
+  'mcp__orkastery__ork_observe',
+]
+const EXTENSOES_DE_CODIGO = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts'])
+/** O CLI de claims dentro de um comando do `Bash` (pelo `ork` ou pelo `index.js` do CLI): o lote mexeu nas claims. */
+const CLI_DE_CLAIMS = /(?:\bork|\bindex\.js)\s+claims\s+(?:add|retirar|verificar)\b/
+/** Caminhos fora dos `touch_paths` citados por extenso num aviso; o resto vai pela contagem (D8). */
+export const TETO_DE_CAMINHOS_NO_AVISO = 20
+
+/** Uma chamada do lote como o `classic.PostToolBatch` a entrega. */
+export type Chamada = { tool_name?: unknown; tool_input?: unknown }
+export type EntradaDoStatus = { caminho: string; xy: string }
+
+/** Pasta e caminho relativo com uma barra so. */
+export function juntar(pasta: string, rel: string): string {
+  return pasta.replace(/\/+$/, '') + '/' + rel.replace(/^\/+/, '')
+}
+
+/**
+ * A saida de `git status --porcelain=v2 --branch -z`: o HEAD (`# branch.oid`, `null` antes do primeiro commit)
+ * e cada caminho sujo com o codigo XY. Entrada renomeada (`2`) pula o caminho de origem; nova vem como `??`.
+ */
+export function lerStatus(saida: string): { head: string | null; entradas: EntradaDoStatus[] } {
+  let head: string | null = null
+  const entradas: EntradaDoStatus[] = []
+  const registros = saida.split('\0')
+  for (let i = 0; i < registros.length; i++) {
+    const r = registros[i] as string
+    if (r.startsWith('# branch.oid ')) {
+      const oid = r.slice('# branch.oid '.length).trim()
+      head = /^[0-9a-f]{7,64}$/.test(oid) ? oid : null
+      continue
+    }
+    const campos = r.split(' ')
+    const xy = campos[1] ?? ''
+    if (r.startsWith('1 ') && campos.length >= 9) entradas.push({ caminho: campos.slice(8).join(' '), xy })
+    else if (r.startsWith('2 ') && campos.length >= 10) { entradas.push({ caminho: campos.slice(9).join(' '), xy }); i++ }
+    else if (r.startsWith('u ') && campos.length >= 11) entradas.push({ caminho: campos.slice(10).join(' '), xy })
+    else if (r.startsWith('? ') && r.length > 2) entradas.push({ caminho: r.slice(2), xy: '??' })
+  }
+  return { head, entradas }
+}
+
+/** A assinatura de um caminho sujo: o XY e, com `stat`, o tamanho e o `mtimeMs` (D4). */
+export function assinatura(xy: string, stat: { size?: unknown; mtimeMs?: unknown } | null | undefined, comStat: boolean): string {
+  if (!comStat) return xy
+  return stat && typeof stat.size === 'number' && typeof stat.mtimeMs === 'number' ? `${xy}|${stat.size}|${stat.mtimeMs}` : `${xy}|ausente`
+}
+
+/**
+ * Duas assinaturas do mesmo caminho dizem mudanca. A que ficou so com o XY (acima do teto de `stat`) nao se
+ * compara pelo `stat` da outra: o caminho que passa a borda do teto sem mudar nao vira tocado.
+ */
+export function mudou(antes: string | undefined, agora: string): boolean {
+  if (antes === undefined) return true
+  if (antes === agora) return false
+  const [xyAntes, ...statAntes] = antes.split('|')
+  const [xyAgora, ...statAgora] = agora.split('|')
+  return xyAntes !== xyAgora || (statAntes.length > 0 && statAgora.length > 0)
+}
+
+/**
+ * Os caminhos que mudaram entre duas fotos (D4): novo na lista, com assinatura diferente, ou que saiu da lista
+ * com o HEAD parado (reversao). Saida da lista com HEAD novo foi commit e nao conta. Sem foto anterior, nada.
+ */
+export function diferenca(antes: FreioFoto | null, agora: FreioFoto): string[] {
+  if (!antes) return []
+  const tocados = new Set<string>()
+  for (const [caminho, sig] of Object.entries(agora.caminhos)) if (mudou(antes.caminhos[caminho], sig)) tocados.add(caminho)
+  if (antes.head === agora.head) for (const caminho of Object.keys(antes.caminhos)) if (!(caminho in agora.caminhos)) tocados.add(caminho)
+  return [...tocados].sort()
+}
+
+/** O caminho relativo a raiz da sessao, ou `null` quando ele fica fora dela ou nao e caminho. */
+export function relativo(caminho: unknown, raiz: string): string | null {
+  if (typeof caminho !== 'string' || caminho.trim() === '') return null
+  const base = raiz.replace(/\/+$/, '')
+  let rel = caminho.trim()
+  if (rel.startsWith('/')) {
+    if (!rel.startsWith(base + '/')) return null
+    rel = rel.slice(base.length + 1)
+  }
+  rel = rel.replace(/^(?:\.\/)+/, '')
+  const partes = rel.split('/')
+  return rel !== '' && !partes.some(p => p === '' || p === '.' || p === '..') ? rel : null
+}
+
+const nomeDa = (c: Chamada) => (typeof c?.tool_name === 'string' ? c.tool_name : '')
+
+/** Os caminhos que as ferramentas de escrita do lote citam, dentro da raiz, sem repeticao. */
+export function caminhosDoLote(chamadas: readonly Chamada[], raiz: string): string[] {
+  const achados = new Set<string>()
+  for (const c of chamadas) {
+    const campo = ESCRITA[nomeDa(c)]
+    if (!campo) continue
+    const rel = relativo((c.tool_input as Record<string, unknown> | null)?.[campo], raiz)
+    if (rel) achados.add(rel)
+  }
+  return [...achados].sort()
+}
+
+/** O lote so tem ferramentas de leitura (ou nenhuma chamada): nao ha o que fotografar. */
+export function soLeitura(chamadas: readonly Chamada[]): boolean {
+  return chamadas.every(c => FERRAMENTAS_DE_LEITURA.includes(nomeDa(c)))
+}
+
+/** O lote registrou, retirou ou mudou claim: a lista do nucleo precisa ser relida. */
+export function mexeuNasClaims(chamadas: readonly Chamada[]): boolean {
+  return chamadas.some(c => nomeDa(c) === 'mcp__orkastery__ork_claim_add'
+    || (nomeDa(c) === 'Bash' && CLI_DE_CLAIMS.test(String((c.tool_input as { command?: unknown } | null)?.command ?? ''))))
+}
+
+/** O lote regravou um artefato de fase: o plano precisa ser relido. */
+export function mexeuNoPlano(chamadas: readonly Chamada[]): boolean {
+  return chamadas.some(c => nomeDa(c) === 'mcp__orkastery__ork_artifact_write')
+}
+
+const fronteira = (c: string) => c === '' || /[\s'"=:(),;|&<>]/.test(c)
+
+/** O texto cita `alvo` com fronteira dos dois lados. */
+function cita(texto: string, alvo: string, antes: (c: string) => boolean): boolean {
+  for (let i = texto.indexOf(alvo); i >= 0; i = texto.indexOf(alvo, i + 1)) {
+    if (antes(i === 0 ? '' : (texto[i - 1] as string)) && fronteira(texto[i + alvo.length] ?? '')) return true
+  }
+  return false
+}
+
+/** O comando cita o caminho inteiro, com ou sem `./` na frente (D5, forca 2). */
+export function citaCaminho(comando: string, caminho: string): boolean {
+  return cita(comando, caminho, fronteira) || cita(comando, './' + caminho, fronteira)
+}
+
+/**
+ * O comando cita o mesmo nome-base de um fonte TS ou JS, com extensao de codigo (D5, forca 1): pega o teste
+ * compilado (`core/test/x.test.ts` contra `core/dist-test/test/x.test.js`). Nome-base curto nao casa.
+ */
+export function citaNomeBase(comando: string, caminho: string): boolean {
+  const base = caminho.slice(caminho.lastIndexOf('/') + 1)
+  const ponto = base.lastIndexOf('.')
+  if (ponto <= 0 || !EXTENSOES_DE_CODIGO.has(base.slice(ponto + 1))) return false
+  const nome = base.slice(0, ponto)
+  if (nome.length < MINIMO_DO_NOME_BASE) return false
+  const alvo = nome + '.'
+  for (let i = comando.indexOf(alvo); i >= 0; i = comando.indexOf(alvo, i + 1)) {
+    const antes = i === 0 ? '' : (comando[i - 1] as string)
+    if (antes !== '/' && !fronteira(antes)) continue
+    let j = i + alvo.length
+    while (j < comando.length && /[a-z]/.test(comando[j] as string)) j++
+    if (EXTENSOES_DE_CODIGO.has(comando.slice(i + alvo.length, j)) && fronteira(comando[j] ?? '')) return true
+  }
+  return false
+}
+
+const numero = (id: string) => Number(id.slice(1)) || 0
+
+/** Ordem da fila: a forca maior antes; na mesma forca, a claim mais nova antes. */
+function ordenar(pedidos: FreioPedido[]): FreioPedido[] {
+  return pedidos.sort((a, b) => b.forca - a.forca || numero(b.id) - numero(a.id))
+}
+
+/**
+ * As claims que os caminhos tocados afetam, com a forca e os caminhos de cada uma (D5). Claim sem comando fica de
+ * fora: a conferencia so diria que ela nao tem como ser verificada.
+ */
+export function claimsAfetadas(claims: readonly FreioClaim[], tocados: readonly string[]): FreioPedido[] {
+  const afetadas: FreioPedido[] = []
+  for (const c of claims) {
+    if (c.comandos.length === 0) continue
+    let forca = 0
+    const caminhos: string[] = []
+    for (const t of tocados) {
+      const f = c.arquivo === t ? 3 : c.comandos.some(cmd => citaCaminho(cmd, t)) ? 2 : c.comandos.some(cmd => citaNomeBase(cmd, t)) ? 1 : 0
+      if (f > 0) { caminhos.push(t); forca = Math.max(forca, f) }
+    }
+    if (forca > 0) afetadas.push({ id: c.id, forca, caminhos })
+  }
+  return ordenar(afetadas)
+}
+
+/** A fila com as claims novas, sem repeticao: a claim que ja esta nela junta os caminhos e fica com a forca maior. */
+export function enfileirar(fila: readonly FreioPedido[], afetadas: readonly FreioPedido[]): FreioPedido[] {
+  const porId = new Map(fila.map(p => [p.id, { ...p, caminhos: [...p.caminhos] }]))
+  for (const a of afetadas) {
+    const ja = porId.get(a.id)
+    if (!ja) { porId.set(a.id, { ...a, caminhos: [...a.caminhos] }); continue }
+    ja.forca = Math.max(ja.forca, a.forca)
+    for (const c of a.caminhos) if (!ja.caminhos.includes(c)) ja.caminhos.push(c)
+  }
+  return ordenar([...porId.values()])
+}
+
+/** O caminho casa com um `touch_path`: caminho exato ou pasta (com ou sem barra no fim), `*` sem barra e `**` (D9). */
+export function casaTouchPath(caminho: string, padrao: string): boolean {
+  const p = padrao.replace(/\/+$/, '')
+  if (p === '') return false
+  if (!p.includes('*')) return caminho === p || caminho.startsWith(p + '/')
+  let fonte = '^'
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i] as string
+    if (c === '*') {
+      if (p[i + 1] === '*') { fonte += '.*'; i++ } else fonte += '[^/]*'
+    } else fonte += /[.+?^${}()|[\]\\]/.test(c) ? '\\' + c : c
+  }
+  return new RegExp(fonte + '$').test(caminho)
+}
+
+/** Os caminhos tocados fora da uniao dos `touch_paths` do plano; plano sem `touch_paths` nao avisa nada (D9). */
+export function foraDosTouchPaths(tocados: readonly string[], touchPaths: readonly string[] | null): string[] {
+  if (!touchPaths || touchPaths.length === 0) return []
+  return tocados.filter(t => !touchPaths.some(p => casaTouchPath(t, p)))
+}
+
+/** A vigia de uma thread antes da primeira foto. */
+export function vigiaVazia(thread: string): FreioVigia {
+  return { thread, foto: null, seq: 0, toques: {}, fila: [], avisadosFora: [], foraPendentes: [] }
+}
+
+/**
+ * O que um lote faz na vigia: foto nova, toques, claims afetadas na fila e os caminhos novos fora dos `touch_paths`,
+ * guardados uma vez cada para o aviso do laco principal (o lote de subagente toca, mas nao recebe o aviso).
+ */
+export function aplicarLote(v: FreioVigia, lote: { foto: FreioFoto | null; doLote: readonly string[]; claims: readonly FreioClaim[] | null; touchPaths: readonly string[] | null }):
+  { vigia: FreioVigia; tocados: string[]; afetadas: FreioPedido[]; fora: string[] } {
+  const tocados = [...new Set([...lote.doLote, ...(lote.foto ? diferenca(v.foto, lote.foto) : [])])].sort()
+  const seq = v.seq + 1
+  const toques = { ...v.toques }
+  for (const t of tocados) toques[t] = seq
+  const afetadas = lote.claims ? claimsAfetadas(lote.claims, tocados) : []
+  const fora = foraDosTouchPaths(tocados, lote.touchPaths).filter(c => !v.avisadosFora.includes(c))
+  return {
+    vigia: {
+      ...v, foto: lote.foto ?? v.foto, seq, toques, fila: enfileirar(v.fila, afetadas),
+      avisadosFora: [...v.avisadosFora, ...fora], foraPendentes: [...(v.foraPendentes ?? []), ...fora],
+    },
+    tocados, afetadas, fora,
+  }
+}
+
+/** Tira os caminhos fora dos `touch_paths` ainda nao avisados, para o lote do laco principal devolver. */
+export function tomarFora(v: FreioVigia): { vigia: FreioVigia; fora: string[] } {
+  return { vigia: { ...v, foraPendentes: [] }, fora: v.foraPendentes ?? [] }
+}
+
+/** O aviso de `touch_paths` para o modelo, com teto de caminhos; sem caminho novo fora do plano, nenhum texto. */
+export function textoDoFora(fora: readonly string[]): string {
+  if (fora.length === 0) return ''
+  const citados = fora.slice(0, TETO_DE_CAMINHOS_NO_AVISO).join(', ')
+  const resto = fora.length > TETO_DE_CAMINHOS_NO_AVISO ? ` e mais ${fora.length - TETO_DE_CAMINHOS_NO_AVISO}` : ''
+  return `Freio de Lote: o lote mexeu fora dos touch_paths do plano: ${citados}${resto}.`
+}

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

@@ -0,0 +1,285 @@
+// O Freio de Lote (RM-059, fatia F2). Na sessao de fase, acha as claims que o lote de ferramentas mexeu, pede
+// ao nucleo a conferencia delas no sandbox do verify (`ork claims conferir`) e devolve o que quebrou no lote
+// seguinte. Nunca para o laco agentico, nunca roda comando de claim, nunca grava estado de claim e nunca fala
+// pelo dono. A logica fica nos modulos puros ao lado; aqui so as chamadas ao `$`, sempre escritas como
+// `x.noun.metodo(...)`, como o validador exige.
+import type { EngineInterface, Register } from 'claude-code'
+import type { FreioCarga, FreioFoto, FreioVigia } from '../types'
+import {
+  argsDaFerramenta, cargaVazia, claimsDoNucleo, claimsVelhas, FERRAMENTA_DAS_CLAIMS, FERRAMENTA_DO_PLANO, jsonDoMcp,
+  maiorNumeroDeClaim, planoVelho, SERVIDOR, statusNoRetrato, textoDoPlano, threadAtiva, touchPathsDoPlano,
+} from './carga'
+import {
+  aplicarLote, ARGV_DO_STATUS, assinatura, caminhosDoLote, diferenca, juntar, lerStatus, mexeuNasClaims, mexeuNoPlano,
+  soLeitura, TETO_DE_STAT, TETO_DO_STATUS_MS, textoDoFora, tomarFora, vigiaVazia,
+} from './lote'
+import type { Chamada } from './lote'
+import {
+  acumular, argvDaConferencia, ESPERA_DO_FIM_MS, fecharRodada, indisponivelSemRodada, iniciarRodada, lerConferencia, limitarTexto,
+  MOTIVO_PROCESSO_ABERTO, precisaDeLaco, TETO_POR_RODADA, textoDaEntrega, textoDoStatus, tomarEntrega, VIGIA_DA_CONFERENCIA_MS,
+} from './conferencia'
+import type { Leitura } from './conferencia'
+
+const CARGA = { plugin: 'ork-freio', key: 'carga' } as const
+const VIGIA = { plugin: 'ork-freio', key: 'vigia' } as const
+const TENTATIVAS_DE_ESCRITA = 5
+/**
+ * O laco de conferencia desta carga do modulo esta rodando (D10). Fica no modulo, nao no `$.state`: uma troca do
+ * worker mata o laco junto com a marca, e a rodada que ficou aberta no estado e retomada pelo laco seguinte.
+ */
+let rodando = false
+/**
+ * O processo da ultima rodada ainda nao fechou (o vigia venceu e o `return` nao chegou a ele, como num processo que
+ * nao escreve nada). Enquanto ele existir, nenhuma rodada nova abre: duas conferencias nunca correm juntas.
+ */
+let fluxoAberto: Promise<unknown> | null = null
+
+/** A sessao de fase com thread, pelo contexto da ponte; qualquer outra sessao fica sem Freio (D10). */
+type ContextoDeFase = { thread: string; raiz: string }
+
+const mensagem = (erro: unknown) => (erro instanceof Error ? erro.message : String(erro)).slice(0, 300)
+
+async function contextoDeFase($: EngineInterface): Promise<ContextoDeFase | null> {
+  const ctx = await $.ork.contexto()
+  return ctx.papel === 'fase' && ctx.thread ? { thread: ctx.thread, raiz: ctx.raiz } : null
+}
+
+/** Grava a carga com `ifVersion`, aplicando `mudar` sobre a versao mais nova (como a ponte faz com a faixa). */
+async function atualizarCarga($: EngineInterface, thread: string, mudar: (atual: FreioCarga) => FreioCarga): Promise<FreioCarga> {
+  for (let i = 0; i < TENTATIVAS_DE_ESCRITA; i++) {
+    const lida = await $.state.get(CARGA)
+    const atual = lida.value && lida.value.thread === thread ? lida.value : cargaVazia(thread)
+    const nova = mudar(atual)
+    const escrita = await $.state.set(CARGA, nova, { ifVersion: lida.version })
+    if (escrita.isSet) return nova
+  }
+  throw new Error('ork-freio: a carga nao foi guardada')
+}
+
+/** Grava a vigia do mesmo jeito; `mudar` e pura e pode rodar de novo quando outra escrita passou na frente. */
+async function atualizarVigia<T>($: EngineInterface, thread: string, mudar: (atual: FreioVigia) => { vigia: FreioVigia; extra: T }): Promise<{ vigia: FreioVigia; extra: T }> {
+  for (let i = 0; i < TENTATIVAS_DE_ESCRITA; i++) {
+    const lida = await $.state.get(VIGIA)
+    const atual = lida.value && lida.value.thread === thread ? lida.value : vigiaVazia(thread)
+    const r = mudar(atual)
+    const escrita = await $.state.set(VIGIA, r.vigia, { ifVersion: lida.version })
+    if (escrita.isSet) return r
+  }
+  throw new Error('ork-freio: a vigia nao foi guardada')
+}
+
+/**
+ * A carga (T2.1): o estado da thread pelo retrato da ponte, as claims e o plano pelas duas ferramentas de
+ * leitura do nucleo (D2). Cada parte falha sozinha e fica para a proxima leitura.
+ */
+async function carregar($: EngineInterface, ctx: ContextoDeFase, partes: { retrato: boolean; claims: boolean; plano: boolean }): Promise<FreioCarga> {
+  const agora = await $.clock.now()
+  const erros: string[] = []
+  let status: string | null | undefined
+  let claims: FreioCarga['claims'] | undefined
+  let maiorClaim = 0
+  let touchPaths: string[] | null = null
+  let planoLido = false
+  if (partes.retrato) {
+    try {
+      status = statusNoRetrato((await $.ork.retrato({ thread: ctx.thread })).retrato, ctx.thread)
+    } catch (erro) { erros.push(`retrato: ${mensagem(erro)}`) }
+  }
+  if (partes.claims) {
+    try {
+      const r = await $.mcp.call(SERVIDOR, FERRAMENTA_DAS_CLAIMS, argsDaFerramenta(FERRAMENTA_DAS_CLAIMS, ctx.thread))
+      const lista = jsonDoMcp(r, FERRAMENTA_DAS_CLAIMS)
+      claims = claimsDoNucleo(lista)
+      maiorClaim = maiorNumeroDeClaim(lista)
+    } catch (erro) { erros.push(`claims: ${mensagem(erro)}`) }
+  }
+  if (partes.plano) {
+    try {
+      const r = await $.mcp.call(SERVIDOR, FERRAMENTA_DO_PLANO, argsDaFerramenta(FERRAMENTA_DO_PLANO, ctx.thread))
+      touchPaths = touchPathsDoPlano(textoDoPlano(jsonDoMcp(r, FERRAMENTA_DO_PLANO)))
+      planoLido = true
+    } catch (erro) { erros.push(`plano: ${mensagem(erro)}`) }
+  }
+  // Uma leitura mais velha nunca sobrescreve outra mais nova que gravou antes dela (duas cargas ao mesmo tempo).
+  return atualizarCarga($, ctx.thread, atual => ({
+    ...atual,
+    ...(status !== undefined ? { statusDaThread: status } : {}),
+    ...(claims !== undefined && agora >= atual.claimsEm ? { claims, claimsEm: agora, maiorClaim } : {}),
+    ...(planoLido && agora >= atual.planoEm ? { touchPaths, planoLido: true, planoEm: agora } : {}),
+    erros,
+  }))
+}
+
+/** A foto do `git status` da worktree (D4), com o `stat` de cada caminho sujo ate o teto; `null` se o git falhar. */
+async function fotografar($: EngineInterface, raiz: string): Promise<FreioFoto | null> {
+  let r
+  try {
+    // Sem lock opcional: o `git status` do Freio nunca segura o `index.lock` que um commit do modelo precisa.
+    r = await $.process.run(ARGV_DO_STATUS, { cwd: raiz, timeoutMs: TETO_DO_STATUS_MS, env: { GIT_OPTIONAL_LOCKS: '0' } })
+  } catch { return null }
+  if (r.exitCode !== 0) return null
+  const lido = lerStatus(r.stdout)
+  const caminhos: Record<string, string> = {}
+  for (let i = 0; i < lido.entradas.length; i++) {
+    const entrada = lido.entradas[i] as { caminho: string; xy: string }
+    const comStat = i < TETO_DE_STAT
+    const stat = comStat ? await $.fs.stat(juntar(raiz, entrada.caminho)).catch(() => null) : null
+    caminhos[entrada.caminho] = assinatura(entrada.xy, stat, comStat)
+  }
+  return { head: lido.head, caminhos }
+}
+
+/** A primeira foto, guardada so quando ainda nao ha foto (o reload nao apaga o que o lote anterior viu). */
+async function primeiraFoto($: EngineInterface, ctx: ContextoDeFase): Promise<void> {
+  const foto = await fotografar($, ctx.raiz)
+  if (!foto) return
+  await atualizarVigia($, ctx.thread, v => ({ vigia: v.foto ? v : { ...v, foto }, extra: null }))
+}
+
+/**
+ * Uma rodada no nucleo (D6): `ork claims conferir` por `$.process.spawn`, na raiz da sessao, com o vigia do mod.
+ * O processo que nao abre e a saida fora do formato viram conferencia indisponivel (D7).
+ */
+async function rodarConferencia($: EngineInterface, ctx: ContextoDeFase, ids: readonly string[]): Promise<Leitura> {
+  let stdout = ''
+  let stderr = ''
+  let vigia: { cancel: () => void } | undefined
+  try {
+    const fluxo = $.process.spawn({ argv: argvDaConferencia(ctx.thread, ids), cwd: ctx.raiz })
+    const lido = (async () => {
+      for await (const pedaco of fluxo) {
+        if (pedaco.stream === 'stdout') stdout = acumular(stdout, pedaco.text, false)
+        else stderr = acumular(stderr, pedaco.text, true)
+      }
+      return fluxo.result
+    })()
+    lido.catch(() => undefined)
+    fluxoAberto = lido
+    void lido.catch(() => undefined).then(() => { if (fluxoAberto === lido) fluxoAberto = null })
+    const vencido = new Promise<'vencido'>(resolver => { vigia = $.clock.after(VIGIA_DA_CONFERENCIA_MS, () => resolver('vencido')) })
+    const fim = await Promise.race([lido, vencido])
+    if (fim === 'vencido') {
+      // Pede o fim do processo; a volta seguinte do laco espera ele fechar (uma espera so, com teto) antes de abrir
+      // rodada nova, e com ele aberto a conferencia fica indisponivel.
+      void fluxo.return(undefined as never).catch(() => undefined)
+      return { tipo: 'prazo' }
+    }
+    return lerConferencia(stdout, fim.code, stderr)
+  } catch (erro) {
+    return { tipo: 'indisponivel', motivo: `ork claims conferir nao rodou: ${mensagem(erro)}` }
+  } finally {
+    vigia?.cancel()
+  }
+}
+
+/** As claims ativas da carga e o maior numero ja dado, para a rodada nao levar claim retirada; `null` sem lista lida. */
+async function claimsAtivas($: EngineInterface, ctx: ContextoDeFase): Promise<{ ids: string[]; maior: number } | null> {
+  const carga = (await $.state.get(CARGA)).value
+  return carga && carga.thread === ctx.thread && carga.claims ? { ids: carga.claims.map(c => c.id), maior: carga.maiorClaim ?? 0 } : null
+}
+
+/**
+ * O laco de fundo (T2.3): uma rodada por vez, ate a fila acabar, a pausa chegar ou a conferencia faltar. A recusa
+ * de uma claim so rele as claims e segue com as outras; a conducao alheia pausa um minuto.
+ */
+async function conferirEmLaco($: EngineInterface, ctx: ContextoDeFase): Promise<void> {
+  if (rodando) return
+  rodando = true
+  try {
+    for (;;) {
+      if (fluxoAberto) {
+        const aberto = fluxoAberto
+        await Promise.race([aberto.catch(() => undefined), new Promise(resolver => { $.clock.after(ESPERA_DO_FIM_MS, () => resolver(undefined)) })])
+        if (fluxoAberto === aberto) {
+          const quando = await $.clock.now()
+          const parada = await atualizarVigia($, ctx.thread, v => ({ vigia: indisponivelSemRodada(v, MOTIVO_PROCESSO_ABERTO, quando), extra: null }))
+          $.ui.status(textoDoStatus(parada.vigia, quando))
+          break
+        }
+      }
+      const agora = await $.clock.now()
+      const ativas = await claimsAtivas($, ctx)
+      const { vigia } = await atualizarVigia($, ctx.thread, v => ({ vigia: iniciarRodada(v, agora, TETO_POR_RODADA, ativas), extra: null }))
+      if (!vigia.rodada) break
+      $.ui.status(textoDoStatus(vigia, agora))
+      const leitura = await rodarConferencia($, ctx, vigia.rodada.ids)
+      const depois = await $.clock.now()
+      const fechada = await atualizarVigia($, ctx.thread, v => ({ vigia: fecharRodada(v, leitura, depois), extra: null }))
+      $.ui.status(textoDoStatus(fechada.vigia, depois))
+      if (leitura.tipo === 'recusada') await carregar($, ctx, { retrato: false, claims: true, plano: false })
+      if (leitura.tipo === 'indisponivel' || leitura.tipo === 'ocupada') break
+    }
+  } finally {
+    rodando = false
+  }
+}
+
+/** Abre o laco fora do despacho do lote, por `$.clock.after`; o laco que ja roda pega a fila nova. */
+function pedirConferencia($: EngineInterface, ctx: ContextoDeFase): void {
+  if (rodando) return
+  $.clock.after(0, () => { void conferirEmLaco($, ctx).catch(() => undefined) })
+}
+
+export const register: Register = on => {
+  // A carga roda fora do inicio da sessao: o MCP pode ainda estar conectando, e o inicio nao espera por ela.
+  // O `session.start` dispara de novo num reload, e a carga refaz a leitura do mesmo jeito (D10).
+  on('session.start', async ($, e, next) => {
+    const iniciada = await next(e)
+    try {
+      const ctx = await contextoDeFase($)
+      if (ctx) {
+        $.clock.after(0, () => {
+          void (async () => {
+            await carregar($, ctx, { retrato: true, claims: true, plano: true }).catch(() => undefined)
+            await primeiraFoto($, ctx).catch(() => undefined)
+          })()
+        })
+      }
+    } catch { /* sem a ponte, o Freio fica dormente */ }
+    return iniciada
+  })
+
+  // O lote (T2.2 e T2.3): devolve o que a conferencia apurou desde o lote anterior, acha os arquivos tocados e as
+  // claims afetadas, pede a conferencia ao nucleo e avisa os `touch_paths`. Responde so com `additionalContext` e
+  // nunca para o laco: na sessao de fundo nao ha quem o retome. Falha deixa o lote passar. O lote de subagente
+  // (`agent_id`) conta os toques, mas a entrega e o aviso ficam para o lote do laco principal, que e quem os le.
+  on('classic.PostToolBatch', async ($, e, next) => {
+    const resultado = await next(e)
+    const ctx = await contextoDeFase($)
+    if (!ctx) return resultado
+    let carga = (await $.state.get(CARGA)).value
+    if (carga && carga.thread === ctx.thread && !threadAtiva(carga.statusDaThread)) return resultado
+    const chamadas: Chamada[] = Array.isArray(e.tool_calls) ? e.tool_calls : []
+    const doSubagente = typeof e.agent_id === 'string' && e.agent_id !== ''
+    const doLote = caminhosDoLote(chamadas, ctx.raiz)
+    const foto = soLeitura(chamadas) ? null : await fotografar($, ctx.raiz)
+    const mexeu = doLote.length > 0 || foto !== null
+    // O lote que mexeu nas claims ou no plano rele na hora; a lista velha so e relida quando ha caminho para casar.
+    const lida = (await $.state.get(VIGIA)).value
+    const anterior = lida && lida.thread === ctx.thread ? lida.foto : null
+    const previstos = doLote.length + (foto ? diferenca(anterior, foto).length : 0)
+    const nasClaims = mexeuNasClaims(chamadas)
+    const noPlano = mexeuNoPlano(chamadas)
+    if (previstos > 0 || nasClaims || noPlano) {
+      const agora = await $.clock.now()
+      const atual = carga && carga.thread === ctx.thread ? carga : cargaVazia(ctx.thread)
+      const relerClaims = nasClaims || (previstos > 0 && claimsVelhas(atual, agora, false))
+      const relerPlano = noPlano || (previstos > 0 && planoVelho(atual, agora, false))
+      if (relerClaims || relerPlano) carga = await carregar($, ctx, { retrato: false, claims: relerClaims, plano: relerPlano })
+    }
+    const lote = { foto, doLote, claims: carga?.thread === ctx.thread ? carga.claims : null, touchPaths: carga?.thread === ctx.thread ? carga.touchPaths : null }
+    const { vigia, extra } = await atualizarVigia($, ctx.thread, v => {
+      const aplicada = mexeu ? aplicarLote(v, lote).vigia : v
+      if (doSubagente) return { vigia: aplicada, extra: { entrega: null, fora: [] as string[] } }
+      const f = tomarFora(aplicada)
+      const t = tomarEntrega(f.vigia)
+      return { vigia: t.vigia, extra: { entrega: t.entrega, fora: f.fora } }
+    })
+    // A rodada que ficou aberta no estado (o laco morreu com o worker) e retomada como a fila.
+    if (precisaDeLaco(vigia)) pedirConferencia($, ctx)
+    $.ui.status(textoDoStatus(vigia, await $.clock.now()))
+    const partes = [extra.entrega ? textoDaEntrega(extra.entrega) : '', textoDoFora(extra.fora)].filter(t => t !== '')
+    const texto = limitarTexto(partes.join('\n'))
+    return texto ? { ...resultado, additionalContext: [...(resultado.additionalContext ?? []), texto] } : resultado
+  }).catch(($, e, next) => next(e))
+}

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

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