throughline 0.8.9 → 0.9.1

package/CHANGELOG.md

@@ -10,6 +10,39 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.9.1] — 2026-08-14
+
+### Fixed
+
+- Claude-facing SessionStart, UserPromptSubmit, and Stop entrypoints now ignore
+  non-Claude camelCase envelopes immediately after JSON parsing and before any
+  database, state, VS Code task, handoff, transcript, or runtime-error side
+  effect. The boundary requires non-empty `sessionId` and `hookEventName` and
+  the absence of Claude's `session_id`; it does not convert payloads or add a
+  Grok transcript reader.
+
+### Changed
+
+- CI now uses the shared factory workflow for the maintained native and WSL2
+  environments.
+
+### Documentation
+
+- Synchronized the current README, Codex skill, contributor entrypoint, docs
+  overview, and implementation plan around the v0.9.0 read-only handoff-context
+  contract. Historical ADRs, archived plans, and RAG source records remain
+  unchanged as point-in-time evidence.
+
+## [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 |
@@ -340,6 +343,19 @@ Throughline state をまだ書いていない現在セッションも表示で
 | `throughline status` | DB 統計表示 (sessions / skeletons / bodies / details) |
 | `throughline --version` | インストール済みバージョンを表示 |
 
+### ローカルlauncher向けread-only handoff context
+
+通常handoffを実行せず、同一端末のlauncherからThroughline記憶だけを使う場合は次を呼ぶ:
+
+```bash
+throughline handoff-context --session codex:<thread-id> --json
+```
+
+成功時の`throughline.handoff_context.v1`は`schema`、`status`、`sessionId`、`context`だけを返す。
+`context`はSessionStartと同じ予算付き継承文脈で、DB作成・migration・baton消費・session merge・
+latest session推測・`sessions.merged_into`変更・L1/L2/L3 rowの所属変更は行わない。AItermは任意の
+別vendor portable forkでこの境界を使う。Observer feedはcompleted-turn projectionであり代替ではない。
+
 スラッシュコマンド (Claude Code 内でユーザーが叩く):
 
 | コマンド | 役割 |

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
@@ -763,15 +765,12 @@ entry to the `tasks` array yourself:
 
 ## Commands
 
-**v0.6.3 は2026-07-14に公開済みです。** factory diagnostics は Codex の managed
-`UserPromptSubmit` / `PostToolUse` / `Stop` hooks がすべて canonical `ready` の場合に
-Codex readiness を `ready` と返す。Claude connector は未検査のまま明示的に
-`unverified` とし、Codex-only overall を妨げない。local runtime error
-aggregate は collection が既定OFFで、canonical dotagents config の
-`collection.enabled: true` を明示した場合だけ収集します。いずれも network I/O は
-行いません。`throughline@0.6.3`、tag / GitHub Release、公開 CI run
-`29284655280`（9/9 green）を確認済みです。npm registry artifact の shasum は
-`4f3fcd2598a75f026358dae7f3eb3165242b580b` です。
+**v0.9.0 was published on 2026-08-04.** It adds the versioned, read-only
+`handoff-context` boundary for local launchers. The command opens only an
+existing database and leaves baton state, session ownership, and memory rows
+unchanged. Existing factory diagnostics, Observer, runtime-error, capture, and
+normal handoff behavior remain available under the same explicit-failure and
+local-only contracts.
 
 | Command                                        | What it does                                                 |
 | ---------------------------------------------- | ------------------------------------------------------------ |
@@ -797,6 +796,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 |
@@ -819,6 +819,23 @@ aggregate は collection が既定OFFで、canonical dotagents config の
 | `throughline status`                           | Print DB statistics (sessions, skeletons, bodies, details)   |
 | `throughline --version`                        | Print the installed version                                  |
 
