🔐 launchdがiCloud保護フォルダに書けない問題と自己回復型リトライの設計

自動化スクリプトが「動いている」ように見えるのに、肝心のファイルは一切更新されていない——そんな体験をしたことはありますか。Lily は今年の春、Claude Code との会話ログを Obsidian Vault に毎晩自動で取り込む仕組みを作っていたとき、まさにこの落とし穴にはまりました。スクリプトはエラーなく終了するのに、Vault の中身は何も変わらない。ログを漁ってようやくわかったのは、macOS の TCC（Transparency, Consent, and Control）という仕組みが、システムのバックグラウンドタスク管理エンジン「launchd」からの書き込みを静かにブロックしていたということでした。

「TCC」と聞くと難しそうですが、要するに macOS のプライバシー番人です。アプリやスクリプトが勝手にあなたの写真やドキュメントを読み書きできないよう、OS が検閲しています。特に iCloud Drive で同期している `~/Documents` 配下のフォルダは強く保護されており、バックグラウンドで動く launchd のジョブがそこへ書き込もうとすると、エラーも出さずに無視されることがあります。

この記事では、`vault-auto-ingest.sh` という実際のスクリプトを題材に、TCC 問題の根本原因から解決策、そして「失敗しても次の機会に自動でやり直す」自己回復型設計までを解剖します。フルディスクアクセスの付与、iCloud が symlink を壊す罠、caffeinate によるスリープ対策、lockdir による二重実行防止、そして複数発火スロットと done マーカーを組み合わせた「成功するまでリトライ・成功後は即終了」パターンを、実際のコードと検証コマンドで順を追って説明します。

何を作ったか——全体構成

Lily が作ったのは「夜間オートingest」と呼んでいる仕組みです。Claude Code との会話ログを毎晩自動でまとめて、個人のナレッジベース（Obsidian Vault）に書き込み、翌朝の「今日のブリーフ」まで生成するパイプラインです。

登場するファイルと場所を先に整理します。

スクリプト本体を `~/Documents` 内ではなく `~/.claude/scripts/` に置いているのも TCC 対策の一環です。launchd は TCC 保護下のパスにあるスクリプトをそもそも実行できないため、スクリプト自体は保護外のディレクトリに置く必要があります。スクリプト冒頭のコメントにもその理由が記してあります。

# スクリプト自身は ~/.claude/scripts/（保護外）に置く（~/Documents だと launchd から exec 不可）。

TCC の正体——iCloud フォルダが「保護対象」になる理由

TCC とは何か

TCC は macOS が管理する「アプリのアクセス権台帳」です。カメラ、マイク、連絡先、そして「フルディスクアクセス（FDA）」などがこの台帳で管理されています。ユーザーが直接操作する通常アプリは「このアプリに許可しますか？」というダイアログで権限を取得できます。

問題は、launchd はユーザーに代わって起動するバックグラウンドの仕組みだという点です。launchd から起動されたスクリプトは「誰が起動したか」という文脈が通常の操作と異なるため、iCloud Drive で同期中の `~/Documents` に対して書き込み権限を持たない状態で動きます。

サイレント失敗の恐ろしさ

特に怖いのがサイレント失敗です。権限不足で書き込みに失敗しても、エラーコードが返らず、スクリプトが `exit 0`（正常終了）で終わることがあります。何も起きていないのに「成功した」と思わせる最悪のパターンです。Lily がこの問題に気づくのに数日かかったのも、ログに何も残らなかったからでした。

実際のスクリプトでは、これを早期検知するためのプリフライトチェックが入っています。

if ! ( cd "$VAULT" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1 ); then
  echo "[$(date '+%F %T')] ❌ FDA未付与: launchdから Vault にアクセス不可(TCC保護)。" >> "$LOG"
  echo "    解決: システム設定 > プライバシーとセキュリティ > フルディスクアクセス で /bin/bash を許可。" >> "$LOG"
  notify_fail "FDA未付与: vault にアクセス不可（設定→フルディスクアクセス→/bin/bash）"
  exit 1
