throughline 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -10,6 +10,19 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.6.1] — 2026-07-13
+
+### Added
+
+- **Spotter auditor context v1.** `throughline auditor-context` adds an
+  opt-in, JSON-only, read-only projection for Spotter. It verifies the exact
+  session/project and the latest completed L2 user/assistant pair against an
+  origin/turn/SHA-256 freshness expectation, supplied explicitly or derived
+  from a Claude JSONL or Codex rollout. Only `fresh` returns bounded pair
+  bodies; all other states return no bodies. The command never creates,
+  migrates, or writes the Throughline DB. Opt-in and any onward transmission
+  remain Spotter responsibilities.
+
 ## [0.6.0] — 2026-07-12
 
 L2 capture is rebuilt from "save only the last pair each Stop" to a

package/README.md

@@ -109,7 +109,7 @@ Anthropic API usage from the transcript JSONL (no `length / 4` heuristics).
 
 ---
 
-## Three-layer memory model (schema v7)
+## Three-layer memory model (schema v8)
 
 ```mermaid
 flowchart LR
@@ -789,6 +789,35 @@ project history.
 
 ---
 
+## Spotter auditor context (read-only)
+
+`throughline auditor-context` is a **Spotter-only, opt-in read-only
+projection** for an auditor. It does not create, migrate, or write the
+Throughline database. The caller must name an exact `--session` and `--project`;
+the stored session must belong to that project root (or one of its descendants).
+
+It returns only completed L2 user/assistant pairs—never L1 summaries, L3 tool
+details, developer messages, or an in-flight Codex turn. Freshness is checked
+against the latest completed pair by origin session, turn number, and normalized
+SHA-256 hashes. Supply that expectation either explicitly, or derive it from a
+Claude JSONL / Codex rollout with `--host claude|codex --transcript`; the two
+sources are mutually exclusive. Returned context is bounded by `--recent-turns`
+(default 2), `--max-body-chars` (1,200), and `--max-total-chars` (4,000).
+
+The command is JSON-only. `fresh` is the only status that contains pair bodies;
+`empty`, `stale`, `session_mismatch`, `unavailable`, and `schema_mismatch`
+return no bodies and still exit successfully. Argument and internal errors are
+fixed JSON errors on stderr with a non-zero exit. Spotter owns the
+decision to opt in and any onward transmission of this local projection;
+Throughline only reads and projects it.
+
+```bash
+throughline auditor-context --session claude-session-id --project "$PWD" \
+  --host claude --transcript "$HOME/.claude/projects/.../session.jsonl" --json
+```
+
+---
+
 ## Requirements
 
 - **Node.js >= 22.5** (for the built-in `node:sqlite` module — no native build
@@ -812,7 +841,7 @@ plain `.mjs` files.
     └── <session_id>.json     Per-session activity state for the monitor
 ```
 
-Schema v7:
+Schema v8:
 
 - `sessions` — one row per `session_id`, with `project_path` and `merged_into`
 - `skeletons` — L1 one-liners, keyed by `(session_id, origin_session_id, turn, role)`
@@ -970,7 +999,7 @@ unchanged here.
 
 **Database got corrupted / want a clean slate**
 Delete `~/.throughline/throughline.db` (and the `-shm` / `-wal` companion files)
-and `~/.throughline/state/*.json`. A fresh database with schema v7 is created on
+and `~/.throughline/state/*.json`. A fresh database with schema v8 is created on
 the next hook fire.
 
 **New session didn't inherit memory from the previous one**

package/bin/throughline.mjs

@@ -10,6 +10,7 @@
  *   throughline session-start # SessionStart hook (Claude Code から呼ばれる)
  *   throughline detail <時刻> # L2+L3 詳細取得 (Claude が Bash 経由で呼ぶ想定)
  *   throughline handoff-preview # Codex-facing throughline_handoff JSON preview
+ *   throughline auditor-context --json # Read-only bounded auditor context JSON
  *   throughline codex-capture # Capture active Codex rollout turns into Throughline DB
  *   throughline codex-hook user-prompt-submit # Codex current-session auto-refresh prompt hook
  *   throughline codex-hook post-tool-use # Codex current-session auto-refresh tool-loop hook
