[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7FCZ8R856QEP8AZC2FD3M6W":3,"skill-same:01M7FCZ8R856QEP8AZC2FD3M6W":58},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7FCZ8R856QEP8AZC2FD3M6W","experiment-queue",null,"SSH job queue for multi-seed\u002Fmulti-config ML experiments with OOM-aware retry, stale-screen cleanup, and wave-transition race prevention. Use when user says \"batch experiments\", \"队列实验\", \"run grid\", \"multi-seed sweep\", \"auto-chain experiments\", or when \u002Frun-experiment is insufficient for 10+ jobs that need orchestration.","CZX-LBJ\u002Fdeepseek-science","CZX-LBJ","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F204594689?v=4","01M7FC59WQ9PFXT04MKGJDCFFT","czx","01M7FC59XB2GW0BKWN9JTDBQS7",1,"MIT","https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Faris\u002Fskills\u002Fexperiment-queue\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: experiment-queue\ndescription: SSH job queue for multi-seed\u002Fmulti-config ML experiments with OOM-aware retry, stale-screen cleanup, and wave-transition race prevention. Use when user says \"batch experiments\", \"队列实验\", \"run grid\", \"multi-seed sweep\", \"auto-chain experiments\", or when \u002Frun-experiment is insufficient for 10+ jobs that need orchestration.\nargument-hint: \"[manifest-or-grid-spec]\"\nallowed-tools: Bash(*), Read, Grep, Glob, Edit, Write, Skill(run-experiment), Skill(monitor-experiment)\n---\n\n# Experiment Queue\n\n> ⏱ **External cadence: visibility only.** This skill already runs its own\n> detached server-side scheduler (60s poll + `depends_on` + wave transitions).\n> Use its status output for overnight visibility (N done \u002F N running \u002F N\n> pending); do **not** wrap it in a second `\u002Floop` \u002F `CronCreate` poll — that\n> duplicates the scheduler on an uncoordinated clock and races the\n> wave-transition logic it was built to prevent. See\n> [`shared-references\u002Fexternal-cadence.md`](..\u002Fshared-references\u002Fexternal-cadence.md)\n> (\"don't duplicate an existing scheduler\").\n\nOrchestrate large batches of ML experiments on SSH remote GPU servers with proper state tracking, OOM retry, stale cleanup, and wave transitions.\n\n## When to Use This Skill\n\nUse when `\u002Frun-experiment` is insufficient:\n- **≥10 jobs** that need batching across GPUs\n- **Multi-seed sweeps** (e.g., 21 seeds × 12 cells)\n- **Wave transitions** (run wave 1, wait, run wave 2, wait, run wave 3...)\n- **Teacher+student chains** (train teacher then distill; auto-trigger student after teacher done)\n- **OOM-prone configs** where you need to retry with different GPU or wait\n- **Mixed seed grids** where failed cells need re-running\n\nDo NOT use for:\n- Single ad-hoc experiment (use `\u002Frun-experiment`)\n- Modal\u002FVast.ai deployments (those have their own orchestration)\n- Experiments that need manual inspection between runs\n\n## Why This Exists\n\nBased on session audit (2026-04-16), the major wall-clock sinks in multi-seed grid experiments are:\n\n1. **Stale screens** — python finishes, wandb uploads, screen hangs, next wave blocked\n2. **OOM on shared GPU** — previous job's memory not yet released\n3. **Wave race** — new wave launches before previous wave fully settles\n4. **Missing checkpoints** — student launches before teacher saved\n5. **Parser duplication** — rewriting multi-seed analysis python every batch\n\nAll of these are pure engineering friction that can be orchestrated.\n\n## Core Concepts\n\n> **Environment contract**: queue jobs assume the target env is already built\n> and validated per `..\u002Fshared-references\u002Fcompute-env-contract.md` (spec-hash\n> ledger + kernel witness). A wave of jobs dying at import time = the env\n> contract was skipped, not a queue bug; check the provider's\n> `.aris\u002Fcompute\u002F\u003Cprovider>.md` ledger before re-queueing.\n\n### Job Manifest\n\nA manifest lists jobs with explicit state:\n\n```yaml\nproject: my_grid_experiment\ncwd: \u002Fhome\u002Fuser\u002Fyour_project\nconda: my_env\n# Optional: override conda hook path if conda is not at a standard location.\n# Can be a bare path (wrapped automatically) or a full `eval \"$(... shell.bash hook)\"` string.\n# Falls back to auto-detect of ~\u002Fanaconda3, ~\u002Fminiconda3, \u002Fopt\u002Fanaconda3, etc.,\n# or the ARIS_CONDA_HOOK environment variable.\n# conda_hook: \u002Fcustom\u002Fpath\u002Fto\u002Fconda\nssh: gpu-server\ndefault_cmd: >\n  python run_distill.py --backbone softmax --lam 0.5\n  --K 500 --L 96 --W 16 --n_steps 30000 --batch_size 128 --lr 1e-4\n\npreconditions:\n  - type: checkpoint_exists\n    path: checkpoints\u002Ftransformer\u002Fteacher_L96_K500_N{N}.pt\n\ngpus: [0, 1, 2, 3, 4, 5, 6, 7]\nmax_parallel: 8\ngpu_free_threshold_mib: 500  # optional, default 500; raise for shared servers, lower for tight packing\noom_retry:\n  delay: 120\n  max_attempts: 3\n\njobs:\n  - id: s200_N64_n50K\n    args: {seed: 200, n_hidden: 64, n_train_subset: 50000, subset_seed: 2024}\n  - id: s200_N128_n50K\n    args: {seed: 200, n_hidden: 128, n_train_subset: 50000, subset_seed: 2024}\n  # ... 14 more\n```\n\n### Job State Machine\n\n```\npending → running → completed\n                 ↘ failed_oom → pending (after delay) [retry up to N]\n                 ↘ failed_other → stuck (needs manual inspection)\nstale screen (process gone, screen lingering) → failed_other → stuck\n```\n\n> **Operator note on `stuck` (the agent's move, not the queue's):** the queue\n> deterministically parks `failed_other` jobs as `stuck` — that part is code and\n> unchanged. Before handing a `stuck` batch to the human, the OPERATING AGENT\n> should check: if the same failure repeats across jobs, try ONE clean\n> reimplement of the **agent-generated wrapper\u002Fattempt script only** — never\n> user\u002Fproject source (`run_*.py` you didn't write), the manifest, queue state,\n> logs, or results (see `shared-references\u002Fexternal-cadence.md` § *Let a broken\n> attempt restart, not just patch*). Reserve the human handoff for\n> contract\u002Fenvironment doubts, not merely broken attempt code.\n\n### Wave Orchestration\n\nA \"wave\" is a batch of jobs that fit available GPUs. Next wave only starts when:\n1. All current-wave python processes have exited\n2. No stale screens remain for current-wave tags\n3. GPU memory has dropped below threshold (≤500 MiB)\n4. Precondition checks pass for next-wave jobs\n\n## Workflow\n\n### Step 1: Parse Manifest \u002F Build from Grid\n\nInput can be:\n- **YAML manifest** (explicit job list, recommended for complex cases)\n- **Grid spec** (Cartesian product of param values, e.g., `N=[64,128,256] × n=[50K,150K,500K,652K]`)\n- **Natural language description** (Claude parses into manifest)\n\nBind the run identifiers once so every later step (manifest save, scp, launch, monitor, resume) refers to the same paths. Set these as local shell variables before generating the manifest:\n\n```bash\n# REPLACE the placeholder path before running, or pre-export PROJECT_DIR:\nPROJECT_DIR=\"${PROJECT_DIR:?set PROJECT_DIR to the local project root}\"\nRUN_TS=$(date -u +%Y%m%dT%H%M%SZ)             # one timestamp per run, reused everywhere\nLOCAL_RUN_DIR=\"$PROJECT_DIR\u002Fexperiment_queue\u002F$RUN_TS\"\nmkdir -p \"$LOCAL_RUN_DIR\"\n```\n\nSave the built manifest to `$LOCAL_RUN_DIR\u002Fmanifest.json` for reproducibility.\n\n### Step 2: Pre-flight\n\n- Check SSH connection works\n- Check conda env exists on remote\n- Check `cwd` exists on remote\n- Check all preconditions (checkpoints, input files)\n- Check GPU availability (at least `max_parallel` free GPUs)\n\nIf any precondition fails, show user which jobs are blocked and why.\n\n### Step 3: Launch Scheduler\n\nThe canonical scheduler implementation lives in `skills\u002Fexperiment-queue\u002Fscripts\u002Fqueue_manager.py` (Phase 3.3 move, Arch C). `tools\u002Fexperiment_queue\u002Fqueue_manager.py` is now a Python `os.execv` shim retained for legacy resolver-chain compatibility. Three preliminaries before launch.\n\n**3a. Resolve the local helper directory.** The two helpers (`queue_manager.py`, `build_manifest.py`) now sit under `skills\u002Fexperiment-queue\u002Fscripts\u002F` in the ARIS repo, with shims at `tools\u002Fexperiment_queue\u002F` for legacy resolver layers. Use this hybrid chain so the skill works from any project layout:\n\n```bash\n# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).\nQUEUE_TOOLS=\"\"\nif [ -n \"${CLAUDE_SKILL_DIR:-}\" ] && [ -f \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fqueue_manager.py\" ]; then\n  QUEUE_TOOLS=\"$CLAUDE_SKILL_DIR\u002Fscripts\"\nfi\n# Layers 1-4: legacy chain via tools\u002Fexperiment_queue\u002F shims.\nif [ -z \"$QUEUE_TOOLS\" ]; then\n  cd \"$(git rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)\" || exit 1\n  if [ -z \"${ARIS_REPO:-}\" ] && [ -f .aris\u002Finstalled-skills.txt ]; then\n      ARIS_REPO=$(awk -F'\\t' '$1==\"repo_root\"{print $2; exit}' .aris\u002Finstalled-skills.txt 2>\u002Fdev\u002Fnull) || true\n  fi\n  if [ -z \"${ARIS_REPO:-}\" ] && [ -f \"$HOME\u002F.aris\u002Frepo\" ]; then\n      ARIS_REPO=$(cat \"$HOME\u002F.aris\u002Frepo\" 2>\u002Fdev\u002Fnull) || true\n  fi\n  QUEUE_TOOLS=\".aris\u002Ftools\u002Fexperiment_queue\"\n  [ -f \"$QUEUE_TOOLS\u002Fqueue_manager.py\" ] || QUEUE_TOOLS=\"tools\u002Fexperiment_queue\"\n  [ -f \"$QUEUE_TOOLS\u002Fqueue_manager.py\" ] || { [ -n \"${ARIS_REPO:-}\" ] && QUEUE_TOOLS=\"$ARIS_REPO\u002Ftools\u002Fexperiment_queue\"; }\n  [ -f \"$QUEUE_TOOLS\u002Fqueue_manager.py\" ] || QUEUE_TOOLS=\"\"\nfi\n[ -z \"$QUEUE_TOOLS\" ] && { echo \"ERROR: experiment_queue helpers not found (layer 0: \\$CLAUDE_SKILL_DIR\u002Fscripts\u002F; layers 1-4: .aris\u002Ftools\u002F, tools\u002F, \\$ARIS_REPO\u002Ftools\u002F, \\$ARIS_REPO\u002Ftools\u002F via ~\u002F.aris\u002Frepo). Rerun install_aris.sh or smart_update.sh (refreshes ~\u002F.aris\u002Frepo), set ARIS_REPO, or copy the canonical scripts from \\$ARIS_REPO\u002Fskills\u002Fexperiment-queue\u002Fscripts\u002F.\" >&2; exit 1; }\n```\n\nThe `.aris\u002Ftools` symlink is set up by `install_aris.sh` (#174). Older installs without that symlink fall through to `tools\u002Fexperiment_queue` (works if invoked from inside the ARIS repo), `$ARIS_REPO\u002Ftools\u002Fexperiment_queue`, or the same path resolved via the global pointer file `~\u002F.aris\u002Frepo` (#366, for installs with no project-local manifest). After Phase 3.3, each of those legacy paths contains a Python `os.execv` shim that forwards to the canonical `skills\u002Fexperiment-queue\u002Fscripts\u002F` location, so existing users do not need to re-run anything.\n\n**3b. Compute remote paths.** Use both a remote-relative form (for `scp` destinations — modern `scp` runs in SFTP mode and does NOT reliably expand `$HOME` in destination paths) and a `$HOME`-prefixed form (for `ssh ... command` strings, where remote bash WILL expand `$HOME`):\n\n```bash\nREMOTE_RUN_REL=\".aris_queue\u002Fruns\u002F$RUN_TS\"          # for scp destinations (relative to remote home)\nREMOTE_RUN_DIR=\"\\$HOME\u002F$REMOTE_RUN_REL\"            # for ssh command strings (literal $HOME, expanded on remote)\n```\n\n**3c. Bootstrap the remote run directory and copy helpers + manifest.** Per-invocation and idempotent. Use a unique run directory rather than `\u002Ftmp` so concurrent queues do not collide and so resume-after-crash is reproducible.\n\n```bash\nssh \u003Cserver> \"mkdir -p \\\"$REMOTE_RUN_DIR\u002Flogs\\\" \\\"\\$HOME\u002F.aris_queue\\\"\"\nscp \"$QUEUE_TOOLS\u002Fqueue_manager.py\" \"$QUEUE_TOOLS\u002Fbuild_manifest.py\" \u003Cserver>:.aris_queue\u002F\nscp \"$LOCAL_RUN_DIR\u002Fmanifest.json\" \u003Cserver>:\"$REMOTE_RUN_REL\u002Fmanifest.json\"\n```\n\n**3d. Launch the scheduler as a detached `nohup` process on the SSH host:**\n\n```bash\nssh \u003Cserver> \"nohup python3 \\\"\\$HOME\u002F.aris_queue\u002Fqueue_manager.py\\\" \\\\\n  --manifest \\\"$REMOTE_RUN_DIR\u002Fmanifest.json\\\" \\\\\n  --state    \\\"$REMOTE_RUN_DIR\u002Fqueue_state.json\\\" \\\\\n  --log-dir  \\\"$REMOTE_RUN_DIR\u002Flogs\\\" \\\\\n  > \\\"$REMOTE_RUN_DIR\u002Fqueue_mgr.log\\\" 2>&1 &\"\n```\n\nNotes for callers:\n- `--log-dir` is what `queue_manager.py` actually consumes (per-job log files for OOM detection). Do NOT pass `--log \u003Cpath>` — that flag is declared but unused, and a single combined log breaks the per-job stale-screen \u002F OOM heuristics.\n- Persist `RUN_TS` \u002F `REMOTE_RUN_REL` \u002F `REMOTE_RUN_DIR` to disk so monitoring and resume can reload them without regenerating:\n\n  ```bash\n  {\n    printf 'PROJECT_DIR=%q\\n'    \"$PROJECT_DIR\"\n    printf 'RUN_TS=%q\\n'         \"$RUN_TS\"\n    printf 'LOCAL_RUN_DIR=%q\\n'  \"$LOCAL_RUN_DIR\"\n    printf 'REMOTE_RUN_REL=%q\\n' \"$REMOTE_RUN_REL\"\n    printf 'REMOTE_RUN_DIR=%q\\n' \"$REMOTE_RUN_DIR\"\n  } > \"$LOCAL_RUN_DIR\u002Frun_meta.txt\"\n  ```\n\n  `%q` shell-escapes the values so the file is safely sourceable later. Note that `REMOTE_RUN_DIR` keeps a literal `$HOME` (do not expand it locally), which is the right form for re-use inside `ssh \"...\"` strings later.\n\n**3e. Resume an existing queue (only when the user asks).** A fresh `RUN_TS` per invocation is correct for *new* queues. To resume a crashed queue, do NOT regenerate `RUN_TS` — reload the recorded values and re-run only the launch command (Step 3d), not the bootstrap (Step 3c):\n\n```bash\nLOCAL_RUN_DIR=\"\u002Fabs\u002Fpath\u002Fto\u002Fproject\u002Fexperiment_queue\u002F\u003Cexisting-run-ts>\"   # the run dir to resume\n. \"$LOCAL_RUN_DIR\u002Frun_meta.txt\"                                            # reloads PROJECT_DIR \u002F RUN_TS \u002F REMOTE_RUN_REL \u002F REMOTE_RUN_DIR\n# Then re-run Step 3d verbatim. Do NOT re-run Step 3c (would overwrite manifest.json + state.json).\n```\n\nA `queue_state.json` written before the 2026-08 scheduler fix records jobs the old code\nmis-judged as failed. Resuming it parks those jobs as `stuck` — they are not retried, so a\nstate file whose jobs are all `failed_other` finishes with nothing launched. Delete that\nstate file and re-run the manifest from Step 3c.\n\nThe scheduler:\n- Reads manifest\n- Loops: for each pending job, assign to free GPU, launch via `screen`\n- Polls job status (every 60s)\n- Detects stale screens (python exited but screen detached → kill)\n- Detects OOM (CUDA OOM in log → mark failed_oom → retry after delay)\n- Detects completion (expected output JSON\u002Ffile exists) → mark completed\n- Launches next wave when current wave settles\n- Writes state to `queue_state.json` continuously\n\n### Step 4: Monitoring\n\nUser can check state anytime, using `$REMOTE_RUN_DIR` from Step 3b (or reload from `$LOCAL_RUN_DIR\u002Frun_meta.txt` for an older run):\n\n```bash\nssh \u003Cserver> \"cat \\\"$REMOTE_RUN_DIR\u002Fqueue_state.json\\\"\" \\\n  | jq '.jobs | group_by(.status) | map({(.[0].status): length}) | add'\n```\n\nNote: `\u002Fmonitor-experiment` is currently focused on screen sessions, result JSONs, and W&B; it does not yet read `queue_state.json` directly. For queue-state monitoring, use the literal command above against the recorded `REMOTE_RUN_DIR`. (Tracking `\u002Fmonitor-experiment` queue-state integration as a follow-up.)\n\n### Step 5: Post-completion\n\nWhen all jobs in `manifest.json` are `completed` or `stuck`:\n- The remote scheduler (`queue_manager.py`) exits cleanly with `All jobs done` to its own stdout (captured in `$REMOTE_RUN_DIR\u002Fqueue_mgr.log`). It does NOT write the local summary.\n- The **local** skill agent then aggregates state into `$LOCAL_RUN_DIR\u002Fsummary.md` (read `$REMOTE_RUN_DIR\u002Fqueue_state.json`, group by status, optionally pull per-job logs).\n- Local skill agent invokes `\u002Fanalyze-results` if `analyze_on_complete: true`.\n\n## Grid Spec Syntax\n\nInstead of writing 24 job entries manually:\n\n```yaml\ngrid:\n  N: [64, 128, 256]\n  n: [50000, 150000, 500000, 652000]\n  seed: [42, 200, 201]\ntemplate:\n  id: \"s${seed}_N${N}_n${n}\"\n  args: {seed: ${seed}, n_hidden: ${N}, n_train_subset: ${n}}\n```\n\nExpands to 36 jobs automatically.\n\n## Wave Chaining\n\nFor sequential phases (teacher → student):\n\n```yaml\nphases:\n  - name: train_teachers\n    grid:\n      N: [384, 512]\n    template:\n      cmd: python run_train.py --direction c --backbone softmax --n_hidden ${N} ...\n      expected_output: checkpoints\u002Ftransformer\u002Fteacher_L96_K500_N${N}.pt\n  \n  - name: distill_students\n    depends_on: [train_teachers]        # must be a LIST, even for a single dependency\n    grid:\n      N: [384, 512]\n      seed: [42, 200, 201]\n    template:\n      cmd: python run_distill.py --n_hidden ${N} --seed ${seed} ...\n      expected_output: figures\u002Fdistill_sw_N${N}_*_seed${seed}.json\n```\n\nScheduler enforces `depends_on`: `distill_students` jobs stay `pending` until every\n`train_teachers` job is terminal — `completed` **or** `stuck`. A failed teacher does not\nhold its students back, so check `queue_state.json` for `stuck` jobs before trusting a\ndependent wave.\n\n## OOM Handling\n\nDetect OOM from stdout:\n```regex\ntorch\\.OutOfMemoryError: CUDA out of memory\n```\n\nOn detection:\n1. Mark job `failed_oom`\n2. Kill screen\n3. Wait `oom_retry.delay` seconds\n4. Check if current GPU is free; if not, try another free GPU\n5. Requeue as `pending`\n6. Max `oom_retry.max_attempts` before marking `stuck`\n\n## Stale Screen Detection\n\nEvery 60s, for each running screen:\n1. Check screen exists (`screen -ls`)\n2. Check python PID still running (`ps -p`)\n3. If screen exists but python exited:\n   - If expected output file exists → mark `completed`, kill stale screen\n   - If no output file → mark `failed_other`, kill screen\n\n## Resume-on-restart\n\nIf scheduler crashes \u002F is killed:\n1. Read `queue_state.json`\n2. For each `running` job: check screen; if still alive, keep; if not, re-evaluate state\n3. For each `pending`: continue normally\n4. Idempotent: safe to restart scheduler without losing state\n\n## Output: Summary Report\n\n```markdown\n# Experiment Queue Summary\n\n**Project**: my_grid_experiment\n**Started**: 2026-04-16 11:36:29\n**Completed**: 2026-04-16 18:02:14\n**Total wall-clock**: 6h 25m\n**Jobs**: 40 completed, 2 OOM-retried then completed, 0 stuck\n\n## Phases\n| Phase | Jobs | Success | OOM retries | Duration |\n| --- | --- | --- | --- | --- |\n| train_teachers | 2 | 2 | 0 | 58m |\n| distill_students | 24 | 24 | 2 | 4h 02m |\n| multi_seed_validation | 16 | 16 | 0 | 1h 25m |\n\n## Results Files\n- 42 JSON files in `figures\u002Fdistill_sw_*.json`\n\n## Next Steps\n- Run `\u002Fanalyze-results` on output JSONs\n- Figures auto-regen via `artifact-sync` (if configured)\n```\n\n## Comparison with `\u002Frun-experiment`\n\n| Feature | `\u002Frun-experiment` | `experiment-queue` |\n| --- | --- | --- |\n| Single-shot experiment | ✅ | ✅ (overkill) |\n| Multi-GPU parallel | Basic | Proper scheduling |\n| Wave transitions | Manual | Automatic |\n| OOM retry | Manual | Automatic |\n| Stale screen cleanup | Manual | Automatic |\n| Teacher→student chain | Manual | Built-in |\n| State persistence | No | Yes (JSON) |\n| Resume on crash | No | Yes |\n| Grid expansion | Manual | Declarative |\n\n**Rule**: Use `\u002Frun-experiment` for ≤5 jobs. Use `experiment-queue` for ≥10 jobs or anything with phases.\n\n## Key Rules\n\n- **Never overlap screens on the same GPU** — always wait for `memory.used \u003C 500 MiB` before launching new job\n- **Always write state to disk** — every state change flushed to `queue_state.json`\n- **Idempotent scheduler** — safe to restart; picks up from state file\n- **Expected-output-based completion** — don't trust screen state alone; verify output file exists\n- **Bounded retry** — max N OOM retries, then mark `stuck` and alert\n- **Dependencies enforced at launch** — a wave launches only after every job in the phases it\n  depends on has reached a terminal state. Note \"terminal\" includes `stuck`: if a teacher job\n  fails, the phase still completes and its students launch against a missing checkpoint. Check\n  `queue_state.json` for `stuck` jobs before trusting a dependent wave's results.\n\n## Known Failure Modes\n\n- **SSH connection drop during scheduling**: scheduler keeps running on remote (nohup), just reconnect and check\n- **GPU reservation by another user**: scheduler waits, does not pre-empt\n- **Disk full on remote**: scheduler detects write failure, marks all pending `stuck`, alerts\n\n## Example Session\n\nUser: \"跑 T5+T6 全部实验：T5 = N∈{80,192} × n 4 values × seed {200,201}, T6 = N∈{384,512} × n 4 values × seed {42,200,201}; T6 需要先 train teacher\"\n\nClaude invokes `\u002Fexperiment-queue`:\n1. Parses description into 2-phase manifest\n2. Phase 1: T5 (16 jobs, no teacher dependency) + T6 teacher training (2 jobs)\n3. Phase 2: T6 distillation (24 jobs, depends on teachers)\n4. Deploys scheduler via nohup\n5. Reports: \"Scheduler PID 93534, total 42 jobs, estimated 6-7h wall-clock\"\n\nThen user can check anytime or wait for summary report.\n\n## See Also\n\n- `\u002Frun-experiment` — single experiment deployment\n- `\u002Fmonitor-experiment` — check progress (now reads from queue_state.json)\n- `\u002Fanalyze-results` — post-hoc analysis\n- `skills\u002Fexperiment-queue\u002Fscripts\u002Fqueue_manager.py` (canonical, Phase 3.3 move) — the scheduler implementation; resolved at runtime via the fallback chain in Step 3a. Legacy entry at `tools\u002Fexperiment_queue\u002Fqueue_manager.py` is an `os.execv` shim.\n- `skills\u002Fexperiment-queue\u002Fscripts\u002Fbuild_manifest.py` (canonical, Phase 3.3 move) — build manifest from grid spec; same resolution chain. Legacy entry at `tools\u002Fexperiment_queue\u002Fbuild_manifest.py` is an `os.execv` shim.\n\n## Rationale \u002F Source\n\nIdentified via 2026-04-16 post-mortem analysis (Codex GPT-5.5 xhigh) of a 1.5-day\nmulti-seed paper experiment session:\n\n- Wall-clock sink: stale screens, OOM, wave transitions, manual parser\n- Token sink: re-writing orchestration code each session\n- Cognitive sink: tracking which cells succeeded, which failed, which to retry\n\nThis skill targets the wall-clock sink specifically; see `artifact-sync` and\n`paper-fix-auto-apply` for the other two.\n","# Experiment Queue\n\n> ⏱ **External cadence: visibility only.** This skill already runs its own\n> detached server-side scheduler (60s poll + `depends_on` + wave transitions).\n> Use its status output for overnight visibility (N done \u002F N running \u002F N\n> pending); do **not** wrap it in a second `\u002Floop` \u002F `CronCreate` poll — that\n> duplicates the scheduler on an uncoordinated clock and races the\n> wave-transition logic it was built to prevent. See\n> [`shared-references\u002Fexternal-cadence.md`](..\u002Fshared-references\u002Fexternal-cadence.md)\n> (\"don't duplicate an existing scheduler\").\n\nOrchestrate large batches of ML experiments on SSH remote GPU servers with proper state tracking, OOM retry, stale cleanup, and wave transitions.\n\n## When to Use This Skill\n\nUse when `\u002Frun-experiment` is insufficient:\n- **≥10 jobs** that need batching across GPUs\n- **Multi-seed sweeps** (e.g., 21 seeds × 12 cells)\n- **Wave transitions** (run wave 1, wait, run wave 2, wait, run wave 3...)\n- **Teacher+student chains** (train teacher then distill; auto-trigger student after teacher done)\n- **OOM-prone configs** where you need to retry with different GPU or wait\n- **Mixed seed grids** where failed cells need re-running\n\nDo NOT use for:\n- Single ad-hoc experiment (use `\u002Frun-experiment`)\n- Modal\u002FVast.ai deployments (those have their own orchestration)\n- Experiments that need manual inspection between runs\n\n## Why This Exists\n\nBased on session audit (2026-04-16), the major wall-clock sinks in multi-seed grid experiments are:\n\n1. **Stale screens** — python finishes, wandb uploads, screen hangs, next wave blocked\n2. **OOM on shared GPU** — previous job's memory not yet released\n3. **Wave race** — new wave launches before previous wave fully settles\n4. **Missing checkpoints** — student launches before teacher saved\n5. **Parser duplication** — rewriting multi-seed analysis python every batch\n\nAll of these are pure engineering friction that can be orchestrated.\n\n## Core Concepts\n\n> **Environment contract**: queue jobs assume the target env is already built\n> and validated per `..\u002Fshared-references\u002Fcompute-env-contract.md` (spec-hash\n> ledger + kernel witness). A wave of jobs dying at import time = the env\n> contract was skipped, not a queue bug; check the provider's\n> `.aris\u002Fcompute\u002F\u003Cprovider>.md` ledger before re-queueing.\n\n### Job Manifest\n\nA manifest lists jobs with explicit state:\n\n```yaml\nproject: my_grid_experiment\ncwd: \u002Fhome\u002Fuser\u002Fyour_project\nconda: my_env\n# Optional: override conda hook path if conda is not at a standard location.\n# Can be a bare path (wrapped automatically) or a full `eval \"$(... shell.bash hook)\"` string.\n# Falls back to auto-detect of ~\u002Fanaconda3, ~\u002Fminiconda3, \u002Fopt\u002Fanaconda3, etc.,\n# or the ARIS_CONDA_HOOK environment variable.\n# conda_hook: \u002Fcustom\u002Fpath\u002Fto\u002Fconda\nssh: gpu-server\ndefault_cmd: >\n  python run_distill.py --backbone softmax --lam 0.5\n  --K 500 --L 96 --W 16 --n_steps 30000 --batch_size 128 --lr 1e-4\n\npreconditions:\n  - type: checkpoint_exists\n    path: checkpoints\u002Ftransformer\u002Fteacher_L96_K500_N{N}.pt\n\ngpus: [0, 1, 2, 3, 4, 5, 6, 7]\nmax_parallel: 8\ngpu_free_threshold_mib: 500  # optional, default 500; raise for shared servers, lower for tight packing\noom_retry:\n  delay: 120\n  max_attempts: 3\n\njobs:\n  - id: s200_N64_n50K\n    args: {seed: 200, n_hidden: 64, n_train_subset: 50000, subset_seed: 2024}\n  - id: s200_N128_n50K\n    args: {seed: 200, n_hidden: 128, n_train_subset: 50000, subset_seed: 2024}\n  # ... 14 more\n```\n\n### Job State Machine\n\n```\npending → running → completed\n                 ↘ failed_oom → pending (after delay) [retry up to N]\n                 ↘ failed_other → stuck (needs manual inspection)\nstale screen (process gone, screen lingering) → failed_other → stuck\n```\n\n> **Operator note on `stuck` (the agent's move, not the queue's):** the queue\n> deterministically parks `failed_other` jobs as `stuck` — that part is code and\n> unchanged. Before handing a `stuck` batch to the human, the OPERATING AGENT\n> should check: if the same failure repeats across jobs, try ONE clean\n> reimplement of the **agent-generated wrapper\u002Fattempt script only** — never\n> user\u002Fproject source (`run_*.py` you didn't write), the manifest, queue state,\n> logs, or results (see `shared-references\u002Fexternal-cadence.md` § *Let a broken\n> attempt restart, not just patch*). Reserve the human handoff for\n> contract\u002Fenvironment doubts, not merely broken attempt code.\n\n### Wave Orchestration\n\nA \"wave\" is a batch of jobs that fit available GPUs. Next wave only starts when:\n1. All current-wave python processes have exited\n2. No stale screens remain for current-wave tags\n3. GPU memory has dropped below threshold (≤500 MiB)\n4. Precondition checks pass for next-wave jobs\n\n## Workflow\n\n### Step 1: Parse Manifest \u002F Build from Grid\n\nInput can be:\n- **YAML manifest** (explicit job list, recommended for complex cases)\n- **Grid spec** (Cartesian product of param values, e.g., `N=[64,128,256] × n=[50K,150K,500K,652K]`)\n- **Natural language description** (Claude parses into manifest)\n\nBind the run identifiers once so every later step (manifest save, scp, launch, monitor, resume) refers to the same paths. Set these as local shell variables before generating the manifest:\n\n```bash\n# REPLACE the placeholder path before running, or pre-export PROJECT_DIR:\nPROJECT_DIR=\"${PROJECT_DIR:?set PROJECT_DIR to the local project root}\"\nRUN_TS=$(date -u +%Y%m%dT%H%M%SZ)             # one timestamp per run, reused everywhere\nLOCAL_RUN_DIR=\"$PROJECT_DIR\u002Fexperiment_queue\u002F$RUN_TS\"\nmkdir -p \"$LOCAL_RUN_DIR\"\n```\n\nSave the built manifest to `$LOCAL_RUN_DIR\u002Fmanifest.json` for reproducibility.\n\n### Step 2: Pre-flight\n\n- Check SSH connection works\n- Check conda env exists on remote\n- Check `cwd` exists on remote\n- Check all preconditions (checkpoints, input files)\n- Check GPU availability (at least `max_parallel` free GPUs)\n\nIf any precondition fails, show user which jobs are blocked and why.\n\n### Step 3: Launch Scheduler\n\nThe canonical scheduler implementation lives in `skills\u002Fexperiment-queue\u002Fscripts\u002Fqueue_manager.py` (Phase 3.3 move, Arch C). `tools\u002Fexperiment_queue\u002Fqueue_manager.py` is now a Python `os.execv` shim retained for legacy resolver-chain compatibility. Three preliminaries before launch.\n\n**3a. Resolve the local helper directory.** The two helpers (`queue_manager.py`, `build_manifest.py`) now sit under `skills\u002Fexperiment-queue\u002Fscripts\u002F` in the ARIS repo, with shims at `tools\u002Fexperiment_queue\u002F` for legacy resolver layers. Use this hybrid chain so the skill works from any project layout:\n\n```bash\n# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).\nQUEUE_TOOLS=\"\"\nif [ -n \"${CLAUDE_SKILL_DIR:-}\" ] && [ -f \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fqueue_manager.py\" ]; then\n  QUEUE_TOOLS=\"$CLAUDE_SKILL_DIR\u002Fscripts\"\nfi\n# Layers 1-4: legacy chain via tools\u002Fexperiment_queue\u002F shims.\nif [ -z \"$QUEUE_TOOLS\" ]; then\n  cd \"$(git rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)\" || exit 1\n  if [ -z \"${ARIS_REPO:-}\" ] && [ -f .aris\u002Finstalled-skills.txt ]; then\n      ARIS_REPO=$(awk -F'\\t' '$1==\"repo_root\"{print $2; exit}' .aris\u002Finstalled-skills.txt 2>\u002Fdev\u002Fnull) || true\n  fi\n  if [ -z \"${ARIS_REPO:-}\" ] && [ -f \"$HOME\u002F.aris\u002Frepo\" ]; then\n      ARIS_REPO=$(cat \"$HOME\u002F.aris\u002Frepo\" 2>\u002Fdev\u002Fnull) || true\n  fi\n  QUEUE_TOOLS=\".aris\u002Ftools\u002Fexperiment_queue\"\n  [ -f \"$QUEUE_TOOLS\u002Fqueue_manager.py\" ] || QUEUE_TOOLS=\"tools\u002Fexperiment_queue\"\n  [ -f \"$QUEUE_TOOLS\u002Fqueue_manager.py\" ] || { [ -n \"${ARIS_REPO:-}\" ] && QUEUE_TOOLS=\"$ARIS_REPO\u002Ftools\u002Fexperiment_queue\"; }\n  [ -f \"$QUEUE_TOOLS\u002Fqueue_manager.py\" ] || QUEUE_TOOLS=\"\"\nfi\n[ -z \"$QUEUE_TOOLS\" ] && { echo \"ERROR: experiment_queue helpers not found (layer 0: \\$CLAUDE_SKILL_DIR\u002Fscripts\u002F; layers 1-4: .aris\u002Ftools\u002F, tools\u002F, \\$ARIS_REPO\u002Ftools\u002F, \\$ARIS_REPO\u002Ftools\u002F via ~\u002F.aris\u002Frepo). Rerun install_aris.sh or smart_update.sh (refreshes ~\u002F.aris\u002Frepo), set ARIS_REPO, or copy the canonical scripts from \\$ARIS_REPO\u002Fskills\u002Fexperiment-queue\u002Fscripts\u002F.\" >&2; exit 1; }\n```\n\nThe `.aris\u002Ftools` symlink is set up by `install_aris.sh` (#174). Older installs without that symlink fall through to `tools\u002Fexperiment_queue` (works if invoked from inside the ARIS repo), `$ARIS_REPO\u002Ftools\u002Fexperiment_queue`, or the same path resolved via the global pointer file `~\u002F.aris\u002Frepo` (#366, for installs with no project-local manifest). After Phase 3.3, each of those legacy paths contains a Python `os.execv` shim that forwards to the canonical `skills\u002Fexperiment-queue\u002Fscripts\u002F` location, so existing users do not need to re-run anything.\n\n**3b. Compute remote paths.** Use both a remote-relative form (for `scp` destinations — modern `scp` runs in SFTP mode and does NOT reliably expand `$HOME` in destination paths) and a `$HOME`-prefixed form (for `ssh ... command` strings, where remote bash WILL expand `$HOME`):\n\n```bash\nREMOTE_RUN_REL=\".aris_queue\u002Fruns\u002F$RUN_TS\"          # for scp destinations (relative to remote home)\nREMOTE_RUN_DIR=\"\\$HOME\u002F$REMOTE_RUN_REL\"            # for ssh command strings (literal $HOME, expanded on remote)\n```\n\n**3c. Bootstrap the remote run directory and copy helpers + manifest.** Per-invocation and idempotent. Use a unique run directory rather than `\u002Ftmp` so concurrent queues do not collide and so resume-after-crash is reproducible.\n\n```bash\nssh \u003Cserver> \"mkdir -p \\\"$REMOTE_RUN_DIR\u002Flogs\\\" \\\"\\$HOME\u002F.aris_queue\\\"\"\nscp \"$QUEUE_TOOLS\u002Fqueue_manager.py\" \"$QUEUE_TOOLS\u002Fbuild_manifest.py\" \u003Cserver>:.aris_queue\u002F\nscp \"$LOCAL_RUN_DIR\u002Fmanifest.json\" \u003Cserver>:\"$REMOTE_RUN_REL\u002Fmanifest.json\"\n```\n\n**3d. Launch the scheduler as a detached `nohup` process on the SSH host:**\n\n```bash\nssh \u003Cserver> \"nohup python3 \\\"\\$HOME\u002F.aris_queue\u002Fqueue_manager.py\\\" \\\\\n  --manifest \\\"$REMOTE_RUN_DIR\u002Fmanifest.json\\\" \\\\\n  --state    \\\"$REMOTE_RUN_DIR\u002Fqueue_state.json\\\" \\\\\n  --log-dir  \\\"$REMOTE_RUN_DIR\u002Flogs\\\" \\\\\n  > \\\"$REMOTE_RUN_DIR\u002Fqueue_mgr.log\\\" 2>&1 &\"\n```\n\nNotes for callers:\n- `--log-dir` is what `queue_manager.py` actually consumes (per-job log files for OOM detection). Do NOT pass `--log \u003Cpath>` — that flag is declared but unused, and a single combined log breaks the per-job stale-screen \u002F OOM heuristics.\n- Persist `RUN_TS` \u002F `REMOTE_RUN_REL` \u002F `REMOTE_RUN_DIR` to disk so monitoring and resume can reload them without regenerating:\n\n  ```bash\n  {\n    printf 'PROJECT_DIR=%q\\n'    \"$PROJECT_DIR\"\n    printf 'RUN_TS=%q\\n'         \"$RUN_TS\"\n    printf 'LOCAL_RUN_DIR=%q\\n'  \"$LOCAL_RUN_DIR\"\n    printf 'REMOTE_RUN_REL=%q\\n' \"$REMOTE_RUN_REL\"\n    printf 'REMOTE_RUN_DIR=%q\\n' \"$REMOTE_RUN_DIR\"\n  } > \"$LOCAL_RUN_DIR\u002Frun_meta.txt\"\n  ```\n\n  `%q` shell-escapes the values so the file is safely sourceable later. Note that `REMOTE_RUN_DIR` keeps a literal `$HOME` (do not expand it locally), which is the right form for re-use inside `ssh \"...\"` strings later.\n\n**3e. Resume an existing queue (only when the user asks).** A fresh `RUN_TS` per invocation is correct for *new* queues. To resume a crashed queue, do NOT regenerate `RUN_TS` — reload the recorded values and re-run only the launch command (Step 3d), not the bootstrap (Step 3c):\n\n```bash\nLOCAL_RUN_DIR=\"\u002Fabs\u002Fpath\u002Fto\u002Fproject\u002Fexperiment_queue\u002F\u003Cexisting-run-ts>\"   # the run dir to resume\n. \"$LOCAL_RUN_DIR\u002Frun_meta.txt\"                                            # reloads PROJECT_DIR \u002F RUN_TS \u002F REMOTE_RUN_REL \u002F REMOTE_RUN_DIR\n# Then re-run Step 3d verbatim. Do NOT re-run Step 3c (would overwrite manifest.json + state.json).\n```\n\nA `queue_state.json` written before the 2026-08 scheduler fix records jobs the old code\nmis-judged as failed. Resuming it parks those jobs as `stuck` — they are not retried, so a\nstate file whose jobs are all `failed_other` finishes with nothing launched. Delete that\nstate file and re-run the manifest from Step 3c.\n\nThe scheduler:\n- Reads manifest\n- Loops: for each pending job, assign to free GPU, launch via `screen`\n- Polls job status (every 60s)\n- Detects stale screens (python exited but screen detached → kill)\n- Detects OOM (CUDA OOM in log → mark failed_oom → retry after delay)\n- Detects completion (expected output JSON\u002Ffile exists) → mark completed\n- Launches next wave when current wave settles\n- Writes state to `queue_state.json` continuously\n\n### Step 4: Monitoring\n\nUser can check state anytime, using `$REMOTE_RUN_DIR` from Step 3b (or reload from `$LOCAL_RUN_DIR\u002Frun_meta.txt` for an older run):\n\n```bash\nssh \u003Cserver> \"cat \\\"$REMOTE_RUN_DIR\u002Fqueue_state.json\\\"\" \\\n  | jq '.jobs | group_by(.status) | map({(.[0].status): length}) | add'\n```\n\nNote: `\u002Fmonitor-experiment` is currently focused on screen sessions, result JSONs, and W&B; it does not yet read `queue_state.json` directly. For queue-state monitoring, use the literal command above against the recorded `REMOTE_RUN_DIR`. (Tracking `\u002Fmonitor-experiment` queue-state integration as a follow-up.)\n\n### Step 5: Post-completion\n\nWhen all jobs in `manifest.json` are `completed` or `stuck`:\n- The remote scheduler (`queue_manager.py`) exits cleanly with `All jobs done` to its own stdout (captured in `$REMOTE_RUN_DIR\u002Fqueue_mgr.log`). It does NOT write the local summary.\n- The **local** skill agent then aggregates state into `$LOCAL_RUN_DIR\u002Fsummary.md` (read `$REMOTE_RUN_DIR\u002Fqueue_state.json`, group by status, optionally pull per-job logs).\n- Local skill agent invokes `\u002Fanalyze-results` if `analyze_on_complete: true`.\n\n## Grid Spec Syntax\n\nInstead of writing 24 job entries manually:\n\n```yaml\ngrid:\n  N: [64, 128, 256]\n  n: [50000, 150000, 500000, 652000]\n  seed: [42, 200, 201]\ntemplate:\n  id: \"s${seed}_N${N}_n${n}\"\n  args: {seed: ${seed}, n_hidden: ${N}, n_train_subset: ${n}}\n```\n\nExpands to 36 jobs automatically.\n\n## Wave Chaining\n\nFor sequential phases (teacher → student):\n\n```yaml\nphases:\n  - name: train_teachers\n    grid:\n      N: [384, 512]\n    template:\n      cmd: python run_train.py --direction c --backbone softmax --n_hidden ${N} ...\n      expected_output: checkpoints\u002Ftransformer\u002Fteacher_L96_K500_N${N}.pt\n  \n  - name: distill_students\n    depends_on: [train_teachers]        # must be a LIST, even for a single dependency\n    grid:\n      N: [384, 512]\n      seed: [42, 200, 201]\n    template:\n      cmd: python run_distill.py --n_hidden ${N} --seed ${seed} ...\n      expected_output: figures\u002Fdistill_sw_N${N}_*_seed${seed}.json\n```\n\nScheduler enforces `depends_on`: `distill_students` jobs stay `pending` until every\n`train_teachers` job is terminal — `completed` **or** `stuck`. A failed teacher does not\nhold its students back, so check `queue_state.json` for `stuck` jobs before trusting a\ndependent wave.\n\n## OOM Handling\n\nDetect OOM from stdout:\n```regex\ntorch\\.OutOfMemoryError: CUDA out of memory\n```\n\nOn detection:\n1. Mark job `failed_oom`\n2. Kill screen\n3. Wait `oom_retry.delay` seconds\n4. Check if current GPU is free; if not, try another free GPU\n5. Requeue as `pending`\n6. Max `oom_retry.max_attempts` before marking `stuck`\n\n## Stale Screen Detection\n\nEvery 60s, for each running screen:\n1. Check screen exists (`screen -ls`)\n2. Check python PID still running (`ps -p`)\n3. If screen exists but python exited:\n   - If expected output file exists → mark `completed`, kill stale screen\n   - If no output file → mark `failed_other`, kill screen\n\n## Resume-on-restart\n\nIf scheduler crashes \u002F is killed:\n1. Read `queue_state.json`\n2. For each `running` job: check screen; if still alive, keep; if not, re-evaluate state\n3. For each `pending`: continue normally\n4. Idempotent: safe to restart scheduler without losing state\n\n## Output: Summary Report\n\n```markdown\n# Experiment Queue Summary\n\n**Project**: my_grid_experiment\n**Started**: 2026-04-16 11:36:29\n**Completed**: 2026-04-16 18:02:14\n**Total wall-clock**: 6h 25m\n**Jobs**: 40 completed, 2 OOM-retried then completed, 0 stuck\n\n## Phases\n| Phase | Jobs | Success | OOM retries | Duration |\n| --- | --- | --- | --- | --- |\n| train_teachers | 2 | 2 | 0 | 58m |\n| distill_students | 24 | 24 | 2 | 4h 02m |\n| multi_seed_validation | 16 | 16 | 0 | 1h 25m |\n\n## Results Files\n- 42 JSON files in `figures\u002Fdistill_sw_*.json`\n\n## Next Steps\n- Run `\u002Fanalyze-results` on output JSONs\n- Figures auto-regen via `artifact-sync` (if configured)\n```\n\n## Comparison with `\u002Frun-experiment`\n\n| Feature | `\u002Frun-experiment` | `experiment-queue` |\n| --- | --- | --- |\n| Single-shot experiment | ✅ | ✅ (overkill) |\n| Multi-GPU parallel | Basic | Proper scheduling |\n| Wave transitions | Manual | Automatic |\n| OOM retry | Manual | Automatic |\n| Stale screen cleanup | Manual | Automatic |\n| Teacher→student chain | Manual | Built-in |\n| State persistence | No | Yes (JSON) |\n| Resume on crash | No | Yes |\n| Grid expansion | Manual | Declarative |\n\n**Rule**: Use `\u002Frun-experiment` for ≤5 jobs. Use `experiment-queue` for ≥10 jobs or anything with phases.\n\n## Key Rules\n\n- **Never overlap screens on the same GPU** — always wait for `memory.used \u003C 500 MiB` before launching new job\n- **Always write state to disk** — every state change flushed to `queue_state.json`\n- **Idempotent scheduler** — safe to restart; picks up from state file\n- **Expected-output-based completion** — don't trust screen state alone; verify output file exists\n- **Bounded retry** — max N OOM retries, then mark `stuck` and alert\n- **Dependencies enforced at launch** — a wave launches only after every job in the phases it\n  depends on has reached a terminal state. Note \"terminal\" includes `stuck`: if a teacher job\n  fails, the phase still completes and its students launch against a missing checkpoint. Check\n  `queue_state.json` for `stuck` jobs before trusting a dependent wave's results.\n\n## Known Failure Modes\n\n- **SSH connection drop during scheduling**: scheduler keeps running on remote (nohup), just reconnect and check\n- **GPU reservation by another user**: scheduler waits, does not pre-empt\n- **Disk full on remote**: scheduler detects write failure, marks all pending `stuck`, alerts\n\n## Example Session\n\nUser: \"跑 T5+T6 全部实验：T5 = N∈{80,192} × n 4 values × seed {200,201}, T6 = N∈{384,512} × n 4 values × seed {42,200,201}; T6 需要先 train teacher\"\n\nClaude invokes `\u002Fexperiment-queue`:\n1. Parses description into 2-phase manifest\n2. Phase 1: T5 (16 jobs, no teacher dependency) + T6 teacher training (2 jobs)\n3. Phase 2: T6 distillation (24 jobs, depends on teachers)\n4. Deploys scheduler via nohup\n5. Reports: \"Scheduler PID 93534, total 42 jobs, estimated 6-7h wall-clock\"\n\nThen user can check anytime or wait for summary report.\n\n## See Also\n\n- `\u002Frun-experiment` — single experiment deployment\n- `\u002Fmonitor-experiment` — check progress (now reads from queue_state.json)\n- `\u002Fanalyze-results` — post-hoc analysis\n- `skills\u002Fexperiment-queue\u002Fscripts\u002Fqueue_manager.py` (canonical, Phase 3.3 move) — the scheduler implementation; resolved at runtime via the fallback chain in Step 3a. Legacy entry at `tools\u002Fexperiment_queue\u002Fqueue_manager.py` is an `os.execv` shim.\n- `skills\u002Fexperiment-queue\u002Fscripts\u002Fbuild_manifest.py` (canonical, Phase 3.3 move) — build manifest from grid spec; same resolution chain. Legacy entry at `tools\u002Fexperiment_queue\u002Fbuild_manifest.py` is an `os.execv` shim.\n\n## Rationale \u002F Source\n\nIdentified via 2026-04-16 post-mortem analysis (Codex GPT-5.5 xhigh) of a 1.5-day\nmulti-seed paper experiment session:\n\n- Wall-clock sink: stale screens, OOM, wave transitions, manual parser\n- Token sink: re-writing orchestration code each session\n- Cognitive sink: tracking which cells succeeded, which failed, which to retry\n\nThis skill targets the wall-clock sink specifically; see `artifact-sync` and\n`paper-fix-auto-apply` for the other two.\n",{"name":5,"description":7,"allowed-tools":24,"argument-hint":25},"Bash(*), Read, Grep, Glob, Edit, Write, Skill(run-experiment), Skill(monitor-experiment)","[manifest-or-grid-spec]","main","18193d71ea3441d7c033dbf195b8a7c75ac96f75","packages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Faris\u002Fskills\u002Fexperiment-queue",0,"https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science","https:\u002F\u002Fgithub.com\u002FCZX-LBJ","一个没事喜欢随便写点代码的小菜鸡\r\n","2026-10-22 09:48:04",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add CZX-LBJ\u002Fdeepseek-science --skill experiment-queue",{"tool":40,"command":41},"bunx","bunx skills add CZX-LBJ\u002Fdeepseek-science --skill experiment-queue",{"tool":43,"command":44},"pnpm","pnpm dlx skills add CZX-LBJ\u002Fdeepseek-science --skill experiment-queue","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Faris\u002Fskills\u002Fexperiment-queue\u002FSKILL.md",true,[48,54],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"scripts\u002Fbuild_manifest.py","SCRIPT","脚本",4562,"https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Faris\u002Fskills\u002Fexperiment-queue\u002Fscripts\u002Fbuild_manifest.py",{"path":55,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":56,"sourceHtmlUrl":57},"scripts\u002Fqueue_manager.py",15116,"https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Faris\u002Fskills\u002Fexperiment-queue\u002Fscripts\u002Fqueue_manager.py",[59,66,73,80,87,94],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M7FEEKSNMRMKW6JEK93PFDFY","bio-free-energy-calculations","Performs alchemical free-energy calculations including relative binding free energy (RBFE \u002F FEP+) and absolute binding free energy (ABFE) via OpenFE, FEP+, GROMACS, AMBER pmemd, and OpenMM with explicit lambda scheduling, soft-core potentials, MBAR\u002FBAR analysis, cycle-closure validation, and protocol-appropriate enhanced sampling. Compares ML alternatives (Boltz-2 affinity, DeepDock). Use when ranking analogs by binding affinity beyond docking accuracy, performing prospective lead optimization, or validating SAR predictions.","https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Fbioskills\u002Fchemoinformatics\u002Ffree-energy-calculations\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M7FEE5CTE5QK55CEMXNNVWY9","bio-conformer-generation","Generates 3D conformer ensembles using RDKit ETKDGv3 with knowledge-enhanced distance geometry, MMFF94\u002FUFF force-field optimization, CREST + GFN2-xTB semi-empirical refinement, and macrocycle-aware torsion preferences. Provides explicit decision rules for single vs ensemble conformer use, RMSD pruning, energy windows, conformer count, and force-field choice. Use when preparing 3D ligands for docking, generating descriptor input for 3D QSAR, or sampling macrocycle\u002Fpeptide conformational ensembles.","https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Fbioskills\u002Fchemoinformatics\u002Fconformer-generation\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7FEDNGFEMFWD1MSEDR5H7CY","bio-admet-prediction","Predicts ADMET properties using ADMETlab 3.0 (119 platform features, including 77 prediction models with modeled-endpoint uncertainty), ADMET-AI, DeepChem MolNet, and chemprop D-MPNN with explicit handling of OECD QSAR principles, applicability domain assessment, calibration, hERG\u002FCYP\u002FAMES endpoints, and PAINS \u002F Lipinski \u002F Ro5 \u002F Veber \u002F BBB druglikeness filters. Use when filtering compounds for drug-likeness, prioritizing leads by predicted safety, or building an in-house ADMET QSAR model.","https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Fbioskills\u002Fchemoinformatics\u002Fadmet-prediction\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7FED69GFB54FRF7AV5066DN","writing-systems-papers","Paragraph-level structural blueprint for 10-12 page systems papers targeting OSDI, SOSP, ASPLOS, NSDI, and EuroSys. Provides page allocation, paragraph templates, and writing patterns. Use when user says \"写系统论文\", \"systems paper structure\", \"OSDI paper\", \"SOSP paper\", or wants fine-grained structural guidance for a systems conference submission.","https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Faris\u002Fskills\u002Fwriting-systems-papers\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M7FECVVDWZ0X0VEDTCE4B4DZ","wiki-enrich","Fill in the per-paper TODO sections of research-wiki\u002Fpapers\u002F\u003Cslug>.md pages that literature-ingest skills leave as bare scaffolds. Use when user says 'enrich wiki', 'fill paper TODOs', 'wiki body 補完', '把 paper 摘要寫進 wiki', 'research-wiki 自動填', or after a batch ingest that left papers\u002F as TODO scaffolds.","https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Faris\u002Fskills\u002Fwiki-enrich\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":19},"01M7FECD4BCJ2MTSBDDSE3ZAJ5","web-debug-search","Search GitHub, Stack Exchange, Chinese technical communities, official documentation, and general developer web sources for software errors, compatibility problems, API usage questions, and real-world workarounds. Use for debugging and discovery only; results are not paper-citation evidence.","https:\u002F\u002Fgithub.com\u002FCZX-LBJ\u002Fdeepseek-science\u002Fblob\u002Fmain\u002Fpackages\u002Fskill\u002Fskill-science\u002Fassets\u002Fsources\u002Faris\u002Fskills\u002Fweb-debug-search\u002FSKILL.md",[],[]]