fi

`cd` して `git rev-parse --git-dir` を実行するだけです。これが通れば Vault にアクセスできている証拠、通らなければ TCC にブロックされています。この一節でサイレント失敗が「大声の失敗」に変わります。失敗を沈黙させないことが、自己回復設計の出発点です。

フルディスクアクセス（FDA）を /bin/bash に付与する

解決策は、macOS のシステム設定から `/bin/bash` にフルディスクアクセスを付与することです。操作手順は次の通りです。

1. アップルメニュー →「システム設定」を開く

2.「プライバシーとセキュリティ」→「フルディスクアクセス」を選ぶ

1. 右下の「＋」ボタンを押してファイル選択ダイアログを開く
2. `Shift + Cmd + G` を押して `/bin/bash` と入力し、追加する
3. `/bin/bash` のスイッチがオンになっていることを確認する

この設定は一度やれば次からは不要です。ただし、OS のメジャーアップデート後に権限がリセットされることがあるため、アップデート後に挙動がおかしいと感じたらまずここを確認してください。

設定後の確認は次のコマンドで手軽にできます。

/bin/bash -c "cd ~/Documents/claude-obsidian && git status"

これが通常のターミナルで動くことは当然ですが、launchd から実行した場合に通るかどうかを確認するには、前述のプリフライトチェックをスクリプトに組み込み、ログを見るのが確実です。`~/.claude/logs/vault-auto-ingest.log` を開いて `❌ FDA未付与` の行が出ていなければ権限は通っています。

symlink を iCloud が破壊する罠

FDA を付与する前に思いつく回避策として「Vault への symlink を `~/Documents` 外に作ればいいのでは」というアイデアがあります。iCloud の保護対象外のパスから symlink でアクセスすれば、制限をすり抜けられるのでは、という発想です。

残念ながら、iCloud がこの手法を破壊します。

iCloud は同期中のフォルダを常時監視しており、その中の symlink を「通常のファイルと同じもの」として扱おうとします。実際に起きるのは、iCloud が symlink を実体ファイルにコピーしたり、競合ファイルとして処理したりして、リンク先が意図しないパスに書き換えられるなどの問題です。スクリプトのコメントには実際の検証日とともに明記されています。

# symlinkで ~/ に逃がす案は iCloud が symlink を競合処理して壊すため不可（2026-06-01 検証済み）。

この教訓から、スクリプトの置き場は最初から `~/.claude/scripts/` に固定しています。「symlink で回避する」という発想は魅力的に見えますが、iCloud 同期フォルダが絡む場合は使えないと覚えておいてください。FDA を正面から付与するのが、遠回りに見えて最も確実な道です。

caffeinate でスリープ凍結を防ぐ

なぜスリープが問題になるのか

macOS はバッテリー節約のため、蓋を閉じたり一定時間操作がないとスリープします。スリープ中はバックグラウンドスクリプトも途中で止まります。Claude Code のログを Obsidian に取り込む処理は 40〜50 分かかることがあるため、途中で凍結すると半端なマーカーだけが残り「完了済みだが実際は未完了」という状態が生まれます。

caffeinate の使い方

`caffeinate` はスリープを抑止する macOS 付属のコマンドです。スクリプトの冒頭に次の一節があります。

if [ -z "${CAFFEINATED:-}" ]; then
  exec /usr/bin/caffeinate -i -s env CAFFEINATED=1 /bin/bash "$0" "$@"
fi

`-i` フラグが「アイドルスリープを防ぐ」、`-s` フラグが「システムスリープを防ぐ（ただし AC 電源接続時のみ有効）」を意味します。`CAFFEINATED` という環境変数を立てることで、caffeinate 配下で再実行されたときに無限ループしないようになっています。

caffeinate の限界と timeout の組み合わせ

重要な注意点があります。 `-s` はバッテリー駆動中は効きません。充電ケーブルを外して蓋を閉じると、caffeinate があっても OS がシステムスリープを優先する場合があります。これが後述する「複数スロット発火」が必要な理由のひとつです。

スリープで凍結したランが wake 後にゾンビ化しないよう、重い処理にはすべて `timeout` が被せてあります。

TIMEOUT_BIN="/opt/homebrew/bin/timeout"
run_to() { local s=$1; shift; if [ -n "$TIMEOUT_BIN" ]; then "$TIMEOUT_BIN" --kill-after=30 "$s" "$@"; else "$@"; fi; }

`--kill-after=30` は「SIGTERM を送って 30 秒後にまだ生きていたら SIGKILL を送る」という意味です。GNU coreutils の `timeout` が見つからない場合は素通しにして、少なくとも動作は継続できるようにしてあります。凍結したランは timeout で刈り取られ、次のスロットがやり直す——これが自己回復サイクルの基本単位です。

lockdir による二重実行防止

なぜ二重実行が起きるのか

複数の発火スロットを設定していると、前のランがまだ動いているのに次のスロットが起動することがあります。また、launchd の定時発火と手動でのデバッグ実行が重なる場合もあります。実際にスクリプトのコメントには `2026-06-10 に launchd 分と手動分のレースが実発生` と記録されています。二重実行が起きると、Vault への書き込みが競合し、git のコミットが壊れることがあります。

mkdir ロックの仕組み

二重実行を防ぐにはロックが必要です。ファイルシステムでアトミックなロックを実現する定番手法が `mkdir` ロックです。

LOCKDIR="$HOME/.claude/locks/vault-auto-ingest.lock"
if ! /bin/mkdir "$LOCKDIR" 2>/dev/null; then
  oldpid=$(cat "$LOCKDIR/pid" 2>/dev/null || true)
  if [ -n "${oldpid:-}" ] && kill -0 "$oldpid" 2>/dev/null; then
    echo "[$(date '+%F %T')] 別インスタンス実行中(pid=${oldpid}) — skip" >> "$LOG"
    exit 0
  fi
  rm -rf "$LOCKDIR"
  /bin/mkdir "$LOCKDIR" 2>/dev/null || exit 0
fi
echo $$ > "$LOCKDIR/pid"
trap 'rm -rf "$LOCKDIR"' EXIT INT TERM

`mkdir` はファイルシステムのアトミック操作なので、2 つのプロセスが同時に `mkdir` しようとすると片方だけが成功します。`LOCKDIR/pid` にプロセス ID を書き込んでおき、2 番目のプロセスが来たときに `kill -0 $oldpid` でそのプロセスが生きているか確認します。生きていればスキップ、死んでいれば（クラッシュして lock が残った「stale lock」）ロックを消して自分が引き継ぎます。

`trap 'rm -rf "$LOCKDIR"' EXIT INT TERM` は、スクリプトが正常終了・Ctrl-C・強制終了のどれで終わってもロックを必ず解放するための記述です。これがないと、クラッシュ後に次のランが永遠にロック待ちになります。

複数スロット発火と done マーカーによる自己回復リトライ

plist の4スロット設定

`com.shun.vault-auto-ingest.plist` には4つの発火時刻が登録されています。

<key>StartCalendarInterval</key>
<array>
  <dict><key>Hour</key><integer>4</integer><key>Minute</key><integer>55</integer></dict>
  <dict><key>Hour</key><integer>8</integer><key>Minute</key><integer>15</integer></dict>
  <dict><key>Hour</key><integer>10</integer><key>Minute</key><integer>15</integer></dict>
  <dict><key>Hour</key><integer>12</integer><key>Minute</key><integer>15</integer></dict>
</array>

4:55 は「深夜に静かに走らせる本命スロット」です。ただしスリープ中だと動けないため、朝 8:15、10:15、12:15 の3スロットがキャッチアップとして控えています。重要なのは、これらが単純な繰り返しではなく「成功したら残りをスキップ、失敗したら次が引き継ぐ」という設計になっている点です。

