Guias
Acompanhe pontos de HITL e decisões
Diferencie uma sessão viva de uma sessão que consegue continuar.
Observe threads e sessões
ork monitor acompanha threads; ork sessions hitl encontra sessões paradas, inclusive as que não têm thread. O radar separa espera humana, falha e estado residual usando a evidência do runtime. Uma sessão listada como viva pode estar aguardando uma resposta.
O resumo do pulse sai pelo transporte de .orkastery/monitor/pulse-host.json, um arquivo desta máquina. Na versão 0.6.10, versionado no git, ou como link, ele não vale, e a varredura sai com transporte.rastreado sem rodar nada; o mesmo vale para o master-host.json do digest.
ork monitor
ork sessions hitl
ork pulse --jsonResponda no canal autorizado
Sem --registrar, o radar é somente leitura. A opção de registro grava transições reais no ledger. Perguntas e alternativas devem vir da sessão observada; um estado desconhecido permanece desconhecido. A sessão filha não se apresenta como o dono para responder um gate.
Uma pergunta curta, com contexto
O contrato ork.hitl-curto/v1 organiza título, pergunta em uma frase, o que trava e desde quando, alternativas de uma linha com consequência, recomendação com motivo e uma última linha dizendo como responder. Evidências, claims, riscos e diff ficam acessíveis pelo código seguido de detalhes. O ingresso autenticado e sua prova HMAC continuam obrigatórios. São até cinco alternativas, uma com o selo Recomendação, em no máximo 15 linhas.
ork gate request <thread> --formato telegramPedidos do ork por alternativas
Todo pedido que o próprio ork abre ao dono é uma seleção de 3 a 5 alternativas, com exatamente uma marcada como Recomendação. O registro recusa, sem gravar nada, o pedido fora disso: hitl.selecao.fora-da-faixa, hitl.selecao.recomendada ou hitl.selecao.texto-livre. Resposta em texto só passa com uma dependência técnica: o comando exato que o dono roda no terminal e o motivo.
ork prompt lint reprova o template que peça um confirmo em texto livre ou que o dono cole texto (regra hitl-texto-livre). O tempo parado por essas perguntas aparece em ork ledger stats, no campo hitlDeConducao, com a mediana comparada à meta de 5 minutos. O mesmo tempo chega ao ork pulse e ao ork roadmap status: cada pergunta aberta, com há quanto tempo para a thread e desde que hora, no fuso do dono, e a mediana dos últimos 7 dias. O resumo do pulse ganha uma linha só acima da meta, junto do resumo que já sai, sem furar a cadência. A pergunta nativa de uma sessão do host continua com as opções do próprio host.
ork prompt lint
ork ledger stats
ork pulse --json
ork roadmap status --jsonTexto livre e linha estável
Texto livre inequívoco (o vocabulário fechado, a letra a a e ou o dígito 1 a 5) pode ser associado à ação de uma alternativa. Ambiguidade volta como pergunta. Uma palavra solta só vale na janela de escuta aberta pelo núcleo, com um único pedido para o dono em todas as threads, e nunca para ato irreversível. O agente não responde pelo dono.
Reabrir o mesmo gate no mesmo contexto mantém o código. Resposta vencida só passa ao pedido renovado quando conteúdo e contexto são idênticos; mudança recusa a resposta. Lotes reconferem cada gate antes de registrar.
Quando o runtime cai, o dono é a última instância
O ork retry run sobe uma escada com o mesmo prompt e o mesmo sha256: reerguer o daemon do claude-bg, usar o primeiro alvo do fallback do bloco e, por último, outro perfil do mesmo runtime. Cada degrau vai ao ledger da thread como runtime_recuperacao, com o destino efetivo e a prova, e o degrau pulado ou interrompido não gasta tentativa.
Esgotados os três degraus, o dono é chamado com gate_blocked human.pending e três alternativas, uma recomendada, o comando que confere o runtime e o que retoma a fase com o mesmo prompt. A escada vale por episódio e nunca abre uma segunda sessão na mesma worktree; com o daemon travado, o retry o reergue antes da prova de vida, e a terceira recusa seguida sem resposta chama o dono.
ork retry plan <thread>
ork retry run <thread> --dry-runStatus e nota com prova de origem
ork roadmap status é leitura pura e reúne o relatório por grupos, #HITL no que espera o dono e o próximo passo. Impedimentos técnicos aparecem como responsabilidade do orquestrador, exceto o que só o dono resolve no terminal, como confiar no diretório da worktree ou aceitar termos novos do CLI: esse vira espera dele, com o comando exato e o ork retry run. Na versão 0.6.10, o resumo do pulse traz esses impedimentos num bloco próprio, e o impedimento novo sai na hora, sem esperar a cadência.
Pedido ao dono e pedido à condução são contratos diferentes. Quando a sessão de uma thread precisa de uma ação que o sandbox dela não pode executar, ela registra com ork_request_conduction um motivo enumerado e o comando exato, sem executá-lo. O pedido aparece no relatório como trabalho da condução, o ork retry não redespacha a fase enquanto ele estiver aberto, e nada disso chega ao dono como pergunta.
ork master pedir solicita a nota de 0 a 5 e o motivo pelo Telegram autenticado; o recibo acompanha a gravação. Na sessão do dono, o diálogo nativo do host também coleta a nota: a ferramenta MCP ork_request_master_note recebe só o threadId, pede o formulário, grava master_done com autorizadoPor dono (dialogo nativo), o canal claude-code e o recibo assinado; sem formulário no cliente, recusa com master.nota.sem-dialogo sem gravar nada. A nota pelo diálogo nativo vale como nota humana, e um --por digitado pelo agente não substitui prova de canal.
ork roadmap status
ork master pedir <thread> --formato telegram