throughline 0.6.3 → 0.8.0

package/CHANGELOG.md

@@ -10,6 +10,103 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.8.0] — 2026-07-18
+
+### Changed (breaking behavior)
+
+- **Injection is now push/pull, and L1 is no longer injected (ADR 0016).** The
+  budgeted resume context (9,500 chars) is rebuilt as: header +
+  current-position anchor + an always-shown retrieval-guide section as the
+  fixed part, then the **entire remaining budget is filled with L2 turns in
+  full**, newest-first, turn-atomically (a user+assistant pair goes in whole
+  or not at all — no fixed N, no fragment packing). L1 summaries are no longer
+  injected; older memory is pulled on demand instead. The guide section bakes
+  in the exact session id, ISO-millisecond boundary (strict less-than) and
+  turn counts at injection time, so the pull side never recomputes the window.
+
+### Added
+
+- **`throughline recall --l2|--l1` (ADR 0016).** Read-only pull commands the
+  injected guide section points at. `recall --l2 --session <id> --before
+  <ISO ms> --last <N>` returns the N turns of full L2 bodies older than the
+  boundary, in the same line grammar as the injection (including L3 inline
+  suffixes). `recall --l1 ... --skip <N>` lists every turn older than the
+  `--l2` range with its L1 summary, honestly marking unsummarized turns
+  ("全 M ターン / 要約済み K") and always pointing at `throughline detail
+  <time>` for full text. The DB is opened read-only; a missing DB is an
+  explicit error and is never created or migrated.
+
+### Fixed
+
+- **Windows ACL scripts get a 15s timeout (was 3s).** On windows-latest CI
+  runners a cold PowerShell start was measured at 3.0–3.2s, so the 3s
+  `spawnSync` cap killed the ACL apply/verify scripts of the completed-turn
+  receipt store and the runtime error store and surfaced as a flaky
+  "Windows owner-only ACL verification failed" (2 consecutive runs, including
+  a docs-only commit). The explicit hard-failure contract is unchanged; only
+  the cap was raised.
+
+## [0.7.0] — 2026-07-17
+
+### Changed (breaking behavior)
+
+- **Two-phase handoff (ADR 0014).** Claude Code can fire multiple
+  `SessionStart` hooks for the same project within a few hundred ms, and some
+  of them never materialize into a real session (no transcript is ever
+  written). Such a "ghost" could consume the handoff baton first and silently
+  swallow the predecessor's memory while the real session started empty
+  (observed twice on 2026-07-17; upstream report:
+  anthropics/claude-code#78455). `SessionStart` now only registers a pending
+  intent (new schema v9 table `pending_handoffs`); the merge and the context
+  injection happen at the session's **first `UserPromptSubmit`** — a prompt is
+  proof the session is real, and a ghost never submits one. Baton eligibility
+  is measured against the consuming session's birth time (`0 <= birth −
+  baton_write <= 1h TTL`); a baton written after the session was born is left
+  in place for its true successor instead of being stolen by a running
+  session. The auto path (`source='clear'`) freezes its predecessor choice at
+  `SessionStart` and skips transcript-less (ghost) candidates.
+- **Injection is budgeted to 9,500 chars (ADR 0014).** Hook stdout larger than
+  ~10,000 chars is silently persisted to a file by Claude Code and the model
+  only sees the first 2KB (measured: 9,501 chars pass inline, 15,286 get
+  persisted; every >10k injection since v2.1.195 was degraded this way).
+  The resume context now always fits inline: header + current-position anchor
+  are kept in full, then L1 and L2 fill newest-first. Dropped L2 rows are
+  announced inside the injection with their `[time role]` references so the
+  model can retrieve any of them via `throughline detail`.
+- **L1 summarization backend and ratio are configurable (ADR 0015).** The
+  Claude-primary backend order is now `codex-sidecar` (when configured) →
+  Codex CLI (default `gpt-5.6-luna`, reasoning effort `low`, chosen by a
+  measured 83-run evaluation) → Claude Haiku → raw L2, with every fallback
+  step recording its reason. The compression target is a ratio (default 0.2 =
+  1/5 of the source turn). Overrides: `THROUGHLINE_L1_MODEL`,
+  `THROUGHLINE_L1_EFFORT`, `THROUGHLINE_L1_RATIO` (invalid ratio values are an
+  explicit error, not a silent default). The Codex CLI invocation now passes
+  an explicit `-m`; previously `--ignore-user-config` silently ran the CLI's
+  built-in default model.
+
+### Added
+
+- Schema v9: `pending_handoffs` table (session_id PK, project_path, source,
+  auto_predecessor_id, created_at). Rows belonging to ghost sessions are never
+  consumed and stay behind harmlessly.
+- The inheritance decision log now records both phases
+  (`phase: 'session-start' | 'prompt-submit'`) including injection size and
+  dropped-row counts.
+- First npm release to include the JSON-only completed-turn Observer CLI
+  boundary: `throughline observer-read` (opaque-cursor pages) and
+  `throughline observer-wait` (bounded wait up to 3600s). The completed feed
+  uses Throughline-owned Claude Stop receipts and Codex rollout
+  `task_complete` records; stale DB projection is reported as
+  `projection_pending` without bodies (ADR 0002–0013).
+
+### Fixed
+
+- Claude Stop waits for the transcript flush barrier before backfilling
+  (ADR 0012), and Observer reads wait out transient SQLite writer locks with a
+  bounded busy wait instead of failing hard (ADR 0013).
+
+## [0.6.3] — 2026-07-14
+
 ### Fixed
 
 - `throughline factory-diagnostics --json` now reports the Codex hook summary
@@ -1002,7 +1099,10 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.6.2...HEAD
+[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/kitepon-rgb/Throughline/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/kitepon-rgb/Throughline/compare/v0.6.3...v0.7.0
+[0.6.3]: https://github.com/kitepon-rgb/Throughline/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/kitepon-rgb/Throughline/compare/v0.6.1...v0.6.2
 [0.3.22]: https://github.com/kitepon-rgb/Throughline/releases/tag/v0.3.22
 [0.3.21]: https://github.com/kitepon-rgb/Throughline/compare/v0.3.19...v0.3.21

package/README.md

@@ -109,7 +109,7 @@ Anthropic API usage from the transcript JSONL (no `length / 4` heuristics).
 
 ---
 
-## Three-layer memory model (schema v8)
+## Three-layer memory model (schema v9)
 
 ```mermaid
 flowchart LR
@@ -119,7 +119,7 @@ flowchart LR
     H --> L3[("L3 · details<br/>tool I/O · thinking")]
     H -. "async<br/>Haiku" .-> L1[("L1 · skeletons<br/>one-liners")]
 
-    L2 -- "recent 20 turns" --> S["Next SessionStart<br/>injection"]
+    L2 -- "recent 20 turns" --> S["Next session's first prompt<br/>injection"]
     L1 -- "older turns" --> S
     L3 -. "on demand · throughline detail" .-> S
 
@@ -152,12 +152,17 @@ injects it as plain text:
 - L3 stays in SQLite and is retrieved on demand via `/sc-detail <time>`
 
 L1 summaries are generated lazily: for sessions that stay under 20 turns, no
-external summarizer is invoked. In the current Claude-primary path, Throughline uses **Claude Haiku 4.5**
-via a subprocess (`claude -p --model claude-haiku-4-5-*`), reusing your Claude
-Max login — no API key required. When `codex-sidecar` is explicitly configured
-for the `summarize-l1` preset, Throughline can use that instead.
-For Codex-primary capture, the L1 backend is the Codex CLI; failures are explicit
-and do not fall back to Claude Haiku or raw L2.
+external summarizer is invoked. Summaries target a **compression ratio**
+(default 1/5 of the source turn, configurable via `THROUGHLINE_L1_RATIO`;
+invalid values are an explicit error, not a silent default). In the
+Claude-primary path the backend order is: `codex-sidecar` (when explicitly
+configured for the `summarize-l1` preset) → **Codex CLI** (default
+`gpt-5.6-luna` at reasoning effort `low`, chosen by measured evaluation —
+see ADR 0015; override via `THROUGHLINE_L1_MODEL` / `THROUGHLINE_L1_EFFORT`)
+→ **Claude Haiku 4.5** via a subprocess (`claude -p`), reusing your Claude
+Max login — no API key required. Each fallback step records its reason.
+For Codex-primary capture, the L1 backend is the Codex CLI only; failures are
+explicit and do not fall back to Claude Haiku or raw L2.
 
 All three layers (L1/L2/L3) have working write paths as of schema v5.
 `/sc-detail HH:MM:SS` returns user/assistant text (L2) plus a kind-grouped view
@@ -177,13 +182,14 @@ flowchart LR
     U["User types<br/>/clear or /tl"] -->|UserPromptSubmit| W["writeBaton<br/>(session_id + TTL 1h)"]
     W --> B[("handoff_batons<br/>SQLite")]
     M["VSCode menu<br/>clear"] -->|no UserPromptSubmit| X["no baton"]
-    NS["Next SessionStart"] --> C{"baton<br/>present?"}
+    NS["Next SessionStart<br/>(registers intent only)"] --> FP["First user prompt<br/>(proof the session is real)"]
+    FP --> C{"baton<br/>present?"}
     B -.-> C
     X -.-> C
     C -->|yes| P1["baton path<br/>(primary)<br/>merge that exact predecessor"]
-    C -->|no, source='clear'| P2["auto path<br/>(fallback)<br/>findLatestClaudePredecessor"]
+    C -->|no, source='clear'| P2["auto path<br/>(fallback)<br/>predecessor frozen at SessionStart"]
     C -->|no, source!='clear'| P3["fresh session<br/>no merge"]
-    P1 --> INJ["inject L1 + L2 + L3 refs"]
+    P1 --> INJ["inject L1 + L2 + L3 refs<br/>(budgeted ≤ 9,500 chars)"]
     P2 --> INJ
 
     classDef primary fill:#7c5cff,stroke:#1a1f2e,color:#fff
@@ -198,9 +204,20 @@ flowchart LR
 
 When the user types `/clear` or `/tl` in the prompt, the `UserPromptSubmit`
 hook writes a handoff baton with **that session's `session_id`** into the
-`handoff_batons` table. The next `SessionStart` (within the 1-hour TTL)
-consumes the baton and merges that exact predecessor's memory into the new
-session, regardless of the `source` value.
+`handoff_batons` table. The next new session consumes the baton **at its
+first user prompt** (eligibility: the session must have been born within the
+1-hour TTL after the baton was written) and merges that exact predecessor's
+memory, regardless of the `source` value.
+
+Why the first prompt and not `SessionStart` itself: Claude Code can fire
+multiple `SessionStart` hooks for the same project within a few hundred
+milliseconds, and some of them never materialize into a real session (no
+transcript is ever written). At `SessionStart` time a real session and such a
+"ghost" are indistinguishable — even a real session's transcript file appears
+only ~0.5s **after** the hook fires. A ghost that consumed the baton first
+would silently swallow the predecessor's memory while the real session
+started empty. Deferring consumption to the first user prompt closes this:
+a ghost never submits a prompt, so it can never take the baton (ADR 0014).
 
 This path is deterministic: it names the predecessor by id rather than
 guessing, so multi-window scenarios where "most recently updated session"
@@ -216,8 +233,10 @@ typed /tl:    Session A → /tl    → (new chat / restart) → Session B (consu
 Since Claude Code 2.1.128, the SessionStart hook receives `source='clear'`
 reliably after `/clear`. When no baton is present (for example because the
 `/clear` was triggered by the VSCode extension's menu and never reached
-`UserPromptSubmit`), Throughline falls back to `findLatestClaudePredecessor`
-to pick the most recent unmerged session for the same project and merges it.
+`UserPromptSubmit`), Throughline resolves the most recent unmerged session
+for the same project **at `SessionStart` time** (freezing that choice, and
+skipping candidates that have no transcript — i.e. ghosts) and performs the
+merge + injection at the session's first user prompt.
 
 Set `THROUGHLINE_DISABLE_AUTO_HANDOFF=1` in your environment to opt out of
 this fallback. **The env var only affects the fallback**; typed `/clear` and
@@ -226,15 +245,23 @@ this fallback. **The env var only affects the fallback**; typed `/clear` and
 
 ### What gets injected
 
-Both paths inject the **same** curated memory:
+Both paths inject the **same** curated memory (push/pull design, ADR 0016):
 
 - A **"現在地 (latest exchange)"** anchor (added in v0.4.12) re-surfaces the
   most recent user directive and the most recent assistant turn directly under
   the header, each truncated to 600 characters
-- L1 summaries (older turns, one-line)
-- L2 verbatim (most recent 20 turns, full text)
+- A **pull guidance section** (always present) with ready-to-run
+  `throughline recall` commands — session id, an ISO-ms boundary, and turn
+  counts are baked in at injection time
+- L2 verbatim: as many of the most recent turns as fit the ~9,500-char
+  injection budget, packed whole-turn (typically 7–8 turns; more for light
+  conversations). **L1 summaries are not injected** — the rest of the
+  20-turn window is retrieved verbatim via `throughline recall --l2`, and
+  everything older via `throughline recall --l1` (summarized turns show
+  their L1 line; unsummarized ones are listed explicitly with a
+  `throughline detail` pointer)
 - L3 references (`throughline detail <time>` retrieval commands, attached
-  inline to each L1/L2 row; bodies stay in SQLite)
+  inline to each L2 row; bodies stay in SQLite)
 
 The injection is reframed as **"resuming an interrupted task"** rather than
 "reading past logs". The L2 verbatim already contains the last assistant
