Sidequest: Why the Tick Checks for Files Before It Runs a Job

Cold open

A when glob and an unless glob are two questions the Assistant asks the file system before it starts a job: "is there any work waiting?" and "is anything stuck?" Only a yes to the first and a no to the second lets the job run.

How it came up

You were watching the session build the Sidequests pipeline, the machinery that is producing this very episode. Pieces were landing quickly. Codex built the autocast side, Claude reviewed it, the kill-test passed 50 out of 50, and the session merged a change it called "usage-gated tick jobs plus when glob and unless glob preconditions." Then it added a new module file for sidequest, starting in shadow mode, and two odd keys went past in it: one listing the folders for pending and claimed items, and one pointing at a folder called held. That is the moment you typed slash huh.

So yes, this episode is partly about how this episode got made. Very meta. Try not to think about it while driving.

The problem: 288 knocks on an empty door

The Assistant ticks every 5 minutes, which comes to 288 ticks a day. Most modules run on a schedule: the Director Report on Sunday evening, the Fleet Forecast at half past eleven at night. Sidequest is different. It has no schedule, because nobody knows when you will next be confused. It is a tick job, which means it is considered on every single tick.

Without a precondition, every tick would launch autocast, a full Python program. Autocast would start up, look in its spool folder, find nothing, and quit. That happens 288 times a day, for maybe 2 real questions. The project's traps document already names this failure: "288 ticks a day." Each pointless launch also leaves a receipt, a ledger entry and an event line behind it. Your event log would turn into a diary of nothing happening.

The fix is to have the Assistant look before it leaps. When you type slash huh, the huh mod drops one small JSON file into autocast's pending folder. Checking whether that folder has any files in it is almost free for the tick. It is just a look at a directory listing, with no program to start and no model to call. So the tick checks first, and only starts autocast when there is actually something in the queue.

A glob is just a wildcard filename pattern, like "every file ending in dot json in this folder." So when glob means "run only when this pattern matches something."

Why there are two folders in the "when"

The when glob lists two folders, pending and claimed, and it is enough for either one to match. Pending is obvious: new questions are waiting. Claimed is the clever part. When autocast picks up an item, it moves it from pending to claimed. If the worker gets killed halfway through, say by a crash, a timeout or a reboot, the item is stranded in claimed while pending is empty. If the job only watched pending, nothing would ever come back to clean up the stranded item. Watching claimed as well guarantees a recovery run. That is the Assistant's restart-safety rule, applied to a queue.

The unless: one stuck item stops the line

The unless glob points at the held folder, which is quarantine. If an episode rendered but could not be delivered, the item is parked in held. You ruled on 11 October that one stuck delivery pauses the whole feed until someone runs autocast's resend command. The reason is that you do not want ten new questions to pile in after a broken one, each failing in the same way and each opening an alert. So while anything sits in held, the job spawns nothing, even as new slash huh items keep arriving in pending. They wait. The queue itself is the holding pen.

Three details that make it trustworthy

First, the check runs before everything else, including the shadow-mode logic and the usage gate. Without that ordering, shadow mode would write a "would fire" line on every tick, and the usage meter would be consulted for an empty queue.

Second, it only speaks when something changes. Going from idle to busy, or from busy to held, is recorded once. It does not log "still idle" 288 times a day.

Third, and this is the subtle one: an unreadable folder must not look like an empty one. Python's usual way of matching filename patterns quietly ignores permission errors, which the traps document already warns about. If the spool folder became unreadable, a naive check would decide there was simply no work, forever, without a sound. The real code treats an unreadable folder as a failure and opens an alert, so "I could not look" never gets mistaken for "nothing there."

Where you have seen this before

The idea is older than your estate. Apple's own launchd has a setting called queue directories, which keeps a job running for as long as a folder is not empty, and systemd has a condition that skips a unit unless a file pattern matches. The Assistant is not inventing anything here. It is giving its own tick the same reflex the operating systems built in decades ago, because its jobs live in its registry rather than as separate system units.

The other half of this change sits in your usage module. The usage poller now declares that it produces the meter, so a tick job is still never allowed to wait on a meter reading it is supposed to write itself. That is the same principle seen from the other side: think about what a job depends on before you let it run.

If you remember one thing: the tick looks at the files first because checking a folder is free and starting a program is not, so sidequest wakes only when a question is waiting and stays asleep while anything is stuck.