thebpandey/session-cleanup

Was macht session-cleanup?

Erst prüfen, dann löschen – und nur, nachdem das Ziel inspiziert wurde. Das Ziel ist, dass der Besitzer die Session verlassen kann, in dem Wissen, dass nichts mehr läuft, nichts verloren ist und nichts Altes zurückbleibt. Ein übersehenes Überbleibsel ist billig; ein gelöschter, nicht gepusher Commit ist es nicht. Im Zweifel geht ein Fund in ASK, niemals in AUTO-CLEAN.

Funktioniert in jedem Git-Repo. Die Lanes-Harness-, Beads- und Vercel-Teile schalten sich nur zu, wenn sie vorhanden sind; andernfalls werden sie still übersprungen.

Phase 1: Prüfung (nur lesend)

Führen Sie die gebündelte Prüfung aus dem Repo (einem beliebigen Worktree davon) aus. Verwenden Sie das Skript für Ihr Betriebssystem; der Skill-Ordner kann unter ~/.claude/skills/, ~/.codex/skills/ oder ~/.agents/skills/ liegen:

# Linux und macOS
bash <skill-verz>/scripts/audit.sh                 # --no-fetch für offline

# Windows (PowerShell 5.1 oder 7)
powershell -NoProfile -ExecutionPolicy Bypass -File <skill-verz>\scripts\audit.ps1   # -NoFetch für offline

Beide geben einen Abschnitt pro Bereich aus (CONTEXT, WORKING_TREE, SYNC, WORKTREES, BRANCHES, STASHES, LANES, PROCESSES, ARTIFACTS, TRACKER, DEPLOY, SESSION_LOG). Der einzige Schreibvorgang ist ein einfaches git fetch (niemals --prune). Es liest niemals .env-Dateien und gibt keine Prozessumgebungen aus.

Wie „diese Session“ festgelegt wird (wichtig für jede Klassifizierung):

• Prozesse: owner=this_session bedeutet, dass diese Session (oder etwas, das sie gestartet hat) den Prozess gestartet hat. Unter Linux wird dies durch die geerbte CLAUDE_CODE_SESSION_ID nachgewiesen, die nohup überlebt. macOS und Windows verbergen die Umgebungen anderer Prozesse, daher bedeutet es dort „Nachkomme des Claude-Prozesses“ (CLAUDE_PID); ein Prozess, der abgetrennt und neu zugeordnet wurde, wird stattdessen als started_during_session angezeigt, was ASK ist, es sei denn, Sie können ihn in diesem Gespräch nachverfolgen. owner=harness_do_not_kill sind die eigenen MCP-Server und Plugins von Claude Code: diese niemals anfassen. other_session_or_user gehört jemand anderem.
• Dateien, Branches, Stashes: this_session / pre_session vergleicht den Zeitstempel mit session_start (erster Zeitstempel im Transkript dieser Session). Zeitstempel sind ein Hinweis, kein Beweis: etwas, das während des Session-Zeitfensters erstellt wurde, könnte aus einer parallelen Session stammen. Behandeln Sie ein Element nur dann als dieser Session zugehörig, wenn der Zeitstempel dies sagt und Sie es in diesem Gespräch nachverfolgen können (Sie haben den Befehl ausgeführt, der es erstellt hat). Sonst ist es ASK.

Außerhalb von Claude Code (z. B. in Codex) gibt es keine CLAUDE_CODE_SESSION_ID oder CLAUDE_PID, daher ist session_id unknown, alles wird mit pre_session getaggt, und Prozesse werden nur durch in_repo abgeglichen. Übergeben Sie --since <ISO-Zeit> (-Since unter Windows) mit dem Session-Start, falls bekannt, und behandeln Sie andernfalls Dateien und Prozesse als ASK, es sei denn, Sie können sie auf einen Befehl in diesem Gespräch zurückführen.

