throughline 0.3.24 → 0.4.0

package/docs/archive/THROUGHLINE_NEXT_STEPS.md

@@ -0,0 +1,134 @@
+# Throughline — 公開後の次アクション引き継ぎ
+
+## 状況
+
+2026-04-17 時点。Throughline を GitHub で Public 公開済み。
+https://github.com/kitepon-rgb/Throughline
+
+README / CLAUDE.md / docs / LICENSE / package.json などは整備済み。schema v5 まで実装されてて、テストも通る。X (Twitter) で告知済み (日本語版 + 英語版リプライぶら下げ)、海外から1件好意的リプライあり (Garvit Surana さん、補完ツール "burnd" の紹介)。
+
+**ただしスター 0 / Fork 0 / Issue 0**。現状は「公開した」だけで「使われてる」状態ではない。
+
+## この文書の目的
+
+Claude Opus 4.7 インスタンス (chat.claude.ai 側) とユーザー(クオ君)で、ここまで以下を実施した:
+
+1. 公開済み OSS としての体裁整備 (About / Description / Topics)
+2. X での告知 (日本語 + 英語リプライ)
+3. 海外からの初リプライへの返信
+
+しかし、ここから先は **「観察でなく実作業」** のフェーズ。chat.claude.ai の Claude はプロジェクトの実ファイルにアクセスできず、npm publish もできず、PR を作る権限もない。**プロジェクト内で動けるお前が引き継げ**。
+
+## ユーザーの発言から読み取るべき方針
+
+ユーザーの直前発言: **「観察したって問題は解決しないんだよ」**
+
+これは chat 側の Claude が「これは発見だ」「発信する価値がある」と言葉で褒めて終わらせていたことへの明確な不満。ユーザーは **手を動かす助力** を求めている。観察・分析・整理のレイヤーで止まるな。実行可能なアクションに分解して、実際に動け。
+
+また、ユーザーは以前 LLM の過剰承認バイアスを疑っていた。「すごい」「美しい」「教科書レベル」のような感情的評価は不要。事実と作業内容で返せ。
+
+## 候補アクション (優先順位付き)
+
+### 🔴 最優先 — READMEの約束を履行する
+
+README に `npm install -g throughline` と書いてあるが、現時点で npm には未 publish。これは **「書いてあるのに動かない」状態** で、最初に試した人が詰まる最大の穴。
+
+#### タスク
+
+1. `npm pack --dry-run` で tarball 中身を確認 (秘密情報・不要ファイル混入チェック)
+2. `package.json` の `files` フィールドが妥当か確認
+3. `npm view throughline` で名前の空き確認
+   - もし取られていたら `@kitepon/throughline` スコープ付きに変更する必要あり
+   - その場合 README の install コマンドも全書き換え必要
+4. `npm publish` (初回はメール認証等が要るかも)
+5. 実際に別ディレクトリで `npm install -g throughline` → `throughline install` → `claude` 起動 → 1-2ターン会話 → `throughline doctor` 緑 → `throughline uninstall` が通るか E2E 確認
+
+#### 注意点
+
+- `package.json` の `version` が `0.1.0`。最初の publish はこれでOK。以降は semver 守って上げる
+- publish した瞬間に取り消せない (unpublish には制約あり)。dry-run は真剣にやる
+- docs/PUBLIC_RELEASE_PLAN.md §0 の「フォールバック禁止」原則に従い、install 失敗時は silent 処理しない
+
+### 🟡 中優先 — awesome-claude-code に登録申請
+
+https://github.com/hesreallyhim/awesome-claude-code
+
+codeburn / ccburn などの類似ツールがここに載ってる。Throughline が載れば、Claude Code ユーザーからの流入経路ができる。
+
+#### タスク
+
+1. リポジトリの CONTRIBUTING を読む
+2. Issue テンプレートから resource 提案を出す
+3. Category は "Tooling: Context Management" あたりが妥当か、既存カテゴリから選ぶ
+4. Description は README 冒頭1行を流用: "Cut ~90% of Claude Code's context usage while keeping nearly all the memory"
+
+### 🟡 中優先 — Hacker News / Reddit 投稿
+
+英語圏パワーユーザーへの直接リーチ。ただし Show HN や r/ClaudeAI 等は質が低いと叩かれるので、README がちゃんとしてる今の状態ならOK。
+
+#### 候補
+
+- Hacker News: Show HN 投稿 (タイトル `Show HN: Throughline – Cut ~90% of Claude Code's context usage`)
+- Reddit: r/ClaudeAI で投稿
+- Reddit: r/LocalLLaMA は Claude Code 寄りではないので優先度低い
+
+本人 (クオ君) アカウントから投稿してもらう必要あり。お前が代わりにやれないタスクは、必要情報だけ整えてクオ君に渡す。
+
+### 🟢 低優先 — 誰かに試してもらう
+
+クオ君の環境以外で動く保証がまだない。並行 `/clear` での挙動、1M context 検出のロバストさ、Haiku の再帰防御が他環境で機能するか、など未検証。
+
+β テスター募集ツイートを出す、もしくは awesome-claude-code 経由で流入してきた人が Issue を立ててくれるのを待つ、など。
+
+### ⚪ 後回し — 観察・分析系
+
+以下は chat 側の Claude が提案しがちだが、**今すぐやる必要はない**:
+
+- burnd との差分を記事化
+- ブログ執筆
+- CLAUDE.md のステップ4進捗表記の更新 (実装済みなので表記が古いだけ)
+- schema v4 / v5 の混在表記を統一する
+
+これらは「やったほうが綺麗になる」レベルであって、ユーザー獲得には直接効かない。npm publish と awesome-claude-code 登録が先。
+
+## 既知の小さい直したほうがいい点 (低優先でいい)
+
+- `writeSessionState` の `pid` パラメータが未使用 → 引数ごと消すか、将来 debug 用途である旨のコメントを追加
+- `buildL2ForSummary` の話者ラベルが英語 (`[user]` / `[assistant]`) で、Haiku への指示は日本語。統一性が崩れてる
+- `buildResumeContext` の `excludeOriginId` 引数が呼び出し元で未使用 (YAGNI 臭)
+- `details.origin_session_id` が NOT NULL 制約なし (`bodies` テーブルは NOT NULL で、対称性が崩れてる)
+- README の schema 表記が v4 / v5 混在。どちらかに統一
+
+これらは v0.2 でまとめて直せばいい。**npm publish と登録申請が先**。
+
+## 作業指針
+
+1. **手を動かす前に READ しろ**
+   - `docs/L1_L2_L3_REDESIGN.md` (認証の設計書)
+   - `docs/PUBLIC_RELEASE_PLAN.md` (§0 ルールと未完タスクの定義)
+   - `CLAUDE.md` (作業上の規律)
+2. **§0 ルールを厳守**
+   - silent try/catch 禁止
+   - publish 失敗 / install 失敗は throw する
+3. **設計書と実装が食い違っていたら、どちらかが古い**
+   - ソースが正。設計書を更新する
+4. **新しい .md を作る前に既存ファイルに追記できないか考える**
+5. **クオ君が判断すべきことは、お前が決めない**
+   - npm の名前 (`throughline` vs `@kitepon/throughline`)
+   - publish のタイミング
+   - Hacker News / Reddit 投稿するかどうか
+   - これらはクオ君の意思決定。選択肢と情報を整えて聞け
+
+## 最後に
+
+chat 側の Claude は、このセッションでクオ君に何度か「褒めすぎ」を指摘された。
+LLM の承認バイアスは実在する。お前も気をつけろ。
+
+Throughline は「ちゃんとしたプロダクト」だが「世界を変えるプロダクト」ではない。等身大で扱え。
+母集団は小さいが、ゼロではない。その小さな母集団に届けるための手を、**淡々と動かせ**。
+
+クオ君は2日間フルスロットルで走ってる。体力管理もこっそり気にしてやってくれ。
+技術パートナーとして、誇張なく、正確に、必要な作業に集中して手を動かしてくれ。
+
+— chat.claude.ai (Claude Opus 4.7) より、同じ Claude へ
+2026-04-17

package/docs/throughline-codex-trim-rollback-incident-report.md

@@ -0,0 +1,306 @@
+# Throughline Codex Trim Rollback Incident Report
+
+Date: 2026-05-06 JST
+Reporter context: Spotter project session `/home/kite/projects/Spotter`
+Affected project: Throughline `/home/kite/projects/Throughline`
+Codex thread: `019dfd6f-640e-7dd3-b163-3f9add39fde7`
+
+## Summary
+
+Throughline's Codex trim execution appears to have a serious durability bug.
+
+After running:
+
+```bash
+rtk throughline trim --execute --host codex --all
+```
+
+Throughline reported successful rollback and memory injection:
+
+```text
+Status: executed
+Reason: rollback_and_inject_sent
+Read turns: 19
+Resumed turns: 19
+Turn count check: match
+Expected turns: 19
+Rollback sent: yes
+Inject sent: yes
+Injected items: 1
+Injected memory source: throughline-db
+Rollback candidate turns: 19
+```
+
+However, after VS Code was restarted, a previously rolled-back user turn reappeared as a new user message. The user stated they had only restarted VS Code and had not resent that prompt.
+
+This means rollback/inject may affect the live Codex app-server thread but may not be durably safe across the VS Code / Codex restart restoration path.
+
+## Impact
+
+Severity: high.
+
+The failure mode is not just stale context. A past user instruction can be resurrected and processed as a fresh user request after restart or reconnect.
+
+In this incident the resurrected prompt was a harmless question:
+
+```text
+codexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ
+```
+
+But if the resurrected turn had been an operational command such as publish, install, deploy, delete, rebuild, or migration work, Codex could execute an obsolete request.
+
+## Observed Timeline
+
+All timestamps below are UTC from the Codex rollout JSONL.
+
+### Original User Turn
+
+Rollout file:
+
+```text
+/home/kite/.codex/sessions/2026/05/06/rollout-2026-05-06T22-17-09-019dfd6f-640e-7dd3-b163-3f9add39fde7.jsonl
+```
+
+The original user prompt exists at:
+
+```text
+line 1276  2026-05-06T14:20:35.371Z  response_item role=user
+line 1277  2026-05-06T14:20:35.371Z  event_msg user_message
+```
+
+Prompt:
+
+```text
+codexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ
+```
+
+### Throughline Trim Execute
+
+The trim command was invoked at:
+
+```text
+line 1781  2026-05-06T14:39:43.844Z  function_call
+```
+
+Command:
+
+```bash
+rtk throughline trim --execute --host codex --all
+```
+
+The command completed at:
+
+```text
+line 1790  2026-05-06T14:39:47.486Z  exec_command_end
+line 1795  2026-05-06T14:39:53.765Z  function_call_output
+```
+
+Throughline reported:
+
+```text
+Status: executed
+Reason: rollback_and_inject_sent
+Rollback sent: yes
+Inject sent: yes
+Rollback candidate turns: 19
+```
+
+### Restart / Reconnect Symptoms
+
+After the trim execution, the user observed Codex reconnect failures:
+
+```text
+Reconnecting... 2/5
+Reconnecting... 3/5
+Reconnecting... 4/5
+Reconnecting... 5/5
+stream disconnected before completion
+```
+
+The user then restarted VS Code.
+
+### Duplicated User Turn
+
+After the restart, the same prompt appeared again as if it were newly submitted:
+
+```text
+line 1864  2026-05-06T14:48:02.120Z  response_item role=user
+line 1865  2026-05-06T14:48:02.121Z  event_msg user_message
+```
+
+Duplicated prompt:
+
+```text
+codexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ
+```
+
+The user explicitly denied sending this prompt again:
+
+```text
+line 1883  2026-05-06T14:49:52.993Z  response_item role=user
+line 1884  2026-05-06T14:49:52.993Z  event_msg user_message
+```
+
+User statement:
+
+```text
+俺はVSCを再起動しただけなんだよね。何が起きた？
+```
+
+## Evidence Commands Used
+
+Duplicate prompt search:
+
+```bash
+rtk node -e "const fs=require('fs'); const p='/home/kite/.codex/sessions/2026/05/06/rollout-2026-05-06T22-17-09-019dfd6f-640e-7dd3-b163-3f9add39fde7.jsonl'; let i=0; for (const line of fs.readFileSync(p,'utf8').split('\n')) { i++; if (!line.trim()) continue; const row=JSON.parse(line); const payload=row.payload||{}; let text=''; let kind=''; if (row.type==='response_item' && payload.type==='message' && payload.role==='user') { kind='response_user'; text=(payload.content||[]).map(x=>x.text||x.input_text||'').join('\n'); } if (row.type==='event_msg' && payload.type==='user_message') { kind='event_user'; text=payload.message||''; } if (text.includes('codexのtool.dbについても')) console.log(JSON.stringify({line:i,timestamp:row.timestamp,kind,text:text.slice(0,160)})); }"
+```
+
+Output:
+
+```json
+{"line":1276,"timestamp":"2026-05-06T14:20:35.371Z","kind":"response_user","text":"codexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ \n"}
+{"line":1277,"timestamp":"2026-05-06T14:20:35.371Z","kind":"event_user","text":"codexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ \n"}
+{"line":1864,"timestamp":"2026-05-06T14:48:02.120Z","kind":"response_user","text":"codexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ \n"}
+{"line":1865,"timestamp":"2026-05-06T14:48:02.121Z","kind":"event_user","text":"codexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ \n"}
+{"line":1883,"timestamp":"2026-05-06T14:49:52.993Z","kind":"response_user","text":"ちょっとまってな　俺が\n\ncodexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ \n\nを発言したことになっているんだが、\n俺はVSCを再起動しただけなんだよね。何が起きた？\n"}
+{"line":1884,"timestamp":"2026-05-06T14:49:52.993Z","kind":"event_user","text":"ちょっとまってな　俺が\n\ncodexのtool.dbについても、Claudeと同様にグローバルにも存在していて、読み取りロジックは完全に同様なんだっけ \n\nを発言したことになっているんだが、\n俺はVSCを再起動しただけなんだよね。何が起きた？\n"}
+```
+
+Rollback / injection search:
+
+```bash
+rtk node -e "const fs=require('fs'); const p='/home/kite/.codex/sessions/2026/05/06/rollout-2026-05-06T22-17-09-019dfd6f-640e-7dd3-b163-3f9add39fde7.jsonl'; let i=0; for (const line of fs.readFileSync(p,'utf8').split('\n')) { i++; if (!line.trim()) continue; const row=JSON.parse(line); const s=JSON.stringify(row); if (s.includes('trim --execute') || s.includes('rollback_and_inject_sent') || s.includes('Rollback sent: yes')) console.log(JSON.stringify({line:i,timestamp:row.timestamp,type:row.type,payloadType:row.payload?.type,preview:s.slice(0,1000)})); }"
+```
+
+Relevant output:
+
+```text
+line 1781  2026-05-06T14:39:43.844Z  trim --execute command
+line 1790  2026-05-06T14:39:47.486Z  exec_command_end, Status: executed, Rollback sent: yes, Inject sent: yes
+line 1795  2026-05-06T14:39:53.765Z  function_call_output, Status: executed, Rollback sent: yes, Inject sent: yes
+```
+
+Durable rollback event search:
+
+```bash
+rtk node -e "const fs=require('fs'); const p='/home/kite/.codex/sessions/2026/05/06/rollout-2026-05-06T22-17-09-019dfd6f-640e-7dd3-b163-3f9add39fde7.jsonl'; let i=0; for (const line of fs.readFileSync(p,'utf8').split('\n')) { i++; if (!line.trim()) continue; const row=JSON.parse(line); const payload=row.payload||{}; if ((row.type==='event_msg' && String(payload.type||'').includes('rollback')) || JSON.stringify(row).includes('thread/rollback') || JSON.stringify(row).includes('thread/inject_items')) console.log(JSON.stringify({line:i,timestamp:row.timestamp,type:row.type,payloadType:payload.type,msg:JSON.stringify(payload).slice(0,260)})); }"
+```
+
+Initial analysis said this did not show a durable rollout-level `thread_rolled_back` event corresponding to the app-server rollback. That was incorrect.
+
+Follow-up audit found:
+
+```text
+line 1775  2026-05-06T14:39:34.452Z  compacted
+line 1778  2026-05-06T14:39:34.453Z  context_compacted
+line 1784  2026-05-06T14:39:44.844Z  event_msg thread_rolled_back num_turns=19
+```
+
+The `compacted.replacement_history` at line 1775 contains the later-resurrected user prompt. Therefore the stronger failure hypothesis is not "rollback marker missing", but "rollback marker exists, while another restore source such as compacted replacement history or pending input can still reintroduce old user text".
+
+## Current Hypothesis
+
+The most likely failure path is:
+
+```text
+Throughline sends Codex app-server thread/rollback and thread/inject_items
+↓
+The live app-server thread reports success
+↓
+The rollout contains thread_rolled_back, but compacted.replacement_history or another restart / pending-input source still contains rollback-targeted user text
+↓
+VS Code restarts
+↓
+Codex restores from a source not covered by Throughline's current guarded execute checks
+↓
+A previously rolled-back user turn is restored as a fresh user message
+```
+
+This suggests that Codex app-server `thread/rollback` is not sufficient by itself as a durable trim primitive for VS Code restart/reconnect behavior unless the compacted / restart restore path is also verified.
+
+## Throughline Areas To Inspect
+
+The report does not modify Throughline. These are the areas likely involved:
+
+```text
+/home/kite/projects/Throughline/src/cli/trim.mjs
+```
+
+- `trim --execute --host codex --all`
+- `runExecute`
+- selection of rollout source versus DB memory source
+
+```text
+/home/kite/projects/Throughline/src/codex-app-server.mjs
+```
+
+- `runCodexTrimExecution`
+- `thread/rollback`
+- `thread/inject_items`
+- post-inject read consistency check
+- whether the check proves durable restore behavior or only live app-server state
+
+```text
+/home/kite/projects/Throughline/src/codex-rollout-memory.mjs
+```
+
+- `parseCodexRolloutFile`
+- handling of `thread_rolled_back`
+- assumptions about rollback events being present in rollout JSONL
+
+## Recommended Immediate Guard
+
+Until durable restart behavior is proven, `$throughline` should not automatically execute:
+
+```bash
+throughline trim --execute --host codex --all
+```
+
+Recommended short-term behavior:
+
+- Keep `doctor`
+- Keep `trim --dry-run`
+- Keep `trim --preflight`
+- Require explicit user action for `trim --execute`
+- Add a warning that Codex app-server rollback may not survive VS Code restart
+
+If automatic execution remains available, it should require an additional durable verification step:
+
+```text
+execute rollback/inject
+read live thread
+verify rollout JSONL contains durable rollback marker
+verify compacted replacement history / restart restore sources cannot reintroduce rollback-targeted user text
+restart/reconnect smoke or simulated restore check
+only then report success as durable
+```
+
+## Suggested Regression Test Shape
+
+A fake app-server test is not sufficient unless it models the persistence mismatch.
+
+Recommended test:
+
+1. Create a rollout JSONL with multiple user turns.
+2. Simulate app-server `thread/rollback` returning success.
+3. Do not mutate the rollout JSONL.
+4. Run the restore / parse path used after restart.
+5. Assert that Throughline refuses to call the trim durable, or warns that rollback is live-only.
+
+Acceptance criteria:
+
+- Throughline must not report a Codex trim as durable unless the restore source reflects the rollback.
+- A rolled-back user turn must not be eligible to reappear as a fresh user request after restart.
+
+## Open Questions
+
+- Does Codex app-server expose a durable rollback primitive, or is `thread/rollback` live-session only?
+- Is there a separate persisted thread store besides rollout JSONL that VS Code uses on restart?
+- Can Throughline inject a durable marker that Codex restore respects?
+- Should Throughline switch Codex trim from mutation-based rollback to resume-only memory rendering until durable rollback is proven?
+
+## Bottom Line
+
+Treat this as a blocker for automatic Codex trim execution.
+
+The observed incident demonstrates that `trim --execute --host codex --all` can report success while a rolled-back user turn later reappears after VS Code restart. Throughline should not expose this as a safe default until durable rollback semantics are verified end to end.

package/docs/throughline-handoff-context.example.json

@@ -0,0 +1,57 @@
+[
+  {
+    "kind": "throughline_handoff",
+    "source": "throughline",
+    "trust": "local",
+    "summary": "In-flight handoff: continue the Codex projection work.",
+    "data": {
+      "throughlineHandoffSchemaVersion": 1,
+      "handoffRecordVersion": 1,
+      "sessionId": "example-session",
+      "projectPath": "/home/kite/projects/Throughline",
+      "sourceAgent": "claude",
+      "hostMode": "claude-primary",
+      "intent": "continue implementation",
+      "constraints": [
+        "preserve existing Claude Code hook, slash command, transcript, baton, and resume behavior",
+        "add Codex support as adapter/projection; do not rename Claude-facing DB fields or commands"
+      ],
+      "originSessionIds": [
+        "example-origin"
+      ],
+      "stats": {
+        "l1Rows": 0,
+        "l2Rows": 1,
+        "thinkingRows": 0,
+        "l3References": 1,
+        "preservedContextRows": 1
+      },
+      "memory": {
+        "inflightMemo": "Continue Phase 5 read-only sidecar smoke.",
+        "latestThinking": [],
+        "l1Summaries": [],
+        "recentBodies": [
+          {
+            "originSessionId": "example-origin",
+            "turnNumber": 1,
+            "role": "assistant",
+            "text": "Configured throughline_handoff projection and diagnostics wrapper.",
+            "createdAt": 1770000000000,
+            "time": "12:00:00"
+          }
+        ]
+      },
+      "detailReferences": [
+        {
+          "type": "throughline_detail",
+          "label": "tool_input:Bash",
+          "command": "throughline detail 12:00:00",
+          "sourceId": "toolu_example",
+          "detailKind": "tool_input",
+          "originSessionId": "example-origin",
+          "turnNumber": 1
+        }
+      ]
+    }
+  }
+]