throughline 0.8.9 → 0.9.0

package/CHANGELOG.md

@@ -10,6 +10,16 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-08-04
+
+### Added
+
+- `throughline handoff-context --session <id> --json` returns the exact
+  budgeted SessionStart inheritance context through a versioned local CLI
+  boundary. It opens only an existing database read-only and never creates or
+  migrates it, consumes a baton, merges sessions, changes `sessions.merged_into`,
+  or reassigns L1/L2/L3 memory rows.
+
 ## [0.8.9] — 2026-08-02
 
 ### Fixed

package/README.ja.md

@@ -1,5 +1,7 @@
 <p align="center">
-  <img src=".github/og.png" alt="Throughline — Claude Code のコンテキスト消費を約 90% 削減しつつ記憶はほぼ残す" width="100%">
+  <img src=".github/og.png" alt="Throughline — 環境や境界が変わっても方向と記憶を保って進むクジラの群れ" width="100%">
+  <br>
+  <sub><em>この画像は、環境や境界が変わっても、関係・方向・記憶を失わずに進み続ける連続性を表しています。</em></sub>
 </p>
 
 # Throughline
@@ -332,6 +334,7 @@ Throughline state をまだ書いていない現在セッションも表示で
 | `throughline doctor` | Node バージョン、hook 登録状況、DB、PATH をチェック |
 | `throughline doctor --trim --host claude` | trim boundary と手動手順を診断 |
 | `throughline handoff-preview --session <id>` | Codex 向け `throughline_handoff` JSON projection を表示 |
+| `throughline handoff-context --session <id> --json` | SessionStart と同じ引き継ぎ文脈を versioned JSON で取得。記憶行の `session_id` と `sessions.merged_into` は変更せず、同一端末内の別ベンダーランチャーから使える |
 | `throughline codex-sidecar-diagnostics` | この project の `codex-sidecar` diagnostics status を確認 |
 | `throughline codex-sidecar-dry-run` | App Server を呼ばずに read-only sidecar request を正規化表示 |
 | `throughline trim --dry-run --host codex` | Codex same-thread trim の dry-run preview |

package/README.md

@@ -1,5 +1,7 @@
 <p align="center">
-  <img src=".github/og.png" alt="Throughline — cut ~90% of Claude Code's context usage while keeping nearly all the memory" width="100%">
+  <img src=".github/og.png" alt="Throughline — a whale family carrying direction and memory across changing boundaries" width="100%">
+  <br>
+  <sub><em>This image represents continuity that preserves relationships, direction, and memory even as environments and boundaries change.</em></sub>
 </p>
 
 # Throughline
@@ -797,6 +799,7 @@ aggregate は collection が既定OFFで、canonical dotagents config の
 | `throughline runtime-errors reopen <fingerprint> --json` | Explicitly reopen a resolved aggregate without fabricating a new occurrence |
 | `throughline runtime-errors compact --json`    | Remove only acknowledged, resolved aggregates after retention; open or unacknowledged records remain |
 | `throughline handoff-preview --session <id>`   | Print a Codex-facing `throughline_handoff` JSON projection    |
+| `throughline handoff-context --session <id> --json` | Print the exact SessionStart inheritance context as versioned JSON without moving memory rows or changing `sessions.merged_into`; intended for local launchers that need portable cross-vendor context |
 | `throughline codex-capture --codex-thread-id <id>` | Capture active Codex rollout turns into a `codex:<thread_id>` DB session |
 | `throughline codex-summarize --session codex:<id>` | Summarize captured Codex L2 into L1 with the Codex CLI backend |
 | `throughline codex-resume --session codex:<id>` | Render Codex active-work context from a captured Codex session |

package/bin/throughline.mjs

@@ -11,6 +11,7 @@
  *   throughline detail <時刻> # L2+L3 詳細取得 (Claude が Bash 経由で呼ぶ想定)
  *   throughline recall --l2|--l1 # 注入案内から辿る pull 用 read-only 記憶取得
  *   throughline handoff-preview # Codex-facing throughline_handoff JSON preview
+ *   throughline handoff-context --session <id> --json # Read-only inheritance context JSON
  *   throughline auditor-context --json # Read-only bounded auditor context JSON
  *   throughline factory-diagnostics --json # Native factory read-only readiness JSON
  *   throughline migrate --json # Migrate the existing Throughline database only
