pm-heartbeat

name

pm-heartbeat

description

Append a TaskHeartbeat for a task currently in working phase. Workers call this periodically to signal they're still alive on a claim; sweep uses heartbeat freshness to detect dead claimants. Refuses if the task isn't working (exit 6) or if the current working status is owned by a different agent (exit 12 — lease lost). Use from a worker loop while holding a claim, on an interval shorter than the configured sweep TTL.

pm:heartbeat — keep a working claim alive

Procedure

../scripts/pm heartbeat --task <task-sha> [--agent ID]

• Reads the latest TaskStatus for <task-sha>.
• Refuses with exit 6 if the latest status is not working — heartbeat is meaningless on a non-working task.
• Refuses with exit 12 if the latest working status's attributes.agent does not equal --agent — the lease has been taken over by a different worker (e.g. via sweep + reclaim, then a fresh pm executing). This prevents a zombie worker from writing heartbeats that mis-attribute liveness to a new owner.
• On success, appends a TaskHeartbeat with:
  • attributes.agent = <agent-id>
  • links.task = <task-sha>
  • links.claimStatus = <current working status record>
  • links.prevHeartbeat = <prev heartbeat tip> (omitted if first)

Worker loop usage

A worker holding a claim should heartbeat at an interval comfortably shorter than the sweeper's --ttl (rule of thumb: 3× margin — e.g. heartbeat every 60s with pm sweep --ttl 300).

while true; do
  pm heartbeat --task "$TASK" --agent "$PM_AGENT_ID"
  case $? in
    0) sleep 60 ;;
    6|12) echo "lost lease ($?)"; exit 1 ;;
  esac
done

--agent defaults to $PM_AGENT_ID (or hostname-pid if unset). Pass the same agent id used for the original pm executing call — otherwise exit 12 will fire even though your process is the one that holds the claim.

Race-safety

Concurrent heartbeats from the same agent serialize via chain_predecessor on prevHeartbeat: only one append per round becomes the new chain tip; the loser raises HeadMoved (which the caller can ignore — the chain extended, that's the goal).

Concurrent sweep preempt-heartbeats compete on the same chain. If the sweep's preempt commits first, this heartbeat will see HeadMoved and the next call will surface exit 6 (the sweep follow-on appended a reclaim TaskStatus, so latest status is no longer working).

The lease-loss check (exit 12) is the formal counterpart of the heartbeat[a, t] precondition t.owner = a in system-models/planning_lease.als.

Exit codes

Code	Meaning
0	Heartbeat appended
6	Task not in working phase — heartbeat is meaningless (e.g. reclaimed, finished, cancelled)
12	Current working status is owned by a different agent — lease lost (zombie heartbeat refused)

Notes

• Heartbeats are append-only and chained by prevHeartbeat. The chain is purely an audit trail + a sync point for the sweep preempt; no consumer reads heartbeat content.
• claimStatus lets a sweeper distinguish heartbeats from a dead claim cycle from those of a fresh one in case of post-mortem inspection.