@@ -367,7 +394,8 @@ turns are `0`, there is no current trim saving under the active keep-recent
 setting.
 
 Claude-side rewind UI itself is not driven by Throughline. The auto-handoff
-flow is `/clear` → new SessionStart → automatic injection of curated memory.
+flow is `/clear` → new session → automatic injection of curated memory at the
+session's first user prompt.
 Throughline does not invoke `/rewind` or any Claude Code internal command.
 
 Codex-primary setup has an installed Stop hook after global
@@ -643,7 +671,7 @@ Example output:
   does not delay Claude's reply from reaching you. L1 Haiku summarization
   (`claude -p` subprocess + inference, seconds to tens of seconds) would
   otherwise stall the user-facing response of every turn; since L1 is only
-  needed for the *next* session's SessionStart injection, there is no reason
+  needed for the *next* session's injection, there is no reason
   to block the current turn on it. Existing installs need
   `throughline uninstall && throughline install` to promote the flag (the
   dedup logic skips entries that match by command string).
@@ -716,13 +744,15 @@ entry to the `tasks` array yourself:
 
 ## Commands
 
-**v0.6.3 はリリース準備中です。** factory diagnostics は Codex の managed
+**v0.6.3 は2026-07-14に公開済みです。** factory diagnostics は Codex の managed
 `UserPromptSubmit` / `PostToolUse` / `Stop` hooks がすべて canonical `ready` の場合に
 Codex readiness を `ready` と返す。Claude connector は未検査のまま明示的に
 `unverified` とし、Codex-only overall を妨げない。local runtime error
 aggregate は collection が既定OFFで、canonical dotagents config の
 `collection.enabled: true` を明示した場合だけ収集します。いずれも network I/O は
