🔒 復帰後の4連射を mv 1行で潰す: launchd キュー処理を冪等にする

月商ゼロから半年、Claude Code で自律環境を構築して今月は月商120万円です。仕組みが壊れる瞬間こそ、設計の甘さがむき出しになります。

なぜこの仕組みが効くのか

「作業で直す」と「環境で直す」の分岐点

自動化が壊れると、人は反射的に「次はこうしよう」という作業レベルの対策を探します。「ログをこまめに確認する」「手動でリトライする」「もう少し間隔を空ける」。この種の対策はすべて、問題が再発した時の傷を小さくするための処置です。原因を潰していないので、同じ条件が揃えば必ず再発します。

自動化システムを半年運用して確信したのは、スケジューラーと共有ディレクトリを組み合わせた構成は、排他制御を明示的に実装しない限り必ず競合する、という事実です。「運が悪ければ競合する」ではなく「競合する条件が揃えば必ず競合する」。確率の問題ではなく、構造の問題です。

2026年9月17日、Codex が丸1日 usage_limit_exceeded で止まりました。~/.codex/sessions/2026/09/17/ 配下には54セッションが積み上がり、全部が上限エラーで終了しています。この間、note-autolike・ai-portraits-fragments・social-autolike の3ワークフローに発注を撃ち続けた結果、~/dev/note-autolike/done/ ディレクトリに未処理の JSON が積み上がりました。翌朝05:20の実測で needs_imagegen_thumbnail フラグ付きの JSON が 43本から57本 に膨らんでいます。14本が新規に積み上がり、そのすべてが未処理のまま放置されていた状態です。

Codex が復帰した直後、5つの launchd レーンが一斉に起動しました。各レーンのピックアップスクリプトは done/ 配下の JSON を ls あるいは glob で取得して処理を始めます。排他制御がないので、同じ JSON を複数プロセスが同時に見に行く。結果として funnel-pm レーンは同一 JSON を 1分差で4回処理しました。8/11件が2連射以上という数字が示すように、これは偶発的な事故ではなく設計上の必然です。

launchd は「ファイルの取り合い」を知らない

com.lily.codex-note-funnel.plist の StartCalendarInterval を見ると、10:40と16:40の2エントリが設定されています。

<key>StartCalendarInterval</key>
<array>
    <dict>
        <key>Hour</key>
        <integer>10</integer>
        <key>Minute</key>
        <integer>40</integer>
    </dict>
    <dict>
        <key>Hour</key>
        <integer>16</integer>
        <key>Minute</key>
        <integer>40</integer>
    </dict>
</array>

launchd はこのスケジュールに従って run-codex-funnel.sh を呼び出すだけです。「前回の処理が終わったか」も「他のレーンが同じファイルを処理中か」も、launchd は一切関知しません。これは設計通りの正しい動作です。launchd はスケジューラーであって、ミューテックスではありません。ファイルキューの排他制御はアプリケーション層の責任、つまりピックアップスクリプト自身が実装すべき機能です。

蓄積＋一斉復帰が競合を顕在化させる

通常運転では、各レーンのタイミングが微妙にズレていることで競合が起きにくい状態が自然に保たれています。処理対象の JSON も1本ずつ順次追加されるため、複数レーンが同じファイルを同時に見る機会が少ない。

ところが Codex の usage_limit_exceeded のような長時間停止が入ると状況が一変します。停止期間中に57本の JSON が溜まった状態で全レーンが一斉起動する。

通常運転:
  レーンA → job_001 処理 → 完了
  レーンB → job_002 処理 → 完了  （タイミングがズレており競合しない）

Codex 復帰直後:
  レーンA ─┐
  レーンB ─┤──→ job_001 を同時取得 → 4連射
  funnel-pm ─┘
  （57本が溜まっており、全レーンが先頭ファイルに殺到）

「間隔を調整する」という作業対策では、この「一斉放出」パターンに対応できません。どれだけ間隔を縮めても、復帰直後の一瞬は必ず全レーンが同時に起動します。

ロックファイルでは不十分な理由

「lockファイルを作ればいい」という発想は自然です。しかし実装をよく見ると問題があります。

# NG: check-then-act は原子的でない
LOCKFILE=~/dev/note-autolike/.processing.lock
if [ ! -f "$LOCKFILE" ]; then
    touch "$LOCKFILE"
    process_file "$json"
    rm "$LOCKFILE"
fi

if [ ! -f ] で確認してから touch するまでの間に、別プロセスが割り込める「Time of Check to Time of Use（TOCTOU）」の窓があります。2つのプロセスが同時に「ファイルなし」を確認して両方が touch を実行する、これが競合です。高負荷・高頻度の環境では、この窓が実際に開きます。

さらに、プロセスが処理途中でクラッシュするとロックファイルが残り続けます。次回以降の全実行がロックを見て即退出するため、処理が完全に詰まります。クラッシュ後の回復手順を別途用意する必要があり、運用コストが上がります。

