# Vận hành: máy, hàng chờ, lệnh, sự cố, cách làm việc với người dùng

## Cập nhật 2026-11-07: metric và queue nested

- Metric hiện hành do người dùng cung cấp là `κ=max(0,2·Acc−1)` và `H=2·κ·L/(κ+L)`, cửa sổ switch có điểm cuối là switch tiếp theo. Xem `CONTEXT_3_RULES.md` mục 4; các CSV/JSON H cũ không tự cập nhật.
- Scorer mới: `experiments/decoder_lodo/scorer_kappa_next_inclusive.py`; kiểm tra bằng `../../.venv/bin/python test_scorer_kappa_next_inclusive.py` từ thư mục `experiments/decoder_lodo`. Scorer này tạm thời cho phép sustain vượt điểm cuối tìm kiếm nhưng không vượt trial; cần đối chiếu scorer BTC. Không ghi đè `reports/eda_full/scripts/scorer.py`, vì các kết quả lịch sử phụ thuộc bản cũ.
- Job chấm lại: `rescore_kappa_next_inclusive.py --ensemble two --standalone` xuất `results/research/bmms3_enhanced_ensemble_2seed_kappa_next_inclusive.csv` và `bmms3_vs_direct_kappa_next_inclusive.csv`. Bản `--ensemble four` xuất `bmms3_enhanced_ensemble_4seed_kappa_next_inclusive.csv`. Các file không có `inclusive` là lần thử trước, không dùng làm kết quả chốt. Đối chiếu stdout/exit code trước khi dùng file partial.
- Trong `eeg_nested`, dùng `JOBQUEUE_NAMESPACE=nested python runners/jobqueue.py status` và `logs/jobqueue_nested.log`; state ở `runners/jobs_nested/`. Tại thời điểm cập nhật, job `380a` đang chấm theo biên độc quyền cũ; `380b` chờ chấm lại theo biên bao gồm, rồi seed BMMS 3 và các fold/evaluation còn lại chờ tuần tự. Đây chỉ là snapshot; kiểm tra lại trước khi báo. Không can thiệp tiến trình khác hoặc khởi động lại scheduler khi có job đang chạy.
- `bmms_3feature_runner.py` với `SCORE_KAPPA_NEXT=1` chấm các job seed mới bằng scorer inclusive và ghi `evaluation_metric_version`; các JSON cũ s0/s1 vẫn metric cũ. Job `387_bmms3_mix_4seed` đã trỏ tới scorer inclusive. Ensemble giữ emission gốc và thang BMMS cố định; chưa có nested cross-fitting riêng cho nhánh BMMS và chưa hoàn tất leakage test đầu-cuối.

- **Scheduler mặc định đã ngừng** (khoảng 13:00 UTC 03/11; chỉ còn scheduler `nested`, PID lúc 07/11 là 1024374, `--max-jobs 1`). `runners/jobs/running/` còn ghi `78100_lpftcbramod_dec_s0`, `78110_lpftcbramod_dec_s1` nhưng cả hai đã xong (log 13:29 và 14:57 ngày 03/11). `runners/jobs/pending/` còn `7900_stimpt_USTC`, `79100`–`79111` (H1, chờ USTC) và `79200_antisym_transformer`: không chạy cho đến khi có scheduler mặc định. Khởi động lại chỉ khi người dùng đồng ý, và không khi đang có job nặng của queue khác.
- Script mới 03–07/11 (thư mục `experiments/decoder_lodo/`): `nested_stack_base.py`, `nested_stack_decoder.py`, `nested_stack_fusion.py`, `nested_schedule_generate.py`, `nested_schedule_eval.py`, `switch_rate_aux_experiment.py`, `masked_rate_experiment.py`, `rate_aux_baseline_ensemble.py`, `learn_rate_mix.py`, `recipe_transformer_ensemble.py`, `recipe_transformer_proxy_zero.py`, `audit_*.py`, `antisym_transformer_experiment.py`, `runners/run_baseline_recipe_seed.sh`, `bmms_env_*`, `bmms_enhanced_*`, `bmms_3feature_*`, `bmms3_enhanced_mix_score.py`, `bmms3_enhanced_4seed_mix_score.py`, `score_bmms3_vs_direct.py`, `stimulus_only_runner.py`, `direct_env_runner.py`, `scorer_kappa_next*.py`, `rescore_kappa_next*.py`. Mô hình nền tảng: `fm_models/`, `fm_input.py`, `fm_embed.py`, `fm_screen.py`, `fm_pretrain_stim.py`, `dump_g.py`; thư viện phụ cho BIOT cài riêng ở `experiments/external_data/foundation_models/pydeps` (không đụng `.venv`).
- Trọng số fold decoder không được lưu (`run_experiment.py`); vì vậy leakage test đầu-cuối cho các stack phải train lại hoặc thêm lưu trọng số.

