throughline 0.3.19 → 0.3.21

package/.claude/commands/sc-detail.md

@@ -0,0 +1,22 @@
+---
+description: Throughline の退避済みターン（L2 本文 + L3 ツール入出力）を時刻で復元する
+argument-hint: <HH:MM:SS> または <HH:MM:SS>-<HH:MM:SS>
+---
+
+以下の Bash コマンドを実行し、結果を全文そのまま表示してください（要約せず、一字一句）。
+
+```bash
+throughline detail "$ARGUMENTS"
+```
+
+## 使い方
+
+- `/sc-detail 14:23:05` — 指定時刻のターンを復元
+- `/sc-detail 14:23-14:30` — 時刻範囲のターンをまとめて復元
+
+## 何が返るか
+
+- **L2**: そのターンの会話本文（ユーザー発言 + Claude 返答）
+- **L3**: そのターンで実行されたツールの入出力
+
+これは Throughline のセッション記憶 `~/.throughline/throughline.db` から読み出されます。

package/.claude/commands/tl.md

@@ -0,0 +1,30 @@
+---
+description: 次の新規セッションに現セッションの記憶を引き継ぐためのバトンを置く (Throughline)
+---
+
+Throughline の UserPromptSubmit hook が `/tl` を検出し、バトン（現セッション ID）を保存しました。
+
+次に必ずやること（スキップ厳禁）:
+
+1. 今この時点の「中断地点の状態」を自分の文脈から思い出し、以下 4 項目を Markdown で整理する:
+   - **次の一手**: 今まさに何をやろうとしていたか（1-3 文、具体的に）
+   - **現在の方針 / 仮説**: 追っているバグの原因、設計の方向性、調査中の観点など
+   - **未解決の疑問**: 判断保留中の論点
+   - **進行中 TODO**: 完了済みを除いた現行 TODO（TodoWrite の最新状態や Plan の内容を踏まえて、意味のあるものだけ）
+
+2. Bash ツールで次のコマンドを実行し、stdin で上記 Markdown を流し込む:
+
+   ```bash
+   throughline save-inflight <<'EOF'
+   **次の一手**: ...
+   **現在の方針**: ...
+   **未解決の疑問**: ...
+   **進行中 TODO**:
+   - [ ] ...
+   - [ ] ...
+   EOF
+   ```
+
+Bash の出力 (`[throughline] in-flight memo saved (N chars) for next session`) がそのまま完了確認になります。追加のユーザーへの報告テキストは不要です。ツール呼び出し後は何も返さずターンを終えて構いません（必要なら一言だけ）。
+
+バトン（および in-flight メモ）は 1 時間で失効します。失効後に新セッションを開いた場合は引き継ぎは発火しません。

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.19",
+  "version": "0.3.21",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [
@@ -21,6 +21,7 @@
   "files": [
     "bin/",
     "src/",
+    ".claude/commands/",
     "README.md",
     "LICENSE"
   ],

package/src/cli/install.mjs

@@ -10,10 +10,15 @@
  * node のインストール先や OS が変わっても PATH さえ通れば動く。
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, unlinkSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const SLASH_COMMANDS_SRC = join(PACKAGE_ROOT, '.claude', 'commands');
+const SC_SLASH_COMMAND_FILES = ['tl.md', 'sc-detail.md'];
+
 // Throughline が管理する hook コマンド一覧
 // schema v4 以降: PostToolUse (capture-tool) は廃止。Stop 内で L2/L3 を一括処理する。
 const SC_COMMANDS = [
@@ -48,6 +53,42 @@ function resolveSettingsPath(args) {
   return join(homedir(), '.claude', 'settings.json');
 }
 
+function resolveCommandsDir(args) {
+  if (args.includes('--project')) {
+    return join(process.cwd(), '.claude', 'commands');
+  }
+  return join(homedir(), '.claude', 'commands');
+}
+
+function installSlashCommands(commandsDir) {
+  if (!existsSync(SLASH_COMMANDS_SRC)) {
+    return { installed: [], skipped: 'source-missing' };
+  }
+  if (!existsSync(commandsDir)) mkdirSync(commandsDir, { recursive: true });
+  const installed = [];
+  for (const name of SC_SLASH_COMMAND_FILES) {
+    const src = join(SLASH_COMMANDS_SRC, name);
+    if (!existsSync(src)) continue;
+    const dest = join(commandsDir, name);
+    copyFileSync(src, dest);
+    installed.push(name);
+  }
+  return { installed, skipped: null };
+}
+
+function uninstallSlashCommands(commandsDir) {
+  const removed = [];
+  if (!existsSync(commandsDir)) return removed;
+  for (const name of SC_SLASH_COMMAND_FILES) {
+    const dest = join(commandsDir, name);
+    if (existsSync(dest)) {
+      unlinkSync(dest);
+      removed.push(name);
+    }
+  }
+  return removed;
+}
+
 function readSettings(settingsPath) {
   if (!existsSync(settingsPath)) return {};
   return JSON.parse(readFileSync(settingsPath, 'utf8'));
@@ -62,6 +103,7 @@ function writeSettings(settingsPath, obj) {
 export async function run(args = []) {
   const uninstall = args.includes('--uninstall');
   const settingsPath = resolveSettingsPath(args);
+  const commandsDir = resolveCommandsDir(args);
   const current = readSettings(settingsPath);
   const existingHooks = current.hooks ?? {};
   const scSet = new Set(SC_COMMANDS);
@@ -81,8 +123,12 @@ export async function run(args = []) {
     }
 
     writeSettings(settingsPath, current);
+    const removedCommands = uninstallSlashCommands(commandsDir);
     console.log('Throughline hooks を削除しました。');
     console.log(`  ${settingsPath}`);
+    if (removedCommands.length > 0) {
+      console.log(`  slash commands 削除: ${removedCommands.join(', ')} (${commandsDir})`);
+    }
     return;
   }
 
@@ -100,6 +146,7 @@ export async function run(args = []) {
 
   current.hooks = existingHooks;
   writeSettings(settingsPath, current);
+  const { installed: installedCommands, skipped } = installSlashCommands(commandsDir);
 
   const scope = args.includes('--project') ? 'プロジェクトローカル' : 'グローバル（全プロジェクト）';
   console.log(`Throughline hooks をインストールしました [${scope}]`);
@@ -110,5 +157,13 @@ export async function run(args = []) {
   console.log('  Stop             → throughline process-turn   (L1 要約 + L2 本文保存 + L3 詳細保存)');
   console.log('  UserPromptSubmit → throughline prompt-submit  (/tl バトン書き込み)');
   console.log('');
+  if (installedCommands.length > 0) {
+    console.log(`slash commands を配置しました: ${installedCommands.map(n => '/' + n.replace(/\.md$/, '')).join(', ')}`);
+    console.log(`  ${commandsDir}`);
+    console.log('');
+  } else if (skipped === 'source-missing') {
+    console.log('注意: パッケージ内に slash commands のソースが見つからないためスキップしました。');
+    console.log('');
+  }
   console.log('  アンインストール: throughline uninstall');
 }

package/src/cli/install.test.mjs

@@ -0,0 +1,150 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { run } from './install.mjs';
+
+function makeTempHome() {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-install-test-'));
+  const origUserprofile = process.env.USERPROFILE;
+  const origHome = process.env.HOME;
+  process.env.USERPROFILE = dir;
+  process.env.HOME = dir;
+  const resolved = homedir();
+  return {
+    dir,
+    resolved,
+    restore() {
+      if (origUserprofile === undefined) delete process.env.USERPROFILE;
+      else process.env.USERPROFILE = origUserprofile;
+      if (origHome === undefined) delete process.env.HOME;
+      else process.env.HOME = origHome;
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+function silence() {
+  const origLog = console.log;
+  const origErr = console.error;
+  console.log = () => {};
+  console.error = () => {};
+  return () => {
+    console.log = origLog;
+    console.error = origErr;
+  };
+}
+
+test('global install copies /tl and /sc-detail to ~/.claude/commands/', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    const tl = join(home.dir, '.claude', 'commands', 'tl.md');
+    const sc = join(home.dir, '.claude', 'commands', 'sc-detail.md');
+    assert.ok(existsSync(tl), 'tl.md should be installed globally');
+    assert.ok(existsSync(sc), 'sc-detail.md should be installed globally');
+    const tlBody = readFileSync(tl, 'utf8');
+    assert.match(tlBody, /Throughline/, 'tl.md content should be real');
+    const settings = JSON.parse(readFileSync(join(home.dir, '.claude', 'settings.json'), 'utf8'));
+    assert.ok(settings.hooks?.UserPromptSubmit, 'UserPromptSubmit hook should be registered');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
+test('project install copies commands to cwd/.claude/commands/', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const projectDir = mkdtempSync(join(tmpdir(), 'tl-install-proj-'));
+  const origCwd = process.cwd();
+  process.chdir(projectDir);
+  const unsilence = silence();
+  try {
+    await run(['--project']);
+    const tl = join(projectDir, '.claude', 'commands', 'tl.md');
+    assert.ok(existsSync(tl), 'tl.md should be installed in project');
+    const globalTl = join(home.dir, '.claude', 'commands', 'tl.md');
+    assert.ok(!existsSync(globalTl), '--project should NOT touch global dir');
+  } finally {
+    unsilence();
+    process.chdir(origCwd);
+    home.restore();
+    rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
+test('uninstall removes slash command files', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    const tl = join(home.dir, '.claude', 'commands', 'tl.md');
+    assert.ok(existsSync(tl), 'install should have placed tl.md');
+    await run(['--uninstall']);
+    assert.ok(!existsSync(tl), 'uninstall should remove tl.md');
+    const sc = join(home.dir, '.claude', 'commands', 'sc-detail.md');
+    assert.ok(!existsSync(sc), 'uninstall should remove sc-detail.md');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
+test('uninstall preserves unrelated slash commands in the same dir', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    const otherCmd = join(home.dir, '.claude', 'commands', 'unrelated.md');
+    writeFileSync(otherCmd, '# unrelated slash command\n');
+    await run(['--uninstall']);
+    assert.ok(existsSync(otherCmd), 'uninstall must not touch unrelated files');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
+test('install is idempotent: second run keeps exactly one tl.md and one hook entry', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    await run([]);
+    await run([]);
+    const tl = join(home.dir, '.claude', 'commands', 'tl.md');
+    assert.ok(existsSync(tl));
+    const settings = JSON.parse(readFileSync(join(home.dir, '.claude', 'settings.json'), 'utf8'));
+    const stopGroups = settings.hooks.Stop;
+    const processTurnCount = stopGroups
+      .flatMap(g => g.hooks ?? [])
+      .filter(h => h.command === 'throughline process-turn')
+      .length;
+    assert.equal(processTurnCount, 1, 'double-install must not duplicate hook entries');
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});

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');
 });