-行いません。v0.6.3 の npm publish、tag、GitHub Release は未実施です。
+行いません。`throughline@0.6.3`、tag / GitHub Release、公開 CI run
+`29284655280`（9/9 green）を確認済みです。npm registry artifact の shasum は
+`4f3fcd2598a75f026358dae7f3eb3165242b580b` です。
 
 | Command                                        | What it does                                                 |
 | ---------------------------------------------- | ------------------------------------------------------------ |
@@ -732,6 +762,9 @@ aggregate は collection が既定OFFで、canonical dotagents config の
 | `throughline monitor [--all] [--session <id>]` | Run the multi-session token monitor                          |
 | `throughline monitor --diag`                   | Dump TTY/columns/env diagnostics (for debugging monitor render bugs) |
 | `throughline detail <time>`                    | Retrieve L2 body text and L3 tool I/O for a turn (see below) |
+| `throughline recall --l2\|--l1 --session <id> --before <ISO> ...` | Pull older memory referenced by the injection's guidance section (read-only; the exact command is baked into each injection) |
+| `throughline observer-read --project <absolute-directory> --json` | Read one completed-turn Observer page through the JSON-only public boundary |
+| `throughline observer-wait --project <absolute-directory> --after-cursor <opaque> [--timeout-seconds 3600] --json` | Wait up to 3600 seconds for a completed-turn Observer cursor change |
 | `throughline doctor`                           | Check Node version, hook registration, DB writability, PATH  |
 | `throughline doctor --session <id-prefix>`     | Diagnose a specific session — detect state/transcript drift, idle vs. stuck |
 | `throughline doctor --trim --host claude\|codex` | Diagnose trim host boundaries, manual procedure, and Codex host primitive blockage |
