throughline 0.3.24 → 0.4.0

package/docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md

@@ -0,0 +1,286 @@
+# Throughline `/clear` 自動引継ぎ計画 (TODO 兼)
+
+`/clear` をトリガーにした **自動かつ軽量な引継ぎ** を実現する計画。
+2026-05-08 セッションの議論と実機検証、外部仕様調査に基づく。
+A 案 (= /clear で自動引継ぎ + /tl は逃げ道として残す + /tl-trim 廃止) **採択確定**。
+
+> 過去の経緯 (なぜ `/tl` バトンを採用したか) は [INHERITANCE_ON_CLEAR_ONLY.md](INHERITANCE_ON_CLEAR_ONLY.md) を参照。
+> 本書は **2026-05-08 時点の現状検証 + 新理想設計** を扱う。
+
+---
+
+## 1. 確定した事実 (実機検証済み)
+
+### 1.1 `/clear` 後の SessionStart `source` は 2.1.128 で reliable
+
+```
+inheritance-decision.log (2026-05-08 12:26 検証)
+  12:26:08.481Z  source="startup"   session=05735717  ← 新 chat 開始
+  12:26:52.257Z  source="clear"     session=b2addc4a  ← /clear 後
+```
+
+- Claude Code `2.1.128` (VSCode native extension, Linux/WSL2) で `/clear` 後の SessionStart は **確実に `source='clear'`** を payload に乗せる
+- 過去の [GitHub issue #49937](https://github.com/anthropics/claude-code/issues/49937) (= VSCode 拡張で /clear 後も `source='startup'` になっていたバグ) は **解決済み**
+- v2.1.105 (VSCode `/clear` not clearing conversation context fix) と v2.1.126 (Windows SessionStart hook env files apply) のリリースで段階的に修正された
+
+### 1.2 SessionStart `source` の 4 値 (公式 docs)
+
+| 値 | 意味 |
+|---|---|
+| `startup` | 新 chat / VSCode 再起動 / 別 project / cold start |
+| `resume` | `--resume` / `--continue` / `/resume` |
+| `clear` | `/clear` 直後 |
+| `compact` | 自動 / 手動 compaction 直後 |
+
+source: [code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)
+
+### 1.3 `/clear` 等価の user-defined slash command は **作れない**
+
+調査結果 (claude-code-guide Agent + bundled `claude-code` 検査):
+
+- `.claude/commands/*.md` (skill markdown) は **prompt 拡張**であり、built-in `/clear` を programmatic に invoke できない
+- "subcommand" や "exec built-in" 構文は無い
+- `/clear` には built-in alias が存在しない
+- CLI flag `claude clear` も無い
+- cross-platform で「新ウィンドウ起動」する built-in も無い (`/branch` は full history copy で軽量化と矛盾、VSCode URL scheme は VSCode 専用)
+
+→ **「引継ぎたい /clear」と「reset したい /clear」を `source` 値で区別する手段は無い**
+
+### 1.4 `/rewind` は fork 動作 (caveat 記録済み)
+
+- `/rewind` Continue 確認画面に "A new forked conversation will be created after rewinding" と明示
+- 同 thread 内 rollback ではなく、新 fork session id を生成
+- 詳細は caveat `claude-code/claude-code-rewind-fork-conversation-rollback-primitive` を参照
+- 本計画では `/rewind` は **対象外**
+
+---
+
+## 2. 採用する理想設計
+
+### 2.1 引継ぎ発火条件 (2 経路)
+
+| 経路 | 条件 | 起動 |
+|---|---|---|
+| **auto path** | `source='clear'` かつ env `THROUGHLINE_DISABLE_AUTO_HANDOFF` の値が `'1'` でない | 自動引継ぎ |
+| **baton path** | `handoff_batons` テーブルに TTL (1 時間) 内 baton あり (= ユーザーが `/tl` を打った) | `source` 値関係なく引継ぎ |
+
+判定ロジック (擬似コード):
+
+```
+on SessionStart(source, session_id, project_path):
+  baton = consumeBaton(project_path)  // atomic SELECT + DELETE, TTL 超過は sessionId=null で返る
+  if baton.sessionId:
+    inject(curated_memory)  // baton path
+    return
+  if source == 'clear' and env.THROUGHLINE_DISABLE_AUTO_HANDOFF != '1':
+    inject(curated_memory)  // auto path
+    return
+  // 何もしない
+```
+
+`consumeBaton` が先発なので「両方同時成立」は構造上発生しない (= baton ありなら baton 経路、無ければ source 判定)。
+
+### 2.2 注入内容: L1 + L2 + L3 refs のみ (baton/auto どちらの経路でも同一)
+
+含める:
+- ヘッダ + Reading Contract framing (= Codex 側 `renderCodexRolloutMemoryPreview` の写像)
+- **L1 summaries** (古い turn の一行要約)
+- **L2 bodies** (直近 20 turn の verbatim)
+- **L3 references** (= `throughline detail <時刻>` の取り出しコマンド一覧、Codex 風の `- ${kind}: ${detailCommand}` フォーマット)
+- Continuation Instruction (= 「これは過去ログではなく現在進行中の作業」と明示)
+
+含めない (= 削除):
+- 中断直前の in-flight memo (memo セクション)
+- 中断直前の thinking (extended thinking セクション)
+- 既存の Claude 向け footer の冗長な使い方説明
+
+理由: L2 全文があれば最後の assistant turn 自体に「次に何をしようとしていたか」が含まれている。memo / thinking は redundant。
+
+### 2.3 `/tl` の役割: **残すが簡素化**
+
+- `/tl` slash command 自体は **維持** (= 明示意思マーカー = baton path のトリガー)
+- 簡素化:
+  - memo 4 項目入力要求を **削除** ([.claude/commands/tl.md](../.claude/commands/tl.md) を「baton 立てるだけ」の最小実装に)
+  - `save-inflight` CLI を **削除** (memo を baton.memo_text に保存する役目だった)
+  - `handoff_batons.memo_text` 列を **drop** (schema v8 migration)
+  - `src/baton.mjs` の `updateBatonMemo` 関数を **削除** (memo_text 列が drop されるため)
+- `prompt-submit.mjs` の baton 書き込み path は **維持** (`UserPromptSubmit` hook で `/tl` 検出 + writeBaton)
+
+ユーザーから見た `/tl` の使い方:
+- 自動引継ぎ ON (デフォルト): `/tl` を打たなくても `/clear` で自動引継ぎ。打っても挙動は同じ
+- 自動引継ぎ OFF (env で disable): `/tl` を打ってから新セッションスタートすれば baton 経由で引継ぎ
+
+### 2.4 `/tl-trim` 廃止 (Codex 側を壊さない)
+
+- 元機能: memo 入力 + dry-run preview 表示
+- 新仕様で memo 廃止 + 軽量化方針 → 役割なし
+- 削除対象:
+  - [.claude/commands/tl-trim.md](../.claude/commands/tl-trim.md) (slash command)
+  - [src/cli/trim.mjs](../src/cli/trim.mjs) の **Claude path 部分のみ** 削除 (`describeTrimHost('claude')` ブランチ、Claude 用 memory preview 経路など)
+  - 関連 test
+- **維持** (Codex 側を壊さないため):
+  - [src/cli/trim.mjs](../src/cli/trim.mjs) の Codex path (`--host codex`, `--codex-thread-id`, `--preflight`, `--execute`, etc.) はすべて維持
+  - [src/trim-model.mjs](../src/trim-model.mjs) の `describeTrimHost('codex')` / `buildTrimPlan` の Codex 関連
+  - [src/codex-app-server.mjs](../src/codex-app-server.mjs), [src/codex-rollout-memory.mjs](../src/codex-rollout-memory.mjs), `codex-*` CLI 全般
+  - `bin/throughline.mjs` の `trim` dispatch (Codex 経路で必要)
+  - Codex skill ([codex/skills/throughline](../codex/skills/throughline)) の trim 機能 (= 機能自体は無変更、SKILL.md 内の `/tl-trim` 言及があれば 4 TODO で update)
+
+### 2.5 `THROUGHLINE_DISABLE_AUTO_HANDOFF` env var
+
+- 値が `'1'` のとき auto path を skip
+- それ以外の値、または未設定 → auto path 有効 (= デフォルト ON)
+- 判定箇所: [src/session-start.mjs](../src/session-start.mjs)
+- 設定方法: ユーザーが `.bashrc` / `.zshrc` / VSCode terminal env / `~/.claude/settings.json` の `env` セクションで設定
+
+### 2.6 トレードオフ (受容する)
+
+- ⚠️ 「reset したい /clear」も auto path で引継ぎ発火する → 受容 (= 不要なら env で OFF)
+- ⚠️ baton TTL は 1 時間 (= 既存仕様維持)
+
+---
+
+## 3. 確定した内部判断
+
+### 3.1 `/rewind` source 検証 — 不要
+
+A 採択により本計画は `/rewind` を扱わない。`/rewind` 後の `source` 値は将来要件で再検討。
+
+### 3.2 `handoff_batons` テーブル — 残す + memo_text 列だけ drop
+
+- table 自体は baton path で必要なので **維持**
+- `memo_text TEXT` 列を schema v8 migration で drop
+- 既存の memo データは廃棄 (受容)
+- **SQLite DROP COLUMN 互換確認必須**: `ALTER TABLE ... DROP COLUMN` は SQLite 3.35.0+ で利用可。Node.js v22.5+ 同梱の SQLite バージョンで動作するか実装時に検証
+
+### 3.3 旧 `/tl` ユーザー移行 — `/tl` 自体は continue、memo 関連だけ breaking
+
+- `/tl` slash command 自体は使い続けられる (簡素化されただけ)
+- 廃止される機能: memo 4 項目入力、`save-inflight` CLI、`/tl-trim`
+- breaking change として CHANGELOG に明示
+
+### 3.4 `source='compact'` 扱い — 引継ぎしない
+
+auto-compaction は Claude Code 内部の context 圧縮で、conversation 連続性は host 側が担保している。Throughline 側で別途引継ぎを発火する必要なし。
+
+### 3.5 ログファイルの扱い
+
+- `~/.throughline/logs/inflight-memo.log`: `save-inflight` CLI 削除で **新規書き込みなし**。既存ファイルは削除提案を README / CHANGELOG に書く (= 自動削除はしない、ユーザー手動)
+- `~/.throughline/logs/inheritance-decision.log` 内の `baton_has_memo` フィールド: memo 廃止で意味を失うため、`logDecision()` から **削除**
+- `~/.throughline/logs/baton-write.log`: 維持 (= `/tl` baton 書き込みログとして引き続き有用)
+
+---
+
+## 4. 実装 TODO (実装開始可)
+
+優先度順:
+
+- [ ] **schema v8 migration** ([src/db.mjs](../src/db.mjs)): `ALTER TABLE handoff_batons DROP COLUMN memo_text`
+  - SQLite 3.35.0+ サポート確認 (Node.js v22.5+ 同梱版)
+  - 動かない場合は `CREATE TABLE` + `INSERT SELECT` + `DROP` の rebuild migration に切り替え
+- [ ] **`src/baton.mjs`**:
+  - `consumeBaton` 戻り値から `memoText` プロパティを削除
+  - `updateBatonMemo` 関数を **削除**
+  - `BATON_TTL_MS`, `writeBaton`, `consumeBaton` は維持
+- [x] **`src/handoff-record.mjs`**: **維持** (Codex 側 codex-handoff.mjs / codex-resume / codex-handoff-smoke 等が `memory.inflightMemo` / `memory.latestThinking` を参照しているため、削除すると Codex を壊す)。Claude 側で「使わない」のは resume-context.mjs 側で実現済み
+- [ ] **`src/resume-context.mjs`**: 注入テキストを新仕様に書き換え:
+  - memo セクション削除
+  - thinking セクション削除
+  - L3 references 一覧追加 (Codex `renderCodexRolloutMemoryPreview` 形式)
+  - footer 簡素化 (Continuation Instruction だけ残す)
+- [ ] **`src/session-start.mjs`** を 2.1 のロジックに改修:
+  - `consumeBaton` 先発 → `baton.sessionId` あれば inject
+  - 無ければ `source==='clear'` かつ env が `'1'` でない場合に inject
+  - それ以外は何もしない
+  - `logDecision()` から `baton_has_memo` フィールド削除
+- [ ] **`src/cli/save-inflight.mjs`** 削除
+- [ ] **`bin/throughline.mjs`** の `save-inflight` dispatch 削除 (`trim` dispatch は **維持**)
+- [ ] **`src/prompt-submit.mjs`**: 維持 (baton 書き込み + ensureMonitorTaskFile)
+- [ ] **[.claude/commands/tl.md](../.claude/commands/tl.md)**: memo 4 項目入力要求を削除、純粋に「baton 立てるだけ」の最小実装に書き換え
+- [x] **`/tl-trim` 関連削除**:
+  - [.claude/commands/tl-trim.md](../.claude/commands/tl-trim.md) ファイル削除
+  - **`src/cli/trim.mjs` 自体は維持**: Codex 経路 (`--host codex`, `--preflight`, `--execute`, `--codex-app-server-bin` 等) と doctor `--trim --host claude` で使う `describeTrimHost('claude')` の dry-run 表示が依存しているため、コード削除はしない (= ユーザーが直接 `throughline trim --host claude --dry-run` を打つ余地は残す。実用は SessionStart 自動経路に置き換わる)
+- [ ] **[src/cli/install.mjs](../src/cli/install.mjs)**: Throughline 管理 slash commands の copy 対象リストから `tl-trim.md` を除外。`tl.md` は維持。`src/cli/install.test.mjs` の関連 test も update
+- [ ] **[bin/throughline.mjs](../bin/throughline.mjs) の `showHelp()` 文言 update**:
+  - `save-inflight` 関連 help 文言を削除
+  - `/tl-trim` / Claude trim 関連の help 文言を削除
+  - Codex trim 関連 (`trim --dry-run`, `--preflight`, `--execute --host codex` など) は **維持**
+  - `bin/throughline.mjs` の `save-inflight` dispatch case 削除 (上の TODO と重複するが help text だけ別作業)
+- [ ] **[codex/skills/throughline/SKILL.md](../codex/skills/throughline/SKILL.md)**: `/tl-trim` への言及があれば削除し、`throughline trim --execute --host codex` 直接呼び出しに統一。Codex 側 trim 案内自体は維持
+- [ ] **[.codex-sidecar.yml](../.codex-sidecar.yml)** 確認: `/tl-trim` / `save-inflight` 経路の参照があれば削除。無ければ no-op
+- [ ] **テスト全部更新**:
+  - `src/baton.test.mjs` → memo 関連 test 削除、`updateBatonMemo` test 削除
+  - `src/session-merger.test.mjs` → source='clear' 自動経路の test 追加
+  - `src/resume-context.test.mjs` → memo/thinking 削除を反映
+  - `src/handoff-record.test.mjs` → projection 簡素化
+  - `src/hook-entrypoints.test.mjs` → save-inflight subprocess test ケース削除 (= 独立ファイルではなく本ファイル内の test)
+  - `src/turn-processor.test.mjs` → 既存維持
+  - `src/trim-cli.test.mjs` / `src/trim-model.test.mjs` → Claude path 関連テストのみ削除、Codex 経路テストは維持
+  - 新規: env var 判定 test、source='clear' auto path test
+- [ ] **docs 更新**:
+  - [CLAUDE.md](../CLAUDE.md): 設計の核を書き換え (「`/tl` バトンのみ」→「`source='clear'` 自動 + `/tl` 逃げ道」)
+  - [README.md](../README.md): 以下範囲を update:
+    - Quick Start: 「`/clear` で自動引継ぎ」中心に書き直し
+    - 「Explicit handoff via `/tl`」セクション: `save-inflight` / memo 4 項目要求の記述を削除、`/tl` は逃げ道として簡素な記述に
+    - Troubleshoot / How it compares 等の他セクション: `/tl-trim`, `save-inflight`, `inflight-memo.log` への言及をすべて削除
+    - `THROUGHLINE_DISABLE_AUTO_HANDOFF` env var 紹介を新規追加
+    - 既存 `inflight-memo.log` ファイルは新版で書き込み停止することを README で告知 (= 手動削除提案)
+  - [CHANGELOG.md](../CHANGELOG.md): breaking change を明示 (memo 廃止、save-inflight 削除、/tl-trim 削除、`updateBatonMemo` 削除、baton_has_memo フィールド削除)
+  - [INHERITANCE_ON_CLEAR_ONLY.md](INHERITANCE_ON_CLEAR_ONLY.md): 「2026-04 段階の検証 → 2026-05 でバグ修正により案 A 成立、本書は履歴扱い」note 追加
+  - [PUBLIC_RELEASE_PLAN.md](PUBLIC_RELEASE_PLAN.md): version bump + breaking change 反映
+- [ ] **package.json**: **0.4.0** に bump (semver minor、pre-1.0 の breaking)
+- [ ] **caveat 記録**: 「`/clear` SessionStart `source` は 2.1.128 で reliable、過去 #49937 は fix 済み」を public で記録
+
+---
+
+## 5. 削減できるコード規模 (見積もり)
+
+廃止対象:
+- `src/cli/save-inflight.mjs` (~80 行) → 削除
+- `src/cli/trim.mjs` の Claude path 部分 (~30 行) → 削除 (Codex path は維持)
+- [.claude/commands/tl-trim.md](../.claude/commands/tl-trim.md) (~40 行) → 削除
+- `src/baton.mjs` の `updateBatonMemo` 関数 (~10 行) → 削除
+- `handoff_batons.memo_text` 列 (schema migration、コードへの影響は consumeBaton 戻り値変更のみ)
+- `src/hook-entrypoints.test.mjs` 内 save-inflight test ケース (~30 行) → 削除
+- `resume-context.mjs` の memo/thinking セクション (~30 行) → 削除
+- `handoff-record.mjs` の memo/thinking projection (~50 行) → 削除
+- [.claude/commands/tl.md](../.claude/commands/tl.md) の memo 4 項目要求 (~20 行) → 削除
+
+代わりに追加:
+- `session-start.mjs` の env / source 判定 (~15 行)
+- `resume-context.mjs` の L3 refs framing (~30 行)
+
+純減 ~245 行。
+
+---
+
+## 6. Codex 側との整合 (壊さない)
+
+Codex 側 v0.3.25 の以下は本計画で **完全に無変更**:
+
+- `codex-capture` / `codex-summarize` / `codex-resume` (Codex primary L1/L2/L3 path)
+- `codex-resume --format handoff` (新規 Codex thread 用 prompt)
+- `trim --execute --host codex` / `--preflight --host codex` (app-server `thread/rollback` + `thread/inject_items`)
+- Codex Stop hook 90% auto-refresh
+- restore-safety / host primitive audit diagnostics
+- Codex skill ([codex/skills/throughline](../codex/skills/throughline)) の trim 機能 (= 機能自体は無変更、SKILL.md 内の `/tl-trim` 言及があれば 4 TODO で update)
+- [src/codex-app-server.mjs](../src/codex-app-server.mjs), [src/codex-rollout-memory.mjs](../src/codex-rollout-memory.mjs)
+- [src/trim-model.mjs](../src/trim-model.mjs) の Codex 関連 (`describeTrimHost('codex')`, `buildTrimPlan` の Codex source path)
+
+`codex-resume --memo-stdin` は引き続きユーザーが stdin で memo を流す経路。Throughline DB の baton.memo_text には依存していない (= 列削除の影響なし)。
+
+`/tl-trim` 削除に伴って Codex 経由でも slash command としての `/tl-trim` は使えなくなる。Codex 用 trim は `throughline trim --execute --host codex` を **CLI 直接呼ぶ**運用に統一 (Codex skill SKILL.md がそれを案内する)。
+
+---
+
+## 7. 進め方
+
+1. **本計画 確定** (ユーザー A 採択済み、本書 update により方針固定)
+2. **実装** (上記 TODO 順)
+3. **テスト + 実機 smoke + commit**
+4. **publish** (npm 0.4.0 として release)
+
+実機 smoke 手順:
+- 自動引継ぎ ON (デフォルト): /clear → 新セッションで curated memory 注入を確認
+- 自動引継ぎ OFF: env を立てて /clear → 注入されないことを確認
+- baton path: `/tl` を打って新 chat タブで開く → baton 経由で注入を確認
+- Codex 側 regression: `npm test` で既存 Codex test がすべて pass することを確認、`throughline trim --execute --host codex` の CLI 動作も維持

package/docs/THROUGHLINE_CODEX_DUAL_SUPPORT.md

@@ -0,0 +1,249 @@
+# Throughline: Claude / Codex 両対応計画
+
+この文書は Throughline repository に貼り付けるための実装ブリーフです。目的は、Throughline を Claude Code と Codex の両方から安全に使える形へ育てることです。
+
+## この文書の位置づけ
+
+この文書は **Claude / Codex 両対応の architecture brief** です。
+
+関連文書:
+
+| 文書 | 役割 |
+|---|---|
+| [THROUGHLINE_CODEX_FIRST_ROADMAP.md](THROUGHLINE_CODEX_FIRST_ROADMAP.md) | 2026-05-06 以降の次フェーズ計画。Codex primary 実用化を先行する |
+| [THROUGHLINE_CODEX_TRIM_ROLLBACK_FIX_PLAN.md](THROUGHLINE_CODEX_TRIM_ROLLBACK_FIX_PLAN.md) | 2026-05-06 incident 後の修正計画。2026-05-08 の controlled smoke 後、過剰な Codex trim blocker は解除し、restore-safety / host primitive audit は diagnostics として扱う |
+| [THROUGHLINE_CODEX_TRIM_IMPLEMENTATION_PLAN.md](THROUGHLINE_CODEX_TRIM_IMPLEMENTATION_PLAN.md) | この文書と rollback trim の気づきを統合した旧計画と実装履歴。完了済み根拠として参照する |
+| [throughline-rollback-context-trim-insight.md](throughline-rollback-context-trim-insight.md) | conversation-only rollback を「model-visible context の delete primitive」と見る設計メモ |
+
+この文書は Codex adapter / sidecar integration の方針を定義する。今後の実装順は [THROUGHLINE_CODEX_FIRST_ROADMAP.md](THROUGHLINE_CODEX_FIRST_ROADMAP.md) を優先する。
+
+## 目標
+
+Throughline は agent-neutral な handoff / context compression infrastructure になるべきです。
+
+Claude Code transcript と handoff behavior は守りつつ、Codex primary bridge と `codex-sidecar` 経由の compact context も生成できるようにします。現行の `HandoffRecord` は安定した中間表現だが、保存元はまだ Claude transcript 由来であり、Codex capture を実装して初めて source adapter が Codex 由来になる。
+
+目指す形:
+
+- Throughline core は特定 agent に依存しない。
+- Claude transcript support は first-class かつ stable のまま維持する。
+- Codex support は `throughline_handoff` context block、Codex primary entrypoint、Codex CLI backend、`codex-sidecar` integration として追加する。
+- 既存の Claude handoff behavior を壊さない。
+
+## 優先順位
+
+1. Throughline を Codex primary で使えるようにする。Codex primary の L2 -> L1 backend は Codex CLI を本線にする。
+2. Codex で Claude Rewind 相当の context trim を完成させる。2026-05-08 時点では Codex current-thread trim execute / auto-refresh は再有効化済みで、DB memory と turn-count guard を必須にする。
+3. そのあと Claude 側の `/rewind` UX / 自動化 surface を詰める。
+
+Claude transcript handling の置き換えから始めないでください。Codex 対応は adapter / bridge / Codex primary entrypoint として追加します。
+
+Claude primary で `codex-sidecar` が使えない場合は、現在の Claude subagent behavior をそのまま維持します。Codex 向け adapter / bridge が存在するからといって、既存の Claude path を削ったり劣化させたりしないでください。Codex primary の可用性は Codex CLI / app-server / rollout の実測で別に判定します。
+
+## Architecture 方針
+
+概念上、次の layer に分けます。
+
+| Layer | Responsibility |
+|---|---|
+| Agent-neutral core | handoff record、compression output、reference、persistence、validation |
+| Claude adapter | Claude Code transcript parsing、tool I/O assumption、Claude handoff command |
+| Codex adapter | `throughline_handoff` context block、`codex-sidecar` request shaping、result capture |
+| Shared fixtures | Claude / Codex adapter の両方で使う handoff example と expected output |
+
+Codex path が Claude internals を parse するのは、それが明示的に adapter の責務である場合だけにしてください。core は stable handoff object を扱うべきです。
+
+## Codex Sidecar Integration
+
+この節は `codex-sidecar` integration の設計です。Codex primary の capture / L2 -> L1 backend は [THROUGHLINE_CODEX_FIRST_ROADMAP.md](THROUGHLINE_CODEX_FIRST_ROADMAP.md) を優先します。
+
+Sidecar 向けには、Throughline が `codex-sidecar` contract に合う plain JSON context block を生成します。
+
+```json
+{
+  "kind": "throughline_handoff",
+  "source": "throughline",
+  "trust": "local",
+  "summary": "In-flight handoff: Next: continue",
+  "data": {
+    "throughlineHandoffSchemaVersion": 1,
+    "handoffRecordVersion": 1,
+    "sessionId": "session-id",
+    "projectPath": "/repo",
+    "sourceAgent": "claude",
+    "hostMode": "claude-primary",
+    "intent": "continue implementation",
+    "constraints": ["preserve Claude transcript contract"],
+    "originSessionIds": ["old-session"],
+    "stats": {},
+    "memory": {},
+    "detailReferences": [
+      {
+        "type": "throughline_detail",
+        "label": "tool_input:Bash",
+        "command": "throughline detail 12:00:01",
+        "sourceId": "toolu_1",
+        "detailKind": "tool_input",
+        "originSessionId": "old-session",
+        "turnNumber": 2
+      }
+    ]
+  }
+}
+```
+
+`codex-sidecar` の top-level `references` は `path` 必須です。Throughline の DB /
+`throughline detail <時刻>` 参照は `data.detailReferences` に置きます。file path /
+line reference は既知の場合だけ top-level `references` に足し、必須にはしません。
+`SidecarContextBlock` は top-level `schemaVersion` を保持しないため、Throughline 側の
+schema version は `data.throughlineHandoffSchemaVersion` に入れます。
+`hostMode` は `claude-primary` / `codex-primary` / `unknown` を明示指定します。自動 host-agent detection は初期実装に入れません。
+
+Codex-facing workflow では、この context block を次の用途に使います。
+
+- `codex_explore`: previous handoff context を使って repo question に答える。
+- `codex_review`: last handoff を intent として current changes を review する。
+- `codex_opinion`: handoff に含まれる plan を challenge する。
+- `codex_risk_check`: handoff が触れている risky area を確認する。
+- `codex_work`: isolated worktree で小さな scoped task を続行する。
+
+## Claude Behavior を守る
+
+コード変更の前に、現在の Claude contract を特定して文書化してください。
+
+- transcript file shape
+- tool input / output parsing assumption
+- compaction format
+- handoff markdown / JSON schema
+- command name と argument
+- resume behavior
+- Claude session がまだ動くことを示す test / fixture
+
+Codex のために既存の Claude-facing field を rename しないでください。必要なら Codex adapter projection を追加します。
+
+## Background Subagent Shift
+
+現行 Throughline で subagent 的に外部 model call しているのは、Stop hook の
+L2 → L1 要約だけです。具体的には [src/haiku-summarizer.mjs](../src/haiku-summarizer.mjs)
+が `claude -p --model claude-haiku-4-5-*` を呼びます。
+
+移行方針:
+
+- Claude primary では、`codex-sidecar diagnostics --project <repo> --preset summarize-l1` が成功する環境では、L2 → L1 要約に `codex-sidecar` を使う。
+- Claude primary では、`codex-sidecar` が disabled / unavailable / diagnostics failure / run failure の環境では、現行の Claude Haiku 要約を維持する。
+- Codex primary では、次フェーズ計画 [THROUGHLINE_CODEX_FIRST_ROADMAP.md](THROUGHLINE_CODEX_FIRST_ROADMAP.md) に従い、L2 → L1 要約 backend は Codex CLI を本線にする。Codex CLI が使えない場合は silent fallback せず明示 error とする。
+- `/tl` の in-flight memo は [.claude/commands/tl.md](../.claude/commands/tl.md) が現行メイン Claude に書かせる handoff memo であり、subagent ではない。これは Codex sidecar へ移さない。
+
+handoff review、continuity check、risk analysis などは現行 `src/` 実装には存在しません。
+後続で追加する場合だけ、`throughline_handoff` context block と read-only sidecar workflow
+として扱います。
+
+## 懸念: Codex が Codex を呼ぶ場合
+
+ユーザーが Claude から Throughline を使っている場合、この形には価値があります。
+
+```text
+Claude primary -> Throughline -> codex-sidecar -> Codex second opinion
+```
+
+一方、ユーザーが Codex から Throughline を使っている場合、次の形を無条件で行わないでください。
+
+```text
+Codex primary -> Throughline -> codex-sidecar -> Codex again
+```
+
+Codex-on-Codex が有効なのは、sidecar に別の境界がある場合だけです。
+
+- isolated worktree から実行される。
+- durable `SidecarResult` を生成する。
+- diagnosis 用の raw App Server log を書く。
+- critic / reviewer / risk-analyst など prompt role が明確に違う。
+- independent second pass として明示的に要求されている。
+
+別の境界がないなら、Throughline は別の Codex に委譲せず、現在の Codex session に handoff を直接 consume させてください。
+Throughline 自体を Codex primary から使う場合は、まず [THROUGHLINE_CODEX_FIRST_ROADMAP.md](THROUGHLINE_CODEX_FIRST_ROADMAP.md) の Codex primary capture / Codex active-work resume renderer / Codex CLI L2→L1 backend を本線にします。`throughline codex-capture` と `throughline codex-resume` が Codex primary の入口であり、`throughline codex-sidecar-diagnostics`、`throughline codex-sidecar-dry-run` などは sidecar を使う review / risk-check / second opinion の診断 surface です。
+
+Recommended policy:
+
+| Host agent | Sidecar choice |
+|---|---|
+| Claude | independent review、risk、exploration、scoped continuation には Codex sidecar を優先 |
+| Codex | isolation、structured result capture、explicit second-pass review がある場合のみ Codex sidecar を使う |
+| Unknown / automation | implicit recursion ではなく明示 config を要求 |
+
+Sidecar availability policy:
+
+この表は `codex-sidecar` の availability を表す。Codex primary の L2 → L1 backend availability ではない。
+
+| Codex sidecar availability | Behavior |
+|---|---|
+| `unavailable` | `codex-sidecar` が存在しない、実行不能、この repo 向けに未設定、または diagnostics 失敗。既存の Claude subagent path を維持 |
+| `configured` | `codex-sidecar diagnostics --project <repo>` が成功。request shaping、dry-run、docs、planned read-only integration は使ってよい |
+| `operational` | `codex_explore` など read-only smoke が成功。approved review、explore、opinion、risk-check sidecar task に使ってよい |
+| `work-capable` | `codex_work` smoke が成功し、allowed paths が設定済み。worktree-backed scoped edit に使ってよい |
+| explicitly disabled | 既存の Claude subagent path を維持 |
+
+これは hidden fallback ではありません。Claude primary の互換モードです。Codex sidecar が使えない環境では、現在の Claude-backed behavior を baseline とします。
+
+「Codex sidecar が使える」の最小実用定義は、単に `codex` binary があることではありません。`codex-sidecar` が存在し、対象 repository で diagnostics を成功させられることです。`codex-sidecar` がない場合、Throughline は sidecar unavailable と扱ってください。Codex primary 自体の可用性は、Codex CLI と app-server / rollout の実測で別に判定します。
+
+Preferred health check:
+
+```bash
+codex-sidecar diagnostics --project <repo> --preset review
+```
+
+Development-path health check:
+
+```bash
+node /home/kite/projects/codex-sidecar/packages/cli/dist/index.js diagnostics \
+  --project <repo> \
+  --preset review
+```
+
+Dry-run checks:
+
+```bash
+throughline codex-sidecar-dry-run \
+  --project <repo> \
+  --preset review \
+  --context-file docs/throughline-handoff-context.example.json \
+  "Review Throughline dual support request shape only."
+
+throughline codex-sidecar-dry-run \
+  --project <repo> \
+  --preset risk-check \
+  --context-file docs/throughline-handoff-context.example.json \
+  "Risk-check Throughline dual support request shape only."
+```
+
+Structured result policy:
+
+- Dry-run output is diagnostic evidence only; it is not persisted in Throughline memory.
+- Real read-only sidecar runs return structured JSON on stdout. If the result contains `rawEventLogRef`, treat that as the canonical durable link to the App Server event log.
+- Do not mix sidecar result JSON into L1/L2/L3 memory tables. If Throughline later needs durable indexing, add a separate `sidecar_runs` style record keyed by project / workflow / preset / status / `rawEventLogRef`.
+
+## Implementation Checklist
+
+- [x] 既存の Claude transcript / handoff contract を audit する。
+- [x] adapter 変更前に、現在の Claude behavior を固定する test を追加する。
+- [x] stable handoff object がまだない場合は追加する。
+- [x] `throughline_handoff` 用の Throughline-to-`SidecarContextBlock` conversion path を追加する。
+- [x] Codex context block の fixture snapshot を追加する。
+- [x] Claude primary / Codex primary mode の docs を追加する。
+- [x] Codex-on-Codex recursion を避ける explicit `hostMode` config を追加する。自動 detection は未実装。
+- [x] background Claude subagent task を移す前に Codex sidecar availability check を入れる。sidecar absent または diagnostics failure は explicit `unavailable`。
+- [x] sample handoff を使った read-only `codex-sidecar` smoke を追加する。2026-05-06 に `throughline_handoff` fixture + `codex-sidecar explore` で成功済み。
+- [x] `review` / `risk-check` dry-run を追加する。2026-05-06 に `throughline_handoff` fixture + `throughline codex-sidecar-dry-run` で成功済み。
+- [x] sidecar structured result は stdout JSON + `rawEventLogRef` link として扱い、Throughline memory tables には混ぜない方針を明文化する。
+
+## Done Definition
+
+Throughline が dual-supported になったと言える条件:
+
+- 既存の Claude transcript / handoff behavior が通る。
+- Codex が `throughline_handoff` context block を受け取れる。
+- Throughline が Codex の structured result を保存または link できる。
+- Codex primary mode が実質的な境界なしに recursive delegation しない。
+- Codex-unavailable environment では既存の Claude subagent behavior を維持する。
+- Claude、current Codex、Codex sidecar の使い分けが docs に説明されている。