Sidequest: Why the Tick Locks the Door Behind It

Cold open

flock is a lock the operating system holds for you. A program asks the kernel "let me hold this file exclusively", and any other program that asks for the same file while the first one holds it gets told no. The Assistant takes one of these at the start of every tick and lets go at the end.

There is a small joke inside your question. You did not run into flock on your own this time. Claude handed you that exact sentence, "flock, why does the tick care", as the test phrase for the brand new huh command. The sidequest build plan uses the same line as its example of something that goes past you mid-session. So you typed the test, and the test turned into a real episode. That is a good first sign for the system.

Where it showed up

That session was wrapping up the Sidequest pipeline. Part of it was teaching the tick to start usage-gated jobs only when files are waiting in the queue, which is what the previous episode covered. The Assistant's notes describe the tick as the thing that "holds a single-instance lock", and that is the phrase you asked about. The lock is older than Sidequests. It went live on 18 August, and it is the reason this new module can run on the tick without double-publishing your episodes.

The problem it solves

Every 5 minutes launchd wakes the Assistant and it runs one tick: read the registry, probe everything, decide, maybe summon a job. Now picture a session, or you, starting a second tick by hand while the daemon is halfway through its own.

Both ticks read the same state. Both see that the autocast occurrence for today has not been settled yet. Both mark it running. Both spawn the job, and you get 2 copies of the same episode in your feed. That was the real risk once autocast went live in August. Until then the only protection was a no-entry sign in CLAUDE.md telling sessions not to hand-run the tick, and as the build plan put it, that kind of warning is "wallpaper by mid-session". Every new live module that summons a job made the window wider. Sidequest is another one.

So the tick now locks a door before it does anything. The first tick through takes the lock on the tick's lock file. A second tick tries the same door, finds it held, and stops straight away. It prints one plain sentence along the lines of "another tick is running, here is its process number and start time, nothing done", and exits. It does not count as a failed tick. It advances no counters, writes no heartbeat and summons nothing. It just did not happen.

Why flock specifically

The obvious way to build a lock is a marker file: create it when you start, delete it when you finish. The trouble is the crash. If the tick is killed halfway, the marker stays behind, and every later tick thinks someone is still running. Then you need a staleness rule like "a marker older than 10 minutes is probably dead", and now you are guessing.

flock gets rid of the guess. The kernel owns the lock and ties it to the running process, so when that process dies for any reason, even a hard kill, the kernel releases the lock at that moment. The file can sit there forever, but the lock is in the kernel, not in the file. What the file holds, the process number and start time, is only there so the refusal message can tell you who has the door. Nothing decides anything from it.

That is why it fits the crash test so well. The kill-test gate kills the Assistant at 6 different points, 50 times each, and one of the checks is that a restarted tick never finds the lock still held. Every kill in that test lands on a tick that is holding the lock, so the lock gets a rough workout.

The paranoid part: fail closed

There was one design argument here, and Codex and Fable settled it in review. What happens when the lock cannot be taken at all? Say the lock file cannot be opened, or the kernel returns some odd error that does not mean "someone else holds it".

The tempting answer is to run anyway, since the lock is only a safety net. They chose the opposite. Only one specific answer from the kernel means "someone else has it", and anything else refuses the tick with the error in the message. The reasoning: a passing glitch in the second caller is exactly when the daemon might be mid-tick, so running unlocked "just this once" is the double-run the lock exists to stop.

This also follows the "fail dumb" invariant. If the state folder is broken for good, every tick refuses, the heartbeat stamp goes stale, and the watch chain notices from outside, through floor-selfcheck on popcorn2 and the pinkserver watcher. The Assistant does not try to diagnose itself. It goes quiet in a way that simpler systems are built to notice.

Where else this lives in your estate

The same lock turns up in a few other places.

The event log uses one. Every line the Assistant writes to its monthly event file is written under a flock, and the archiver that ships old months to the bucket takes the same lock. That way a writer cannot add a line to a file that is in the middle of being archived and moved.

The usage-mode file in your config folder, the one the SwiftBar menu reads, has a flock around changes, so banked resets and lane pins cannot overwrite each other. The reboot drill takes its own non-blocking lock too: if a second drill run finds it held, it reports "nothing to do" and leaves.

There is a practical side for you. If you ever want a tick right now, do not run one by hand. Use the launchctl kickstart command from the CLAUDE.md, which pokes the daemon itself, and the lock never comes into it.

If you remember one thing: the tick takes a lock the kernel holds, so two ticks can never act on the same thing twice, and a crashed tick cannot leave the door jammed.