ls-codex-heartbeat-checks

Opt-in agent heartbeat harness for target repositories: initialize config, run transaction-safe checks, preserve artifacts, and wire cron only after explicit activation.

SKILL.md

GitHub

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.
  • Use configure-lscli to preview an existing provider/runtime connection, with explicit --mode review|coding, --provider-profile and --grant. Review requires explicit --context files; coding requires --resource-parent. --apply preserves unrelated settings and backs up exact prior bytes privately. It selects the agent for manual runs without enabling heartbeat or cron. An enabled recurring agent must first switch to collection only or be disabled. Static configuration checks do not resolve credentials or prove run readiness.
  • readiness inspects the selected LSCli agent without hooks, provider requests, credential resolution or state creation. --probe explicitly attempts one bounded execution: review discloses only selected granted context; coding exercises native preflight with no model tools. Keep static evidence, probe evidence and live schedule/collection readiness distinct. Never retry a failed probe automatically or silently fall back to another mode.
  • 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.
  • Scheduled execution defaults to collection only. enable --with-agent validates the configured enabled profile before selecting reviews; --collection-only restores collection-only scheduling. Repeated enable and disable preserve the selected mode. Generated run --scheduled commands read that selection anew.
  • Live crontab updates own one target-specific block, preserve unrelated entries, retain a compressed backup, and reconcile write acknowledgements by readback. Ambiguous markers, changed owned blocks and unresolved writes stop updates. A legacy unmarked entry is preserved; inspect it before an explicit migration to avoid enrolling the same target twice.
  • Put routine inventory collection in hooks.before: these commands run before agent resolution. Agent setup or execution failure still records a failed run and preserves completed collection artifacts; it does not run hooks.after.
  • 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 configure-lscli --help
localsetup harness codex-heartbeat readiness
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.

For advice without model tools, explicitly select the unselected lscli-review template using the read-only review contract. It uses the verified SDK runtime, selected provider and bounded read/disclosure grant without requiring a native tool sandbox. Collection finishes before context is read. Saved advice is private data and must never be executed automatically.

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.