From 756ae6959575501f129521945cb63bd50c438fa4 Mon Sep 17 00:00:00 2001 From: Tom Softreck Date: Mon, 16 Nov 2026 19:47:27 +0100 Subject: [PATCH] docs(release, ticket-137): document fixos anomalies and release 2.4.0 Add the information document for the host anomaly detector and raise VERSION and pyproject.toml to 2.4.0 so an installed fixOS includes ticket-135 (artifact store reclaim) and ticket-136 (fixos anomalies). Co-Authored-By: Claude Fable 5.2 --- VERSION | 2 +- docs/information/host-anomalies.md | 128 +++++++++++++++++++++++++++++ project/ticket-137/README.md | 30 +++++++ project/ticket-137/intent.json | 88 ++++++++++++++++++++ pyproject.toml | 2 +- 5 files changed, 248 insertions(+), 2 deletions(-) create mode 100644 docs/information/host-anomalies.md create mode 100644 project/ticket-137/README.md create mode 100644 project/ticket-137/intent.json diff --git a/VERSION b/VERSION index 276cbf9..197c4d5 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.3.0 +2.4.0 diff --git a/docs/information/host-anomalies.md b/docs/information/host-anomalies.md new file mode 100644 index 0000000..7721778 --- /dev/null +++ b/docs/information/host-anomalies.md @@ -0,0 +1,128 @@ +--- +{ + "schema": "wellmanifest.docs/document/v1", + "id": "host-anomalies", + "kind": "information", + "version": 1, + "title": "Wykrywanie anomalii hosta poza zwykłym czyszczeniem cache", + "status": "proposed", + "owner": "semcod/fixos", + "created": "2026-11-16", + "updated": "2026-11-16", + "review_after": "2026-12-16", + "source_revision": "e5947fdc66774dfb41bedbfaeedff4e4248dc67f", + "affected_repositories": ["semcod/fixos"], + "evidence": [ + "https://github.com/semcod/fixos/blob/e5947fdc66774dfb41bedbfaeedff4e4248dc67f/fixos/diagnostics/host_anomalies.py", + "https://github.com/semcod/fixos/blob/e5947fdc66774dfb41bedbfaeedff4e4248dc67f/fixos/cli/anomalies_cmd.py", + "https://github.com/semcod/fixos/blob/e5947fdc66774dfb41bedbfaeedff4e4248dc67f/tests/unit/test_host_anomalies.py" + ] +} +--- + +# Wykrywanie anomalii hosta poza zwykłym czyszczeniem cache + + +## Cel + +`fixos anomalies` wykrywa przyczyny obciążenia i braku miejsca, których nie +widzą `fixos auto` ani `fixos cleanup`: usługi w pętli restartów, logi +kontenerów bez rotacji, duże nieruszane katalogi w magazynach stanu narzędzi, +odtwarzalne indeksy IDE oraz procesy zombie i grupy zawieszonych procesów. +Detektory działają lokalnie, bez LLM i bez zmian w systemie. + + +## Zakres + +| Kategoria | Co jest zgłaszane | Ważność | +| --- | --- | --- | +| `restart-loop` | jednostki systemd (systemowe i użytkownika) z `NRestarts` ≥ 50 w stanie `auto-restart` albo z ≥ 500 restartami | `high` w pętli, inaczej `medium` | +| `container-logs` | brak `log-opts.max-size` w `/etc/docker/daemon.json`; logi `*-json.log` ≥ 100 MiB | `medium`, `low` | +| `stale-state` | najwyższy katalog w `~/.local/state` lub `~/.local/share` o rozmiarze ≥ progu, w którym nic nie zmieniono od N dni | `review` | +| `ide-index` | katalog `~/.cache/JetBrains//index` ≥ progu | `safe`, a przy działającym IDE `protected` | +| `zombie-processes` | ≥ 10 procesów zombie pod jednym rodzicem | `medium` | +| `idle-process-group` | ≥ 50 uśpionych procesów starszych niż 24 h o identycznym pełnym poleceniu | `medium` | + +Katalogi prywatne i magazyny poświadczeń (`Downloads`, `Documents`, `.ssh`, +`.gnupg` i pozostałe z listy `artifact_store.PROTECTED_HOME_DIRS`) nigdy nie są +kandydatami. + + +## Dowody + +Źródło: ticket-136, commit e5947fd (PR 179). **10 testów jednostkowych PASS**, +Ruff PASS, natywna bramka governance PASS; testy CI na Pythonie 3.10–3.12 oraz +Alpine, Arch, Debian, Fedora i Ubuntu PASS. + +Uruchomienie na hoście budującym 2026-11-16 zwróciło 23 ustalenia: 4 usługi w +pętli restartów (do 63 tys. restartów), 15 katalogów stanu o łącznym rozmiarze +45,7 GiB oraz 4 procesy-rodzice z 10–342 procesami zombie. Pierwsza wersja +błędnie zgłaszała `docker-proxy` i `containerd-shim` jako grupy zawieszonych +procesów; grupowanie po pełnym poleceniu usunęło te fałszywe alarmy i jest +objęte testem. + +Dokument nie jest dowodem instalacji wersji 2.4.0 na konkretnym komputerze. + + +## Użycie i decyzje + +```bash +# Raport czytelny dla człowieka +fixos anomalies + +# Raport maszynowy (schemat fixos.host-anomalies/v1) +fixos anomalies --json + +# Inne progi katalogów stanu i indeksów IDE +fixos anomalies --min-size-gb 5 --min-age-days 30 + +# Usuń indeksy IDE, które nie są w tej chwili używane +fixos anomalies --remove-safe + +# Podgląd usunięcia wskazanego katalogu stanu +fixos anomalies --remove ~/.local/state/narzedzie/backups --dry-run +``` + +`--remove` i `--remove-safe` usuwają wyłącznie katalogi, które bieżący skan +nadal oznacza jako usuwalne (`stale-state` albo `ide-index` bez działającego +IDE), położone w katalogu domowym, niebędące dowiązaniem symbolicznym ani +katalogiem chronionym. Każde usunięcie zapisuje pokwitowanie +`fixos.host-anomaly-removal/v1` w `~/.local/state/fixos/receipts/`. + +Pozostałe kategorie mają tylko podpowiedziane polecenia (`systemctl disable +--now`, wpis `log-opts` do `daemon.json`, `truncate`, `pgrep`). fixOS ich nie +wykonuje, bo zmieniają usługi i procesy należące do innych właścicieli. + +`stale-state` ma zawsze ważność `review`: magazyny stanu zawierają zarówno +odtwarzalne kopie i obrazy, jak i pokwitowania oraz dowody. Przed usunięciem +sprawdź zawartość katalogu. + + +## Ograniczenia + +Pomiar katalogów stanu używa `du` z limitem 30 minut na korzeń; na obciążonym +hoście z magazynem rzędu 100 GiB skan trwa kilkadziesiąt minut. Po +przekroczeniu limitu dany korzeń nie zwraca kandydatów, a raport tego nie +sygnalizuje. + +„Bez zmian od N dni” opiera się na mtime plików, a nie na faktycznym użyciu; +dane tylko czytane wyglądają jak nieużywane. Otwarte uchwyty plików nie są +sprawdzane dla katalogów stanu. + +Logi kontenerów wymagają uprawnień do odczytu `/var/lib/docker/containers`; +bez nich zgłaszany jest tylko brak rotacji. Detektor indeksów IDE obejmuje +wyłącznie produkty JetBrains. Procesy widoczne są tylko w bieżącej przestrzeni +nazw PID. + + +## Następne kroki + +Zasygnalizować w raporcie korzeń, którego pomiar przekroczył limit czasu. +Dodać kontrolę otwartych uchwytów przed oznaczeniem katalogu stanu jako +kandydata. Rozważyć dołączenie raportu do `fixos auto --dry-run`. +[Diagnostyka dużych plików](storage-triage.md). + + +## Historia + +- Wersja 1: polecenie `fixos anomalies` z ticket-136 (e5947fd), dokumentacja i wydanie 2.4.0 w ticket-137. Liczby opisują sprawdzony commit i jedno uruchomienie na hoście budującym; nie dowodzą publikacji pakietu na PyPI. diff --git a/project/ticket-137/README.md b/project/ticket-137/README.md new file mode 100644 index 0000000..a529a4d --- /dev/null +++ b/project/ticket-137/README.md @@ -0,0 +1,30 @@ +# Ticket 137: Document host anomaly detection and release 2.4.0 + +- **ID**: ticket-137 +- **Owner**: unresolved:human +- **Status**: IN_PROGRESS +- **Workflow state**: EDIT +- **Created**: 2026-11-16 + +## Goal and scope + +`fixos anomalies` (ticket-136) and the artifact store reclaim (ticket-135) are +merged but unreleased: the package version is still 2.3.0, so an installed +fixOS does not have them. + +Scope: add `docs/information/host-anomalies.md` describing the command, its +categories, removal guards and limits, and raise `VERSION` and +`pyproject.toml` to 2.4.0. No code changes. `CHANGELOG.md` is owned by the +governance workstream and is not touched here. + +## Acceptance criteria + +- [x] AC-01: `python -m fixos.cli --version` reports 2.4.0 from the ticket worktree. +- [x] AC-02: The document follows the repository docs format (front matter and + the seven `docs:section` markers) and states only verified results. +- [ ] AC-03: Governance check and exact-head review pass. + +## Tracking boundary + +This directory contains the minimal reviewed intent. Optional participant prose +and raw command logs are not required delivery output. diff --git a/project/ticket-137/intent.json b/project/ticket-137/intent.json new file mode 100644 index 0000000..f4fa488 --- /dev/null +++ b/project/ticket-137/intent.json @@ -0,0 +1,88 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-137", + "summary": "Document host anomaly detection and release 2.4.0", + "workstream": "integration", + "classification": { + "kind": "FEATURE", + "priority": "P2", + "origin": "requested" + }, + "allowedPaths": [ + "project/ticket-137/**", + "TODO.md", + "project/TICKETS.md", + "VERSION", + "docs/information/host-anomalies.md", + "pyproject.toml" + ], + "forbiddenPaths": [ + "project/ticket-*/user-*.md" + ], + "stacks": [], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null, + "delivery": { + "acceptedBaseSha": "6d38f9beb4c1dfd1dffb64be82b107f5b9535734", + "targetBranch": "main", + "outcome": "fixos 2.4.0 ships host anomaly detection and artifact store reclaim, with the anomalies command documented.", + "nonGoals": [ + "No code changes; the feature was delivered by ticket-135 and ticket-136.", + "No PyPI publication in this ticket." + ], + "complexity": "S", + "estimatedMinutes": 20, + "budgets": { + "maxImplementationFiles": 3, + "maxAffectedComponents": 2, + "maxPublicInterfaceChanges": 0, + "maxRuntimeDependencies": 0 + }, + "architecture": { + "status": "accepted", + "decision": "Add an information document for fixos anomalies in the repository docs format and raise VERSION and pyproject.toml to 2.4.0 in the same integration ticket.", + "components": [ + { + "name": "documentation", + "paths": [ + "docs/information/host-anomalies.md" + ] + }, + { + "name": "packaging", + "paths": [ + "VERSION", + "pyproject.toml" + ] + } + ], + "responsibilityChanges": false, + "interfaceChanges": [], + "dataChanges": [], + "ui": { + "impact": "none", + "states": [], + "evidence": [] + }, + "rollback": "Revert the commit; no runtime behaviour depends on it." + }, + "runtimeDependencies": [], + "validation": [ + { + "criterion": "AC-01", + "commands": [ + "python -m fixos.cli --version" + ], + "evidence": "reports 2.4.0" + }, + { + "criterion": "AC-02", + "commands": [ + "./project/governance-check.sh" + ], + "evidence": "governance-check output" + } + ] + } +} diff --git a/pyproject.toml b/pyproject.toml index 3698fb7..14c80f2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "fixos" -version = "2.3.0" +version = "2.4.0" description = "AI-powered Linux/Windows diagnostics and repair – audio, hardware, system issues" readme = "README.md" requires-python = ">=3.10"