CruxExperts/LocalSetup / ls/skills/ls-codex-heartbeat-checks
ls-codex-heartbeat-checks
VerifiedOpt-in agent heartbeat harness for target repositories: initialize config, run transaction-safe checks, preserve artifacts, and wire cron only after explicit activation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.6 KB |
| references/artifacts.md | markdown | 1.3 KB |
| references/command-logging.md | markdown | 1.9 KB |
| references/config.md | markdown | 23.2 KB |
| references/process-control.md | markdown | 7.5 KB |
| references/recovery.md | markdown | 4.2 KB |
| references/transactions.md | markdown | 1.4 KB |
| scripts/codex_heartbeat.pyexecutable | script | 25.3 KB |
| scripts/codex_heartbeat_support.py | script | 17.7 KB |
| scripts/heartbeat_lscli.py | script | 4.6 KB |
| scripts/heartbeat_process.py | script | 5.9 KB |
| scripts/heartbeat_protocol.py | script | 4.1 KB |
| scripts/heartbeat_review.py | script | 5.8 KB |
| templates/HEARTBEAT.md | markdown | 728 B |
| templates/codex_heartbeat.yaml | config | 1.8 KB |
scripts/heartbeat_protocol.py
View on GitHub"""Strict, bounded LSCli event receipt; never a source of task authority."""
import json
import re
FRAME_LIMIT = 4 * 1024 * 1024
IDENTIFIER = re.compile(r"[a-zA-Z0-9_.:-]{1,128}\Z")
DIGEST = re.compile(r"[a-f0-9]{64}\Z")
def _object(pairs):
value = {}
for key, item in pairs:
if key in value:
raise ValueError("duplicate protocol key")
value[key] = item
return value
def _constant(value):
raise ValueError("nonfinite protocol number")
class Receipt:
def __init__(self):
self.buffer = bytearray()
self.sequence = 0
self.identity = None
self.status = None
self.checkpoint = None
def feed(self, raw: bytes) -> bool:
"""Return whether a complete valid start/progress frame was observed."""
active = False
for part in raw.splitlines(keepends=True):
if self.status is not None:
raise ValueError("bytes after terminal result")
self.buffer.extend(part)
if len(self.buffer) > FRAME_LIMIT:
raise ValueError("protocol frame limit")
if not self.buffer.endswith(b"\n"):
continue
try:
value = json.loads(self.buffer.decode("utf-8"), object_pairs_hook=_object,
parse_constant=_constant)
except (ValueError, RecursionError) as exc:
raise ValueError("invalid protocol JSON") from exc
self.buffer.clear()
active = self._frame(value) or active
return active
def _frame(self, value) -> bool:
if (not isinstance(value, dict) or set(value) != {"schema_version", "sequence", "type", "data"}
or type(value["schema_version"]) is not int or value["schema_version"] != 1
or type(value["sequence"]) is not int or value["sequence"] != self.sequence + 1
or not isinstance(value["data"], dict)):
raise ValueError("invalid protocol envelope")
self.sequence += 1
kind, data = value["type"], value["data"]
if kind == "start":
if (self.identity is not None or set(data) != {"task", "session", "profile"}
or any(not isinstance(data[k], str) or not IDENTIFIER.fullmatch(data[k])
for k in ("task", "session"))
or not isinstance(data["profile"], str) or not 1 <= len(data["profile"]) <= 256):
raise ValueError("invalid protocol start")
self.identity = {k: data[k] for k in ("task", "session", "profile")}
return True
if kind == "progress" and self.identity is not None:
return True
if kind != "result":
raise ValueError("unexpected protocol event")
status = data.get("status")
if (not isinstance(status, str) or not IDENTIFIER.fullmatch(status)
or not set(data) <= {"status", "task", "session", "output", "checkpoint"}):
raise ValueError("invalid protocol result")
if self.identity is not None:
if any(data.get(k) != self.identity[k] for k in ("task", "session")):
raise ValueError("protocol identity mismatch")
elif set(data) != {"status"} or status == "completed":
raise ValueError("completion requires start")
if status == "completed":
if (set(data) != {"status", "task", "session", "output", "checkpoint"}
or not isinstance(data["output"], str)
or not isinstance(data["checkpoint"], str)
or not DIGEST.fullmatch(data["checkpoint"])):
raise ValueError("invalid completed result")
self.checkpoint = data["checkpoint"]
self.status = status
return False
def finish(self, returncode) -> dict:
if self.buffer or self.status is None:
raise ValueError("missing or truncated terminal result")
return {"completed": returncode == 0 and self.status == "completed",
"status": self.status, "sequence": self.sequence,
"identity": self.identity, "checkpoint": self.checkpoint}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |