session-exit-classification-runbook.md Raw History Folder

Session Exit Classification Runbook

This runbook classifies browser sessions using existing P0 marker files in the log directory:

session_<id>.startup.marker
session_<id>.shutdown.marker
session_<id>.abrupt.marker

Marker directory (default):

LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dumber/logs"

Crash report directory (auto-generated on startup when abrupt exits are detected):

CRASH_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dumber/logs/crashes"

Classification Model

clean_exit (marker-confirmed)
- shutdown.marker is present.
main_process_crash_or_abrupt (marker-confirmed)
- abrupt.marker is present and no shutdown.marker exists.
external_kill_or_oom_inferred (best-effort)
- startup.marker exists, but shutdown.marker and abrupt.marker are both missing.
- This is explicitly inferred, not confirmed.

Implementation path in code:

internal/bootstrap/session_exit_classification.go
- ClassifySessionExitFromMarkers(lockDir, sessionID)
- BuildSessionExitReport(lockDir)

Quick Marker Report (Shell)

LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dumber/logs"

for startup in "$LOG_DIR"/session_*.startup.marker; do
  [ -e "$startup" ] || continue
  base="$(basename "$startup")"
  sid="${base#session_}"
  sid="${sid%.startup.marker}"
  shutdown="$LOG_DIR/session_${sid}.shutdown.marker"
  abrupt="$LOG_DIR/session_${sid}.abrupt.marker"

  if [ -f "$shutdown" ]; then
    class="clean_exit"
    inf="marker-confirmed"
  elif [ -f "$abrupt" ]; then
    class="main_process_crash_or_abrupt"
    inf="marker-confirmed"
  else
    class="external_kill_or_oom_inferred"
    inf="best-effort"
  fi

  printf "%s\t%s\t%s\n" "$sid" "$class" "$inf"
done | sort

Optional System-Log Correlation

Use this only when external_kill_or_oom_inferred needs more evidence.

Get the startup timestamp for a session:

SID="<session-id>"
LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dumber/logs"
cat "$LOG_DIR/session_${SID}.startup.marker"

Inspect user journal around that window:

journalctl --user --since "2026-02-07 10:00:00" --until "2026-02-07 10:10:00" | rg -i "dumber|killed|oom|sigkill|signal"

Inspect kernel/system OOM evidence:

journalctl -k --since "2026-02-07 10:00:00" --until "2026-02-07 10:10:00" | rg -i "oom|out of memory|killed process"

Optional coredump check:

coredumpctl list | rg -i "dumber"

Print GitHub-ready issue payload from generated report:

dumber crashes issue latest

Interpretation guidance:

OOM/killed lines near the startup window strengthen external_kill_or_oom_inferred.
No OOM evidence does not prove a clean exit; keep inference label explicit.

source

1# Session Exit Classification Runbook
2
3This runbook classifies browser sessions using existing P0 marker files in the log directory:
4
5- `session_<id>.startup.marker`
6- `session_<id>.shutdown.marker`
7- `session_<id>.abrupt.marker`
8
9Marker directory (default):
10
11```bash
12LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dumber/logs"
13```
14
15Crash report directory (auto-generated on startup when abrupt exits are detected):
16
17```bash
18CRASH_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dumber/logs/crashes"
19```
20
21## Classification Model
22
23- `clean_exit` (`marker-confirmed`)
24  - `shutdown.marker` is present.
25- `main_process_crash_or_abrupt` (`marker-confirmed`)
26  - `abrupt.marker` is present and no `shutdown.marker` exists.
27- `external_kill_or_oom_inferred` (`best-effort`)
28  - `startup.marker` exists, but `shutdown.marker` and `abrupt.marker` are both missing.
29  - This is explicitly inferred, not confirmed.
30
31Implementation path in code:
32
33- `internal/bootstrap/session_exit_classification.go`
34  - `ClassifySessionExitFromMarkers(lockDir, sessionID)`
35  - `BuildSessionExitReport(lockDir)`
36
37## Quick Marker Report (Shell)
38
39```bash
40LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dumber/logs"
41
42for startup in "$LOG_DIR"/session_*.startup.marker; do
43  [ -e "$startup" ] || continue
44  base="$(basename "$startup")"
45  sid="${base#session_}"
46  sid="${sid%.startup.marker}"
47  shutdown="$LOG_DIR/session_${sid}.shutdown.marker"
48  abrupt="$LOG_DIR/session_${sid}.abrupt.marker"
49
50  if [ -f "$shutdown" ]; then
51    class="clean_exit"
52    inf="marker-confirmed"
53  elif [ -f "$abrupt" ]; then
54    class="main_process_crash_or_abrupt"
55    inf="marker-confirmed"
56  else
57    class="external_kill_or_oom_inferred"
58    inf="best-effort"
59  fi
60
61  printf "%s\t%s\t%s\n" "$sid" "$class" "$inf"
62done | sort
63```
64
65## Optional System-Log Correlation
66
67Use this only when `external_kill_or_oom_inferred` needs more evidence.
68
691. Get the startup timestamp for a session:
70
71```bash
72SID="<session-id>"
73LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dumber/logs"
74cat "$LOG_DIR/session_${SID}.startup.marker"
75```
76
772. Inspect user journal around that window:
78
79```bash
80journalctl --user --since "2026-02-07 10:00:00" --until "2026-02-07 10:10:00" | rg -i "dumber|killed|oom|sigkill|signal"
81```
82
833. Inspect kernel/system OOM evidence:
84
85```bash
86journalctl -k --since "2026-02-07 10:00:00" --until "2026-02-07 10:10:00" | rg -i "oom|out of memory|killed process"
87```
88
894. Optional coredump check:
90
91```bash
92coredumpctl list | rg -i "dumber"
93```
94
955. Print GitHub-ready issue payload from generated report:
96
97```bash
98dumber crashes issue latest
99```
100
101Interpretation guidance:
102
103- OOM/killed lines near the startup window strengthen `external_kill_or_oom_inferred`.
104- No OOM evidence does not prove a clean exit; keep inference label explicit.