aesop / daemons
CLAUDE.md2 starsChanged 31 days agoMITView on GitHub
Purpose: Long-running backup, push, secret-scan daemon (run-watchdog.sh) ensuring fleet-wide repo safety, plus self-healing supervisor (selfheal.sh) detecting stale sibling heartbeats and triggering safe daemon restarts.
In this repository21 other files it gives its agents.
- auth/CLAUDE.mdCLAUDE.md
- bin/CLAUDE.mdCLAUDE.md
- chat/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- dash/CLAUDE.mdCLAUDE.md
- driver/CLAUDE.mdCLAUDE.md
- hooks/CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- monitor/CLAUDE.mdCLAUDE.md
- scan/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- state_store/CLAUDE.mdCLAUDE.md
- stdio/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- tools/CLAUDE.mdCLAUDE.md
- ui/CLAUDE.mdCLAUDE.md
- buildsystemSkill
- dashboardSkill
- fleetSkill
- healthcheckSkill
- powerSkill
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 53
Single-instance guard: run-watchdog.sh and selfheal.sh each use atomic mkdir ($LOCK_DIR) to prevent concurrent daemons (both daemon and …
- Distinctive: line 54
CRLF-safe, no line continuations: Use POSIX-safe heredocs (no backslash wrapping).
- Very specific: line 59
Alert Bridge integration: After backup-fleet.sh cycles, run-watchdog calls python tools/alert_bridge.py --scan || true to post …
- Very specific: line 61
Selfheal safety: Never kills/restarts a daemon with a fresh heartbeat (idempotent).
- Very specific: line 63
The scheduler is the loop: run-merge-queue.sh has no loop, no sleep and no watcher.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
daemons/ — Watchdog and self-healing daemons
Purpose: Long-running backup, push, secret-scan daemon (run-watchdog.sh) ensuring fleet-wide repo safety, plus self-healing supervisor (selfheal.sh) detecting stale sibling heartbeats and triggering safe daemon restarts.
Universal rules (every domain)
- Feature branch only, never main; every push gated by
python tools/secret_scan.py --stagedexit 0. - Tests never pollute cwd or global git config; temp dirs only; dummy secrets are runtime-concatenated, never literal.
- In worktrees use ABSOLUTE paths under the worktree for every write.
- Domain docs stay minimal-but-complete; update this file in the same PR as code it describes.
Files
- conductor-root.sh: Sourceable, side-effect-free helper defining
resolve_conductor_root <aesop_root>; the same CONDUCTOR_ROOT rule backup-fleet.sh and selfheal.sh inline (explicit env wins; sibling only for the canonicalaesopbasename; then$HOME/conductor3; a candidate counts only if it holdsstate/.watchdog-heartbeat; else empty). The daemons' own inline derivation is unchanged. Consumed bydash/watchdog-gui.shso the TUI reads the heartbeat the daemon writes without re-deriving it. Its one sibling-derivation line carries thedefaultmarker the portability gate exempts. - run-watchdog.sh: Daemon supervisor (1.8K); spawns backup-fleet.sh every 150s with atomic lockfile guard, maintains heartbeat, logs to FLEET-BACKUP.log, calls
tools/git_integrity_check.py --repos-jsonon .watchdog-repos.json after each cycle (appends FLEET-BACKUP.log; on DAMAGED repos writes SECURITY-ALERTS.log alert), posts security alerts via alert_bridge.py (opt-in);run_pr_sweep_throttled()runstools/pr_sweep.py(session-independent PR actor: arms auto-merge, nudges BEHIND, signals stuck-red/DIRTY) at most once per 15 minutes via the.pr-sweep-laststamp, from both the--oncepath and the daemon loop. Traps INT/TERM cleanly.run_receipt_flush()runstools/receipt_flush.py --repo $AESOP_ROOTevery cycle (both paths; the backstop for the detached pre-push poller; fail-open).run_task_ingest()runstools/ingest_task_events.py --state-dir "$AESOP_ROOT/state"each cycle (both paths; fail closed: a non-zero exit is logged as ERROR to FLEET-BACKUP.log, and--onceexits 1; no python interpreter is an ERROR plus return 1, never a silent return 0; a checkout without the tool is logged as skipped). The daemon's state dir is the one at$AESOP_ROOT, so a box whose scheduled task points ataesop-daemon-runtimewrites its cursor and heartbeat under that tree, not the primaryaesop/state. Tests:tests/test-run-watchdog-ingest.sh. Halt detection (wave-27 safety fix): check_halt() callspython tools/halt.py --statusas the single source of truth, respecting AESOP_STATE_ROOT env var > aesop.config.json state_root > default; bash never re-derives the sentinel path, eliminating drift from configuration overrides. On the--oncepath, when check_halt fails closed, the smoke prints "WATCHDOG SMOKE: FAILED (halt check error, exit N)" and exits 1, while a genuine.HALTprints "WATCHDOG SMOKE: PASSED (halted: HALT sentinel honored, no cycle run)" and exits 0. BASH_SOURCE exec-guard: all path/env variables declared INSIDE the guard (sourcing exposes only functions like acquire_lock/release_lock/check_halt, not env side effects). - backup-fleet.sh: Core backup worker (5.3K); discovers repos (~/., ~/, ~/dev/), stashes uncommitted work to backup/ branches, pushes unpushed commits, scans tracked/untracked files for secrets. Blocks push if secret-scan fails. Set -u pipefail at top; heartbeat is written at the START of the cycle (before autodiscovery; 2026-10-29 fix: prevents 22-minute monitoring gap when autodiscovery hangs) and again at the END (on success). A heartbeat must attest to work DONE, but a stale START heartbeat is also necessary to prove the daemon is alive during long-running autodiscovery. Heartbeat contract (rules): (a) every COMPLETED cycle writes it at END (exit 0 clean, exit 3 BLOCKED/WARN); (b) hard failures (exit 1: cycle cannot stage scratch file or persist
.watchdog-repos.json) never write at END but do write at START so the daemon's liveness is visible; (c) stale START + missing END heartbeat = cycle hung (monitored by run-watchdog and selfheal; e.g. autodiscovery timeout 22 min > 600s selfheal threshold triggers restart). On exit 3 the blocked repo names are written to$CONDUCTOR_ROOT/state/.watchdog-blocked; a clean cycle removes it. Scanner HIGH/FOUND/FATAL lines are appended to FLEET-BACKUP.log viarun_secret_gate(matched values stay masked by secret_scan.py'smask_secret). Timeout bounds (2026-10-29 fix):REPO_OPERATION_TIMEOUT(default 60s, env-overridable) wraps per-repo git operations (process_repo calls); repos exceeding it are logged as TIMEOUT and skipped.AUTODISCOVERY_TIMEOUT(default 240s) bounds the entire autodiscovery loop viatimeout "$AUTODISCOVERY_TIMEOUT" discover_reposso cycles fit in the 5-minute scheduler interval; on timeout, a WARN line is logged and processing continues with discovered repos. Heartbeat location (2026-10-06 fix): writes to$CONDUCTOR_ROOT/state/.watchdog-heartbeat(not AESOP_ROOT) so the shared monitoring infrastructure (GUI, idle_tick, monitor, power_selftest) can read it regardless of worktree or AESOP_ROOT path. Heartbeat-pollution guard (2026-10-07 fix, recurrence of the 2026-10-06 incident): CONDUCTOR_ROOT is NO LONGER derived unconditionally as a sibling of AESOP_ROOT. Every worktree (aesop-wt-*) and every test fixture is a direct child of the same$HOMEas the real~/conductor3, so the old unconditional${CONDUCTOR_ROOT:-$(dirname "$AESOP_ROOT")/conductor3}silently resolved to the REAL fleet-state root for ANY AESOP_ROOT shape, letting test/lane runs overwrite the live heartbeat. Now: explicitCONDUCTOR_ROOTalways wins; otherwise the sibling is auto-derived ONLY whenbasename "$AESOP_ROOT"is exactlyaesop(the canonical tree); any other shape skips the heartbeat write entirely (same fail-closed contract as other failure paths). See tests/test-backup-fleet-heartbeat-guard.sh. Secret-gate scope: the scan always covers the full pushed range, including the root commit and add-then-remove; listing, write-tree and push failures report BLOCKED or FAILED, never CLEAN; logs go to stderr. - selfheal.sh: Self-healing supervisor; monitors heartbeats of run-watchdog.sh and the sibling monitor daemon (CONDUCTOR_ROOT-resolved). On each cycle (~60s), detects stale heartbeats (>600s age) and restarts dead daemons. Single-instance guarded via atomic mkdir. Never kills anything with fresh heartbeat (idempotent). Logs to state/SELFHEAL.log. BASH_SOURCE exec-guard: all path/env variables inside guard. CRLF-safe. Supports
--oncemode for testing. - run-merge-queue.sh: Merge-queue advancer runner (~140 lines). NOT a daemon and NOT a loop: one invocation runs exactly ONE bounded pass of
tools/merge_queue.py --advance, and the 5-minuteAesopMergeQueueScheduled Task IS the loop. Deliberate -- merging must not depend on a live interactive session (measured green->merge dead time ~31.75 HOURS sessionless vs 9-109 seconds seated). Zerosleepcalls, zero polling. Halt detection (wave-27 safety fix): check_halt() callspython tools/halt.py --statusas the single source of truth, respecting AESOP_STATE_ROOT env var > aesop.config.json state_root > default; bash never re-derives the sentinel path, eliminating drift from configuration overrides. Fail-closed (mirrors run-watchdog.sh, PR #957): box-wide$CONDUCTOR_ROOT/state/.HALTis honored by existence with no interpreter, and whenCONDUCTOR_ROOTis unset and AESOP_ROOT is not the canonicalaesoptree it is UNRESOLVED and fails closed (2026-10-20: the old$USERPROFILE|$HOME/conductor3default is gone; history, 2026-10-16 P1 fix: an unset CONDUCTOR_ROOT used to disable the box-wide check, and the exportedAESOP_STATE_ROOTmade halt.py treat the box-wide HALT as an isolated override, so green PRs merged during a halt); only halt.py exit 0 means "not halted"; any other result (Store-stub exit 49, missing interpreter, traceback) logsHALT-CHECK-FAILEDand skips the pass.cds to$AESOP_ROOTbecauseghresolves the repo from cwd, exports onlyAESOP_QUEUE_ROOTbeforecd(neverAESOP_STATE_ROOT; a caller-set value still isolates) so merge_queue.py's cwd isolation guard can verify it's in the dedicated queue root; teststests/test-run-merge-queue-halt.shTests 6-7 cover the HOME-resolved case. appends to state/MERGE-QUEUE.log, and propagates the tool's exit code. BASH_SOURCE exec-guard: every path/env variable declared INSIDE the guard, so sourcing exposes only resolve_python/log_line/check_halt. - run-hidden.cs → bin/run-hidden.exe (exe gitignored): C# launcher, GUI subsystem, starts bash with
CreateNoWindow, waits, and returns the child exit code. Compiled by install-tasks.ps1 with the .NET Frameworkcsc.exewhen missing or older than the source; a failed build exits 1 before any task is touched. It is the task action itself, so a missing exe fails the task (fail closed) instead of running visibly.run-hidden.vbsis retired:WScript.Shell.Run(cmd, 0, True)hides only the first window, and bash.exe still got a console on Windows 11. The derived watchdog command is brace-grouped ({ bash .../run-watchdog.sh --once; } >> .../cron-watchdog.log 2>&1) so the log captures the whole run; a hand-supplied-WatchdogCommandchain (e.g.git fetch && git reset && ...) is the caller's to group the same way. A task registered before #1133 still points atrun-hidden.vbsand is re-registered by the divergence path, so runinstall-tasks.ps1from the runtime checkout after any launcher change. - install-tasks.ps1: Windows task installer (PowerShell 5.1). Every scheduler call passes
-TaskPathroot (\), so a disabled\Aesop\<name>copy is never read or written. Action:bin\run-hidden.exe "<bash-exe>" -lc "<cmd>"; trigger: interval repeating 10y; settings: Hidden, IgnoreNew, 1h timeout. Params: BashExe, WatchdogCommand, MonitorCommand, MergeQueueCommand, intervals, TaskPrefix, -DryRun, -Plan, -ExistingTasksJson, -Uninstall, -EnableAuditLog, -EnableMergeQueue, -All, -Force. -Plan (-Plan -ExistingTasksJson <file>) prints JSON per task (name, execute, arguments, interval, logon type, decision) and calls no scheduler cmdlet; the decision isregister,unchanged, orre-register-because-<field>-diverged. Ignored same-name tasks outside the root are listed. AESOP_INSTALL_TASKS_DRY_RUN=1 refuses the real path (registration and -Uninstall); -Plan and -DryRun stay allowed. Divergence (D45): any difference in action.Execute, action.Arguments, principal.LogonType, or interval re-registers, which converges old wscript tasks; there is no warn-and-skip. Scope: default watchdog only; -EnableMergeQueue merge-queue only (OPT-IN: it merges to main with no interactive session); -All all three; -MonitorCommand monitor only. -Uninstall removes all three. -Force re-registers regardless. Tests:tests/test_install_tasks.py(Windows only) drives ONLY -Plan with fixtures and greps itself for the scheduler cmdlet names, so it is the one file that may never name them.tests/test_install_tasks_stubbed.py(Windows only) is the ONLY file allowed to stubGet-ScheduledTask,Register-ScheduledTaskandUnregister-ScheduledTask: it drives the real registration branch against recording stubs (hermeticity probe, interval-change re-registration, identical-config idempotence) and never setsAESOP_INSTALL_TASKS_DRY_RUN. Live-record reads use the CIM propertyActions[0].Arguments(plural;.Argumentis theNew-ScheduledTaskActionparameter name and yields$null, which would make every existing task look divergent). Trigger comparison (e881846942fd): an existing task whose action matches but whose repetitionIntervalorDurationdiffers is re-registered, never reported idempotent; both are parsed from CIM's ISO-8601 strings withXmlConvert(ConvertTo-WholeMinutes). Regression-covered in plan mode by test_interval_divergence_reregisters and test_duration_divergence_reregisters, and on the real branch by test_interval_change_reports_update_not_idempotent and test_same_interval_and_command_is_idempotent (stubbed file).
State files & contracts (git-ignored)
$CONDUCTOR_ROOT/state/.watchdog-heartbeat: Unix epoch seconds; updated by backup-fleet.sh at the end of every completed cycle (exit 0 or exit 3); used by selfheal.sh to detect staleness (>600s). selfheal.sh resolves the same path with the same CONDUCTOR_ROOT rule as backup-fleet.sh and SKIPs the watchdog check when it cannot be resolved. Path is shared across all monitoring infrastructure (GUI, idle_tick, monitor) regardless of AESOP_ROOT worktree location.$CONDUCTOR_ROOT/state/.watchdog-blocked: Present only after a completed cycle with >=1 BLOCKED repo; one blocked repo name per line. Written with the heartbeat on exit 3, removed by a clean cycle. Lets consumers distinguish healthy from healthy-with-blocked.$AESOP_ROOT/state/.watchdog-lock/: Atomic lockfile dir (mkdir-based, POSIX atomic). Containspid(written first) andtimestamp(epoch, refreshed every loop iteration by the holder). Reclaimed ONLY when the pid is dead (kill -0 fails), or when there is no pid and the timestamp is >300s old; a live holder is never reclaimed. Reclaim is an atomicmvaside, so only one reclaimer wins (f18337dc30c3).$AESOP_ROOT/state/.selfheal-lock/: Atomic lockfile dir for selfheal.sh (same pattern as watchdog); prevents concurrent healing attempts.$AESOP_ROOT/state/.watchdog-repos.json: Per-cycle snapshot [{repo, state: CLEAN|PUSHED|SNAPSHOTTED|BLOCKED, age}] with JSON-escaped repo names (backslash/quote/newline/control chars).$AESOP_ROOT/state/FLEET-BACKUP.log: Append-only; cycle start/end, repo statuses, secret-scan blocks, monitor staleness signals.$AESOP_ROOT/state/SELFHEAL.log: Append-only; self-healing cycle start/end, stale heartbeat detection, daemon restart actions (dry-run or real).$AESOP_ROOT/state/SECURITY-ALERTS.log: Append-only security alerts (read by alert_bridge.py for Slack/Discord webhooks).$AESOP_ROOT/state/.alert-bridge-cursor: Line number of last sent alert (idempotent dispatch).$AESOP_ROOT/state/.merge-queue-lock/: Atomic lockfile dir for run-merge-queue.sh's advancer pass (owned by tools/merge_queue.py, not the shell). Containstimestamp+pid; fail-closed on contention (a held lock means the scheduler just retries in 5 minutes), reclaimed only past 600s.$AESOP_ROOT/state/.merge-queue-heartbeat: Unix epoch seconds; beaten once per advancer pass.$AESOP_ROOT/state/merge-queue/exceptions.jsonl: Append-only advancer exception ledger; one JSON object per line,{ts, pr, kind, detail, run_url}, deduped on (pr, kind, detail) so a re-entrant pass appends nothing.$AESOP_ROOT/state/MERGE-QUEUE.log: Append-only; per-pass START/END markers and the advancer's stdout.$AESOP_ROOT/state/.pr-sweep-last: Unix epoch seconds; written after eachtools/pr_sweep.pyinvocation; throttles the sweep to once per 15 minutes regardless of the watchdog's own 5-minute cadence..HALT: Kill-switch sentinel (JSON {reason}); checked at cycle start by run-watchdog.sh and run-merge-queue.sh viapython tools/halt.py --statusas the single source of truth. Daemon reads halt.py's resolution chain (AESOP_STATE_ROOT env > aesop.config.json state_root >$AESOP_ROOT/state/.HALT), so halt.py --status and daemon are always synchronized. A halted cycle logs "HALTED:<reason>" and skips all work until cleared. Box-wide:$CONDUCTOR_ROOT/state/.HALT(written byhalt.py setunless AESOP_STATE_ROOT is set) is honored by run-watchdog.sh from any checkout (2026-10-14 N-01); run-watchdog check_halt fails CLOSED (HALT-CHECK-FAILED = skipped cycle) on any unexpected halt.py exit (F-02). Behavioral proof tests: test-daemon-halt-config-path.sh (AESOP_STATE_ROOT and config overrides), test-run-watchdog-halt-boxwide.sh (operator halt from another checkout, Store-stub exit 49, no interpreter). Prior drift (daemon re-deriving sentinel path) fixed in wave-27.
Environment variables
AESOP_ROOT(no default for backup-fleet.sh: unset refuses to run): Project root; prepends to all state/ and tools/ paths. backup-fleet.sh never falls back to.. The run-watchdog.sh entry point exports it, deriving it from its own script location when unset, never from the current directory. That derivation is announced on stderr (NOTICE: AESOP_ROOT unset; derived checkout root ...), so it is never silent; the scheduled task relies on it (install-tasks.ps1 sets no AESOP_ROOT). Test:tests/test-run-watchdog-root.sh(tracker cebab35aabeb).CONDUCTOR_ROOT(fail-closed rule,daemons/conductor-root.sh, mirrored bytools/common.py::try_resolve_conductor_rootandtools/halt.py): an explicit value always wins; the siblingconductor3is derived ONLY when AESOP_ROOT's basename is exactlyaesop; any other shape is UNRESOLVED. Readers never fall back to a home fleet root or a cwd guess: run-watchdog.sh refuses to start (exit 2), run-merge-queue.sh's box-wide check fails closed (HALT-CHECK-FAILED), halt.py --status exits 3, and pr_sweep.py exits 2 before any write. Every test pins its own fixtureCONDUCTOR_ROOT.AESOP_WATCHDOG_CYCLE_CMD: Override backup-fleet.sh invocation (test override); if set, runs asbash -c "$AESOP_WATCHDOG_CYCLE_CMD".AESOP_SELFHEAL_SKIP_RESTART: If set, selfheal.sh detects stale heartbeats and logs dry-run actions instead of actually restarting daemons (test-only flag).AESOP_STATE_ROOT(default:$AESOP_ROOT/state): State directory; exported by run-merge-queue.sh so the advancer's lock/heartbeat/ledger land with the rest of state. Single live store (D25):aesop.config.jsonkeystate_root(absolute,~allowed) is the one documented config key for the live event store. run-watchdog.sh exportsAESOP_STATE_ROOTfrom it when the env var is unset (viapython tools/state_root.py --config-only; an unreadable config is logged as ERROR), and its task-event ingest writes to${AESOP_STATE_ROOT:-$AESOP_ROOT/state}.tools/boot_state.pyresolves through the sametools/state_root.pywith precedence--state-dir>AESOP_STATE_ROOT> config key, and FAILS CLOSED (exit 2, one stderr line namingstate_root) when none is set, so the brief can no longer read a silent stale<repo>/state. Tests:tests/test_state_root.py,tests/test_boot_state.py.AESOP_MERGE_QUEUE_CMD: Override thetools/merge_queue.py --advanceinvocation (test override); if set, runs asbash -c "$AESOP_MERGE_QUEUE_CMD".REPO_OPERATION_TIMEOUT(default: 60): Per-repo git operation timeout in seconds (backup-fleet.sh; 2026-10-29 fix). Each repo'sprocess_repocall is wrapped intimeout $REPO_OPERATION_TIMEOUT; timeout exit 124 is logged as TIMEOUT status and the repo is skipped.AUTODISCOVERY_TIMEOUT(default: 240): Entire autodiscovery loop timeout in seconds (backup-fleet.sh; 2026-10-29 fix). Bounds the cycle duration so it fits within the 5-minute scheduler interval, preventing indefinite hangs.
Invariants & Style
- Single-instance guard: run-watchdog.sh and selfheal.sh each use atomic mkdir ($LOCK_DIR) to prevent concurrent daemons (both daemon and --once modes). Stale-lock recovery is pid-based (dead holder = reclaimable); a live holder is never reclaimed. selfheal.sh does not respawn run-watchdog.sh while a HALT sentinel exists.
- CRLF-safe, no line continuations: Use POSIX-safe heredocs (no backslash wrapping); scripts must work on Windows/CRLF systems.
- Append-only logs: FLEET-BACKUP.log, SELFHEAL.log only grow; rotate via tools/rotate_logs.py if >20KB.
- Secret-scan gate:
scan_tracked_files()andscan_unpushed_commits()call tools/secret_scan.py; non-0 exit blocks push, marks repo BLOCKED. - Exit codes: run-watchdog exits 0 on healthy cycle (--once) or clean startup (daemon); exits non-zero on cycle failure (backup step failed). selfheal exits 0 always (trap cleans up); backup-fleet exits 0 on a clean cycle, 3 when >=1 repo is BLOCKED by the secret-scan gate (heartbeat and
.watchdog-blockedwritten; run-watchdog treats 3 as WARN and the daemon stays up), and 1 on a hard failure (no heartbeat). - Path dedup via realpath: Avoids processing symlinked repos twice.
- Alert Bridge integration: After backup-fleet.sh cycles, run-watchdog calls
python tools/alert_bridge.py --scan || trueto post HIGH/CRITICAL alerts and heartbeat staleness. No-op if webhook_url missing in aesop.config.json (opt-in feature). Cursor file ensures idempotent dispatch. - Cycle cadence: 150s for watchdog backup cycles; 60s for selfheal healing cycles.
- Selfheal safety: Never kills/restarts a daemon with a fresh heartbeat (idempotent). Monitors both local (watchdog) and conductor3 (monitor) heartbeats from aesop state/. Restarts via documented launch command (bash run-watchdog.sh / bash run-monitor.sh) in background.
- Windows: tasks must be registered via install-tasks.ps1 (hidden launcher
bin\run-hidden.exe) — never raw bash.exe actions (visible console window flashes every interval). - The scheduler is the loop: run-merge-queue.sh has no loop, no sleep and no watcher; it runs one bounded pass and exits. Never add polling here or in tools/merge_queue.py — a scheduled actor that waits is just a session with extra steps.
- The advancer never bypasses a gate: no
--admin, no--auto, no force-push, no review-thread resolution, no secret-scan tampering, no model calls. It merges only whenenforce_adminsis asserted AND every required check is green under its own fail-closed bucketing; anything else becomes an exception row.
Cadence verification (Windows)
Heartbeats prove a daemon ran; they cannot prove it ran at the right rate. The refinement monitor once fired hourly against its 20-minute SLA with every cycle exiting 0 and every heartbeat fresh at read time -- nothing compared the registered cadence to the defined one.
tools/task_cadence_check.py closes that gap: it parses this directory's install-tasks.ps1
as the source of truth (binding each Register-DaemonTask call site's -TaskName /
-IntervalMinutes through the param defaults and ${TaskPrefix} interpolation, so expected
cadences are never hand-copied), then reads live state from schtasks /query /tn <name> /xml
and compares. Exit 1 on interval mismatch, unregistered task, or disabled task; exit 2
(fail-closed) on any query/parse failure, which outranks exit 1 so an unevaluable task is
never masked by clean siblings. <Enabled> is optional in Task Scheduler XML and its absence
means enabled; /xml output is UTF-16 and is decoded by BOM.
Windows-only by construction: on any other platform it prints a SKIPPED-non-windows line and
exits 0, so ubuntu CI is unaffected. The intended consumer is the local /power self-test
(power_selftest.py), which should invoke it alongside the existing heartbeat-staleness
checks. Run it manually after any install-tasks.ps1 change or after a reboot:
python tools/task_cadence_check.py [--json].
Its tests (tests/test_task_cadence_check.py) are fixture-driven and never shell out to
schtasks -- the query function is injectable -- so the suite runs identically on both OSes.
Testing
Run all daemons tests (hermetic, uses mktemp fixtures):
bash tests/test-run-watchdog.sh
bash tests/test-run-watchdog-lockguard.sh
bash tests/test-run-watchdog-halt.sh
bash tests/test-run-watchdog-ingest.sh
bash tests/test-daemon-halt-config-path.sh
bash tests/backup-fleet.test.sh
bash tests/test-selfheal.sh
bash tests/test-backup-fleet-blocked-heartbeat.sh
bash tests/test-selfheal-conductor-heartbeat.shOr via npm:
npm run test:shSelfheal test coverage:
- Stale heartbeat detection (missing/corrupt/old timestamps → treated as stale).
- Fresh heartbeat respect (never restart daemons with live heartbeats).
- Append-only logging (each cycle appends cycle start/end + actions).
- Single-instance guard (concurrent invocations lock second one out).
- Dry-run mode (AESOP_SELFHEAL_SKIP_RESTART=1 logs actions without restarting).
Tests never touch real AESOP_ROOT/state; all invocations point at throwaway mktemp dirs. REPO_ROOT locates the script under test only.
Dropped (reason)
- Alert Bridge details (wave-14 feature; see tools/alert_bridge.py for implementation)
- Config parsing details (see aesop.config.json structure in root CLAUDE.md)
- Per-function implementation details (inlined only contracts/interfaces above)
Map of all domains: /CLAUDE.md
- Box fence in run-watchdog.sh:
run_box_fenceruns tools/box_fence.py before the lock and any cycle; a FAIL logs an ERROR line to FLEET-BACKUP.log and exits 1 (daemon and --once); WARN (offline) logs and continues.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

