@orkastery/cli 0.5.3 → 0.6.0

package/adapters/claude-code/mods/ork-ponte/hooks/papel.ts

@@ -0,0 +1,42 @@
+// O papel da sessao (RM-059, D4 do plano dos mods). Modulo puro: so dados entram e saem, para o
+// teste do nucleo transpila-lo sem o Claude Code. Nenhum `$` passa por aqui.
+import type { OrkPapel } from '../types'
+
+/** So o servidor MCP sem thread registra esta ferramenta (core/src/mcp-server.ts). */
+export const FERRAMENTA_DO_DONO = 'mcp__orkastery__ork_request_decision'
+export const MANIFESTO_DO_PROJETO = 'orkastery.yaml'
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+
+export type EntradaDoPapel = {
+  /** O `ORK_DISPATCH_ID` que o despacho passa pelo `--settings`. */
+  dispatchId: string | undefined
+  /** A raiz da sessao tem `orkastery.yaml`. */
+  temManifesto: boolean
+  /** Os nomes das ferramentas que o modelo tem agora (`$.tool.list()`). */
+  ferramentas: readonly string[]
+}
+
+/**
+ * `fase` com `ORK_DISPATCH_ID`; `dono` sem ele, com `orkastery.yaml` na raiz e o servidor `orkastery`
+ * sem thread conectado; `dormente` no resto, quando nenhum gancho da ponte age alem do inicio.
+ */
+export function decidirPapel(e: EntradaDoPapel): OrkPapel {
+  if (typeof e.dispatchId === 'string' && e.dispatchId.trim() !== '') return 'fase'
+  if (e.temManifesto && e.ferramentas.includes(FERRAMENTA_DO_DONO)) return 'dono'
+  return 'dormente'
+}
+
+/** A thread do despacho na sessao de fase, so com id valido; `null` fora dela. */
+export function threadDoDespacho(papel: OrkPapel, thread: string | undefined): string | null {
+  if (papel !== 'fase' || typeof thread !== 'string') return null
+  return ID_DE_THREAD.test(thread) ? thread : null
+}
+
+export function idDeThreadValido(thread: unknown): thread is string {
+  return typeof thread === 'string' && ID_DE_THREAD.test(thread)
+}
+
+/** Junta pasta e nome com uma barra so, sem depender de `node:path` (o mod nao tem Node). */
+export function juntar(pasta: string, nome: string): string {
+  return pasta.replace(/\/+$/, '') + '/' + nome.replace(/^\/+/, '')
+}

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

