Sidequest: The Daemon, and Why It Keeps Running Yesterday's Code

The thing itself

The daemon is the Assistant itself: a long-running program that launchd starts on your Mac and keeps alive. It wakes every 5 minutes for a tick, and it keeps running the code it loaded when it started, no matter what changes on disk afterwards.

What happened in your session

You asked for expired hot mode to stop showing in the usage readout, and then the same for lane pins and passed targets. After the first commit, Claude said the daemon did not need reinstalling "because it does not run this code". After the second commit, Claude reinstalled it anyway, "as guardsmith asked." That sounds like it contradicts the first remark. It does not, but you were right to be confused.

The mental model

Think of the daemon as a chef who memorised the recipe book the morning the restaurant opened. If you edit the book during service, the chef keeps cooking from memory. Python works the same way: a running program reads its code once at startup and holds it in memory. Editing the files does nothing until the process restarts.

The daemon treats your settings differently. Each tick it rereads the registry, the toml files you edit by hand. That is why your edits take effect within 5 minutes without anyone restarting anything. The shorthand in the project docs is "hot-reloads config, never code."

That split causes a known trap. If code and registry change together, the registry can arrive first and get read by old code that does not understand it. On 1 October that opened three "disabled by a config error" rows in Capture. So the rule is: after merging code, run the install script, which restarts the daemon on the new code. The daemon's startup event records which commit it is running, so "is the fix live?" can be answered from the event log.

So why "does not need it", then "reinstalling anyway"?

Both remarks were true, and they were answering different questions.

The usage resident does not run inside the daemon. Each tick, the daemon starts it as a separate short-lived program, a fresh Python process that loads whatever code is on disk at that moment. The part you changed was the display, which only runs when you or a session type usage. That code was never loaded into the daemon's memory, so the change was live immediately. That was Claude's first point.

The guardsmith nag cannot tell the difference. It is a small check called check-installed, and it is deliberately blunt. It looks up which commit the daemon announced at its last startup and asks git one thing: has anything in the assistant folder or the residents folder changed since that commit? If so, it says "main has code the daemon is not running, reinstall." It does not work out whether that code is actually loaded by the daemon or by a subprocess. Your usage files are in the residents folder, so it fired.

Is that a bug? Not really, it is a deliberate trade. The nag has to finish within guardsmith's 5-second budget, can use only Python's standard library, and fails open: if it cannot read something, it stays quiet. A smarter version would have to trace imports to see what the daemon really loads, and it would be wrong in some new way. A reinstall is cheap and safe: the install script handles restarting over the running daemon. So the blunt rule costs a few seconds of unnecessary restart, and in return a real code change is never left unloaded. Claude saw the full suite pass, followed the nag, and moved on. It was the right call, just not a necessary one this time.

Where else this lives

The same rule holds elsewhere in your estate: a long-running process does not see new code until it restarts. On popcorn2, every service in its rootless podman container keeps running the old build after a deploy until it is restarted, and that is why the deploy flow ends with a restart. The Assistant's twist is that half of it, the registry, does reload live. That convenience is also what made the 1 October mix-up possible.

If you remember one thing: the daemon rereads your settings every tick but keeps running the code it started with, so new code needs a reinstall, and the nag asks for one whenever code changes, even when it was not strictly needed.