takt/docs/implements/retry-and-session.ja.md

failed -> retry とセッション再開の動作原理

このドキュメントは、takt list の failed タスクを Retry したときの挙動と、AI セッション再開の実際の仕組みを整理した実装メモです。

問題の要約

• failed -> retry で「前回のセッションがそのまま復活するか」が分かりづらい。
• 実際には「タスク固有のセッション再開」ではなく「保存済みの persona セッション利用」で再開される。

解決方針（実装の見方）

• Retry が何を再投入するかを確認する。
• 再実行時にどのセッションIDを読み込むかを確認する。
• session: refresh や worktree 条件など、再開しないケースを明記する。

実装の流れ

1. takt list で failed タスクに Retry を選ぶ。
2. retryFailedTask() が TaskRunner.requeueFailedTask() を呼ぶ。
3. 失敗タスク配下の元タスクファイルを .takt/tasks/ にコピーする。
4. YAML タスクの場合のみ、必要に応じて start_movement と retry_note を書き換える。

参照:

• src/features/tasks/list/taskRetryActions.ts
• src/infra/task/runner.ts

重要: Retry で復元される情報

requeueFailedTask() はタスクファイルに sessionId を書き戻さない。
復元対象は start_movement と retry_note のみ。

つまり、failed タスクを Retry しても「その failed ディレクトリに紐づくセッションID」を直接復元する実装にはなっていない。

セッション再開の実際

再実行時の pieceExecution で、プロジェクト保存済みセッションをロードして initialSessions に渡す。

• 通常実行: loadPersonaSessions(projectCwd, provider)
• worktree 実行: loadWorktreeSessions(projectCwd, cwd, provider)

その後、各 movement の Phase 1 実行で OptionsBuilder.buildAgentOptions() が sessionId を組み立てる。

参照:

• src/features/tasks/execute/pieceExecution.ts
• src/core/piece/engine/OptionsBuilder.ts

セッション再開しない条件

• movement 側が session: refresh の場合。
• cwd !== projectCwd など、セッション再開を抑止する条件に当たる場合。

このため、Retry で常に同じ会話が厳密再開されるわけではない。

運用上の注意

• failed -> retry は正しい復旧手順。
• ただしセッションは「タスク単位」ではなく「persona の保存状態」基準で再開される。
• 前回文脈を確実に残したい場合は、retry_note に再試行理由と前提を明記する。