@@ -0,0 +1,331 @@
+// A ponte dos mods do Orkastery (RM-059, onda 0). Acrescenta ao `$` o noun `$.ork`, que os outros mods
+// do Orkastery usam para saber em que sessao estao, ler o nucleo, publicar na faixa e pedir caminhos
+// vigiados, e guarda a regra de autoridade (T0.6): nenhum mod aprova gate, permissao, nota do MASTER,
+// push ou tag pelo dono, nem fala como o 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 { Register } from 'claude-code'
+import type { Ork, OrkAssinatura, OrkContexto, OrkMaestro, OrkMostrado, OrkRetratoGuardado } from '../types'
+import { comporFaixa, desenharFaixa, nomeDeModValido, trocarLinha } from './faixa'
+import type { Achado, Autoridade } from './guarda'
+import {
+  avaliarAmbiente, avaliarArgv, avaliarCaminho, avaliarUses, ehModDoOrkastery, lerAutoridade, MARCA_DE_MOD, NOME_DA_PONTE,
+} from './guarda'
+import { CHAVE_NO_STORE, conferirMostrado, lerRegistro, registrarMostrado } from './mostrado'
+import {
+  argsDoMaestro, argvDaConsulta, cacheValido, caminhosCobertos, chaveDoPedido, conferirPedidoDeRetrato, FERRAMENTA_DO_RETRATO,
+  guardar, interpretarCli, interpretarMcp, raizPeloGit, SERVIDOR, subirAteOEstado, TETO_DO_CLI_MS,
+} from './nucleo'
+import { decidirPapel, juntar, MANIFESTO_DO_PROJETO, threadDoDespacho } from './papel'
+import { caminhosPadrao, fundirCaminhos, idsDeThread, ledgerDaThread, ledgersRecentes, pastaDasThreads, registrarPedido } from './vigia'
+
+const RETRATOS = { plugin: 'ork-ponte', key: 'retratos' } as const
+const FAIXA = { plugin: 'ork-ponte', key: 'faixa' } as const
+const VIGIAS = { plugin: 'ork-ponte', key: 'vigias' } as const
+const TENTATIVAS_DE_ESCRITA = 5
+
+/** O que os ganchos da ponte usam do noun, montado no `engine.create` de cada carga. */
+type Interno = {
+  contexto: () => Promise<OrkContexto>
+  raizDoEstado: () => Promise<string | null>
+  ledgersRecentes: (raiz: string) => Promise<string[]>
+}
+let interno: Interno | undefined
+/** O `classic.SessionStart` desta carga ja respondeu os `watchPaths`. */
+let inicioRespondido = false
+
+// A guarda (T0.6). A lista de autoridade e lida do disco uma vez por carga (D6 da thread): `null` quando
+// falta ou nao tem o formato, e entao tudo que a guarda cobre fecha para os mods do Orkastery.
+let autoridade: Autoridade | null | undefined
+let motivoSemLista = ''
+let raizDaPonte = ''
+/** Mods do Orkastery sem prefixo `ork-`, conhecidos pelo `orkastery-mod.json` no `plugin.register`. */
+const conhecidos = new Set<string>()
+
+function pai(dir: string): string {
+  const sem = dir.replace(/\/+$/, '')
+  const i = sem.lastIndexOf('/')
+  return i <= 0 ? '/' : sem.slice(0, i)
+}
+
+/** A lista ao lado dos mods e, na falta dela, dentro da pasta da ponte (contrato para a distribuicao). */
+async function obterAutoridade(ler: (caminho: string) => Promise<unknown>): Promise<Autoridade | null> {
+  if (autoridade !== undefined) return autoridade
+  const candidatos = [juntar(pai(raizDaPonte), 'autoridade.json'), juntar(raizDaPonte, 'autoridade.json')]
+  const motivos: string[] = []
+  for (const caminho of candidatos) {
+    try {
+      autoridade = lerAutoridade(String(await ler(caminho)))
+      return autoridade
+    } catch (erro) {
+      motivos.push(`${caminho}: ${erro instanceof Error ? erro.message : String(erro)}`)
+    }
+  }
+  motivoSemLista = motivos.join('; ').slice(0, 400)
+  autoridade = null
+  return null
+}
+
+const recusa = (a: Achado) => `ork-ponte: ${a.regra}: ${a.porque}. Mod do Orkastery nao age pelo dono; ` +
+  'registre uma decisao autonoma pelo nucleo ou leve a pergunta ao dono pelo dialogo nativo'
+const semLista = () => `ork-ponte: lista de autoridade ausente ou invalida (${motivoSemLista || 'nao lida'}); ` +
+  'a guarda fecha para os mods do Orkastery'
+const ehMod = (nome: unknown) => ehModDoOrkastery(nome, conhecidos)
+
+export const register: Register = on => {
+  on('engine.create', async ($, e, next) => {
+    const built = await next(e)
+
+    const lerContexto = async (): Promise<OrkContexto> => {
+      const dispatchId = await built.env.get('ORK_DISPATCH_ID')
+      const raiz = await built.session.root()
+      let temManifesto = false
+      let ferramentas: string[] = []
+      if (dispatchId === undefined || dispatchId.trim() === '') {
+        temManifesto = await built.fs.exists(juntar(raiz, MANIFESTO_DO_PROJETO))
+        if (temManifesto) ferramentas = (await built.tool.list()).map(t => t.name)
+      }
+      const papel = decidirPapel({ dispatchId, temManifesto, ferramentas })
+      const thread = threadDoDespacho(papel, await built.env.get('ORK_DISPATCH_THREAD'))
+      return { papel, thread, raiz }
+    }
+
+    // A raiz do estado (a pasta com `orkastery.yaml` e `.orkastery/`), achada uma vez por carga.
+    let raizDoEstado: string | null | undefined
+    const acharRaizDoEstado = async (): Promise<string | null> => {
+      if (raizDoEstado !== undefined) return raizDoEstado
+      const raiz = await built.session.root()
+      let achada = await subirAteOEstado(raiz, caminho => built.fs.exists(caminho))
+      if (achada === null) {
+        const git = await built.process.run(['git', 'rev-parse', '--path-format=absolute', '--git-common-dir'],
+          { cwd: raiz, timeoutMs: 5000 }).catch(() => undefined)
+        const candidata = git && git.exitCode === 0 ? raizPeloGit(git.stdout) : null
+        if (candidata !== null && await built.fs.exists(juntar(candidata, '.orkastery'))) achada = candidata
+      }
+      raizDoEstado = achada
+      return achada
+    }
+
+    const assinar = async (caminhos: readonly string[]): Promise<OrkAssinatura> => {
+      const assinatura: OrkAssinatura = []
+      for (const caminho of caminhos) {
+        const s = await built.fs.stat(caminho).catch(() => undefined)
+        assinatura.push(s ? { caminho, tamanho: s.size, mtimeMs: s.mtimeMs } : { caminho, ausente: true })
+      }
+      return assinatura
+    }
+
+    const lerLedgersRecentes = async (raiz: string): Promise<string[]> => {
+      const entradas = await built.fs.list(pastaDasThreads(raiz)).catch(() => [])
+      const ledgers: Array<{ caminho: string; mtimeMs?: number }> = []
+      for (const id of idsDeThread(entradas).slice(0, 400)) {
+        const caminho = ledgerDaThread(raiz, id)
+        const s = await built.fs.stat(caminho).catch(() => undefined)
+        ledgers.push(s ? { caminho, mtimeMs: s.mtimeMs } : { caminho })
+      }
+      return ledgersRecentes(ledgers)
+    }
+
+    const registrar = async (m: OrkMostrado): Promise<void> => {
+      const agora = new Date(await built.clock.now()).toISOString()
+      await built.store.set(CHAVE_NO_STORE, registrarMostrado(await built.store.get(CHAVE_NO_STORE), m, agora))
+    }
+
+    const ork: Ork = {
+      papel: async () => (await lerContexto()).papel,
+      contexto: async () => lerContexto(),
+      retrato: async bruto => {
+        const pedido = conferirPedidoDeRetrato(bruto)
+        const chave = chaveDoPedido(pedido)
+        const guardados = await built.state.get(RETRATOS)
+        const anterior = guardados.value?.[chave]
+        if (anterior !== undefined) {
+          const agora = await built.clock.now()
+          if (cacheValido(anterior, await assinar(anterior.caminhos), agora)) {
+            return { fonte: 'cache', lidoEm: anterior.lidoEm, retrato: anterior.retrato as OrkMaestro }
+          }
+        }
+        let retrato: unknown
+        let fonte: 'mcp' | 'cli'
+        try {
+          retrato = interpretarMcp(await built.mcp.call(SERVIDOR, FERRAMENTA_DO_RETRATO, argsDoMaestro(pedido)))
+          fonte = 'mcp'
+        } catch {
+          const argv = argvDaConsulta({ consulta: 'maestro', ...pedido })
+          retrato = interpretarCli(argv, await built.process.run(argv, { timeoutMs: TETO_DO_CLI_MS }))
+          fonte = 'cli'
+        }
+        const lidoEm = await built.clock.now()
+        // O `stat` sai depois da leitura: uma mudanca no meio fica no cache ate o teto de 60 s.
+        const caminhos = caminhosCobertos(await acharRaizDoEstado(), pedido, retrato)
+        if (caminhos.length > 0) {
+          const entrada: OrkRetratoGuardado = { fonte, lidoEm, retrato, caminhos, assinatura: await assinar(caminhos) }
+          // Escrita recusada (por exemplo, dentro de um desenho) so deixa de guardar.
+          await built.state.set(RETRATOS, guardar(guardados.value, chave, entrada), { ifVersion: guardados.version })
+            .catch(() => undefined)
+        }
+        return { fonte, lidoEm, retrato: retrato as OrkMaestro }
+      },
+      ler: async pedido => {
+        const argv = argvDaConsulta(pedido)
+        return interpretarCli(argv, await built.process.run(argv, { timeoutMs: TETO_DO_CLI_MS }))
+      },
+      faixa: async ({ mod, texto }) => {
+        if (!nomeDeModValido(mod)) throw new Error('ork-ponte: nome de mod invalido')
+        if (texto !== undefined && typeof texto !== 'string') throw new Error('ork-ponte: texto da faixa precisa ser texto')
+        let publicada = false
+        for (let i = 0; i < TENTATIVAS_DE_ESCRITA; i++) {
+          const atual = await built.state.get(FAIXA)
+          const linhas = trocarLinha(atual.value, mod, texto, await built.clock.now())
+          const escrita = await built.state.set(FAIXA, linhas, { ifVersion: atual.version })
+          if (escrita.isSet) { publicada = linhas.some(l => l.mod === mod); break }
+        }
+        if (publicada && texto !== undefined && (await lerContexto()).papel === 'dono') {
+          await registrar({ mod, canal: 'faixa', texto })
+        }
+        return { publicada }
+      },
+      vigiar: async ({ mod, caminhos }) => {
+        for (let i = 0; i < TENTATIVAS_DE_ESCRITA; i++) {
+          const atual = await built.state.get(VIGIAS)
+          const pedidos = registrarPedido(atual.value, mod, caminhos)
+          const escrita = await built.state.set(VIGIAS, pedidos, { ifVersion: atual.version })
+          if (escrita.isSet) return { caminhos: pedidos[mod] ?? [], valeNoProximoInicio: inicioRespondido }
+        }
+        throw new Error('ork-ponte: o pedido de caminhos nao foi guardado')
+      },
+      mostrado: async pedido => registrar(conferirMostrado(pedido)),
+      mostrados: async () => lerRegistro(await built.store.get(CHAVE_NO_STORE)),
+    }
+
+    interno = { contexto: lerContexto, raizDoEstado: acharRaizDoEstado, ledgersRecentes: lerLedgersRecentes }
+    raizDaPonte = built.plugin.root
+    return { ...built, ork }
+  })
+
+  // So a ponte responde `watchPaths` entre os mods do Orkastery: o que veio de baixo, os padroes e os pedidos.
+  on('classic.SessionStart', async ($, e, next) => {
+    const resultado = await next(e)
+    if (interno === undefined) return resultado
+    const contexto = await interno.contexto()
+    if (contexto.papel === 'dormente') return resultado
+    const raiz = await interno.raizDoEstado()
+    const recentes = contexto.papel === 'dono' && raiz !== null ? await interno.ledgersRecentes(raiz) : []
+    const pedidos = (await $.state.get(VIGIAS)).value
+    inicioRespondido = true
+    return { ...resultado, watchPaths: fundirCaminhos(resultado.watchPaths, caminhosPadrao(contexto.papel, raiz, contexto.thread, recentes), pedidos) }
+  }).catch(($, e, next) => next(e))
+
+  // A faixa acima do prompt: uma linha por mod; sem linha, a faixa fica com quem esta abaixo.
+  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
+    if (e.props.hasSurvey) return next(e)
+    const linhas = comporFaixa((await $.state.get(FAIXA)).value, e.props.bodyColumns, e.props.maxRows)
+    if (linhas.length === 0) return next(e)
+    const { Box, Text } = $.ui.resolve(e)
+    return desenharFaixa({ Box, Text }, linhas)
+  })
+
+  // A guarda em tempo de execucao (T0.6). Cada chamada de `$` e um evento que passa por todos os ganchos,
+  // de qualquer camada, menos o de quem chamou: a ponte ve a chamada do mod onde quer que ele esteja na
+  // cadeia. So um gancho mais externo que respondesse sem `next` a contornaria, e por isso esses eventos
+  // ficam reservados a ponte (o `plugin.register` abaixo recusa o mod que os registra). Cada gancho tem
+  // `.catch` que fecha: sem poder chamar o `$`, o `.catch` decide so com o evento e a lista ja lida.
+
+  // A lista tambem e lida no inicio, para a sessao saber logo quando a guarda esta fechada.
+  on('session.start', async ($, e, next) => {
+    const lida = await obterAutoridade(caminho => $.fs.read(caminho))
+    if (lida === null) $.ui.status(semLista())
+    return next(e)
+  })
+
+  on('process.run', async ($, e, next) => {
+    if (!ehMod(next.origin.plugin)) return next(e)
+    const a = await obterAutoridade(caminho => $.fs.read(caminho))
+    if (a === null) return { deny: semLista() }
+    const achado = avaliarArgv(a, e.argv, e.init?.stdin)
+    return achado ? { deny: recusa(achado) } : next(e)
+  }).catch(($, e, next) => {
+    if (next.called || !ehMod(next.origin.plugin)) return next(e)
+    if (!autoridade) return { deny: semLista() }
+    const achado = avaliarArgv(autoridade, e.argv, e.init?.stdin)
+    return achado ? { deny: recusa(achado) } : next(e)
+  })
+
+  on('process.spawn', async function* ($, e, next) {
+    if (ehMod(next.origin.plugin)) {
+      const a = await obterAutoridade(caminho => $.fs.read(caminho))
+      if (a === null) return { deny: semLista() }
+      const achado = avaliarArgv(a, e.argv, e.input)
+      if (achado) return { deny: recusa(achado) }
+    }
+    return yield* next(e)
+  }).catch(async function* ($, e, next) {
+    if (next.called || !ehMod(next.origin.plugin)) return yield* next(e)
+    if (!autoridade) return { deny: semLista() }
+    const achado = avaliarArgv(autoridade, e.argv, e.input)
+    if (achado) return { deny: recusa(achado) }
+    return yield* next(e)
+  })
+
+  // Mod do Orkastery que hooka evento proibido ou reservado, chama `$.prompt.submit` ou le `ORK_HITL_*`
+  // nem carrega. O nome `ork-ponte` fica reservado a esta pasta.
+  on('plugin.register', async ($, e, next) => {
+    if (e.root === raizDaPonte) return next(e)
+    if (e.name === NOME_DA_PONTE) return { refuse: `ork-ponte: o nome ${NOME_DA_PONTE} e reservado a ponte do Orkastery` }
+    const marcado = e.name.startsWith('ork-') || await $.fs.exists(juntar(e.root, MARCA_DE_MOD)).catch(() => false)
+    if (!marcado) return next(e)
+    conhecidos.add(e.name)
+    const a = await obterAutoridade(caminho => $.fs.read(caminho))
+    if (a === null) return { refuse: semLista() }
+    const achado = avaliarUses(a, e.uses)
+    return achado ? { refuse: recusa(achado) } : next(e)
+  }).catch(($, e, next) => (e.root !== raizDaPonte && (e.name.startsWith('ork-') || conhecidos.has(e.name))
+    ? { refuse: 'ork-ponte: a guarda falhou ao conferir o mod do Orkastery' } : next(e)))
+
+  // Texto enviado como se fosse do dono, vindo de mod do Orkastery, nao entra.
+  on('prompt.submit', ($, e, next) => {
+    const mod = e.origin.kind === 'plugin' && 'name' in e.origin ? e.origin.name : undefined
+    if (ehMod(mod)) {
+      return { drop: `ork-ponte: o mod ${String(mod)} nao fala pelo dono; use a faixa, uma notificacao ou a decisao autonoma do nucleo` }
+    }
+    return next(e)
+  }).catch(($, e, next) => (next.called ? next(e)
+    : ehMod(e.origin.kind === 'plugin' && 'name' in e.origin ? e.origin.name : undefined)
+      ? { drop: 'ork-ponte: a guarda falhou; texto de mod nao entra' } : next(e)))
+
+  on('session.append', ($, e, next) => {
+    const mod = e.origin.kind === 'plugin' && 'name' in e.origin ? e.origin.name : undefined
+    if (ehMod(mod) && e.message.type === 'user') {
+      return { deny: `ork-ponte: o mod ${String(mod)} nao grava linha de usuario; o modelo a leria como palavra do dono` }
+    }
+    return next(e)
+  }).catch(($, e, next) => (next.called ? next(e)
+    : ehMod(e.origin.kind === 'plugin' && 'name' in e.origin ? e.origin.name : undefined) && e.message.type === 'user'
+      ? { deny: 'ork-ponte: a guarda falhou; linha de usuario de mod nao entra' } : next(e)))
+
+  // A propria ponte le o ambiente e a lista do disco: so os outros mods do Orkastery passam por aqui.
+  on('env.get', async ($, e, next) => {
+    const origem = next.origin.plugin
+    if (origem === NOME_DA_PONTE || !ehMod(origem)) return next(e)
+    const a = await obterAutoridade(caminho => $.fs.read(caminho))
+    if (a === null) return { deny: semLista() }
+    const achado = avaliarAmbiente(a, e.name)
+    return achado ? { deny: recusa(achado) } : next(e)
+  }).catch(($, e, next) => {
+    if (next.called || next.origin.plugin === NOME_DA_PONTE || !ehMod(next.origin.plugin)) return next(e)
+    const achado = autoridade ? avaliarAmbiente(autoridade, e.name) : null
+    return autoridade && !achado ? next(e) : { deny: achado ? recusa(achado) : semLista() }
+  })
+
+  on('fs.read', async ($, e, next) => {
+    const origem = next.origin.plugin
+    if (origem === NOME_DA_PONTE || !ehMod(origem)) return next(e)
+    const a = await obterAutoridade(caminho => $.fs.read(caminho))
+    if (a === null) return { deny: semLista() }
+    const achado = avaliarCaminho(a, e.path)
+    return achado ? { deny: recusa(achado) } : next(e)
+  }).catch(($, e, next) => {
+    if (next.called || next.origin.plugin === NOME_DA_PONTE || !ehMod(next.origin.plugin)) return next(e)
+    const achado = autoridade ? avaliarCaminho(autoridade, e.path) : null
+    return autoridade && !achado ? next(e) : { deny: achado ? recusa(achado) : semLista() }
+  })
+}

