throughline 0.6.3 → 0.8.0

package/docs/adr/0008-observer-wait-deadline-cancel.md

@@ -0,0 +1,81 @@
+# ADR 0008: observer-waitはmonotonic deadlineの最終再確認と明示cancelを持つ
+
+日付: 2026-07-15
+
+## Context
+
+Observerは完了turnが無い間、最大一時間Throughlineを待つ。DB／WAL／mtimeは完了証拠ではなく、
+Claude receiptまたはCodex `task_complete`から再構成したcompleted cursorだけがchangedを決める。
+deadline到達時に再確認せずtimeoutすると境界直前の完了を取りこぼし、cancel時にtimerやsignal listenerを
+残すと次のwaitへ副作用が漏れる。wall clockの変更で一時間を過不足させてもならない。
+
+この契約はControlのDecision証拠に使うため、追記可能な計画書ではなく不変ADRとして置く。
+
+## Decision
+
+1. Libraryは`waitForObserverTurnChange`を公開し、`projectPath`、必須`afterCursor`、
+   `timeoutSeconds`（既定3600、1以上3600以下）、`AbortSignal`と既存host read optionsを受ける。
+   test用のclock／sleep／resolver injectionは非公開または明示的なdependency引数としてよいが、公開CLI
+   optionにはしない。
+2. 呼出直後に一度completed-only cursorを再計算する。after cursorが無効なら`resync_required`、
+   cross-host tieなら`ambiguous_parent`、cursorが変化済みなら待たず`changed`を返す。
+3. 変化が無い時だけ短いintervalで再計算する。deadlineはmonotonic clockで固定し、wall clockの進退を
+   duration判定へ使わない。DB transaction、file handle、host固有index snapshotをsleep中に保持しない。
+4. 各wake後はtimeout判定より先にcompleted cursorを再計算する。deadline以上でも最後の一回がchanged、
+   `resync_required`、`ambiguous_parent`ならその状態を返し、最後までunchangedの時だけ`timeout`を返す。
+   deadline後に追加のpoll cycleは開始しない。
+5. wait wireは`throughline.observer_wait.v1`とし、次のshapeだけを返す。raw project path、本文、session／
+   thread／origin ID、host index pathを含めない。
+
+   ```json
+   {
+     "schema": "throughline.observer_wait.v1",
+     "status": "changed",
+     "afterCursor": "tlc1....",
+     "throughCursor": "tlc1...."
+   }
+   ```
+
+   | status | throughCursor |
+   |---|---|
+   | `changed` | 呼出seriesの新しいcompleted cursor |
+   | `timeout` | 入力`afterCursor`と同値 |
+   | `resync_required` | `null` |
+   | `ambiguous_parent` | `null` |
+
+6. AbortSignalが呼出前または待機中にabortされたら成功wireを返さず、固定codeを持つcancel errorで終了する。
+   signalと完了が同じwakeで競合した時は、abort観測後に新しい成功pollを開始しない。pending timerを解除し、
+   Libraryは呼出後にlistener／handleを保持しない。
+7. 公開CLIは次とし、`--project`、`--after-cursor`、`--json`を必須にする。未知／重複option、値欠落、
+   範囲外timeoutを拒否する。`--timeout-seconds`既定は3600である。
+
+   ```text
+   throughline observer-wait --project <absolute-existing-directory>
+     --after-cursor <opaque> [--timeout-seconds <1..3600>] --json
+   ```
+
+8. 4種の既知状態はstdout単一行JSON、stderr空、exit 0とする。hard failureはstdout空、stderr単一行の
+   固定error JSON、exit 1とし、例外本文やpath／cursor／hash／raw identityを転記しない。
+
+   | 条件 | code | message |
+   |---|---|---|
+   | CLI構文／timeout形式 | `E_OBSERVER_WAIT_ARGS` | `invalid observer-wait arguments` |
+   | projectのhard input拒否 | `E_OBSERVER_WAIT_INPUT` | `observer wait input is invalid` |
+   | signal／parent disconnect | `E_OBSERVER_WAIT_CANCELLED` | `observer wait was cancelled` |
+   | その他の内部失敗 | `E_OBSERVER_WAIT_INTERNAL` | `observer wait failed` |
+
+9. CLIは`SIGINT`、`SIGTERM`、Node IPCの`disconnect`を一つのAbortControllerへ写す。通常の子processが
+   IPC無しで親だけ終了する場合も一時間孤児化しないよう、起動時`ppid`を保存し、poll interval以下の
+   周期で`process.ppid`変化または`process.kill(parentPid, 0)`の`ESRCH`を検出してabortする。`EPERM`は
+   親不在の証拠にしない。終了時にsignal listenerと親watch timerを必ず外す。stdout／stderrのpipe断は
+   成功扱いにせず、`EPIPE`を握りつぶして別経路へfallbackしない。
+10. cursorのversion、project、prefix、rollback不一致はLibrary既定どおり`resync_required`でexit 0とする。
+    waitはDB本文freshnessを待たず、`changed`後の`observer-read`が`projection_pending`を裁定する。
+
+## Consequences
+
+- 呼出前に完了済みなら即時changed、待機中なら次poll、deadline境界なら最終再確認で回収できる。
+- timeout、resync、曖昧親、cancelを混同せず、Observerは保存cursorを安全に据え置ける。
+- 一時間waitでもtransactionやtimer leakを残さず、read側のDB freshness責務を重複しない。
+- OSがSIGKILLした場合のcleanupや親死活監視daemonは非目標であり、通常signal／IPC／pipe契約を越えて
+  成功を偽装しない。

