feat: opt-in smart heartbeat that only fires when session state changes

[c2keesey]

Summary

Adds a heartbeat_smart flag under [conductor] settings. When enabled, the per-conductor heartbeat.sh installed by agent-deck conductor setup snapshots session state on each tick and only sends a check-in to the conductor when the snapshot differs from the previous run.

The default is false, so behavior is unchanged unless the user opts in.

[conductor]
heartbeat_smart = true   # default: false

Closes #545 (this PR replaces that earlier, rougher attempt).

Motivation

On profiles where the conductor is mostly idle, the timer-driven heartbeat wakes the conductor every N minutes just to have it report "all clear". For users running the conductor against expensive models (or who just want quieter tmux output), that's wasted work. With heartbeat_smart = true, the heartbeat tick is a cheap shell snapshot when nothing has moved, and the conductor is only woken when there's actually something to look at.

How it works

The smart variant of heartbeat.sh:

1. Same conductor status enabled-guard as the standard script.
2. Snapshots the current set of title:status pairs from agent-deck list --json, sorted, with the conductor's own session filtered out. Parsing uses portable awk (works on GNU and BSD/macOS), matching the parser style used by the existing heartbeat script.
3. Compares against the previous snapshot in heartbeat.state (an absolute path interpolated next to heartbeat.sh at install time, so the script doesn't depend on $0).
4. If they match, exits 0.
5. If they differ, writes the new snapshot atomically (tmp + mv) before sending, so a crash mid-send can't cause a re-fire loop.
6. Same idle/waiting status gate and same group-scoped check-in message as the standard heartbeat.

Migration

MigrateConductorHeartbeatScripts honours the same setting, so flipping heartbeat_smart and re-running agent-deck conductor setup (or letting the migration sweep run on next start) refreshes existing managed scripts in place. The managed-script detector recognises both the standard # Heartbeat for conductor: header and the new # Smart heartbeat for conductor: header, so neither variant is mistaken for a user-authored custom script.

Setup output

  [ok] Heartbeat timer installed (every 15 min, smart)

When heartbeat_smart = false (the default), the existing (every 15 min) line is unchanged.

Tests

8 new tests in internal/session/conductor_test.go:

• TestConductorSmartHeartbeatScript_TemplateStructure — smart template contains the diffing comparison, atomic state write, status guard, and group-scoped message.
• TestInstallHeartbeatScript_StandardWritesScriptWithoutSmartMarkers — InstallHeartbeatScript(name, "default", false) writes the standard script via t.Setenv("HOME", tmpHome), strips -p for the default profile, and contains no smart markers.
• TestInstallHeartbeatScript_SmartInterpolatesStateFileAndPreservesProfile — smart install interpolates the absolute heartbeat.state path, leaves no {STATE_FILE} placeholder, keeps -p for non-default profiles, and produces an executable file.
• TestInstallHeartbeatScript_SmartDefaultProfileStripsFlag — smart install with the default profile still strips -p.
• TestInstallHeartbeatScript_SmartScriptIsExecutableShell — runs bash -n against the rendered smart script so awk/quoting regressions surface at go test time.
• TestConductorSettings_HeartbeatSmartDefault — HeartbeatSmart defaults to false.
• TestMigrateConductorHeartbeatScripts_DetectsSmartHeader — both header variants are recognised by the migration sweep's managed-script check.

All existing conductor tests still pass.

Test plan

• go test ./internal/session/ -run "Heartbeat|Smart|Conductor" -count=1 — passes
• go build ./... — passes
• gofmt clean
• bash -n syntax check on rendered smart script (covered by test above)
• Manual: install with heartbeat_smart = true, observe heartbeat.state populating and conductor only being poked on real state changes