debug-gateway

Reading the kirocrew-debug tools

Five read-only tools answer five questions about the live gateway. The tool descriptions say what each one covers, and docs/reference/debug/README.md carries the rest. This skill is the part neither of them has: which question to ask first, and how to read an answer without drawing the opposite conclusion.

Where the surrounding material lives, all in one reference doc. An installed build does not carry the repository's docs tree, so read it at Debugging a running gateway, or at docs/reference/debug/README.md in a checkout:

• symptom table: section "Symptom to tool"
• the sandbox traps, including the empty placeholder mounts: section "Sandbox traps"
• who may take each reading: section "Authorization"
• why the server is opt-in, and how to grant it: the paragraph above the five questions

Ask before you conclude

1. Before reporting that a change did not work, call debug_gateway. A gateway that started before your commit is executing the previous revision, and a daemon that outlived the change hands out backends built from the old checkout. Both look exactly like a broken fix.
2. A refusal is blocked-by-policy's job; debug_refusals gives it the class.
3. Before calling a refused path protected, read that class. Only sensitive_path_match means the path is protected. unverifiable_path means the path was never judged, and the row's own action line says what to do.

Fields that read as the opposite of what they mean

debug_gateway

gateway_predates_head has three readings, not two. null is neither true nor false: the start time comes from procfs, so it is absent off Linux, and HEAD's commit time needs a git checkout, so it is absent on an installed wheel. Treat null as unmeasured and say so, rather than concluding the gateway is current.

mcp_gateway_daemon.matches_this_install false has two meanings, so read fingerprint beside it. A real fingerprint that differs means the daemon is serving backends built from another checkout, and a directive tool can report success against one. unknown (pre-fingerprint build) means the daemon cannot be compared at all, which is unmeasured rather than stale. A null matches_this_install has two causes, told apart by running beside it: running: false is a measured absence (no daemon), while running: null is a FAILED probe — the daemon could not be described — which is unmeasured, not a confirmed absence. Do not read a failed probe as "no daemon". recorder.available false means the build carries no diagnostics package, which is also why three of the five tools cannot answer on it.