@orkastery/cli 0.5.3 → 0.6.0

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

@@ -0,0 +1,410 @@
+// A regra de autoridade dos mods do Orkastery (RM-059, T0.5 e T0.6; D5 do plano dos mods): nenhum mod
+// aprova gate, permissao, nota do MASTER, push ou tag pelo dono, nem fala como o dono. A lista mora em
+// `adapters/claude-code/mods/autoridade.json`; este modulo so a interpreta, e e o mesmo casamento para a
+// guarda estatica (`core/scripts/checar-mods.cjs`, por transpilacao) e para a guarda em tempo de execucao
+// da ponte. Modulo puro: so dados entram e saem, nenhum `$` passa por aqui. E melhor esforco: argv montado
+// em tempo de execucao escapa da varredura estatica, e um script em arquivo escapa das duas.
+
+export const FORMATO_DA_AUTORIDADE = 'ork.mods-autoridade/v1'
+export const NOME_DA_PONTE = 'ork-ponte'
+export const MARCA_DE_MOD = 'orkastery-mod.json'
+
+export type RegraDeArgv = {
+  id: string
+  porque: string
+  /** Comando do `ork`: o prefixo das palavras posicionais, como o `parseArgs` do CLI as separa. */
+  sequencia?: string[]
+  /** Opcao que precisa estar junto (`--score`, `--por`, `--autorizar-push`). */
+  opcao?: string
+  /** Programa na posicao de comando (`git`, `gh`). */
+  programa?: string
+  /** Subcomando do programa (`push`, `tag`); sem ele, o programa inteiro. */
+  subcomando?: string
+}
+
+export type Autoridade = {
+  formato: string
+  regra: string
+  ganchosProibidos: Array<{ id: string; evento: string; componente?: string; porque: string }>
+  decisoesProibidas: Array<{ id: string; evento: string; decisao: string; porque: string }>
+  chamadasProibidas: Array<{ id: string; chamada: string; tipo?: string; porque: string }>
+  argvProibido: RegraDeArgv[]
+  ambienteProibido: Array<{ id: string; prefixo: string; porque: string }>
+  caminhosProibidos: Array<{ id: string; trecho: string; porque: string }>
+  reservadosAPonte: Array<{ id: string; evento: string; porque: string }>
+  permitidos: Array<{ id: string; sequencia: string[]; porque: string }>
+}
+
+/** O que a guarda achou: a regra (id) e o porque, para a recusa dizer o motivo. */
+export type Achado = { regra: string; porque: string }
+
+const SECOES = ['ganchosProibidos', 'decisoesProibidas', 'chamadasProibidas', 'argvProibido', 'ambienteProibido',
+  'caminhosProibidos', 'reservadosAPonte', 'permitidos'] as const
+
+function texto(v: unknown): v is string {
+  return typeof v === 'string' && v.trim() !== ''
+}
+
+function listaDeTexto(v: unknown): v is string[] {
+  return Array.isArray(v) && v.length > 0 && v.every(texto)
+}
+
+/** Confere a forma da lista; qualquer desvio e erro, porque a guarda fecha sem lista valida. */
+export function validarAutoridade(x: unknown): Autoridade {
+  const a = x as Record<string, unknown> | null
+  if (!a || typeof a !== 'object' || Array.isArray(a)) throw new Error('lista de autoridade nao e um objeto')
+  if (a.formato !== FORMATO_DA_AUTORIDADE) throw new Error(`formato da lista de autoridade: ${String(a.formato)}`)
+  if (!texto(a.regra)) throw new Error('lista de autoridade sem regra')
+  const ids = new Set<string>()
+  for (const secao of SECOES) {
+    const itens = a[secao]
+    if (!Array.isArray(itens)) throw new Error(`lista de autoridade sem a secao ${secao}`)
+    for (const bruto of itens) {
+      const item = bruto as Record<string, unknown>
+      if (!item || !texto(item.id) || !texto(item.porque)) throw new Error(`item sem id ou porque em ${secao}`)
+      if (ids.has(item.id as string)) throw new Error(`id repetido na lista de autoridade: ${String(item.id)}`)
+      ids.add(item.id as string)
+      const falta = (campo: string) => { throw new Error(`${secao}/${String(item.id)} sem ${campo}`) }
+      if ((secao === 'ganchosProibidos' || secao === 'reservadosAPonte' || secao === 'decisoesProibidas') && !texto(item.evento)) falta('evento')
+      if (secao === 'decisoesProibidas' && !texto(item.decisao)) falta('decisao')
+      if (secao === 'chamadasProibidas' && !texto(item.chamada)) falta('chamada')
+      if (secao === 'ambienteProibido' && !texto(item.prefixo)) falta('prefixo')
+      if (secao === 'caminhosProibidos' && !texto(item.trecho)) falta('trecho')
+      if (secao === 'permitidos' && !listaDeTexto(item.sequencia)) falta('sequencia')
+      if (secao === 'argvProibido') {
+        const porSequencia = listaDeTexto(item.sequencia)
+        const porPrograma = texto(item.programa)
+        if (porSequencia === porPrograma) throw new Error(`argvProibido/${String(item.id)} precisa de sequencia ou programa, um so`)
+        if (item.opcao !== undefined && !(texto(item.opcao) && (item.opcao as string).startsWith('--'))) falta('opcao com --')
+        if (item.subcomando !== undefined && !texto(item.subcomando)) falta('subcomando')
+      }
+    }
+  }
+  return a as unknown as Autoridade
+}
+
+/** Le e confere o texto do `autoridade.json`. */
+export function lerAutoridade(conteudo: string): Autoridade {
+  return validarAutoridade(JSON.parse(conteudo))
+}
+
+/** Mod do Orkastery: nome `ork-*` ou pasta com `orkastery-mod.json` (os conhecidos vem do `plugin.register`). */
+export function ehModDoOrkastery(nome: unknown, conhecidos?: { has: (n: string) => boolean }): boolean {
+  return typeof nome === 'string' && (nome.startsWith('ork-') || (conhecidos?.has(nome) ?? false))
+}
+
+function nomeBase(token: string): string {
+  const t = token.replace(/\/+$/, '')
+  return t.slice(t.lastIndexOf('/') + 1)
+}
+
+/** As palavras posicionais e as opcoes, exatamente como o `parseArgs` do CLI do ork as separa. */
+export function separarArgs(resto: readonly string[]): { posicionais: string[]; opcoes: Set<string> } {
+  const posicionais: string[] = []
+  const opcoes = new Set<string>()
+  for (let i = 0; i < resto.length; i++) {
+    const a = resto[i] as string
+    if (a.startsWith('--')) {
+      const igual = a.indexOf('=')
+      if (igual > 0) { opcoes.add(a.slice(2, igual)); continue }
+      opcoes.add(a.slice(2))
+      const proximo = resto[i + 1]
+      if (proximo !== undefined && !proximo.startsWith('--')) i++
+    } else posicionais.push(a)
+  }
+  return { posicionais, opcoes }
+}
+
+function comecaCom(lista: readonly string[], prefixo: readonly string[]): boolean {
+  return prefixo.length > 0 && prefixo.every((p, i) => lista[i] === p)
+}
+
+const WRAPPERS = new Set(['env', 'nohup', 'timeout', 'nice', 'ionice', 'setsid', 'stdbuf', 'sudo', 'doas', 'command',
+  'exec', 'time', 'xargs', 'chrt', 'taskset', 'unbuffer', 'then', 'do', 'else', 'if', 'while', 'until', '!'])
+const OPCOES_COM_VALOR: Record<string, readonly string[]> = {
+  env: ['-u', '--unset', '-C', '--chdir'], sudo: ['-u', '-g', '-C', '-D', '-h', '-p', '-r', '-t', '-U'],
+  nice: ['-n', '--adjustment'], ionice: ['-c', '-n', '-p'], timeout: ['-k', '--kill-after', '-s', '--signal'],
+  xargs: ['-a', '-d', '-E', '-I', '-L', '-n', '-P', '-s'], chrt: ['-p'], taskset: ['-p'], doas: ['-u', '-C'],
+}
+const SHELLS = new Set(['sh', 'bash', 'dash', 'zsh', 'ksh', 'mksh', 'ash', 'fish', 'busybox'])
+const INTERPRETADORES: Record<string, readonly string[]> = {
+  node: ['-e', '--eval', '-p', '--print'], nodejs: ['-e', '--eval', '-p', '--print'], deno: ['eval'],
+  bun: ['-e', '--eval'], python: ['-c'], python3: ['-c'], perl: ['-e', '-E'], ruby: ['-e'], php: ['-r'],
+}
+const OPCOES_GLOBAIS_DO_GIT = ['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env']
+const ENTRADA_DO_ORK = /(^|\/)(ork|ork\.c?js|ork\.mjs|index\.c?js|cli\.c?js)$/
+const MAX_PROFUNDIDADE = 4
+
+/**
+ * Tira o que so embrulha o comando (`env A=1`, `nohup`, `timeout 10`, `sudo -u x`) e devolve o comando de fato.
+ * `env` sem comando imprime o ambiente inteiro: `despejo` avisa isso.
+ */
+function semEmbrulho(tokens: readonly string[]): { tokens: string[]; scriptDoEnv?: string; despejo?: boolean } {
+  let t = [...tokens]
+  let ultimo = ''
+  for (let voltas = 0; voltas < 8 && t.length > 0; voltas++) {
+    while (t.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(t[0] as string)) t = t.slice(1)
+    const base = nomeBase(t[0] ?? '')
+    if (!WRAPPERS.has(base)) break
+    ultimo = base
+    t = t.slice(1)
+    const comValor = OPCOES_COM_VALOR[base] ?? []
+    while (t.length > 0) {
+      const a = t[0] as string
+      if (base === 'env' && (a === '-S' || a === '--split-string')) return { tokens: [], scriptDoEnv: t[1] ?? '' }
+      if (comValor.includes(a)) { t = t.slice(2); continue }
+      if (a.startsWith('-') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(a)) { t = t.slice(1); continue }
+      if (base === 'timeout' && /^\d+(\.\d+)?[smhd]?$/.test(a)) { t = t.slice(1); continue }
+      break
+    }
+  }
+  return { tokens: t, ...(t.length === 0 && ultimo === 'env' ? { despejo: true } : {}) }
+}
+
+/**
+ * O comando expoe o ambiente inteiro do processo (onde mora `ORK_HITL_*` quando o host o exporta):
+ * `printenv` sem nome, `export -p`, `declare -x`, `set` sem argumento, `compgen -e` ou `/proc/<pid>/environ`.
+ */
+function despejaOAmbiente(tokens: readonly string[]): boolean {
+  const base = nomeBase(tokens[0] ?? '')
+  const args = tokens.slice(1)
+  if (base === 'printenv') return args.every(t => t.startsWith('-'))
+  if (base === 'export') return args.length === 0 || args.includes('-p')
+  if (base === 'declare' || base === 'typeset') return args.some(t => /^-[A-Za-z]*[xp]/.test(t))
+  if (base === 'set') return args.length === 0
+  if (base === 'compgen') return args.includes('-e')
+  return tokens.some(t => /^\/proc\/[^/]+\/environ$/.test(t.replace(/\/{2,}/g, '/')))
+}
+
+/** Uma variavel da lista citada no texto (`echo $ORK_HITL_TOKEN`, `printenv ORK_HITL_TOKEN`). */
+function citaAmbienteProibido(a: Autoridade, texto: string): Achado | null {
+  const r = a.ambienteProibido.find(p => texto.includes(p.prefixo))
+  return r ? { regra: r.id, porque: r.porque } : null
+}
+
+/** Um texto que cita caminho ou variavel da lista, seja ou nao linha de comando (a varredura estatica usa). */
+export function avaliarCitacao(a: Autoridade, texto: unknown): Achado | null {
+  return typeof texto === 'string' ? avaliarCaminho(a, texto) ?? citaAmbienteProibido(a, texto) : null
+}
+
+function despejo(a: Autoridade): Achado | null {
+  const r = a.ambienteProibido[0]
+  return r ? { regra: r.id, porque: `${r.porque} (o comando imprime o ambiente inteiro)` } : null
+}
+
+/** O resto do argv quando ele chama o CLI do ork (por `ork`, `node .../index.js` ou `npx ork`); `null` se nao chama. */
+function restoDoOrk(tokens: readonly string[]): string[] | null {
+  const base = nomeBase(tokens[0] ?? '')
+  if (base === 'ork') return tokens.slice(1)
+  if (base === 'node' || base === 'nodejs') {
+    let i = 1
+    while (i < tokens.length && (tokens[i] as string).startsWith('-')) i += ['-r', '--require', '--import', '--loader'].includes(tokens[i] as string) ? 2 : 1
+    const script = tokens[i]
+    if (script !== undefined && (ENTRADA_DO_ORK.test(script) || script.includes('@orkastery/'))) return tokens.slice(i + 1)
+  }
+  return null
+}
+
+function avaliarOrk(a: Autoridade, resto: readonly string[]): Achado | null {
+  const { posicionais, opcoes } = separarArgs(resto)
+  if (a.permitidos.some(p => comecaCom(posicionais, p.sequencia))) return null
+  for (const r of a.argvProibido) {
+    if (!r.sequencia || !comecaCom(posicionais, r.sequencia)) continue
+    if (r.opcao !== undefined && !opcoes.has(r.opcao.replace(/^--/, ''))) continue
+    return { regra: r.id, porque: r.porque }
+  }
+  return null
+}
+
+function avaliarPrograma(a: Autoridade, tokens: readonly string[]): Achado | null {
+  const base = nomeBase(tokens[0] ?? '')
+  for (const r of a.argvProibido) {
+    if (!r.programa || r.programa !== base) continue
+    if (r.subcomando === undefined) return { regra: r.id, porque: r.porque }
+    let i = 1
+    while (i < tokens.length) {
+      const t = tokens[i] as string
+      if (base === 'git' && OPCOES_GLOBAIS_DO_GIT.includes(t)) { i += 2; continue }
+      if (t.startsWith('-')) { i++; continue }
+      break
+    }
+    if (tokens[i] === r.subcomando) return { regra: r.id, porque: r.porque }
+  }
+  return null
+}
+
+/** Um caminho lido ou citado que esta na lista (`.hermes/.env`), com as barras normalizadas. */
+export function avaliarCaminho(a: Autoridade, caminho: unknown): Achado | null {
+  if (typeof caminho !== 'string') return null
+  // Grafia normalizada e sem diferenca de maiusculas: num sistema que as ignora, `.HERMES/.env` e o mesmo arquivo.
+  const normal = caminho.replace(/\\/g, '/').replace(/\/(\.\/)+/g, '/').replace(/\/{2,}/g, '/').toLowerCase()
+  const r = a.caminhosProibidos.find(c => normal.includes(c.trecho.toLowerCase()))
+  return r ? { regra: r.id, porque: r.porque } : null
+}
+
+/** Uma variavel de ambiente da lista (`ORK_HITL_*`). */
+export function avaliarAmbiente(a: Autoridade, nome: unknown): Achado | null {
+  if (typeof nome !== 'string') return null
+  const r = a.ambienteProibido.find(p => nome.startsWith(p.prefixo))
+  return r ? { regra: r.id, porque: r.porque } : null
+}
+
+/** Separa um texto de shell em comandos e palavras: aspas respeitadas; `;`, `&`, `|`, `(`, `)`, crase e `$(` cortam. */
+export function comandosDoTexto(textoDoShell: string): string[][] {
+  const comandos: string[][] = []
+  let atual: string[] = []
+  let palavra = ''
+  let temPalavra = false
+  let aspa: '"' | "'" | null = null
+  const fecharPalavra = () => { if (temPalavra) atual.push(palavra); palavra = ''; temPalavra = false }
+  const fecharComando = () => { fecharPalavra(); if (atual.length > 0) comandos.push(atual); atual = [] }
+  for (let i = 0; i < textoDoShell.length; i++) {
+    const c = textoDoShell[i] as string
+    if (aspa !== null) {
+      if (c === aspa) aspa = null
+      else palavra += c
+      continue
+    }
+    if (c === '"' || c === "'") { aspa = c; temPalavra = true; continue }
+    if (c === '\\' && i + 1 < textoDoShell.length) { palavra += textoDoShell[++i]; temPalavra = true; continue }
+    if (c === ' ' || c === '\t') { fecharPalavra(); continue }
+    if (c === ';' || c === '&' || c === '|' || c === '\n' || c === '(' || c === ')' || c === '`' || c === '{' || c === '}') { fecharComando(); continue }
+    if (c === '$' && textoDoShell[i + 1] === '(') { fecharComando(); i++; continue }
+    palavra += c
+    temPalavra = true
+  }
+  fecharComando()
+  return comandos
+}
+
+/** Codigo de interpretador (`node -e`, `python -c`): leitura solta, por palavras, so para pegar o obvio. */
+function avaliarCodigoSolto(a: Autoridade, codigo: string): Achado | null {
+  const palavras = codigo.split(/[^A-Za-z0-9_.\/@-]+/).filter(Boolean)
+  for (let i = 0; i < palavras.length; i++) {
+    const base = nomeBase(palavras[i] as string)
+    for (const r of a.argvProibido) {
+      if (r.programa && r.programa === base) {
+        if (r.subcomando === undefined || palavras.slice(i + 1, i + 6).includes(r.subcomando)) return { regra: r.id, porque: r.porque }
+      }
+      if (r.sequencia && comecaCom(palavras.slice(i), r.sequencia)) {
+        if (r.opcao === undefined || palavras.includes(r.opcao)) return { regra: r.id, porque: r.porque }
+      }
+    }
+  }
+  return avaliarCaminho(a, codigo)
+}
+
+/** Um texto de shell: cada comando dele passa pela regra de argv. */
+export function avaliarTexto(a: Autoridade, textoDoShell: string, profundidade = 0): Achado | null {
+  const direto = avaliarCaminho(a, textoDoShell) ?? citaAmbienteProibido(a, textoDoShell)
+  if (direto) return direto
+  for (const comando of comandosDoTexto(textoDoShell)) {
+    const achado = avaliarArgv(a, comando, undefined, profundidade + 1)
+    if (achado) return achado
+  }
+  return null
+}
+
+/**
+ * Um argv que um mod quer rodar (`$.process.run`, `$.process.spawn`), com o texto do `stdin` quando o comando e
+ * um shell que le o script da entrada. Devolve o primeiro achado ou `null`.
+ */
+export function avaliarArgv(a: Autoridade, argv: readonly unknown[], stdin?: unknown, profundidade = 0): Achado | null {
+  if (profundidade > MAX_PROFUNDIDADE) return { regra: 'profundidade', porque: 'comando aninhado demais para a guarda conferir' }
+  const brutos = argv.map(t => String(t))
+  for (const t of brutos) {
+    const achado = avaliarCaminho(a, t) ?? citaAmbienteProibido(a, t)
+    if (achado) return achado
+  }
+  if (typeof stdin === 'string') {
+    const noStdin = citaAmbienteProibido(a, stdin)
+    if (noStdin) return noStdin
+  }
+  const { tokens, scriptDoEnv, despejo: soEnv } = semEmbrulho(brutos)
+  if (scriptDoEnv !== undefined) return avaliarTexto(a, scriptDoEnv, profundidade)
+  if (soEnv || despejaOAmbiente(tokens)) return despejo(a)
+  if (tokens.length === 0) return null
+  const base = nomeBase(tokens[0] as string)
+  if (base === 'eval') return avaliarTexto(a, tokens.slice(1).join(' '), profundidade)
+  if (SHELLS.has(base)) {
+    const i = tokens.findIndex((t, j) => j > 0 && /^-[A-Za-z]*c[A-Za-z]*$/.test(t))
+    if (i > 0) return tokens[i + 1] === undefined ? null : avaliarTexto(a, tokens[i + 1] as string, profundidade)
+    const temScript = tokens.slice(1).some(t => !t.startsWith('-'))
+    if (!temScript && typeof stdin === 'string') return avaliarTexto(a, stdin, profundidade)
+    return null
+  }
+  const inline = INTERPRETADORES[base]
+  if (inline) {
+    const i = tokens.findIndex((t, j) => j > 0 && inline.includes(t))
+    if (i > 0 && tokens[i + 1] !== undefined) return avaliarCodigoSolto(a, tokens[i + 1] as string)
+  }
+  if (['npx', 'pnpx', 'bunx'].includes(base)) {
+    let i = 1
+    while (i < tokens.length && (tokens[i] as string).startsWith('-')) i++
+    const alvo = tokens[i] ?? ''
+    if (alvo === 'ork' || alvo.startsWith('@orkastery/')) return avaliarOrk(a, tokens.slice(i + 1))
+    return avaliarArgv(a, tokens.slice(i), undefined, profundidade + 1)
+  }
+  if (['npm', 'pnpm', 'yarn', 'bun'].includes(base)) {
+    // `npm exec`, `pnpm dlx`, `yarn run` e tambem `yarn <bin>` e `pnpm <bin>`, que rodam o binario sem subcomando, e
+    // opcao com valor no meio (`yarn --cwd x ork ...`): cada posicao depois do gerenciador e tentada como comando.
+    for (let i = 1; i < tokens.length && i <= 12; i++) {
+      const alvo = tokens[i] as string
+      if (alvo.startsWith('-')) continue
+      const achado = alvo === 'ork' || alvo.startsWith('@orkastery/') ? avaliarOrk(a, tokens.slice(i + 1))
+        : avaliarArgv(a, tokens.slice(i), undefined, profundidade + 1)
+      if (achado) return achado
+    }
+    return null
+  }
+  const programa = avaliarPrograma(a, tokens)
+  if (programa) return programa
+  const resto = restoDoOrk(tokens)
+  return resto === null ? null : avaliarOrk(a, resto)
+}
+
+type Glob = { exato: string } | { prefixo: string }
+
+function glob(padrao: string): Glob {
+  if (padrao === '*') return { prefixo: '' }
+  return padrao.endsWith('.*') ? { prefixo: padrao.slice(0, -1) } : { exato: padrao }
+}
+
+/** O padrao de um `on(...)` (`*`, `fs.*`, `fs.read`) alcanca o evento ou o padrao da lista? */
+export function sobrepoe(padraoDoMod: string, padraoDaLista: string): boolean {
+  if (padraoDoMod.startsWith('!')) return false
+  if (padraoDoMod.startsWith('telemetry.') || padraoDaLista.startsWith('telemetry.')) return padraoDoMod === padraoDaLista
+  const m = glob(padraoDoMod)
+  const l = glob(padraoDaLista)
+  if ('exato' in m && 'exato' in l) return m.exato === l.exato
+  if ('exato' in m) return m.exato.startsWith((l as { prefixo: string }).prefixo)
+  if ('exato' in l) return l.exato.startsWith(m.prefixo)
+  return m.prefixo.startsWith(l.prefixo) || l.prefixo.startsWith(m.prefixo)
+}
+
+/** Ganchos de um mod (os padroes do `on`): proibidos (sem componente) ou reservados a ponte. */
+export function avaliarEventos(a: Autoridade, eventos: readonly string[], ehPonte = false): Achado | null {
+  for (const evento of eventos) {
+    const proibido = a.ganchosProibidos.find(g => g.componente === undefined && sobrepoe(evento, g.evento))
+    if (proibido) return { regra: proibido.id, porque: proibido.porque }
+    if (ehPonte) continue
+    const reservado = a.reservadosAPonte.find(r => sobrepoe(evento, r.evento))
+    if (reservado) return { regra: reservado.id, porque: `gancho reservado a ponte: ${reservado.porque}` }
+  }
+  return null
+}
+
+/** O que o motor escaneou de um modulo no `plugin.register`: ganchos, chamadas e variaveis lidas. */
+export function avaliarUses(a: Autoridade, uses: { events?: readonly string[]; calls?: readonly string[]; env?: { reads?: readonly string[] } },
+  ehPonte = false): Achado | null {
+  const eventos = avaliarEventos(a, uses.events ?? [], ehPonte)
+  if (eventos) return eventos
+  for (const c of a.chamadasProibidas) {
+    if (c.tipo === undefined && (uses.calls ?? []).includes(c.chamada)) return { regra: c.id, porque: c.porque }
+  }
+  for (const nome of uses.env?.reads ?? []) {
+    const achado = avaliarAmbiente(a, nome)
+    if (achado) return achado
+  }
+  return null
+}

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

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

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