@@ -76,6 +77,11 @@ switch (cmd) {
   case 'handoff-preview':
     await (await import('../src/cli/handoff-preview.mjs')).run(rest);
     break;
+  case 'handoff-context': {
+    const exitCode = (await import('../src/cli/handoff-context.mjs')).run(rest);
+    if (exitCode !== 0) process.exitCode = exitCode;
+    break;
+  }
   case 'auditor-context': {
     const exitCode = (await import('../src/cli/auditor-context.mjs')).run(rest);
     if (exitCode !== 0) process.exitCode = exitCode;
@@ -202,6 +208,9 @@ 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 handoff-context --session <id> --json
+                              Print the exact inheritance context without
+                              changing database ownership
   throughline auditor-context --session <id> --project <root>
                               Read only bounded completed user/assistant context
                               for an auditor; requires either --host plus --transcript,

package/docs/00_overview.md

@@ -20,6 +20,7 @@
 | [13_native_factory_diagnostics_plan.md](13_native_factory_diagnostics_plan.md) | native factory read-only readiness 診断の実装記録 |
 | [14_observer_completed_turn_feed_plan.md](14_observer_completed_turn_feed_plan.md) | Observer向けcompleted-only read / wait CLIのactive計画。CLI・opaque cursor・pagination・最大3600秒waitは実装済み、公開／full regression gateは継続中 |
 | [15_windows_ci_release_latency_plan.md](15_windows_ci_release_latency_plan.md) | Windows CI 18分の原因、ACL安全網を維持した短縮、release gateの受入条件 |
+| [16_readonly_handoff_context_plan.md](16_readonly_handoff_context_plan.md) | DB所有権を変更せずSessionStartと同じ記憶を返す、ローカルランチャー向けread-only I/F |
 | [BUGHUB_RUNTIME_ERROR_STORE_PLAN.md](BUGHUB_RUNTIME_ERROR_STORE_PLAN.md) | local runtime error aggregate store の契約と実装 TODO |
 
 ## Supporting Records

package/docs/04_public_release_plan.md

@@ -144,7 +144,7 @@ schema v4 で PostToolUse (`capture-tool`) は廃止、L2/L3 は Stop 内で一
 | **npm公開 (v0.8.6): 製品所有DB migration入口** | `throughline migrate --json` は既存DBだけをproduction migrationで現行schemaへ移行し、versioned bounded JSONを返す。DB不在は作らず`not_applicable`、現行は`already_current`、future schemaと失敗は非0。`factory-diagnostics`のread-only契約は維持する。0.8.5はdry-run後に別作業の未コミット文書が混入したためdeprecateし、同一runtimeをclean worktreeから0.8.6として再公開した。設計判断は [ADR 0018](adr/0018-product-owned-database-migration.md) |
 | **公開済み (v0.8.7): Windows CI release latency** | completed-turn receiptの256件境界fixtureと実ACL検証を分離し、production mutationのPowerShellはdistinct state transitionだけに限定する。temporary ACL失敗時の旧store保持とdirectory／lock／final storeのnative ACL testを維持する。CIは9 matrixのままevent／ref単位concurrency、unit test 5分SLO／8分timeoutとする。設計判断は [ADR 0020](adr/0020-windows-ci-release-latency.md) |
 | **npm公開 (v0.8.8): Codex hook timeout key修理** | Codex `hooks.json` の3 managed hookは秒単位の正規key `timeout`を30／30／300で書く。無視される旧`timeoutSec` entryは次回global installでcommand identityにより置換し、doctorは旧形式を要再install、factory diagnosticsはnot readyとする。Claude hooksとObserver wait deadline APIは変更しない。npm `latest` として2026-08-02T00:43Zに公開済み。tag / GitHub Releaseは未作成（要作成） |
-| **release準備 (v0.8.9): Codex hook診断のPATH非依存化** | 期待hook commandのnode表記は呼び出し元の`PATH`で変わるため、登録済みcommandとの文字列比較では最小PATH（launchd factory reporter等）から正規登録が「legacy command」と誤判定され、`codex_hooks`が恒常的に`not_ready`になっていた。比較を解析済みidentity（node実体realpath＋CLI script realpath＋event）へ変更する。別install／別event／旧PATH解決型／realpath未解決は従来どおり要再install扱い。hooks.json の書式と Claude-facing hook は変更しない |
+| **npm公開 (v0.8.9): Codex hook診断のPATH非依存化** | 期待hook commandのnode表記は呼び出し元の`PATH`で変わるため、登録済みcommandとの文字列比較では最小PATH（launchd factory reporter等）から正規登録が「legacy command」と誤判定され、`codex_hooks`が恒常的に`not_ready`になっていた。比較を解析済みidentity（node実体realpath＋CLI script realpath＋event）へ変更した。別install／別event／旧PATH解決型／realpath未解決は従来どおり要再install扱い。hooks.jsonの書式とClaude-facing hookは変更しない。公開commit `5dbd3af`、CI run `30731697079` 9/9 green、npm `latest` 0.8.9、shasum `780f8e72d9bd4b0c4a331db48116a415a4bde34b`、tag / GitHub Release（v0.8.8分も遡って作成）、registry由来global installを2026-08-02に確認した |
 | **未リリース: Codex current-session 75% trigger** | Codex 自動発火を token-monitor に依存させず、global install が Codex `UserPromptSubmit` / `PostToolUse` hooks も登録する。hook は当該 Codex session の rollout `token_count` を直接読み、verified 75% 以上なら同じ user turn または tool loop 継続前に `$throughline` workflow 実行指示を `additionalContext` で注入する。Stop hook の guarded auto-refresh は残す。`~/.codex/config.toml` は旧 `codex_hooks = true` に加えて現行 `hooks = true` も有効化する |
 | **グローバル E2E 検証** | 2026-04-17 別ディレクトリから `throughline doctor` 全緑を確認 |
 

package/docs/16_readonly_handoff_context_plan.md

@@ -0,0 +1,31 @@
+# Read-only handoff context
+
+## 目的
+
+通常 handoff が使う `buildBudgetedResumeContext` の出力を、DB 所有権を変えずにローカルプログラムが
+取得できる read-only CLI として公開する。最初の consumer は AIterm の portable fork だが、I/F は
+特定 consumer や vendor に依存させない。
+
+実行 ToDo、依存、状態、完了証拠の正本は Lattice plan `readonly-handoff-context` とする。
+
+## 契約
+
+- `throughline handoff-context --session <id> --json` は session を明示必須とする。
+- 既存 DB を `DatabaseSync(..., { readOnly: true })` で開き、作成・migration・書込みをしない。
+- `buildBudgetedResumeContext(db, { sessionId, isInheritance: true })` をそのまま使う。
+- 成功 JSON は schema、status、sessionId、context だけを返す。renderer 統計は公開しない。
+- 引数不正、DB open 失敗、context 不在は非 0 終了とする。
+
+## 非目標
+
+- baton、pending handoff、merge、backfill、通常 SessionStart / UserPromptSubmit の変更。
+- Observer projection、Codex 専用 renderer、latest session 推測、project/cwd 照合。
+- DB schema 全面診断、hash、cursor、暗号化、daemon、network I/O、retry、cache。
+- budget や `excludeOriginId` を CLI option として公開すること。
+
+## 受入条件
+
+- CLI の context が同じ DB に対する既存 budgeted renderer の出力と完全一致する。
+- 実行前後で `sessions.merged_into` と L1/L2/L3 の `session_id` が変わらない。
+- DB 不在時に DB や親ディレクトリを作らない。
+- focused test と全回帰が成功し、公開 package と global install から新 command を実行できる。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.8.9",
+  "version": "0.9.0",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [
@@ -38,7 +38,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --import ./src/test-env.mjs --test src/*.test.mjs src/cli/*.test.mjs"
+    "test": "node --import ./src/test-env.mjs --test scripts/verify-release-commit.test.mjs src/*.test.mjs src/cli/*.test.mjs",
+    "verify:release-commit": "node scripts/verify-release-commit.mjs",
+    "prepublishOnly": "npm run verify:release-commit && npm test"
   },
   "engines": {
     "node": ">=22.13"

package/src/cli/handoff-context.mjs

@@ -0,0 +1,71 @@
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { buildBudgetedResumeContext } from '../resume-context.mjs';
+
+export const HANDOFF_CONTEXT_SCHEMA = 'throughline.handoff_context.v1';
+
+export function parseArgs(argv = []) {
+  if (
+    argv.length !== 3 ||
+    argv[0] !== '--session' ||
+    typeof argv[1] !== 'string' ||
+    argv[1].length === 0 ||
+    argv[2] !== '--json'
+  ) {
+    throw new TypeError('usage error');
+  }
+  return { sessionId: argv[1] };
+}
+
+export function readHandoffContext(sessionId, {
+  dbPath = join(homedir(), '.throughline', 'throughline.db'),
+} = {}) {
+  if (!existsSync(dbPath)) return null;
+
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
+    return buildBudgetedResumeContext(db, {
+      sessionId,
+      isInheritance: true,
+    })?.text ?? null;
+  } finally {
+    db.close();
+  }
+}
+
+export function run(argv = [], {
+  stdout = process.stdout,
+  stderr = process.stderr,
+  readContext = readHandoffContext,
+} = {}) {
+  let sessionId;
+  try {
+    ({ sessionId } = parseArgs(argv));
+  } catch {
+    stderr.write('Usage: throughline handoff-context --session <id> --json\n');
+    return 2;
+  }
+
+  let context;
+  try {
+    context = readContext(sessionId);
+  } catch {
+    stderr.write('Throughline handoff context could not be read.\n');
+    return 1;
+  }
+  if (!context) {
+    stderr.write('Throughline handoff context is not available for that session.\n');
+    return 1;
+  }
+
+  stdout.write(`${JSON.stringify({
+    schema: HANDOFF_CONTEXT_SCHEMA,
+    status: 'ready',
+    sessionId,
+    context,
+  })}\n`);
+  return 0;
+}

package/src/cli/handoff-context.test.mjs

@@ -0,0 +1,143 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DatabaseSync } from 'node:sqlite';
+
+import { buildBudgetedResumeContext } from '../resume-context.mjs';
+
+const REPO_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+const BIN_PATH = join(REPO_ROOT, 'bin/throughline.mjs');
+const SESSION_ID = 'claude-source-session';
+
+function runCli(home, args = ['handoff-context', '--session', SESSION_ID, '--json']) {
+  return spawnSync(process.execPath, [BIN_PATH, ...args], {
+    cwd: REPO_ROOT,
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+    encoding: 'utf8',
+  });
+}
+
+function createFixture(home) {
+  const dir = join(home, '.throughline');
+  mkdirSync(dir, { recursive: true });
+  const dbPath = join(dir, 'throughline.db');
+  const db = new DatabaseSync(dbPath);
+  db.exec(`
+    PRAGMA user_version = 9;
+    CREATE TABLE sessions (
+      session_id TEXT PRIMARY KEY,
+      project_path TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      merged_into TEXT
+    );
+    CREATE TABLE skeletons (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      turn_number INTEGER NOT NULL,
+      role TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      origin_session_id TEXT
+    );
+    CREATE TABLE bodies (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      origin_session_id TEXT NOT NULL,
+      turn_number INTEGER NOT NULL,
+      role TEXT NOT NULL,
+      text TEXT NOT NULL,
+      token_count INTEGER,
+      created_at INTEGER NOT NULL
+    );
+    CREATE TABLE details (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      turn_number INTEGER,
+      tool_name TEXT NOT NULL,
+      input_text TEXT,
+      output_text TEXT,
+      token_count INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      origin_session_id TEXT,
+      kind TEXT NOT NULL DEFAULT 'tool_input',
+      source_id TEXT
+    );
+  `);
+  db.prepare(
+    `INSERT INTO sessions
+       (session_id, project_path, status, created_at, updated_at, merged_into)
+     VALUES (?, ?, 'active', ?, ?, NULL)`,
+  ).run(SESSION_ID, '/work/project', 1_700_000_000_000, 1_700_000_004_000);
+  db.prepare(
+    `INSERT INTO skeletons
+       (session_id, origin_session_id, turn_number, role, summary, created_at)
+     VALUES (?, ?, 1, 'assistant', ?, ?)`,
+  ).run(SESSION_ID, 'older-origin', '以前に portable fork の方針を決めた', 1_700_000_001_000);
+  const insertBody = db.prepare(
+    `INSERT INTO bodies
+       (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+     VALUES (?, ?, 2, ?, ?, 8, ?)`,
+  );
+  insertBody.run(SESSION_ID, SESSION_ID, 'user', '所有権を変えずに記憶を渡して', 1_700_000_002_000);
+  insertBody.run(SESSION_ID, SESSION_ID, 'assistant', 'read-only I/F を実装する', 1_700_000_003_000);
+  db.prepare(
+    `INSERT INTO details
+       (session_id, origin_session_id, turn_number, tool_name, output_text, created_at, kind, source_id)
+     VALUES (?, ?, 2, 'Read', 'schema inspected', ?, 'tool_output', 'detail-1')`,
+  ).run(SESSION_ID, SESSION_ID, 1_700_000_003_500);
+  return { db, dbPath };
+}
+
+function ownershipSnapshot(db) {
+  return {
+    sessions: db.prepare('SELECT session_id, merged_into FROM sessions ORDER BY session_id').all(),
+    skeletons: db.prepare('SELECT id, session_id FROM skeletons ORDER BY id').all(),
+    bodies: db.prepare('SELECT id, session_id FROM bodies ORDER BY id').all(),
+    details: db.prepare('SELECT id, session_id FROM details ORDER BY id').all(),
+  };
+}
+
+test('handoff-context emits the exact inheritance context without changing DB ownership', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-handoff-context-'));
+  try {
+    const { db, dbPath } = createFixture(home);
+    const before = ownershipSnapshot(db);
+    const expected = buildBudgetedResumeContext(db, {
+      sessionId: SESSION_ID,
+      isInheritance: true,
+    })?.text;
+    db.close();
+
+    const result = runCli(home);
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      schema: 'throughline.handoff_context.v1',
+      status: 'ready',
+      sessionId: SESSION_ID,
+      context: expected,
+    });
+
+    const verify = new DatabaseSync(dbPath, { readOnly: true });
+    assert.deepEqual(ownershipSnapshot(verify), before);
+    verify.close();
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('handoff-context fails without creating a missing database', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-handoff-context-missing-'));
+  try {
+    const result = runCli(home);
+    assert.notEqual(result.status, 0);
+    assert.equal(existsSync(join(home, '.throughline')), false);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/cli/help.test.mjs

@@ -51,6 +51,8 @@ test('CLI help exposes guided Codex handoff and guarded execute semantics', () =
   assert.match(result.stdout, /Use --execute to/);
   assert.match(result.stdout, /--open-host auto\|desktop\|vscode\|cli\|none/);
   assert.match(result.stdout, /throughline trim --execute/);
+  assert.match(result.stdout, /throughline handoff-context --session <id> --json/);
+  assert.match(result.stdout, /without\s+changing database ownership/);
   assert.match(result.stdout, /injectable DB memory/);
   assert.match(result.stdout, /matching/);
   assert.match(result.stdout, /rollout\/app-server turns/);
@@ -66,3 +68,8 @@ test('CLI help Codex commands are dispatchable', () => {
     assert.match(bin, new RegExp(`case '${subcommand}':`), `${command} is missing dispatch`);
   }
 });
+
+test('CLI help exposes the dispatchable read-only handoff context boundary', () => {
+  const bin = readFileSync(BIN_PATH, 'utf8');
+  assert.match(bin, /case 'handoff-context':/);
+});

package/src/windows-acl-test-helper.mjs

@@ -1,5 +1,10 @@
 import { spawnSync } from 'node:child_process';
 
+// GitHub hosted Windows runners can spend more than 15 seconds starting the
+// inbox Windows PowerShell process while the Node matrix is contended. This is
+// a hang guard for a fixture boundary, not a latency assertion.
+const WINDOWS_ACL_FIXTURE_TIMEOUT_MS = 30_000;
+
 export function applyWindowsPrivateAcl(path, directory = false) {
   if (process.platform !== 'win32') return;
   const script = String.raw`
@@ -14,10 +19,10 @@ $acl.AddAccessRule($rule)
 if($isDir){[System.IO.Directory]::SetAccessControl($target,$acl)}else{[System.IO.File]::SetAccessControl($target,$acl)}
 `;
   const result = spawnSync('powershell.exe', [
-    '-NoProfile', '-NonInteractive', '-Command', script,
+    '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script,
   ], {
     encoding: 'utf8',
-    timeout: 15_000,
+    timeout: WINDOWS_ACL_FIXTURE_TIMEOUT_MS,
     windowsHide: true,
     env: {
       ...process.env,
@@ -43,10 +48,10 @@ $rule=$rules[0]
 if($rule.IdentityReference.Value -ne $sid -or $rule.AccessControlType -ne 'Allow' -or $rule.IsInherited -or ($rule.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -ne [System.Security.AccessControl.FileSystemRights]::FullControl){exit 43}
 `;
   const result = spawnSync('powershell.exe', [
-    '-NoProfile', '-NonInteractive', '-Command', script,
+    '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script,
   ], {
     encoding: 'utf8',
-    timeout: 15_000,
+    timeout: WINDOWS_ACL_FIXTURE_TIMEOUT_MS,
     windowsHide: true,
     env: {
       ...process.env,