## 1. Cách người dùng muốn làm việc

| Điều | Chi tiết |
|---|---|
| Ngôn ngữ | luôn trả lời bằng tiếng Việt, kể cả khi người dùng viết tiếng Anh; giữ thuật ngữ như LODO, HMM, SDT, H |
| Không ngồi chờ | khởi động job, nói xem log ở đâu và mất bao lâu, rồi kết thúc lượt; chỉ kiểm tra khi được hỏi ("check tien do") |
| Số seed | thí nghiệm mới chạy ít nhất 2 seed |
| Job nặng | luôn qua hàng chờ |
| Git | commit thay đổi mã trong `experiments/`, cuối message có dòng `Co-Authored-By` theo hướng dẫn của phiên |
| Kiểu yêu cầu | ngắn, không dấu, thường là "check tien do", "chay ... di", "them ... di"; khi nói "làm hết đi" nghĩa là cứ tiến hành |
| Hẹn giờ | khi máy chật, người dùng yêu cầu hẹn job chạy lúc 7:00 sáng giờ Việt Nam (00:00 UTC) |

## 2. Máy

- 24 GB RAM, **không có swap**, 8 nhân CPU, GPU 32 GB. RAM là giới hạn, không phải VRAM.
- Mỗi tiến trình train chiếm 2,5–4 GB RAM.
- **Máy dùng chung.** Người khác chạy việc riêng dưới cùng tài khoản root (đã thấy: `train_suite27.py` trong
  `/root/disk_3tb/earlywarning`, `train.py --tag frame_asd_...`, script trong `/root/thao`, server Cursor / Lingma /
  VSCode), có lúc chiếm tới 20 GB. **Không được đụng vào các tiến trình đó.**
- Đồng hồ máy là UTC; giờ Việt Nam = UTC + 7.

## 3. Hàng chờ job

Thư mục làm việc: `experiments/decoder_lodo`. Python của dự án: `../../.venv/bin/python` (python hệ thống thiếu thư viện).

```bash
python runners/jobqueue.py add TEN -- "LENH ..."     # thêm job; job chờ khởi động theo thứ tự tên
python runners/jobqueue.py status                    # pending / running / done / failed, tải, GPU, RAM trống
```

- Trạng thái nằm ở `runners/jobs/{pending,running,done,failed,held}/TEN.json`; đầu ra ở `logs/jobs/TEN.log`; nhật ký của
  bộ xếp hàng ở `logs/jobqueue.log`.
- Bộ xếp hàng chạy trong tmux, phiên `decoder_lodo`, cửa sổ `jobq`, với
  `--max-jobs 3 --max-load 11 --min-gpu-free-gb 6 --min-ram-free-gb 6 --score-jobs 3`.
- Nó chỉ khởi động job mới khi còn ít nhất 6 GB RAM trống. Việc kiểm tra chỉ diễn ra lúc khởi động, nên job đang chạy
  vẫn có thể bị kill nếu người khác chiếm thêm RAM sau đó.
- **Đổi thứ tự ưu tiên**: đổi tên file trong `pending/` (và trường `name` bên trong) để nó xếp trước.
- **Job phụ thuộc job khác**: dùng vòng `until [ -f results/X.json ]; do sleep 60; done` ở đầu lệnh. Job đang chờ kiểu
  này vẫn chiếm một trong ba chỗ.

### Xử lý sự cố

| Tình huống | Cách xử lý |
|---|---|
| Job hỏng với mã 137 | hệ điều hành kill vì hết RAM; chuyển file JSON từ `failed/` về `pending/` (bỏ các trường `started`, `finished`, `returncode`); các fold đã xong được dùng lại |
| Job hỏng với mã 143 | nhận tín hiệu dừng từ bên ngoài, nguồn chưa rõ (4 lần ngày 6/10); xử lý như trên |
| Cần khởi động lại bộ xếp hàng | chỉ làm khi `running/` trống, vì khi khởi động nó đưa mọi job "đang chạy" về hàng chờ và sẽ chạy trùng; giữ job chờ bằng cách chuyển sang `held/`; Ctrl-C trong cửa sổ `jobq` làm đóng cửa sổ, nên tạo lại bằng `tmux new-window -d -t decoder_lodo -n jobq -c "$PWD" "bash -c '... jobqueue.py run ...; exec bash'"` |
| Hẹn giờ | chuyển job sang `held/`, tạo cửa sổ tmux `release` chạy `sleep N; mv runners/jobs/held/*.json runners/jobs/pending/` |
| Dừng job của mình | kill theo PID cụ thể (lấy cây tiến trình con của bộ xếp hàng bằng `pgrep -P`) |

