Operate Search docs

Common failures

Start with read-only diagnosis, then gated mutate. Prefer CLI verbs that emit machine-readable reasons.

Quick map

Symptom	First command	Likely page
Local env weird	`hobo doctor`	this page · CLI
Deploy blocked	`hobo verify` / `hobo can-deploy`	Contracts
Policy deny	inspect `policy.Decided`	Policy
Append fails OCC	reload & retry	EventStore
`STALE_FENCE`	re-acquire lease	ActorHost
DB won’t open	schema version / OPFS	Schema
Control plane refuses	`hobo station status`	Stations
Identity dual weird	`hobo identity status`	Identity
Agent can’t tool	scopes + MCP auth	MCP

Gatekeeper denied

Read gatekeeper.Decided reasons (gate field).
Contracts → fix producer/consumer skew (can-deploy).
Policy → change pack or satisfy obligation — do not retry denials.
Cost → quota/budget.
Effects/resilience → visibility only unless configured as hard gate.

Durability failures

Code	Action
`OPTIMISTIC_SEQUENCE_CONFLICT`	Reload aggregate; retry decide/append
`STALE_FENCE` / `MISSING_FENCE`	Lease discipline — not OCC retry
`UNSUPPORTED_SCHEMA_VERSION`	Upgrade runtime to match DB
`PERSISTENCE_UNAVAILABLE`	Browser without OPFS while durable required — change mode or environment
`SQLITE_BUSY`	Single-owner violation or short busy timeout — check writers

Station / broker

Missing Station fails closed. hobo station init then set defaultStation / activeRail. Broker receipts must pin stationId + railHash.

Still stuck

Replay the stream with inspect
Check Crew handoffs for open obligations
File evidence with attest exports — not screenshots of secrets

Doctor in CLI guide · Errors · Anti-patterns