+### Read-only handoff context for local launchers
+
+Use this boundary when a local launcher needs Throughline memory without
+performing a normal handoff:
+
+```bash
+throughline handoff-context --session codex:<thread-id> --json
+```
+
+The successful `throughline.handoff_context.v1` object contains only `schema`,
+`status`, `sessionId`, and `context`. The context is the same budgeted
+inheritance text used by SessionStart. The command does not create or migrate a
+database, consume a baton, merge sessions, infer a latest session, change
+`sessions.merged_into`, or reassign L1/L2/L3 rows. AIterm uses this boundary for
+its optional cross-vendor portable fork; the Observer feed is a separate
+completed-turn projection and is not a substitute.
+
 Slash commands (invoked by the user in Claude Code):
 
 | Command       | What it does                                                      |

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/codex/skills/throughline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: throughline
-description: Use when the user asks to use Throughline from Codex, continue or restore Throughline memory, prepare a new Codex thread handoff, summarize a captured Codex session, or check whether the Throughline Codex Stop hook captured the current session. Hide long Throughline command details behind this workflow.
+description: Use when the user asks to use Throughline from Codex, continue or restore Throughline memory, export read-only handoff context for a local launcher, prepare a new Codex thread handoff, summarize a captured Codex session, or check whether the Throughline Codex Stop hook captured the current session. Hide long Throughline command details behind this workflow.
 ---
 
 # Throughline
@@ -112,6 +112,22 @@ throughline codex-summarize --session codex:<current-thread-id> --json
 Codex-primary summarization uses the Codex CLI backend. Do not claim it fell
 back to Claude Haiku.
 
+### "export memory" / "portable fork context"
+
+Run:
+
+```bash
+throughline handoff-context --session <exact-session-id> --json
+```
+
+This is a local read-only export for another launcher. It requires an exact
+session id and returns `schema`, `status`, `sessionId`, and `context`. It does
+not create or migrate the database, consume a baton, merge sessions, move
+memory rows, or change `sessions.merged_into`. Do not substitute the Observer
+completed-turn feed, infer the latest session, or read the SQLite database
+directly. If the command fails or returns no context, report that failure
+instead of falling back to a different memory source.
+
 ### "trim" / "rewind" / "rollback" / "context cleanup"
 
 Default to the same fresh-thread handoff flow as bare `$throughline` when the

package/docs/00_overview.md

