throughline 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -10,6 +10,16 @@ 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
@@ -1144,7 +1154,8 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.4...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

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

@@ -779,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 |

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/docs/04_public_release_plan.md

@@ -140,7 +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に確認した |
-| **release candidate (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契約は変更しない。公開実績はpush後CI、npm、tag / GitHub Release、registry由来global installの確認後に追記する |
+| **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/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.4",
+  "version": "0.8.5",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [

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}