Heartbeat

A background daemon per Claude profile tracking each session's state: running, waiting, blocked, idle, ended or died.

You and orchestrator agents read session state here, not from transcripts. Landing flow: Merge strategy; stateless gate rules: Permission System.

Status commands

smine-heartbeat status queries the daemon; flags narrow or reshape it.

Running the daemon

When heartbeat is down

Sessions keep working, with a hook error notice per event; no heart attack runs.

A restart rebuilds only sessions with a ~/.claude/sessions/ file and a transcript at <claude home>/projects/*/<id>.jsonl. Hook-only sessions stay unknown until their next hook, then show since_restart; old ledger denials do not re-block them.

How states are decided

Inputs: hook events, the toolpolicy denial-ledger tail, process exits, registry seeds.

Heart attack

The heart attack is heartbeat's own kill: heartbeat alone, no orchestrator or subscription, is allowed to end a session's agent automatically. Its one application today is the model policy: it stops any subagent on a forbidden model, spawned without a model, or whose transcript model lacks the named one.

Git state

serve --repos <claude home>/smine/repos.json enables git state. The file is read at start and watched: a repo registered on the Repos page is scanned and watched at once, a removed one leaves the rows, no restart. A file not written yet (no repo registered) is an empty registry; a malformed one degrades the git sensor and keeps the running set.

Config

What a scan reports

Fleets

A fleet: joined sessions, each subscriber, its registered worker branches. /join fleet: T1 runs smine-heartbeat join --fleet T1. Heartbeat never reads or writes titles for membership; the session-title hook adds the member token after a join.

Runs

Members

smine-heartbeat record --kind assigned|decided|merged|spawned|note --subject <text> [--member <letter>]… [--detail <text>]

Binding and branches

Subscribe

An orchestrator subscribes from its Bash tool, handing the daemon its messaging socket and token (CLAUDE_CODE_MESSAGING_SOCKET, CLAUDE_CODE_MESSAGING_TOKEN).

smine-heartbeat subscribe --fleet T1 --target feature/heartbeat

A restarted session has a new socket and must subscribe again; the old subscription ends itself.

Digests

Member changes collect while the subscriber works; on idle, one digest carries them as a new turn.

Latest member state wins; stale changes and fleet lines drop (fleet_integrated after a reopen). Joins, restarts and the first scan after start announce nothing. Member lines lead with the token:

idle(T1-MA CC,FD - Design - T1-MA[WIP])
done(T1-MC general-purpose a1)

Digests are ledger-claimed before sending, never sent twice.

Landing

One landing turn per registered repository and target; a branch's landing target is its branches row's target, the staging target a setting (Git state § Config). Only the done skill creates or moves targets. Who lands what, when: Merge strategy.

Refusals exit 1, reason on stderr: unknown, ended or died session; cwd unknown or in no registered repo; or below (no branch row: done from a worktree no scan listed yet).

no branch row for <cwd>
the session already has a landing entry for <target> in <repo>
token does not match the landing request
not the turn holder
no landing turn is held for <branch>

heartbeat: landing turn granted for <target> in <repo>. Continue the landing steps, then run: smine-heartbeat land --end landed

Entry states

Read it

Status landings: a row per selected repository and target with holder or queue, plus a staging-target row per selected repository while one is configured. --fleet selects the bound repository only, none before binding.

Runtime enforcement

Skills declare enforcement in the enforce block of <leaf>.cue; deploy renders enforce.json beside the deployed SKILL.md only if the install holds both gate and heartbeat components. No file: no enforced run, no gate rule.

Patterns carry install-scoped $SKILL_… variables, filled with this install's program, regex-quoted (^smine-rules base ). An unset variable drops its anchor plus the checks and judgments naming it. The model check refuses repo-scoped variables in anchors (Skillcue § Interfaces and environment).

Stateless gate rules: the tool-policy gate (Permissions). Heartbeat enforces anchors and checks in every session, reporting failed checks and judgment points to the session's one watcher, its bound /runtime agent.

Runs

Anchors

An anchor is a named call, logged on a successful PostToolUse with its response's captures; failed calls never log.

Checks

Watching a session

A watch is one-to-one: /runtime session: <id or title> [mode: act] runs the subscribe below, binding the watcher to exactly one session; only its findings reach the watcher or can be answered.

smine-heartbeat runtime subscribe --target <id or exact title> --mode report|act

Moves

Each finding (check_failed, judgment) unlocks one move, once, while its run is open: send or stop, ledger-claimed (synced) before going live.

Verdict chain per hook answer: heart attack → member guard → runtime (subscriber guard, the hook's check decision incl. a killed session, armed stop, hand-over).

Read it

smine-heartbeat runtime status [--format json] or GET /runtime: the runtime document (schema 1, cmd/heartbeat/schema/runtime-v1.json) with watches (subscriptions, each with target), runs (open, ended, killed, each with anchors, failures, passes) and every session's findings; no token.

Action ledger

~/.claude/heartbeat/actions.jsonl: append-only, 0600, in the 0700 heartbeat dir; replayed at start, so runs, letters, delivered members, journals and landing turns survive restarts.

Peek

The daemon uses the config server's central peek on 127.0.0.1:<peek.port> when its /healthz serves the same Claude home; it never starts one. peek_addr renders from the peek.port setting, default 4242.

Fleet page and orchestrator

Page

The config server's Heartbeat section has two tabs, Fleet and Runtime.

Members

Attended sessions run /join fleet: T1 once, /done when work is committed and finished. Titles: … - T1-MA[WIP], [READY] after a committing turn, then [DONE]; /close leaves the fleet, ending at [CLOSED]. Outside a fleet, /done lands the session's own branch on its landing target; one based on the default branch lands nothing.

Orchestrator

1. Start it

   From a session worktree of the repo:

   /fleet fleet: T1 target: <branch> [playbook: feature|design] [master: <plan file>] [collisions: all]

2. Subscribe

   Subscribes as … - T1-O[WIP], never a member; switches its worktree to the run's merge branch (fleets[].merge_branch).

3. Land members

   Judges collisions, fast-forwards delivered members onto the merge branch (git merge --ff-only), journals every act; never checks out the target. Members behind the merge branch are asked to restack and /done again; delivered worker branches behind it the orchestrator restacks on a work branch. Never a merge commit.

4. Sync the target

   Once integrated, syncs the target via /done in its landing turn: restack if it moved, then an ancestry-checked fast-forward (smine-agentwt forward). A target checked out elsewhere moves in that worktree, refused only while it has uncommitted changes to tracked files (queue: sync blocked until you commit). A target that is no landing target answers no-target; the orchestrator stops.

5. Finish

   Removes worker branches, runs unsubscribe --finish (the run dissolves). /close in its session removes the merge branch. Landing on main stays yours.

Worker cells

Each worker starts as a background command: a claude -p cell in .claude/worktrees/<name> on claude/<name>.

smine-routine worker -base <merge branch> -name <name> -skill <leaf> -args <text>

The launcher commits leftovers, removes the worktree, prints one JSON result line (status done, failed or stopped); its exit wakes the orchestrator. A cell is a root session, so its subagents work in its own worktree; a subagent's subagents were fenced to the orchestrator's.

-keep-stopped keeps a stopped cell's worktree; -resume <session id> continues it there with -args as next prompt, how the feature playbook hands a stopped implementer its refined plan.

Merge strategy

A session's branch lands on the branch it started from, by replay and fast-forward, never by a merge commit. Heartbeat grants the turns (Landing); this section is who lands what, when.

Branches and landing targets

Flows between refs, in order:

Branch states

A branch enters Working when its worktree is created and leaves from On main with /close.

Landing a session

/done in a session in no fleet. You type it; an agent's own call is admitted only after /join or inside /fleet.

1. Clean tree

   Uncommitted work is committed first.

2. Accept

   smine-heartbeat done resolves the landing target and requests its turn: accepted <target> granted or queued <n>. Queued: the session ends its turn; heartbeat's message when the turn frees resumes it at step 3. No target: no-target <base>, title to DONE, nothing lands.

3. Create

   A missing staging target is created from main's tip after the grant; heartbeat grants its turn before it exists.

4. Catch up

   If main holds commits the staging target lacks, the staging target's unreleased commits replay onto main's tip and it moves; the old tip stays as claude-restack/<slug>-<short>-orig.

5. Placed check

   smine-agentwt unplaced --onto <target> <branch> lists the commits the target lacks; none: the turn ends abandoned.

6. Restack

   They replay onto the target's tip on a work branch (conflicts resolved by both sides' intent, audit run), unless the target's tip is already in the branch. The checked-out branch keeps its name; its old series becomes the -orig archive, removed through the safety-gated remove once adoption is green (kept if the removal is skipped). Any other branch stays on its work branch for the caller to adopt, with no archive.

7. Fast-forward

   smine-agentwt forward --onto <target> <tip> moves the target after checking the tip holds the target's tip.

8. End

   smine-heartbeat land --end landed

9. Close

   /done --close then runs /close, removing the session's worktree and branch; the Desktop session stays open.

Landing a fleet

Members land on the fleet's merge branch; only the orchestrator moves it.

Starting behind

Release

What you may do

Skill model merges

A custom git merge driver merges two branches' version bumps of one skill model file.

Landing commands

Landing files