Menu
HKUST HPC4 への SSH 接続・リモートコマンド実行・ファイル転送・経路整備を提供する。Codex が文脈から判断して .codex/skills/hpc4/scripts/ 配下の bash script を直接呼ぶ。ユーザが /hpc4 で対話的に呼ぶことも可。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | hpc4 |
| description | HKUST HPC4 への SSH 接続・リモートコマンド実行・ファイル転送・経路整備を提供する。Codex が文脈から判断して .codex/skills/hpc4/scripts/ 配下の bash script を直接呼ぶ。ユーザが /hpc4 で対話的に呼ぶことも可。 |
| user-invocable | true |
HKUST HPC4 (hpc4.ust.hk) クラスタへの SSH 接続を、Codex のローカル実行環境から支援する。
HPC4 は HKUST 内部 network（有線 / Ivanti の 143.89/16、または HKUST キャンパス eduroam の 10.79/16 NAT）からしか到達できない。同じ Mac 上で「Codex との通信に使う通常の default route」と「HPC4 用の経路（HKUST eduroam 直結 / 有線 / Ivanti split-tunnel）」を同居させるのが運用の前提。
この同居は実は VPN / network client が起動時に kernel routing table に書き込む結果として OS が自然に成立させる：default route は通常通信、HKUST 向け route は HKUST 側接続、longest-prefix-match で衝突なし。skill 自身は default route や Codex の通信経路に絶対手を出さず、HPC4 (143.89.184.3) の host route 1 つだけを管理する。
ITSO 公式の HPC4 接続規約（オンキャンパス eduroam/有線 vs オフキャンパス Ivanti SSL VPN、eduroam の federated 性質、認証方法等）の正確な文言と出典は policy.md を参照。SKILL.md は運用最小限のみを書く。
このスキルが Codex 経由で動作する以上、「Codex に相談できない瞬間こそ user が一番困る」 という catch-22 がある。Codex に相談できない時、user は terminal だけで状況を把握して action する必要がある。これを設計に直接織り込む：
net-up-local.sh を自分の Terminal で実行していて、HKUST IF が存在し L3 route も正しいのに TCP 22 だけ落ちる場合は、B/C より pf main ruleset の kill-switch を最有力として扱い、pfctl -F rules を 1 回だけ自動実行して再判定する。flush 後も不通なら user space から復旧不能として止める（過去の com.apple/hpc4 anchor 戦略は撤去済み）。.codex/skills/hpc4/scripts/ 配下の bash script を直接呼ぶのが基本。ユーザが /hpc4 で対話的に呼ぶことも可だが、それは副経路この .codex/ skill は Codex 実行を前提にする。Codex の通常 sandbox では macOS の route socket / TCP probe / BatchMode SSH が高確率で判定不能になるため、HPC4 に関わる観測・SSH・転送 command は 初回から require_escalated で実行する。通常 sandbox で 1 回失敗させてから escalation するのは診断ではなく、既知の false negative を再生しているだけなのでやらない。
権限境界は 2 種類ある。混同しない：
route get、ping、nc、BatchMode SSH などが Operation not permitted 系で false negative になる状態。これは host route や pf を変更する操作ではない。status.sh、net-up.sh、net-down.sh、ssh-run.sh、xfer.sh のように経路・疎通・SSH 到達性を観測する command は、Codex では最初から require_escalated で呼ぶ。route add/delete、pfctl -F rules など、macOS の routing / packet filter を変更する操作。これは Codex 直実行では扱わない。user が自分の Terminal で net-up-local.sh / net-down-local.sh を実行した時だけ interactive sudo を許可し、その helper 内では必要な route / pf 修正を自動実行してよい。status.sh が [?] route socket 制限、[?] HPC4 egress：判定不能、[?] TCP 22 疎通：判定不能、[?] passwordless SSH：判定不能 を出した場合、Codex が通常 sandbox で実行してしまった可能性が高い。これは「HPC4 が壊れている」でも「ユーザ操作が必要」でもなく、Codex sandbox 内の観測が信用できないという意味。これは事故後の回復手順として扱い、同じ目的の command を require_escalated で実行し直して、その結果で分岐する。ユーザが escalation を拒否した、またはこの実行環境に escalation が無い場合だけ、「別ターミナルで同じ絶対パスの script を実行して確認」と案内する。
目的が queue 確認・ジョブ投入・ファイル転送など明確な場合、status.sh の [?] だけで作業を止めない。目的コマンド自体を初回から require_escalated で実行し、実到達性で判定する。
下表の scripts / helpers はすべて bash .codex/skills/hpc4/scripts/<name>.sh [args] の形で実行できる。Codex から呼ぶ HPC4 観測・SSH・転送 script は初回から require_escalated で実行する。例外は write-user-conf.sh のような純ローカル設定生成と、そもそも Codex から呼ばない *-local.sh helper だけ。ssh-run.sh / xfer.sh は ping が通れば直接 ssh、通らなければ net-up.sh を呼んで経路を診断するので、経路 OK のときは経路を意識せず目的の操作を直接呼んでよい。net-up.sh が user による sudo を要求した場合は exit 3 で抜けるので、その場合のみ net-up-local.sh を user の Terminal で実行してもらう。
| script | 引数 | 呼ぶべき場面 |
|---|---|---|
status.sh | なし | HPC4 関連作業の前にざっと健康状態を確認したい時、またはトラブル切り分け時 |
ssh-run.sh | '<command>' | HPC4 上で任意コマンドを実行したい時（squeue、sbatch、ls、cat 等。経路は自動整備） |
xfer.sh | put <l> <r> / get <r> <l> | 単一ファイルの往復（スクリプト、小さい結果ファイル等） |
xfer.sh | put-r <l> <r> / get-r <r> <l> | ディレクトリ単位の rsync 転送（大量結果の引き上げ等） |
net-up.sh | なし | 経路を診断したい時、status で TCP 22 不通を発見した時。Codex 直実行では sudo しない |
net-up-local.sh | なし | Codex は直接呼ばない。route / pf 操作に sudo が必要な時、または SSH key passphrase 入力が必要な時に、user が自分の Terminal で実行する helper。L3 正常 + TCP 22 不通なら pf main ruleset flush を 1 回だけ自動実行し、経路 OK 後に passwordless SSH 未成立なら候補鍵を選ばせて ssh-add まで実行する |
net-down.sh | なし | HPC4 host route と ControlMaster をリセットしたい時（トラブル時のみ）。route 削除は user 委任、ControlMaster close は自動実行 |
write-user-conf.sh | <itso_username> | user.conf.local を生成したい時（setup フロー A で使う） |
setup フロー（user.conf.local 生成 + passwordless SSH 確立）は単一の script ではなく 本ファイル後段の「setup フロー」節 に手順がある。Codex はそれを順に踏む。
/hpc4 で起動された時、または Codex が文脈から呼ぶ時の起点まず最初に bash .codex/skills/hpc4/scripts/status.sh を require_escalated で走らせ、その出力を見て分岐:
user.conf.local が無い → ユーザに ITSO 名を聞いて write-user-conf.sh で書き出し、もう一度 status.sh から始める[?] route socket 制限 または egress / TCP 22 / passwordless SSH が [?] → 通常 sandbox で誤実行してしまった事故として扱う。require_escalated で同じ status.sh を実行し直す。拒否・不可の場合だけ、別ターミナルで同じ script を実行してもらう[ng] HKUST 圏内 IF なし → status.sh が出した日本語の指示（「HKUST キャンパス内 eduroam か HKUST 有線、またはオフキャンパスなら Ivanti Secure Access を起動してください」）をそのまま提示。修正後に再開するよう案内し、setup を ここで止める（ssh-copy-id まで進めない）[ng] HPC4 host route：... stale pin または [ng] HPC4 egress：... HKUST 圏外 → user に bash .codex/skills/hpc4/scripts/net-up-local.sh を別ターミナルで実行してもらう。完了したら status.sh から再開[ng] TCP 22 不通 → bash .codex/skills/hpc4/scripts/net-up.sh を require_escalated で呼んで詳細診断する。Codex 直実行で実 L4 遮断なら net-up-local.sh を user Terminal で実行してもらう。net-up-local.sh 内では、L3 正常 + TCP 22 不通の時点で pf main ruleset flush を 1 回だけ自動実行して再判定する[ok] + passwordless SSH 未成立 → setup ステップ C を実行（まず net-up-local.sh で候補鍵の選択と ssh-add、それでも未成立なら選択鍵に対応する ssh-copy-id 案内）/hpc4 を直接打った場合は 何をしたいかを 1 文で聞く（例: 「HPC4 のセットアップは済んでいます。何をしますか？（例: queue 確認 / ジョブ投入 / ファイル転送 / 状態確認）」）。Codex 自律呼び出しの場合は文脈から目的の script を選んで進める143.89/16 または HKUST eduroam の 10.79/16）を持つ IF があるか」だけで判定する。製品名では分岐しないnet-up-local.sh を user Terminal で実行してもらうpfctl -F rules を 1 回だけ自動実行し、再判定するuser.conf.local（gitignored）に閉じる。リポジトリ本体には書かない[?] は unknown であり、失敗 verdict ではない。Codex sandbox では route / TCP / SSH probe が既知に判定不能になるため、status.sh、net-up.sh、net-down.sh、ssh-run.sh、xfer.sh は最初から require_escalated で実行する。通常 sandbox の [?] を見てから行動を決める設計にしない。素の Bash コマンド例を見ても、Codex tool 呼び出しでは sandbox_permissions="require_escalated" を付ける。ssh-add が必要な時は user に bash .codex/skills/hpc4/scripts/net-up-local.sh を自分の Terminal で実行してもらう。helper 内では route 修正、pf main ruleset flush、SSH agent への鍵追加を自動実行してよい。Codex 配下では sudo password / Touch ID prompt や passphrase prompt が silent fail し、呼び出し側が「成功した」と誤認する事故が起きるためWrite で書き出す。cp や chmod をユーザに打たせない。ssh-copy-id や sudo route のように特権/対話が必要なものは別ターミナル依頼が許容されるが、ネットワーク verdict が ok でない限り認証系の依頼はしない。また、別ターミナル依頼で渡す bash コマンドは必ず絶対パスで書く（user の新しいシェルは ~ で始まるためプロジェクト相対パスでは No such file になる）。各 script は出力時点で ${SKILL_DIR} を絶対化済みなので、status.sh / net-up.sh の出力をそのまま転送するのが安全hpc4.ust.hk (143.89.184.3)、Slurm account 既定値 watanabemc（user.conf.local で override 可能）143.89/16、または HKUST キャンパス eduroam の 10.79/16）を持つ IF が 1 つでもあれば動く。具体的には：HKUST キャンパス内 eduroam、HKUST 有線、Ivanti Secure Access (HKUST SSL VPN)。HKUST 以外の eduroam（DT Hub 等の HKSTP 施設、他大学、空港）は対象外 — 同じ SSID で繋がるが HKUST 内部 IP は降ってこない（policy.md 参照）。default route を別 VPN が握っていても、その VPN の kill-switch / packet filter / NEPacketTunnelProvider が 143.89.184.3 行きを遮断していなければ HPC4 だけは抜けられるゴール：user.conf.local を作成し、passwordless SSH が通る状態にする。ユーザには最大でも「ITSO ユーザ名を答える」「別ターミナルで 1 コマンド打って password+2FA を通す」の 2 アクションのみを依頼する。
起点は常に status.sh：Codex では require_escalated で実行し、interface 状態と HPC4 への到達性を分類してから動く。
.codex/skills/hpc4/user.conf.local が既に存在し、HPC4_USER が空でないなら、ステップ A を丸ごとスキップしてステップ B に進む。login4 に ssh するときの username）」。候補を ssh config / known_hosts / メールアドレス等から推定しようとしない。候補は無限にあり、聞いたほうが速く正確。bash .codex/skills/hpc4/scripts/write-user-conf.sh <username> を実行し、user.conf.local を生成。.gitignore に .codex/skills/hpc4/user.conf.local が含まれているか確認し、未登録なら追記。bash .codex/skills/hpc4/scripts/status.sh を require_escalated で実行し、出力の各 stage を見て分岐：
[ok] HKUST 圏内 IF：... + [ok] HPC4 経路：... + [ok] TCP 22 到達 OK → そのままステップ C へ[?] route socket 制限、[?] HPC4 egress、[?] TCP 22、[?] passwordless SSH → 通常 sandbox で誤実行してしまった事故として扱う。status.sh を require_escalated で実行し、[ok] なら続行、[ng] ならその [ng] の分岐に従う。escalation が拒否・不可の場合だけ、別ターミナルで同じ絶対パスの script を実行してもらう[ng] HKUST 圏内 IF なし → status.sh が出した日本語の救済文をそのままユーザに伝える（HKUST キャンパス内 eduroam / 有線、またはオフキャンパスなら Ivanti Secure Access）。修正後 /hpc4 で再開させ、ssh-copy-id まで進めない[ng] HPC4 host route：... stale pin → user に bash .codex/skills/hpc4/scripts/net-up-local.sh を別ターミナルで実行してもらう。完了したら再開[ng] HPC4 egress：... HKUST 圏外 → user に bash .codex/skills/hpc4/scripts/net-up-local.sh を別ターミナルで実行してもらう。完了したら再開[ng] TCP 22 不通 → bash .codex/skills/hpc4/scripts/net-up.sh を require_escalated で実行して詳細診断。Codex 直実行で sudo が必要なら net-up-local.sh を案内する。user Terminal helper 内で L3 正常 + TCP 22 不通になった場合は pf main ruleset flush を 1 回だけ自動実行し、flush 後も復旧しなければ user space から復旧不能として止める要点：Codex sandbox の観測制限を踏まえ、観測系 command は初回から escalation で実行する。Codex が直接呼ぶ scripts は sudo prompt を扱わない。route / pf 変更が必要な時は user Terminal 専用 helper に委任する。
前提：ステップ B のネットワーク verdict が [ok] であること。NG のまま進めない。
passwordless SSH 行を見る。net-up-local.sh を user の Terminal で実行してもらう。HPC4_IDENTITY_FILE が設定済みならその鍵を使い、未設定なら ~/.ssh/ から候補鍵を提示して選ばせる。暗号化された秘密鍵が agent 未登録なだけなら、この helper が ssh-add を実行し、Terminal 上で passphrase を入力させてから再判定する。net-up-local.sh 後も未成立の場合だけ、以下を 1 回だけ提示：
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519 を自動実行してよい（BatchMode 可）net-up-local.sh が出す選択鍵に対応した ssh-copy-id -i <selected-key>.pub <HPC4_USER>@hpc4.ust.hk を「別ターミナルで 1 回だけ実行してください（password + 2FA の入力が必要）」と案内bash .codex/skills/hpc4/scripts/ssh-run.sh 'hostname && whoami' を require_escalated で走らせて、login{N} と自分の username が返ってくることを確認。
Codex が shell から叩く際のテンプレート（パスは working directory 起点）。下の code block は Bash コマンド文字列だけを示す。Codex tool 呼び出しでは、write-user-conf.sh 以外の HPC4 観測・SSH・転送 command に必ず sandbox_permissions="require_escalated" を付ける：
# 状態確認
bash .codex/skills/hpc4/scripts/status.sh
# クラスタ状態の問い合わせ
bash .codex/skills/hpc4/scripts/ssh-run.sh 'squeue -u $USER' # 自分のキュー状況
bash .codex/skills/hpc4/scripts/ssh-run.sh 'savail' # パーティション空き
bash .codex/skills/hpc4/scripts/ssh-run.sh 'squota -A {account}' # group quota
# ジョブ投入の往復
bash .codex/skills/hpc4/scripts/xfer.sh put job.sh /scratch/$USER/job.sh
bash .codex/skills/hpc4/scripts/ssh-run.sh 'cd /scratch/$USER && sbatch job.sh'
bash .codex/skills/hpc4/scripts/xfer.sh get-r /scratch/$USER/results results/
判定の本質：HKUST 内部 IPv4（143.89/16 または HKUST eduroam の 10.79/16）を持つ IF がこの Mac に 1 つでもあるか。製品名で分岐しない。ifconfig を直接読む。
net-up.sh / status.sh 共通の core）find_hkust_iface：ifconfig を全 IF 走査して HKUST 内部 IPv4（143.89/16 または HKUST eduroam の 10.79/16）を持つ IF を探す — routing と独立した「HKUST 圏内能力」の判定。stale な host pin が route get を歪めても、ここは騙されない
current_hpc4_iface で既存の host pin を見て、HKUST 圏外 IF を指していたら → user に net-up-local.sh を実行してもらい削除。stale pin 起因の誤診断と「圏外」を別 path で報告するのが keyroute get 143.89.184.3 で kernel の自然な egress を見る — HKUST 圏外 IF を選んでいる稀ケースなら user に net-up-local.sh を実行してもらい host route を追加143.89/16、HKUST キャンパス eduroam は内部 NAT pool の 10.79/16）。IF がそのいずれかの IPv4 を持っているか否かで「HKUST 圏に居るか」を一意に判定できる。federated eduroam（DT Hub 等）はここで自動的に弾かれる（その施設の NAT が降ってくるだけで、HKUST 内部 IP は降ってこない）143.89/16 → utun の subnet route を入れるので、典型的には host pin 無しでも HPC4 に届く。pin が必要になるのは何かが natural route を阻害している場合のみSSH 側は ControlMaster で 12h persist、password+2FA は実質 1 日 1 回で済む。
Codex が直接呼ぶ scripts は sudo prompt や SSH key passphrase prompt を扱わない。route / pf 操作（host route add/delete、pf main ruleset flush）または暗号化鍵の ssh-add が必要な時は、scripts が bash .codex/skills/hpc4/scripts/net-up-local.sh を案内するので、user が自分の Terminal でそれを実行する。net-up-local.sh は interactive sudo を許可し、L3 正常 + TCP 22 不通では pfctl -F rules を 1 回だけ自動実行する。経路 OK 後、passwordless SSH が未成立なら HPC4_IDENTITY_FILE の明示鍵、または ~/.ssh/ から選択された候補鍵を ssh-add し、Terminal 上で passphrase を入力させてから再判定する。
これは Codex tool escalation とは別物。require_escalated は sandbox 外で read/probe command を実行して観測制限を外すための実行モードであり、sudo password / Touch ID を扱う仕組みではない。したがって観測系 command は初回から escalation で実行するが、route add/delete や pfctl -F rules のような実変更は user Terminal helper に委任し、helper 内で完結させる。
なぜ Codex 実行中の sudo / passphrase 入力を避けるか：Codex の shell 実行では sudo password / Touch ID prompt や SSH key passphrase prompt が user に届かない、または入力できない。route / pf 操作と ssh-add は user Terminal helper に委任することで、Codex に相談できない時でも user が terminal だけで完結できる設計になる。
bash .codex/skills/hpc4/scripts/status.sh を require_escalated で実行して現状を取り、どの層で落ちているか特定（ネットワーク / 認証 / ControlMaster）bash .codex/skills/hpc4/scripts/net-up.sh を require_escalated で実行して経路を診断。sudo が必要なら user に bash .codex/skills/hpc4/scripts/net-up-local.sh を実行してもらうbash .codex/skills/hpc4/scripts/net-down.sh を require_escalated で実行した後、net-up.sh を require_escalated で実行して完全リセットssh -F .codex/skills/hpc4/ssh_config -l <user> -vvv hpc4 を require_escalated で直接叩いて詳細ログを取るリポジトリを clone した人は /hpc4 を 1 回走らせれば（または Codex に「HPC4 のセットアップして」と頼めば）setup フローが起動して使える状態になる。事前作業は不要。
接続が通った後、HPC4 上で sbatch を回す側で踏みやすい罠を集約する。プロジェクト固有の事項は含まない。
--array=0-N を付けると 1 job が N+1 個の array task に展開される。各 task は独立に schedule・課金されるuser.conf.local の HPC4_ACCOUNT が既定値（未設定なら watanabemc）amd, intel, ...）。binary を compile した CPU と一致させる。ISA 不整合（avx2/avx512 命令を出した binary を持たない CPU で実行）は illegal instruction で即落ちするsacctmgr show qos {qos_name} format=Name,MaxSubmitPU,MaxJobsPU,MaxWall--array=0-149 を 1 回 sbatch すると 150 進む。MaxSubmit より大きい array は受理されないQOS の MaxSubmit を超える array job を続けて投げると QOSMaxSubmitJobPerUserLimit で reject される。現在の queue 数を見て、上限まで余裕がある分だけ投入する dispatcher を回すのが定石:
QUEUE_LIMIT=$((MaxSubmitPU - margin)) # 手動投入の余地を残す
ARRAY_SIZE=... # この sbatch で発行する task 数
while :; do
n_q=$(squeue -u "$USER" -h -t PD,R 2>/dev/null | wc -l)
if (( n_q + ARRAY_SIZE <= QUEUE_LIMIT )); then
break
fi
sleep 60
done
sbatch --parsable my_array.sh
-t PD,R は 必須: CG/CD/F も含めると終了済 job まで数えてしまう。
nohup ... & disown の生存性は OS / login shell / SSH client の組み合わせに依存し、SIGHUP が漏れて落ちるケースが実測される。安全側に倒すため、数時間以上回す dispatcher は tmux/screen の detached session に入れる。Codex tool 呼び出しでは ssh-run.sh を require_escalated で実行する:
bash .codex/skills/hpc4/scripts/ssh-run.sh 'tmux new-session -d -s {name} "bash dispatcher.sh > log 2>&1"'
# 復帰時
bash .codex/skills/hpc4/scripts/ssh-run.sh 'tmux list-sessions; tail -20 log'
dispatcher の生死は まず tmux list-sessions または ps -ef | grep dispatcher で確認する。log は補助情報に過ぎない: NFS の間欠 I/O で log に NULL byte が混入し grep が "binary file matches" を出したり tail が乱れたりすることがあるが、process が生存していれば dispatch 自体は正常に進行している。
| Path | 容量 | 永続性 |
|---|---|---|
/home/$USER | 200 GB | 永続。コード・設定・軽量結果 |
/project/{group} | TB 単位（group 共用） | 永続。大データセット |
/scratch/$USER | 500 GB | 60 日 inactive で削除。計算中間ファイル |
→ 残したい結果は home か project へ。scratch は揮発と意識する。
login node は共用なので CPU/I/O を握るスクリプトを直接走らせない:
squeue / ls / tail などの軽量問い合わせ、軽量 dispatcher、tmux、modules + 単発 make重い処理は srun --account={account} --partition={partition} --pty bash で interactive job に入る。
sacctmgr show qos {qos} format=Name,MaxSubmitPU,MaxJobsPU,MaxWall で QOS 上限を記録squota -A {account} で残り CPU-hour 確認これらは本 skill が既に対策を組み込んでいるが、症状を知っておくと debug が早い:
getaddrinfo は /etc/resolv.conf のみを参照する。Ivanti 等の split-tunnel VPN は scutil 側にしか DNS を push しないため、host hpc4.ust.hk は通るのに ssh hpc4 だけ "Could not resolve" になる → 本 skill の ssh_config は HostName を IP 直指定（HostKeyAlias で known_hosts 整合は維持）includeAllNetworks=true) や VPN クライアント独自の packet filter で塞がれる。kernel routing は正しいので、pf main ruleset flush でも復旧できない場合は skill 側からは復旧不能bash .codex/skills/hpc4/scripts/net-up.sh を require_escalated で再実行（冪等）scp -l は username ではなく bandwidth limit: ssh の -l user と違い、scp の -l は kbps 制限。username は -o User=... か user@host:path で渡す（本 skill の xfer.sh は ssh_config 経由で正しく渡している）すべて bash .codex/skills/hpc4/scripts/ssh-run.sh '<HPC4 上で実行する 1 行>' の形。Codex tool 呼び出しではすべて require_escalated で実行する：
# 自分の queue 内訳（job 名で集計）
bash .codex/skills/hpc4/scripts/ssh-run.sh 'squeue -u $USER -h -o "%j %T" | sort | uniq -c | sort -rn'
# QOS 上限と使用状況
bash .codex/skills/hpc4/scripts/ssh-run.sh 'sacctmgr -n -p show qos {qos_name} format=Name,MaxSubmitPU,MaxJobsPU,MaxWall'
# group の残り quota
bash .codex/skills/hpc4/scripts/ssh-run.sh 'squota -A {account}'
# partition の空き
bash .codex/skills/hpc4/scripts/ssh-run.sh 'savail'
# tmux + dispatcher log 末尾
bash .codex/skills/hpc4/scripts/ssh-run.sh 'tmux list-sessions; tail -20 ~/path/to/log'