@@ -0,0 +1,55 @@
+// O registro do que um mod mostrou ao dono (RM-059, M5 do dono; D8 da thread). O Telegram nao deve
+// repetir o que o dono ja viu no terminal: a ponte guarda o que foi mostrado num formato versionado, no
+// proprio `$.store`, para o nucleo deduplicar depois. Um item por mod, chave e texto. Modulo puro.
+import type { OrkCanal, OrkMostrado, OrkRegistroDeMostrados } from '../types'
+
+export const FORMATO_DO_MOSTRADO = 'ork.mod-mostrado/v1'
+export const CHAVE_NO_STORE = 'mostrados'
+export const TETO_DE_MOSTRADOS = 200
+export const TETO_DO_TEXTO_MOSTRADO = 500
+export const CANAIS: readonly OrkCanal[] = ['faixa', 'painel', 'notificacao', 'toast', 'status', 'transcript']
+const NOME_DE_MOD = /^[a-z0-9][a-z0-9-]{0,63}$/
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+
+function vazio(): OrkRegistroDeMostrados {
+  return { formato: FORMATO_DO_MOSTRADO, itens: [] }
+}
+
+/** O registro guardado, ou um vazio se o que estava no store nao e deste formato. */
+export function lerRegistro(guardado: unknown): OrkRegistroDeMostrados {
+  const r = guardado as Partial<OrkRegistroDeMostrados> | null | undefined
+  if (!r || r.formato !== FORMATO_DO_MOSTRADO || !Array.isArray(r.itens)) return vazio()
+  return { formato: FORMATO_DO_MOSTRADO, itens: r.itens.filter(i => i && typeof i.mod === 'string' && typeof i.texto === 'string') }
+}
+
+/** Confere o que o mod diz ter mostrado. */
+export function conferirMostrado(m: unknown): OrkMostrado {
+  const x = (m ?? {}) as Record<string, unknown>
+  if (typeof x.mod !== 'string' || !NOME_DE_MOD.test(x.mod)) throw new Error('ork-ponte: nome de mod invalido')
+  if (typeof x.canal !== 'string' || !CANAIS.includes(x.canal as OrkCanal)) throw new Error(`ork-ponte: canal desconhecido: ${String(x.canal)}`)
+  if (typeof x.texto !== 'string' || x.texto.trim() === '') throw new Error('ork-ponte: texto mostrado vazio')
+  if (x.chave !== undefined && (typeof x.chave !== 'string' || x.chave.length > 200)) throw new Error('ork-ponte: chave invalida')
+  if (x.thread !== undefined && (typeof x.thread !== 'string' || !ID_DE_THREAD.test(x.thread))) throw new Error('ork-ponte: id de thread invalido')
+  return {
+    mod: x.mod, canal: x.canal as OrkCanal, texto: x.texto,
+    ...(x.chave !== undefined ? { chave: x.chave as string } : {}),
+    ...(x.thread !== undefined ? { thread: x.thread as string } : {}),
+  }
+}
+
+/**
+ * Acrescenta o que foi mostrado: o mesmo mod, chave e texto so ganham `ultimaVez` e mais uma vez; o resto
+ * entra no fim. Acima do teto saem os vistos ha mais tempo.
+ */
+export function registrarMostrado(guardado: unknown, m: OrkMostrado, agoraIso: string): OrkRegistroDeMostrados {
+  const r = lerRegistro(guardado)
+  const texto = m.texto.replace(/\s+/g, ' ').trim().slice(0, TETO_DO_TEXTO_MOSTRADO)
+  const chave = m.chave ?? null
+  const mesmo = (i: OrkRegistroDeMostrados['itens'][number]) => i.mod === m.mod && i.chave === chave && i.texto === texto
+  const anterior = r.itens.find(mesmo)
+  const resto = r.itens.filter(i => !mesmo(i))
+  const item = anterior
+    ? { ...anterior, canal: m.canal, ultimaVez: agoraIso, vezes: anterior.vezes + 1 }
+    : { mod: m.mod, canal: m.canal, chave, thread: m.thread ?? null, texto, primeiraVez: agoraIso, ultimaVez: agoraIso, vezes: 1 }
+  return { formato: FORMATO_DO_MOSTRADO, itens: [...resto, item].slice(-TETO_DE_MOSTRADOS) }
+}

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

