Module pulse 

Run-bounding and liveness, shared by every tool: the --timeout watchdog that keeps any run bounded, and the --heartbeat pulse that gives an agent a sign of life during a long one.

Two enforcement styles, chosen per tool:

• Watchdog — a hard self-bound for the tools that do their own work (ct-search, ct-view, ct-tree, ct-edit, ct-patch): when the limit passes, the process prints a one-line message and exits 2. The mutating tools disarm it before their write phase, so a timeout can never interrupt a file write halfway.
• The child-running tools (ct-test, ct-each) instead bound the child through supervise, folding a timeout into the verdict rather than aborting — see that module.

The Heartbeat is a small thread that prints a templated line every interval — minimal by default ([{ELAPSED}s]), token-customisable with --heartbeat-emit, and routable to stdout or stderr with --heartbeat-to. Dynamic tokens (e.g. ct-each’s current {ITEM}) flow through a shared PulseState.

Structs

Heartbeat

A running heartbeat: a thread printing one templated line per interval. Dropping the guard stops the pulse promptly (before drop returns), so no pulse can land after a tool’s final output.

HeartbeatOpts

The shared --heartbeat option group, #[command(flatten)]-ed into every leaf tool’s CLI so the flags are named and documented identically.

PulseState

Live token values a heartbeat renders each pulse, updatable while running (e.g. ct-each sets {ITEM}/{INDEX}/{DONE}/{TOTAL} as it advances).

Watchdog

A hard --timeout bound for a self-contained (non-child-running) tool.

Enums

PulseTo

Stream selector for --heartbeat-to.

Constants

DEFAULT_HEARTBEAT_TEMPLATE

The default --heartbeat-emit template: deliberately minimal.

Functions

limit_label

Render a duration limit for messages: 2s, 1.5s — no trailing zeros.

secs

Convert a positive seconds value (fractional allowed) into a Duration.

watchdog

Arm a Watchdog from a raw --timeout value, if one was given. The returned guard must be held for the span the bound should cover.