@@ -18,8 +18,9 @@
 | [10_transcript_injection_plan.md](10_transcript_injection_plan.md) | transcript injection 検証計画と v0.5 実機結果 |
 | [11_codex_monitor_implementation_plan.md](11_codex_monitor_implementation_plan.md) | Codex monitor 対応の実装記録 |
 | [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は継続中 |
+| [14_observer_completed_turn_feed_plan.md](14_observer_completed_turn_feed_plan.md) | Observer向けcompleted-only read / wait CLIの完了済み設計・受入記録。v0.7.0で公開済み |
 | [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。v0.9.0で公開済み |
 | [BUGHUB_RUNTIME_ERROR_STORE_PLAN.md](BUGHUB_RUNTIME_ERROR_STORE_PLAN.md) | local runtime error aggregate store の契約と実装 TODO |
 
 ## Supporting Records
@@ -43,6 +44,11 @@ ThroughlineはClaude Stop receiptとCodex rolloutの`task_complete`だけからc
 ObserverがDB、WAL、rolloutを直接監視するfallbackは持たない。waitは最大3600秒で、`changed`、`timeout`、
 `resync_required`、`ambiguous_parent`を返す。
 
+portable contextの公開境界は`throughline handoff-context --session <id> --json`である。既存DBを
+read-onlyで開き、SessionStartと同じbudgeted inheritance contextを返すが、baton、merge、
+`sessions.merged_into`、L1/L2/L3 rowの`session_id`は変更しない。Observer境界とは用途もschemaも別で、
+AIterm v0.23.0はこのCLIだけをconsumer境界として使う。
+
 ## Entrypoints
 
 - [../CLAUDE.md](../CLAUDE.md): AI 作業者向けの正本。

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,40 @@
+# Read-only handoff context
+
+## 目的
+
+通常 handoff が使う `buildBudgetedResumeContext` の出力を、DB 所有権を変えずにローカルプログラムが
+取得できる read-only CLI として公開する。最初の consumer は AIterm の portable fork だが、I/F は
+特定 consumer や vendor に依存させない。
+
+実行 ToDo、依存、状態、完了証拠の正本は Lattice plan `readonly-handoff-context` とする。
+
+## 完了
+
+2026-08-04に`throughline@0.9.0`としてnpm、tag、GitHub Release、global installまで公開した。
+focused契約testと全回帰は729 pass／1 skip／0 fail。AIterm v0.23.0の代表cross-vendor smokeでは
+Codex source memoryをClaudeへ注入し、前後でsource session、`sessions.merged_into`、L1/L2/L3 row所属が
+完全一致することを確認した。公開後の現行ドキュメント全域監査は、Latticeの終端ToDoを再openして
+README、作業者入口、配布Codex skill、docs索引、計画、CHANGELOGへ同期した。変更Markdownの
+相対リンク監査とCLI help／handoff-contextのfocused test 5/5を通過した。
+
+## 契約
+
+- `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/docs/adr/0020-windows-ci-release-latency.md

@@ -54,3 +54,26 @@ read-only refuterによる敵対的検証ではP0はなく、次のP1を設計
 - matrix縮小
 - npm自動publish、credential保管
 - release番号だけを根拠にした性能成功扱い
+
+## Terminal audit evidence
+
+2026-08-08 に公開後の終端監査を再確認し、次を受け入れた。
+
+- 公開commit `df215fcaeb6d09d13bfbf5389c6f7c98a995b25c` は現在の `origin/main` の祖先で、
+  annotated tag `v0.8.7` は同commitへ解決する。
+- GitHub Actions run `29726067549` は公開commitに対して9/9 greenである。Windows jobは
+  2分46秒／2分53秒／2分59秒、unit test stepは2分14秒／2分26秒／2分38秒で、
+  5分SLOと3分目標を満たした。
+- GitHub Release `v0.8.7` はdraft／prereleaseではなく公開済みで、公開commit、CI run、
+  Windows実測、npm shasumを保持する。
+- npm registryの `throughline@0.8.7` はshasum
+  `35a50f6878095d0881e75ebfb1da097a8da937c8`、integrity
+  `sha512-7Z/Mz0FRT2bJaxOLl+M8AYlNp5AhmaouQYeiLQ5BKu94+iyo/p1l1vrOhlFHWMlNSv4a89mGYtEAzolPZGRKtA==`
+  を返す。registryから再取得したtarballも同じSHA-1で、212 entries、package version `0.8.7`
+  を確認した。
+- 元のrelease sessionではregistry版global install、`throughline --version = 0.8.7`、
+  managed hooks／skillの再install、migration、`doctor --codex` exit 0まで受け入れた。
+  現在のglobal installは後続release `0.9.0`へ正当に更新済みのため、監査目的のdowngradeは行わない。
+
+以上により、製品受入は2026-07-20時点で完了しており、遅延していたLattice terminal-auditの
+記録を証拠付きで閉じてよいと裁定する。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.8.9",
+  "version": "0.9.1",
   "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/hook-entrypoints.test.mjs

@@ -34,10 +34,10 @@ function childEnv(home) {
   };
 }
 
-function runNode(args, { home, cwd = REPO_ROOT, input = '' }) {
+function runNode(args, { home, cwd = REPO_ROOT, input = '', env = {} }) {
   return spawnSync(process.execPath, args, {
     cwd,
-    env: childEnv(home),
+    env: { ...childEnv(home), ...env },
     input,
     encoding: 'utf8',
   });
@@ -74,6 +74,71 @@ test('hook modules can be imported without executing their hook body', () => {
   }
 });
 
+test('Grok camelCase envelopes are unsupported no-op before Throughline side effects [GF04T]', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const common = {
+    sessionId: 'grok-session',
+    cwd: project,
+    workspaceRoot: project,
+    timestamp: '2026-08-14T00:00:00Z',
+    permissionMode: 'default',
+  };
+  const cases = [
+    {
+      event: 'SessionStart',
+      entrypoint: 'src/session-start.mjs',
+      input: { ...common, hookEventName: 'session_start', source: 'startup' },
+    },
+    {
+      event: 'UserPromptSubmit',
+      entrypoint: 'src/prompt-submit.mjs',
+      input: { ...common, hookEventName: 'user_prompt_submit', prompt: 'hello' },
+    },
+    {
+      event: 'Stop',
+      entrypoint: 'src/turn-processor.mjs',
+      input: {
+        ...common,
+        hookEventName: 'stop',
+        reason: 'end_turn',
+        stopHookActive: false,
+        lastAssistantMessage: 'done',
+        backgroundTasks: [],
+        sessionCrons: [],
+      },
+    },
+  ];
+
+  try {
+    const results = cases.map(({ event, entrypoint, input }) => {
+      const result = runNode([join(REPO_ROOT, entrypoint)], {
+        home,
+        cwd: project,
+        input: JSON.stringify(input),
+        env: { THROUGHLINE_NO_VSCODE: '0', TERM_PROGRAM: 'vscode' },
+      });
+      return { event, status: result.status, stdout: result.stdout, stderr: result.stderr };
+    });
+
+    assert.deepEqual(
+      {
+        results,
+        throughlineStateExists: existsSync(join(home, '.throughline')),
+        vscodeTaskExists: existsSync(join(project, '.vscode', 'tasks.json')),
+      },
+      {
+        results: cases.map(({ event }) => ({ event, status: 0, stdout: '', stderr: '' })),
+        throughlineStateExists: false,
+        vscodeTaskExists: false,
+      },
+    );
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('prompt-submit subprocess writes a /tl baton into an isolated DB', () => {
   const home = makeTempHome();
   const project = makeTempProject();

package/src/hook-envelope.mjs

@@ -0,0 +1,12 @@
+// Grok can invoke Claude-compatible hook commands with its camelCase wire.
+// Throughline does not support Grok as a host, so this envelope is ignored
+// before DB, state, VS Code task, transcript, or runtime-error side effects.
+export function isUnsupportedNonClaudeEnvelope(payload) {
+  return payload !== null
+    && typeof payload === 'object'
+    && typeof payload.sessionId === 'string'
+    && payload.sessionId.length > 0
+    && typeof payload.hookEventName === 'string'
+    && payload.hookEventName.length > 0
+    && !Object.hasOwn(payload, 'session_id');
+}

package/src/prompt-submit.mjs

@@ -42,6 +42,7 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { recordRuntimeErrorBestEffort } from './runtime-error-store.mjs';
+import { isUnsupportedNonClaudeEnvelope } from './hook-envelope.mjs';
 
 // Phase 0-5 spike marker (SessionStart の spike-inject.flag とは別)
 const PROMPT_SPIKE_MARKER_PATH = join(homedir(), '.throughline', 'spike-prompt.flag');
@@ -143,6 +144,7 @@ export async function run() {
   });
 
   const payload = JSON.parse(raw);
+  if (isUnsupportedNonClaudeEnvelope(payload)) return;
   const { session_id, cwd, prompt } = payload;
 
   // VSCode 新規プロジェクトへの tasks.json 自動プロビジョニング。

package/src/session-start.mjs

@@ -32,6 +32,7 @@ import { logDecision } from './decision-log.mjs';
 import { existsSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { recordRuntimeErrorBestEffort } from './runtime-error-store.mjs';
+import { isUnsupportedNonClaudeEnvelope } from './hook-envelope.mjs';
 
 const ENV_DISABLE_AUTO_HANDOFF = 'THROUGHLINE_DISABLE_AUTO_HANDOFF';
 
@@ -91,6 +92,7 @@ export async function run() {
   });
 
   const payload = JSON.parse(raw);
+  if (isUnsupportedNonClaudeEnvelope(payload)) return;
   const { session_id, cwd, source, transcript_path } = payload;
 
   if (!session_id) throw new Error('Missing session_id in SessionStart payload');

package/src/turn-processor.mjs

@@ -46,6 +46,7 @@ import { readLatestUsage } from './transcript-usage.mjs';
 import { pathToFileURL } from 'node:url';
 import { recordRuntimeErrorBestEffort } from './runtime-error-store.mjs';
 import { writeCompletedTurnReceipt } from './completed-turn-receipts.mjs';
+import { isUnsupportedNonClaudeEnvelope } from './hook-envelope.mjs';
 
 /** 直近 N ターンは bodies を生で残し、それより古いものだけ L1 要約する。 */
 export const L2_WINDOW = 20;
@@ -191,6 +192,7 @@ export async function run() {
   });
 
   const payload = JSON.parse(raw || '{}');
+  if (isUnsupportedNonClaudeEnvelope(payload)) return;
   const { session_id, transcript_path, cwd, last_assistant_message } = payload;
   if (!session_id) throw new Error('Missing session_id in Stop payload');
 

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,