done マーカーで「成功後は即終了」

スクリプトの冒頭に次の行があります。

TODAY=$(date +%Y%m%d)
DONE_MARKER="$HOME/.claude/logs/.vault-ingest-done-${TODAY}"

[ -f "$DONE_MARKER" ] && exit 0

`.vault-ingest-done-20260702` のような日付入りのファイルが存在すれば、即 `exit 0` で終了します。このファイルはすべての処理が成功した後にだけ `touch` されます。成功した時点でその日の処理は完了し、残りのスロットは空振りで終わります。失敗した場合はマーカーが作られないので、次のスロットが再度試みます。

マーカーは毎日日付が変わると自動的に「存在しない」状態になるため、翌日は新鮮な状態から始まります。また、7日より古いマーカーは定期的に掃除されます。

find "$HOME/.claude/logs" -maxdepth 1 -name '.vault-ingest-*' -mtime +7 -delete 2>/dev/null

段階マーカーで途中から再開する

長い処理をひとつの done マーカーだけで管理すると、途中まで成功していても毎回最初からやり直しになります。それを防ぐために「段階マーカー」が使われています。

STEP2A_MARKER="$HOME/.claude/logs/.vault-ingest-step2a-claude-${TODAY}"
STEP2B_MARKER="$HOME/.claude/logs/.vault-ingest-step2b-codex-${TODAY}"

Claude Code のログ処理（step2a）と Codex のログ処理（step2b）が独立したマーカーを持っています。step2a が完了していれば step2a はスキップし、step2b だけを再試行するという粒度で再開できます。

[ -f "$STEP2A_MARKER" ] && [ -f "$STEP2B_MARKER" ] && touch "$STEP2_MARKER"

両方揃ったときだけ `STEP2_MARKER` が立ち、最終的に全工程完了で `DONE_MARKER` が立つ、という3層構造です。この設計の背景にはログが記されています。Vault への書き込みが40分枠に収まらず連日タイムアウトしていた問題（hot.md が凍結していた真因）を受けて、ソース別に処理を2本に分割し、各々に軽い timeout を設定しました。

失敗を Desktop に可視化する

自動化の失敗で最もまずいのは「失敗していることに気づかない」ことです。ログファイルを毎朝確認する習慣がなければ、数日間 Vault が更新されていなくても誰も気づきません。

このスクリプトは失敗時に Desktop に Markdown ファイルを作成します。

FAILED_FILE="$HOME/Desktop/Daily Brief/FAILED-${TODAY}.md"
notify_fail() {
  local reason="$1"
  mkdir -p "$HOME/Desktop/Daily Brief" 2>/dev/null
  { echo "# Daily Brief 生成失敗 — $(date '+%F %T')"; echo ""
    echo "- 理由: ${reason}"
    echo "- 詳細ログ: ~/.claude/logs/vault-auto-ingest.log"
    echo "- 自動再試行: 8:15 / 10:15 / 12:15 とログイン時（成功したらこのファイルは自動で消える）"
  } > "$FAILED_FILE" 2>/dev/null
  /usr/bin/osascript -e "display notification \"${reason}\" with title \"Daily Brief 生成失敗\"" >/dev/null 2>&1
}

`FAILED-20260702.md` というファイルが Desktop の「Daily Brief」フォルダに現れれば、一目で今日の処理が失敗していることがわかります。`osascript` による macOS 通知も飛ぶので、作業中であれば気づけます。

成功した瞬間にこのファイルは削除されます。「失敗中だけ存在するファイル」という設計で、平常時に邪魔になりません。さらに、連続障害で過去日の `FAILED-*.md` が複数溜まっている場合は、当日成功時に過去日分もまとめて掃除されます。

find "$HOME/Desktop/Daily Brief" -maxdepth 1 -name "FAILED-*.md" ! -name "FAILED-${TODAY}.md" -delete 2>/dev/null

