feat: live-sync heartbeat commits machine-written paths
The checkout IS the deployment and symlinks make live state (memories, auto-learned skills, agent config, desktop settings) dirty tracked files continuously; no commit law covered machine churn, so it accumulated unpushed for weeks — one disk held the only copy of ~61 managed skills, a settings fix stayed local-only, and dirty trees refused merges. scripts/live-sync.sh (systemd user timer, ~15 min) commits ONLY the allowlisted machine/desktop-live tiers with hooks armed, merges origin/main, pushes, and reaps wt/* worktrees older than 7 days. Task dirt outside the allowlist is never staged; conflicts abort and alert via ntfy; branch guard refuses off main; never --no-verify, never force. Black-box contract pinned by tests/live-sync.bats (9 tests, suite 36/36). Refs #11
This commit is contained in:
Frank
@@ -11,6 +11,10 @@ timestamp: 2026-08-28
|
||||
|
||||
# Bundle Change Log
|
||||
|
||||
## 2026-10-18 — live-sync heartbeat for machine-written paths (Refs #11)
|
||||
|
||||
Root-caused the month of silent divergence in the live checkout (~61 auto-learned skills on one disk only, a stranded `unexpectedStopDetection` fix, merge-refusals from dirty trees): the checkout IS the deployment, symlinks make machine writes dirty tracked files by design, and no commit law covered that churn. Added `scripts/live-sync.sh` + systemd user timer — allowlist tiers (memories, managed-skills, live config, dotfiles) auto-commit with hooks armed, merge `origin/main`, push, and reap stale `wt/*` worktrees; everything outside the allowlist is never staged, conflicts abort-and-alert. Black-box suite `tests/live-sync.bats` (9 tests). Tier law in AGENTS.md § Live-sync tiers; reference page `tools/live-sync.md` registered in the tools index.
|
||||
|
||||
## 2026-10-18 — Fleet law: filed PRs open in Frank's browser immediately
|
||||
|
||||
Both repos' git rules now require it: the moment a PR is opened, `xdg-open <PR-URL>` drops a Firefox tab on the workstation (AGENTS.md § Trunk-based SDLC here; § Git Workflow step 6 in `dank/serverAppConfigs`, riding their PR #6 branch).
|
||||
|
||||
@@ -8,6 +8,7 @@ Configuration guides and reference material for installed software. Each tool ha
|
||||
|
||||
* [[cachyos|cachyos]] — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on the workstation.
|
||||
* [comfyui](comfyui/index.md) — Node-based AI image generation engine on dankclaw. FLUX.2 klein 4B, CPU backend, systemd managed.
|
||||
* [live-sync](live-sync.md) — Heartbeat daemon committing machine-written paths (memories, managed-skills, live config, dotfiles) in the command-center checkout; systemd user timer, alerts via ntfy.
|
||||
* [[applications|applications]] — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming.
|
||||
* ](ghostty/index.md) — GPU-accelerated terminal emulator with extensive configuration, keybindings, and shaders.
|
||||
* ](gitea/index.md) — Private Git hosting on dankclaw. Quadlet-managed containers: Gitea, PostgreSQL, Caddy.
|
||||
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
type: reference
|
||||
title: live-sync heartbeat
|
||||
description: Auto-commit daemon for machine-written paths in the command-center checkout — the deployment is live, so symlinks make config churn dirty tracked files continuously.
|
||||
tags:
|
||||
- git
|
||||
- automation
|
||||
- systemd
|
||||
- deployment
|
||||
- fleet
|
||||
verified: 2026-10-18
|
||||
timestamp: 2026-10-18
|
||||
---
|
||||
|
||||
# live-sync heartbeat
|
||||
|
||||
The command-center checkout IS the deployment, and several tracked files are
|
||||
live state: the harness writes memories and managed-skills, the operator
|
||||
edits `config.yml`/`models.yml` through the `cfg://` surface, and desktop
|
||||
GUIs (Noctalia, niri) rewrite dotfiles through symlinks. Before Refs #11 this
|
||||
machine churn just piled up unpushed — one disk holding the only copy of ~61
|
||||
auto-learned skills, a settings fix stranded locally, and merge-refusals
|
||||
because the dirty tree collided with incoming work.
|
||||
|
||||
`scripts/live-sync.sh` is the pressure valve: a heartbeat that commits the
|
||||
machine's own writes on a schedule. Tier law (which paths it may touch) lives
|
||||
in [AGENTS.md](../../AGENTS.md) § Live-sync tiers.
|
||||
|
||||
## Contract (black-box)
|
||||
|
||||
Run = one pass: flock → branch guard (`main` only) → stage allowlisted dirty
|
||||
tiers → commit (hooks armed) → fetch + merge `origin/main` → push → reap
|
||||
stale `wt/*` worktrees. Exit `0` = quiet heartbeat (synced/no-op/reaped);
|
||||
exit `1` = an alert was raised. Pinned by `tests/live-sync.bats`.
|
||||
|
||||
Hard properties:
|
||||
|
||||
- **Allowlist only.** Task dirt (`plugins/`, `omp-docs/`, prose) is never
|
||||
staged — merge conflicts with in-flight work become impossible by
|
||||
construction.
|
||||
- **Hooks stay armed.** A secret-gate refusal aborts the commit, leaves
|
||||
changes staged for a human, and alerts. Never `--no-verify`, never force.
|
||||
- **Never fights the remote.** Merge conflict → `merge --abort`, local
|
||||
commit kept, alert. Retries are automatic next tick.
|
||||
- **Branch guard.** On a non-`main` checkout it refuses and alerts — same
|
||||
rule as the doctrine ("never end a session off main").
|
||||
- **Polite reaper.** `wt/wt-*` worktrees untouched for 7+ days are removed
|
||||
with their `wt/*` branch; dirty or process-occupied worktrees are skipped.
|
||||
|
||||
## Alerts
|
||||
|
||||
`notify()` writes stderr always; pushes to ntfy when the topic file
|
||||
`~/.config/ntfy/live-sync` (mode 600, topic text only) exists, throttled to
|
||||
one push per hour. Test seams: `LIVE_SYNC_REPO`, `LIVE_SYNC_NOTIFY`,
|
||||
`LIVE_SYNC_NTFY_TOPIC_FILE`, `LIVE_SYNC_AGE_DAYS`.
|
||||
|
||||
## Install
|
||||
|
||||
Units ship in `dotfiles/systemd-user/.config/systemd/user/` and propagate
|
||||
with the usual dotfiles chain:
|
||||
|
||||
```bash
|
||||
systemctl --user enable --now live-sync.timer # after the unit is linked
|
||||
systemctl --user start live-sync.service # one manual heartbeat
|
||||
journalctl --user -u live-sync.service -n 20 # observe
|
||||
```
|
||||
|
||||
## Failure modes
|
||||
|
||||
| Event | Result |
|
||||
|-------|--------|
|
||||
| Harness mid-write | commits a valid snapshot; remainder lands next heartbeat |
|
||||
| Gitea down | commit safe locally; push retries next tick (≤15 min stale window) |
|
||||
| Same file edited on two boxes | real merge conflict → ntfy → human resolves (visible, not silent) |
|
||||
| Feature branch checked out in main checkout | refuses + alerts; protects the never-end-off-main rule |
|
||||
| Secret shape in machine-written content | hook blocks, changes stay staged, alert |
|
||||
Reference in New Issue
Block a user