experiment-queue skill

Experiment Queue

Orchestrate large batches of ML experiments on SSH remote GPU servers with proper state tracking, OOM retry, stale cleanup, and wave transitions.

When to Use This Skill

Use when /run-experiment is insufficient:

• ≥10 jobs that need batching across GPUs
• Multi-seed sweeps (e.g., 21 seeds × 12 cells)
• Wave transitions (run wave 1, wait, run wave 2, wait, run wave 3...)
• Teacher+student chains (train teacher then distill; auto-trigger student after teacher done)
• OOM-prone configs where you need to retry with different GPU or wait
• Mixed seed grids where failed cells need re-running

Do NOT use for:

• Single ad-hoc experiment (use /run-experiment)
• Modal/Vast.ai deployments (those have their own orchestration)
• Experiments that need manual inspection between runs

Why This Exists

Based on session audit (2026-04-16), the major wall-clock sinks in multi-seed grid experiments are:

1. Stale screens — python finishes, wandb uploads, screen hangs, next wave blocked
2. OOM on shared GPU — previous job's memory not yet released
3. Wave race — new wave launches before previous wave fully settles
4. Missing checkpoints — student launches before teacher saved
5. Parser duplication — rewriting multi-seed analysis python every batch

All of these are pure engineering friction that can be orchestrated.

Core Concepts

Environment contract: queue jobs assume the target env is already built

and validated per ../shared-references/compute-env-contract.md (spec-hash

ledger + kernel witness). A wave of jobs dying at import time = the env

contract was skipped, not a queue bug; check the provider's

.aris/compute/.md ledger before re-queueing.

Job Manifest

A manifest lists jobs with explicit state:

project: my_grid_experiment
cwd: /home/user/your_project
conda: my_env
# Optional: override conda hook path if conda is not at a standard location.
# Can be a bare path (wrapped automatically) or a full `eval "$(... shell.bash hook)"` string.
# Falls back to auto-detect of ~/anaconda3, ~/miniconda3, /opt/anaconda3, etc.,
# or the ARIS_CONDA_HOOK environment variable.
# conda_hook: /custom/path/to/conda
ssh: gpu-server
default_cmd: >
  python run_distill.py --backbone softmax --lam 0.5
  --K 500 --L 96 --W 16 --n_steps 30000 --batch_size 128 --lr 1e-4

preconditions:
  - type: checkpoint_exists
    path: checkpoints/transformer/teacher_L96_K500_N{N}.pt

gpus: [0, 1, 2, 3, 4, 5, 6, 7]
max_parallel: 8
gpu_free_threshold_mib: 500  # optional, default 500; raise for shared servers, lower for tight packing
oom_retry:
  delay: 120
  max_attempts: 3

jobs:
  - id: s200_N64_n50K
    args: {seed: 200, n_hidden: 64, n_train_subset: 50000, subset_seed: 2024}
  - id: s200_N128_n50K
    args: {seed: 200, n_hidden: 128, n_train_subset: 50000, subset_seed: 2024}
  # ... 14 more

Job State Machine

pending → running → completed
                 ↘ failed_oom → pending (after delay) [retry up to N]
                 ↘ failed_other → stuck (needs manual inspection)
stale screen (process gone, screen lingering) → failed_other → stuck

Operator note on stuck (the agent's move, not the queue's): the queue

deterministically parks failed_other jobs as stuck — that part is code and

unchanged. Before handing a stuck batch to the human, the OPERATING AGENT

should check: if the same failure repeats across jobs, try ONE clean

reimplement of the agent-generated wrapper/attempt script only — never

user/project source, the manifest, queue state, logs, or results (per

external-cadence.md, "Let a broken attempt restart, not just patch").

Reserve the human handoff for contract/environment doubts, not merely broken

attempt code.

Wave Orchestration

A "wave" is a batch of jobs that fit available GPUs. Next wave only starts when:

1. All current-wave python processes have exited
2. No stale screens remain for current-wave tags
3. GPU memory has dropped below threshold (≤500 MiB)
4. Precondition checks pass for next-wave jobs

Workflow

Step 1: Parse Manifest / Build from Grid

Input can be:

• YAML manifest (explicit job list, recommended for complex cases)
• Grid spec (Cartesian product of param values, e.g., N=[64,128,256] × n=[50K,150K,500K,652K])
• Natural language description (Claude parses into manifest)

Bind run identifiers once so every later step refers to the same paths:

# REPLACE the placeholder path before running, or pre-export PROJECT_DIR:
PROJECT_DIR="${PROJECT_DIR:?set PROJECT_DIR to the local project root}"
RUN_TS=$(date -u +%Y%m%dT%H%M%SZ)
LOCAL_RUN_DIR="$PROJECT_DIR/experiment_queue/$RUN_TS"
mkdir -p "$LOCAL_RUN_DIR"

Save the built manifest to $LOCALRUNDIR/manifest.json for reproducibility.

Step 2: Pre-flight

• Check SSH connection works
• Check conda env exists on remote
• Check cwd exists on remote
• Check all preconditions (checkpoints, input files)
• Check GPU availability (at least max_parallel free GPUs)

If any precondition fails, show user which jobs are blocked and why.

Step 3: Launch Scheduler

Resolve the bundled helper directory ($PROJECTDIR / $RUNTS / $LOCALRUNDIR already set in Step 1). Phase 3.3 (Arch C) moved the canonical scripts to skills/experiment-queue/scripts/; tools/experiment_queue/ retains os.execv shims for legacy resolver layers:

if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
fi
[ -n "${ARIS_REPO:-}" ] || { echo "ERROR: ARIS_REPO not set. Use install_aris_codex.sh managed install or export ARIS_REPO=/path/to/ARIS."; exit 1; }
# Prefer the new canonical location; fall back to legacy tools/ shim path.
QUEUE_TOOLS="$ARIS_REPO/skills/experiment-queue/scripts"
[ -f "$QUEUE_TOOLS/queue_manager.py" ] || QUEUE_TOOLS="$ARIS_REPO/tools/experiment_queue"
[ -f "$QUEUE_TOOLS/queue_manager.py" ] || { echo "ERROR: queue_manager.py not found at $ARIS_REPO/skills/experiment-queue/scripts/ or $ARIS_REPO/tools/experiment_queue/"; exit 1; }

Compute remote paths (note: modern scp runs in SFTP mode and does NOT reliably expand $HOME in destination paths — use remote-relative for scp, $HOME-prefixed for ssh command strings):

REMOTE_RUN_REL=".aris_queue/runs/$RUN_TS"
REMOTE_RUN_DIR="\$HOME/$REMOTE_RUN_REL"

Bootstrap remote run dir + copy helpers + copy manifest. Per-invocation, idempotent:

ssh <server> "mkdir -p \"$REMOTE_RUN_DIR/logs\" \"\$HOME/.aris_queue\""
scp "$QUEUE_TOOLS/queue_manager.py" "$QUEUE_TOOLS/build_manifest.py" <server>:.aris_queue/
scp "$LOCAL_RUN_DIR/manifest.json" <server>:"$REMOTE_RUN_REL/manifest.json"

Launch the scheduler as a detached nohup process:

ssh <server> "nohup python3 \"\$HOME/.aris_queue/queue_manager.py\" \\
  --manifest \"$REMOTE_RUN_DIR/manifest.json\" \\
  --state    \"$REMOTE_RUN_DIR/queue_state.json\" \\
  --log-dir  \"$REMOTE_RUN_DIR/logs\" \\
  > \"$REMOTE_RUN_DIR/queue_mgr.log\" 2>&1 &"

Notes: --log-dir is what queue_manager.py actually consumes (per-job log files for OOM detection). Do NOT pass --log — that flag is declared but unused.

Persist run identifiers for monitoring + resume (sourceable later):

{
  printf 'PROJECT_DIR=%q\n'    "$PROJECT_DIR"
  printf 'RUN_TS=%q\n'         "$RUN_TS"
  printf 'LOCAL_RUN_DIR=%q\n'  "$LOCAL_RUN_DIR"
  printf 'REMOTE_RUN_REL=%q\n' "$REMOTE_RUN_REL"
  printf 'REMOTE_RUN_DIR=%q\n' "$REMOTE_RUN_DIR"
} > "$LOCAL_RUN_DIR/run_meta.txt"

%q shell-escapes values; REMOTERUNDIR keeps a literal $HOME (correct for later reuse inside ssh "...").

Resume an existing queue. Do NOT regenerate RUNTS. Reload from runmeta.txt and re-run only the launch command above (not the bootstrap):

LOCAL_RUN_DIR="/abs/path/to/project/experiment_queue/<existing-run-ts>"
. "$LOCAL_RUN_DIR/run_meta.txt"
# Then re-run the launch command verbatim; do NOT re-run mkdir/scp.

The scheduler: