throughline 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -10,6 +10,18 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.4.4] — 2026-05-09
+
+### Changed
+
+- Token monitor now treats Claude transcript and Codex rollout files as live
+  inputs. State-file `usage` snapshots remain a fallback, but the display and
+  stale hiding no longer wait for Stop hook completion when the live files are
+  still changing.
+- `throughline install` now provisions or repairs the current project's VS Code
+  `Throughline Monitor` task when running under VS Code / Cursor / VSCodium, so
+  monitor auto-start setup no longer depends solely on the first hook event.
+
 ## [0.4.3] — 2026-05-09
 
 ### Changed

package/README.ja.md

@@ -213,6 +213,10 @@ throughline monitor --session <id-prefix>
 ▶ Throughline       2ed5039c  ████░░░░░░░░░░░░░░░░  205.1k /  21%  残 794.9k  claude-opus-4-6
 ```
 
+監視中は Claude transcript / Codex rollout をライブに読み、Stop hook の state
+snapshot はライブ usage が取れない場合の控えとして使います。これにより表示更新は
+Stop 完了待ちではなくなります。
+
 詳細仕様 (resize 追従、1M context 検出、ステイル隠し、Stop hook の非同期化など) は
 [英語版 README](README.md#multi-session-token-monitor) を参照してください。
 
@@ -222,7 +226,7 @@ throughline monitor --session <id-prefix>
 
 | コマンド | 役割 |
 | --- | --- |
-| `throughline install` | `~/.claude/settings.json` (ユーザー全体) に hook を登録 |
+| `throughline install` | hook / Codex skill を登録し、VS Code 配下なら現プロジェクトの monitor task も配置 |
 | `throughline install --project` | 現リポジトリの `.claude/settings.json` だけに hook を登録 |
 | `throughline uninstall` | hook を削除 |
 | `throughline monitor` | マルチセッション監視を起動 |

package/README.md

@@ -18,7 +18,7 @@
 
 ```bash
 npm install -g throughline