package/adapters/claude-code/mods/ork-ponte/hooks/vigia.ts

@@ -0,0 +1,76 @@
+// Os caminhos vigiados dos mods do Orkastery (RM-059, T0.4; D7 do plano dos mods e D12 da thread). Os
+// `watchPaths` de varios ganchos de `classic.SessionStart` se fundem e a ultima escrita vence: por isso so
+// a ponte responde, juntando o que veio de baixo, os padroes do papel e os pedidos dos mods. Modulo puro.
+import type { OrkPapel } from '../types'
+
+export const TETO_DE_CAMINHOS = 64
+export const TETO_DE_LEDGERS_DO_DONO = 48
+export const TETO_POR_MOD = 16
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+const NOME_DE_MOD = /^[a-z0-9][a-z0-9-]{0,63}$/
+
+function juntar(pasta: string, nome: string): string {
+  return pasta.replace(/\/+$/, '') + '/' + nome
+}
+
+export function pastaDasThreads(raizDoEstado: string): string {
+  return juntar(raizDoEstado, '.orkastery/threads')
+}
+
+export function ledgerDaThread(raizDoEstado: string, thread: string): string {
+  return juntar(pastaDasThreads(raizDoEstado), `${thread}/ledger.jsonl`)
+}
+
+/** Ids de thread validos entre as entradas da pasta das threads (so pastas). */
+export function idsDeThread(entradas: ReadonlyArray<{ name: string; kind: string }>): string[] {
+  return entradas.filter(e => e.kind === 'dir' && ID_DE_THREAD.test(e.name)).map(e => e.name).sort()
+}
+
+/** Os ledgers mais recentes por `mtimeMs`, com teto; ausente (sem `mtimeMs`) fica de fora. */
+export function ledgersRecentes(ledgers: ReadonlyArray<{ caminho: string; mtimeMs?: number }>, teto = TETO_DE_LEDGERS_DO_DONO): string[] {
+  return ledgers.filter(l => typeof l.mtimeMs === 'number')
+    .sort((a, b) => (b.mtimeMs as number) - (a.mtimeMs as number) || (a.caminho < b.caminho ? -1 : 1))
+    .slice(0, teto).map(l => l.caminho)
+}
+
+/** O que a ponte vigia por padrao: o ledger da thread na fase; a pasta e os ledgers recentes no dono. */
+export function caminhosPadrao(papel: OrkPapel, raizDoEstado: string | null, thread: string | null, recentes: readonly string[]): string[] {
+  if (raizDoEstado === null) return []
+  if (papel === 'fase') return thread !== null && ID_DE_THREAD.test(thread) ? [ledgerDaThread(raizDoEstado, thread)] : []
+  if (papel === 'dono') return [pastaDasThreads(raizDoEstado), ...recentes]
+  return []
+}
+
+/** Confere e guarda o pedido de um mod: caminhos absolutos, sem `..`, com teto por mod. */
+export function registrarPedido(pedidos: Readonly<Record<string, string[]>> | undefined, mod: unknown,
+  caminhos: unknown): Record<string, string[]> {
+  if (typeof mod !== 'string' || !NOME_DE_MOD.test(mod)) throw new Error('ork-ponte: nome de mod invalido')
+  if (!Array.isArray(caminhos)) throw new Error('ork-ponte: caminhos precisa ser uma lista')
+  const validos: string[] = []
+  for (const c of caminhos) {
+    if (typeof c !== 'string' || !c.startsWith('/') || c.split('/').includes('..')) throw new Error('ork-ponte: caminho vigiado precisa ser absoluto e sem ..')
+    if (!validos.includes(c)) validos.push(c)
+  }
+  if (validos.length > TETO_POR_MOD) throw new Error(`ork-ponte: no maximo ${TETO_POR_MOD} caminhos por mod`)
+  const todos = { ...(pedidos ?? {}) }
+  if (validos.length === 0) delete todos[mod]
+  else todos[mod] = validos
+  return todos
+}
+
+/**
+ * O `watchPaths` final: primeiro o que veio de baixo (nunca cortado, nao e da ponte), depois os padroes e
+ * os pedidos dos mods em ordem de nome, sem duplicata, ate o teto.
+ */
+export function fundirCaminhos(deBaixo: readonly string[] | undefined, padrao: readonly string[],
+  pedidos: Readonly<Record<string, readonly string[]>> | undefined, teto = TETO_DE_CAMINHOS): string[] {
+  const saida: string[] = []
+  for (const c of deBaixo ?? []) if (!saida.includes(c)) saida.push(c)
+  const limite = Math.max(teto, saida.length)
+  const nossos = [...padrao, ...Object.keys(pedidos ?? {}).sort().flatMap(m => (pedidos ?? {})[m] ?? [])]
+  for (const c of nossos) {
+    if (saida.length >= limite) break
+    if (!saida.includes(c)) saida.push(c)
+  }
+  return saida
+}

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

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