flock コマンドによるファイルロックも考えられますが、launchd がプロセスを新規生成するたびにファイルディスクリプタが引き継がれないため、レーン間での排他には機能しません。

autolike-plist-reconcile.sh が示したガードの思想

既存の ~/.claude/scripts/autolike-plist-reconcile.sh に、同じ問題意識で実装されたガードがあります。これは AUTOLIKE_TIMEOUT_SEC の値が plist と launchd のロード済み値でズレていた場合に reload するスクリプトですが、核心部は次のコードです。

pid=$(launchctl list | awk -v l="$L" '$3==l{print $1}')
if [ -n "$pid" ] && [ "$pid" != "-" ]; then
    echo "[$(date '+%F %T')] $L 実行中(pid=$pid) のため見送り ($have -> $want)" >>"$LOG"
    continue
fi
launchctl bootout "$D/$L" 2>/dev/null

スクリプト冒頭のコメントに「走行中のジョブを bootout するとその run のいいねが丸ごと消えるため、必ず待つ」とあります。launchctl list で PID を取得し、-（非実行中）でなければ bootout をスキップする。処理に入る前に「他者が既に処理中か」を確認し、そうならば即座に退出する——この発想が今回の mv パターンと同じです。

ただし PID チェックには限界があります。「確認」と「bootout」の間に新しいプロセスが起動する可能性をゼロにはできません。このスクリプトが動く文脈では許容範囲ですが、ファイルキューの排他取得には不十分です。より強力なアトミック操作が必要です。

全体の流れ

アーキテクチャ図：競合から解決まで

Codex usage_limit_exceeded から復帰
              │
              ▼
    ~/dev/note-autolike/done/ に 57 本が滞留
    ┌────────────────────────────────────────┐
    │  job_20260917_001.json                │
    │  job_20260917_002.json                │
    │  ...                                  │
    │  job_20260917_057.json                │
    └────────────────────────────────────────┘
              │
    5 レーンが launchd により一斉起動
    ┌────────────────────────────────────────┐
    │ com.lily.codex-note-funnel   (10:40)  │
    │ com.lily.autolike.note1               │
    │ com.lily.autolike.note2               │
    │ com.lily.autolike.funnel-pm  ← 4連射  │
    │ com.lily.autolike.social              │
    └────────────────────────────────────────┘
              │
    【修正前】各レーンが done/ を glob → 先頭ファイルを取得
              │  排他なし → 全レーンが job_001 を同時に read
              ↓
    funnel-pm が 1分差で同一 JSON を 4 回処理
    ─────────────────────────────────────────
    【修正後】mv による原子的所有権取得
    ┌────────────────────────────────────────┐
    │  mv done/job_001.json processing/     │
    │  ├─ 成功: 自プロセスのみが処理を継続   │
    │  └─ 失敗: 他プロセスが取得済み → exit 0│
    └────────────────────────────────────────┘
              │
    「1ファイル = 1プロセスのみ処理」が保証される

mv がアトミックである理由

同一ファイルシステム上の mv は、POSIX の rename(2) システムコールを1回で実行します。カーネルレベルで「ファイル名を変更する」という操作が不可分に完了するため、2つのプロセスが同時に mv done/job_001.json processing/job_001.json を実行しても、どちらか一方だけが成功し、もう一方は必ずエラーになります。「確認」と「取得」の間に窓が生まれません。

PID チェックと mv の根本的な違いはここにあります。PID チェックは「確認」と「処理開始」が別の操作です。mv は「確認」と「取得」が一つのシステムコールの中で完結します。

# 2プロセスが同時に実行した場合の挙動
# プロセスA: mv done/job_001.json processing/job_001.json → 成功（終了コード 0）
# プロセスB: mv done/job_001.json processing/job_001.json → 失敗（No such file or directory, 終了コード 1）

pickup スクリプトへの組み込み

run-codex-funnel.sh の先頭に差し込む実装です。

#!/bin/bash
set -uo pipefail

DONE_DIR=~/dev/note-autolike/done
PROCESSING_DIR=~/dev/note-autolike/processing
mkdir -p "$PROCESSING_DIR"

