throughline 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -10,6 +10,27 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.8.5] — 2026-07-20
+
+### Added
+
+- `throughline migrate --json` now provides the product-owned database
+  migration entry point used after package updates. It migrates only an
+  existing Throughline database, reports a versioned bounded result, leaves a
+  missing database absent, and rejects future schemas or migration failures
+  with a non-zero exit status.
+
+## [0.8.4] — 2026-07-20
+
+### Fixed
+
+- The installed Codex skill now selects Desktop, VS Code, or CLI from the
+  current Codex surface and passes an explicit `--open-host` value. A command
+  launched through an older persistent PTY can no longer silently redirect a
+  Desktop handoff to the PTY's inherited VS Code or Terminal host.
+- `codex-handoff-start` now reports both requested and resolved open hosts in
+  JSON and text output while retaining the existing `openHost` field.
+
 ## [0.8.3] — 2026-07-20
 
 ### Fixed
@@ -1133,7 +1154,9 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.3...HEAD
+[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.5...HEAD
+[0.8.5]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.4...v0.8.5
+[0.8.4]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.3...v0.8.4
 [0.8.3]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.2...v0.8.3
 [0.8.2]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.0...v0.8.1

package/README.ja.md

@@ -34,7 +34,10 @@ global install は Codex の `UserPromptSubmit` / `PostToolUse` / `Stop` hook
 rollout capture と monitor state 書き込みだけを行い、**使用量閾値での
 `$throughline` 自動注入はしない**（token-monitor は表示専用）。bare
 `$throughline` は app-server 経由で新規 Codex thread を開始し、Throughline DB
-の handoff memory を developer item として注入する。current-thread rollback
+の handoff memory を developer item として注入する。このとき現在のCodex UI surfaceから
+Desktop／VS Code／CLIを選び、対応する`--open-host`を明示する。shellや永続PTYから継承した
+環境変数はsurface判定に使わない。`auto`はsurfaceが本当に不明な直接CLI利用時だけの互換経路。
+current-thread rollback
 診断が要る時だけ明示的に `trim --execute --host codex` を使う。既存の
 非 Throughline Codex hook は保持される。
 

package/README.md

@@ -569,7 +569,10 @@ reminds you to pipe the same memo when using them separately. Add `--execute`
 to create a new Codex app-server thread, inject the handoff memory as a
 developer item, and open it with `--open-host auto|desktop|vscode|cli|none`. `auto`
 opens the new task in Codex Desktop when invoked there, while preserving the
-existing VS Code and CLI routes. The
+existing VS Code and CLI routes. The result reports both the requested and
+resolved host. The installed `$throughline` skill passes the current Codex
+surface explicitly so a persistent shell or PTY cannot redirect the handoff.
+The
 individual commands remain available: validate the fresh-thread handoff with
 `throughline codex-handoff-smoke --session codex:<thread-id>`, optionally audit
 the model-smoke boundary with
@@ -776,6 +779,7 @@ aggregate は collection が既定OFFで、canonical dotagents config の
 | `throughline doctor --trim --host claude\|codex` | Diagnose trim host boundaries, manual procedure, and Codex host primitive blockage |
 | `throughline doctor --codex`                   | Diagnose Codex primary entry state, captured DB sessions, context-refresh memory contract, new-thread handoff readiness, safe continuation status, and host primitive audit |
 | `throughline factory-diagnostics --json`       | Versioned read-only native factory readiness JSON for database schema/migration, connector hooks, and representative capture/restore/handoff; does not emit bodies, secrets, absolute paths, or raw state |
+| `throughline migrate --json`                   | Migrate only an existing Throughline database to the current schema and emit a versioned bounded result; a missing database is not created, while future schemas and migration failures exit non-zero |
 | `throughline runtime-errors snapshot --json`   | Read the bounded product-owned runtime error aggregate. Collection occurs only when canonical dotagents config explicitly sets `collection.enabled: true`; this command performs no network I/O |
 | `throughline runtime-errors diagnostics --json` | Read bounded collection/store status without exposing the state path or raw errors |
 | `throughline runtime-errors ack <cursor> --json` | Explicitly acknowledge records through a monotonic cursor; unacknowledged records are never compacted |
@@ -787,7 +791,7 @@ aggregate は collection が既定OFFで、canonical dotagents config の
 | `throughline codex-summarize --session codex:<id>` | Summarize captured Codex L2 into L1 with the Codex CLI backend |
 | `throughline codex-resume --session codex:<id>` | Render Codex active-work context from a captured Codex session |
 | `throughline codex-resume --session codex:<id> --format handoff` | Render a concise fresh-thread handoff prompt without mutating the current thread |
-| `throughline codex-handoff-start --session codex:<id>` | Guided start plan for moving handoff memory into a new Codex thread; add `--execute` to create the thread through app-server, inject developer memory, and open it with `--open-host auto\|desktop\|vscode\|cli\|none`; `auto` keeps Codex Desktop handoffs in the Desktop app; use `--print-prompt` to include the prompt and `--memo-stdin` to carry a current-work memo |
+| `throughline codex-handoff-start --session codex:<id>` | Guided start plan for moving handoff memory into a new Codex thread; add `--execute` to create the thread through app-server, inject developer memory, and open it with `--open-host auto\|desktop\|vscode\|cli\|none`; output includes requested and resolved host, and the installed `$throughline` skill passes the current Codex surface explicitly; use `--print-prompt` to include the prompt and `--memo-stdin` to carry a current-work memo |
 | `throughline codex-handoff-smoke --session codex:<id>` | Read-only validation that the fresh-thread handoff prompt is pasteable before starting a new thread |
 | `throughline codex-handoff-model-smoke --session codex:<id>` | Experimental marker smoke for the handoff prompt. `--dry-run` checks readiness / command boundary without starting Codex exec; `--memo-stdin` carries a current-work memo; live `codex exec --ephemeral --sandbox read-only` requires explicit env opt-in |
 | `throughline codex-visibility-smoke --session codex:<id>` | Experimental Codex app-server marker smoke; injects memory and starts a model turn |

package/bin/throughline.mjs

@@ -13,6 +13,7 @@
  *   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
+ *   throughline migrate --json # Migrate the existing Throughline database only
  *   throughline runtime-errors snapshot --json # Product-owned runtime error aggregates
  *   throughline codex-capture # Capture active Codex rollout turns into Throughline DB
  *   throughline codex-hook user-prompt-submit # Codex current-session auto-refresh prompt hook
@@ -95,6 +96,11 @@ switch (cmd) {
     if (exitCode !== 0) process.exitCode = exitCode;
     break;
   }
+  case 'migrate': {
+    const exitCode = (await import('../src/cli/migrate.mjs')).run(rest);
+    if (exitCode !== 0) process.exitCode = exitCode;
+    break;
+  }
   case 'runtime-errors': {
     const exitCode = (await import('../src/cli/runtime-errors.mjs')).run(rest);
     if (exitCode !== 0) process.exitCode = exitCode;
@@ -207,6 +213,8 @@ Usage:
   throughline factory-diagnostics --json
                               Read-only native factory readiness JSON. Never emits
                               session/prompt bodies, secrets, absolute paths, or raw state
+  throughline migrate --json  Migrate the existing Throughline database only.
+                              Does not create a missing database and emits a versioned JSON result
   throughline runtime-errors snapshot --json
                               Read bounded local runtime error aggregates. Also supports
                               diagnostics, ack <cursor>, resolve <fingerprint>, and compact

package/codex/skills/throughline/SKILL.md

@@ -25,6 +25,17 @@ not ask for confirmation. Execute the handoff-start command directly. If it
 fails, report the error plainly instead of silently falling back to another
 memory source or current-thread rollback.
 
+Choose the open host from the current Codex application surface, not from
+environment variables inherited by the shell or a persistent PTY. Pass it
+explicitly whenever the surface is known:
+
+- Codex Desktop: `--open-host desktop`
+- Codex in VS Code: `--open-host vscode`
+- Codex CLI: `--open-host cli`
+
+Use `--open-host auto` only when the Codex surface is genuinely unknown. In
+that case, report both the requested and resolved hosts from the CLI result.
+
 ## Common Requests
 
 ### Bare "$throughline" / "use Throughline"
@@ -32,9 +43,13 @@ memory source or current-thread rollback.
 Run:
 
 ```bash
-throughline codex-handoff-start --execute
+throughline codex-handoff-start --execute --open-host desktop
 ```
 
+The example above is for Codex Desktop. Replace `desktop` with `vscode` or
+`cli` when that is the current Codex surface. Do not copy the host identity
+from the shell or PTY that happens to execute the command.
+
 This is the Codex new-thread continuation flow. It does not mutate the current
 Codex thread. Report the new thread id, open status, and any manual resume
 command if the host could not be opened automatically.
@@ -80,7 +95,7 @@ If the user wants to continue in a fresh Codex thread instead of mutating the
 current thread, use:
 
 ```bash
-throughline codex-handoff-start --session codex:<current-thread-id> --execute
+throughline codex-handoff-start --session codex:<current-thread-id> --execute --open-host <current-codex-surface>
 ```
 
 If the user gave a current-work memo, pipe it with `--memo-stdin`. This starts a
@@ -106,7 +121,7 @@ memory, unless they explicitly ask to mutate the current Codex thread.
 Execute:
 
 ```bash
-throughline codex-handoff-start --execute
+throughline codex-handoff-start --execute --open-host <current-codex-surface>
 ```
 
 Report only the essential outcome, especially the new thread id and open status.
@@ -120,7 +135,7 @@ throughline trim --dry-run --host codex
 Safe new-thread continuation:
 
 ```bash
-throughline codex-handoff-start --session codex:<current-thread-id> --execute --json
+throughline codex-handoff-start --session codex:<current-thread-id> --execute --open-host <current-codex-surface> --json
 ```
 
 Report the context reduction estimate from the dry-run when present:

package/docs/04_public_release_plan.md

@@ -140,6 +140,8 @@ schema v4 で PostToolUse (`capture-tool`) は廃止、L2/L3 は Stop 内で一
 | **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に確認した |
+| **npm 公開 (v0.8.4): Codex handoff host境界の明示化** | `$throughline` skillは現在のCodex UI surfaceからDesktop／VS Code／CLIを選び、`--open-host`を明示する。shell／永続PTYの継承環境はsurface判定に使わない。`codex-handoff-start`は互換の`openHost`を残し、requested / resolved hostをJSONとtextで報告する。古いVS Code由来PTY事故形と配布skillをfocused testで固定し、Claude-facing hook／`/tl`／baton／resume契約は変更しない。公開commit `5b840b6`、CI run `29721583754` 9/9 green、npm `latest` 0.8.4、shasum `1f2c39a22e45f3e02e8739ee5fd6ceefc6a71034`、tag / GitHub Release、registry由来global install、配置skill一致、`doctor --codex` exit 0を2026-07-20に確認した。判断証拠は [ADR 0017](adr/0017-codex-handoff-host-boundary.md) |
+| **release準備 (v0.8.5): 製品所有DB migration入口** | `throughline migrate --json` は既存DBだけをproduction migrationで現行schemaへ移行し、versioned bounded JSONを返す。DB不在は作らず`not_applicable`、現行は`already_current`、future schemaと失敗は非0。`factory-diagnostics`のread-only契約は維持する。設計判断は [ADR 0018](adr/0018-product-owned-database-migration.md) |
 | **未リリース: 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` 全緑を確認 |
 

package/docs/05_codex_first_roadmap.md

@@ -28,7 +28,7 @@
 - Claude-primary の現行 L2 -> L1 要約は `codex-sidecar` が configured の場合に sidecar を優先し、使えない場合は Claude Haiku 経路に戻る。Codex-primary は Codex CLI backend 失敗を明示 error にし、Claude Haiku / raw L2 へ fallback しない。
 - Codex guarded trim は、Codex app-server の `thread/read` / `thread/resume` / `thread/rollback` / `thread/inject_items` を使う。明示 thread identity と injectable memory がない場合は mutation 前に拒否する。rollout/app-server turn count mismatch は診断に残し、`thread/read` / `thread/resume` が同じ count を返す場合は app-server 側の差分で rollback `numTurns` を補正する。
 - Claude `/rewind` 自動化はまだ有効化しない。
-- 2026-05-10 update: Codex automatic current-thread refresh mutation は無効化する。live rollback / inject で token_count が一時的に落ちても同一 thread で戻る実測があるため、`UserPromptSubmit` / `PostToolUse` / `Stop` hooks は capture / monitor state write のみ行い、`codex_auto_refresh_disabled` で quiet にする。bare `$throughline` は `codex-handoff-start --execute` による app-server 新スレッド handoff とし、明示 `trim --execute --host codex` だけを診断用 current-thread rollback / inject path として残す。
+- 2026-05-10 update: Codex automatic current-thread refresh mutation は無効化する。live rollback / inject で token_count が一時的に落ちても同一 thread で戻る実測があるため、`UserPromptSubmit` / `PostToolUse` / `Stop` hooks は capture / monitor state write のみ行い、`codex_auto_refresh_disabled` で quiet にする。bare `$throughline` は `codex-handoff-start --execute --open-host <current-codex-surface>` による app-server 新スレッド handoff とし、明示 `trim --execute --host codex` だけを診断用 current-thread rollback / inject path として残す。current surfaceはCodex UI contextから決め、shell／永続PTYの継承環境へ委ねない。
 
 ## 新セッション引き継ぎ
 
@@ -271,7 +271,7 @@ Phase 3 implementation result (2026-05-06):
 - [x] `throughline codex-resume --format handoff` は current thread を mutate せず、新規 Codex thread に貼る短い handoff prompt を返す。handoff view は L2 件数 / 本文長 / detail refs を cap し、full active-work context は通常 text renderer に残す。
 - [x] `throughline codex-handoff-smoke --session codex:<thread_id>` は新規 thread handoff prompt を read-only に検査し、prompt size / required sections / mutation boundary / detail command dedupe を固定する。
 - [x] `throughline codex-handoff-model-smoke --session codex:<thread_id>` は明示 opt-in 時だけ `codex exec --ephemeral --ignore-user-config --ignore-rules --sandbox read-only` で handoff prompt の marker model smoke を行う。`--dry-run` は env なしで readiness / command boundary を監査し、`--print-prompt` で結合 prompt を出せる。`--memo-stdin` で Codex-primary current-work memo も同じ prompt に含める。structural handoff smoke が ready でなければ拒否し、current thread は mutate しない。
-- [x] `throughline codex-handoff-start --session codex:<thread_id>` は safe continuation の guided entrypoint として、structural smoke / model smoke dry-run / handoff render / optional live smoke / `--print-prompt` をまとめて表示する。`--execute` では app-server `thread/start` + `thread/inject_items` で新 thread に developer memory を注入し、`--open-host auto|desktop|vscode|cli|none` で表示を開く。`auto` は Codex Desktop 起点（`CODEX_INTERNAL_ORIGINATOR_OVERRIDE="Codex Desktop"` または `__CFBundleIdentifier=com.openai.codex`）を CLI より先に識別し、Desktop の `codex://threads/<thread-id>` deep link で新 thread を同アプリ内に開く。VS Code と CLI の既存経路は維持する。`--memo-stdin` 時は replay 用コマンドにも `--memo-stdin` を伝播し、same memo を pipe する注意を出す。
+- [x] `throughline codex-handoff-start --session codex:<thread_id>` は safe continuation の guided entrypoint として、structural smoke / model smoke dry-run / handoff render / optional live smoke / `--print-prompt` をまとめて表示する。`--execute` では app-server `thread/start` + `thread/inject_items` で新 thread に developer memory を注入し、`--open-host auto|desktop|vscode|cli|none` で表示を開く。CLIはrequested / resolved hostを両方報告する。`auto` は Codex Desktop 起点（`CODEX_INTERNAL_ORIGINATOR_OVERRIDE="Codex Desktop"` または `__CFBundleIdentifier=com.openai.codex`）を CLI より先に識別するが、bare `$throughline` skillは現在のCodex UI surfaceを明示指定し、永続PTYの継承環境へhost選択を委ねない。Desktop の `codex://threads/<thread-id>` deep linkとVS Code / CLI の既存経路は維持する。`--memo-stdin` 時は replay 用コマンドにも `--memo-stdin` を伝播し、same memo を pipe する注意を出す。
 - [x] `throughline codex-resume --format item-json` は Codex developer message item JSON を返す。
 - [x] `codex-resume` は explicit session を受け取れる。省略時は cwd の最新 `codex:%` session だけを対象にし、Claude session を混ぜない。
 - [x] `src/codex-handoff.test.mjs` / `src/codex-resume.test.mjs` で renderer と CLI shape を固定した。
@@ -440,7 +440,7 @@ Phase 5 implementation status (2026-05-06):
 - [x] `doctor --codex` は Claude settings を変更しない。Codex primary entrypoint の診断に限定する。
 - [x] 実セッションで `doctor --codex` -> `codex-capture` -> `codex-resume --format item-json` -> `doctor --codex` の local smoke を実施した。`codex-resume` は developer message item JSON を描画し、再診断で captured DB session が 1 件として表示された。
 - [x] 実セッションで `codex-visibility-smoke` を実施した。`THROUGHLINE_EXPERIMENTAL_CODEX_MODEL_VISIBLE_SMOKE=1` を必須にし、長い model turn に備えて `--request-timeout-ms 150000` / `--timeout-ms 180000` を使えるようにした。
-- [x] Codex primary の setup / install 手順は README に記録した。global install は Codex hooks と `$throughline` skill を自動登録する。2026-05-10 以降、bare `$throughline` は `throughline codex-handoff-start --execute` による app-server 新スレッド handoff とする。hooks は capture / monitor state write だけを行い、current-thread rollback / inject は明示 `trim --execute --host codex` を要求された時だけ使う。
+- [x] Codex primary の setup / install 手順は README に記録した。global install は Codex hooks と `$throughline` skill を自動登録する。2026-05-10 以降、bare `$throughline` は `throughline codex-handoff-start --execute --open-host <current-codex-surface>` による app-server 新スレッド handoffとし、current surfaceはCodex UI contextから明示する。hooks は capture / monitor state write だけを行い、current-thread rollback / inject は明示 `trim --execute --host codex` を要求された時だけ使う。
 - [x] `codex-summarize` を明示診断・運用 flow に追加した。Codex CLI backend を使い、Claude Haiku へ fallback しない。
 - [x] Codex primary の summarize / guarded execute まで含む end-to-end smoke を実施した。2026-05-07 correction では guarded execute を live app-server smoke としてのみ扱った。2026-05-08 unblock 後は、controlled rollback model-visible smoke の `not-reproduced` と current-thread live run の `execute-durable-verified` を合わせて、Codex current-thread trim 完了条件に含める。
   - `codex-capture`: `capturedTurns = 41`, `capturedRows = 75`, `capturedDetails = 2424`
@@ -460,7 +460,7 @@ Phase 5 implementation status (2026-05-06):
   - 追加確認: current VSCode-origin parent thread `019dfd38-c530-71c3-b7b8-180bdd3054bc` は hook shape 変更前に開始していたため、変更後の自然 Stop smoke としては不適格。assistant final 後に rollout は `task_complete` まで進んだが latest DB session は exec child のままだった。次に VSCode-origin を見る場合は、hook shape 変更後に新しく開始した Codex session で確認する。
   - 最終確認: hook shape 変更後に新しく開始した VSCode-origin Codex session で 1 turn 完了後、`throughline doctor --codex` を実行した。`current Codex thread` は `019dfd62-9a9d-7211-bf91-89d8e3fc908e`、`latest DB session` は `codex:019dfd62-9a9d-7211-bf91-89d8e3fc908e` で一致し、`Codex hooks feature: enabled`、`Codex Stop hook: registered`、command は `/usr/bin/node /home/kite/projects/Throughline/bin/throughline.mjs codex-hook stop`、`async: false`、`timeoutSec: 300` だった。VSCode-origin の自然 Stop hook による DB capture も解決済みとして扱う。
   - historical 2026-05-07 correction: 以下の Codex trim smoke は live app-server primitive の履歴として残す。ただし 2026-05-06 incident 後、restart / reconnect 越しの durable context trim 成功とは一時的に扱わず、`$throughline` / Codex Stop hook の automatic mutation を止めていた。
-  - 2026-05-10 UX 修正: bare `$throughline` は `doctor --codex` / `trim --dry-run --all` / `trim --preflight --all` を AI に順番実行させる説明 surface でも、`trim --execute --host codex --all` を直接実行する current-thread refresh でもなく、`throughline codex-handoff-start --execute` による app-server 新スレッド handoff とする。current-thread rollback / inject は明示要求時だけ使う。
+  - 2026-05-10 UX 修正: bare `$throughline` は `doctor --codex` / `trim --dry-run --all` / `trim --preflight --all` を AI に順番実行させる説明 surface でも、`trim --execute --host codex --all` を直接実行する current-thread refresh でもなく、`throughline codex-handoff-start --execute --open-host <current-codex-surface>` による app-server 新スレッド handoff とする。current surfaceはCodex UI contextから明示し、current-thread rollback / inject は明示要求時だけ使う。
   - memory contract 修正: Codex guarded trim でも注入 memory は元の `/tl` 思想を正とする。古い turn は L1 summaries、直近 20 turn は L2 full bodies、L3 は reference only で、L3 bodies / tool payloads は注入しない。rollout source は rollback candidate と app-server turn-count 補正の根拠であり、Throughline DB memory がある場合に rollout active work preview を注入 memory として使わない。DB memory が無い execute は rollout preview を注入せず、mutation 前に拒否する。
   - doctor visibility 修正: `doctor --codex` は旧 context refresh readiness として rollback source、inject memory source、memory contract、L1 summaries / recent L2 bodies / L3 references-only count、heuristic reduction estimate を表示していた。実 thread `019dfd62-9a9d-7211-bf91-89d8e3fc908e` では live readiness として `context refresh: ready`、`rollback source: codex-rollout`、`inject memory source: throughline-db`、`memory contract: older L1 + latest 20 L2 full bodies + L3 references only` を確認した。ただし incident 後は restart-safe readiness ではない。
   - 削減量の記録: `trim --dry-run --host codex` は rollout text がある場合に `contextReductionEstimate` を返す。2026-05-06 の現在 thread `019dfd62-9a9d-7211-bf91-89d8e3fc908e` では通常 keep-recent preview だと `capturedTurns = 14` / `keepRecent = 20` のため `rollbackTurns = 0`、推定削減量も 0 だった。旧 bare `$throughline` context refresh は `--all` を使っていたため、この keep-recent preview の 0 は「Codex で削減できない」という意味ではない。

package/docs/06_codex_trim_rollback_fix_plan.md

@@ -25,8 +25,9 @@ count を返す場合は、その差分で rollback `numTurns` を補正しま
 一時的に下がっても同一 thread で戻る挙動を確認したため、Codex automatic
 current-thread refresh は無効化します。`UserPromptSubmit` / `PostToolUse` / `Stop`
 hooks は capture / monitor state write のみ行い、`codex_auto_refresh_disabled` で
-quiet にします。bare `$throughline` は `codex-handoff-start --execute` による
-app-server 新スレッド handoff とします。
+quiet にします。bare `$throughline` は
+`codex-handoff-start --execute --open-host <current-codex-surface>` による
+app-server 新スレッド handoff とし、surfaceはCodex UI contextから明示します。
 
 最初のインシデント仮説に対する重要な訂正:
 

package/docs/09_rollback_context_trim_insight.md

@@ -25,7 +25,7 @@
 
 2026-05-09 skill UX: bare `$throughline` は diagnostics / dry-run / preflight を AI に順番実行させる surface ではなく、`throughline trim --execute --host codex --all` を直接走らせる scripted current-thread refresh としていた。目的は rollback と、Throughline DB の L2 最新 20 full bodies + older L1 summaries + L3 references-only memory injection のみだった。2026-05-10 以降は `--json` の full plan / memory preview が tool output として context を再膨張させるため、通常 path では付けないようにした。
 
-2026-05-10 rollback UX correction: 追加 live 実験で、current-thread rollback / inject 後に token_count が一時的に下がっても同一 thread で戻る挙動を確認した。これを受け、Codex automatic current-thread refresh は無効化し、`UserPromptSubmit` / `PostToolUse` / `Stop` hooks は capture / monitor state write のみ行う。bare `$throughline` は `throughline codex-handoff-start --execute` による app-server 新スレッド handoff とし、明示 `trim --execute --host codex` は診断用 current-thread path として残す。
+2026-05-10 rollback UX correction: 追加 live 実験で、current-thread rollback / inject 後に token_count が一時的に下がっても同一 thread で戻る挙動を確認した。これを受け、Codex automatic current-thread refresh は無効化し、`UserPromptSubmit` / `PostToolUse` / `Stop` hooks は capture / monitor state write のみ行う。bare `$throughline` は `throughline codex-handoff-start --execute --open-host <current-codex-surface>` による app-server 新スレッド handoffとし、surfaceはCodex UI contextから明示する。明示 `trim --execute --host codex` は診断用 current-thread path として残す。
 
 2026-05-07 host primitive audit: `throughline codex-host-primitive-audit` で installed Codex app-server schema を機械監査した。`thread/rollback` / `thread/inject_items` / `thread/compact/start` / `thread/start` / `thread/fork` / `thread/resume` は存在するが、rollback 済み user text を current-thread の model-visible input へ復活させない deletion / isolation / projection primitive は見つからなかった。`thread/resume(history)` は schema 上 `[UNSTABLE] FOR CODEX CLOUD - DO NOT USE` で、`thread_id` も ignored になるため、Throughline の current-thread repair primitive には採用しない。
 

package/docs/15_windows_ci_release_latency_plan.md

@@ -0,0 +1,82 @@
+# Windows CI・リリース待ち時間改修計画
+
+## 目的
+
+ThroughlineのWindows CIがLinux／macOSの約1分に対して16〜18分かかり、定型releaseを
+実用不能な長さへ押し上げている。Windows互換性matrixとowner-only ACL契約を維持したまま、
+unit testを5分以内（目標3分以内）へ短縮し、release前の同一candidateに対するCIを1回へ
+集約する。
+
+## 現状の実測
+
+GitHub Actions run `29722650046`（Windows Node 22.13.0）のTAP計測では、次の3テストだけで
+約26分相当の直列test時間を占めた。実jobはfile単位の重なりがあるため約18分で完了する。
+
+| テスト | `duration_ms` |
+|---|---:|
+| observer feed: Claude history floor, host/thread switch, cross-host tie, and opaque cursor | 568,093 ms |
+| completed turn receipt: bounded store drops only oldest receipts | 559,807 ms |
+| completed turn receipt: noisy project cannot evict another project anchor | 436,267 ms |
+
+3テストはいずれも256件境界を作るため公開APIを257回呼び、その各mutationでWindows
+PowerShellを複数回起動してdirectory／lock／temporary／final storeのACLを検証している。
+境界計算の反復とACL実機検証が結合されていることが主因で、runner一般の遅さではない。
+
+また現行workflowはmainへのpushごとに9 matrixを新規起動し、同じbranchの旧runをcancelしない。
+短時間の段階commitでWindows 18分runが重複する。
+
+## 決定
+
+1. completed-turn receiptの大量境界テストは、正規schemaの境界直前storeをfixtureとして用意し、
+   最後の1 mutationだけ公開APIで実行する。limit超過、history floor、project分離、cursor判定の
+   受入条件は変更しない。
+2. Windows owner-only ACLは専用integration testでdirectory、SQLite lock、final storeを
+   `windows-acl-test-helper`から外部検証する。大量境界テストからPowerShell反復を除いても、
+   production ACL契約の実機coverageを失わない。
+3. CIのunit test stepへ`timeout-minutes: 5`を設定する。5分超は性能劣化としてfail closedにする。
+4. workflowへbranch単位の`concurrency`を設定し、新しいcommitが来た時は同一workflow／refの
+   古いrunをcancelする。
+5. OS 3種 × Node `22.13.0`／`22.x`／`24.x`の9 matrixは維持する。互換範囲を速度対策のために
+   縮小しない。
+6. `0.8.5`の最終candidateへ実装・version・CHANGELOG・README・正本文書をまとめ、push後CIを
+   1回だけrelease gateとして使う。公開後のSHA／CI番号はGitHub Releaseを正本とし、証拠追記だけの
+   追加commit／追加CIを作らない。
+
+## 非目標
+
+- Windows ACLの適用・read-back検証、atomic rename、失敗時の旧store保持を弱めない。
+- Windows testをskipしない。matrixのOS／Node versionを減らさない。
+- completed-turn receiptの256件limit、history floor、cursor、project分離契約を変えない。
+- Claude hooks、Codex adapter、DB migration、handoff契約を変更しない。
+- release自動publishやcredential保管をworkflowへ追加しない。
+
+## 既知の罠
+
+- fixtureを直接書くだけでは公開APIの境界mutationを検証できない。必ずlimit直前から最後の1件を
+  `writeCompletedTurnReceipt`で追加する。
+- Windowsでfixtureを書き換える時も既存owner-only ACLを保持し、専用ACL testはproduction APIが
+  作った実pathを外部helperで検査する。
+- `concurrency.cancel-in-progress`は別branch／別PRをcancelしないref単位にする。
+- test timeoutはjob全体ではなくunit test stepに置き、setup-node等の外部遅延と製品test性能を混ぜない。
+- 進行中の旧CIを新しいcandidateの成功証拠として流用しない。
+
+## 受入条件
+
+- [ ] 3つの大量境界テストが公開契約を維持したままPowerShell反復を行わない。
+- [ ] Windows専用ACL testがdirectory／lock／storeのowner-only ACLを外部検証する。
+- [ ] focused testとfull `npm test`がgreen。
+- [ ] CI定義にunit test 5分上限とref単位concurrencyがある。
+- [ ] 最終GitHub Actionsで9/9 green、Windows各jobのunit testが5分以内（目標3分以内）。
+- [ ] `npm pack --dry-run --json`で公開物を確認する。
+- [ ] npm `throughline@0.8.5`、tag／GitHub Release、registry由来global install、
+  `throughline --version = 0.8.5`、配置skill／hooks／doctorを確認する。
+
+## 工程
+
+工程状態と完了証拠の正本はLattice storeとし、この文書は目的、判断、非目標、受入条件を所有する。
+
+1. ベースライン計測と原因同定
+2. 敵対的検証と設計裁定
+3. 安全網とfixture分離
+4. workflow・文書統合
+5. push後CI、npm公開、global install

package/docs/adr/0017-codex-handoff-host-boundary.md

@@ -0,0 +1,50 @@
+# ADR 0017: Codex handoff の open host は現在の UI surface から明示する
+
+- Status: accepted（2026-07-20実装・v0.8.4公開）
+- 関連: [Codex First Roadmap](../05_codex_first_roadmap.md)、
+  [Codex Trim Rollback修正計画](../06_codex_trim_rollback_fix_plan.md)
+
+## 問題
+
+Codex Desktopから `$throughline` を使っても、コマンド実行shellが以前のVS CodeやTerminalから
+継承した永続PTYである場合、`--open-host auto` は現在のUIではなく古い環境変数を見てしまう。
+新しいthread自体は正しく作られても、表示先だけがVS CodeやCLIへ逸れる事故になっていた。
+
+## 決定
+
+- `$throughline` skillは、AIが現在動いているCodex UI surfaceをDesktop／VS Code／CLIから選び、
+  `codex-handoff-start --execute --open-host <surface>` として明示する。
+- shell／永続PTYの継承環境は、skillのsurface判定根拠にしない。
+- `auto`は直接CLIからsurfaceが本当に不明な場合の互換経路として残す。
+- `codex-handoff-start`は既存consumer向けの`openHost`を維持し、requested hostとresolved hostを
+  JSON／textの両方へ追加して、host解決を観測可能にする。
+- Claude-facing hooks、`/tl`、baton、transcript、resume契約は変更しない。
+
+## 棄却した案
+
+1. **Desktop判定環境変数の優先順位だけを上げる**: 古いPTYに残った値を「現在のUI」と誤認する
+   根本問題が残るため棄却した。
+2. **`auto`を削除する**: 既存CLI consumerとの互換を不要に壊すため棄却した。
+3. **既存`openHost` fieldをrenameする**: machine-readable consumerを壊すため、追加fieldで拡張した。
+
+## 受入証拠
+
+- 公開commit: `5b840b69688713ba29f4d39f8520953bae846ea7`
+- GitHub Actions: run `29721583754`、Linux／macOS／Windows × Node 22.13.0／22.x／24.xの9/9成功
+- npm: `throughline@0.8.4`、`latest = 0.8.4`
+- npm shasum: `1f2c39a22e45f3e02e8739ee5fd6ceefc6a71034`
+- GitHub Release: `v0.8.4`
+- registry由来global install: `/opt/homebrew/lib/node_modules/throughline`はsymlinkでないcopy、
+  `throughline --version`は`0.8.4`
+- `throughline install`後の`~/.codex/skills/throughline/SKILL.md`はrepoと公開packageの双方に
+  byte-for-byte一致し、`doctor --codex`はexit 0
+
+`doctor --codex`はローカルの`.vscode/tasks.json`に古い絶対パスがあることも警告したが、
+診断上は「次のVS Code hook eventで修復」とされる既存ローカル状態であり、本releaseの
+host選択契約や公開packageの受入失敗ではない。
+
+## 帰結
+
+- Codex UIとcommand実行shellの由来が異なっても、handoffの表示先は現在のUIへ固定される。
+- requested／resolved hostの差を出力から追跡でき、将来のhost追加でもsilent fallbackを避けられる。
+- Claude primaryの既存surfaceとCodexのcurrent-thread診断pathは影響を受けない。

package/docs/adr/0018-product-owned-database-migration.md

@@ -0,0 +1,43 @@
+# ADR 0018: product-owned database migration
+
+- Status: Accepted
+- Date: 2026-07-20
+- Scope: dotagents `factory-master/fm-0645`
+
+## Context
+
+`agents-update` はregistry packageを更新した直後にfactory reporterを実行する。Throughlineの
+`factory-diagnostics` は意図的にread-onlyであり、旧schema DBを検出してもmigrationせず
+`not_ready`を返す。一方、現行のmigration入口は通常のwrite CLIがDBを開く副作用に埋もれている。
+このためschema更新後の初回updateは、利用者が別CLIを手で一度実行しない限り失敗する。
+
+## Decision
+
+1. Throughlineは `throughline migrate --json` を製品所有の正規入口として提供する。
+2. 対象は既存のdefault DBだけとする。DBが存在しない場合は作成せず`not_applicable`、現行schemaは
+   `already_current`、旧schemaは既存のproduction migrationを実行して`migrated`を返す。
+3. 対応版より新しいschema、migration失敗、migration後のversion不一致は非0で明示する。
+   silent fallback、DB削除、空DBへの置換は行わない。
+4. JSONはversioned schema、before/after/supported schema version、statusを持つ。秘密、DB内容、絶対pathは
+   出力しない。
+5. dotagentsの`agents-update`はThroughline package更新後、factory reporterより前にこの入口を自動実行する。
+   利用者に別の手動migrationを要求しない。migration失敗はupdate失敗として残し、factory gateで隠さない。
+6. v8 fixtureからv9への移行、現行schemaの冪等性、DB不在時の非作成、future schema拒否、strict CLI引数、
+   updaterの実行順と失敗伝播をfocused testで固定する。
+
+## Compatibility
+
+- Claude/Codex hooks、handoff、baton、recall、通常の`getDb()`自動migrationは変更しない。
+- `factory-diagnostics`はread-onlyのまま維持し、診断にmutationを混ぜない。
+- migration commandは任意pathや任意SQLを受け取らず、Throughline所有DBだけを扱う。
+
+## Rollback
+
+公開前は本commitをrevertする。公開後は旧packageへ戻せるが、DB schema downgradeは行わない。
+schema更新前のDBへ戻す必要がある場合は、hostごとに更新前backupを復元して対応版packageを使う。
+
+## Non-goals
+
+- Lattice本体・Lattice repoの変更
+- factory reporter側でのThroughline DB mutation
+- schema downgrade、DB repair、破損DBの自動再生成

package/package.json

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

package/src/cli/codex-handoff-start.mjs

@@ -190,6 +190,8 @@ function buildGuidance({ sessionId, parsed, handoffSmoke, handoffPrompt }) {
     ]),
   };
   const ready = handoffSmoke.status === 'ready';
+  const requestedOpenHost = parsed.openHost;
+  const resolvedOpenHost = resolveOpenHost(requestedOpenHost);
   return {
     status: ready ? 'ready' : 'not-ready',
     reason: ready ? 'fresh_thread_handoff_start_ready' : 'handoff_smoke_not_ready',
@@ -198,6 +200,8 @@ function buildGuidance({ sessionId, parsed, handoffSmoke, handoffPrompt }) {
     startThreadManually: !parsed.execute,
     execute: parsed.execute,
     openHost: parsed.openHost,
+    requestedOpenHost,
+    resolvedOpenHost,
     handoffSmoke,
     modelPromptChars: modelPrompt.length,
     estimatedModelPromptTokens: estimateTokens(modelPrompt),
@@ -234,7 +238,8 @@ function renderTextResult(result) {
   lines.push(`  session:           ${result.sessionId}`);
   lines.push(`  mutates thread:    ${result.mutatesCurrentThread ? 'yes' : 'no'}`);
   lines.push(`  execute:           ${result.execute ? 'yes' : 'no'}`);
-  lines.push(`  open host:         ${result.openHost}`);
+  lines.push(`  open requested:    ${result.requestedOpenHost ?? result.openHost}`);
+  lines.push(`  open resolved:     ${result.resolvedOpenHost ?? result.open?.host ?? result.openHost}`);
   lines.push(`  handoff smoke:     ${result.handoffSmoke.status}`);
   lines.push(`  prompt chars:      ${result.handoffSmoke.promptChars}/${result.handoffSmoke.maxPromptChars}`);
   lines.push(`  model prompt:      ${result.modelPromptChars}`);
@@ -304,6 +309,8 @@ function openStartedCodexThread({ threadId, host, cwd }) {
       status: 'skipped',
       reason: 'open_host_none',
       host: resolvedHost,
+      requestedHost: host,
+      resolvedHost,
       desktopUrl,
       vscodeUrl,
       resumeCommand,
@@ -323,6 +330,8 @@ function openStartedCodexThread({ threadId, host, cwd }) {
         status: 'failed',
         reason: `${resolvedHost}_deep_link_open_failed`,
         host: resolvedHost,
+        requestedHost: host,
+        resolvedHost,
         desktopUrl,
         vscodeUrl,
         resumeCommand,
@@ -333,6 +342,8 @@ function openStartedCodexThread({ threadId, host, cwd }) {
       status: 'opened',
       reason: `${resolvedHost}_deep_link_opened`,
       host: resolvedHost,
+      requestedHost: host,
+      resolvedHost,
       desktopUrl,
       vscodeUrl,
       resumeCommand,
@@ -355,6 +366,8 @@ end tell
           status: 'failed',
           reason: 'terminal_open_failed',
           host: resolvedHost,
+          requestedHost: host,
+          resolvedHost,
           desktopUrl,
           vscodeUrl,
           resumeCommand,
@@ -365,6 +378,8 @@ end tell
         status: 'opened',
         reason: 'terminal_resume_opened',
         host: resolvedHost,
+        requestedHost: host,
+        resolvedHost,
         desktopUrl,
         vscodeUrl,
         resumeCommand,
@@ -374,6 +389,8 @@ end tell
       status: 'manual',
       reason: 'cli_auto_open_unsupported_on_platform',
       host: resolvedHost,
+      requestedHost: host,
+      resolvedHost,
       desktopUrl,
       vscodeUrl,
       resumeCommand,
@@ -384,6 +401,8 @@ end tell
     status: 'failed',
     reason: 'unsupported_open_host',
     host: resolvedHost,
+    requestedHost: host,
+    resolvedHost,
     desktopUrl,
     vscodeUrl,
     resumeCommand,

package/src/cli/codex-handoff-start.test.mjs

@@ -27,6 +27,21 @@ test('codex-handoff-start auto-selects Codex Desktop before inherited VS Code si
   );
 });
 
+test('codex-handoff-start does not mistake a stale VS Code PTY for Desktop without a Desktop signal', () => {
+  assert.equal(
+    _internal.resolveOpenHost('auto', {
+      VSCODE_IPC_HOOK_CLI: '/tmp/stale-vscode.sock',
+    }),
+    'vscode',
+  );
+  assert.equal(
+    _internal.resolveOpenHost('desktop', {
+      VSCODE_IPC_HOOK_CLI: '/tmp/stale-vscode.sock',
+    }),
+    'desktop',
+  );
+});
+
 test('codex-handoff-start keeps VS Code and CLI auto-open behavior', () => {
   assert.equal(
     _internal.resolveOpenHost('auto', { CODEX_INTERNAL_ORIGINATOR_OVERRIDE: 'codex_vscode' }),
@@ -149,6 +164,9 @@ test('codex-handoff-start prints guided ready JSON for latest Codex session', as
     assert.equal(payload.sessionId, 'codex:thread-handoff-start');
     assert.equal(payload.mutatesCurrentThread, false);
     assert.equal(payload.startThreadManually, true);
+    assert.equal(payload.openHost, 'auto');
+    assert.equal(payload.requestedOpenHost, 'auto');
+    assert.ok(['desktop', 'vscode', 'cli'].includes(payload.resolvedOpenHost));
     assert.equal(payload.memoStdin, false);
     assert.equal(payload.memoReplayNote, null);
     assert.equal(payload.handoffSmoke.status, 'ready');
@@ -178,6 +196,8 @@ test('codex-handoff-start can print the exact fresh-thread prompt', async () =>
     assert.equal(result.status, 0, result.stderr);
     assert.match(result.stdout, /throughline codex handoff start/);
     assert.match(result.stdout, /status:\s+ready/);
+    assert.match(result.stdout, /open requested:\s+auto/);
+    assert.match(result.stdout, /open resolved:\s+(desktop|vscode|cli)/);
     assert.match(result.stdout, /commands:/);
     assert.match(result.stdout, /## Throughline: New Codex Thread Handoff/);
     assert.match(result.stdout, /latest handoff start body/);
@@ -284,12 +304,18 @@ test('codex-handoff-start execute creates a new app-server thread and can skip o
     assert.equal(payload.status, 'started');
     assert.equal(payload.reason, 'new_thread_handoff_started');
     assert.equal(payload.execute, true);
+    assert.equal(payload.openHost, 'none');
+    assert.equal(payload.requestedOpenHost, 'none');
+    assert.equal(payload.resolvedOpenHost, 'none');
     assert.equal(payload.startThreadManually, false);
     assert.equal(payload.newThread.threadId, '019e2000-0000-7000-8000-000000000001');
     assert.equal(payload.newThread.delivery, 'developer-item');
     assert.equal(payload.newThread.injectSent, true);
     assert.equal(payload.newThread.turnStatus, 'not-started');
     assert.equal(payload.open.status, 'skipped');
+    assert.equal(payload.open.host, 'none');
+    assert.equal(payload.open.requestedHost, 'none');
+    assert.equal(payload.open.resolvedHost, 'none');
     assert.equal(
       payload.open.desktopUrl,
       'codex://threads/019e2000-0000-7000-8000-000000000001',

package/src/cli/install.test.mjs

@@ -181,6 +181,10 @@ test('global install copies Throughline Codex skill to ~/.codex/skills/', async
     assert.match(skillBody, /name: throughline/);
     assert.match(skillBody, /Bare "\$throughline"/);
     assert.match(skillBody, /throughline codex-handoff-start --execute/);
+    assert.match(skillBody, /--open-host desktop/);
+    assert.match(skillBody, /--open-host vscode/);
+    assert.match(skillBody, /--open-host cli/);
+    assert.match(skillBody, /not from[\s\S]*persistent PTY/);
     assert.match(skillBody, /do not run doctor \/ dry-run \/ preflight first/);
     assert.match(metadataBody, /start a new Codex thread with Throughline handoff memory/);
     assert.doesNotMatch(metadataBody, /scripted current-thread rollback/);

package/src/cli/migrate.mjs

@@ -0,0 +1,44 @@
+import { CURRENT_VERSION, DatabaseMigrationError, migrateDefaultDb } from '../db.mjs';
+
+export const MIGRATION_SCHEMA = 'throughline.database_migration.v1';
+
+export function parseArgs(argv = []) {
+  if (argv.length !== 1 || argv[0] !== '--json') throw new TypeError('usage error');
+  return { json: true };
+}
+
+function result({ status, beforeSchemaVersion, afterSchemaVersion }) {
+  return {
+    schema: MIGRATION_SCHEMA,
+    status,
+    beforeSchemaVersion,
+    afterSchemaVersion,
+    supportedSchemaVersion: CURRENT_VERSION,
+  };
+}
+
+export function run(argv = [], { stdout = process.stdout, migrate = migrateDefaultDb } = {}) {
+  try {
+    parseArgs(argv);
+  } catch {
+    stdout.write(`${JSON.stringify(result({
+      status: 'invalid_request', beforeSchemaVersion: null, afterSchemaVersion: null,
+    }))}\n`);
+    return 2;
+  }
+
+  try {
+    stdout.write(`${JSON.stringify(result(migrate()))}\n`);
+    return 0;
+  } catch (error) {
+    const failure = error instanceof DatabaseMigrationError
+      ? error
+      : new DatabaseMigrationError('migration_failed', null, null);
+    stdout.write(`${JSON.stringify(result({
+      status: failure.code,
+      beforeSchemaVersion: failure.beforeSchemaVersion,
+      afterSchemaVersion: failure.afterSchemaVersion,
+    }))}\n`);
+    return 1;
+  }
+}

package/src/cli/migrate.test.mjs

@@ -0,0 +1,140 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DatabaseSync } from 'node:sqlite';
+
+import { CURRENT_VERSION } from '../db.mjs';
+import { MIGRATION_SCHEMA, parseArgs, run } from './migrate.mjs';
+
+const REPO_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+const BIN_PATH = join(REPO_ROOT, 'bin/throughline.mjs');
+
+function runCli(home, args = ['migrate', '--json']) {
+  return spawnSync(process.execPath, [BIN_PATH, ...args], {
+    cwd: REPO_ROOT,
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+    encoding: 'utf8',
+  });
+}
+
+function createV8Db(home) {
+  const dir = join(home, '.throughline');
+  mkdirSync(dir, { recursive: true });
+  const db = new DatabaseSync(join(dir, 'throughline.db'));
+  db.exec(`
+    PRAGMA user_version = 8;
+    CREATE TABLE sessions (session_id TEXT PRIMARY KEY, project_path TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'active', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, merged_into TEXT);
+    CREATE TABLE skeletons (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, turn_number INTEGER NOT NULL, role TEXT NOT NULL, summary TEXT NOT NULL, created_at INTEGER NOT NULL, origin_session_id TEXT);
+    CREATE TABLE bodies (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, origin_session_id TEXT NOT NULL, turn_number INTEGER NOT NULL, role TEXT NOT NULL, text TEXT NOT NULL, token_count INTEGER, created_at INTEGER NOT NULL, UNIQUE(session_id, origin_session_id, turn_number, role));
+    CREATE TABLE details (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, turn_number INTEGER, tool_name TEXT NOT NULL, input_text TEXT, output_text TEXT, token_count INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, origin_session_id TEXT, kind TEXT NOT NULL DEFAULT 'tool_input', source_id TEXT);
+    CREATE TABLE handoff_batons (project_path TEXT PRIMARY KEY, session_id TEXT NOT NULL, created_at INTEGER NOT NULL);
+    CREATE UNIQUE INDEX uq_skeletons_turn_v3 ON skeletons(session_id, origin_session_id, turn_number, role);
+    CREATE UNIQUE INDEX uq_details_source ON details(session_id, origin_session_id, source_id) WHERE source_id IS NOT NULL;
+  `);
+  db.close();
+}
+
+test('migrate CLI migrates a v8 fixture to the current schema', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-migrate-v8-'));
+  try {
+    createV8Db(home);
+    const result = runCli(home);
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      schema: MIGRATION_SCHEMA,
+      status: 'migrated',
+      beforeSchemaVersion: 8,
+      afterSchemaVersion: CURRENT_VERSION,
+      supportedSchemaVersion: CURRENT_VERSION,
+    });
+    const db = new DatabaseSync(join(home, '.throughline', 'throughline.db'), { readOnly: true });
+    assert.equal(db.prepare('PRAGMA user_version').get().user_version, CURRENT_VERSION);
+    assert.deepEqual(db.prepare('PRAGMA table_info(pending_handoffs)').all().map((row) => row.name), [
+      'session_id', 'project_path', 'source', 'auto_predecessor_id', 'created_at',
+    ]);
+    db.close();
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('migrate CLI is idempotent for the current schema', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-migrate-current-'));
+  try {
+    createV8Db(home);
+    assert.equal(runCli(home).status, 0);
+    const result = runCli(home);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(JSON.parse(result.stdout).status, 'already_current');
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('migrate CLI does not create a missing database', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-migrate-missing-'));
+  try {
+    const result = runCli(home);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(JSON.parse(result.stdout).status, 'not_applicable');
+    assert.equal(existsSync(join(home, '.throughline')), false);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('migrate CLI rejects a future schema without changing it', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-migrate-future-'));
+  try {
+    createV8Db(home);
+    const dbPath = join(home, '.throughline', 'throughline.db');
+    const db = new DatabaseSync(dbPath);
+    db.exec(`PRAGMA user_version = ${CURRENT_VERSION + 1}`);
+    db.close();
+    const result = runCli(home);
+    assert.equal(result.status, 1, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      schema: MIGRATION_SCHEMA,
+      status: 'future_schema',
+      beforeSchemaVersion: CURRENT_VERSION + 1,
+      afterSchemaVersion: CURRENT_VERSION + 1,
+      supportedSchemaVersion: CURRENT_VERSION,
+    });
+    const verify = new DatabaseSync(dbPath, { readOnly: true });
+    assert.equal(verify.prepare('PRAGMA user_version').get().user_version, CURRENT_VERSION + 1);
+    verify.close();
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('migrate CLI accepts only --json and does not reflect arguments', () => {
+  for (const argv of [[], ['--json', '--json'], ['--db', '/private/secret.db', '--json']]) {
+    const output = [];
+    assert.equal(run(argv, { stdout: { write(value) { output.push(value); } } }), 2);
+    assert.equal(JSON.parse(output[0]).status, 'invalid_request');
+    assert.doesNotMatch(output[0], /private|secret/);
+  }
+  assert.deepEqual(parseArgs(['--json']), { json: true });
+  assert.throws(() => parseArgs([]), /usage error/);
+});
+
+test('migrate CLI reports an internal migration failure without reflecting its cause', () => {
+  const output = [];
+  assert.equal(run(['--json'], {
+    stdout: { write(value) { output.push(value); } },
+    migrate() { throw new Error('/private/throughline.db contents'); },
+  }), 1);
+  assert.deepEqual(JSON.parse(output[0]), {
+    schema: MIGRATION_SCHEMA,
+    status: 'migration_failed',
+    beforeSchemaVersion: null,
+    afterSchemaVersion: null,
+    supportedSchemaVersion: CURRENT_VERSION,
+  });
+  assert.doesNotMatch(output[0], /private|contents/);
+});

package/src/db.mjs

@@ -3,7 +3,7 @@
  */
 
 import { DatabaseSync } from 'node:sqlite';
-import { mkdirSync } from 'fs';
+import { existsSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 
@@ -240,6 +240,74 @@ function initSchema(db) {
   }
 }
 
+/**
+ * 既存の Throughline DB だけを現在 schema へ移行する。
+ * 通常の getDb() と異なり、DB や親ディレクトリを作成しない。
+ *
+ * @returns {{ status: 'not_applicable' | 'already_current' | 'migrated', beforeSchemaVersion: number | null, afterSchemaVersion: number | null, supportedSchemaVersion: number }}
+ */
+export function migrateDefaultDb() {
+  if (!existsSync(DB_PATH)) {
+    return {
+      status: 'not_applicable',
+      beforeSchemaVersion: null,
+      afterSchemaVersion: null,
+      supportedSchemaVersion: CURRENT_VERSION,
+    };
+  }
+
+  let db;
+  try {
+    db = new DatabaseSync(DB_PATH);
+    db.exec(`PRAGMA busy_timeout = ${DB_BUSY_TIMEOUT_MS}`);
+    db.exec('PRAGMA foreign_keys = ON');
+
+    const beforeSchemaVersion = Number(db.prepare('PRAGMA user_version').get().user_version ?? 0);
+    if (beforeSchemaVersion > CURRENT_VERSION) {
+      throw new DatabaseMigrationError('future_schema', beforeSchemaVersion, beforeSchemaVersion);
+    }
+
+    if (beforeSchemaVersion === CURRENT_VERSION) {
+      return {
+        status: 'already_current',
+        beforeSchemaVersion,
+        afterSchemaVersion: beforeSchemaVersion,
+        supportedSchemaVersion: CURRENT_VERSION,
+      };
+    }
+
+    const journalMode = db.prepare('PRAGMA journal_mode').get().journal_mode;
+    if (String(journalMode).toLowerCase() !== 'wal') {
+      db.exec('PRAGMA journal_mode = WAL');
+    }
+    initSchema(db);
+    const afterSchemaVersion = Number(db.prepare('PRAGMA user_version').get().user_version ?? 0);
+    if (afterSchemaVersion !== CURRENT_VERSION) {
+      throw new DatabaseMigrationError('version_mismatch', beforeSchemaVersion, afterSchemaVersion);
+    }
+    return {
+      status: 'migrated',
+      beforeSchemaVersion,
+      afterSchemaVersion,
+      supportedSchemaVersion: CURRENT_VERSION,
+    };
+  } catch (error) {
+    if (error instanceof DatabaseMigrationError) throw error;
+    throw new DatabaseMigrationError('migration_failed', null, null);
+  } finally {
+    db?.close();
+  }
+}
+
+export class DatabaseMigrationError extends Error {
+  constructor(code, beforeSchemaVersion, afterSchemaVersion) {
+    super(code);
+    this.code = code;
+    this.beforeSchemaVersion = beforeSchemaVersion;
+    this.afterSchemaVersion = afterSchemaVersion;
+  }
+}
+
 /**
  * DB インスタンスを返す（シングルトン）
  * @returns {DatabaseSync}