throughline 0.5.0 → 0.6.1

package/rag/01-hooks/raw/session-end-reasons.md

@@ -0,0 +1,21 @@
+# Claude Code Hooks — SessionEnd reason enum (Extract)
+
+Source: <https://code.claude.com/docs/en/hooks> (fetched 2026-07-11)
+確度: 公式 docs verbatim（Matcher patterns テーブルより）。実機検証は Throughline docs/12 A Phase 1 spike で実施予定。
+
+## SessionEnd
+
+- SessionEnd イベントの matcher は「why the session ended」でフィルタする。
+- **reason enum**: `clear` / `resume` / `logout` / `prompt_input_exit` / `bypass_permissions_disabled` / `other`
+- `clear` = "Session cleared with /clear command"
+- **デフォルト timeout は 1.5 秒**で /clear にも適用される（hook が 1.5 秒を超えるとサイレント kill）→ 登録時は per-hook timeout を明示すること。
+
+## SessionStart source（同 fetch での再確認）
+
+- `source` enum: `"startup"`（新規）/ `"resume"` / `"clear"`（/clear 後）/ `"compact"`
+
+## Throughline 的含意（実測とセット）
+
+- VSCode（2.1.195〜2.1.207 実測）は /clear で `source:"clear"` を送る。Desktop（2.1.205 実測）は `source:"startup"` を送る＝クライアント実装差（docs/12 §2）。
+- ビルトイン /clear は UserPromptSubmit / UserPromptExpansion のどちらにも乗らない（UserPromptExpansion の対象は skill / custom command / mcp_prompt のみ）＝ /clear 検知は SessionEnd(reason='clear') が唯一の hook 経路候補。
+- Desktop が SessionEnd(reason='clear') を実際に発火するかは未検証（2026-07-11 時点）。

package/{docs/RAG → rag}/INDEX.md

@@ -7,17 +7,17 @@ This directory accumulates third-party specifications relevant to Throughline's
 ## Folder layout
 
 ```text
-docs/RAG/
+rag/
 ├── INDEX.md (this file — synthesized findings, paths forward)
-└── _raw/                       (verbatim spec extracts, kept close to source wording)
-    ├── 01-hooks/
-    │   └── hooks-reference-extract.md      ← Claude Code hooks reference
-    ├── 02-messages-api/
-    │   └── messages-api-extract.md         ← Anthropic Messages API spec
-    ├── 03-settings/
-    │   └── sessions-extract.md             ← /clear, /compact, /resume behavior
-    └── 04-skills/
-        └── initialUserMessage-investigation.md ← deep-dive on the killer field
+├── 01-hooks/
+│   ├── raw/hooks-reference-extract.md      ← Claude Code hooks reference
+│   └── raw/session-end-reasons.md          ← SessionEnd reason enum + timeout 1.5s (2026-07-11 fetch)
+├── 02-messages-api/
+│   └── raw/messages-api-extract.md         ← Anthropic Messages API spec
+├── 03-settings/
+│   └── raw/sessions-extract.md             ← /clear, /compact, /resume behavior
+└── 04-skills/
+    └── raw/initialUserMessage-investigation.md ← deep-dive on the killer field
 ```
 
 ---
@@ -33,7 +33,7 @@ docs/RAG/
 ### Finding 1: `additionalContext` is a system reminder, not a user message
 
 > "Claude Code wraps the string in a system reminder and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it **does not appear as a chat message** in the interface."