この3段階——「プリフライトで大声の失敗に変える」「Desktop に失敗ファイルを作る」「osascript で通知を飛ばす」——が揃って初めて、サイレント失敗のリスクを実用的に抑えられます。

検証コマンドと使い回すときの注意

全体ヘルスを一発確認する

`automation-health.sh` を実行すると、launchd の登録状況・各バッチの最終実行時刻・Vault の鮮度・ログの重複など、自動化基盤全体の健全性を一括確認できます。

bash ~/.claude/scripts/automation-health.sh

出力は `✓`（正常）、`⚠`（警告）、`✗`（障害）の三段階で色分けされます。赤が一つでもあれば `exit 1` で終わるため、CI やスクリプトから呼び出してチェックすることもできます。スクリプトは launchd ジョブのロード状態、hooks スクリプトの存在と実行権限、Vault の hot.md の鮮度、cron と launchd の二重登録、ディスク肥大まで横断的に確認します。

vault-auto-ingest を手動テストする

動作確認は done マーカーを一時退避してから行います。

mv ~/.claude/logs/.vault-ingest-done-$(date +%Y%m%d) /tmp/ 2>/dev/null
bash ~/.claude/scripts/vault-auto-ingest.sh
tail -f ~/.claude/logs/vault-auto-ingest.log

テスト後は `/tmp/.vault-ingest-done-*` を `~/.claude/logs/` に戻すか、そのまま今日分の完了マーカーとして残します。launchd のロード状態は次のコマンドで確認できます。

launchctl list | grep com.shun.vault-auto-ingest

PID 列に数字があれば実行中、ハイフンなら待機中です。last exit が `0` 以外なら前回のランが失敗しています。`exit 78` が続く場合はクラッシュループの可能性があり、plist の設定ミスや依存ファイルの欠落を疑ってください。

別のプロジェクトに転用するときの注意点

この設計を別の用途に転用するときに特に気をつけるべき点をまとめます。

スクリプトの置き場所: `~/Documents` または iCloud 同期対象のどのディレクトリにも置かないこと。launchd からの exec が通りません。`~/.local/bin/` や `~/.claude/scripts/` など、ホームディレクトリ直下の隠しフォルダが安全です。

plist の StandardOutPath/StandardErrorPath: 標準出力の向き先も iCloud 外に設定します。`~/Documents` に出力しようとすると、ログすら書けずに詰まります。設定ファイルの中でパスを指定するとき、`~/` ではなくフルパスで書く必要があることにも注意してください。plist は `~` の展開をしません。

PATH の補完: launchd が起動するシェルは最小 PATH（`/usr/bin:/bin` 程度）しか持っていません。Homebrew の `timeout`、nvm の `node`、`git` など、自分でインストールしたツールはスクリプト内で PATH を明示的に補う必要があります。

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"

`vault-auto-ingest.sh` では nvm の node もバージョン非依存の方法で検索して PATH に追加しています。Vault の git commit フック（node 製）が動かなければ `git commit` 自体が失敗するため、この一手間が欠かせません。

symlink は使わない: iCloud 同期フォルダ内への symlink は iCloud によって破壊されます。2026-06-01 の検証で確認済みです。この回避策は機能しないため、FDA を正面から付与するのが正解です。

これらの問題は、インターネット上に情報が少なく、実際に手を動かして一つずつ確認するまで原因の特定が難しいものばかりです。TCC による FDA の必要性、iCloud の symlink 破壊、caffeinate のバッテリー制限、マーカーによる自己回復——それぞれが独立した問題でありながら、すべてが噛み合って初めて「信頼できる自動化」が完成します。同じ構成を組む際の調査コストを少しでも下げられれば、この記事を書いた目的は達成です。

📕 この記事の内容を、実装まで全部まとめた有料記事があります 手順・コード・テンプレをそのまま渡しています AIで「寝てても回る仕組み」をゼロから30日で組む全手順