throughline 0.6.2 → 0.7.0

package/docs/adr/0007-observer-read-cli-contract.md

@@ -0,0 +1,61 @@
+# ADR 0007: observer-read CLIはJSON-only read境界と固定error codeを持つ
+
+日付: 2026-07-15
+
+## Context
+
+ObserverはThroughlineの内部moduleやDBを直接読まず、公開CLIだけを子processとして呼ぶ。Libraryの
+`readObserverTurnPage`は既知状態を値で返す一方、引数、page token、project、DB schema／project／I/Oの
+hard failureは例外で拒否する。CLIが例外本文、path、session、cursor、本文をstderrへ出すとprivacy境界を
+壊し、既知状態までnon-zeroへ丸めるとObserverがretry／resyncを正しく選べない。
+
+この契約はControlのDecision証拠に使うため、追記可能な計画書ではなく不変ADRとして置く。
+
+## Decision
+
+1. 公開入口は次とし、`--project`と`--json`を必須にする。`--after-cursor`、`--through-cursor`、
+   `--page-token`、`--limit`は各0回または1回だけ受理し、未知option、重複、値欠落、余剰位置引数を拒否する。
+
+   ```text
+   throughline observer-read --project <absolute-existing-directory>
+     [--after-cursor <opaque>] [--through-cursor <opaque>]
+     [--page-token <opaque>] [--limit <1..100>] --json
+   ```
+
+2. `--page-token`は`--after-cursor`と`--through-cursor`の両方がある場合だけ受理する。cursor／tokenの
+   decode、project canonicalization、固定series検証はCLIへ複製せず`readObserverTurnPage`へ委ねる。
+3. `snapshot`、`delta`、`thread_switched`、`host_switched`、`resync_required`、
+   `projection_pending`、`ambiguous_parent`はすべて既知状態である。stdoutへ
+   `throughline.observer_read.v1`を単一行JSONとして一度だけ出し、stderr空、exit 0とする。
+4. hard failureはstdoutを空に保ち、stderrへ次の固定shapeを単一行JSONとして一度だけ出し、exit 1とする。
+   error messageへ例外本文、path、body、cursor／token、hash、session／thread／origin IDを転記しない。
+
+   ```json
+   {"schema":"throughline.observer_read.v1","status":"error","code":"E_OBSERVER_READ_ARGS","message":"invalid observer-read arguments"}
+   ```
+
+5. 固定codeは次へ限定する。
+
+   | 条件 | code | message |
+   |---|---|---|
+   | CLI構文、必須／重複option、limit形式 | `E_OBSERVER_READ_ARGS` | `invalid observer-read arguments` |
+   | project／page tokenのhard input拒否 | `E_OBSERVER_READ_INPUT` | `observer read input is invalid` |
+   | DB schema不一致 | `E_OBSERVER_READ_DB_SCHEMA` | `observer read database schema is unsupported` |
+   | DB project不一致 | `E_OBSERVER_READ_DB_PROJECT` | `observer read database project does not match` |
+   | DB open／query／I/O失敗 | `E_OBSERVER_READ_DB_IO` | `observer read database could not be read` |
+   | 上記以外の内部失敗 | `E_OBSERVER_READ_INTERNAL` | `observer read failed` |
+
+6. 公開CLIへ`--db`、`--codex-home`、receipt store path、raw session指定を追加しない。製品標準pathと
+   host固有indexをlibrary既定で解決し、testはdependency injectionまたは隔離HOME／CODEX_HOMEを使う。
+7. `bin/throughline.mjs`はsubcommandを明示dispatchし、返却exit codeだけを`process.exitCode`へ写す。
+   import時にCLIを自動実行せず、parserと`run`はunit test可能に保つ。
+8. cursorのversion、project、prefix、rollback不一致はLibrary既定どおり`resync_required`の既知状態で
+   exit 0とする。page tokenのversion、binding、offset／prefix不一致だけはsilent skipを防ぐhard input
+   errorであり、`E_OBSERVER_READ_INPUT`へ写す。
+
+## Consequences
+
+- Observerはstdoutだけを成功／既知状態wireとしてparseでき、stderrは固定codeのhard failureだけになる。
+- DB遅延やresyncをprocess failureと誤認せず、page token改変やDB破損を成功JSONへ丸めない。
+- 内部例外や端末固有pathがadapter境界から漏れない。
+- waitのdeadline、poll、signal／parent disconnect契約は別ADR／Taskで扱い、read CLIへ混ぜない。

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/package.json

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

package/rag/01-hooks/hook-stdout-10k-persisted-output.md

@@ -0,0 +1,48 @@
+# Hook stdout は約 10k 字で `<persisted-output>` に file 化され、モデル可視は先頭 2KB に劣化する
+
+- **出典**: 自前実測（tracer 実験 + 全 transcript 掃引）。このMac、Claude Code 2.1.211
+- **取得日**: 2026-07-17
+- **確度**: confirmed（境界2点 + 実運用12件で再現）
+
+## 事実
+
+SessionStart / UserPromptSubmit の hook **plain stdout**（および文書上は
+`hookSpecificOutput` の context string）は、約 10,000 字を超えると inline 注入されず、
+transcript の `attachment.content` が以下に置換される:
+
+```
+<persisted-output>
+Output too large (11.7KB). Full output saved to: ~/.claude/projects/<proj>/<session>/tool-results/hook-<uuid>...
+<先頭 ~2KB の preview>
+...
+</persisted-output>
+```
+
+- 全文は attachment の `stdout` field に保存されるが、**モデル可視は `content`
+  (= path + 先頭 2KB preview) だけ**。モデルがツールでファイルを読まない限り本文は届かない。
+- 境界実測: **9,501 字は inline 通過 / 15,286 字は file 化**（公称上限は hooks reference の
+  「10,000 characters per context string」と整合）。
+- tracer 実験: 11,953 字 stdout の 10k 境界後 tracer は Haiku から不可視、境界前 tracer は可視。
+
+## 影響（Throughline での実害）
+
+実運用 transcript 掃引の結果、SessionStart 注入で 10k 超だった **12 件（2026-06-28 /
+v2.1.195 以降の全件）が 12 件とも劣化**していた（例: 64,148 字 emit → 可視 2,054 字）。
+記憶注入の L1+L2 本体はモデルに読まれておらず、ヘッダ + 現在地アンカーが偶然先頭 2KB に
+収まっていたため「機能している風」に見えていた。
+
+v2.1.195 より前に 10k 超を emit した実績が手元に無いため、「いつ導入されたか」は未確定。
+運用上は「現行版では 10k 超 = 劣化」で確定。
+
+## 対処
+
+注入は予算内レンダリングで行う（Throughline は `buildBudgetedResumeContext`、上限 9,500 字。
+ヘッダ + アンカー常時全文、L1 → L2 を新しい側から詰め、省略は注入文へ明示）。
+詳細は [ADR 0014](../../docs/adr/0014-two-phase-handoff-ghost-baton.md)。
+
+## 検証手順（再現用）
+
+1. 一時 project に `.claude/settings.json` で UserPromptSubmit hook を登録し、
+   10k 境界の前後に tracer を置いた ~12k 字を stdout に emit する
+2. `claude -p --model claude-haiku-4-5-*` で「見えている tracer を列挙して」と問う
+3. transcript の `attachment.content` / `attachment.stdout` を比較する

package/rag/INDEX.md

@@ -86,6 +86,10 @@ Verified via [openclaude source](04-skills/raw/initialUserMessage-investigation.
 
 SessionEnd reason enum: `clear|resume|logout|prompt_input_exit|bypass_permissions_disabled|other`、default timeout 1.5s（/clear にも適用）— [session-end-reasons.md](01-hooks/raw/session-end-reasons.md)。実測: ビルトイン /clear はどのクライアントでも UserPromptSubmit に届かない（同一セッション /tl 対照実験 ×2 + VSCode 2.1.207）。VSCode は `source:"clear"` を送るが Desktop 2.1.205 は `source:"startup"`（クライアント実装差・バージョン交絡棄却済み）。→ Desktop の /clear 検知は SessionEnd(reason='clear') が唯一の hook 経路候補（実機検証は [docs/12](../docs/12_desktop_clear_handoff_plan.md) A Phase 1）。
 
+### Finding 9: hook stdout は ~10k 字で persisted-output に file 化、モデル可視は先頭 2KB のみ (2026-07-17)
+
+SessionStart / UserPromptSubmit の hook stdout は約 10,000 字超で `<persisted-output>`（保存ファイルパス + 先頭 2KB preview）に置換され、モデルには preview しか届かない（silent degradation、hook は exit 0 のまま）。境界実測 9,501 字 inline / 15,286 字 file 化。実運用の 10k 超注入 12 件（v2.1.195 以降）は 12/12 劣化 — 記憶注入の L1+L2 本体は読まれていなかった。対処は 9,500 字予算内レンダリング。詳細: [hook-stdout-10k-persisted-output.md](01-hooks/hook-stdout-10k-persisted-output.md)、[ADR 0014](../docs/adr/0014-two-phase-handoff-ghost-baton.md)。
+
 ---
 
 ## Throughline 仮説の見直し