Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.3.0
2.4.0
128 changes: 128 additions & 0 deletions docs/information/host-anomalies.md
Original file line number Diff line number Diff line change
@@ -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

<!-- docs:section purpose -->
## 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.

<!-- docs:section scope -->
## 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/<produkt>/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.

<!-- docs:section evidence -->
## 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.

<!-- docs:section content -->
## 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.

<!-- docs:section limitations -->
## 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.

<!-- docs:section next_actions -->
## 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).

<!-- docs:section history -->
## 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.
30 changes: 30 additions & 0 deletions project/ticket-137/README.md
Original file line number Diff line number Diff line change
@@ -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.
88 changes: 88 additions & 0 deletions project/ticket-137/intent.json
Original file line number Diff line number Diff line change
@@ -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"
}
]
}
}
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Loading