homelab-codex-ws/docs
oskar 3474744607 docs(recon): node-agent vs stability-agent — decide-support merge/retire
Decide-support recon for the two per-node sensors. Finding-first, sections 1-5
per brief, ends with DECISION NEEDED (no recommendation).

Headline: stability-agent's filesystem event channel is structurally unreadable
by the control plane, not merely mis-tagged. Recon D15 named one break; there
are five, stacked, any one fatal:
  1. wrong subtree   — events/<date>/<node>/events.jsonl vs events/<node>/
  2. wrong extension — observer.py:912 / supervisor.py:605 glob **/*.json
  3. wrong format    — observer json.load()s the whole file; JSONL is not one
  4. never shipped   — node_agent.py:788 rsyncs only events/<node>/
  5. details vs payload key, plus service=None (D15)

D15 is stale on master but still true in production: fix f92e161 (2026-07-29) is
merged, the running solaria image was built 2026-05-17, and 100% of the 5,056
deployed events sampled carry service=None. Moot regardless — breaks 1-4 mean
the observer never opens the file. All six event types are inert, not just
containers_not_running.

Counterweight: stability-agent is the sole writer of the Redis keys the
agent-system WebUI renders (4 node, 130 service, 31,458-entry stream, refreshed
during the recon). node-agent has no Redis code. Retiring it blanks that UI.

Runtime evidence over the retained window:
  node-agent      50,773 events -> 1 incident
  stability-agent  7,317 events -> 0 incidents (structurally zero since
                                  first deploy 2026-05-17)

Also found: deploy-local.sh validates 'chelsty' but the repo has
hosts/chelsty-infra/, so the only override carrying MQTT_HOST has never been
applied (stale homelab:nodes:chelsty key from 2026-06-02); scripts/lib/events.sh
writes to the same dead path; CLAUDE.md:100 documents the dead format as
canonical; recon B7 is stale — stability-agent IS in hosts/{solaria,vps}
services.yaml, but deploy-node.sh:93 skips it.

Read-only recon: no runtime mutations, no config changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-30 20:07:56 +02:00
..
architecture docs(recon): node-agent vs stability-agent — decide-support merge/retire 2026-07-30 20:07:56 +02:00
infra docs(infra): audyt niezarzadzanych stackow VPS — mapa przed konsolidacja do GitOps 2026-07-27 17:49:37 +02:00
kb test(kb-query): luki T1–T3 z test_fallback.py + status kalibracji ollama-piha (salvage S3+S4) 2026-07-30 16:40:24 +02:00
sessions docs(sessions): wciągnięcie loga 2026-07-27 kb-f4-fallback z porzucanego brancha (salvage S2) 2026-07-30 16:40:24 +02:00
access.md Document current homelab state 2026-04-15 17:37:25 +02:00
agents.md docs: uzupelnij dokumentacje pod katem agentow AI 2026-05-20 12:06:23 +02:00
backlog.md docs(backlog): follow-upy z etapu 0 — 40-register.sh stary schemat topologii, komentarz mqtt_unreachable w observerze 2026-07-29 19:15:55 +02:00
capabilities.md docs: uzupelnij dokumentacje pod katem agentow AI 2026-05-20 12:06:23 +02:00
chelsty-runtime.md docs: session summary 2026-05-27 + update observer/control-plane/chelsty docs 2026-05-27 16:18:31 +02:00
chelsty-stability-agent.md docs(chelsty): update docs and topology for site/node split 2026-05-20 14:23:57 +02:00
core-stack.md Document current homelab state 2026-04-15 17:37:25 +02:00
deployment.md docs(deployment): add critical warning — deploy.sh vps destroys control-plane (project-name divergence, 2026-06-25 incident) 2026-06-25 16:30:53 +02:00
event-system.md Implement filesystem-first runtime event system 2026-05-12 13:38:25 +02:00
hardware.md Document current homelab state 2026-04-15 17:37:25 +02:00
hetzner-vps.md Document VPS connectivity diagnostics 2026-04-15 20:38:09 +02:00
joplin-server.md Document VPS connectivity diagnostics 2026-04-15 20:38:09 +02:00
lifecycle.md Harden deployment runtime framework 2026-05-11 21:20:13 +02:00
networking.md Document current homelab state 2026-04-15 17:37:25 +02:00
node-onboarding.md Implement reproducible node onboarding 2026-05-12 13:18:00 +02:00
observer-runtime.md feat(observer): 3-state node liveness (fresh/stale/dead) + transitions + read-time net 2026-06-17 20:07:25 +02:00
questions.md Document Hetzner VPS handoff 2026-04-15 17:46:42 +02:00
service-model.md Add node capability model 2026-05-11 20:46:50 +02:00
services.md Document Hetzner VPS handoff 2026-04-15 17:46:42 +02:00
stability-agent-rollout.md Fix stability agent fleet deploy scripts 2026-05-17 21:09:06 +02:00
standards.md docs: uzupelnij dokumentacje pod katem agentow AI 2026-05-20 12:06:23 +02:00
topology.md Add CHELSTY home automation inventory model 2026-05-11 20:54:54 +02:00
vps-control-plane.md docs: session summary 2026-05-27 + update observer/control-plane/chelsty docs 2026-05-27 16:18:31 +02:00