@@ -775,8 +808,9 @@ Slash commands (invoked by the user in Claude Code):
 | `/sc-detail <time>` | Retrieve L2 body text and L3 tool I/O for a past turn       |
 
 > Since v0.4.1, both `/clear` and `/tl` typed in the prompt write a baton
-> identifying the current session, so the next `SessionStart` deterministically
-> inherits that exact predecessor. The `source='clear'` auto path remains as a
+> identifying the current session, so the next new session deterministically
+> inherits that exact predecessor (merge + injection happen at that session's
+> first user prompt — see ADR 0014). The `source='clear'` auto path remains as a
 > fallback for `/clear` triggered outside `UserPromptSubmit` (for example via
 > the VSCode extension menu); `THROUGHLINE_DISABLE_AUTO_HANDOFF=1` only opts
 > out of that fallback.
@@ -785,6 +819,29 @@ Hook subcommands (invoked by Claude Code, not by humans):
 `session-start` (SessionStart), `process-turn` (Stop),
 `prompt-submit` (UserPromptSubmit — detects `/tl` and `/clear` and writes a baton).
 
+### Observer completed-turn feed (development)
+
+`observer-read` and `observer-wait` are JSON-only, read-only CLI boundaries for
+the separate Observer product; Throughline does not add an MCP server or grant
+Observer access to its DB, WAL, or rollout files. Pass an existing absolute
+project directory. The returned `throughline.observer_cursor.v1` cursor is
+opaque and bounded: callers may store and return it, but must not decode or
+modify it.
+
+`observer-read` returns a completed-only `snapshot`, `delta`,
+`thread_switched`, or `host_switched` page. A stale or invalid cursor returns
+`resync_required`; a completed source whose DB pair projection is not yet fresh
+returns `projection_pending` without bodies. Pagination is bound to the exact
+project, after cursor, and fixed through cursor, so a newly completed turn is
+collected by the next wait instead of being mixed into an in-progress page.
+
+`observer-wait` returns one of four successful states: `changed`, `timeout`,
+`resync_required`, or `ambiguous_parent`. `timeout` preserves the input cursor.
+The default and maximum `--timeout-seconds` value is 3600. Claude completion is
+derived from Throughline's private Stop receipt; Codex completion is derived
+only from that host's rollout `task_complete`. The CLI never recommends DB
+polling as a fallback.
+
 ### `throughline detail` — for AI, not humans
 
 `throughline detail` is the escape hatch Claude itself uses to pull archived
