Guides
Track HITL points and decisions
Distinguish a live session from one that can make progress.
Observe threads and sessions
ork monitor tracks threads; ork sessions hitl finds blocked sessions, including those without a thread. The radar distinguishes human waiting, failure and stale state using runtime evidence. A session listed as live may be waiting for an answer.
The pulse summary goes out through the transport in .orkastery/monitor/pulse-host.json, a file that belongs to this machine. In version 0.6.10, if it is tracked by git, or is a link, it does not count, and the sweep exits with transporte.rastreado without running anything; the same applies to master-host.json for the digest.
ork monitor
ork sessions hitl
ork pulse --jsonAnswer through the authorized channel
Without --registrar, the radar is read-only. The recording option writes actual transitions to the ledger. Questions and options must come from the observed session; unknown state remains unknown. A child session cannot impersonate the owner to answer a gate.
A short question with context
ork.hitl-curto/v1 organizes a title, one-sentence question, what is blocked and since when, one-line options with consequences, a reasoned recommendation and a final response instruction. Evidence, claims, risks and diff are available using the short code followed by detalhes. Authenticated ingress and its HMAC proof remain required. There are up to five options, one marked Recommendation, in at most 15 lines.
ork gate request <thread> --formato telegramRequests from ork as options
Every request that ork itself opens to the owner is a selection of 3 to 5 options, with exactly one marked Recommendation. Registration refuses anything else without recording it: hitl.selecao.fora-da-faixa, hitl.selecao.recomendada or hitl.selecao.texto-livre. A text answer is accepted only with a technical dependency: the exact command the owner runs in the terminal and the reason.
ork prompt lint fails a template that asks for a free-text confirmation or for the owner to paste text (rule hitl-texto-livre). Time blocked by these questions appears in ork ledger stats, in the hitlDeConducao field, with the median compared to the 5-minute target. The same time reaches ork pulse and ork roadmap status: each open question, with how long it has been blocking the thread and since when, in the owner’s timezone, and the median over the last 7 days. The pulse summary gains a line only above the target, alongside the summary that is already due, without breaking the cadence. A native question from a host session keeps the host’s own options.
ork prompt lint
ork ledger stats
ork pulse --json
ork roadmap status --jsonFree text and stable codes
Unambiguous free text (the closed vocabulary, a letter from a to e or a digit from 1 to 5) can map to an option’s action. Ambiguity produces a clarification. A standalone word is accepted only within the core’s open listening window, with one request for the owner across all threads, and never for an irreversible action. The agent cannot answer for the owner.
Reopening the same gate in the same context retains its code. An expired response transfers to a renewed request only when content and context are identical; changes cause rejection. Batches revalidate every gate before recording.
When the runtime falls, the owner is the last resort
ork retry run climbs a ladder with the same prompt and the same sha256: restart the claude-bg daemon, use the block's first fallback target and, last, another profile of the same runtime. Each step goes to the thread ledger as runtime_recuperacao, with the effective destination and the evidence, and a skipped or interrupted step costs no attempt.
Once the three steps are exhausted, the owner is called with gate_blocked human.pending and three options, one recommended, the command that checks the runtime and the one that resumes the phase with the same prompt. The ladder applies per episode and never opens a second session in the same worktree; with a stuck daemon, retry restarts it before the liveness proof, and the third refusal in a row without an answer calls the owner.
ork retry plan <thread>
ork retry run <thread> --dry-runStatus and scores with provenance
ork roadmap status is read-only: it groups the report, marks owner decisions with #HITL and shows the next step. Technical blockers remain the orchestrator’s responsibility, except those only the owner can clear in the terminal, such as trusting the worktree directory or accepting new CLI terms: these become a wait for the owner, with the exact command and ork retry run. In version 0.6.10, the pulse summary lists these blockers in their own block, and a new one goes out right away, without waiting for the cadence.
A request to the owner and a request to conduction are different contracts. When a thread’s session needs an action its sandbox cannot run, it records with ork_request_conduction an enumerated reason and the exact command, without running it. The request shows in the report as conduction work, ork retry does not redispatch the phase while it is open, and none of it reaches the owner as a question.
ork master pedir requests a score from 0 to 5 and a reason through authenticated Telegram; the receipt accompanies the record. In the owner's session, the host's native dialog also collects the score: the ork_request_master_note MCP tool takes only the threadId, asks for the form, and records master_done with autorizadoPor dono (dialogo nativo), the claude-code channel and the signed receipt; without a form in the client, it refuses with master.nota.sem-dialogo without recording anything. The native-dialog score counts as a human score, and an agent-supplied --por cannot replace channel proof.
ork roadmap status
ork master pedir <thread> --formato telegram