Guides / When something is wrong
When something is wrong
Run kosa8 doctor first. It checks the things that actually stop kosa8
working, and for each failure it says what it observed, why that matters, and what fixes it.
$ kosa8 doctor ✓ platform darwin/arm64 ✓ hypervisor support kern.hv_support=1 ✓ kosa8d daemon reachable ✗ one daemon only 2 kosa8d processes: 15022, 36328 why it matters: two daemons cannot share the engine disk, and the second one to want it fails with an error that does not mention the first → inspect with `ps -p 15022,36328`, then stop the one you do not want ✓ guest kernel and rootfs present ✓ state directory is private 0700
Letting it repair things
kosa8 doctor --fix repairs the failures that are safe to repair unattended and tells
you exactly what it did.
$ kosa8 doctor --fix repaired: ✓ removed the stale socket file; `kosa8 daemon start` will work now · inspect with `ps -p 15022,36328` … (there is no automatic fix for this) · make install-guest (there is no automatic fix for this) ✓ created ~/.kosa8/log ✓ restricted ~/.kosa8 to you only
--dry-run shows what --fix would do and changes nothing.
What it will not do
This is not an agent that fixes everything, on purpose. A repair loop that acts on a failure it does not recognise turns a small problem into a large one — the obvious remedy for "another daemon is holding the disk" is to kill it, and the daemon it kills might be the one doing your real work.
So every repair carries a risk class, the same ones the approval gate uses, and only the safe ones are ever applied for you:
| Class | Example | Applied by --fix? |
|---|---|---|
| read-only | Reading a permission bit | Yes |
| contained | Removing a socket nothing is listening on; creating a missing log directory; tightening permissions on your own state directory | Yes |
| destructive | Stopping a daemon; removing a machine or a snapshot | Never |
| escalating | Downloading guest images; re-signing a binary | Never |
No flag changes that. It is the same reasoning as the approval gate: a switch that turns off every safeguard is not a safeguard. Destructive and escalating failures are printed as a command for you to run, with enough context to decide whether you want to.
If a check cannot read the state it needs, it says so and nothing is repaired. Acting on a state you could not read is exactly how a repair tool causes the damage it exists to prevent.
Prevention beats repair
The duplicate-daemon failure above is what prompted all of this, and it is deliberately not in the repair list. kosa8d now takes an exclusive lock on its state directory, so a second daemon refuses to start and names the one already running. A problem that cannot happen needs no healer.