Heartbeat And Pacemaker In Keel
keel heartbeat is now the canonical pacemaker contract. If a human, an AI harness, or a visual scene needs to know whether the board is still energized, it should read the same derived signal.
Canonical
The pacemaker is now a CLI surface
Keel no longer needs a synthetic heartbeat file to describe recent activity. `keel heartbeat` is the public inspection surface for the board’s wake state.
Derived
The signal comes from Git and the worktree
The heartbeat is projected from dirty worktree paths, the Git index, the latest commit, or a filesystem fallback when Git is unavailable.
Governing Boundary
The commit boundary closes loop debt
Dirty repository energy is warning-level loop debt. Hooks and the commit action are the governor controls that close it cleanly.
What keel heartbeat tells you
keel heartbeat
keel heartbeat --json
The heartbeat output answers five practical questions:
| Field | Meaning |
|---|---|
state | Whether the pacemaker is currently energized or idle |
source | Which source won: dirty worktree, Git index, head commit, or filesystem fallback |
last_activity_at | The timestamp of the newest activity Keel could prove |
dirty / dirty_files | Whether there is uncommitted repository energy still on the floor |
decay_minutes | The charge window before the system falls back to idle |
The important shift is conceptual: the heartbeat is no longer a file to poke. It is a read model to inspect.
The pacemaker protocol after formalization
The protocol is now simpler:
- Work changes the repository.
keel heartbeatprojects the newest trustworthy activity.- Scene surfaces consume that projection.
- The commit boundary closes dirty energy through hooks and the commit itself.
This is why the pacemaker belongs in the CLI. It is board state, not a ritual.
Mission Stack does not redefine heartbeat
Mission Stack adds coordination across repos, but it does not change what
keel heartbeat means inside one repo.
keel heartbeatandkeel heartbeat --jsonstay repo-local- stack id, stack mode, checkpoint state, and waiting receipts belong to
keel turn,keel next,keel mission next --status, andkeel doctor - stack-aware surfaces should add their own text and JSON fields without overloading heartbeat output
How scenes should read the pacemaker
The heartbeat command is the source of truth. Scene surfaces should only visualize that truth.
| Surface | Correct pacemaker behavior |
|---|---|
keel flow --scene | Show the unplugged circuit when the heartbeat is idle, and only allow the mission-intake override while the heartbeat is energized |
keel workshop --scene | Turn the workbench lamp on only when the heartbeat is energized |
keel health --scene | Do not invent pacemaker state; show structural subsystem health only |
keel doctor --scene | Treat pacemaker drift as a diagnostic finding, not a separate power model |
If a scene disagrees with keel heartbeat, the scene is wrong.
That heartbeat gate matters for keel flow. Keel may temporarily keep the circuit open while missions, voyages, or bearings are still being validly created, but only if the pacemaker can still prove recent repository motion. Once the board goes idle, that intake exception disappears and the same transitional doctor debt can short-circuit the flow again.
For representative scene outputs and the exact state legends those scenes should obey, read Scene Surfaces.
Dirty energy is not failure
Keel treats dirty heartbeat energy as warning-level loop debt, not a structural failure. That distinction matters:
- missing recent activity can make the board idle
- dirty worktree activity should warn
- doctor and health should still describe structural truth separately from wake state
This keeps the pacemaker honest without overstating it.
Downstream copies should preserve the same contract
If Keel is embedded inside another repository, keep this language recognizable in downstream AGENTS.md and INSTRUCTIONS.md. Downstream repos can change wrappers and proof rules, but they should not replace the derived heartbeat model with custom wake files or repo-local rituals.
For the visual contract that sits on top of the pacemaker, continue with Scene Surfaces.