Füllen Sie dann die Lücken, die das Skript nicht sehen kann, nach Möglichkeit parallel:

1. Ihre eigenen Hintergrundarbeiten. Listen Sie Hintergrund-Bash-Tasks, Monitore, Unteragenten und geplante Aufweckvorgänge auf, die Sie in diesem Gespräch gestartet haben und die noch laufen. Stoppen Sie beendete oder untätige mit dem Tool, das sie gestartet hat (TaskStop, Monitor-Stopp usw.).
2. Anforderungs-Überbleibsel. Durchsuchen Sie das Gespräch nach allem, was der Besitzer gebeten hat, später zu löschen oder nur vorübergehend zu behalten (ein Uploads-Ordner, ein Debug-Flag, ein Testkonto, eine temporäre Datei). Prüfen Sie, ob es noch existiert.
3. Deploy-Zustand (nur wenn DEPLOY eine Plattform anzeigt). Holen Sie den Commit-SHA des neuesten Produktions-Deployments und vergleichen Sie ihn mit main_tip. Für Vercel: vercel ls --prod, um das neueste Produktions-Deployment zu finden, dann vercel inspect <url> (oder den Vercel MCP / das Dashboard) für dessen Git-Commit. Wenn Sie den SHA nicht erhalten können, melden Sie „deploy: unverified“ mit dem Grund. Leiten Sie niemals eine Übereinstimmung aus Zeitstempeln ab.
4. Alles außerhalb des Repos, das die Session berührt hat (ein Worktree eines anderen Repos, eine globale Installation). Melden Sie es; verändern Sie es nicht.

Phase 2: Jeden Fund klassifizieren

AUTO-CLEAN (sicher und wiederherstellbar; ausführen, dann melden):

• Lokale Branches, die vollständig in main gemergt sind (git branch -d, niemals -D), ausschließlich main, dem aktuellen Branch und jedem Branch, der in einem Worktree ausgecheckt ist.
• Entfernbare Worktree-Einträge, deren Ordner bereits verschwunden ist (git worktree prune).
• Saubere verlinkte Worktrees innerhalb dieses Repos, deren Branch in main gemergt ist und keine Commits voraus hat (git worktree remove <pfad>, kein --force; dann git branch -d). Wenn der Lanes-Harness ihn besitzt, verwenden Sie stattdessen das Harness-Skript (siehe unten).
• Temp-Ordner, deren Lane oder Branch nicht mehr existiert und die kein Prozess offen hat (open_handles=0; vor dem Löschen sofort mit lsof +D <verz> nachprüfen).
• Prozesse mit owner=this_session, die Sie diesem Gespräch zuordnen können und die untätig oder nicht mehr benötigt werden (Dev-Server, Watcher, kopflose Browser). Nur per PID töten (kill <pid> auf Linux/macOS, Stop-Process -Id <pid> auf Windows).
• Veraltete Build-Typ-Caches (.next/types, .next/dev/types), die gitignored sind. Diese werden beim nächsten Build neu generiert.
• Eigene Scratch-Dateien dieser Session in ihrem Scratchpad-Ordner und ungetrackter Müll im Repo (*.orig, *.rej, verirrte Logs), der this_session ist und auf einen von Ihnen ausgeführten Befehl zurückführbar ist.

ASK (könnte Arbeit verlieren oder ist nicht nachweislich dieser Session zuzuordnen):

• Ungemergte Branches oder Commits, die nicht in main sind. Ein Branch, der als PATCHES_ALREADY_IN_main markiert ist, wurde wahrscheinlich squash- oder rebase-gemergt: sagen Sie das, aber fragen Sie trotzdem vor -D.
• Verschmutzte Worktrees (dirty_files > 0), Stashes, coverage/ und test-results/, die möglicherweise als Nachweis gewünscht werden.
• Prozesse other_session_or_user oder started_during_session sowie jeden Prozess, den Sie nicht zuordnen können.
• Alles pre_session und jede ungetrackte Datei, die Sie nicht erstellt haben.