### Những lỗi Claude đã mắc, cần tránh

- **Không dùng `pkill -f` / `pgrep -f` rồi kill theo tên script.** Lệnh bọc `bash -c` của hàng chờ cũng khớp, và có lần
  đã kill cả shell của chính mình. Ngày 6/10, một lệnh `grep` theo chuỗi con đã khớp nhầm hai job và dừng oan job ghép.
- **Không chạy thêm tiến trình nặng ngoài hàng chờ.** Ngày 4/10 chạy thêm 7 tiến trình trong tmux làm một job bị kill.
- **Không dùng `sleep` dài ở tiền cảnh**; dùng vòng `until` có `timeout` ngắn nếu cần chờ một điều kiện.
- Job nhẹ (chỉ ghép và chấm trên evidence đã lưu, vài phút, khoảng 1–2 GB) có thể chạy trực tiếp khi RAM còn nhiều.

## 4. Cấu trúc thư mục cần biết

| Đường dẫn | Nội dung |
|---|---|
| `data/` | dữ liệu cuộc thi; chỉ đọc |
| `experiments/` | repo git cục bộ (chỉ mã, cấu hình, JSON kết quả); gốc repo `EEG-sAAD-...` không phải repo git |
| `experiments/decoder_lodo/` | toàn bộ benchmark và phương pháp |
| `experiments/decoder_lodo/cache/<prep>/` | dữ liệu đã tiền xử lý theo từng kiểu (mỗi kiểu khoảng 2 GB) |
| `experiments/decoder_lodo/folds/<exp>/<DS>.pkl` | evidence của từng fold (đầu vào của bước ghép); trọng số mô hình fold **không** được lưu |
| `experiments/decoder_lodo/results/<exp>.json` | điểm của từng thí nghiệm; `results/research/*.csv` cho các phân tích |
| `experiments/decoder_lodo/models/` | mô hình pretrain (`pretrain_spk_*`) và mô hình train trên cả 5 dataset (`all5_direct_clf*`) |
| `experiments/external_data/` | Fuglsang, SparrKULee, AASD, Carta, Broderick và script chuyển đổi |
| `reports/eda_full/scripts/` | `common.py`, `scorer.py`, `e1_switch.py` (HMM, đóng nhãn, chuyển chú ý tổng hợp) |
| `docs_challenge/` | bản sao luật cuộc thi |
| `EEG-sAAD Data Story.html` | **không đọc nguyên file** (rất lớn) |

Quy ước tên thí nghiệm: `<bộ giải mã>__<prep><tag>`, hậu tố `_s1`, `_s2`, `_s3` cho seed (seed 0 không có hậu tố).

## 5. Lệnh hay dùng

```bash
cd experiments/decoder_lodo; PY=../../.venv/bin/python; P=eaP_n5_t60

# decoder (GLIMPSE_THR=norm), seed S
GLIMPSE_THR=norm $PY run_experiment.py --decoder vlaai_ws --prep $P --aug-variant cluster --extra-train Fuglsang2020 \
  --targets env,onset,dom --init-from models/pretrain_spk_vlaai_ws_sS.pt --evidence-weights lda \
  --tag _aug_cluster_onset_dom_xFUG_ptSPK_sS --train-seed S

# bộ phân loại 10 s 3 khối (GLIMPSE_THR=onorm), seed S
GLIMPSE_THR=onorm $PY direct_classifier.py --prep $P --window-s 10 --set model_blocks=3 \
  --init-from models/pretrain_spk_direct_clf_w10_b3_sS.pt --min-epochs 10 --train-seed S --tag _w10b3_ptSPK_sS

# ghép và chấm trên LODO (kết quả nối vào results/research/fuse_general.csv)
$PY fuse_general.py --dec D D_s1 ... --clf W W_s1 ... --a 0.3 0.5 0.7 --pstay 0.998 0.9997 --name "nhãn"

# chuyển chú ý thật: train trên cả 5 dataset rồi chạy trên AASD, Carta
GLIMPSE_THR=norm $PY eval_external.py --seed S --prep $P --dataset AASD,Carta2026 --targets env,onset,dom \
  --extra-train Fuglsang2020 --init-from models/pretrain_spk_vlaai_ws_sS.pt --evidence-weights lda --ref D_sS --tag _bestP
GLIMPSE_THR=norm $PY eval_external_clf.py --seed S --prep $P --window-s 10 --set model_blocks=3 \
  --init-from models/pretrain_spk_direct_clf_w10_b3_sS.pt --ref W_sS --tag _w10b3P
$PY fuse_external.py --dec-tag _bestP --dec D:0 D_s1:1 ... --clf W:_w10b3P:0 W_s1:_w10b3P:1 ...

# kiểm tra lookahead; bảng dò siêu tham số
GLIMPSE_THR=norm $PY leakage_test.py
$PY hp_summary.py
```