@@ -65,6 +66,11 @@ switch (cmd) {
   case 'handoff-preview':
     await (await import('../src/cli/handoff-preview.mjs')).run(rest);
     break;
+  case 'auditor-context': {
+    const exitCode = (await import('../src/cli/auditor-context.mjs')).run(rest);
+    if (exitCode !== 0) process.exitCode = exitCode;
+    break;
+  }
   case 'codex-capture':
     await (await import('../src/cli/codex-capture.mjs')).run(rest);
     break;
@@ -149,6 +155,10 @@ Usage:
   throughline monitor           Multi-session token monitor (use --all, --session <id>)
   throughline detail <time>     Retrieve L2+L3 detail for a turn (e.g. 14:23:05 or 14:23-14:30)
   throughline handoff-preview   Print Codex-facing throughline_handoff JSON
+  throughline auditor-context --session <id> --project <root>
+                              Read only bounded completed user/assistant context
+                              for an auditor; requires either --host plus --transcript,
+                              or explicit pair identity/hashes; always requires --json
   throughline codex-capture     Capture active Codex rollout turns into DB
                               (requires --codex-thread-id or env thread id)
   throughline codex-hook user-prompt-submit

package/docs/12_desktop_clear_handoff_plan.md

@@ -50,7 +50,7 @@ docs 整合: ビルトインコマンドは UserPromptSubmit（prompt 送信時
 
 ### 3. 案A（startup 時間窓フォールバック）不採用の根拠
 
-- 幽霊セッション: 2026-07-11 だけで project_path=/Users/kite の startup が **182 件**（03:02〜12:56、最短間隔 0.001 秒、全て bodies=0）。haiku-workdir に 207 件＝headless `claude -p` も SessionStart hook を発火する。
+- 幽霊セッション: 2026-07-11 だけで user home直下のproject_pathのstartupが **182 件**（03:02〜12:56、最短間隔 0.001 秒、全て bodies=0）。haiku-workdir に 207 件＝headless `claude -p` も SessionStart hook を発火する。
 - 幽霊がチェーンに入ると MAX_CHAIN_DEPTH=10（[src/session-merger.mjs](../src/session-merger.mjs):14）へ数時間で到達し resolveMergeTarget throw → ターン捕捉が恒久停止＝ここで記憶が本当に失われる。
 - source='startup' は「/clear の後継」と「並行して開いた別窓」を原理的に区別できず、稼働中セッションのレコードを relabel して記憶を split する。「bodies>0 の前任だけ選ぶ」は前任側フィルタなので無効（refuter 検証済み）。
 
@@ -90,7 +90,7 @@ docs 整合: ビルトインコマンドは UserPromptSubmit（prompt 送信時
 - [x] 本プランを docs/12 として正本化（本文書）
 - [x] rag/01-hooks に SessionEnd reason enum を還流（[session-end-reasons.md](../rag/01-hooks/raw/session-end-reasons.md)）、rag/INDEX.md に Finding 8 追記
 - [x] 今日の調査を caveat に記録: public `claude-code-clear-userpromptsubmit-hook`（confirmed）/ private `claude-code-desktop-assistant-transcript-jsonl`（tentative・B-2 で更新）
-- [x] 実稼働デプロイ（2026-07-12）: `npm i -g /Users/kite/Developer/Throughline`（symlink 化＝リポ変更が即時反映。リリース時は registry 版へ戻す）
+- [x] 実稼働デプロイ（2026-07-12）: ローカルcheckoutをglobal install（symlink化＝リポ変更が即時反映。リリース時はregistry版へ戻す）
 
 ## Workstream B-1 — 捕捉のバックフィル化（先行。A の E2E 品質の前提。挙動修正レーン＝挙動差を明文化して個別承認）
 
@@ -117,7 +117,7 @@ docs 整合: ビルトインコマンドは UserPromptSubmit（prompt 送信時
   | Desktop セッション削除（675493fb） | 発火（12 秒後） | **`other`** | payload 構造は /clear と完全同一 |
   | VSCode `/clear`（fa43271f） | 即時 | **`clear`** | 42ms 後に後継 SessionStart(source=clear)→auto merge。仕組み自体は健全 |
 
-  副次発見: Desktop の幽霊セッション（/Users/kite）も SessionEnd(other) を高頻度で発火する。
+  副次発見: Desktop のuser home直下の幽霊セッションも SessionEnd(other) を高頻度で発火する。
 - [x] 判定: **NO-GO**。Desktop は /clear で SessionEnd を即時発火するが reason を `other` にラベルし、**セッション削除（明示的破棄）と区別不能**。reason=other でバトンを書くと削除セッションの記憶が次セッションに蘇る誤注入 + 幽霊バトン汚染。reason 不問の退行案は不採用（計画どおり）。→ A Phase 2 は実装せず停止、fallback 裁定へ
 - [x] spike 撤去: settings.json から SessionEnd 登録を削除（JSON 検証済み）、spike ファイル削除（git 履歴に残存）。実測ログ `~/.throughline/logs/session-end-spike.log` は証拠として保全
 

package/package.json

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

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`);
+  }
+}