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 |
references/recovery.md
View on GitHub---
status: ACTIVE
version: 3.4
---
# Heartbeat Recovery
A fresh ordinary run acquires `heartbeat.lock` before it scans `*.staged` directories or reads `active.json`. Any staged run left after a prior owner is finalized as `failed_recovered`, preserved under a `*.recovered-*` directory, and recorded in the next run manifest.
An existing lock stays authoritative unless all of these hold: its JSON has a creation time, same-host name, and positive PID; the recorded age meets `heartbeat.stale_after_seconds`; and the same-host PID no longer exists. Only then does the harness acquire the old inode lock, unlink that held stale pathname, close the old descriptor, and retry exclusive creation. It never renames a locked inode. Cross-host, malformed, unreadable, permission-denied, future-dated, young, or live-PID locks return `status: locked` without changing state.
## Ambiguous lock procedure
1. Run `localsetup harness codex-heartbeat status` and preserve the reported lock evidence.
2. Confirm with the lock owner or host operator that no heartbeat process owns the recorded PID. Age alone is not sufficient.
3. Do not delete or rename the lock manually. The runtime reclaims only a proven stale lock while it holds that inode; any ambiguous lock remains a stop condition.
4. If ownership cannot be established, leave the lock in place and investigate.
Corrupt or unsafe pointers also stop the ordinary run instead of being silently trusted.
Reserved execution shares the overlap-lock checks but does not scan or recover
ordinary staged transactions. Its result/accounting recovery follows the separate
procedure below. Reserved `--no-agent` skips before either recovery path; it is
not evidence that an ordinary transaction check ran.
## Reserved result acknowledgement recovery
A reserved action can finish and preserve its private result while accounting
still reports reconciliation_required. Inspect accounting and the retained
state-root/heartbeat/action-binding/result.json before taking further action.
If that exact result exists, review its SHA-256 and use the original private
action input to join it to the pending reservation:
~~~bash
localsetup --target-directory /work/project harness codex-heartbeat accounting reconcile --accounting-root /private/task-control --input /private/action.json --expected-binding ORIGINAL_ACTION_BINDING --expected-head CURRENT_ACCOUNTING_HEAD --result-sha256 REVIEWED_RESULT_SHA256
~~~
The command revalidates the action and its original protected registration,
checks its frozen profile/grant bytes and private result file, and requires the
same pending operation, authorization and current accounting head. Completed
results additionally require successful process/protocol evidence and the exact
settled profile-bound session checkpoint; compound completion also requires the
matching private compaction receipt and source/destination checkpoints at the
same settled historical journal prefix. Historical checkpoints confer no new
resume authority; the final coding checkpoint must remain current. It appends
only the missing result record,
retains every charged allocation, and returns awaiting_controller_review. Record
a separate controller progress disposition afterward. Execution completion does
not accept an issue or authorize another attempt.
No agent phase or provider request is dispatched. If the result was already
recorded, inspect the new head and review that recorded result instead. Missing,
changed, unsafe or unverifiable evidence leaves the reservation unresolved; do
not replay work, reset accounting or manufacture a replacement result. A failed
retained outcome is recorded as failure, without claiming a settled session;
any later resume still requires the session owner's uncertainty checks.
The original action inputs and runtime registration must still produce the
original binding. After an upgrade or input change, recover the exact compatible
prior selection or preserved input through its owning recovery procedure before
retrying reconciliation. This command does not migrate bindings or choose a
replacement runtime. It follows the accounting command's private-file, generic
error and exit 0/2/130 contract. Existing heartbeat overlap locks and ordinary
transaction recovery remain separate from this accounting operation.
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: 472k | 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 |