throughline 0.3.2 → 0.3.4

package/README.md

@@ -178,13 +178,70 @@ Example output (real values from a running 1M-context Opus session):
 - **Line-wrap safe.** Each line is truncated to `process.stdout.columns - 1`
   before drawing, preserving ANSI color codes. The redraw cursor math cannot
   desync on narrow terminals.
-
-### VS Code auto-start
-
-For contributors working on Throughline itself, a `.vscode/tasks.json` in this
-repo launches `throughline monitor` automatically in a dedicated terminal when
-you open the folder. Drop an equivalent config into your own project's
-`.vscode/tasks.json` to get the same behavior.
+- **Resize resilient.** Column width is polled every second, so pane drags that
+  don't fire a terminal `resize` event (common in VS Code's integrated
+  terminal) still trigger a full redraw.
+- **Per-row "last updated" stamp.** Each session row ends with `(24m ago)` so
+  you can tell a frozen display apart from an idle session at a glance. When
+  you need more detail, `throughline doctor --session <id-prefix>` compares the
+  state file against the actual transcript JSONL and flags drift, idle time,
+  and `/clear`-induced transcript path staleness.
+- **State-backed usage snapshot.** When the Stop hook finishes a turn it
+  persists the latest `tokens / model / contextWindowSize` back into the state
+  file. The monitor prefers this snapshot over re-reading the JSONL, which
+  removes a source of flicker when the transcript path in state drifts from
+  the one Claude Code is currently appending to.
+
+### VS Code auto-start (automatic)
+
+After `throughline install`, any VS Code / Cursor / VSCodium project you work in
+gets `.vscode/tasks.json` provisioned automatically on the next assistant turn.
+The file configures `runOn: folderOpen` so the monitor appears in a dedicated
+terminal panel the next time you open that folder.
+
+**How it works.** The Stop hook runs at the end of every assistant response.
+Once per project it inspects `.vscode/tasks.json`:
+
+- **No file yet** → creates one with a single `Throughline Monitor` task.
+- **Plain JSON with other tasks** → appends the monitor task, preserves your
+  existing entries, `version`, and indentation.
+- **JSONC (comments or trailing commas)** → does not touch the file. Prints a
+  one-time notice to stderr asking you to paste the snippet below.
+- **Already contains a Throughline Monitor task** → does nothing (idempotent;
+  this is the common path on every subsequent turn).
+
+The generated task uses `type: 'process'` with the absolute path to Node and
+`bin/throughline.mjs` so Windows `.cmd` shims and missing PATH entries cannot
+break it.
+
+**Opt out:** set `THROUGHLINE_NO_VSCODE=1` in the environment used by Claude
+Code. Delete `.vscode/tasks.json` (or just the monitor entry) if you want to
+stop auto-start for a project that already has one.
+
+**Manual snippet for JSONC tasks.json files.** If Throughline refused to edit
+your `tasks.json` because it contains comments or trailing commas, add this
+entry to the `tasks` array yourself:
+
+```jsonc
+{
+  "label": "Throughline Monitor",
+  "type": "shell",
+  "command": "throughline monitor",
+  "isBackground": true,
+  "presentation": {
+    "reveal": "always",
+    "panel": "dedicated",
+    "group": "throughline",
+    "close": false,
+    "echo": false,
+    "focus": false,
+    "showReuseMessage": false,
+    "clear": true
+  },
+  "runOptions": { "runOn": "folderOpen" },
+  "problemMatcher": []
+}
+```
 
 ---
 
@@ -199,6 +256,7 @@ you open the folder. Drop an equivalent config into your own project's
 | `throughline detail <time>`                    | Retrieve L2 body text and L3 tool I/O for a turn (see below) |
 | `throughline save-inflight`                    | Called by `/tl` to attach an in-flight memo (stdin) to the current baton |
 | `throughline doctor`                           | Check Node version, hook registration, DB writability, PATH  |
