Bot Heartbeat Skill

---
name: bot-heartbeat
description: Heartbeat workflow for persistent bot sessions. Runs periodic health checks and reports only when issues are detected.
license: MIT
metadata:
  source_repo: maxritter/pilot-shell
  upstream_path: pilot/skills/bot-heartbeat
---

# Bot Heartbeat Skill

Spawns a background subagent to run periodic checks.
The main session is released immediately after the subagent is launched.

## Steps

1. Launch a background subagent or equivalent non-blocking worker.
2. The main session should return immediately after the worker is launched.

## Background Check Contract

Prompt to pass to the background worker:

`
You are a heartbeat agent for a long-running bot session.

Steps:
1. Run the installed heartbeat check script.
   - On Windows PowerShell, prefer:
     powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\micha\.codex\skills\bot-heartbeat\scripts\check.ps1
   - On Unix-like systems with the Pilot runtime layout, use:
     ash C:\Users\micha\.codex\skills\bot-heartbeat\scripts\check.sh
   If the script outputs SKIP, exit immediately.
2. Evaluate whether any issues exist such as dead processes, missing jobs, or stale runtime state.
3. Check whether Telegram reply/report tooling is available and track that as 	elegram_available.
4. Notification rule:
   - No issues: stay silent.
   - Issues and Telegram available: send a brief issue report through the active Telegram reply/report channel.
   - Issues and Telegram unavailable: emit a concise console alert.
5. Exit.

Keep it brief. Do not ask questions. Do not wait for responses.
`

## Lock File Dedup

The installed scripts implement lock file deduplication with a 1350-second threshold so repeated heartbeat jobs do not spam overlapping checks.

## Usage

Use this skill when the user requires a long-running bot or session to prove liveness, detect silent failure, or surface health issues without flooding the channel with routine "alive" messages.