無人実行のエージェントをタイムアウトで止めたとき、書きかけのファイルが残る問題

書き込みを原子的にする — temp と rename

ファイルシステムにおける最も確実な原子的書き込みは、昔ながらの「別名の一時ファイルに全部書き切ってから、目的のパスへ rename する」パターンです。同一ファイルシステム上の rename（mv）はアトミックなので、目的のパスには「完全に書けた状態」か「まだ存在しない状態」のどちらかしか観測されません。書き込みの途中状態が外から見えることはありません。

bash で無人実行に組み込むなら、こうなります。

#!/usr/bin/env bash
set -euo pipefail
 
# 出力先と、同じディレクトリ内のユニークな一時ファイル
DEST="out/articles/result.json"
RUN_ID="$(date +%s)-$$"                 # 秒 + PID で実行ごとに一意
TMP="$(dirname "$DEST")/.tmp.${RUN_ID}.json"
 
# 途中で死んでも temp を必ず片付ける
cleanup() { rm -f "$TMP"; }
trap cleanup EXIT INT TERM
 
# エージェントの出力を temp に書き切る
agy run generate-article --out "$TMP"
 
# 書けた中身を確かめてから初めて原子的に公開する
[ -s "$TMP" ] || { echo "empty output"; exit 1; }   # サイズ0を弾く
python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$TMP"   # 壊れたJSONを弾く
 
mv -f "$TMP" "$DEST"     # 同一FS上の rename はアトミック
trap - EXIT
echo "published: $DEST"

ここで効いているのは三点です。第一に、エージェントには temp に書かせること。目的のパスに直接書かせると、殺された瞬間にそのパスが壊れます。第二に、trap ... EXIT INT TERM でどんな止まり方をしても temp を消すこと。タイムアウトの SIGTERM もここで拾えます。第三に、mv の直前にサイズと中身の妥当性を検証すること。検証を通った場合だけ公開へ進みます。

Node で書く場合も考え方は同じで、fsync を挟んでから rename します。

import { writeFile, rename, open } from "node:fs/promises";
import { dirname, join } from "node:path";
 
async function atomicWrite(dest, data) {
  const runId = `${Date.now()}-${process.pid}`;
  const tmp = join(dirname(dest), `.tmp.${runId}`);
  await writeFile(tmp, data, "utf8");
 
  // OSバッファをディスクへ確定させてから rename する
  const fh = await open(tmp, "r");
  await fh.sync();
  await fh.close();
 
  await rename(tmp, dest);   // 同一FS上ではアトミック
}

fsync（Node の fh.sync()）を入れる理由は、rename 自体はアトミックでも、電源断などで「rename は済んだのにファイル本体のデータがまだディスクに届いていない」状態が理論上ありうるからです。無人で連続稼働させるなら、ここを省かないほうが安全だと考えています。

「前回の残骸」を踏まないための二つの規律

原子的書き込みは半分書けたファイルを根絶しますが、固定名 temp の混入は別の規律で防ぎます。私はこの問題で痛い目を見てから、二つを必ず守るようにしています。

1. 一時ファイルに固定名を使わない

/tmp/insert.txt のような固定名は、書き込みに失敗した回の残骸が次回そのまま読まれる温床です。上のコードのように 実行ごとに一意な名前（秒 + PID、あるいは対象の slug を含めた名前）を付ければ、前回の temp を今回が拾うことは構造的に起こりません。さらに temp は出力先と同じディレクトリに置きます。別ファイルシステム（例: /tmp と作業ディレクトリ）をまたぐと rename がアトミックでなくなり、コピー＋削除に退化して原子性が崩れるためです。

2. 起動時に古い temp を掃除する

trap で消すのが基本ですが、プロセスが SIGKILL（kill -9）で強制終了されると trap すら走りません。そこで起動直後に、一定時間より古い自分の temp を掃除する保険を入れます。

# 起動時: 1時間以上前の取り残し temp を掃除（自分の命名規則のものだけ）
find out/articles -name '.tmp.*' -mmin +60 -delete 2>/dev/null || true

「自分の命名規則に一致するものだけ」を対象にするのが肝心です。広いパターンで消すと、同じディレクトリで並行している別エージェントの作業中ファイルを巻き込みかねません。

書き込み後の内容アサーションを exit code と分ける

今回固有の印を照合する

最後の守りが、exit code とは独立した内容検証です。mv で公開する前に「書けたものが今回意図した内容か」を確かめます。サイズ0や壊れた構文を弾くだけでなく、私は「今回の slug が本文に含まれているか」「前回の slug が紛れていないか」といった、その実行に固有の印を照合するようにしています。

# 公開直前: 今回の slug が含まれ、かつ前回の混入痕がないことを確認
grep -q "$SLUG" "$TMP"               || { echo "self-marker missing"; exit 1; }
grep -q "$PREV_SLUG" "$TMP" 2>/dev/null && { echo "previous-run contamination"; exit 1; }

検証ゲートと公開を別の処理にする

ここで重要な運用上の判断がもう一つあります。検証と公開を一つの処理にまとめないことです。「検証して、通ったら同じ流れで mv する」と書くと、検証ステップの途中失敗が握り潰されて、未検証のまま公開へ進む事故が起こりえます。私は検証ゲートを通したことを確かめてから、別の処理として公開する、という分離を守っています。地味ですが、無人で何百回と回る前提では、この分離が効いてきます。

どこまで守るかの線引き

ここまでの守りは、対話実行ではほとんど不要です。自分が画面を見ているなら、半分書けたファイルにはすぐ気づき、手で消せます。原子的書き込みと内容アサーションが本当に効くのは、人が見ていない無人実行で、しかも出力が後続の自動工程の入力になるときです。Antigravity の CLI やスケジュールタスクで生成物を連鎖させるパイプラインは、まさにこの条件に当てはまります。

逆に、ワンショットで人が結果を確認してから次へ進むような使い方なら、ここまでの仕組みは過剰です。守りのコストは、その出力を誰も見ないまま次の工程が信じてしまうかどうかで決めるのが、私の基準です。個人開発でパイプラインを組むと、つい全部を堅牢にしたくなりますが、堅牢さを入れる場所を間違えると、ただ複雑になるだけだと感じています。

まず一本、いちばん下流で誰も中身を見ていない生成物を選び、その書き込みだけを temp + rename に置き換えてみてください。それだけで「朝、壊れた成果物に気づく」種類の事故は、かなり減るはずです。