Lease the Worker: A Weekend Heartbeat for Agent Side Projects

Description and use

A lightweight watchdog that launches an agent process, monitors its heartbeat via a lease file, and terminates it if the budget is exceeded.

Problem

Weekend agent processes often hang or run indefinitely, wasting wall‑clock time and resources.

Outcome

A minimal, reproducible lease‑based watchdog that ensures agent jobs terminate within a set budget and do not hang indefinitely.

Workflow

• Create lease.json with initial values
• Start worker.py as a new session
• Supervisor polls lease.json every second
• Worker updates heartbeat_unix every 8 seconds
• Supervisor checks for missing heartbeat or deadline breach
• If breach, supervisor kills worker process group
• Worker exits with status "done" or "expired"

Evidence

Supervisor spawns the worker in a new session, then polls. Missing heartbeats and crossed deadlines both become a kill.

Source