-throughline install     # registers Claude hooks, Codex Stop hook, and Codex skill
+throughline install     # registers hooks/skills and provisions the VS Code monitor task
 ```
 
 That's it. Open any Claude Code session and your turns flow into
@@ -517,9 +517,10 @@ Example output:
   (`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`).
   No `length / 4` approximation.
 - **Codex token counts use the rollout `token_count` event when present.** The
-  Codex Stop hook writes `codex:<thread_id>` monitor state and snapshots the
-  latest verified rollout `token_count` sample. If a Codex rollout has no
-  token-count event, Throughline can store an explicit estimate with
+  Codex Stop hook writes `codex:<thread_id>` monitor state with the rollout
+  path. While the monitor is running it reads the live rollout every tick and
+  prefers the latest verified `token_count` sample. If a Codex rollout has no
+  token-count event, Throughline can show an explicit estimate with
   `estimated: true` and the monitor marks it with `est`; it is not presented as
   exact usage.
 - **Codex auto-refresh mutates at the verified 90% threshold.** The Codex Stop
@@ -554,17 +555,17 @@ Example output:
   frame so the previous, wrongly-sized frame can't stack beneath it.
 - **Per-row "last updated" stamp.** Each session row carries an 8-cell
   `just now` / `24m ago` stamp right after the session id, placed before the
-  bar so narrow terminals don't truncate it. It resets to `just now` on every
-  Stop hook, so a growing stamp means the session is truly idle — not the
-  monitor stuck. When you need more detail,
+  bar so narrow terminals don't truncate it. It follows the newest state,
+  transcript, or Codex rollout mtime, so active sessions stay visible and the
+  stamp can move before the next Stop hook completes. 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.
+- **Live usage first, state snapshot as fallback.** When the Stop hook finishes
+  a turn it persists the latest `tokens / model / contextWindowSize` back into
+  the state file. The monitor now prefers live Claude transcript / Codex rollout
+  reads and uses the snapshot only when the live file cannot provide usage, so
+  the display no longer waits for Stop to update.
 - **Host-aware state.** Missing `host` means an older Claude state file.
   Codex states use `host: "codex"`, keep `transcriptPath: null`, and store the
   Codex rollout path separately as `rolloutPath` so the Claude transcript parser
@@ -581,15 +582,17 @@ Example output:
 
 ### 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 first session event.
-The file configures `runOn: folderOpen` so the monitor appears in a dedicated
-terminal panel the next time you open that folder.
+After `throughline install`, the current VS Code / Cursor / VSCodium project
+gets `.vscode/tasks.json` provisioned immediately when VS Code environment
+variables are present. Any other VS Code project you work in also gets the file
+on the first session event. The file configures `runOn: folderOpen` so the
+monitor appears in a dedicated terminal panel the next time you open that
+folder.
 
-**How it works.** `ensureMonitorTaskFile` is called from **all three hooks
-(SessionStart, UserPromptSubmit, Stop)** as of v0.3.18. Whichever one fires
-first in your environment creates the file; the rest are idempotent no-ops.
-Once per project it inspects `.vscode/tasks.json`:
+**How it works.** `ensureMonitorTaskFile` is called from `throughline install`
+and from **all three hooks (SessionStart, UserPromptSubmit, Stop)**. Whichever
+one fires first in your environment creates the file; the rest are idempotent
+no-ops. Once per project it inspects `.vscode/tasks.json`:
 
 - **No file yet** → creates one with a single `Throughline Monitor` task, and
   emits a one-time `<system-reminder>` to stdout so Claude tells you a
@@ -647,7 +650,7 @@ entry to the `tasks` array yourself:
 
 | Command                                        | What it does                                                 |
 | ---------------------------------------------- | ------------------------------------------------------------ |
-| `throughline install`                          | Register Claude user hooks/slash commands, the global Codex Stop hook, and the global `$throughline` Codex skill |
+| `throughline install`                          | Register Claude user hooks/slash commands, the global Codex Stop hook, the global `$throughline` Codex skill, and the current VS Code monitor task when applicable |
 | `throughline install --project`                | Register Claude hooks/slash commands in this repo only       |
 | `throughline uninstall`                        | Remove Throughline-managed Claude hooks/slash commands, only the Throughline-managed Codex hook, and the `$throughline` Codex skill |
 | `throughline monitor [--all] [--session <id>]` | Run the multi-session token monitor                          |

package/package.json

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

package/src/cli/install.mjs

@@ -15,6 +15,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFi
 import { join, dirname, resolve, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
+import { ensureMonitorTaskFile, shouldRecommendGitignore } from '../vscode-task.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const SLASH_COMMANDS_SRC = join(PACKAGE_ROOT, '.claude', 'commands');
@@ -400,6 +401,10 @@ export async function run(args = []) {
   const { installed: installedCommands, skipped } = installSlashCommands(commandsDir);
   const codex = args.includes('--project') ? null : installCodexHooks();
   const codexSkills = args.includes('--project') ? { installed: [], skipped: null } : installCodexSkills(codexSkillsDir);
+  const monitorTask = ensureMonitorTaskFile({
+    cwd: process.cwd(),
+    env: { ...process.env, THROUGHLINE_SUPPRESS_VSCODE_NOTICES: '1' },
+  });
 
   const scope = args.includes('--project') ? 'プロジェクトローカル' : 'グローバル（全プロジェクト）';
   console.log(`Throughline hooks をインストールしました [${scope}]`);
@@ -436,6 +441,15 @@ export async function run(args = []) {
     console.log('注意: パッケージ内に Codex skills のソースが見つからないためスキップしました。');
     console.log('');
   }
+  if (monitorTask.action === 'created' || monitorTask.action === 'merged' || monitorTask.action === 'repaired') {
+    console.log(`VSCode monitor task を${monitorTask.action === 'repaired' ? '修復' : '配置'}しました:`);
+    console.log(`  ${monitorTask.path}`);
+    console.log('  既に VSCode でこのフォルダを開いている場合は Developer: Reload Window を 1 回実行してください。');
+    if (shouldRecommendGitignore(process.cwd())) {
+      console.log('  共有リポジトリでは .vscode/tasks.json を .gitignore に追加することを推奨します。');
+    }
+    console.log('');
+  }
   console.log('  アンインストール: throughline uninstall');
 
   if (!resolveThroughlineOnPath()) {

package/src/cli/install.test.mjs

@@ -30,13 +30,16 @@ function silence() {
   const origLog = console.log;
   const origErr = console.error;
   const origStderrWrite = process.stderr.write.bind(process.stderr);
+  const origStdoutWrite = process.stdout.write.bind(process.stdout);
   console.log = () => {};
   console.error = () => {};
   process.stderr.write = () => true;
+  process.stdout.write = () => true;
   return () => {
     console.log = origLog;
     console.error = origErr;
     process.stderr.write = origStderrWrite;
+    process.stdout.write = origStdoutWrite;
   };
 }
 
@@ -144,6 +147,37 @@ test('global install copies Throughline Codex skill to ~/.codex/skills/', async
   }
 });
 
+test('global install provisions VSCode monitor task for the current project when running under VSCode', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const projectDir = mkdtempSync(join(tmpdir(), 'tl-install-monitor-'));
+  const origCwd = process.cwd();
+  const origVscodePid = process.env.VSCODE_PID;
+  process.chdir(projectDir);
+  process.env.VSCODE_PID = '12345';
+  const unsilence = silence();
+  try {
+    await run([]);
+    const tasksPath = join(projectDir, '.vscode', 'tasks.json');
+    assert.ok(existsSync(tasksPath), 'install should create current-project VSCode tasks.json');
+    const tasks = JSON.parse(readFileSync(tasksPath, 'utf8'));
+    const task = tasks.tasks.find((t) => t.label === 'Throughline Monitor');
+    assert.ok(task, 'Throughline Monitor task should be present');
+    assert.deepEqual(task.args.slice(1), ['monitor']);
+    assert.deepEqual(task.runOptions, { runOn: 'folderOpen' });
+  } finally {
+    unsilence();
+    if (origVscodePid === undefined) delete process.env.VSCODE_PID;
+    else process.env.VSCODE_PID = origVscodePid;
+    process.chdir(origCwd);
+    home.restore();
+    rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
 test('global install preserves existing Codex hooks and is idempotent', async () => {
   const home = makeTempHome();
   if (home.resolved !== home.dir) {

package/src/state-file.mjs

@@ -47,10 +47,9 @@ export function normalizeProjectPath(p) {
  *   host?: 'claude'|'codex',
  * }} data
  *
- * usage: monitor が表示する tokens/model/contextWindowSize をここに固定保存する。
- * Stop hook が readLatestUsage の結果を載せることで、monitor 側が毎フレーム JSONL を
- * 再スキャンする必要がなくなる。旧バージョン互換のため optional (無ければ monitor が
- * transcriptPath を読んでフォールバック)。
+ * usage: Stop hook 完了時点の tokens/model/contextWindowSize fallback snapshot。
+ * monitor はライブ transcript / rollout を優先して読み、ライブ usage が取れない場合だけ
+ * この snapshot を使う。旧バージョン互換のため optional。
  */
 export function writeSessionState({
   sessionId,

package/src/token-monitor.mjs

@@ -13,16 +13,18 @@
  *   - 状態ファイルはセッション単位 (~/.throughline/state/<session_id>.json)
  *   - setInterval (1s) + mtime 差分検知で更新を捕捉
  *   - updatedAt 降順ソート、先頭行を ▶ でハイライト
- *   - stale は PID 生存チェックで判定
+ *   - stale は state 更新時刻 + live transcript / rollout mtime で判定
  *   - Claude は transcript JSONL の最新 assistant usage を直読
- *   - Codex は Stop hook が state.usage に固定した rollout usage / estimate を表示
+ *   - Codex は rollout JSONL の token_count / active-text estimate を直読
+ *   - state.usage は live ファイルが読めない場合の最後の既知値としてだけ使う
  */
 
 import { basename, dirname, join } from 'node:path';
 import { stripVTControlCharacters } from 'node:util';
 import { statSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { getStateDir, readAllSessionStates, snapshotStateMtimes, normalizeProjectPath } from './state-file.mjs';
+import { getStateDir, readAllSessionStates, snapshotStateMtimes, normalizeProjectPath, STALE_HIDE_MS } from './state-file.mjs';
+import { buildCodexMonitorUsage } from './codex-usage.mjs';
 import { readLatestUsage } from './transcript-usage.mjs';
 import { startSizeQuery } from './terminal-size.mjs';
 
@@ -332,6 +334,44 @@ function formatLine({ state, usage, isActive, now = Date.now() }) {
   return `${marker} ${projectCol} ${hostCol} ${idCol} ${agoCol} ${barCol} ${tokCol}  ${modelCol}${warn}`;
 }
 
+function statFile(path) {
+  if (!path || !existsSync(path)) return null;
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+}
+
+function liveActivityMs(state) {
+  const transcript = statFile(state.transcriptPath);
+  const rollout = statFile(state.rolloutPath);
+  return Math.max(
+    Number(state.updatedAt) || 0,
+    transcript?.mtimeMs ?? 0,
+    rollout?.mtimeMs ?? 0,
+  );
+}
+
+function withLiveActivity(state, now = Date.now()) {
+  const updatedAt = liveActivityMs(state);
+  return {
+    ...state,
+    updatedAt,
+    stale: now - updatedAt > STALE_HIDE_MS,
+  };
+}
+
+function resolveMonitorUsage(state) {
+  if (state.host === 'codex' && state.rolloutPath) {
+    return buildCodexMonitorUsage(state.rolloutPath) ?? state.usage ?? null;
+  }
+  if (state.transcriptPath) {
+    return readLatestUsage(state.transcriptPath) ?? state.usage ?? null;
+  }
+  return state.usage ?? null;
+}
+
 // --- フィルタ ---
 /**
  * セッション一覧に表示フィルタを適用する。
@@ -356,12 +396,12 @@ let lastRenderedLines = 0;
 let lastRenderKey = '';
 
 /**
- * 再描画要否の判定キー。state ファイル群の mtime と transcript JSONL の size を
+ * 再描画要否の判定キー。state ファイル群の mtime と transcript / rollout JSONL の
+ * size + mtime を
  * 1 本の文字列にまとめてハッシュキーとする。キーが前回と同じなら描画スキップ。
  *
- * 注: transcript は JSONL append-only なので size 変化 = 新しい usage エントリ到来と
- * 同義。mtime だけでは transcript 更新を検出できない（state-file の mtime は
- * Stop hook のタイミングで更新され、transcript は Claude の stream 中に太る）。
+ * 注: state-file の mtime は Stop hook のタイミングで更新されるが、
+ * transcript / rollout は実行中に太る。その live file 変化も render key に含める。
  */
 function computeRenderKey() {
   const parts = [];
@@ -369,16 +409,18 @@ function computeRenderKey() {
   const mtimes = snapshotStateMtimes();
   const names = Array.from(mtimes.keys()).sort();
   for (const name of names) parts.push(`s:${name}:${mtimes.get(name)}`);
-  // transcript sizes（state ファイルを読まずに直接 stat、IO 最小化）
+  // live transcript / rollout sizes（state ファイルを読まずに直接 stat、IO 最小化）
   try {
     const states = readAllSessionStates();
     for (const st of states) {
-      if (!st.transcriptPath || !existsSync(st.transcriptPath)) continue;
-      try {
-        const size = statSync(st.transcriptPath).size;
-        parts.push(`t:${st.sessionId}:${size}`);
-      } catch {
-        // stat 失敗は無視（次フレームで回復）
+      for (const [kind, path] of [['t', st.transcriptPath], ['r', st.rolloutPath]]) {
+        if (!path || !existsSync(path)) continue;
+        try {
+          const stat = statSync(path);
+          parts.push(`${kind}:${st.sessionId}:${stat.size}:${stat.mtimeMs}`);
+        } catch {
+          // stat 失敗は無視（次フレームで回復）
+        }
       }
     }
   } catch {
@@ -405,7 +447,8 @@ function resetRenderKeyCache() {
 }
 
 function renderFrame(args) {
-  const states = readAllSessionStates();
+  const now = Date.now();
+  const states = readAllSessionStates().map((state) => withLiveActivity(state, now));
   const filtered = filterStates(states, args, process.cwd()).sort(
     (a, b) => b.updatedAt - a.updatedAt,
   );
@@ -428,15 +471,9 @@ function renderFrame(args) {
       `[Throughline] ${filtered.length} セッション${args.all ? ' (--all)' : ''}`,
     );
     lines.push(header);
-    const now = Date.now();
     for (let i = 0; i < filtered.length; i++) {
       const state = filtered[i];
-      // Stop hook が state.usage に固定値を入れていればそれを使う（JSONL 再スキャン不要）。
-      // 旧バージョンが書いた Claude state や usage スナップショットが取れなかったターンでは
-      // transcriptPath を直読。state 側の情報が 1 本化されると
-      // 「state が古い JSONL を指している」時の表示ブレが減る。
-      const usage = state.usage
-        ?? (state.transcriptPath ? readLatestUsage(state.transcriptPath) : null);
+      const usage = resolveMonitorUsage(state);
       lines.push(formatLine({ state, usage, isActive: i === 0, now }));
     }
   }
@@ -698,6 +735,9 @@ export const _internal = {
   shouldForceFullRedraw,
   resolveColumns,
   setMeasuredColumns,
+  liveActivityMs,
+  withLiveActivity,
+  resolveMonitorUsage,
 };
 
 // --- エントリポイント自動起動 ---

package/src/token-monitor.test.mjs

@@ -1,5 +1,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
 import { _internal } from './token-monitor.mjs';
 import { normalizeProjectPath } from './state-file.mjs';
@@ -17,6 +20,8 @@ const {
   shouldForceFullRedraw,
   resolveColumns,
   setMeasuredColumns,
+  withLiveActivity,
+  resolveMonitorUsage,
 } = _internal;
 
 // state-file は projectPath を resolve + lowercase 正規化する。
@@ -128,6 +133,117 @@ test('filterStates: cwd 不一致は除外（--session も --all もなし）',
   assert.equal(result[0].sessionId, 'a');
 });
 
+test('withLiveActivity: transcript mtime keeps a long-running session visible before Stop', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-monitor-live-activity-'));
+  try {
+    const transcript = join(dir, 'session.jsonl');
+    writeFileSync(transcript, '{"type":"user","message":{"content":"working"}}\n');
+    const now = Date.now();
+    const old = now - (20 * 60 * 1000);
+    const state = withLiveActivity({
+      sessionId: 'live-session',
+      host: 'claude',
+      projectPath: CWD_FOO,
+      transcriptPath: transcript,
+      rolloutPath: null,
+      updatedAt: old,
+      stale: true,
+    }, now);
+
+    assert.equal(state.stale, false);
+    assert.ok(state.updatedAt > old);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveMonitorUsage: live Claude transcript overrides stale Stop snapshot', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-monitor-live-usage-'));
+  try {
+    const transcript = join(dir, 'session.jsonl');
+    writeFileSync(transcript, [
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          model: 'claude-opus-4-6',
+          usage: {
+            input_tokens: 1234,
+            cache_creation_input_tokens: 200,
+            cache_read_input_tokens: 300,
+            output_tokens: 10,
+          },
+        },
+      }),
+      '',
+    ].join('\n'));
+
+    const usage = resolveMonitorUsage({
+      sessionId: 'claude-session',
+      host: 'claude',
+      projectPath: CWD_FOO,
+      transcriptPath: transcript,
+      rolloutPath: null,
+      updatedAt: Date.now(),
+      usage: {
+        tokens: 1,
+        model: 'old-snapshot',
+        contextWindowSize: 200_000,
+        outputTokens: 0,
+      },
+    });
+
+    assert.equal(usage.tokens, 1734);
+    assert.equal(usage.model, 'claude-opus-4-6');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveMonitorUsage: live Codex rollout overrides stale Stop snapshot', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-monitor-live-codex-'));
+  try {
+    const rollout = join(dir, 'rollout.jsonl');
+    writeFileSync(rollout, [
+      JSON.stringify({
+        type: 'turn_context',
+        payload: { model: 'gpt-5.5' },
+      }),
+      JSON.stringify({
+        type: 'event_msg',
+        payload: {
+          type: 'token_count',
+          info: {
+            last_token_usage: { input_tokens: 4567, output_tokens: 89 },
+            model_context_window: 258400,
+          },
+        },
+      }),
+      '',
+    ].join('\n'));
+
+    const usage = resolveMonitorUsage({
+      sessionId: 'codex:thread',
+      host: 'codex',
+      projectPath: CWD_FOO,
+      transcriptPath: null,
+      rolloutPath: rollout,
+      updatedAt: Date.now(),
+      usage: {
+        tokens: 1,
+        model: 'old-snapshot',
+        contextWindowSize: 200_000,
+        outputTokens: 0,
+      },
+    });
+
+    assert.equal(usage.tokens, 4567);
+    assert.equal(usage.model, 'gpt-5.5');
+    assert.equal(usage.estimated, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 // ─── cellWidth ─────────────────────────────────────────────────────
 
 test('cellWidth: ASCII は 1 セル', () => {

package/src/turn-processor.mjs

@@ -279,9 +279,8 @@ export async function run() {
     }
   }
 
-  // monitor が JSONL を毎フレーム再スキャンせずに済むよう、現在確定している usage を
-  // state ファイルに固定する。Stop 完了時点で assistant エントリは transcript に
-  // 書き出し済みなので readLatestUsage が最新値を返す。
+  // monitor の fallback 用に、Stop 完了時点で確定している usage を state ファイルにも
+  // 保存する。通常表示はライブ transcript を優先し、読めない時だけ snapshot を使う。
   // 取得失敗は致命ではないので try/catch で握る（stderr には出す）。
   try {
     const usage = transcript_path ? readLatestUsage(transcript_path) : null;