NUR MELDEN (der Besitzer handelt, oder es dient der Information):

• Abweichung zwischen main und origin (nicht gepusht oder hinterher). Empfehlen Sie den Push oder Pull; führen Sie ihn nicht als Teil der Bereinigung durch.
• Deploy-Unterschiede oder „unverified“-Deploy-Zustand.
• Offene Tracker-Elemente (beads in_progress, tasks.md in Arbeit) ohne aktive Arbeit und erledigte Arbeit, deren Aufgabe noch offen ist. Nennen Sie das Element und was Sie gesehen haben.
• Worktrees oder Ordner außerhalb dieses Repos und upstream_gone-Branches, die noch einzigartige Commits haben.

Sicherheitsregeln

Diese schützen Arbeit, die nicht neu erstellt werden kann. Jede Regel existiert, weil die offensichtliche Abkürzung bereits Arbeit zerstört hat.

• Vor dem Löschen prüfen. Listen Sie für jeden Ordner seinen Inhalt und seine Größe auf. Zeigen Sie für jeden Branch git log --oneline main..<branch> an. Fügen Sie diese Nachweise in den Bericht ein.
• Niemals ungemergte Commits, verschmutzte Worktrees oder Stashes ohne die ausdrückliche Zustimmung des Besitzers in diesem Gespräch löschen. Die Zustimmung für ein Element deckt nicht das nächste ab.
• Prozesse nur per PID töten, nachdem owner=this_session bestätigt wurde und dass Sie ihn gestartet haben. Niemals pkill, killall, kill -9 beim ersten Versuch oder nach Port allein töten.
• Niemals bloßes git stash, git reset --hard, git clean -fdx (oder irgendein git clean -f) oder rm -rf mit einem Glob verwenden. Diese haben kein Rückgängig. Benannte Pfade einzeln löschen.
• git branch -D, git stash drop und git worktree remove --force werden nur für das einzelne Element ausgeführt, das der Besitzer genehmigt hat, nachdem gezeigt wurde, was verloren geht (Commits, Diff-Stat). Notieren Sie den Branch-Tip-SHA im Bericht, damit er wiederhergestellt werden kann.
• Niemals .env-Dateien, Schlüssel oder Zugangsdaten lesen, ausgeben, verschieben oder löschen, selbst wenn sie wie Müll aussehen. Melden Sie sie nur mit Pfad.
• Bleiben Sie innerhalb dieses Repos. Worktrees anderer Apps, losgelöste Checkouts oder gemeinsame /tmp-Ordner werden gemeldet, nicht berührt. Niemals glob-löschen in /tmp.
• Niemals harness_do_not_kill-Prozesse oder den Claude-Prozess selbst töten.

Wenn der Lanes-Harness vorhanden ist

Nur wenn der LANES-Abschnitt ein Statusverzeichnis zeigt. Andernfalls diesen Block überspringen.

• Entfernen Sie Lane-Worktrees, Lane-Temp-Verzeichnisse, Relay-Job-Verzeichnisse und lanes.tsv-Zeilen mit dem eigenen Skript des Harness, niemals mit rm: bash ~/.claude/skills/lanes/lane/cleanup.sh <lane-verz> <branch> für eine gemergte Lane, dann bash ~/.claude/skills/lanes/lane/cleanup.sh --sweep. Führen Sie es vom Haupt-Worktree aus aus.
• WORKTREE_MISSING- und BRANCH_MERGED-Zeilen durchlaufen den Sweep. Zeilen für ungemergte Lanes sind ASK.
• Noch laufende Relay-Jobs (keine rc-Datei) sind NUR MELDEN; der Lanes-Watchdog besitzt sie.
• In einer /lanes-Session integriert die Haupt-Lane; löschen Sie keinen Lane-Branch, dessen Arbeit noch nicht in origin/main gemergt ist.