-> — [Hooks reference](_raw/01-hooks/hooks-reference-extract.md#what-additionalcontext-actually-does-critical)
+> — [Hooks reference](01-hooks/raw/hooks-reference-extract.md#what-additionalcontext-actually-does-critical)
 
 → システムリマインダ = ブリーフィング扱い。モデルが「他人事」と感じる構造的原因。
 
@@ -41,13 +41,13 @@ docs/RAG/
 
 > "any non-JSON text written to stdout is added as context"
 > "Claude Code wraps the string in a system reminder"
-> — [Hooks reference](_raw/01-hooks/hooks-reference-extract.md#stdout)
+> — [Hooks reference](01-hooks/raw/hooks-reference-extract.md#stdout)
 
 → 現行 Throughline v0.4.12 の stdout 注入はこの経路。`additionalContext` と同じカテゴリ = 同じ「他人事」問題。
 
 ### Finding 3: `initialUserMessage` exists in the schema, but is **HEADLESS-ONLY**
 
-Verified via [openclaude source](_raw/04-skills/initialUserMessage-investigation.md#the-critical-constraint-from-openclaude-source-comment):
+Verified via [openclaude source](04-skills/raw/initialUserMessage-investigation.md#the-critical-constraint-from-openclaude-source-comment):
 
 ```text
 // SessionStart hooks can emit initialUserMessage — the first user turn for
@@ -56,19 +56,19 @@ Verified via [openclaude source](_raw/04-skills/initialUserMessage-investigation
 
 → Interactive mode (`/clear` シナリオ) では発火しない。我々の問題には使えない。
 
-**2026-05-24 実機確認**: real Claude Code (v2.1.145) で `~/.throughline/initial-user-message-test.flag` を立てて SessionStart hook を JSON 出力モードに切り替え、`hookSpecificOutput.initialUserMessage` に 8 hex tracer 入りメッセージを乗せて `/clear` 後の cleared-me に「過去発話の tracer を message history だけ見て返して」と尋ねた。ラン (2) 13:33 tracer `9220a79c` (session `0979ad20-…`) → モデル応答 **「ない」**。openclaude のソースコメントが real CC でも妥当であることを実機で確認。詳細: [docs/THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md §6 Phase 0-6](../THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md#phase-0-6--hookspecificoutputinitialusermessage-経路-spike)
+**2026-05-24 実機確認**: real Claude Code (v2.1.145) で `~/.throughline/initial-user-message-test.flag` を立てて SessionStart hook を JSON 出力モードに切り替え、`hookSpecificOutput.initialUserMessage` に 8 hex tracer 入りメッセージを乗せて `/clear` 後の cleared-me に「過去発話の tracer を message history だけ見て返して」と尋ねた。ラン (2) 13:33 tracer `9220a79c` (session `0979ad20-…`) → モデル応答 **「ない」**。openclaude のソースコメントが real CC でも妥当であることを実機で確認。詳細: [docs/10_transcript_injection_plan.md §6 Phase 0-6](../docs/10_transcript_injection_plan.md#phase-0-6--hookspecificoutputinitialusermessage-経路-spike)
 
 ### Finding 4: Messages API treats all messages[] entries equally
 
 > "When creating a new Message, you specify the prior conversational turns with the messages parameter, and the model then generates the next Message in the conversation."
-> — [Messages API](_raw/02-messages-api/messages-api-extract.md#no-differentiation-between-real--synthetic-messages-key)
+> — [Messages API](02-messages-api/raw/messages-api-extract.md#no-differentiation-between-real--synthetic-messages-key)
 
 → もし messages[] に synthetic な過去 turn を入れられれば、モデルは「本物」と区別できない。問題は CC が messages[] を hook から制御させていないこと。
 
 ### Finding 5: `/clear` preserves the JSONL but resets in-memory state
 
 > "/clear: start fresh with an empty context. The previous conversation is saved and resumable"
-> — [Sessions](_raw/03-settings/sessions-extract.md#clear-behavior-key)
+> — [Sessions](03-settings/raw/sessions-extract.md#clear-behavior-key)
 
 → CC は in-memory state を一次ソースに messages[] を構築。JSONL を外から書き換えても in-memory には反映されない (= Phase 0 / Phase 0-5 で実測確認済み)。
 
@@ -82,6 +82,10 @@ Verified via [openclaude source](_raw/04-skills/initialUserMessage-investigation
 
 [anthropics/claude-code/plugins/plugin-dev/skills/hook-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md) は SessionStart hook の `hookSpecificOutput` の `additionalContext` も `initialUserMessage` も触れていない。Plugin 開発者向けの公式チュートリアルですら触れない = どちらも primary 経路として推奨されていない可能性。
 
+### Finding 8: SessionEnd has a `clear` reason; built-in `/clear` never reaches UserPromptSubmit (2026-07-11)
+
+SessionEnd reason enum: `clear|resume|logout|prompt_input_exit|bypass_permissions_disabled|other`、default timeout 1.5s（/clear にも適用）— [session-end-reasons.md](01-hooks/raw/session-end-reasons.md)。実測: ビルトイン /clear はどのクライアントでも UserPromptSubmit に届かない（同一セッション /tl 対照実験 ×2 + VSCode 2.1.207）。VSCode は `source:"clear"` を送るが Desktop 2.1.205 は `source:"startup"`（クライアント実装差・バージョン交絡棄却済み）。→ Desktop の /clear 検知は SessionEnd(reason='clear') が唯一の hook 経路候補（実機検証は [docs/12](../docs/12_desktop_clear_handoff_plan.md) A Phase 1）。
+
 ---
 
 ## Throughline 仮説の見直し

package/src/auditor-context.mjs

@@ -0,0 +1,330 @@
+import { createHash } from 'node:crypto';
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { buildBodyRowsFromActiveTurns } from './codex-capture.mjs';
+import { parseCodexRolloutFile } from './codex-rollout-memory.mjs';
+import { getLogicalTurnGroups } from './transcript-reader.mjs';
+
+export const AUDITOR_CONTEXT_SCHEMA = 'throughline.auditor_context.v1';
+export const AUDITOR_CONTEXT_DB_SCHEMA_VERSION = 8;
+export const DEFAULT_AUDITOR_RECENT_TURNS = 2;
+export const DEFAULT_AUDITOR_MAX_BODY_CHARS = 1200;
+export const DEFAULT_AUDITOR_MAX_TOTAL_CHARS = 4000;
+
+export function defaultAuditorContextDbPath() {
+  return join(homedir(), '.throughline', 'throughline.db');
+}
+
+export function normalizeAuditorBody(value) {
+  return String(value ?? '').normalize('NFC').replace(/\r\n?/g, '\n').trim();
+}
+
+export function hashAuditorBody(value) {
+  return createHash('sha256').update(normalizeAuditorBody(value), 'utf8').digest('hex');
+}
+
+export function deriveAuditorFreshnessExpectation({ host, transcriptPath, sessionId } = {}) {
+  assertNonEmptyString(transcriptPath, 'transcriptPath');
+  assertNonEmptyString(sessionId, 'sessionId');
+  if (host === 'claude') {
+    const latest = getLogicalTurnGroups(transcriptPath).at(-1);
+    if (!latest) return null;
+    return {
+      expectedOriginSessionId: sessionId,
+      expectedTurnNumber: latest.representative.index,
+      expectedUserSha256: hashAuditorBody(latest.user.content),
+      expectedAssistantSha256: hashAuditorBody(latest.representative.content),
+    };
+  }
+  if (host === 'codex') {
+    const parsed = parseCodexRolloutFile(transcriptPath, { includeInFlightTurn: false });
+    const rows = buildBodyRowsFromActiveTurns(parsed.activeTurns, { sessionId, now: 0 });
+    const latestTurnNumber = rows.reduce((max, row) => Math.max(max, row.turnNumber), 0);
+    if (latestTurnNumber < 1) return null;
+    const user = rows.find((row) => row.turnNumber === latestTurnNumber && row.role === 'user');
+    const assistant = rows.find((row) => row.turnNumber === latestTurnNumber && row.role === 'assistant');
+    if (!user || !assistant) return null;
+    return {
+      expectedOriginSessionId: sessionId,
+      // Codex active turns are rebuilt after rollback/in-flight filtering. Their ordinal can
+      // shift between Stop capture and the next UserPromptSubmit, so it is not a stable identity.
+      // Exact session/origin plus both normalized pair hashes remain mandatory below.
+      expectedTurnNumber: null,
+      expectedUserSha256: hashAuditorBody(user.text),
+      expectedAssistantSha256: hashAuditorBody(assistant.text),
+    };
+  }
+  throw new TypeError('host must be claude or codex');
+}
+
+export function readAuditorContext({
+  dbPath = defaultAuditorContextDbPath(),
+  sessionId,
+  projectRoot,
+  expectedOriginSessionId,
+  expectedTurnNumber,
+  expectedUserSha256,
+  expectedAssistantSha256,
+  recentTurns = DEFAULT_AUDITOR_RECENT_TURNS,
+  maxBodyChars = DEFAULT_AUDITOR_MAX_BODY_CHARS,
+  maxTotalChars = DEFAULT_AUDITOR_MAX_TOTAL_CHARS,
+} = {}) {
+  assertNonEmptyString(sessionId, 'sessionId');
+  assertNonEmptyString(projectRoot, 'projectRoot');
+  assertPositiveInteger(recentTurns, 'recentTurns');
+  assertPositiveInteger(maxBodyChars, 'maxBodyChars');
+  assertPositiveInteger(maxTotalChars, 'maxTotalChars');
+
+  if (!existsSync(dbPath)) {
+    return emptyResult('unavailable', 'db_not_found', { sessionId, projectRoot, recentTurns });
+  }
+
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+  } catch (cause) {
+    throw new AuditorContextError('E_AUDITOR_CONTEXT_DB_OPEN', 'auditor context DB could not be opened', { cause });
+  }
+
+  try {
+    const version = Number(db.prepare('PRAGMA user_version').get()?.user_version ?? 0);
+    if (version !== AUDITOR_CONTEXT_DB_SCHEMA_VERSION) {
+      return emptyResult('schema_mismatch', 'unsupported_db_schema', {
+        sessionId,
+        projectRoot,
+        recentTurns,
+        dbSchemaVersion: version,
+      });
+    }
+
+    const session = db.prepare(
+      `SELECT session_id, project_path
+       FROM sessions
+       WHERE session_id = ?`,
+    ).get(sessionId);
+    if (!session) {
+      return emptyResult('empty', 'session_not_found', { sessionId, projectRoot, recentTurns });
+    }
+    if (!isSameProjectOrDescendant(session.project_path, projectRoot)) {
+      return emptyResult('session_mismatch', 'project_mismatch', { sessionId, projectRoot, recentTurns });
+    }
+
+    const rows = db.prepare(
+      `SELECT id, origin_session_id, turn_number, role, text, created_at
+       FROM bodies
+       WHERE session_id = ? AND role IN ('user', 'assistant')
+       ORDER BY created_at ASC, id ASC`,
+    ).all(sessionId);
+    const completed = buildCompletedPairs(rows);
+    if (completed.length === 0) {
+      return emptyResult('empty', 'completed_pair_not_found', { sessionId, projectRoot, recentTurns });
+    }
+
+    const latest = completed.at(-1);
+    const stableTurnIdentityAvailable = Number.isInteger(expectedTurnNumber) && expectedTurnNumber >= 0;
+    const codexPairIdentity = sessionId.startsWith('codex:') && expectedOriginSessionId === sessionId;
+    const expectationComplete =
+      typeof expectedOriginSessionId === 'string' && expectedOriginSessionId.length > 0 &&
+      (stableTurnIdentityAvailable || codexPairIdentity) &&
+      isSha256(expectedUserSha256) && isSha256(expectedAssistantSha256);
+    if (!expectationComplete) {
+      return emptyResult('stale', 'freshness_expectation_incomplete', { sessionId, projectRoot, recentTurns });
+    }
+
+    const expectedUserHash = expectedUserSha256.toLowerCase();
+    const expectedAssistantHash = expectedAssistantSha256.toLowerCase();
+    const matchedIndex = stableTurnIdentityAvailable
+      ? completed.length - 1
+      : completed.findLastIndex((pair) =>
+          pair.originSessionId === expectedOriginSessionId &&
+          hashAuditorBody(pair.user) === expectedUserHash &&
+          hashAuditorBody(pair.assistant) === expectedAssistantHash);
+    const matched = matchedIndex >= 0 ? completed[matchedIndex] : latest;
+    const identityMatched = matchedIndex >= 0 && matched.originSessionId === expectedOriginSessionId &&
+      (!stableTurnIdentityAvailable || matched.turnNumber === expectedTurnNumber);
+    const userMatched = matchedIndex >= 0 && hashAuditorBody(matched.user) === expectedUserHash;
+    const assistantMatched = matchedIndex >= 0 && hashAuditorBody(matched.assistant) === expectedAssistantHash;
+    if (!identityMatched || !userMatched || !assistantMatched) {
+      return emptyResult('stale', 'latest_pair_mismatch', { sessionId, projectRoot, recentTurns });
+    }
+
+    const stableCompleted = completed.slice(0, matchedIndex + 1);
+    const bounded = boundCompletedPairs(stableCompleted.slice(-recentTurns), { maxBodyChars, maxTotalChars });
+    return {
+      schema: AUDITOR_CONTEXT_SCHEMA,
+      status: 'fresh',
+      reason: 'latest_pair_matched',
+      sessionId,
+      projectPath: canonicalProjectPath(projectRoot),
+      source: 'throughline-db-l2',
+      freshness: {
+        originSessionId: matched.originSessionId,
+        turnNumber: matched.turnNumber,
+        identityMatched: true,
+        userMatched: true,
+        assistantMatched: true,
+      },
+      turns: bounded.turns,
+      stats: {
+        requestedTurns: recentTurns,
+        returnedTurns: bounded.turns.length,
+        chars: bounded.chars,
+        truncated: bounded.truncated,
+      },
+    };
+  } catch (cause) {
+    if (cause instanceof AuditorContextError) throw cause;
+    throw new AuditorContextError('E_AUDITOR_CONTEXT_QUERY', 'auditor context query failed', { cause });
+  } finally {
+    db.close();
+  }
+}
+
+export class AuditorContextError extends Error {
+  constructor(code, message, { cause } = {}) {
+    super(message, { cause });
+    this.name = 'AuditorContextError';
+    this.code = code;
+  }
+}
+
+function buildCompletedPairs(rows) {
+  const grouped = new Map();
+  for (const row of rows) {
+    if (!row?.origin_session_id || !Number.isInteger(row.turn_number)) continue;
+    const key = `${row.origin_session_id}\u0000${row.turn_number}`;
+    const pair = grouped.get(key) ?? {
+      originSessionId: row.origin_session_id,
+      turnNumber: row.turn_number,
+      user: null,
+      assistant: null,
+      createdAt: Number(row.created_at) || 0,
+      lastId: Number(row.id) || 0,
+    };
+    if (row.role === 'user' && pair.user === null) pair.user = normalizeAuditorBody(row.text);
+    if (row.role === 'assistant' && pair.assistant === null) pair.assistant = normalizeAuditorBody(row.text);
+    pair.createdAt = Math.max(pair.createdAt, Number(row.created_at) || 0);
+    pair.lastId = Math.max(pair.lastId, Number(row.id) || 0);
+    grouped.set(key, pair);
+  }
+  return [...grouped.values()]
+    .filter((pair) => pair.user !== null && pair.assistant !== null)
+    .sort((a, b) => a.createdAt - b.createdAt || a.lastId - b.lastId)
+    .map(({ lastId: _lastId, ...pair }) => pair);
+}
+
+function boundCompletedPairs(pairs, { maxBodyChars, maxTotalChars }) {
+  const prepared = pairs.map((pair) => {
+    const user = tail(pair.user, maxBodyChars);
+    const assistant = tail(pair.assistant, maxBodyChars);
+    return {
+      ...pair,
+      user,
+      assistant,
+      truncated: user.length < pair.user.length || assistant.length < pair.assistant.length,
+    };
+  });
+
+  const selected = [];
+  let chars = 0;
+  let truncated = prepared.some((pair) => pair.truncated);
+  for (let i = prepared.length - 1; i >= 0; i--) {
+    const pair = prepared[i];
+    const remaining = maxTotalChars - chars;
+    if (remaining <= 0) {
+      truncated = true;
+      continue;
+    }
+    let user = pair.user;
+    let assistant = pair.assistant;
+    if (user.length + assistant.length > remaining) {
+      const assistantBudget = Math.min(assistant.length, Math.ceil(remaining / 2));
+      const userBudget = Math.max(0, remaining - assistantBudget);
+      user = tail(user, userBudget);
+      assistant = tail(assistant, assistantBudget);
+      truncated = true;
+    }
+    if (user.length === 0 || assistant.length === 0) {
+      truncated = true;
+      continue;
+    }
+    chars += user.length + assistant.length;
+    selected.unshift({
+      originSessionId: pair.originSessionId,
+      turnNumber: pair.turnNumber,
+      user,
+      assistant,
+      createdAt: pair.createdAt,
+    });
+  }
+  return { turns: selected, chars, truncated };
+}
+
+function emptyResult(status, reason, { sessionId, projectRoot, recentTurns, dbSchemaVersion } = {}) {
+  return {
+    schema: AUDITOR_CONTEXT_SCHEMA,
+    status,
+    reason,
+    sessionId,
+    projectPath: canonicalProjectPath(projectRoot),
+    source: 'throughline-db-l2',
+    freshness: {
+      identityMatched: false,
+      userMatched: false,
+      assistantMatched: false,
+    },
+    turns: [],
+    stats: {
+      requestedTurns: recentTurns,
+      returnedTurns: 0,
+      chars: 0,
+      truncated: false,
+      ...(Number.isInteger(dbSchemaVersion) ? { dbSchemaVersion } : {}),
+    },
+  };
+}
+
+function canonicalProjectPath(value) {
+  const raw = String(value ?? '');
+  if (/^[A-Za-z]:[\\/]/.test(raw)) {
+    return raw.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  }
+  let normalized = isAbsolute(raw) ? raw : resolve(raw);
+  try {
+    if (existsSync(normalized)) normalized = realpathSync.native(normalized);
+  } catch {
+    // Keep the lexical path when the filesystem cannot resolve it.
+  }
+  return normalized.split(sep).join('/').replace(/\/+$/, '');
+}
+
+function isSameProjectOrDescendant(candidate, root) {
+  const normalizedCandidate = canonicalProjectPath(candidate);
+  const normalizedRoot = canonicalProjectPath(root);
+  const left = /^[A-Za-z]:\//.test(normalizedCandidate) ? normalizedCandidate.toLowerCase() : normalizedCandidate;
+  const right = /^[A-Za-z]:\//.test(normalizedRoot) ? normalizedRoot.toLowerCase() : normalizedRoot;
+  return left === right || left.startsWith(`${right}/`);
+}
+
+function tail(value, maxChars) {
+  if (maxChars <= 0) return '';
+  return value.length <= maxChars ? value : value.slice(value.length - maxChars);
+}
+
+function isSha256(value) {
+  return typeof value === 'string' && /^[a-fA-F0-9]{64}$/.test(value);
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+}
+
+function assertPositiveInteger(value, name) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new TypeError(`${name} must be an integer >= 1`);
+  }
+}