@@ -862,7 +919,8 @@ Schema v8:
 - `skeletons` — L1 one-liners, keyed by `(session_id, origin_session_id, turn, role)`
 - `bodies` — L2 verbatim text (user + assistant), same key shape
 - `details` — L3 records with `kind` column (`tool_input` / `tool_output` / `system` / `image` / `thinking`) and `source_id` for idempotent re-processing
-- `handoff_batons` — one row per `project_path`, with `session_id` and `created_at`. Written by the `UserPromptSubmit` hook when the user types `/tl` or `/clear`. Consumed and deleted by the next `SessionStart` if within the 1-hour TTL. (v8 dropped the `memo_text` column when memo was retired in v0.4.0.)
+- `handoff_batons` — one row per `project_path`, with `session_id` and `created_at`. Written by the `UserPromptSubmit` hook when the user types `/tl` or `/clear`. Consumed and deleted at the next new session's **first user prompt**, if that session was born within the 1-hour TTL. (v8 dropped the `memo_text` column when memo was retired in v0.4.0.)
+- `pending_handoffs` — one row per newborn session (`session_id` PK, `project_path`, `source`, `auto_predecessor_id`, `created_at`). Registered by `SessionStart`, consumed exactly once by the session's first `UserPromptSubmit`. Rows belonging to ghost sessions are never consumed and stay behind harmlessly (a few hundred bytes each). Added in v9 (ADR 0014).
 - `injection_log` — audit trail of injection events
 
 All memory tables carry an `origin_session_id` so rebonded rows keep their
@@ -1014,7 +1072,7 @@ unchanged here.
 
 **Database got corrupted / want a clean slate**
 Delete `~/.throughline/throughline.db` (and the `-shm` / `-wal` companion files)
-and `~/.throughline/state/*.json`. A fresh database with schema v8 is created on
+and `~/.throughline/state/*.json`. A fresh database with schema v9 is created on
 the next hook fire.
 
 **New session didn't inherit memory from the previous one**

package/bin/throughline.mjs

@@ -9,6 +9,7 @@
  *   throughline process-turn  # Stop hook (Claude Code から呼ばれる)
  *   throughline session-start # SessionStart hook (Claude Code から呼ばれる)
  *   throughline detail <時刻> # L2+L3 詳細取得 (Claude が Bash 経由で呼ぶ想定)
+ *   throughline recall --l2|--l1 # 注入案内から辿る pull 用 read-only 記憶取得
  *   throughline handoff-preview # Codex-facing throughline_handoff JSON preview
  *   throughline auditor-context --json # Read-only bounded auditor context JSON
  *   throughline factory-diagnostics --json # Native factory read-only readiness JSON
