Agent Heartbeat

Use this skill when a repository needs an explicit, auditable heartbeat harness for periodic checks run by a configured agent CLI. The runtime is client-neutral: each profile supplies its own executable argv, prompt transport, and launcher mode.

Guardrails

• Installing this skill only makes the harness available. It does not create config, cron entries, or autonomous runs.
• Activate per target repo with localsetup harness codex-heartbeat init and enable.
• Ordinary transaction artifacts stay under the configured ignored target heartbeat state directory (default .localsetup/state/codex-heartbeat/). Reserved actions retain separate private attempt/accounting evidence as described in artifacts.
• enable --install-crontab refuses to install a live crontab unless --yes is also passed.
• Ordinary run --no-agent skips agent profile loading and launcher resolution entirely, then exercises configured hooks, lock acquisition, recovery, command logging, staged validation, and atomic promotion. Broken or missing agent configuration does not prevent this transaction check; normal agent runs still validate it. With reserved-action controller options, --no-agent instead returns an early skip before configuration, locks, hooks or transaction checks. See reserved runs.
• An ordinary run acquires heartbeat.lock before inspecting or changing active and staged state. It reclaims only a same-host lock whose owner PID is absent and whose age meets heartbeat.stale_after_seconds, then unlinks that held stale pathname and retries exclusive acquisition. Ambiguous locks remain locked for manual review.
• Direct hooks reject git commit, git push, and blocked destructive executables unless their specific policy switches are enabled; Git global options are parsed before the subcommand check.
• Every executed or policy-blocked ordinary-run command receives a sidecar. Promotion validates hashes for the result, command log, and every logged sidecar. Reserved execution uses the same overlap lock but its own protected result evidence.
• Agent profiles record execution; they are not a sandbox replacement.

Rule ownership

This skill owns heartbeat harness behavior. HARNESS_AUTOMATION.md is the public reference for the same guardrails; changes to activation, artifacts, transaction handling, or cron wiring belong here first.

• Heartbeat is opt-in per target repo.
• New cron cadence must be faithfully representable: integer minute divisors of 60, or whole-hour divisors of 24. Enabling rejects other intervals before changing configuration. Disabling preserves an existing trigger schedule. See the timezone and wall-clock limits in configuration.
• Cron activation is delegated to explicit harness commands and should be coordinated with ls-cron-job-scheduling when broader scheduling is involved.
• Runtime evidence stays in ignored target state, not public framework docs.

Activation and evidence workflow

Use ls-localsetup-framework-changes for repository checks and ls-cron-job-scheduling for scheduling coordination. Preserve the explicit activation gates throughout this lifecycle:

1. Inspect the target paths, configuration, cron manifest, and launcher with plan.
2. Use init to create HEARTBEAT.md and configuration with heartbeat disabled.
3. Use enable to update the heartbeat configuration and cron manifest while preserving unrelated tasks; retain the live-crontab confirmation gate above.
4. Validate a run with --no-agent when appropriate. Success requires validated staged artifacts and atomic promotion, as defined in references/transactions.md.
5. Inspect configuration, cron, lock, latest pointer, and run evidence with status.
6. Use disable to stop future heartbeat runs without deleting historical artifacts.

Record activation, validation, and artifact locations in the run ledger.

Commands

localsetup harness codex-heartbeat plan
localsetup harness codex-heartbeat init
localsetup harness codex-heartbeat enable
localsetup harness codex-heartbeat status
localsetup harness codex-heartbeat budget
localsetup harness codex-heartbeat run --no-agent
localsetup harness codex-heartbeat disable

budget is read-only. It reports policy, summary, and task reservations from heartbeat.task_queue_path when configured; it does not spawn agents or enforce scheduling.

Standalone runtime script:

python3 ls/skills/ls-codex-heartbeat-checks/scripts/codex_heartbeat.py --target-root . --no-agent

References

• references/config.md
• references/artifacts.md
• references/recovery.md
• references/command-logging.md
• references/process-control.md
• references/transactions.md

LSCli coding runs

The unselected lscli-heartbeat template profile uses an owned protected registration, explicit provider configuration and task grant, stdin prompt, and validated JSONL completion. Configure its absolute paths and bounded limits using the typed profile contract before selecting it. Planning and --no-agent do not call a provider. Activation, credentials, delegated sandbox capability, and recurring authority remain explicit. Generic client profiles retain their existing launcher modes.

Controller accounting

Use controller accounting commands for reviewed private policy initialization, resource inspection, and result-bound progress dispositions. These commands neither run an agent nor close an external issue. Keep accounting and controller inputs outside the writable workspace. Use explicit reserved actions for task-wide enforcement and compound compaction. Ordinary fresh profiles do not acquire that authority from an accounting file's existence.