package/adapters/claude-code/mods/ork-ponte/types/index.d.ts

@@ -0,0 +1,178 @@
+// Contrato do noun `$.ork`, que a ponte acrescenta ao `$` no `engine.create` (RM-059, onda 0).
+// Um mod do Orkastery lista `ork-ponte` em `dependencies` no proprio plugin.json e recebe estes tipos
+// em `.claude-plugin/types/ork-ponte/`. Todo metodo recebe um objeto so: o host recusa noun com mais
+// de um argumento. Sem import nem referencia, como o motor exige de um contrato. O noun e servico aberto
+// a qualquer plugin carregado: o campo `mod` e o nome que quem chama declara, nao uma identidade; a
+// autoridade de cada mod fica com a guarda da ponte, que olha a origem real de cada chamada de `$`.
+
+/**
+ * O papel da sessao: `dono` na sessao interativa do dono (servidor `orkastery` sem thread),
+ * `fase` na sessao despachada pelo nucleo (`ORK_DISPATCH_ID`), `dormente` fora do Orkastery.
+ */
+export type OrkPapel = 'dono' | 'fase' | 'dormente'
+
+/** O que a ponte sabe da sessao, calculado a cada chamada (o MCP pode conectar depois do inicio). */
+export type OrkContexto = {
+  papel: OrkPapel
+  /** A thread do despacho, so na sessao de fase e com id valido. */
+  thread: string | null
+  /** A raiz da sessao, absoluta. */
+  raiz: string
+}
+
+/** As secoes do retrato `ork.maestro-snapshot/v1` do nucleo. */
+export type OrkSecao = 'portfolio' | 'demands' | 'threads' | 'sessions' | 'blockers' | 'leases' | 'retries' | 'hitl'
+  | 'ship' | 'master' | 'nextActions'
+
+/** A lista fechada de consultas de leitura do CLI, todas com `--json` (D10). */
+export type OrkConsulta = 'maestro' | 'thread.status' | 'thread.list' | 'conducao.status' | 'retry.plan' | 'retry.list'
+  | 'pulse' | 'orquestracao.status' | 'sessions.hitl' | 'roadmap.status' | 'accounts.esgotamentos' | 'decisao.placar'
+
+/** O retrato inteiro, uma secao (com `offset`, padrao 0) ou o recorte de uma thread. */
+export type OrkPedidoDeRetrato = {
+  secao?: OrkSecao
+  thread?: string
+  offset?: number
+}
+
+export type OrkPedidoDeLeitura = {
+  consulta: OrkConsulta
+  /** Obrigatoria em `thread.status`, `conducao.status`, `retry.plan` e `decisao.placar`. */
+  thread?: string
+}
+
+/** A acao que o nucleo declara para um item, quando declara (projecao de `ork.maestro-snapshot/v1`). */
+export type OrkAcaoDoMaestro = {
+  operation: string
+  available: boolean
+  reason: string
+  preconditions: string[]
+  readback: string
+}
+
+export type OrkItemDoMaestro = {
+  id: string
+  title: string
+  status: string
+  refs: Array<{ kind: string; id: string }>
+  facts: Record<string, string | number | boolean | null>
+  action?: OrkAcaoDoMaestro
+}
+
+export type OrkSecaoDoMaestro = {
+  state: 'available' | 'empty' | 'unavailable' | 'stale' | 'conflict'
+  source: string
+  observedAt: string
+  items: OrkItemDoMaestro[]
+  gaps: string[]
+}
+
+/** Projecao minima do `ork.maestro-snapshot/v1`; o resto do objeto chega como o nucleo mandou. */
+export type OrkMaestro = {
+  schema: 'ork.maestro-snapshot/v1'
+  observedAt: string
+  sections: Partial<Record<OrkSecao, OrkSecaoDoMaestro>>
+  gaps: string[]
+}
+
+export type OrkRetrato = {
+  /** De onde veio: o MCP do nucleo, a reserva pelo CLI ou o cache da ponte. */
+  fonte: 'mcp' | 'cli' | 'cache'
+  /** Quando a ponte leu, em ms desde a epoca (relogio do `$.clock`). */
+  lidoEm: number
+  retrato: OrkMaestro
+}
+
+/** O `stat` dos ledgers cobertos por um retrato guardado. */
+export type OrkAssinatura = Array<{ caminho: string; tamanho: number; mtimeMs: number } | { caminho: string; ausente: true }>
+
+export type OrkRetratoGuardado = {
+  fonte: 'mcp' | 'cli'
+  lidoEm: number
+  retrato: unknown
+  caminhos: string[]
+  assinatura: OrkAssinatura
+}
+
+/** A linha que um mod publica na faixa. */
+export type OrkLinhaDaFaixa = {
+  mod: string
+  texto: string
+  /** Quando foi publicada, em ms desde a epoca. */
+  em: number
+}
+
+/** Onde um mod mostrou algo ao dono. */
+export type OrkCanal = 'faixa' | 'painel' | 'notificacao' | 'toast' | 'status' | 'transcript'
+
+/** O que um mod diz ter mostrado ao dono: `chave` agrupa o que e a mesma coisa (por exemplo, `hitl:<pedido>`). */
+export type OrkMostrado = {
+  mod: string
+  canal: OrkCanal
+  texto: string
+  chave?: string
+  thread?: string
+}
+
+/** O registro `ork.mod-mostrado/v1` no `$.store` da ponte, para o nucleo deduplicar o Telegram depois. */
+export type OrkRegistroDeMostrados = {
+  formato: 'ork.mod-mostrado/v1'
+  itens: Array<{
+    mod: string
+    canal: OrkCanal
+    chave: string | null
+    thread: string | null
+    texto: string
+    primeiraVez: string
+    ultimaVez: string
+    vezes: number
+  }>
+}
+
+export type OrkVigia = {
+  /** Os caminhos que este mod pediu, como ficaram guardados. */
+  caminhos: string[]
+  /** O `SessionStart` desta sessao ja respondeu: o pedido so vale no proximo (`/clear`, retomada). */
+  valeNoProximoInicio: boolean
+}
+
+export type Ork = {
+  /** O papel desta sessao. */
+  papel: () => Promise<OrkPapel>
+  /** Papel, thread do despacho e raiz da sessao. */
+  contexto: () => Promise<OrkContexto>
+  /**
+   * O retrato do nucleo pelo `ork_maestro`, com reserva na consulta `maestro` do CLI (teto de 10 s).
+   * Volta do cache enquanto o `stat` dos ledgers cobertos nao muda, por no maximo 60 s.
+   */
+  retrato: (pedido?: OrkPedidoDeRetrato) => Promise<OrkRetrato>
+  /** Uma consulta da lista fechada pelo CLI, com teto de 10 s; recusa o que estiver fora dela. */
+  ler: (pedido: OrkPedidoDeLeitura) => Promise<unknown>
+  /**
+   * Publica (ou tira, sem `texto`) a linha deste mod na faixa acima do prompt, que so a ponte desenha.
+   * Na sessao do dono, a linha publicada entra no registro do que foi mostrado.
+   */
+  faixa: (pedido: { mod: string; texto?: string }) => Promise<{ publicada: boolean }>
+  /** Pede caminhos absolutos para o `watchPaths`, que so a ponte responde; sem caminhos, tira o pedido. */
+  vigiar: (pedido: { mod: string; caminhos: string[] }) => Promise<OrkVigia>
+  /** Registra o que o mod mostrou ao dono fora da faixa (painel, notificacao, toast, status). */
+  mostrado: (pedido: OrkMostrado) => Promise<void>
+  /** O registro do que os mods mostraram ao dono. */
+  mostrados: () => Promise<OrkRegistroDeMostrados>
+}
+
+declare module 'claude-code' {
+  interface EngineInterface {
+    ork: Ork
+  }
+  interface PluginState {
+    'ork-ponte': {
+      /** Os retratos guardados, por pedido. */
+      retratos: Record<string, OrkRetratoGuardado>
+      /** As linhas da faixa, uma por mod. */
+      faixa: OrkLinhaDaFaixa[]
+      /** Os caminhos que cada mod pediu para vigiar. */
+      vigias: Record<string, string[]>
+    }
+  }
+}

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

@@ -0,0 +1,14 @@
+{
+  "name": "ork-portao",
+  "version": "0.1.0",
+  "description": "Portão de Tarefas do Orkastery no Claude Code: na sessão de fase do GO, cada tarefa do quadro é uma tarefa do plano com touch_paths e verify, só fecha com a conferência do núcleo aprovada e, com agent teams no piloto, vai ao teammate ocioso com lease livre.",
+  "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-portao/hooks/hooks.json

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