@@ -66,6 +67,11 @@ switch (cmd) {
   case 'detail':
     (await import('../src/sc-detail.mjs')).run(rest);
     break;
+  case 'recall': {
+    const exitCode = (await import('../src/cli/recall.mjs')).run(rest);
+    process.exitCode = exitCode;
+    break;
+  }
   case 'handoff-preview':
     await (await import('../src/cli/handoff-preview.mjs')).run(rest);
     break;
@@ -74,6 +80,16 @@ switch (cmd) {
     if (exitCode !== 0) process.exitCode = exitCode;
     break;
   }
+  case 'observer-read': {
+    const exitCode = (await import('../src/cli/observer-read.mjs')).run(rest);
+    if (exitCode !== 0) process.exitCode = exitCode;
+    break;
+  }
+  case 'observer-wait': {
+    const exitCode = await (await import('../src/cli/observer-wait.mjs')).run(rest);
+    if (exitCode !== 0) process.exitCode = exitCode;
+    break;
+  }
   case 'factory-diagnostics': {
     const exitCode = (await import('../src/cli/factory-diagnostics.mjs')).run(rest);
     if (exitCode !== 0) process.exitCode = exitCode;
@@ -184,6 +200,10 @@ Usage:
                               Read only bounded completed user/assistant context
                               for an auditor; requires either --host plus --transcript,
                               or explicit pair identity/hashes; always requires --json
+  throughline observer-read --project <absolute-directory> --json
+                              Read one JSON-only completed-turn Observer page
+  throughline observer-wait --project <absolute-directory> --after-cursor <opaque> --json
+                              Wait for a completed-turn Observer cursor change
   throughline factory-diagnostics --json
                               Read-only native factory readiness JSON. Never emits
                               session/prompt bodies, secrets, absolute paths, or raw state

package/docs/00_overview.md

@@ -18,6 +18,7 @@
 | [10_transcript_injection_plan.md](10_transcript_injection_plan.md) | transcript injection 検証計画と v0.5 実機結果 |
 | [11_codex_monitor_implementation_plan.md](11_codex_monitor_implementation_plan.md) | Codex monitor 対応の実装記録 |
 | [13_native_factory_diagnostics_plan.md](13_native_factory_diagnostics_plan.md) | native factory read-only readiness 診断の実装記録 |
+| [14_observer_completed_turn_feed_plan.md](14_observer_completed_turn_feed_plan.md) | Observer向けcompleted-only read / wait CLIのactive計画。CLI・opaque cursor・pagination・最大3600秒waitは実装済み、公開／full regression gateは継続中 |
 | [BUGHUB_RUNTIME_ERROR_STORE_PLAN.md](BUGHUB_RUNTIME_ERROR_STORE_PLAN.md) | local runtime error aggregate store の契約と実装 TODO |
 
 ## Supporting Records
@@ -29,6 +30,17 @@
 | [archive/](archive/) | 破棄または履歴扱いの旧設計 |
 | [../rag/INDEX.md](../rag/INDEX.md) | 外部仕様・調査の再利用棚 |
 
+現行ADR:
+
+- [ADR 0001](adr/0001-claude-primary-codex-adapter.md): Claude primaryを維持し、Codexをadapterとして追加する。
+- [ADR 0002](adr/0002-observer-claude-completion-receipt.md): Claude completed turnはThroughline所有のStop receiptで固定する。
+- [ADR 0003](adr/0003-observer-completed-chain-cursor.md): Observer cursorをhost固有のcompleted pair chainとprefix検証へ束縛する。
+
+Observerの公開境界は`throughline observer-read`／`throughline observer-wait`のJSON-only CLIである。
+ThroughlineはClaude Stop receiptとCodex rolloutの`task_complete`だけからcompleted cursorを構築し、
+ObserverがDB、WAL、rolloutを直接監視するfallbackは持たない。waitは最大3600秒で、`changed`、`timeout`、
+`resync_required`、`ambiguous_parent`を返す。
+
 ## Entrypoints
 
 - [../CLAUDE.md](../CLAUDE.md): AI 作業者向けの正本。

package/docs/02_clear_auto_handoff_plan.md

@@ -17,6 +17,14 @@ A 案 (= /clear で自動引継ぎ + /tl は逃げ道として残す + /tl-trim
 > `THROUGHLINE_DISABLE_AUTO_HANDOFF=1` は **fallback path のみに作用** する
 > ようになった (typed `/clear` / `/tl` には効かない)。
 
+> **2026-07-18 (ADR 0016) update**: 注入の中身を push/pull 二段に再設計した。
+> push (9,500 字) はヘッダ + 現在地アンカー + 案内セクション + **L2 をターン原子で
+> 入るだけ全文**（L1 は注入しない）。窓 20 ターンの残りは `throughline recall --l2`、
+> それより古い全ターンは `recall --l1`（要約 or 未要約明示）で pull する。範囲・境界
+> (ISO ms)・件数・session は注入時に案内コマンドへ焼き込み、recall 側は窓を再計算
+> しない。正典は [ADR 0016](adr/0016-push-pull-recall-injection.md)。本書内の
+> 「L1 + L2 を注入する」旧記述はこの update で読み替えること。
+
 ---
 
 ## 1. 確定した事実 (実機検証済み)
@@ -67,33 +75,53 @@ source: [code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)
 
 ## 2. 採用する理想設計
 
-### 2.1 引継ぎ発火条件 (2 経路、v0.4.1 で baton primary に変更)
+### 2.1 引継ぎ発火条件 (2 経路 × 二相、ADR 0014 で二相化)
 
 | 経路 | 条件 | 起動 |
 |---|---|---|
-| **baton path (primary)** | `handoff_batons` テーブルに TTL (1 時間) 内 baton あり (= ユーザーが `/tl` または `/clear` を打った) | `source` 値関係なく確定的に引継ぎ |
-| **auto path (fallback)** | baton 不在 + `source='clear'` + env `THROUGHLINE_DISABLE_AUTO_HANDOFF` が `'1'` でない | `findLatestClaudePredecessor` heuristic で引継ぎ |
+| **baton path (primary)** | `handoff_batons` テーブルに「セッション誕生時刻基準で TTL (1 時間) 内」の baton あり (= ユーザーが `/tl` または `/clear` を打った) | `source` 値関係なく確定的に引継ぎ |
+| **auto path (fallback)** | baton 不在 + `source='clear'` + env `THROUGHLINE_DISABLE_AUTO_HANDOFF` が `'1'` でない | SessionStart 時点で凍結した前任 (transcript 実在フィルタ付き heuristic) へ引継ぎ |
+
+**二相化の理由 (ADR 0014)**: Claude Code は同一 project に短時間で複数の SessionStart を
+発火させることがあり、一部は transcript を生成しない幽霊になる。SessionStart 時点では
+実体と幽霊を判別できない (本物の transcript も hook より数百 ms 遅れて作られる) ため、
+merge・注入は「実体の証明」= 最初の UserPromptSubmit まで遅延する。
+2026-07-17 に幽霊がバトンを先取りして実セッションが記憶ゼロで始まる incident が
+同日 2 回発生した (詳細・実測は [ADR 0014](adr/0014-two-phase-handoff-ghost-baton.md))。
 
 判定ロジック (擬似コード):
 
 ```
 on UserPromptSubmit(prompt, session_id, project_path):
+  // ---- 第二相: 初回プロンプト = 実体の証明 ----
+  pending = consumePendingHandoff(session_id)   // atomic、1 セッション 1 回
+  if pending:
+    baton = consumeBaton(project_path, bornAt = pending.created_at)
+      // age = bornAt - baton.created_at。0 ≤ age ≤ TTL のみ消費。
+      // age < 0 (自分の誕生後に書かれた baton) は本来の後継のため残置
+    if baton.sessionId:
+      merge + inject(budgeted_memory_from(baton.sessionId))   // baton path
+    elif pending.auto_predecessor_id:
+      merge + inject(budgeted_memory_from(pending.auto_predecessor_id))  // auto path
+  // ---- 従来のバトン書き込み (第二相の後) ----
   if isBatonCommand(prompt) or isClearCommand(prompt):
-    writeBaton(project_path, session_id, now)  // typed /clear / /tl が確定的に baton を書く
+    writeBaton(project_path, session_id, now)
 
 on SessionStart(source, session_id, project_path):
-  baton = consumeBaton(project_path)  // atomic SELECT + DELETE, TTL 超過は sessionId=null で返る
-  if baton.sessionId:
-    inject(curated_memory_from(baton.sessionId))  // baton path (primary, env 関係なく発火)
-    return
+  // ---- 第一相: intent 登録のみ。merge も注入もしない ----
+  auto_predecessor = null
   if source == 'clear' and env.THROUGHLINE_DISABLE_AUTO_HANDOFF != '1':
-    predecessor = findLatestClaudePredecessor(project_path, session_id)
-    inject(curated_memory_from(predecessor))  // auto path (fallback)
-    return
-  // 何もしない
+    auto_predecessor = findLatestClaudePredecessor(project_path, session_id)
+      // transcript 実在フィルタ付き: 幽霊 twin (transcript 無し) を前任に選ばない
+  registerPendingHandoff(session_id, project_path, source, auto_predecessor)
 ```
 
-`consumeBaton` が先発なので「両方同時成立」は構造上発生しない (= baton ありなら baton 経路、無ければ source 判定)。typed `/clear` も UserPromptSubmit hook で baton を書くため、通常はほぼ常に baton path が走る。auto path は VSCode 拡張のメニュー由来 `/clear` のように UserPromptSubmit に届かない経路のためのフォールバック。
+baton 消費が auto 判定より先発なので「両方同時成立」は構造上発生しない。typed `/clear` も
+UserPromptSubmit hook で baton を書くため、通常はほぼ常に baton path が走る。auto path は
+VSCode 拡張のメニュー由来 `/clear` のように UserPromptSubmit に届かない経路のためのフォールバック。
+幽霊セッションはプロンプトを発火しないため第二相に到達できず、pending 行 (数百バイト) が
+無害に残るだけになる。TTL ベースの pending GC は置かない (長時間 idle 後の初回プロンプトから
+引継ぎを silent に奪う fallback になるため)。
 
 ### 2.2 注入内容: 現在地アンカー + L1 + L2 + L3 refs (baton/auto どちらの経路でも同一)
 
@@ -105,6 +133,12 @@ on SessionStart(source, session_id, project_path):
 - **L3 references** (= `throughline detail <時刻>` の取り出しコマンド一覧、各 L1/L2 行末尾の inline suffix として集約)
 - Continuation Instruction (= 「これは過去ログではなく現在進行中の作業」と明示)
 
+**注入予算 (ADR 0014)**: hook stdout は約 10,000 字超で `<persisted-output>`
+(ファイルパス + 先頭 2KB preview) に file 化され、モデル可視が先頭 2KB に劣化する
+(実測: 9,501 字 inline 通過 / 15,286 字 file 化。v2.1.195 以降の 10k 超注入 12/12 が劣化)。
+注入は `buildBudgetedResumeContext` (上限 9,500 字) で行い、ヘッダ + アンカーは常に全文、
+L1 → L2 の順に新しい側から予算まで詰める。省略行数は注入文内と decision log に明示する。
+
 含めない (= 削除):
 - 中断直前の in-flight memo (memo セクション)
 - 中断直前の thinking (extended thinking セクション)

package/docs/04_public_release_plan.md

@@ -139,6 +139,7 @@ schema v4 で PostToolUse (`capture-tool`) は廃止、L2/L3 は Stop 内で一
 | **npm 公開 (v0.4.7): Codex monitor direct discovery + 80% auto-refresh** | 2026-05-09 Codex Stop hook auto-refresh の verified usage threshold を 90% から 80% に変更し、Codex native auto-compact より先に Throughline DB memory refresh を試行する。estimate usage / estimated context window では mutation しない。`throughline monitor` は `~/.throughline/state` に加えて `~/.codex/sessions/**/rollout-*.jsonl` を直接 discovery し、Throughline state が未生成の現在 Codex thread も表示する。既存 state がある場合は state の usage snapshot を保持しつつ discovered rollout path / mtime を合流する。Codex 表示 ID は `codex:01` ではなく raw thread id 先頭 8 桁 (`019e085c`) にした。Codex open turn の transient `output_tokens` は token count に overlay するが、モデル欄の `live+<tokens>` marker は表示しない |
 | **npm 公開 (v0.6.1): Spotter auditor context projection** | `throughline auditor-context`を追加。exact session/projectと最新完了L2 pairのorigin/turn/hash freshnessを検査し、fresh時だけbounded user/assistant本文をversioned JSONで返す。DBはread-onlyで開き、作成・migration・WAL書き込みをしない。Spotter側はproject opt-inでのみ利用する。580 tests、CI 6/6、pack scan、registry global install / doctorを通過し、npm / tag / GitHub Releaseを2026-07-13に公開した |
 | **npm 公開 (v0.6.2): factory diagnostics + local runtime error store** | `throughline factory-diagnostics --json` と `throughline runtime-errors ... --json` を追加。collection は canonical dotagents config の `collection.enabled: true` が明示された時だけ有効で既定OFF、store は network I/O を行わない。公開commit `e6ce6e3`、CI `29238704750`、npm `latest`、tag / GitHub Release、registry由来隔離installと診断snapshotを2026-07-13に確認した |
+| **npm 公開 (v0.6.3): Codex diagnostics ready 集約 + Windows bounded observer** | 3 managed Codex hooks が canonical `ready` のとき hook summary / Codex connector を `ready` とし、未検査 Claude connector は明示 `unverified` のまま Codex-only overall から除外する。Windows runtime-error observer は、既存 state の使用前検証と新規 file の ACL 付与・read-back を維持しつつ、同一 mutation 内の重複 PowerShell ACL 検証を除いた。公開commit `fc83ddf`、CI `29284655280`（9/9 green）、npm `throughline@0.6.3`、tag / GitHub Release、npm shasum `4f3fcd2598a75f026358dae7f3eb3165242b580b` を2026-07-14に確認した |
 | **未リリース: Codex current-session 75% trigger** | Codex 自動発火を token-monitor に依存させず、global install が Codex `UserPromptSubmit` / `PostToolUse` hooks も登録する。hook は当該 Codex session の rollout `token_count` を直接読み、verified 75% 以上なら同じ user turn または tool loop 継続前に `$throughline` workflow 実行指示を `additionalContext` で注入する。Stop hook の guarded auto-refresh は残す。`~/.codex/config.toml` は旧 `codex_hooks = true` に加えて現行 `hooks = true` も有効化する |
 | **グローバル E2E 検証** | 2026-04-17 別ディレクトリから `throughline doctor` 全緑を確認 |