package/docs/adr/0009-observer-integration-regression-and-docs.md

@@ -0,0 +1,37 @@
+# ADR 0009: Observer統合の関連回帰と公開文書を受け入れる
+
+日付: 2026-07-15
+
+## Status
+
+Accepted
+
+## Context
+
+Observer向けcompleted-turn feedは、追加したread/wait境界だけでなく、既存のClaude Stop hook、Codex
+capture、auditor-context、token monitorとの互換を維持する必要がある。また、実装済みの公開CLI契約を
+README、AI向け正典、docs overview、CHANGELOGへ同期し、DB直接監視をfallbackとして案内してはならない。
+
+## Decision
+
+1. 次の関連gateをO1統合回帰として受け入れる。
+
+   ```text
+   node --import ./src/test-env.mjs --test \
+     src/hook-entrypoints.test.mjs src/codex-capture.test.mjs \
+     src/auditor-context.test.mjs src/cli/auditor-context.test.mjs \
+     src/cli/codex-hook.test.mjs src/token-monitor.test.mjs
+   ```
+
+   結果は130件成功、失敗・skip・cancel・todo各0、実行時間807.298msだった。
+2. commit `fb558d7`のREADME、CLAUDE.md、`docs/00_overview.md`、CHANGELOG同期を受け入れる。
+3. 文書は`observer-read`／`observer-wait`をJSON-only CLIとして説明し、opaque cursor、read/wait状態、
+   `projection_pending`、最大3600秒wait、Claude receiptとCodex `task_complete`のcompleted境界を記録する。
+4. ThroughlineはMCP serverを所有せず、ObserverへDB、WAL、rolloutの直接監視fallbackを案内しない。
+5. 未公開、Phase full regression、pack gate、独立監査は完了扱いせず、次のO1 gateへ残す。
+
+## Consequences
+
+- O1の関連回帰と文書同期TODOを完了できる。
+- full `npm test`、`npm pack --dry-run --json`、独立監査はPhase完了時に一度だけ実行する。
+- このADRはTask `observer-feed-doc-sync`のfinalization Decisionとして使い、追記可能なplanは使わない。

package/docs/adr/0010-observer-o1-phase-acceptance.md

@@ -0,0 +1,49 @@
+# ADR 0010: Observer O1 Phaseを監査修正込みで受け入れる
+
+日付: 2026-07-15
+
+## Status
+
+Accepted
+
+## Context
+
+Observer向けcompleted-turn feedのPhase O1は、Claude receiptとCodex `task_complete`から
+host-neutralなcompleted chainを構築し、rollback、prefix差替え、pagination、deadline、cancel、
+privacyの境界を維持する。Phase完了候補でfull regressionと独立監査を一度ずつ実施したところ、
+監査は二つの実欠陥を発見し、監査時点の製品判定をFAILEDとした。
+
+1. Claude Stopが複数の過去turnを一括backfillした時、最後のpairしかreceiptへ公開しない。
+2. Codex project resolverがPOSIX pathまで小文字化し、caseだけ異なるprojectを誤照合し得る。
+
+## Decision
+
+1. 独立監査の製品判定FAILEDをControl revision 67でrejectとして保持する。監査の指摘を
+   成功扱いへ書き換えず、同じTODOへの独立監査も反復しない。
+2. P1はcommit `02a809f`で、backfillが返す全logical turn numberを時系列でClaude receiptへ
+   publishする。receipt storeのsame-pair冪等性により、DBだけ回収済みだった過去pairも穴埋めする。
+3. P2はcommit `88fafaf`で、POSIX pathのcaseを保持し、Windows drive pathだけを従来どおり
+   case-insensitiveに扱う。
+4. P1/P2修正後のfocused gateを受け入れる。
+
+   ```text
+   node --import ./src/test-env.mjs --test \
+     src/turn-backfill.test.mjs src/hook-entrypoints.test.mjs \
+     src/codex-thread-index.test.mjs
+   ```
+
+   結果は28件成功、失敗・skip・cancel・todo各0、実行時間693.58925msだった。
+5. Phase完了候補のfull `npm test`は監査前HEAD `c5d6f2d`で一度実施し、661件中660件成功、
+   失敗0、Windows限定1件skip、cancel・todo各0、実行時間32983.729625msだった。
+   監査後の変更範囲は上記focused gateで全て再検証した。fullを現HEADで再実行したとは扱わない。
+6. 修正後HEADの`npm pack --dry-run --json`は`throughline@0.6.3`、entryCount 190、shasum
+   `0d27e31c334f1f1941c27383e7f2a61f20c2e370`で成功した。`git diff --check`も成功した。
+7. Phase O1の実装・関連回帰・文書同期・full/pack・独立監査とその二指摘の修正を完了とする。
+   publish、registry、実端末展開は別Waveであり、このDecisionには含めない。
+
+## Consequences
+
+- Claude receiptとCodex `task_complete`のcompleted chainは、複数turn回収とPOSIX case境界を含めて
+  Observerのread/wait契約へ渡せる。
+- full regressionを細かな修正ごとに反復せず、監査後deltaをfocused gateで検証した証拠が残る。
+- このADRをTask `observer-feed-phase-audit`、Phase gate、Control finalizationの不変Decision証拠に使う。

