throughline 0.3.18 → 0.3.20

package/README.md

@@ -205,24 +205,31 @@ Example output (real values from a running 1M-context Opus session):
 ### 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.
+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.
 
-**How it works.** The Stop hook runs at the end of every assistant response.
+**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`:
 
-- **No file yet** → creates one with a single `Throughline Monitor` task.
+- **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
+  **Developer: Reload Window** is needed to activate the `folderOpen` task once
+  (v0.3.19+).
 - **Plain JSON with other tasks** → appends the monitor task, preserves your
-  existing entries, `version`, and indentation.
+  existing entries, `version`, and indentation (same notice fires once).
 - **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).
+  this is the common path on every subsequent turn; notice is silent).
 
-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.
+The generated task uses `type: 'shell'` with the absolute path to Node and
+`bin/throughline.mjs`. VS Code wraps shell tasks in a PTY (xterm.js) so the
+monitor sees `isTTY=true`, real `columns`, and resize events. Windows `.cmd`
+shims and missing PATH entries cannot break it because the command is already
+an absolute Node binary path.
 
 **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

package/package.json

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

package/src/token-monitor.mjs

@@ -304,8 +304,8 @@ function formatLine({ state, usage, isActive, now = Date.now() }) {
   //   90%超: !! + 強い文言 (赤)
   //   70%超: !  + 弱い文言 (黄)
   const warn =
-    ratio >= 0.9 ? color(ANSI.red + ANSI.bold, '  !! /clear 強く推奨') :
-    ratio >= 0.7 ? color(ANSI.yellow, '  !  そろそろ /clear') :
+    ratio >= 0.9 ? color(ANSI.red + ANSI.bold, '  !! /tl 強く推奨') :
+    ratio >= 0.7 ? color(ANSI.yellow, '  !  そろそろ /tl') :
     '';
 
   const marker = isActive ? color(ANSI.bold + ANSI.cyan, '▶') : ' ';

package/src/token-monitor.test.mjs

@@ -305,13 +305,13 @@ test('formatLine: 70% 未満は警告テキストなし', () => {
   const out = stripColors(formatLine(makeLineArgs(0.5)));
   assert.ok(!out.includes('!!'));
   assert.ok(!out.includes('!  '));
-  assert.ok(!out.includes('/clear'));
+  assert.ok(!out.includes('/tl'));
 });
 
 test('formatLine: 70% 以上で "!" マーカーと弱めの文言', () => {
   const out = stripColors(formatLine(makeLineArgs(0.75)));
   assert.ok(out.includes('!'), 'should include ! marker');
-  assert.ok(out.includes('そろそろ /clear'), 'should show soft warning');
+  assert.ok(out.includes('そろそろ /tl'), 'should show soft warning');
   assert.ok(!out.includes('!!'), 'should not include critical marker yet');
 });
 

package/src/vscode-task.mjs

@@ -161,6 +161,37 @@ function atomicWrite(targetPath, contents) {
   renameSync(tmp, targetPath);
 }
 
+/**
+ * tasks.json を「今まさに作成/マージした」瞬間にユーザー向けへ送る通知テキスト。
+ *
+ * SessionStart / UserPromptSubmit の stdout は Claude Code に additional context として
+ * 取り込まれる。<system-reminder> で包んで Claude に「これをユーザーに伝える」ことを
+ * 明示しておくことで、新規プロジェクト初回セットアップ直後にユーザーへ
+ * 「Reload Window が必要」を即時通知できる。
+ *
+ * 通知するのは action が 'created' か 'merged' の場合のみ。既に存在した場合は
+ * セットアップ済みのため沈黙する（冪等性）。
+ */
+export function buildSetupNotice(action) {
+  if (action !== 'created' && action !== 'merged') return null;
+  return (
+    '<system-reminder>\n' +
+    'Throughline: このプロジェクトに token-monitor の自動起動設定を追加しました (.vscode/tasks.json)。\n' +
+    '今すぐ monitor を起動するには、VSCode のコマンドパレット (Ctrl+Shift+P) から\n' +
+    '  Developer: Reload Window\n' +
+    'を実行してください。次回以降はフォルダを開いた瞬間に自動起動します。\n' +
+    '\n' +
+    'このお知らせは今このプロジェクトで初回セットアップが完了したためだけに 1 度だけ流れています。\n' +
+    '必ずユーザー（あなたの対話相手）に日本語でそのまま伝えてください。\n' +
+    '</system-reminder>\n'
+  );
+}
+
+function emitSetupNotice(action) {
+  const text = buildSetupNotice(action);
+  if (text) process.stdout.write(text);
+}
+
 function emitJsoncGuidanceOnce(vscodeDir) {
   const markerPath = join(vscodeDir, JSONC_MARKER_FILENAME);
   if (existsSync(markerPath)) return;
@@ -215,6 +246,7 @@ export function ensureMonitorTaskFile(opts = {}) {
     if (!existsSync(vscodeDir)) mkdirSync(vscodeDir, { recursive: true });
     const obj = { version: '2.0.0', tasks: [buildMonitorTask(bin)] };
     atomicWrite(tasksPath, JSON.stringify(obj, null, 2) + '\n');
+    emitSetupNotice('created');
     return { action: 'created', path: tasksPath };
   }
 
@@ -243,5 +275,6 @@ export function ensureMonitorTaskFile(opts = {}) {
     tasks: [...(Array.isArray(obj.tasks) ? obj.tasks : []), buildMonitorTask(bin)],
   };
   atomicWrite(tasksPath, JSON.stringify(nextObj, null, indent) + '\n');
+  emitSetupNotice('merged');
   return { action: 'merged', path: tasksPath };
 }

package/src/vscode-task.test.mjs

@@ -10,6 +10,7 @@ import {
   detectIndent,
   hasMonitorTask,
   buildMonitorTask,
+  buildSetupNotice,
 } from './vscode-task.mjs';
 
 const VSCODE_ENV = { TERM_PROGRAM: 'vscode' };
@@ -518,3 +519,60 @@ test('ensureMonitorTaskFile: parse_error for malformed JSON', () => {
     cleanup();
   }
 });
+
+// --- buildSetupNotice ---
+
+test('buildSetupNotice: returns notice text for created', () => {
+  const text = buildSetupNotice('created');
+  assert.ok(text && text.includes('<system-reminder>'));
+  assert.ok(text.includes('Reload Window'));
+  assert.ok(text.includes('tasks.json'));
+  assert.ok(text.includes('ユーザー'));
+});
+
+test('buildSetupNotice: returns notice text for merged', () => {
+  const text = buildSetupNotice('merged');
+  assert.ok(text && text.includes('<system-reminder>'));
+  assert.ok(text.includes('Reload Window'));
+});
+
+test('buildSetupNotice: returns null for already_present (silent idempotency)', () => {
+  assert.equal(buildSetupNotice('already_present'), null);
+});
+
+test('buildSetupNotice: returns null for skipped', () => {
+  assert.equal(buildSetupNotice('skipped'), null);
+});
+
+test('buildSetupNotice: ensureMonitorTaskFile writes notice to stdout on first creation', () => {
+  const { dir, cleanup } = mkTmpCwd();
+  const captured = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = (chunk) => {
+    captured.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+    return true;
+  };
+  try {
+    const r1 = ensureMonitorTaskFile({
+      cwd: dir,
+      env: VSCODE_ENV,
+      throughlineBin: FAKE_BIN,
+    });
+    assert.equal(r1.action, 'created');
+    const r2 = ensureMonitorTaskFile({
+      cwd: dir,
+      env: VSCODE_ENV,
+      throughlineBin: FAKE_BIN,
+    });
+    assert.equal(r2.action, 'already_present');
+  } finally {
+    process.stdout.write = origWrite;
+    cleanup();
+  }
+  const joined = captured.join('');
+  assert.ok(joined.includes('<system-reminder>'), 'notice should be written on created');
+  assert.ok(joined.includes('Reload Window'));
+  // 2 回目 (already_present) では notice は出ない = created 分の 1 回のみ
+  const count = (joined.match(/<system-reminder>/g) ?? []).length;
+  assert.equal(count, 1, 'notice should be emitted exactly once (idempotency)');
+});