Skip to main content

Routines and the registry

A routine is a job the box does on its own, with no one asking. Every routine has one row in one list, called the registry. A job that is not on the list is not allowed onto the box.

Where you see it​

The owner sees routines in the Working for you panel. Each row says what the job does, in plain words, and whether it ran. That panel is the live truth. It joins the registry to what the box reports right now.

What happens, step by step​

A routine is one of two kinds. The kind depends on what starts it.

  • Scheduled. The clock starts it. "Every morning at 8" is scheduled.
  • Triggered. Something in the world starts it. An email arrives, a message comes in.

Here is the trap. "Every 15 minutes, watch for a change" sounds like a trigger. It is not. It is still the clock. Checking fast is still checking on a schedule. Only a job that gets pushed a signal from outside is triggered.

  1. The owner says: "Tell me when a new order shows up in my supplier portal."
  2. The first question is: can this be done without holding a line open? Can the portal send a web message (a webhook) instead? Can a rule be added to a listener that already runs, like the email router?
  3. If not, is a check every 15 minutes good enough? Usually yes. So it becomes a scheduled routine.
  4. The job gets a row in routines.json (the registry). The row says, in plain words, what it does and, where it can, how to prove it ran.
  5. The change is deployed. The deploy script checks the registry. Row found, so the job goes live.
  6. It now shows in the owner's panel, with a green or red mark.

What powers it​

The registry is one file, routines.json. Each row is one routine. These are the main fields.

PartWhat it does
name, whatThe routine's name and what it does, written for the owner.
kindschedule or event. Picked by the owner's story, not the plumbing. A fast poll that answers mail "the moment it arrives" is filed as event.
whenOnly on event rows. A schedule row's timing is read live from its timer, so it is never typed twice.
modeasks (checks with the owner first) or auto (just acts).
ownerstandard (every install gets it) or yours (built for this owner).
doneThe proof it ran. See Proof it ran.
parked, in_progressTurned off on purpose, or built but not yet on.

A few standard routines every install gets:

RoutineWhat it does
Email checkAnswers mail sent to the agent's own address, about every 2 minutes.
Task list syncKeeps phone tasks and vault task files in step, every 15 minutes.
Self-repair checkClears memory and browser buildup, every 30 minutes.
Daily checkupThe 18-point health check at 8 a.m.
Apply confirmed changesPuts owner-approved changes onto the box, checked every minute.
Link checkWeekly. Fixes broken links that need no judgment.
Agent alarm clockWakes each resident agent at the time it picked.

Why it works this way​

A job with no row runs where no one can see it. That happened. One job ran for weeks with nobody able to see it. The test meant to catch exactly that broke too, because it relied on the same list.

So the rule became a gate, not a note. The deploy script, apply.sh, refuses any timer with no row in routines.json. The owner's reason: a written rule only helps someone who already knows it exists.

Try not to build a listener

A triggered routine often means holding a connection open all day. A held connection is a thing that can die at 3 a.m. and look alive while it is deaf. Before building one, check for a listener to add a rule to, a webhook, or a schedule that is good enough.

Connected to​