package/docs/adr/0011-observer-o1-control-lane-reconciliation.md

@@ -0,0 +1,34 @@
+# ADR 0011: Observer O1 Controlのclosure laneを補正する
+
+日付: 2026-07-15
+
+## Status
+
+Accepted
+
+## Context
+
+Control `observer-feed-20260715`のPhase gateは、O1の主要実装Taskが完了したrevision 51の後、
+revision 52で`behavior-preserving`として宣言された。したがって、このgateが対象にするのは
+文書同期、full/pack、独立監査、最終統合からなるclosure laneであり、先行するO1実装全体を
+behavior-preservingと再分類するものではない。
+
+独立監査後、P1/P2の挙動修正がclosure中に必要になった。元gateを改変したり
+`behavior_change=not-applicable`のまま修正を隠したりしてはならない。
+
+## Decision
+
+1. P1/P2の修正受入はcorrective Control `observer-feed-o1-audit-fixes-20260715`が所有する。
+2. corrective Controlは`behavior-change` laneで、二つの修正受入Task、focused gate、
+   [ADR 0010](0010-observer-o1-phase-acceptance.md)をDecision証拠としてrevision 15でfinalize済みである。
+3. 元ControlのPhase gateはrevision 52以降のclosure統合だけを対象とし、
+   `behavior_change=not-applicable`はこのclosure laneに対してのみ記録する。
+4. 元Controlの独立監査FAILEDとworker rejectは保持し、corrective Controlのfinalizationを受けて
+   Phase O1全体を最終受入する。
+5. Phase gateを実装後に追加した事実は消さない。今後のPhaseは実装前にgateを宣言する。
+
+## Consequences
+
+- 挙動修正をbehavior-preservingへ偽装せず、二つのControlの所有境界が明示される。
+- 元Controlはclosure laneとして完了でき、O1の実装・監査・修正証拠を一つのDecision鎖へ統合できる。
+- このADRを元ControlのPhase gateとControl finalizationの不変Decision証拠に使う。

package/docs/adr/0012-claude-stop-transcript-flush-barrier.md

@@ -0,0 +1,32 @@
+# ADR 0012: Claude Stop receiptの前にtranscript flush barrierを置く
+
+日付: 2026-07-16
+
+## Status
+
+Accepted for implementation。Observer queue 19eを保持し、次のlive turnより先に修理する。
+
+## Context
+
+実Claude turnはassistant `end_turn`、Stop hook 4本・hook error 0、Throughline state更新まで成立したが、
+hook実行時の最新sessionにはuser／assistant bodyがなくcompletion receiptも作られなかった。同じtranscriptを
+turn後に現行parserで読むとlatest logical groupは1件だった。Claudeのasync Stop hookがfinal assistant行の
+永続化可視化より先に一度だけtranscriptを読み、`lastTurnNumber === null`で正常no-opしたflush raceである。
+
+## Decision
+
+1. Stop payloadに非空`last_assistant_message`がある場合、latest user groupの非junk assistant本文が
+   その値と一致するまで短いbounded intervalでtranscriptを再読する。
+2. `last_assistant_message`はcompletion identity／flush barrierにだけ使い、L2本文やreceipt digestの
+   ソースにはしない。本文は従来どおりtranscriptからDBへcommitしたpairだけを使う。
+3. latest user groupを必須にし、過去の同文assistantや前turnを一致として採用しない。
+4. deadlineまで一致しなければ明示errorと`HOOK_PROCESS_TURN_FAILED`を返し、completionなしへ丸めない。
+5. markerを持たない旧Claude hostは既存one-shot transcript parser契約を維持する。
+6. Claude Stop hookの`async: true`、DB schema、receipt wire、Observer cursorは変更しない。
+
+## Acceptance
+
+- user行だけの状態でhookを開始し、assistant行を遅延appendしても同じ実行でbody pairとreceiptを作る。
+- 過去turnのassistantがcurrent markerと同文でも、latest userが未完なら待機し、誤ったpairをpublishしない。
+- marker不一致のdeadlineはexplicit failureになり、runtime error ownerは一回だけ記録する。
+- 通常同期flush、markerなし旧payload、複数turn backfillの既存挙動を維持する。

package/docs/adr/0013-observer-read-busy-writer-gate.md

@@ -0,0 +1,46 @@
+# ADR 0013: Observer readは同時writerをboundedに待つ
+
+日付: 2026-07-16
+
+## Status
+
+Accepted。
+
+## Context
+
+queue 19eの実Codexで、2件目の`task_complete`とThroughline captureは成功した一方、同時に走った
+Observer production callerの`observer-read`が一度nonzeroとなり`E_THROUGHLINE_EXEC`で終了した。
+直後の同じ公開readは2件のcompleted turnを返した。campaign-private driverでも同じ書込み瞬間の
+単発nonzeroを観測しており、caller固有の失敗ではない。
+
+completed feedはDB lagを`projection_pending`として扱うが、SQLite lockをstale成功へ丸めてはならない。
+一方、通常のStop captureとreadの短い競合を即時hard failureにすると、正規の継続監視が不安定になる。
+
+## Decision
+
+1. `readCompletedPairProjection`のread-only SQLite connectionだけにbounded busy waitを設定する。
+2. lock解消後は同じDBの整合したsnapshotを読み、pair不足は従来どおり`projection_pending`にする。
+3. busy上限超過、schema不一致、project不一致、その他I/Oは従来どおりhard failureにする。
+4. CLI再spawn、別DB、古い本文、cursor進行へのfallbackは追加しない。
+5. Spotter向け`readAuditorContext`の既存lock failure契約は変更しない。
+
+## Acceptance
+
+- 別processがexclusive writer lockを保持中でも、上限内に解放すればcompleted projectionが同じpairを返す。
+- 上限を越えるlockとその他hard failureはnonzero契約を維持する。
+- Observer read／wait、auditor-context、Codex captureの関連gateを一度通す。
+- 修理済みcandidateでqueue 19e Codex 2-cycle liveを再確認する。
+
+実装gate（2026-07-16）:
+
+- focused `src/auditor-context.test.mjs`: 修正前15/16、修正後16/16 PASS。
+- related Observer read／wait、auditor、receipt、Codex hook／capture: 78/78 PASS。
+- 変更source／testの構文検査、新規ADR lint、`git diff --check`: PASS。
+
+Live acceptance（2026-07-16）:
+
+- 修理済みcandidateのqueue 19e実Codex r11で、親completed-turn 2件と同じObserver generationの
+  completed cycle 2件を確認した。
+- 初回cycle後65秒超の継続、pending reservation／cycle／model operation残留なしを確認した。
+- caller SIGINTはcancelled／exit 130、managed app-serverと親app-serverはterminalとなった。
+- projectは空のまま。raw ID、prompt、model output、credentialは保存していない。

package/docs/adr/0014-two-phase-handoff-ghost-baton.md