Ghi đè siêu tham số: `--set khoá=giá_trị` (ví dụ `lr=0.0002`, `model_blocks=3`, `model_kernels=128`, `model_dropout=0.1`)
và `--aug-set khoá=giá_trị` (ví dụ `noise=0.2`, `p_cluster=0.5`, `clf_lag_jitter=2`, `clf_p_feat_drop=0.2`, `clf_p_switch2=0.5`).

`GLIMPSE_THR` chọn bộ đệm chứa tín hiệu `dom`: decoder dùng `norm`, bộ phân loại dùng `onorm` (cả hai có cùng `dom`);
dữ liệu ngoài AASD và Carta chỉ có `norm`.

## 6. Thời gian chạy điển hình (khi máy rảnh)

| Việc | Thời gian |
|---|---|
| Decoder, 5 fold | khoảng 25 phút |
| Bộ phân loại 5 s, 5 fold | khoảng 60 phút |
| Bộ phân loại 10 s, 5 fold | khoảng 70 phút |
| Pretrain bộ phân loại trên SparrKULee | khoảng 16 phút |
| Train một mô hình trên cả 5 dataset (cho dữ liệu thật) | decoder 10–15 phút, bộ phân loại 20–30 phút |
| Ghép và chấm | 3–10 phút |
| Tạo dữ liệu cho một kiểu tiền xử lý mới | vài phút |

## 7. Bộ nhớ lâu dài của Claude

Thư mục `/root/.claude/projects/-root-disk-3tb-EEG-sAAD-Grand-Challenge-Training-Dataset/memory/`: mỗi file một chủ đề,
`MEMORY.md` là mục lục được nạp ở đầu mỗi phiên. Bản sao tại thời điểm viết tài liệu này là các file `CONTEXT_MEMORY_*.md`
ở gốc repo.

## 8. Cập nhật 2026-10-28: script và job mới

- `experiments/decoder_lodo/`: `eval_stem_external.py` (stem_ms96 trên switch thật), `clf_reschedule.py` + `schedule_noise_score.py`
  (nhiễu lịch; biến môi trường `SCHEDULE_OFFSET`, `SAVE_FOLD_WEIGHTS=1`), `hmm_real_crossfit.py`, `hmm_gated.py`; `eval_external_clf.py
  --train-ext AASD|Carta2026` (A1–A4); `direct_classifier.py --extra-real AASD,Carta2026` (LODO có dữ liệu thật) và các khóa tăng
  cường `clf_real_frac`, `clf_real_straddle`, `clf_real_synth`, `clf_real_lag`, `clf_real_soft`, `--set aux_sw=1 aux_lambda=0.5`.
- Tên job: `5010_schednoise_*`, `5100/5101_a1_*`, `52xx_a2_*`, `53xx_a3_*`, `5400_a4_*`, `5500_lodo_xreal_*`. Kết quả A*:
  `results/research/ext_clf_<DS>_<tag>_s<seed>.json` (+ `_evidence_s<seed>.pkl`), log `logs/a*_*.log`.
- Scheduler tmux `decoder_lodo:jobq` được khởi động lại ngày 23/10 với `--max-jobs 3 --max-load 11 --min-gpu-free-gb 6
  --min-ram-free-gb 6`. Job bị kill bởi thiếu RAM (mã 137) thì đưa JSON từ `failed/` về `pending/`.
- Quy tắc làm việc: báo cáo mọi thí nghiệm đủ switch thật và synthetic, cùng seed, kèm mức nhiễu; người dùng quyết định giữ hay bỏ;
  không dùng tham số hay FLOPs làm tiêu chí; bỏ qua các tiền xử lý chỉ được "cho phép" là hợp lệ.
- Mã từ file ngoài (zip) không được chạy hoặc nạp pickle; `.pt` nạp bằng `weights_only=True` với danh sách cho phép kiểu numpy.