Ohne Harness folgen Worktrees unter .claude/worktrees/ (z. B. von Claude Codes EnterWorktree) den oben genannten einfachen Git-Regeln.

Phase 3: Bericht

Verwenden Sie genau diese Struktur. Halten Sie sie überfliegbar; der Besitzer liest sie am Ende einer langen Session.

## Session-Cleanup

**Bereits sauber:** working tree, sync, worktrees, branches, stashes, processes, artifacts, tracker, deploy
(nur die Bereiche auflisten, die bestanden haben)

**Bereinigt**
- `feat/login-form` Branch: in main gemergt bei a1b2c3d, 0 Commits voraus. Gelöscht mit `git branch -d` (wiederherstellbar: `git branch feat/login-form a1b2c3d`).
- `python3 -m http.server 3000` (PID 170308): von dieser Session für die Vorschau gestartet, untätig. Gestoppt.
- `.next/types` (1,2 MB): gitignored, wird beim Build neu generiert.

**Benötigt Ihre Entscheidung**
- `feat/wip` Branch: 1 Commit nicht in main („wip: draft parser“), letzter Commit vor 2h, verknüpfte Aufgabe bd-42 in_progress.
  Fortsetzen (behalten) oder aufgeben (`git branch -D feat/wip`)?
- `stash@{0}` „On main: sc test stash“, 5 Tage alt. Anwenden oder löschen?

**Nur Meldung**
- main ist 2 Commits ahead von origin/main (nicht gepusht). Push empfohlen.
- Produktions-Deploy: unverified (vercel CLI nicht eingeloggt).

**Nächste Schritte**
- Führen Sie `git worktree list` aus, erwarten Sie nur den Haupt-Worktree.
- Führen Sie `git status --short` aus, erwarten Sie keine Ausgabe.

Regeln für den Bericht:

• Jede „Bereinigt“-Zeile sagt, was es war, seine Größe (bei Dateien und Ordnern) und warum es sicher war. Fügen Sie bei Branches den Tip-SHA hinzu, damit er wiederhergestellt werden kann.
• Jeder „Benötigt Ihre Entscheidung“-Eintrag enthält die Fakten, die für die Entscheidung nötig sind (Alter, Commit-Anzahl, Commit-Betreffe, verknüpfte Aufgabe) und zwei konkrete Optionen.
• Sagen Sie niemals, dass ein Bereich sauber ist, es sei denn, die Prüfung oder ein Befehl in dieser Session hat es gezeigt. Wenn eine Prüfung übersprungen wurde (offline, CLI fehlt, keine Berechtigung), sagen Sie dies unter „Nur Meldung“.
• Nächste Schritte enthalten immer mindestens einen Verifikationsbefehl mit seiner erwarteten Ausgabe.

Nachdem der Besitzer die ASK-Punkte beantwortet hat, führen Sie genau das aus, was er genehmigt hat, führen Sie den relevanten Prüfabschnitt erneut aus und melden Sie das Ergebnis.

Protokollierung

Wenn das Repo einen Session-Log-Ordner hat (SESSION_LOG zeigt _sessions/ oder ähnliches), fügen Sie einen kurzen Cleanup-Eintrag an: Datum, was bereinigt wurde, was auf den Besitzer wartet. Committen Sie ihn nur, wenn die Projektregeln das Committen von Session-Logs erlauben; prüfen Sie CLAUDE.md oder den Ignorier-Status des Ordners (ignored=yes bedeutet nicht committen).

Nicht im Aufgabenbereich

Refactoring, Lint-Fixes, Dead-Code-Entfernung und Abhängigkeits-Upgrades. Wenn Sie sie bemerken, notieren Sie sie als Backlog-Elemente (Speicher oder Tracker) und erwähnen Sie sie in einer Zeile. Pushen, Pullen und Deployen sind ebenfalls nicht im Aufgabenbereich: empfehlen Sie sie, führen Sie sie nicht aus.