@@ -0,0 +1,112 @@
+# ADR 0014: 二相ハンドオフ — 幽霊SessionStartによるバトン奪取の排除と注入10k予算
+
+日付: 2026-07-17
+
+## Status
+
+Accepted（実装済み・live acceptance 済み — 本ADR末尾の記録参照）。
+
+## Context
+
+### Incident: バトンが幽霊セッションに奪われ、実セッションが記憶ゼロで始まる
+
+2026-07-17、dotagentsで同日2回（10:33 JST / 16:39 JST）、`/tl` バトンによる引き継ぎが
+沈黙して失敗した。`~/.throughline/logs/inheritance-decision.log` と DB の実測:
+
+- Claude Code は同一 project_path に対し短時間（実測 315ms / 488ms 差）に複数の
+  SessionStart hook を発火させることがある。うち一部は **transcript を一度も生成せず、
+  sessions 行の updated_at が誕生時刻のまま二度と動かない「幽霊セッション」** になる。
+- 旧実装は SessionStart で `consumeBaton`（BEGIN IMMEDIATE の SELECT+DELETE）→ merge →
+  stdout 注入を行っていたため、**先着した幽霊がバトンを消費して前任の全記憶
+  （skeletons 16件 / bodies 84件等）を吸い込み**、数百ms後の実セッションは
+  `baton_skip_reason: "missing"` で記憶ゼロで始まった。
+- 全期間実測: 同一projectで2秒以内の SessionStart ペアは 3,222 イベント中 56 ペア
+  （= 近接ダブル発火は日常的）。バトン存在時に近接ペアが起きた 2 回は 2 回とも幽霊が勝った。
+- 2026-05 の auto path でも、受け取り側 transcript が存在しない merge が 6 件あり、
+  幽霊 twin（source='clear' の二重発火）が前任に選ばれた形と整合する。
+
+**SessionStart 時点では実体と幽霊を判別する情報が原理的に存在しない。**
+実測で、本物のセッションの transcript ファイルも SessionStart hook 発火の約 461ms
+**後** に作られる（payload の `transcript_path` は「これから作られる予定のパス」）。
+したがって「消費前に transcript 実在を検査する」案は本物も全部弾いて成立しない。
+
+### 第二の欠陥: hook stdout 注入は10k超で file 化され、モデル可視が先頭2KBに劣化する
+
+対策検証中の実測（Claude Code 2.1.211、tracer 実験 + 全 transcript 掃引）:
+
+- SessionStart / UserPromptSubmit の hook stdout は約 10,000 字を超えると
+  `<persisted-output>`（保存ファイルパス + 先頭 2KB preview）に置換され、
+  **モデルに inline で見えるのは先頭 2KB だけ** になる。
+  9,501 字は inline 通過、15,286 字は file 化を確認。
+- 実運用の SessionStart 注入で 10k 超だった 12 件（2026-06-28 / v2.1.195 以降の全件）は
+  **12 件全部が劣化していた**（例: 64,148 字 emit → 可視 2,054 字）。
+  L1+L2 本体はモデルに読まれておらず、ヘッダ + 現在地アンカーが偶然 2KB 内に
+  収まっていたため引き継ぎが機能している風に見えていた。
+
+## Decision
+
+### 二相ハンドオフ（merge・注入を「実体の証明」まで遅延する）
+
+1. **SessionStart（第一相）は intent 登録のみ**。sessions INSERT と
+   `pending_handoffs`（schema v9）への登録だけを行い、consumeBaton / merge / 注入を
+   一切しない。auto path（source='clear'）の前任はこの時点で解決して
+   `auto_predecessor_id` に凍結する。
+2. **最初の UserPromptSubmit（第二相）が consume + merge + 注入を行う**。
+   プロンプト到達 = セッション実在の証明であり、幽霊は構造上ここに到達できない。
+   pending 行の consume は BEGIN IMMEDIATE で atomic（1 セッション 1 回）。
+3. **baton 適格性はセッション誕生時刻基準**: `age = pending.created_at - baton.created_at`
+   が `0 ≤ age ≤ TTL(1h)` のときだけ消費。負 age（自分の誕生後に書かれたバトン）は
+   **削除せず残置**（`future_baton`）— 走行中セッションの横取りと、multi-window で
+   本来の後継のバトンを先食いする穴を同時に塞ぐ。TTL の意味論
+   「/tl から新セッション開始までの猶予」は消費が遅延しても保存される。
+4. **auto path の前任候補に transcript 実在フィルタ**（導出パス or state file）。
+   幽霊 twin は transcript を持たないため前任に選ばれない（2026-05 型の再発防止）。
+   実前任は /clear 前に活動していた実体なので必ず transcript を持つ。
+5. **注入は10k予算内レンダリング** (`buildBudgetedResumeContext`, 上限 9,500 字):
+   ヘッダ + 現在地アンカーは常に全文、L1 → L2 の順に新しい側から予算まで詰め、
+   省略した行数は**注入文内に明示**し decision log にも記録する（黙って切らない）。
+   最新 L2 行が単体で予算超過なら切り詰めて `throughline detail` 参照を付す。
+6. 幽霊の pending 行は誰にも consume されず無害に残る（数百バイト/行）。
+   TTL ベースの GC は**入れない** — 長時間 idle 後の初回プロンプトから引き継ぎを
+   silent に奪う fallback になるため。
+7. 判定ログは `phase: 'session-start' | 'prompt-submit'` の2種を同じ
+   inheritance-decision.log に記録する（本 incident の一次証拠となった実績を保つ）。
+
+### 廃止・撤去
+
+- SessionStart の注入経路と、それにぶら下がっていた Phase 0-2 spike /
+  Phase 0-6 `initialUserMessage` テスト分岐（docs/10 で両 no-go 確定済みの実験残骸）。
+- 「UserPromptSubmit は注入しない」規約 — 理由だった「SessionStart との二重注入」が
+  SessionStart 注入の廃止で消滅したため、注入責務ごと UserPromptSubmit へ移す。
+
+## Acceptance
+
+実装 gate（2026-07-17、このMacで実施済み）:
+
+- `npm test` 680/681 PASS（1 skip は既存の win32 契約 skip）。
+- 新規回帰テスト: 幽霊先着 SessionStart がバトンを奪えず、実セッションの初回プロンプトが
+  記憶を受け取る（incident 再現形）/ 走行中セッションが future baton を奪えない /
+  bornAt 基準 TTL / pending consume の1回性 / 予算レンダリングの省略告知・切り詰め。
+- 10k 実測: 一時 UserPromptSubmit hook + `claude -p`（Haiku）の tracer 実験で、
+  11,953 字 stdout の 10k 境界後 tracer がモデル不可視、`<persisted-output>` 化を確認。
+
+Live acceptance（2026-07-17、このMacで dev 版 global install 後に実施）:
+
+- [x] 実 Claude Code（headless、実 hooks 経由）で、記憶セッション → `/tl` → 新セッション
+      初回プロンプトの引き継ぎを確認。後継が合言葉を即答し、decision log に
+      `phase=session-start`（pending_registered）→ `phase=prompt-submit`
+      （`triggered_path=baton`, `merged=true`, injection 2,095 字・省略ゼロ）が刻まれた。
+      DB は初回 hook 発火で v9 へ migrate（session `8452e936`、前任 `c8b485bd`）。
+- [x] 自己バトン食いの不在を実機確認: `/tl` を打った resume セッション自身の pending は
+      `baton missing` で消化され（消費が baton 書込より先）、バトンは後継まで残った。
+      `baton_age_ms` は誕生時刻基準（21,200ms）で記録された。
+- [x] 幽霊2体（c4f05b96 / 90cb0c0e）の記憶回収済み（skeletons 30 / bodies 166 /
+      details 2,247 を実セッション `9fb15563` へ。DB バックアップ
+      `throughline.db.backup-20260717-ghost-recovery` 取得済み）。
+- [ ] multi-window での近接 SessionStart 実機再現は未実施（幽霊の発生タイミングを
+      任意に誘発できないため。回帰は subprocess テストの incident 再現形で担保）。
+
+## 関連
+
+- 幽霊 SessionStart 自体は Claude Code 側の挙動（upstream 報告は別トラック）。
+- 10k persisted-output は third-party 仕様として rag/01-hooks に実測記録。

