目次
Durable Objects をホストする Worker をデプロイし、トラフィックが流れ続けていると、インスタンスは最大およそ5分間、以前のコードを実行し続けることがある。多くの場合、既定の遅延更新ポリシーが原因だ。2026-10-30 以降、Cloudflare の Durable Objects ドキュメントと Changelog は、既定のコード更新戦略を deferred とし、既定の max_delay を 300秒 と定めている。稼働中のオブジェクトはハイバネーションするまで—またはその遅延が尽きてランタイムがリセットし新コードを載せるまで—現行バージョンを維持できる。
Durable Objects 上で AI エージェント、長寿命セッション、Hibernation WebSocket を動かしているなら、デプロイがいつ本当にコードを切り替えるかがポイントになる。ルールは 2026年10月30日付の Cloudflare Changelog と、同日最終更新の Durable Objects コード更新ドキュメントに従う。Wrangler、段階的トラフィック、REST Create deployment の全経路はまだ測っていません。使ったことがあれば、ページ下部の管理人連絡先からフィードバックできる。
関連記事：Cloudflare、Workers AI の GLM-5.3 で発生したリクエスト横断の KV キャッシュ露出を修正、AWS が Infinity を公開、高並行 Agent 向け研究ランタイム、Cursor Agent SDK公開：フォルダ定義、Eval、デプロイ、同じモデルでもコーディング harness を替えると通過率はほぼ変わらず、請求だけ大きく変わる。
2026-10-30 に何が変わったか
この既定の前は、「デプロイ完了＝すべての Durable Object インスタンスがすでに切り替わった」と読むチームが多かった。Changelog と Durable Objects ドキュメントが示す今の基準線は逆だ。
- 既定モード:
deferred - 既定遅延: フィールド省略時の
max_delay＝ 300秒（5分） - 許容範囲:
0–86400秒（24時間）。API が受け付ける範囲ではミリ秒精度
稼働中の Durable Object は、ハイバネーションするか max_delay に達するまで現行コードのまま動き続けられる。遅延が尽きてもなお稼働中なら、ランタイムはオブジェクトをリセットして新コードを載せる。ハイバネーション後、起こす次のリクエストは新バージョンになる。
だから CI 上ではデプロイが緑でも、粘着したエージェントセッション、alarm ハンドラ、WebSocket は数分間、昨日のビルドのように振る舞うことがある。
immediate と deferred
実務で効くのは次の二モードだ。
| モード | 挙動（Durable Objects ドキュメント） |
|---|---|
immediate | いまリセットして新コードを採用。ハイバネーションを待たない。 |
deferred | ハイバネーションをベストエフォートで待ち、max_delay で上限。 |
短い形もある。{ "mode": "deferred", "max_delay": 0 } は実質すぐ適用する。意図が「今すぐリセット」なら、半年後も読みやすい明示の immediate が向く。
Hibernation WebSocket。 Changelog は、Hibernation API を使う WebSocket について、オブジェクトがハイバネーションし後から新コードを採っても接続を保持できると記す。エージェント UI や長寿命チャットには便利だが、「接続が生きている」は「コードが切り替わった」とは読めない。2026-10-30 既定に対する Hibernation WebSocket の全経路はまだテストしていません。Changelog の文言が正本だ。
Wrangler: durable_objects.code_update_strategy
wrangler.toml／Wrangler 設定では、Durable Object の bindings と同階層（明示バインディングがなく ctx.exports のみの Worker も含む）に戦略を置く。
[durable_objects]
# 形状の例 — フィールド名は現行 Wrangler スキーマに準拠
code_update_strategy = { mode = "deferred", max_delay = 300 }TOML／JSON の正確な書き方は Wrangler 世代で変わり得る。Durable Objects ドキュメント上の名前は durable_objects.code_update_strategy（mode と任意の max_delay）。ブロックを省略したデプロイはプラットフォーム既定 { deferred, 300 } に戻り、その選択は次のデプロイへ自動継承されない。省略したデプロイのたびに再び既定へ戻る。
CLI フラグが設定より優先、deferred には時間が必須
Wrangler CLI フラグは wrangler deploy、versions deploy、rollback に効く。
--durable-objects-code-update-mode immediate--durable-objects-code-update-mode deferred <duration>— 例:deferred 30s
Durable Objects ドキュメント（Changelog の例に加え Docs のルール）によれば、CLI でモードが deferred のときは duration が必須。優先順位は次のとおり。
- CLI フラグ
- Wrangler 設定（
durable_objects.code_update_strategy） - プラットフォーム既定
{ deferred, 300 }
Changelog のサンプルは immediate をよく示す。それでも Docs 規則—CLI の deferred には duration—が拘束力を持つ。
連続デプロイと独立タイマー
同じオブジェクトが稼働したままバージョン A、B、C を順に出すと、各デプロイはそのオブジェクト向けに独自の max_delay タイマーを開始する。最先に発火したタイマーの時点で、オブジェクトはその時点ですでにデプロイ済みの最新バージョンを採る—タイマーを開始した版とは限らない。途中の immediate デプロイはすぐ更新を強制し、中間版を飛ばせる。
AI エージェント群への含意: 連続デプロイは「A→B→C」の三段階ソフト着陸を保証しない。タイマーは競合し、最初の期限が来たときの最新コードが残る（immediate で先に切られていない限り）。
段階的デプロイ（gradual）
段階的ロールアウトで Worker バージョンのトラフィック比率を上げるとき、deferred／immediate の仕組みが効くのはそのバージョンへ新たに振り分けられたオブジェクトだけだ。すでにそのバージョン上にいるオブジェクトは、比率の引き上げで再遅延されない。deferred ウィンドウや gradual のあいだに並存し得る版どうしでは、Durable Object の状態とプロトコルの前方・後方互換を保つ必要がある。
REST Create deployment: 書き込み専用フィールド
Create deployment のリクエスト本文に code_update_strategy を含められる。フィールドは deployment に属し（Worker version リソース外）、write-only：Create／get／list の応答には戦略がエコーされない。保存されたモードを求めて deployment JSON を往復しても応答には出てこない—非既定ポリシーが必要なら次の Create で再度指定する。
スコープ: どのクラスが戦略を共有するか
同一 Worker がエクスポートするすべての Durable Object クラスは、そのデプロイで一つの戦略を共有する（ctx.exports 経由のみのクラスも含む）。別 Worker から script_name で参照されるクラスは、参照先 Worker 側の戦略が支配する。クロススクリプトのバインディングが呼び出し元のデプロイ方針を黙って引き継ぐことはない。
ベストエフォート—戦略がカバーしないもの
Durable Objects ドキュメントは deferred を明示的にベストエフォートとする。
- 切り替え前に進行中の処理がきれいに終わることは保証しない。
- オブジェクトが
max_delayいっぱい動き続けることも保証しない（プラットフォーム要因で早くリセットされ得る）。 - 戦略は、新しい Worker バージョン出荷と無関係な再起動—例: Workers ランタイム更新—を遅らせない。
したがって deferred はベストエフォートに過ぎない。ゼロ中断も、進行中タスクの完了も、費用削減も約束しない。2026-10-30 既定下の中断率や請求影響はまだ測っていません。
エージェント／WebSocket 運用チェックリスト
- 既定の日付。 2026-10-30 以降、設定や CLI が別を言わない限り deferred + 300秒が想定になる。
- 意図。 すぐ切るホットフィックス →
immediate（または意図的なら deferred +max_delay: 0）。ハイバネーション待ちが許容なら deferred と明示のmax_delay。 - CLI deferred に duration。
deferred 30sなど—duration なしの裸のdeferredは Docs 規則に反する。 - デプロイごとの戦略。 省略はプラットフォーム既定へ戻る。デプロイ横断の継承はない。
- 連続デプロイ。 独立タイマー。最先の期限が、その時点の最新デプロイ版を採る。
- gradual ≠ 全員を再遅延。 遅延経路に入るのは新たにその版へ振り分けられたオブジェクトだけ。
- REST の応答。 Create deployment 上の
code_update_strategyは write-only で、応答にはエコーされない。 - Hibernation WebSocket。 接続はハイバネーションとコード採用をまたいで生き残ることがある。アプリプロトコルは別途の確認が要る。ここでの全エッジケースはまだテストしていません。
- 互換性。 deferred ウィンドウと gradual で重なり得る版のあいだで、Durable Object のストレージとメッセージ形式は互換のままにする。
- 関連する Workers AI の話題。 Workers AI 面のキャッシュ／隔離バグは別トピック—上記 GLM-5.3 KV キャッシュ記事を参照。
まとめ
Durable Objects は、デプロイが成功したあとも最大約5分間旧コードを出し続け得る。2026-10-30 以降、deferred と既定 300秒 の max_delay がプラットフォームの基準線だからだ。リセットが正しいプロダクト挙動なら immediate が向き、ハイバネーション待ちが許容なら deferred が残る—ただし deferred は完了保証でも稼働保証でもなく、ベストエフォートにとどまる。本番デプロイを変える前の確認先は、Durable Objects ドキュメント上の現行 CLI と設定スキーマだ。