# done/ から処理対象を1本選ぶ
TARGET=$(ls "$DONE_DIR"/*.json 2>/dev/null | head -1)
[ -z "$TARGET" ] && exit 0          # 対象なし → 正常終了

BASENAME=$(basename "$TARGET")

# アトミックに所有権を取得。失敗 = 他プロセスが取得済み
mv "$TARGET" "$PROCESSING_DIR/$BASENAME" 2>/dev/null || exit 0

WORKING="$PROCESSING_DIR/$BASENAME"
# ここから先は自プロセスだけが処理する権利を持つ

mv が失敗する状況は実質1つです。他のプロセスが既に mv 済みでファイルが存在しない。これが競合した状況そのものなので、exit 0 で即退出するのが正しい応答です。エラーログを出す必要すらありません。

クロスデバイスの mv（別マウントポイントをまたぐ場合）はアトミックでないため注意が必要ですが、今回の構成では done/ と processing/ はどちらも ~/dev/note-autolike/ 配下にあり、同一ファイルシステムが保証されています。

com.lily.codex-note-funnel.plist との接合

com.lily.codex-note-funnel.plist の ProgramArguments は次の構成になっています。

<key>ProgramArguments</key>
<array>
    <string>~/.claude/scripts/claude-quota-guard.py</string>
    <string>--job</string>
    <string>com.lily.codex-note-funnel</string>
    <string>--priority</string>
    <string>--</string>
    <string>~/dev/note-autolike/run-codex-funnel.sh</string>
</array>

claude-quota-guard.py がクォータ制御のラッパーとして先行し、枠があれば run-codex-funnel.sh を起動します。pickup ロジックは run-codex-funnel.sh の中に収まっているため、スクリプトの先頭数行に mv による所有権取得を差し込むだけで対応が完結します。plist の修正は不要です。

launchd は今後も10:40と16:40に run-codex-funnel.sh を呼び出します。Codex の usage_limit_exceeded から復帰した直後に57本の JSON が溜まっていても、run-codex-funnel.sh が起動するたびに「まず mv で1本を取得し、失敗したら即退出する」という動作を繰り返します。funnel-pm レーンを含む5つのプロセスが同時に走っても、各ファイルを処理するプロセスは1つだけに絞られます。

実装の詳細

スクリプト全体像：防御レイヤーを重ねる順番

前半で示したのは mv の一行だけでしたが、実際に稼働させるには前後のレイヤーが必要です。com.lily.codex-note-funnel.plist の ProgramArguments を見ると、claude-quota-guard.py が先行ラッパーとして動き、その後 run-codex-funnel.sh が呼ばれます。スクリプトの全体像はこうなります。

#!/bin/bash
# launchd 環境の PATH は最小限のため先頭で上書きする
PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
export PATH

set -uo pipefail

DONE_DIR=~/dev/note-autolike/done
PROCESSING_DIR=~/dev/note-autolike/processing
PROCESSED_DIR=~/dev/note-autolike/processed
LOG=~/dev/note-autolike/logs/codex-funnel.log

mkdir -p "$PROCESSING_DIR" "$PROCESSED_DIR"

# 起動時リカバリ: 前回クラッシュで processing/ に残ったファイルを done/ へ戻す
for stale in "$PROCESSING_DIR"/*.json; do
    [ -f "$stale" ] || break
    age=$(( $(date +%s) - $(stat -f %m "$stale") ))
    if [ "$age" -gt 3600 ]; then
        mv "$stale" "$DONE_DIR/" 2>/dev/null
        echo "[$(date '+%F %T')] recovered stale: $(basename "$stale")" >> "$LOG"
    fi
done

# done/ から処理対象を1本選ぶ
TARGET=$(ls "$DONE_DIR"/*.json 2>/dev/null | head -1)
[ -z "$TARGET" ] && exit 0

BASENAME=$(basename "$TARGET")

# ─── ここが核心 ─────────────────────────────────────────
# アトミックに所有権を取得。失敗 = 他プロセスが取得済み → 即退出
mv "$TARGET" "$PROCESSING_DIR/$BASENAME" 2>/dev/null || exit 0
# ────────────────────────────────────────────────────────

WORKING="$PROCESSING_DIR/$BASENAME"

# クラッシュ時に processing/ へファイルが残るのを防ぐ EXIT トラップ
# 正常完了時は processed/ へ移動、異常時は done/ へ差し戻す
_cleanup() {
    local code=$?
    if [ $code -eq 0 ]; then
        mv "$WORKING" "$PROCESSED_DIR/$BASENAME" 2>/dev/null
    else
        mv "$WORKING" "$DONE_DIR/$BASENAME" 2>/dev/null
        echo "[$(date '+%F %T')] ERROR exit=$code, returned: $BASENAME" >> "$LOG"
    fi
}
trap '_cleanup' EXIT

# ── ここから先は自プロセスだけが $WORKING を処理する ──
echo "[$(date '+%F %T')] processing: $BASENAME" >> "$LOG"
# ... 本体処理 ...

なぜ PATH を先頭で上書きするのか

com.lily.codex-note-funnel.plist の EnvironmentVariables を見ると、キーは存在しますが中身は空の <dict/> です。

<key>EnvironmentVariables</key>
<dict>
</dict>

launchd がプロセスを起動するときの PATH は /usr/bin:/bin:/usr/sbin:/sbin という最小セットだけです。ターミナルで echo $PATH すると /usr/local/bin が含まれていますが、これは .zshrc や nvm の初期化スクリプトが追加しているものです。launchd はそのようなシェル初期化を実行しません。jq・node・python3 など /usr/local/bin に入っているツールは、plist から起動したスクリプトでは「コマンドが見つからない」という形でサイレントに失敗します。解決策は plist の EnvironmentVariables に書くか、スクリプト先頭でハードコードするかの二択です。 後者のほうがスクリプト単体で動作確認できて便利なので、私は先頭で export PATH する方針に統一しています。

set -uo pipefail と || exit 0 の組み合わせが必須な理由

set -uo pipefail が有効なとき、コマンドが非ゼロ終了コードを返すとスクリプト全体がそこで中断されます。mv は対象ファイルが存在しない場合に終了コード 1 を返します。これは「他プロセスが取得済み」という正常な競合シナリオと完全に一致します。

# NG: set -uo pipefail 環境では mv 失敗でスクリプトが非ゼロ終了する
mv "$TARGET" "$PROCESSING_DIR/$BASENAME" 2>/dev/null

# OK: 失敗を明示的に「正常な退出」に変換する
mv "$TARGET" "$PROCESSING_DIR/$BASENAME" 2>/dev/null || exit 0

2>/dev/null も対になって必要です。|| exit 0 だけでは stderr に "No such file or directory" が出力されます。com.lily.codex-note-funnel.plist の StandardErrorPath は ~/dev/note-autolike/logs/codex-funnel.error.log に向いているため、競合のたびに本来エラーでない行がエラーログに積まれます。ログを監視するとき「エラーログが増えている」というアラートが誤発火する原因になります。

autolike-plist-reconcile.sh が示した「二重チェック」の書き方

autolike-plist-reconcile.sh の PID チェック部分には、見落としがちな細かさがあります。

pid=$(launchctl list | awk -v l="$L" '$3==l{print $1}')
if [ -n "$pid" ] && [ "$pid" != "-" ]; then

launchctl list が返す最初のカラムは PID か - です。- はジョブが登録されているが現在実行中ではないことを意味します。[ -n "$pid" ] だけでは pid が - のときも「PIDあり」と判定されてしまいます。だから [ "$pid" != "-" ] を AND で繋いでいます。

この「変数が空でないこと」と「意味のある値かどうか」を分けてチェックする書き方は、mv パターンにも応用できます。mv の終了コードだけを見るのでなく、WORKING ファイルが実際に存在するかを確認する防御層を加えたい場合はこう書きます。

mv "$TARGET" "$PROCESSING_DIR/$BASENAME" 2>/dev/null || exit 0
# 念のため: mv が成功したはずなのにファイルがない（同一FSでない等）
[ -f "$WORKING" ] || { echo "FATAL: mv succeeded but file missing" >> "$LOG"; exit 1; }

この追加チェックは通常は到達しませんが、クロスデバイスの mv を誤って実行した場合に症状を明示してくれます。set -uo pipefail が有効な環境で黙って落ちるより、ログに原因が残るほうが後のデバッグが圧倒的に速いです。

起動時リカバリの設計思想

スクリプトの先頭に書いた「1時間以上前の processing/ ファイルを done/ へ戻す」処理は、デッドレター対策です。

age=$(( $(date +%s) - $(stat -f %m "$stale") ))
if [ "$age" -gt 3600 ]; then
    mv "$stale" "$DONE_DIR/" 2>/dev/null
fi

mv で所有権を取得した後にプロセスがクラッシュすると、ファイルは processing/ に残ります。EXIT トラップで done/ へ差し戻す設計にしてありますが、シグナル 9 で強制終了された場合などはトラップが動きません。翌朝に done/ を覗いても空、しかし処理は増えていない——という症状はこのパターンが原因です。リカバリを起動時に実行することで、次回の launchd 呼び出しで自動的に再キューに入ります。閾値を 3600 秒（1時間）にしているのは、正常な長時間処理を誤って差し戻さないためです。com.lily.codex-note-funnel.plist の StartCalendarInterval が 10:40 と 16:40 の2エントリなので、最大スケジュール間隔は6時間です。1時間はその範囲内で十分な安全マージンです。

---

私が詰まった話

詰まり1：競合が消えたのにエラーログが増え続けた

mv || exit 0 を実装した翌日、codex-funnel.error.log を見ると1件だった行が32件になっていました。処理件数は正常に増えています。4連射は消えた。なのにエラーログが増える。

最初は「どこかで例外が出ているのでは」と本体処理のデバッグを始めてしまいました。30分ほど追いかけてから気づいたのが 2>/dev/null の欠落です。最初に書いたコードはこうでした。

mv "$TARGET" "$PROCESSING_DIR/$BASENAME" || exit 0

|| は終了コードのハンドリングだけです。stderr への出力は止まりません。launchd は stderr を StandardErrorPath に書き続けます。結果として競合の瞬間のたびに「No such file or directory」が蓄積されました。

正しくはこうです。

mv "$TARGET" "$PROCESSING_DIR/$BASENAME" 2>/dev/null || exit 0

この2つを常にセットで書く習慣を持てていなかったのが原因です。「エラーログが増えた＝本体にバグがある」という先入観でデバッグの方向を誤りました。エラーログが増えたときはまず「正常な失敗を黙らせているか」を確認する、という順序を先に定型にしておくべきでした。

詰まり2：processing/ にファイルが溜まり続け、done/ が永遠に空に見えた

EXIT トラップを実装する前の版で起きた問題です。夜中に Codex がクラッシュするケースが数回続き、翌朝確認すると done/ は空なのに処理が回っていませんでした。

症状を追うと processing/ に5本の JSON が蓄積されていました。スクリプトは起動するたびに done/ を確認して TARGET が空なので exit 0 する。しかし「処理すべきファイル」は processing/ に詰まっています。

done/       ← 空（次の仕事はここに来る）
processing/ ← job_001.json, job_002.json ...  ← ゾンビ
processed/  ← 完了済み

この状態は実害が二重です。一つ目は処理の停止。二つ目は「詰まっていることが外から見えない」こと。done/ が空なので自動化が正常に見える。しかし done/ に新しいファイルが来ても processing/ のゾンビには誰も触れません。

直し方は2つを組み合わせました。EXIT トラップで差し戻すことと、起動時に古い processing/ ファイルをリカバリすることです。どちらか片方では不十分で、トラップが動かない強制終了に対応するにはスタートアップリカバリが必要です。実装後、processing/ ディレクトリを定期的に ls -la してファイルが滞留していないかを確認するだけで、この種の詰まりは翌朝には自動解消されるようになりました。

詰まり3：ターミナルで走らせると成功、launchd から起動すると無言で何もしない

最も時間を溶かした失敗です。run-codex-funnel.sh をターミナルで直接実行すると正常に JSON を処理します。launchd 経由だと codex-funnel.log に「processing: ...」が一切現れません。エラーログも空です。スクリプトは起動しているが、何もしていない。

原因の特定に使ったのは、launchd が起動するシェルをできるだけ忠実に再現する方法です。

env -i HOME="$HOME" PATH=/usr/bin:/bin:/usr/sbin:/sbin bash -l ~/dev/note-autolike/run-codex-funnel.sh

env -i で環境変数を最小化して走らせると、途中で jq: command not found が出ました。本体処理の中で JSON から needs_imagegen_thumbnail フラグを読み出すのに jq を使っていたのですが、jq は /usr/local/bin/jq にインストールされていました。set -uo pipefail が有効なので jq が見つからない時点でスクリプトが非ゼロ終了します。終了コードは codex-funnel.error.log に書かれるはずですが、エラーメッセージそのものが stderr に出ていなかった（jq がないのでエラーテキストも出ない）ため、ログが空でした。

com.lily.codex-note-funnel.plist の EnvironmentVariables が空であることを読んでいれば先に気づけた問題です。ファイルを実際に読む前に「たぶん PATH は大丈夫だろう」という思い込みで動作確認を省いたのが原因でした。以来、launchd 経由のスクリプトはすべて冒頭に PATH= を書くを絶対ルールにしています。

PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
export PATH

この一行が入っているかどうかを、コードレビューの最初に確認するようになりました。

詰まり4：ls *.json が「ファイルなし」で終了コード 2 を返してスクリプトが落ちた

done/ が空のとき、ls "$DONE_DIR"/*.json はシェルのグロブ展開に失敗し、終了コード 2 を返します。set -uo pipefail 環境では、これがスクリプトの異常終了を引き起こします。

# NG: done/ が空のとき ls が exit 2 → pipefail でスクリプト全体が落ちる
TARGET=$(ls "$DONE_DIR"/*.json | head -1)

# OK: 2>/dev/null でエラーを捨て、変数が空かどうかで判断する
TARGET=$(ls "$DONE_DIR"/*.json 2>/dev/null | head -1)
[ -z "$TARGET" ] && exit 0

この問題は done/ が空になるのが「異常」な設計ならば起きません。今回の構成は「通常運転では done/ が空の時間のほうが長い」設計なので、空が正常パスです。「空を正常として扱う」ためには、コマンドの失敗を明示的に吸収する行が必要です。

autolike-plist-reconcile.sh の書き方を見ると、continue を使ってループを抜ける場面が3回あります。

want=$($PB -c "Print :EnvironmentVariables:AUTOLIKE_TIMEOUT_SEC" "$P" 2>/dev/null) || continue
have=$(launchctl print "$D/$L" 2>/dev/null | ...) | head -1)
[ -n "$have" ] || continue
[ "$want" = "$have" ] && continue

|| continue が随所に入っています。「このレーンの情報が取れなければスキップ」という判断を、エラーを止めずに次に進む形で書いています。この「失敗を次の処理への指示に変換する」発想が、今回の mv ... || exit 0 と同じ思想です。エラーはログに残すものではなく、次のアクションへのシグナルとして使うもの——この視点に切り替えてから、スクリプトの見通しが格段によくなりました。

詰まり5：funnel-pm が4連射していると気づくのが1日後だった

最後の「詰まり」は技術というより観測の問題です。9月17日に4連射が起きていたことに気づいたのは翌09:18の05:20に processed/ の件数を数えたときです。ログを見ると1分差で同じJSONのエントリが4つ並んでいました。

問題が起きていた17時間、私は何も知りませんでした。ログは ~/dev/note-autolike/logs/codex-funnel.log に積まれていますが、誰もそれをリアルタイムで監視していません。「処理が重複した」という事実は、processed/ のファイル名が重複していることからしか検出できませんでした。

重複検出のワンライナーは今では毎朝の確認に使っています。

ls ~/dev/note-autolike/processed/ | sed 's/_[0-9]*$//' | sort | uniq -d

ファイル名のタイムスタンプ部分を除いてベース名で重複チェックします。これが何かを返したら、その日の処理に二重実行があったことになります。

重複をゼロにする構造改善（mv パターン）と、それとは独立して「重複があったことに気づける監視」を持つことは、別のレイヤーの問題です。壊れない設計を作りつつ、壊れたときに翌日ではなく当日中に気づける仕組みを持つ——この二段構えが、自動化を実収益につなぐ環境では欠かせません。

つまずきポイント

環境・構成系

• launchd は PATH を引き継がない。EnvironmentVariables ブロックが空のまま動かすと詰まる。com.lily.codex-note-funnel.plist の EnvironmentVariables は空になっており、launchd 起動時の実効 PATH は /usr/bin:/bin:/usr/sbin:/sbin だけです。nvm でインストールした codex はこの PATH には存在しません。run-codex-funnel.sh が set -uo pipefail を持っていても、「コマンドが見つからない」状況では -u は反応が遅れるケースがあります（which codex が空文字を返す）。診断は launchctl start com.lily.codex-note-funnel で手動起動してログを確認するのが最速です。

• Nice: 10 と LowPriorityIO: true はバースト処理と相反する。plist の両設定はシステム高負荷時にスクリプトの実行を後回しにします。Codex 復帰後に57本の JSON を一気に消化したいとき、Nice: 10 は「他のユーザー操作へ CPU を譲る」設定なので処理が遅れます。「バックグラウンドで静かに動く」と「復帰後に全力で消化する」は相反します。どちらを優先するか意図を決め、コメントに書いてください。現状の plist は前者を選んでいます。

• ThrottleInterval のデフォルトは launchd バージョン依存。非ゼロ終了が積み重なると StartCalendarInterval の定刻起動が飛ぶ。p2 の失敗3（exit 1 でスロットリング）と直結する話ですが、追記しておくと、10:40 がスロットリングで飛んだ場合、次の定刻は 16:40 まで6時間後です。codex-funnel.error.log（StandardErrorPath）に何も吐かれていない日を遡って確認するのが確実な診断法です。exit 0 を徹底すればデフォルトの ThrottleInterval 設定で問題ありませんが、「デフォルト任せ」ならその意図を plist のコメントかドキュメントに残してください。

• claimed/ ディレクトリ不在の mv 失敗と、競合回避の mv 失敗は同じ exit 0 を返す。p2 の失敗5で触れた問題ですが、根本にある設計上のトレードオフとして改めて書きます。「正常な競合回避」と「異常な環境不備」を同じ終了コードにすることで、launchd の Throttle を防げますが、問題の発見が遅れます。この沈黙の代償を支払う以上、外部監視が必須です。

mv クレームパターン固有のワナ

• クロスデバイス mv はアトミックでない。POSIX rename(2) がカーネルで直列化されるのは「同一ファイルシステム上」だけです。queue/ と claimed/ が別マウントポイント（例：NFS、Dockerボリューム、外付けドライブ）にまたがると、内部で copy + delete に分解され TOCTOU の窓が生まれます。今回の構成は両ディレクトリとも ~/dev/note-autolike/ 配下なので問題ありませんが、ディレクトリ構成を変更するときは df -h で同一ファイルシステムを確認してください。

• ファイル名のソート順が同秒作成で不安定になる。ls -1 "$QUEUE_DIR"/*.json | sort | head -1 の辞書順ソートは、ファイル名のタイムスタンプ部分が異なることを前提にしています。バッチ投入で1秒以内に複数ファイルが作成されると同名プレフィックスが衝突し、5レーンが異なるファイルを「先頭」として取得します。その結果、クレーム競合が起きずに全レーンが同時処理し、Codex セッションが5本同時起動します。回避策はファイル名にエポック秒 + PID サフィックスを入れること：job_$(date +%s)_$$_$(uuidgen | cut -d- -f1).json。

• claimed/ の残置ファイルが無音のデッドレターキューになる。処理が途中でクラッシュすると、ファイルは claimed/ に残ります。次の launchd 起動では queue/ を見るので claimed/ のファイルは永遠に取得されません。実際に、Codex 復帰後の2026年9月17日に claimed/ 内で複数本が止まっていた日がありました。claimed/ のファイルが1時間以上更新なしに存在したらアラートを出す監視を入れてからは、この状態に気づくまでのタイムラグがゼロになっています。

• claude-quota-guard.py が fd を継承する問題は mv クレーム後も残る。com.lily.codex-note-funnel.plist の ProgramArguments 先頭が ~/.claude/scripts/claude-quota-guard.py です。このPythonラッパーが subprocess.Popen で run-codex-funnel.sh を起動する間、launchd からはジョブが「実行中」に見えます。autolike-plist-reconcile.sh の PID チェック（launchctl list | awk -v l="$L" '$3==l{print $1}' で PID が - でないことを確認）が「codex-funnel は実行中」として reload を見送る判定は、この「ラッパーが生存中」の状態も正しく捕捉します。mv クレームで競合は消えましたが、ラッパー起動を前提にした PID の読み方は意識しておく必要があります。

• reconcile.sh のグロブが codex-note-funnel を対象外にしている。autolike-plist-reconcile.sh の対象は com.lily.autolike.*.plist です。com.lily.codex-note-funnel.plist は別ファイルで、このグロブにはマッチしません。reconcile が行う timeout 値の自動 reload が codex-funnel には効かないので、codex-funnel の timeout 設定変更時は手動で launchctl bootout + bootstrap が必要です。意図通りであればコメントで明記しておくと、半年後の自分が迷いません。

運用・監視系のワナ

• codex-funnel.log のローテーション未設定。plist の StandardOutPath は ~/dev/note-autolike/logs/codex-funnel.log に向いています。launchd はログをローテーションしません。1回あたり数十行のログが積まれ続けると1年で数十MBになります。newsyslog か logrotate での明示的なローテーション、またはスクリプト内での行数上限管理が必要です。

• 「ログが更新されない」を自動検知する仕組みがないと、週単位で止まりに気づかない。10:40 の起動後15分以内に claimed/ の更新タイムスタンプが変わっていなければアラートを飛ばす監視を別途入れています。exit 0 の設計は launchd との相性を最大化しますが、その代わりに「正常終了と無音障害が区別できない」という沈黙のリスクを持ちます。この監視スクリプトはオプションではなく、mv クレームパターンと対で入れるべきものです。

---

ベストプラクティス

自律環境を6ヶ月、月商120万円規模で回して固まったルールを、実コードに根拠を置いて示します。

1. mv による所有権取得をスクリプトの先頭に置く

引数バリデーション・ログ初期化・ディレクトリ確認より前に mv を叩きます。ファイルを取れなければ後続の処理を一切走らせる必要がありません。レーンあたりの CPU・メモリ使用を最小にしつつ、競合解決を最速でさばけます。

TARGET=$(ls -1 "$QUEUE_DIR"/*.json 2>/dev/null | sort | head -1)
[ -z "$TARGET" ] && exit 0
BASENAME=$(basename "$TARGET")
mv "${QUEUE_DIR}/${BASENAME}" "${CLAIMED_DIR}/${BASENAME}" 2>/dev/null || exit 0
# ここより下は自プロセスだけが実行する

2. クレーム成功はログに残し、失敗（競合回避）は無音にする

「成功 = ログあり、競合回避 = 無音」にすると grep "claimed:" codex-funnel.log | wc -l が今日の処理件数になります。フィルタ不要のカウントログは定期監視スクリプトの実装コストを大幅に下げます。exit 0 に 2>/dev/null をセットにするのは一貫したパターンです。

3. exit 0 を返すのは「正常な競合回避」と「queue が空」に限定する

「ディレクトリが存在しない」「権限エラー」「予期しない mv エラー」は exit 1 を返してください。無音終了が増えると障害の発見が遅れます。初期デプロイスクリプトで環境を整えた上で、スクリプト本体は「正常な退出だけが exit 0」という前提で書くと保守コストが下がります。

4. queue/ claimed/ done/ の3ディレクトリで状態を可視化する

ディレクトリ自体が状態を表すと ls ~/dev/note-autolike/claimed/ | wc -l で「詰まっているファイル数」が一発でわかります。フラグ管理や DB 不要で、ls だけが監視ツールになります。

5. ファイル名にエポック秒 + PID を入れてソート順を安定させる

FILENAME="job_$(date +%s)_$$_$(uuidgen | cut -d- -f1).json"

$$ は生成プロセスの PID です。同秒に複数ファイルが作成されても PID が異なれば辞書順が確定します。5レーン全員が同じファイルを先頭として選ぶ、という mv クレームパターンの前提が安定します。

6. reconcile.sh の「見送り理由を記録する」パターンを全スクリプトに統一する

autolike-plist-reconcile.sh 18〜22行目は、実行中のジョブを見つけたとき理由をログに残して continue します：

pid=$(launchctl list | awk -v l="$L" '$3==l{print $1}')
if [ -n "$pid" ] && [ "$pid" != "-" ]; then
  echo "[$(date '+%F %T')] $L 実行中(pid=$pid) のため見送り ($have -> $want)" >>"$LOG"
  continue
fi

「なぜ何もしなかったか」をログに残すパターンは、後からの障害追跡を劇的に楽にします。mv クレームで競合を解消した後も、この習慣は維持してください。

7. クラッシュ後の回復処理はメインスクリプトと分離する

claimed/ の残置ファイルを queue/ に戻す処理をメインスクリプトに組み込むと、2プロセスが同時に「残置ファイルを戻す → 再取得を試みる」という競合が再発します。回復は低頻度で起動する独立した監視スクリプトに委ねる設計を守ってください。

8. クレーム直後にサイドカーファイルで開始時刻を記録する

mv "${QUEUE_DIR}/${BASENAME}" "${CLAIMED_DIR}/${BASENAME}" 2>/dev/null || exit 0
echo "{\"claimed_at\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" \
  > "${CLAIMED_DIR}/${BASENAME}.claim"

.claim サイドカーに開始時刻を書くと「1時間以上経過した .claim を持つファイルを queue/ に戻す」という回復スクリプトが書けます。残置ファイルの老化検知が精度よくできます。

9. 初期デプロイスクリプトをべき等にして再実行可能にする

mkdir -p ~/dev/note-autolike/{queue,claimed,done,logs}

launchd の bootstrap を呼ぶ前にこれを実行するスクリプトを用意してください。ディレクトリが存在しないことで mv が無音失敗するという、p2 の失敗5の再現を構造的に防ぎます。

10. レーン間のログファイルを分離し、行の混ざりを防ぐ

plist の StandardOutPath: codex-funnel.log、StandardErrorPath: codex-funnel.error.log という設定はレーンごとに別ファイルを指しており、これは正しいです。5レーンが同時起動する復帰後の状況で共有ログが混ざると、何が起きたかの再現が不可能になります。ラベル名（com.lily.codex-note-funnel）をログファイル名に含めるのが最低ラインです。

11. ThrottleInterval の挙動を意識して設定の意図を明示する

exit 0 を徹底すれば launchd のデフォルト ThrottleInterval で問題は起きません。ただし「デフォルト任せ」であることを意識的に選択し、plist か運用ドキュメントにその理由を書いておいてください。半年後にトラブルが起きたとき「設定を変えていないのになぜ？」という混乱が防げます。

12. 同一ファイルシステムを df -h で確認してから queue/ と claimed/ を配置する

アトミック性の前提を崩す最大のリスクはクロスデバイス mv です。ディレクトリを変更するたびに確認する習慣をデプロイスクリプトに組み込んでください：

queue_dev=$(df -P "$QUEUE_DIR" | awk 'NR==2{print $1}')
claimed_dev=$(df -P "$CLAIMED_DIR" | awk 'NR==2{print $1}')
[ "$queue_dev" = "$claimed_dev" ] || { echo "ERROR: cross-device mv"; exit 1; }

---

まとめ

Codex の usage_limit_exceeded から復帰した2026年9月17日に起きた「funnel-pm レーンが同一 JSON を1分差で4回処理する」問題は、設計上の必然でした。57本の JSON が溜まった状態で5レーンが一斉起動すれば、排他制御を持たない pickup スクリプトは確率ではなく構造的に衝突します。launchd はスケジューラーであり、ミューテックスではないからです。

解決は1行でした。

mv "$TARGET" "$CLAIMED_DIR/$BASENAME" 2>/dev/null || exit 0

POSIX の rename(2) は同一ファイルシステム上でカーネルが直列化します。「確認してから取得する」PID チェックとは根本的に異なり、確認と取得が1システムコールの中で完結します。fd 継承問題を抱える flock とも違い、プロセスの生死とロックが切り離されています。ファイル自体がクレームのトークンになるため、クラッシュしても残置ファイルが人間にとって読みやすい状態で残ります。

autolike-plist-reconcile.sh の「走行中なら何もしない」という PID チェックパターンと、今回の mv クレームパターンは同じ思想から生まれています。差分は「TOCTOU を持つかどうか」だけです。どちらも「他者が処理中なら退出する」という選択を最初の操作で行う設計です。

自律環境を長期間安定させるには、この種の「競合をそもそも許さない構造」を積み重ねていくしかありません。作業対策は事象の傷を小さくし、環境対策は事象を消す。月商0円から6ヶ月で120万円の規模に持っていけたのは、壊れた日に「次はこうしよう」ではなく「構造を直す」選択を繰り返したからです。

---

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。
📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

---

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

• 制作物・記事は bokuwalily.com にまとめています🖥️
• AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事 に💰
• OSS: github.com/bokuwalily 🐙
• 最新情報・お問い合わせは X @bokuwalily へ🌍
• AI導入・自動化の相談と実装テンプレ7本の配布は 公式LINE から💬

皆さんの ❤️ やシェアが励みになります！