package/docs/adr/0015-l1-summarizer-model-effort-ratio.md

@@ -0,0 +1,81 @@
+# ADR 0015: L1 要約の既定を gpt-5.6-luna / effort low / 削減割合 1/5 にする
+
+日付: 2026-07-17
+
+## Status
+
+Accepted（実装済み・全テスト green。実運用での要約品質の継続観察は運用に委ねる）。
+
+## Context
+
+- オーナー方針: 裏方で動く AI は Codex に寄せる。GPT-5.6 系列（sol / terra / luna）の
+  登場を受け、コスト効率を含めてモデルを選定する。要約の目標量は文字数指定ではなく
+  **削減割合**で決めたい（割合はオーナーが設定で動かせること）。
+- 現行実装の問題: `summarizeWithCodexCli` は isolation のため `--ignore-user-config` で
+  `codex exec` を呼ぶが、これにより `~/.codex/config.toml` のモデル選択も読まれず、
+  **CLI 内蔵デフォルトで走っていた**（明示 `-m` なし）。
+- 基準線: 現行 Claude Haiku 経路は削減割合 1/5（`l2Text.length / 5` を「約N文字」に
+  換算してプロンプトへ渡す割合ベース。docs の「L1 = one-liner」記述は実装と乖離）。
+
+## 実測評価（2026-07-17、このMac）
+
+方法: 実 DB の L2 ターンをソースに、本番と同型のプロンプト・`codex exec` flag で要約を
+生成。**要約を見る前に**各ソースから要点チェックリスト（固有名詞・数値・因果・決定・
+未解決）を作成し、要約ごとの「要点拾い数」で採点。原文に無い内容の混入（捏造）は別枠で
+全数検査。判定者は親セッション（単一判定者、n は下記のとおり＝既定値選定には十分、
+論文品質ではない）。
+
+### Round 1: モデル × 削減割合（5ソース × 7構成 = 35ラン）
+
+| 構成 | 拾い率 | 備考 |
+|---|---|---|
+| Haiku@1/5（現行基準線） | 26/35 = 74%（timeout 1件込み。完走分のみ 93%） | **5本中1本が90秒 timeout で完全失敗**。本番はリトライ後 raw L2 fallback = 実質無圧縮 |
+| luna@1/5 | 32/35 = 91% | 6〜16秒 |
+| luna@1/10 | 80% / luna@1/15 | 64% |
+| terra@1/5 | 32.5/35 = 93% | luna+2%のために上位量を払う価値なし |
+| terra@1/10 | 73% / terra@1/15 | 60% |
+
+**結論1: 圧縮を 1/5 より強めると要点が死ぬ（93%→73〜80%）。モデルを賢くしても
+救えない＝情報量の物理であり、既定割合は 1/5 のまま。**
+
+### Round 2: luna の effort 比較（8ソース × {none, low, medium} × 2反復 = 48ラン）
+
+ソースは別プロジェクト由来3本（Caveat 技術報告 / OpenCClaw 指示書散文 / 6.2k字
+subagent 報告）を追加。`minimal` は luna 非対応（400 error。サポートは
+none/low/medium/high/xhigh）のため none を下端とした。
+
+| effort | 拾い率 | 中央値レイテンシ | 特徴的な欠落 |
+|---|---|---|---|
+| none | 103/116 = 89% | 11.8s | **物語の現在地を落とす**（親の裁定で再開済み→「裁定待ち」と書く ×2、設計矛盾の同型性、「効果検証はこれから」） |
+| **low** | **107.5/116 = 93%** | 12.4s | 最もバランス。反復ブレ ±1〜2項目 |
+| medium | 107.5/116 = 93% | 16.3s | low と同点。**事故の白状を2回とも落とした**（整理しすぎて都合の悪い脱線を刈る傾向） |
+
+捏造は Round 1+2 の全 82 有効ランで 0 件。
+
+**結論2: low が既定。medium は同点で 1.4 倍遅くコスト高。none は事実の羅列は拾えるが
+「誰が何を決めて今どこか」を落とし、再開用 L1 として痛い欠落をする。**
+
+## Decision
+
+1. **既定: `gpt-5.6-luna` / `model_reasoning_effort="low"` / 削減割合 0.2 (=1/5)**。
+2. `summarizeWithCodexCli` は明示 `-m` / `-c model_reasoning_effort=...` を渡す
+   （`--ignore-user-config` によるモデル未指定の穴を修理）。
+3. env で設定可能: `THROUGHLINE_L1_MODEL` / `THROUGHLINE_L1_EFFORT` /
+   `THROUGHLINE_L1_RATIO`（割合形式 0 < r ≤ 1）。**不正な RATIO は黙って既定へ
+   落とさず explicit error**（フォールバック禁止原則）。
+4. claude-primary の backend 順序を **codex-sidecar → Codex CLI (luna@low) → Haiku →
+   raw L2** にする。各段の失敗理由は結果 (`sidecarReason` / `codexCliReason`) に記録
+   する宣言済み fallback。codex-primary は従来どおり Codex CLI 一本で explicit error。
+   （実測で Haiku は timeout 完全失敗があり、luna は同等品質・半分以下のレイテンシ・
+   失敗ゼロのため、Haiku より先に置く。）
+5. sidecar `summarize-l1` preset のモデルは codex-sidecar（別repo）の所有。本 ADR では
+   変更しない。
+6. docs の「L1 = one-liner」記述は「割合ベース（既定 1/5）」へ修正する。
+
+## Acceptance
+
+- `npm test` 684/685 PASS（1 skip は既存 win32 契約）。
+- 新規テスト: 明示 `-m`/effort 引数、env 上書き、RATIO のプロンプト反映、不正 RATIO の
+  explicit error、claude-primary の sidecar→codex-cli→haiku 梯子。
+- 評価の生データ: 実測スクリプト・全要約・採点はセッション scratchpad（使い捨て）。
+  要旨は本 ADR の表が正本。