+| `throughline doctor --session <id-prefix>`     | Diagnose a specific session — detect state/transcript drift, idle vs. stuck |
 | `throughline status`                           | Print DB statistics (sessions, skeletons, bodies, details)   |
 | `throughline --version`                        | Print the installed version                                  |
 

package/bin/throughline.mjs

@@ -45,7 +45,7 @@ switch (cmd) {
     await (await import('../src/cli/save-inflight.mjs')).run();
     break;
   case 'doctor':
-    await (await import('../src/cli/doctor.mjs')).run();
+    await (await import('../src/cli/doctor.mjs')).run(rest);
     break;
   case 'status':
     await (await import('../src/cli/status.mjs')).run();

package/package.json

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

package/src/cli/doctor.mjs

@@ -1,21 +1,31 @@
 /**
- * throughline doctor — 環境チェック
+ * throughline doctor — 環境チェック + セッション診断
  *
- * チェック項目:
+ * 通常: throughline doctor
  *   - Node.js バージョン >= 22.5
  *   - node:sqlite が使えるか
  *   - ~/.throughline/throughline.db が書き込み可能か
  *   - ~/.claude/settings.json に Throughline hook が登録されているか
+ *
+ * セッション診断: throughline doctor --session <id-prefix>
+ *   - 特定セッションの state ファイルと transcript JSONL の整合性をチェック
+ *   - 「モニターが止まって見える」ときの真因切り分け用
+ *     (本当にアイドルか、state の transcriptPath が古い JSONL を指しているか)
  */
 
-import { existsSync, accessSync, readFileSync, constants } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, accessSync, readFileSync, constants, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
+import { getStateDir } from '../state-file.mjs';
+import { readLatestUsage } from '../transcript-usage.mjs';
 
 const GREEN = '\x1b[32m✓\x1b[0m';
 const RED = '\x1b[31m✗\x1b[0m';
 const YELLOW = '\x1b[33m!\x1b[0m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
 
 async function check(label, fn) {
   try {
@@ -32,7 +42,244 @@ async function check(label, fn) {
   }
 }
 
-export async function run() {
+function parseArgs(argv) {
+  const args = { session: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--session') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error('--session requires a session id prefix');
+      }
+      args.session = value;
+      i++;
+    }
+  }
+  return args;
+}
+
+function formatAgo(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return '?';
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day = Math.floor(hr / 24);
+  return `${day}d ago`;
+}
+
+function formatTs(ms) {
+  if (!Number.isFinite(ms)) return '?';
+  const d = new Date(ms);
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+function formatBytes(n) {
+  if (!Number.isFinite(n) || n < 0) return '?';
+  if (n >= 1_000_000_000) return (n / 1_000_000_000).toFixed(2) + ' GB';
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(2) + ' MB';
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + ' kB';
+  return `${n} B`;
+}
+
+/**
+ * transcript JSONL を末尾から走査して最後の assistant エントリの timestamp を返す。
+ * JSONL は append-only だが巨大化しうるので、末尾 256 KB だけ読んで逆順走査する。
+ * @param {string} transcriptPath
+ * @returns {{ ts: number | null, usage: object | null }}
+ */
+function tailLatestAssistantTs(transcriptPath) {
+  try {
+    const stat = statSync(transcriptPath);
+    // シンプル化: 現状の全ファイル read で十分（モニターも全 read している）。
+    // 巨大 JSONL 対策は readLatestUsage 側の将来最適化に任せる。
+    const raw = readFileSync(transcriptPath, 'utf8');
+    const lines = raw.split('\n');
+    let latestTs = null;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const trimmed = lines[i].trim();
+      if (!trimmed) continue;
+      let entry;
+      try {
+        entry = JSON.parse(trimmed);
+      } catch {
+        continue;
+      }
+      if (entry.type !== 'assistant') continue;
+      const ts = entry.timestamp ?? entry.ts ?? null;
+      if (ts) {
+        latestTs = typeof ts === 'string' ? Date.parse(ts) : ts;
+        break;
+      }
+    }
+    return { ts: latestTs, fileMtime: stat.mtimeMs, size: stat.size };
+  } catch (err) {
+    throw new Error(`transcript read failed: ${err.message}`);
+  }
+}
+
+/**
+ * 同じプロジェクトディレクトリ内の最新 JSONL を返す（transcript 差し替え検出用）。
+ * state の transcriptPath と比較して、指し先が「最新」でなければズレている可能性。
+ */
+function findLatestJsonlInSameDir(transcriptPath) {
+  try {
+    const dir = dirname(transcriptPath);
+    if (!existsSync(dir)) return null;
+    const files = readdirSync(dir).filter((n) => n.endsWith('.jsonl'));
+    if (files.length === 0) return null;
+    let best = null;
+    for (const name of files) {
+      const full = join(dir, name);
+      try {
+        const mt = statSync(full).mtimeMs;
+        if (!best || mt > best.mtimeMs) best = { path: full, mtimeMs: mt };
+      } catch {
+        /* skip */
+      }
+    }
+    return best;
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM'; // 他ユーザー所有プロセスは生きている扱い
+  }
+}
+
+function runSessionDiagnosis(prefix) {
+  const stateDir = getStateDir();
+  if (!existsSync(stateDir)) {
+    console.log(`${RED} state ディレクトリが存在しません: ${stateDir}`);
+    console.log(`${DIM}  → Throughline が一度も動作していない可能性。throughline install してから Claude Code を起動してください。${RESET}`);
+    return;
+  }
+  const entries = readdirSync(stateDir)
+    .filter((n) => n.endsWith('.json'))
+    .filter((n) => n.startsWith(prefix) || n.replace(/\.json$/, '').startsWith(prefix));
+  if (entries.length === 0) {
+    console.log(`${RED} prefix "${prefix}" に一致する state ファイルが見つかりません`);
+    console.log(`${DIM}  → ~/.throughline/state/ を ls して session_id を確認してください。${RESET}`);
+    return;
+  }
+  if (entries.length > 1) {
+    console.log(`${YELLOW} 複数のセッションが prefix に一致しました:`);
+    for (const name of entries) console.log(`  - ${name}`);
+    console.log(`${DIM}  → もう少し長い prefix を指定してください。${RESET}`);
+    return;
+  }
+
+  const name = entries[0];
+  const stateFile = join(stateDir, name);
+  const sessionId = name.replace(/\.json$/, '');
+  console.log(`${BOLD}[Session ${sessionId}]${RESET}\n`);
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(stateFile, 'utf8'));
+  } catch (err) {
+    console.log(`${RED} state ファイル読み込み失敗: ${err.message}`);
+    return;
+  }
+
+  const now = Date.now();
+  console.log(`  state file:       ${stateFile}`);
+  console.log(`    updatedAt:      ${formatTs(state.updatedAt)} (${formatAgo(now - (state.updatedAt ?? 0))})`);
+  console.log(`    projectPath:    ${state.projectPath ?? '(未設定)'}`);
+  console.log(`    transcriptPath: ${state.transcriptPath ?? '(未設定)'}`);
+  if (state.pid) {
+    const alive = isPidAlive(state.pid);
+    console.log(`    pid:            ${state.pid} (${alive ? 'alive' : 'dead'})`);
+  }
+  if (state.usage) {
+    const u = state.usage;
+    const pct = u.contextWindowSize ? Math.round((u.tokens / u.contextWindowSize) * 100) : 0;
+    console.log(`    usage (snapshot): ${u.tokens?.toLocaleString()} tokens (${pct}% of ${u.contextWindowSize?.toLocaleString()})`);
+    console.log(`                      model: ${u.model ?? '?'}`);
+  } else {
+    console.log(`    usage (snapshot): ${DIM}(未記録 — 旧バージョンで書かれた state、または Stop が 1 度も走っていない)${RESET}`);
+  }
+  console.log('');
+
+  if (!state.transcriptPath) {
+    console.log(`${YELLOW} transcriptPath が state に含まれていません — 診断不能`);
+    return;
+  }
+
+  if (!existsSync(state.transcriptPath)) {
+    console.log(`  transcript:       ${RED}存在しない${RESET}`);
+    console.log(`${DIM}  → state の transcriptPath が古い or /clear で消えた可能性。新しい発話で state が再生成されます。${RESET}`);
+    return;
+  }
+
+  let tail;
+  try {
+    tail = tailLatestAssistantTs(state.transcriptPath);
+  } catch (err) {
+    console.log(`  transcript:       ${RED}${err.message}${RESET}`);
+    return;
+  }
+  console.log(`  transcript:`);
+  console.log(`    size:           ${formatBytes(tail.size)}`);
+  console.log(`    mtime:          ${formatTs(tail.fileMtime)} (${formatAgo(now - tail.fileMtime)})`);
+  if (tail.ts) {
+    console.log(`    latest assistant entry: ${formatTs(tail.ts)} (${formatAgo(now - tail.ts)})`);
+  } else {
+    console.log(`    latest assistant entry: ${DIM}(未検出 — usage 付きの assistant エントリがまだ無い)${RESET}`);
+  }
+
+  const live = readLatestUsage(state.transcriptPath);
+  if (live) {
+    const pct = live.contextWindowSize ? Math.round((live.tokens / live.contextWindowSize) * 100) : 0;
+    console.log(`    usage (live):   ${live.tokens?.toLocaleString()} tokens (${pct}% of ${live.contextWindowSize?.toLocaleString()})`);
+  }
+  console.log('');
+
+  // diagnosis
+  console.log(`  diagnosis:`);
+  const latestInDir = findLatestJsonlInSameDir(state.transcriptPath);
+  if (latestInDir && latestInDir.path !== state.transcriptPath && latestInDir.mtimeMs > tail.fileMtime) {
+    console.log(`    ${RED}state points to old JSONL${RESET}`);
+    console.log(`      state:  ${state.transcriptPath} (${formatAgo(now - tail.fileMtime)})`);
+    console.log(`      newer:  ${latestInDir.path} (${formatAgo(now - latestInDir.mtimeMs)})`);
+    console.log(`${DIM}    → 次の発話で state が自動修復されます。それでも直らない場合は state ファイルを削除してください。${RESET}`);
+  } else {
+    console.log(`    ${GREEN}state and transcript are consistent${RESET}`);
+  }
+  const idleMs = now - tail.fileMtime;
+  if (idleMs > 10 * 60 * 1000) {
+    console.log(`    ${YELLOW}no transcript activity in ${formatAgo(idleMs)} — session likely idle${RESET}`);
+    console.log(`${DIM}    → Claude Code でこのセッションが動いていれば transcript は必ず太ります。太っていないなら本当にアイドル。${RESET}`);
+  }
+  if (state.usage && live && state.usage.tokens !== live.tokens) {
+    console.log(`    ${YELLOW}state.usage snapshot (${state.usage.tokens}) != live transcript (${live.tokens})${RESET}`);
+    console.log(`${DIM}    → Stop が一度走った後に更に assistant エントリが追記された状態。次の Stop で揃います。${RESET}`);
+  }
+}
+
+export async function run(argv = []) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`[throughline doctor] ${err.message}\n`);
+    process.exit(2);
+  }
+
+  if (args.session) {
+    runSessionDiagnosis(args.session);
+    return;
+  }
+
   console.log('throughline doctor\n');
 
   // Node.js バージョン
@@ -95,4 +342,15 @@ export async function run() {
   });
 
   console.log('');
+  console.log(`${DIM}ヒント: 特定セッションが止まって見えるときは ${RESET}throughline doctor --session <id-prefix>${DIM} で診断できます。${RESET}`);
 }
+
+// テスト用エクスポート
+export const _internal = {
+  parseArgs,
+  formatAgo,
+  formatBytes,
+  runSessionDiagnosis,
+  isPidAlive,
+  findLatestJsonlInSameDir,
+};

package/src/cli/doctor.test.mjs

@@ -0,0 +1,109 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _internal } from './doctor.mjs';
+
+const { parseArgs, formatAgo, formatBytes, findLatestJsonlInSameDir, isPidAlive } = _internal;
+
+// ─── parseArgs ──────────────────────────────────────────────────────
+
+test('parseArgs: 引数なしは session null', () => {
+  assert.deepEqual(parseArgs([]), { session: null });
+});
+
+test('parseArgs: --session <prefix>', () => {
+  assert.deepEqual(parseArgs(['--session', 'abc']), { session: 'abc' });
+});
+
+test('parseArgs: --session の値欠落は throw', () => {
+  assert.throws(() => parseArgs(['--session']), /session id prefix/);
+});
+
+test('parseArgs: --session の次が別フラグなら throw', () => {
+  assert.throws(() => parseArgs(['--session', '--other']), /session id prefix/);
+});
+
+// ─── formatAgo ──────────────────────────────────────────────────────
+
+test('formatAgo: 60 秒未満は秒表示', () => {
+  assert.equal(formatAgo(30_000), '30s ago');
+});
+
+test('formatAgo: 60 分未満は分表示', () => {
+  assert.equal(formatAgo(5 * 60_000), '5m ago');
+});
+
+test('formatAgo: 24 時間未満は時表示', () => {
+  assert.equal(formatAgo(3 * 60 * 60_000), '3h ago');
+});
+
+test('formatAgo: 24 時間以上は日表示', () => {
+  assert.equal(formatAgo(2 * 24 * 60 * 60_000), '2d ago');
+});
+
+test('formatAgo: 無効値', () => {
+  assert.equal(formatAgo(NaN), '?');
+  assert.equal(formatAgo(-1), '?');
+});
+
+// ─── formatBytes ────────────────────────────────────────────────────
+
+test('formatBytes: KB/MB/GB の切り替え', () => {
+  assert.equal(formatBytes(999), '999 B');
+  assert.equal(formatBytes(1_500), '1.5 kB');
+  assert.equal(formatBytes(1_500_000), '1.50 MB');
+  assert.equal(formatBytes(2_000_000_000), '2.00 GB');
+});
+
+test('formatBytes: 無効値', () => {
+  assert.equal(formatBytes(NaN), '?');
+  assert.equal(formatBytes(-1), '?');
+});
+
+// ─── findLatestJsonlInSameDir ──────────────────────────────────────
+
+test('findLatestJsonlInSameDir: 同じディレクトリ内の最新 JSONL を返す', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-doctor-'));
+  try {
+    const older = join(dir, 'a.jsonl');
+    const newer = join(dir, 'b.jsonl');
+    writeFileSync(older, 'x');
+    // mtime を強制的に差をつけるため書き込み間隔を開けたいが、連続 write だと同 ms 。
+    // ここでは newer の内容を後に書いて、後書きが newer の mtime を十分大きくする。
+    const now = Date.now();
+    writeFileSync(newer, 'y');
+    // older の mtime を古く設定
+    utimesSync(older, new Date(now - 10000), new Date(now - 10000));
+    utimesSync(newer, new Date(now), new Date(now));
+    const result = findLatestJsonlInSameDir(older);
+    assert.ok(result);
+    assert.equal(result.path, newer);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('findLatestJsonlInSameDir: 存在しないパスは null', () => {
+  assert.equal(findLatestJsonlInSameDir('/does/not/exist/x.jsonl'), null);
+});
+
+// ─── isPidAlive ─────────────────────────────────────────────────────
+
+test('isPidAlive: 自身の PID は alive', () => {
+  assert.equal(isPidAlive(process.pid), true);
+});
+
+test('isPidAlive: 不正な値は false', () => {
+  assert.equal(isPidAlive(0), false);
+  assert.equal(isPidAlive(-1), false);
+  assert.equal(isPidAlive(null), false);
+  assert.equal(isPidAlive(undefined), false);
+});
+
+test('isPidAlive: 存在しない PID は false', () => {
+  // 巨大な PID はほぼ確実に未使用
+  assert.equal(isPidAlive(2_147_483_646), false);
+});

package/src/state-file.mjs

@@ -37,9 +37,14 @@ export function normalizeProjectPath(p) {
 
 /**
  * セッション状態ファイルを書く
- * @param {{sessionId: string, projectPath: string, transcriptPath: string, pid: number}} data
+ * @param {{sessionId: string, projectPath: string, transcriptPath: string, pid: number, usage?: object|null}} data
+ *
+ * usage: monitor が表示する tokens/model/contextWindowSize をここに固定保存する。
+ * Stop hook が readLatestUsage の結果を載せることで、monitor 側が毎フレーム JSONL を
+ * 再スキャンする必要がなくなる。旧バージョン互換のため optional (無ければ monitor が
+ * transcriptPath を読んでフォールバック)。
  */
-export function writeSessionState({ sessionId, projectPath, transcriptPath, pid }) {
+export function writeSessionState({ sessionId, projectPath, transcriptPath, pid, usage }) {
   if (!sessionId) throw new Error('writeSessionState: sessionId is required');
   if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
   const file = join(STATE_DIR, `${sessionId}.json`);
@@ -50,6 +55,7 @@ export function writeSessionState({ sessionId, projectPath, transcriptPath, pid
     pid: pid ?? process.pid,
     updatedAt: Date.now(),
   };
+  if (usage) payload.usage = usage;
   writeFileSync(file, JSON.stringify(payload));
 }
 

package/src/state-file.test.mjs

@@ -133,3 +133,52 @@ test('snapshotStateMtimes: ディレクトリ未作成なら空 Map', async () =
     assert.equal(snap.size, 0);
   });
 });
+
+test('writeSessionState: usage 付きで書くと JSON に含まれる', async () => {
+  await withIsolatedStateDir(async ({ stateDir, mod }) => {
+    mod.writeSessionState({
+      sessionId: 'sess-a',
+      projectPath: '/tmp/x',
+      transcriptPath: null,
+      pid: 1,
+      usage: { tokens: 123, model: 'claude-opus-4-6', contextWindowSize: 200000, outputTokens: 10 },
+    });
+    const results = mod.readAllSessionStates();
+    assert.equal(results.length, 1);
+    assert.ok(results[0].usage);
+    assert.equal(results[0].usage.tokens, 123);
+    assert.equal(results[0].usage.model, 'claude-opus-4-6');
+  });
+});
+
+test('writeSessionState: usage 無しで書いたらフィールド自体が無い (旧フォーマット互換)', async () => {
+  await withIsolatedStateDir(async ({ stateDir, mod }) => {
+    mod.writeSessionState({
+      sessionId: 'sess-b',
+      projectPath: '/tmp/x',
+      transcriptPath: null,
+      pid: 1,
+    });
+    const results = mod.readAllSessionStates();
+    assert.equal(results.length, 1);
+    assert.equal(results[0].usage, undefined);
+  });
+});
+
+test('readAllSessionStates: 旧バージョンが書いた usage 無しの state を読める', async () => {
+  await withIsolatedStateDir(async ({ stateDir, mod }) => {
+    // 旧フォーマット (usage フィールド無し) を直接書く
+    const file = join(stateDir, 'old-fmt.json');
+    writeFileSync(file, JSON.stringify({
+      sessionId: 'old-fmt',
+      projectPath: '/tmp/foo',
+      transcriptPath: null,
+      pid: 1,
+      updatedAt: Date.now(),
+    }));
+    const results = mod.readAllSessionStates();
+    assert.equal(results.length, 1);
+    assert.equal(results[0].usage, undefined);
+    // usage 無しで読めること自体が互換性の証明
+  });
+});