throughline 0.3.22 → 0.3.24

package/README.ja.md

@@ -0,0 +1,255 @@
+<p align="center">
+  <img src=".github/og.png" alt="Throughline — Claude Code のコンテキスト消費を約 90% 削減しつつ記憶はほぼ残す" width="100%">
+</p>
+
+# Throughline
+
+[![npm version](https://img.shields.io/npm/v/throughline.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/throughline)
+[![license](https://img.shields.io/npm/l/throughline.svg?color=blue)](LICENSE)
+[![node](https://img.shields.io/node/v/throughline.svg?color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
+[![CI](https://github.com/kitepon-rgb/Throughline/actions/workflows/test.yml/badge.svg)](https://github.com/kitepon-rgb/Throughline/actions/workflows/test.yml)
+
+[English](README.md) · **日本語**
+
+> **Claude Code のコンテキスト消費を約 90% 削減しつつ、記憶はほぼそのまま残す。**
+> 「時間の新旧」ではなく **「コンテンツの種類」** で会話を分離する。人間が読みたいテキストは残し、機械が出力したツール I/O は SQLite に退避する。同じ判断、同じ文脈、9 割軽量。
+
+## 30 秒で始める
+
+```bash
+npm install -g throughline
+throughline install     # ~/.claude/settings.json に hook を登録
+```
+
+これだけ。Claude Code のセッションを開けば、以後すべてのターンが
+`~/.throughline/throughline.db` に自動で流れていく。50 ターン作業した後、
+次のセッションへ記憶を引き継ぎたければ `/clear` の前に `/tl` を打つ。新セッションは
+ゼロからのスタートではなく、**思考の途中から再開** される。
+
+## 他の手段との比較
+
+| | Throughline | MemGPT / SummaryBufferMemory | 素の Claude Code |
+|---|---|---|---|
+| **圧縮の軸** | コンテンツの **種類** (テキスト vs ツール I/O) | **新旧** (古い → 要約) | 無し |
+| **コーディング用途への適合** | 高 — ツール I/O こそ重い 80% | 中 — 残したい部分まで圧縮される | — |
+| **`/clear` 後の生存** | ✅ SQLite + `/tl` バトン | ホスト依存 | ❌ |
+| **誤継承リスク** | ゼロ (明示的な `/tl`) | 高 | — |
+| **ランタイム依存** | **ゼロ** (Node 22.5+ 同梱の `node:sqlite`) | 多数 | — |
+| **マルチセッション トークン監視** | ✅ 実測 `message.usage`、`len/4` 推定なし | — | — |
+
+<details>
+<summary><b>なぜこれが効くのか — 80% ツール I/O 問題</b></summary>
+
+通常の Claude Code セッションでは、**コンテキストの 80% はツール I/O** です —
+ファイル読み込み、Bash 出力、grep 結果。これらは Claude が即座に消費するデータですが、
+コンテキスト上には永久に残り、ウィンドウ上限に向かって押し出されていきます。
+
+Throughline はこの問題を、会話を **時間ではなく種類** で分離することで解決します:
+
+```
+Throughline 無し (50 ターン、/clear なし):
+  コンテキスト = ユーザー文 + アシスタント文 + ツール I/O + システムメッセージ
+              ≈ 125,000 トークン (うち 80% は二度と読み返さないツール I/O)
+
+Throughline 有り (50 ターン → /clear → 再開):
+  コンテキスト = 直近 20 ターンの会話本文 (L2)
+              + それ以前 30 ターンの一行要約 (L1)
+              + ツール I/O ゼロ (L3 — SQLite に退避、必要時にだけ取得)
+              ≈ 13,000 トークン — 同じ判断、同じ文脈、90% 軽量
+```
+
+MemGPT や LangChain の SummaryBufferMemory が **新旧** で圧縮するのに対し、
+Throughline は **コンテンツの種類** で分離します。人間が読むべき会話は残し、
+機械が生成した一過性のツール出力は退避する。コーディングアシスタント向けに
+特化した設計です。
+
+退避された L3 は失われていません。過去ターンのツール出力が再び必要になれば、
+Claude は `throughline detail <時刻>` で取り戻せます。
+
+Throughline は加えて、トランスクリプト JSONL から実測 API 使用量を読む
+**マルチセッション トークン監視ツール** も同梱しています (`length / 4` 推定は使いません)。
+
+</details>
+
+---
+
+## 3 層メモリーモデル (schema v7)
+
+```mermaid
+flowchart LR
+    T["1 ターン<br/>ユーザー · アシスタント · ツール · 思考"]
+    T --> H["Stop hook"]
+    H --> L2[("L2 · bodies<br/>本文そのまま")]
+    H --> L3[("L3 · details<br/>ツール I/O · 思考")]
+    H -. "非同期<br/>Haiku" .-> L1[("L1 · skeletons<br/>一行要約")]
+
+    L2 -- "直近 20 ターン" --> S["次セッション<br/>SessionStart 注入"]
+    L1 -- "それ以前" --> S
+    L3 -. "オンデマンド · throughline detail" .-> S
+
+    classDef l1 fill:#3aa0ff,stroke:#1a1f2e,color:#fff
+    classDef l2 fill:#7c5cff,stroke:#1a1f2e,color:#fff
+    classDef l3 fill:#4a5568,stroke:#1a1f2e,color:#fff
+    class L1 l1
+    class L2 l2
+    class L3 l3
+```
+
+| 層 | 名称 | 保存先 | 内容 | ターンあたりコスト |
+| --- | --- | --- | --- | --- |
+| **L1** | スケルトン | 古いターンとして注入 | Haiku が生成する一行要約 | 約 10 トークン |
+| **L2** | ボディ | 直近ターンとして注入 | ユーザー本文 + アシスタント返答そのまま | 自然なフルサイズ |
+| **L3** | ディテール | SQLite のみ | ツール I/O、システムメッセージ、画像、**拡張思考** (オンデマンド) | 重い、退避済 |
+
+3 層は **互いに補完的かつ排他的** で、重複保存はありません。
+拡張思考ブロックは L3 (`kind='thinking'`) に格納されるので、次セッションは
+**前セッションの Claude が中断時に何を考えていたか** を、発話だけでなく
+内省レベルで参照できます。`SessionStart` では **最終ターンの思考** が L2 履歴の
+直上にインライン注入され、それ以前の思考は `throughline detail <時刻>` で取得できます。
+
+`SessionStart` 時、Throughline は SQLite からコンテキストを再構築し、
+プレーンテキストとして注入します:
+
+- **直近 20 ターン** は L2 (`bodies`) のフル本文として注入
+- **それ以前** は L1 (`skeletons`) の一行要約として注入
+- L3 は SQLite に残り、`/sc-detail <時刻>` でオンデマンド取得
+
+L1 要約は `claude -p --model claude-haiku-4-5-*` サブプロセスで
+**Claude Haiku 4.5** が生成します。Claude Max のログイン認証を流用するため
+API キー不要です。要約は遅延実行で、20 ターン未満で終わるセッションでは
+Haiku は一度も呼ばれず、短いタスクの要約コストはゼロです。
+
+3 層 (L1/L2/L3) の書き込みパスは schema v5 から動作しています。
+`/sc-detail HH:MM:SS` はユーザー / アシスタント本文 (L2) と、そのターンで
+L3 に保存された `kind` 別 (ツール入力 / ツール出力 / hook 出力) を返します。
+
+---
+
+## 明示的引き継ぎ — `/tl` (in-flight メモ付き)
+
+引き継ぎは **明示的** であり、自動ではありません。次セッションへ「ここから続けてほしい」と
+渡したいときは、現セッションで `/clear` または新規チャットを開く **前に** `/tl` を打ちます。
+`/tl` 無しの場合、新セッションはまっさらな状態で始まり、過去メモリは引き継がれません。
+
+`/tl` は 2 つの仕事をします:
+
+1. **引き継ぎバトンの書き込み**。現在の `session_id` を `handoff_batons` テーブルへ、
+   `UserPromptSubmit` hook 経由で記録します。
+2. **現 Claude に in-flight メモを書かせる**。`/tl` は Claude に対し、
+   *次に何をしようとしていたか、現在の仮説、未解決の問い、進行中 TODO* を Markdown で
+   要約し、`throughline save-inflight` 経由でバトンの `memo_text` カラムに添付するよう
+   指示します。これにより、トランスクリプト再生だけでは保てない「いま考え中だった内容」を保存できます。
+
+次の `SessionStart` では、hook がバトンを読み、**1 時間以内** であれば
+そのセッションのメモリを `BEGIN IMMEDIATE` トランザクション内で
+`UPDATE session_id = ?` を使って決定論的にマージします。バトンはマージと
+原子的に消費 (削除) されるため、二重発火しません。注入される再開コンテキストは
+**「中断されたタスクの再開」** として再フレーミングされ、in-flight メモと最終ターンの
+拡張思考が先頭に来ることで、新 Claude は思考の途中から拾えます。
+
+```
+Session A (/tl を打つ)  -----------> バトン書き込み
+                                          |
+                          /clear           |
+                             |             ▼
+                          Session B  ---- バトン読込 → A を B にマージ → バトン削除 ---->
+                             |
+                          (もう一度 /tl で更に渡せる)
+```
+
+明示的バトン方式を選んだ理由:
+
+- **誤継承ゼロ**。並行ウィンドウや VSCode 再起動、同じリポジトリでの新規タスクが、
+  前セッションのメモリを誤って引き継ぐことはありません。`/tl` 明示時のみ発火。
+- **VSCode 拡張対応**。`SessionStart` hook の `source` フィールドは VSCode 拡張で
+  `/clear` 後も `"startup"` に書き換えられてしまう
+  ([issue #49937](https://github.com/anthropics/claude-code/issues/49937))。
+  source 判定は信用できないため、ユーザー駆動のバトンで回避。
+- **決定論的**。時間窓ヒューリスティック、PID 推測、祖先プロセス追跡なし。
+  ユーザーが意思を宣言し、hook が実行する。それだけ。
+
+各マージ行は `origin_session_id` を保持するので、`/tl` を繰り返すと
+記憶がチェーン状に蓄積します:
+
+```
+S1 (4 ターン) --/tl,/clear--> S2 (S1 をマージ + 3 ターン追加) --/tl,/clear--> S3 (S2 をマージ + 5 ターン追加)
+                              origin=S1×4                                    origin=S1×4, S2×3, S3×5
+```
+
+---
+
+## マルチセッション トークン監視
+
+実行:
+
+```bash
+throughline monitor            # 現プロジェクトのアクティブな全セッション
+throughline monitor --all      # 全プロジェクト、全セッション
+throughline monitor --session <id-prefix>
+```
+
+実機出力例 (1M context Opus セッション稼働中):
+
+```
+[Throughline] 1 セッション
+▶ Throughline       2ed5039c  ████░░░░░░░░░░░░░░░░  205.1k /  21%  残 794.9k  claude-opus-4-6
+```
+
+詳細仕様 (resize 追従、1M context 検出、ステイル隠し、Stop hook の非同期化など) は
+[英語版 README](README.md#multi-session-token-monitor) を参照してください。
+
+---
+
+## コマンド早見表
+
+| コマンド | 役割 |
+| --- | --- |
+| `throughline install` | `~/.claude/settings.json` (ユーザー全体) に hook を登録 |
+| `throughline install --project` | 現リポジトリの `.claude/settings.json` だけに hook を登録 |
+| `throughline uninstall` | hook を削除 |
+| `throughline monitor` | マルチセッション監視を起動 |
+| `throughline monitor --diag` | TTY/columns/env 診断ダンプ (描画バグ切り分け用) |
+| `throughline detail <時刻>` | あるターンの L2 本文と L3 ツール I/O を取得 (Claude が使う) |
+| `throughline save-inflight` | `/tl` から呼ばれ、現バトンに in-flight メモを添付 (stdin 経由) |
+| `throughline doctor` | Node バージョン、hook 登録状況、DB、PATH をチェック |
+| `throughline doctor --session <id-prefix>` | 特定セッションの state/transcript ズレを診断 |
+| `throughline status` | DB 統計表示 (sessions / skeletons / bodies / details) |
+| `throughline --version` | インストール済みバージョンを表示 |
+
+スラッシュコマンド (Claude Code 内でユーザーが叩く):
+
+| コマンド | 役割 |
+| --- | --- |
+| `/tl` | 引き継ぎバトンを書き込み + Claude に in-flight メモを書かせる |
+| `/sc-detail <時刻>` | 過去ターンの L2 本文と L3 ツール I/O を取得 |
+
+> `/tl` 発火時、Claude は Bash 経由で `throughline save-inflight` を呼びます。
+> 初回は許可確認が出るので、`Bash(throughline save-inflight:*)` を allowlist に
+> 追加すると以後の確認はスキップできます。
+
+---
+
+## 動作要件
+
+- **Node.js 22.5 以上** (組み込み `node:sqlite` モジュール使用、ネイティブビルド不要)
+- **Claude Code** (`SessionStart`, `Stop`, `UserPromptSubmit` hooks 対応版)
+- **Claude Max サブスクリプション** (Haiku ベース L1 要約のため `claude -p` 経由)
+- 対応 OS: **Windows / macOS / Linux**
+
+ランタイム依存 **ゼロ**。npm パッケージは純 `.mjs` ファイルのみで構成されています。
+
+---
+
+## 設計ドキュメント
+
+- [`docs/L1_L2_L3_REDESIGN.md`](docs/L1_L2_L3_REDESIGN.md) — L1/L2/L3 差分階層モデルの **設計仕様書** (schema v4 ベース + v5 L3 分類拡張)。記憶階層化ルールの正典
+- [`docs/INHERITANCE_ON_CLEAR_ONLY.md`](docs/INHERITANCE_ON_CLEAR_ONLY.md) — `/tl` バトン引き継ぎ方式の設計判断記録 (schema v6–v7)
+- [`docs/PUBLIC_RELEASE_PLAN.md`](docs/PUBLIC_RELEASE_PLAN.md) — 公開配布化プラン、§ 0 フォールバック禁止ルール、バージョン別実装ステータス
+- [`CHANGELOG.md`](CHANGELOG.md) — リリース履歴
+- [`docs/archive/`](docs/archive/) — 破棄済み旧設計 (CONCEPT 初期案、session-linking 実験記録など)
+
+---
+
+## ライセンス
+
+MIT — [LICENSE](LICENSE) 参照。

package/README.md

@@ -1,6 +1,45 @@
+<p align="center">
+  <img src=".github/og.png" alt="Throughline — cut ~90% of Claude Code's context usage while keeping nearly all the memory" width="100%">
+</p>
+
 # Throughline
 
-**Cut ~90% of Claude Code's context usage while keeping nearly all the memory.**
+[![npm version](https://img.shields.io/npm/v/throughline.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/throughline)
+[![license](https://img.shields.io/npm/l/throughline.svg?color=blue)](LICENSE)
+[![node](https://img.shields.io/node/v/throughline.svg?color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
+[![CI](https://github.com/kitepon-rgb/Throughline/actions/workflows/test.yml/badge.svg)](https://github.com/kitepon-rgb/Throughline/actions/workflows/test.yml)
+
+**English** · [日本語](README.ja.md)
+
+> **Cut ~90% of Claude Code's context usage while keeping nearly all the memory.**
+> Throughline separates conversation by **type, not time** — humans-readable text stays, machine-generated tool output retires to SQLite. Same decisions, same context, 90% lighter.
+
+## In 30 seconds
+
+```bash
+npm install -g throughline
+throughline install     # registers hooks in ~/.claude/settings.json
+```
+
+That's it. Open any Claude Code session and your turns flow into
+`~/.throughline/throughline.db` automatically. After 50 turns of work, type
+`/clear` (or just open a new chat), then `/tl` first if you want the next
+session to inherit the memory — the new session resumes mid-thought instead
+of starting from zero.
+
+## How it compares
+
+| | Throughline | MemGPT / SummaryBufferMemory | Plain Claude Code |
+|---|---|---|---|
+| **Compression axis** | content **type** (text vs tool I/O) | **recency** (old → summarized) | none |
+| **Coding-assistant fit** | high — tool I/O is the heavy 80% | medium — also compresses what you want to keep | — |
+| **`/clear` survival** | ✅ via SQLite + `/tl` baton | depends on host | ❌ |
+| **Auto-inheritance risk** | zero (explicit `/tl`) | high | — |
+| **Runtime deps** | **zero** (Node 22.5+ built-in `node:sqlite`) | many | — |
+| **Multi-session token monitor** | ✅ real `message.usage`, no `len/4` | — | — |
+
+<details>
+<summary><b>Why this matters — the 80% tool-I/O problem</b></summary>
 
 In a typical Claude Code session, **80% of the context window is tool I/O** —
 file reads, Bash output, grep results. This data is consumed the moment Claude
@@ -33,26 +72,32 @@ again.
 Throughline also ships a multi-session **token monitor** that reads real
 Anthropic API usage from the transcript JSONL (no `length / 4` heuristics).
 
----
-
-## Quick Start
-
-```bash
-npm install -g throughline
-throughline install
-```
-
-That's it. `install` registers Throughline's hooks in `~/.claude/settings.json`
-(user scope), so every Claude Code project on your machine picks it up
-automatically. No per-project wiring required.
-
-Start any Claude Code session and your turns will begin flowing into
-`~/.throughline/throughline.db` in the background.
+</details>
 
 ---
 
 ## Three-layer memory model (schema v7)
 
+```mermaid
+flowchart LR
+    T["Live turn<br/>user · assistant · tools · thinking"]
+    T --> H["Stop hook"]
+    H --> L2[("L2 · bodies<br/>verbatim text")]
+    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"]
+    L1 -- "older turns" --> S
+    L3 -. "on demand · throughline detail" .-> S
+
+    classDef l1 fill:#3aa0ff,stroke:#1a1f2e,color:#fff
+    classDef l2 fill:#7c5cff,stroke:#1a1f2e,color:#fff
+    classDef l3 fill:#4a5568,stroke:#1a1f2e,color:#fff
+    class L1 l1
+    class L2 l2
+    class L3 l3
+```
+
 | Layer | Name       | Where it lives        | Content                                                               | Cost per turn |
 | ----- | ---------- | --------------------- | --------------------------------------------------------------------- | ------------- |
 | **L1** | Skeleton  | injected when old     | one-line Haiku-generated summary of the turn                          | ~10 tok       |
@@ -201,6 +246,15 @@ Example output (real values from a running 1M-context Opus session):
   file. The monitor prefers this snapshot over re-reading the JSONL, which
   removes a source of flicker when the transcript path in state drifts from
   the one Claude Code is currently appending to.
+- **Non-blocking Stop hook (v0.3.22+).** The Stop hook is registered with
+  `"async": true` so `throughline process-turn` runs in the background and
+  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
+  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).
 
 ### VS Code auto-start (automatic)
 
@@ -414,6 +468,74 @@ Run `throughline doctor` — it checks Node version, hook registration, DB
 writability, and PATH resolution. If the binary is not on PATH, reinstall with
 `npm install -g throughline`.
 
+The most common cause is **the npm global `bin/` directory is not on PATH**.
+This happens when you set `npm config set prefix ~/.npm-global` (the sudoless
+recommended setup) but only added the export to `~/.profile`, not `~/.bashrc`.
+VSCode's integrated terminal launches an *interactive non-login* bash, which
+reads `.bashrc` only — so the export is silently skipped and `throughline` is
+not found. Fix:
+
+```bash
+# bash: add to ~/.bashrc
+if [ -d "$HOME/.npm-global/bin" ] ; then
+    PATH="$HOME/.npm-global/bin:$PATH"
+fi
+```
+
+Then reload the shell (`source ~/.bashrc`) and verify with `which throughline`.
+
+`throughline install` itself prints a warning to stderr if PATH resolution
+fails at install time, but if you missed it, run `throughline doctor` again.
+
+**Using Throughline across Windows ↔ WSL2 (or Linux ↔ macOS)**
+
+Two things to know:
+
+1. **The DB lives under `os.homedir()`**, so each environment has its own
+   database. `C:\Users\<you>\.throughline\throughline.db` (Windows) and
+   `/home/<you>/.throughline/throughline.db` (WSL2) are unrelated. Memory does
+   **not** roam. To migrate:
+   ```bash
+   # From WSL2, copy Windows-side DB into WSL2 home
+   cp /mnt/c/Users/<you>/.throughline/throughline.db ~/.throughline/throughline.db
+   ```
+   Or vice versa. Do this with no Claude Code sessions running so WAL/SHM are
+   clean.
+
+2. **WSL2 sees Windows npm shims via `/mnt/c/...AppData/Roaming/npm`**, which
+   may be earlier on PATH than your WSL2-native npm-global bin. Symptom:
+   `which throughline` returns a `/mnt/c/...` path even though you ran
+   `npm install -g throughline` inside WSL2. Fix: ensure
+   `~/.npm-global/bin` is **before** the Windows npm path in `PATH` (the
+   `.bashrc` snippet above prepends, so it does this naturally).
+
+**`.vscode/tasks.json` should not be committed to git (recommended)**
+
+The `Throughline Monitor` task that gets auto-generated contains absolute
+paths specific to your machine (`process.execPath` and the install location
+of `throughline.mjs`). For shared repositories, add one of these to
+`.gitignore`:
+
+```gitignore
+.vscode/tasks.json     # only ignore tasks.json (settings.json etc. stay shared)
+.vscode/                # ignore the whole .vscode directory
+```
+
+Throughline detects this and prints a one-time recommendation when it first
+creates / merges / repairs the file. (You don't have to follow the advice —
+v0.3.23+ auto-repairs stale absolute paths anyway, so committing is not
+catastrophic.)
+
+**Cross-environment `.vscode/tasks.json` errors after switching machines**
+
+If you commit `.vscode/tasks.json` to git and pull it on a different machine
+(Windows ↔ WSL2, Linux ↔ macOS, etc.), the `command` and `args` paths inside
+were absolutized to the original machine. Throughline auto-detects this:
+on the next hook fire it rewrites just the `command` / `args` fields to the
+current environment, preserving any `label` / `presentation` customization
+you made. You'll see a one-time `Reload Window` notice in Claude Code when
+the repair happens.
+
 **`node:sqlite` warning on startup**
 Node.js prints `ExperimentalWarning: SQLite is an experimental feature` on stderr.
 This is cosmetic — the module is stable enough for production and is used

package/package.json

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

package/src/cli/install.mjs

@@ -11,7 +11,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, unlinkSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+import { join, dirname, resolve, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
@@ -89,6 +89,54 @@ function uninstallSlashCommands(commandsDir) {
   return removed;
 }
 
+/**
+ * PATH 上で 'throughline' (Windows なら .cmd / .ps1 / .exe) が解決できるかを確認する。
+ *
+ * 解決できない場合 hook (`throughline session-start` 等) は command not found で
+ * silent fail する。npm の global prefix bin が PATH に通っていない (Linux/WSL2 の
+ * `~/.npm-global` 設定派が `.profile` だけに PATH を書いて `.bashrc` に書き忘れる
+ * パターンなど) と、ユーザーは「入れたのに何も起きない」状態に陥る。
+ *
+ * 戻り値: 解決できた絶対パス、見つからなければ null。
+ */
+export function resolveThroughlineOnPath(env = process.env) {
+  const pathEnv = env.PATH || env.Path || '';
+  const dirs = pathEnv.split(delimiter).filter(Boolean);
+  const exts = process.platform === 'win32'
+    ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';').filter(Boolean)
+    : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join(dir, `throughline${ext}`);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function emitPathWarning() {
+  const lines = [
+    '',
+    '警告: PATH 上で `throughline` コマンドが解決できません。',
+    '      hooks は PATH 経由で `throughline` を呼び出すため、このままでは静かに失敗します。',
+    '',
+    '対処:',
+    '  1) npm の global prefix を確認:  npm prefix -g',
+    '  2) その bin ディレクトリを PATH に追加',
+    '',
+  ];
+  if (process.platform === 'win32') {
+    lines.push('     Windows: 環境変数 PATH に %APPDATA%\\npm を追加');
+  } else {
+    lines.push('     bash:   ~/.bashrc に  export PATH="$(npm prefix -g)/bin:$PATH"  を追記');
+    lines.push('     zsh:    ~/.zshrc に同じ行を追記');
+  }
+  lines.push('');
+  lines.push('  3) シェルを開き直して `throughline doctor` で確認');
+  lines.push('');
+  process.stderr.write(lines.join('\n'));
+}
+
 function readSettings(settingsPath) {
   if (!existsSync(settingsPath)) return {};
   return JSON.parse(readFileSync(settingsPath, 'utf8'));
@@ -166,4 +214,8 @@ export async function run(args = []) {
     console.log('');
   }
   console.log('  アンインストール: throughline uninstall');
+
+  if (!resolveThroughlineOnPath()) {
+    emitPathWarning();
+  }
 }

package/src/cli/install.test.mjs

@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync
 import { tmpdir, homedir } from 'node:os';
 import { join } from 'node:path';
 
-import { run } from './install.mjs';
+import { run, resolveThroughlineOnPath } from './install.mjs';
 
 function makeTempHome() {
   const dir = mkdtempSync(join(tmpdir(), 'tl-install-test-'));
@@ -29,11 +29,14 @@ function makeTempHome() {
 function silence() {
   const origLog = console.log;
   const origErr = console.error;
+  const origStderrWrite = process.stderr.write.bind(process.stderr);
   console.log = () => {};
   console.error = () => {};
+  process.stderr.write = () => true;
   return () => {
     console.log = origLog;
     console.error = origErr;
+    process.stderr.write = origStderrWrite;
   };
 }
 
@@ -153,6 +156,45 @@ test('Stop hook is registered with async:true so it does not block ターン完
   }
 });
 
+// --- resolveThroughlineOnPath (地雷 1: PATH 解決チェック) ---
+
+test('resolveThroughlineOnPath: returns null when PATH is empty', () => {
+  assert.equal(resolveThroughlineOnPath({ PATH: '' }), null);
+  assert.equal(resolveThroughlineOnPath({}), null);
+});
+
+test('resolveThroughlineOnPath: returns null when not in any PATH directory', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-path-empty-'));
+  try {
+    assert.equal(resolveThroughlineOnPath({ PATH: dir }), null);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveThroughlineOnPath: finds throughline binary in PATH directory', () => {
+  // Windows は PATHEXT 経由でしか見つからないので分岐
+  const dir = mkdtempSync(join(tmpdir(), 'tl-path-found-'));
+  try {
+    if (process.platform === 'win32') {
+      const binPath = join(dir, 'throughline.cmd');
+      writeFileSync(binPath, '@echo off\n');
+      const result = resolveThroughlineOnPath({
+        PATH: dir,
+        PATHEXT: '.CMD',
+      });
+      assert.equal(result, binPath);
+    } else {
+      const binPath = join(dir, 'throughline');
+      writeFileSync(binPath, '#!/bin/sh\n');
+      const result = resolveThroughlineOnPath({ PATH: dir });
+      assert.equal(result, binPath);
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('install is idempotent: second run keeps exactly one tl.md and one hook entry', async () => {
   const home = makeTempHome();
   if (home.resolved !== home.dir) {