package/docs/adr/0016-push-pull-recall-injection.md

@@ -0,0 +1,93 @@
+# ADR 0016: 注入の push/pull 再設計 — 現在地 + 入るだけ L2 の push と recall CLI による pull
+
+- Status: accepted (2026-07-18 オーナー裁定)
+- 関連: [ADR 0014](0014-two-phase-handoff-ghost-baton.md)（9,500 字注入予算）、
+  [ADR 0015](0015-l1-summarizer-model-effort-ratio.md)（L1 要約体制）
+
+## 問題
+
+9,500 字の注入予算（hook stdout ~10k で `<persisted-output>` file 化、ADR 0014）の中で、
+旧 `buildBudgetedResumeContext` は **L1 を先に詰めてから L2 を詰めて**いた。実測
+（このMacのDB、L2 1 ターン中央値 ~800 字・平均 ~2,750 字）では L2 は 5〜10 ターンしか
+入らず、しかも L1 生成は `L2_WINDOW = 20` より古いターンにしか走らない（Stop 毎 1 件の
+遅延生成）ため、「予算落ちした 5〜20 ターン前」が **L2 も注入されず L1 も未生成**の
+記憶空白帯になっていた。省略告知は時刻列挙のみで、取り出しは 1 ターンずつ
+`throughline detail` を叩くしかなかった。
+
+## 検討して不採用にした案
+
+1. **固定 N ターン + per-role 切り詰めで L2 を保証し、残りに L1 充填**:
+   L1 生成閾値を N に連動させる案。pull 設計に移った時点で、注入 L1 が pull の L2×残り
+   と同じターンを二重に運ぶ矛盾が出て破棄（会話での敵対的整理）。固定 N 自体も
+   「軽い会話で予算を設計的に遊ばせる」ため破棄。
+2. **multi-hook による 10k 突破**: 実測で**可能**と確認した（下記「実測」）が、hook の
+   構造的想定（1 本 = 1 context string）に無い使い方であり、attachment 順序も非決定の
+   ため不採用。
+3. **全文ログのファイル書き出し + Read 誘導**: DB が正本なのに派生ファイルの寿命管理が
+   発生する。過去ターンのレコードは不変なので、スナップショット性は DB 直参照でも
+   担保できる。CLI 経由の DB 直参照に統一して不採用。
+4. **生 SQL をモデルに案内**: schema 講義で注入が太り、origin フィルタ等の誤クエリ事故面
+   が開く。`detail` と同じ「DB 直参照だがモデルにはコマンド 1 発」の流儀で不採用。
+
+## 決定
+
+push は「現在地」に徹し、過去は pull に出す。
+
+- **push（注入、9,500 字内）**: ヘッダ + 現在地アンカー + 案内セクション
+  （固定部として最優先予約・無条件表示）+ 残り全予算に **L2 を新しい順で
+  丸ごと入るターンだけ全文**（ターン単位の原子。固定 N なし・断片詰めなし・
+  ターン境界の自然な端数は許容）。**L1 は注入しない**。
+  最新ターンが単体で予算超過する場合だけ切り詰めて入れる（従来規則の維持）。
+- **pull（新 CLI `throughline recall` = read-only DB 直参照）**:
+  - `recall --l2 --session <id> --before <ISO8601 ms> --last <N>` —
+    境界より古いターンを新しい側から N 件、L2 全文（注入と同じ行文法 + L3 suffix）
+  - `recall --l1 --session <id> --before <ISO8601 ms> --skip <N>` —
+    --l2 の担当分を飛ばした先の全ターン一覧。**L1 要約があれば要約、無ければ
+    「未要約」と明示**して detail 誘導。冒頭に「全 M ターン / 要約済み K」を正直に表示
+  - 一点掘りは従来どおり `throughline detail <時刻>`（L2+L3）
+- **`L2_WINDOW = 20` は据え置き**。20 の意味が「push（入るだけ）+ pull（残り）」の
+  合計窓に再定義されるだけで、L1 要約ペース・Codex 側・schema への変更なし。
+
+### 間抜け防止 — 機械用境界の完全焼き込み（refuter 敵対的検証 2026-07-18）
+
+実装前に refuter による敵対的検証を通し、real 指摘 6 件を全て設計へ反映した:
+
+| 指摘 | 対処 |
+|---|---|
+| HH:MM:SS 境界は「当日」解決（sc-detail の `timeToUnixRange`）で深夜跨ぎに壊れる | `--before` は ISO 8601 完全日時（ms 精度）。表示用 HH:MM:SS と機械用境界を分離 |
+| 秒切り捨てで同秒行の境界包含が未定義 | 境界は strict less-than の ms 比較で規定 |
+| 20 ターン窓はクエリ時再計算のため、新セッションのターン追記で窓がスライドし古い側が黙って欠落 | `--last <残り件数>` も注入時に焼き込み、recall 側の窓再計算を全廃 |
+| L1 は遅延生成でバックログがあり「全 N ターンの要約」が虚偽になる。未要約ターンがどの取っ手からも見えない | `--l1` は全ターン一覧（要約 or 未要約明示）。件数は「全 M / 要約済み K」形式 |
+| 既定 session 解決（cwd 系）は Codex 併走・複数ウィンドウで非決定 | `--session` も焼き込み。recall は既定解決を持たない |
+| `getDb()` は mkdir + read-write open + migration を行い read-only 契約に反する | recall は `DatabaseSync(path, { readOnly: true })` + 存在チェック。DB を作成しない |
+
+併せて、予算詰めを行（role）単位からターン単位の原子に変更した（行単位だと同一ターンの
+assistant 行だけ入り user 行が pull 側に半身で現れ、境界の算術が濁るため）。
+
+## 実測
+
+### 新設計のレンダリング（2026-07-18、実 DB 191 ターンセッション）
+
+- totalChars 9,158 / 9,500、L2 9 ターン注入、残り 11 ターン、窓外 171 ターン
+  （要約済み 124 / 未要約 47）
+- 焼き込まれた案内コマンドをそのまま実行して、`--l2` が境界ぴったりから 11 ターン
+  （33k 字）、`--l1` が全 171 ターン一覧（118k 字、`--last` で部分取得可）を返すことを確認
+
+### multi-hook 10k 突破の実測（2026-07-18、Claude Code 2.1.211 / 不採用）
+
+- 同一 UserPromptSubmit に hook を 3 本登録 → それぞれ独立の `hook_success` attachment
+  になり 9,000 字 × 3 = 27,000 字が全部モデル可視 inline
+- 1 本だけ 12k にすると**その 1 本だけ**が `<persisted-output>` 化（隣の 9k は無傷）
+  = 10k 判定は per context string
+- 5 本 × 9k = 45,000 字でも全部可視。合算上限は 45k まで観測されず
+- **attachment の並び順は登録順と一致しない**（並列実行のため非決定）
+- 詳細は [rag/01-hooks/hook-stdout-10k-persisted-output.md](../../rag/01-hooks/hook-stdout-10k-persisted-output.md)
+
+## 帰結
+
+- 「5〜20 ターン前の空白帯」は消滅: 窓内の非注入分は `recall --l2` が verbatim で、
+  窓外は `recall --l1` が全ターン（未要約含む）で必ず到達可能
+- push は会話密度に自動適応（中央値 7〜8 ターン、軽い会話なら 10 ターン超、重くて 2〜3）
+- コンテキスト衛生は維持: pull はモデルが必要と判断した時だけ発生する
+- `handoff-executor` の injection stats は
+  `injected_l2_turns / remaining_l2_turns / older_turns / older_summarized` に更新

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [