Troubleshooting the daemon

Troubleshooting

Most daemon issues fall into five buckets. Each has a designed behaviour behind it; the fix is usually to read what the system is telling you rather than to retry harder.

Retrieval returned less than expected

Every retrieval call carries a hard token_budget and the daemon trims to fit. A short answer usually means a tight budget, not missing data. Raise the budget deliberately for that call; do not remove budgets globally, they are the guard against context blowouts.

A call was refused

Under RCX enforce posture, refusals fail closed and mint a signed RefusalReceipt with a reason code. The reason code names the missing scope (tool, tenant, or tier). Fix the grant, or if the refusal was correct, congratulations: policy is working. In observe posture nothing is blocked; check the posture before assuming a bug.

Verification failed

Treat a failed corecruxctl verify-store as an incident, not a nuisance. The chain does not break by accident; something modified state outside the daemon's write path. Preserve the store, verify a backup, and investigate before writing anything else.

Revocation has not settled

Revocation is a signed pull with per-agent acknowledgements. The attestation only issues when zero holders remain, so a pending revocation means named agents have not acked. The console shows which ones; chase those agents rather than re-issuing the pull.

Dense retrieval is empty

The local dense lane needs a bring-your-own embedder (Ollama, vLLM, TEI, llama.cpp, LiteLLM). Until one is configured, lexical plus graph retrieval carries the load; that is expected, not degraded.

Where to look

The operator console at localhost:14800 shows sessions, the work board, and the relation graph. Start there before reaching for raw logs.