@@ -0,0 +1,157 @@
+// A leitura do nucleo pela ponte (RM-059, T0.3; D3 e D10 da thread). Modulo puro: monta o pedido ao
+// `ork_maestro`, a lista fechada de consultas do CLI e o cache por `stat`. As chamadas ao `$` ficam
+// no register.ts. Dados so pelo nucleo: nada aqui le ou escreve estado em `.orkastery/`.
+import type { OrkAssinatura, OrkConsulta, OrkPedidoDeLeitura, OrkPedidoDeRetrato, OrkRetratoGuardado, OrkSecao } from '../types'
+
+export const SERVIDOR = 'orkastery'
+export const FERRAMENTA_DO_RETRATO = 'ork_maestro'
+/** Teto de cada consulta pelo CLI (D10): o mesmo teto total do retrato no nucleo. */
+export const TETO_DO_CLI_MS = 10000
+/** O cache vale enquanto os ledgers cobertos nao mudam, e nunca por mais que isto. */
+export const TETO_DO_CACHE_MS = 60000
+export const TETO_DE_ENTRADAS = 16
+export const TETO_DE_LEDGERS = 50
+/** As secoes do `ork.maestro-snapshot/v1` (core/src/maestro-contract.ts). */
+export const SECOES: readonly OrkSecao[] = ['portfolio', 'demands', 'threads', 'sessions', 'blockers', 'leases',
+  'retries', 'hitl', 'ship', 'master', 'nextActions']
+
+const ID_DE_THREAD = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/
+
+/** A lista fechada de consultas de leitura (D10): o argv depois de `ork`, e se exige thread. */
+export const CONSULTAS: Readonly<Record<OrkConsulta, { argv: readonly string[]; exigeThread: boolean }>> = {
+  'maestro': { argv: ['maestro', '--json'], exigeThread: false },
+  'thread.status': { argv: ['thread', 'status', '<thread>', '--json'], exigeThread: true },
+  'thread.list': { argv: ['thread', 'list', '--json'], exigeThread: false },
+  'conducao.status': { argv: ['conducao', 'status', '<thread>', '--json'], exigeThread: true },
+  'retry.plan': { argv: ['retry', 'plan', '<thread>', '--json'], exigeThread: true },
+  'retry.list': { argv: ['retry', 'list', '--json'], exigeThread: false },
+  'pulse': { argv: ['pulse', '--json'], exigeThread: false },
+  'orquestracao.status': { argv: ['orquestracao', 'status', '--json'], exigeThread: false },
+  'sessions.hitl': { argv: ['sessions', 'hitl', '--json'], exigeThread: false },
+  'roadmap.status': { argv: ['roadmap', 'status', '--json'], exigeThread: false },
+  'accounts.esgotamentos': { argv: ['accounts', 'esgotamentos', '--json'], exigeThread: false },
+  'decisao.placar': { argv: ['decisao', 'placar', '<thread>', '--json'], exigeThread: true },
+}
+
+export class ErroDeLeitura extends Error {}
+
+function conferirThread(thread: unknown): string | undefined {
+  if (thread === undefined) return undefined
+  if (typeof thread !== 'string' || !ID_DE_THREAD.test(thread)) throw new ErroDeLeitura('ork-ponte: id de thread invalido')
+  return thread
+}
+
+/** Confere o pedido de retrato: secao conhecida, offset inteiro e so junto da secao. */
+export function conferirPedidoDeRetrato(p: OrkPedidoDeRetrato | undefined): OrkPedidoDeRetrato {
+  const pedido = p ?? {}
+  const thread = conferirThread(pedido.thread)
+  if (pedido.secao !== undefined && !SECOES.includes(pedido.secao)) throw new ErroDeLeitura(`ork-ponte: secao desconhecida: ${String(pedido.secao)}`)
+  if (pedido.offset !== undefined) {
+    if (pedido.secao === undefined) throw new ErroDeLeitura('ork-ponte: offset so vale com secao')
+    if (!Number.isInteger(pedido.offset) || pedido.offset < 0 || pedido.offset > 100000) throw new ErroDeLeitura('ork-ponte: offset fora da faixa')
+  }
+  return { ...(thread ? { thread } : {}), ...(pedido.secao ? { secao: pedido.secao, offset: pedido.offset ?? 0 } : {}) }
+}
+
+/** Os argumentos do `ork_maestro`: secao e offset andam juntos, como o nucleo exige. */
+export function argsDoMaestro(p: OrkPedidoDeRetrato): Record<string, unknown> {
+  const a: Record<string, unknown> = {}
+  if (p.thread) a.threadId = p.thread
+  if (p.secao) { a.section = p.secao; a.offset = p.offset ?? 0 }
+  return a
+}
+
+/** O argv completo de uma consulta da lista fechada; qualquer outra coisa e recusada. */
+export function argvDaConsulta(p: OrkPedidoDeLeitura & { secao?: OrkSecao; offset?: number }): string[] {
+  const modelo = Object.prototype.hasOwnProperty.call(CONSULTAS, p.consulta) ? CONSULTAS[p.consulta] : undefined
+  if (!modelo) throw new ErroDeLeitura(`ork-ponte: consulta fora da lista fechada: ${String(p.consulta)}`)
+  const thread = conferirThread(p.thread)
+  if (modelo.exigeThread && !thread) throw new ErroDeLeitura(`ork-ponte: a consulta ${p.consulta} exige thread`)
+  const argv = ['ork', ...modelo.argv.map(a => (a === '<thread>' ? (thread as string) : a))]
+  if (p.consulta === 'maestro') {
+    const r = conferirPedidoDeRetrato({ thread, secao: p.secao, offset: p.offset })
+    if (r.thread) argv.push('--thread', r.thread)
+    if (r.secao) argv.push('--section', r.secao, '--offset', String(r.offset ?? 0))
+  }
+  return argv
+}
+
+/** O JSON que o `ork_maestro` devolve no primeiro bloco de texto; recusa resultado com erro. */
+export function interpretarMcp(r: { content?: ReadonlyArray<{ type: string; text?: string }>; isError?: boolean }): unknown {
+  if (r.isError) throw new ErroDeLeitura('ork-ponte: o ork_maestro respondeu com erro')
+  const texto = (r.content ?? []).find(c => c.type === 'text' && typeof c.text === 'string')?.text
+  if (texto === undefined) throw new ErroDeLeitura('ork-ponte: o ork_maestro nao devolveu texto')
+  return JSON.parse(texto)
+}
+
+/** O JSON que o CLI imprime; saida diferente de zero vira erro com o fim do stderr. */
+export function interpretarCli(argv: readonly string[], r: { exitCode: number; stdout: string; stderr: string }): unknown {
+  if (r.exitCode !== 0) {
+    const fim = r.stderr.trim().split('\n').slice(-2).join(' ').slice(0, 300)
+    throw new ErroDeLeitura(`ork-ponte: ${argv.slice(0, 3).join(' ')} saiu ${r.exitCode}${fim ? `: ${fim}` : ''}`)
+  }
+  return JSON.parse(r.stdout)
+}
+
+export type Assinatura = OrkAssinatura
+export type EntradaDoCache = OrkRetratoGuardado
+
+export function chaveDoPedido(p: OrkPedidoDeRetrato): string {
+  return JSON.stringify([p.thread ?? null, p.secao ?? null, p.offset ?? null])
+}
+
+function pai(dir: string): string {
+  const sem = dir.replace(/\/+$/, '')
+  const i = sem.lastIndexOf('/')
+  return i <= 0 ? '/' : sem.slice(0, i)
+}
+
+function juntar(pasta: string, nome: string): string {
+  return pasta.replace(/\/+$/, '') + '/' + nome
+}
+
+/** Os ledgers que o retrato cobre: o da thread pedida, ou os das threads da secao `threads` e a pasta delas. */
+export function caminhosCobertos(raizDoEstado: string | null, p: OrkPedidoDeRetrato, retrato: unknown): string[] {
+  if (!raizDoEstado) return []
+  const base = juntar(raizDoEstado, '.orkastery/threads')
+  if (p.thread) return [juntar(base, `${p.thread}/ledger.jsonl`)]
+  const itens = (retrato as { sections?: { threads?: { items?: Array<{ id?: unknown }> } } } | null)?.sections?.threads?.items ?? []
+  const ids = [...new Set(itens.map(i => i.id).filter((id): id is string => typeof id === 'string' && ID_DE_THREAD.test(id)))]
+  return [base, ...ids.slice(0, TETO_DE_LEDGERS).map(id => juntar(base, `${id}/ledger.jsonl`))]
+}
+
+/** O cache serve so com a mesma assinatura de `stat` e dentro do teto de idade. */
+export function cacheValido(e: EntradaDoCache | undefined, atual: Assinatura, agora: number, teto = TETO_DO_CACHE_MS): boolean {
+  if (!e || e.caminhos.length === 0) return false
+  const idade = agora - e.lidoEm
+  if (!(idade >= 0 && idade < teto)) return false
+  return JSON.stringify(e.assinatura) === JSON.stringify(atual)
+}
+
+/** Guarda a entrada e corta as mais velhas acima do teto de entradas. */
+export function guardar(cache: Readonly<Record<string, EntradaDoCache>> | undefined, chave: string, e: EntradaDoCache,
+  teto = TETO_DE_ENTRADAS): Record<string, EntradaDoCache> {
+  const todas = Object.entries({ ...(cache ?? {}), [chave]: e }).sort((a, b) => b[1].lidoEm - a[1].lidoEm)
+  return Object.fromEntries(todas.slice(0, teto))
+}
+
+/**
+ * Acha a raiz do estado subindo da raiz da sessao ate a pasta com `orkastery.yaml` e `.orkastery/`
+ * ao lado (a worktree da thread fica dentro do checkout principal). `existe` vem do register.ts.
+ */
+export async function subirAteOEstado(raizDaSessao: string, existe: (caminho: string) => Promise<boolean>, niveis = 8): Promise<string | null> {
+  let dir = raizDaSessao.replace(/\/+$/, '') || '/'
+  for (let i = 0; i <= niveis; i++) {
+    if (await existe(juntar(dir, 'orkastery.yaml')) && await existe(juntar(dir, '.orkastery'))) return dir
+    const acima = pai(dir)
+    if (acima === dir) break
+    dir = acima
+  }
+  return null
+}
+
+/** A raiz do checkout principal pelo `git rev-parse --git-common-dir`, quando ele termina em `/.git`. */
+export function raizPeloGit(saida: string): string | null {
+  const linha = saida.trim().split('\n')[0] ?? ''
+  return /^\/.*\/\.git\/?$/.test(linha) ? linha.replace(/\/\.git\/?$/, '') : null
+}