throughline 0.10.2 → 0.10.5

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src=".github/og.png" alt="Throughline — a whale family carrying direction and memory across changing boundaries" width="100%">
+  <img src="https://raw.githubusercontent.com/kitepon/Throughline/main/.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>
@@ -9,7 +9,7 @@
 [![npm version](https://img.shields.io/npm/v/throughline.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/throughline)
 [![license](https://img.shields.io/npm/l/throughline.svg?color=blue)](LICENSE)
 [![node](https://img.shields.io/node/v/throughline.svg?color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
-[![CI](https://github.com/kitepon-rgb/Throughline/actions/workflows/test.yml/badge.svg)](https://github.com/kitepon-rgb/Throughline/actions/workflows/test.yml)
+[![CI](https://github.com/kitepon/Throughline/actions/workflows/test.yml/badge.svg)](https://github.com/kitepon/Throughline/actions/workflows/test.yml)
 
 **English** · [日本語](README.ja.md)
 
@@ -20,10 +20,12 @@ Built and maintained by [Quo](https://x.com/QLyun35332) at [kitepon.dev](https:/
 
 ## Ownership boundary
 
-This repository owns the database, migrations, capture contracts, release, and
-diagnostics. Cross-product installation and host integration are handled by
-[dotagents](https://github.com/kitepon-rgb/dotagents), the internal development
-toolchain behind kitepon.dev's products.
+This repository owns installation, configuration, state, schema and migrations,
+diagnostics, recovery, updates, and release decisions. Throughline works on its
+own through the documented CLI and does not require a factory controller.
+[dotagents](https://github.com/kitepon/dotagents) may wire Throughline into the
+kitepon.dev development factory, but it integrates the product rather than
+owning its state or controlling its lifecycle.
 MarkItDown is a separately managed third-party CLI.
 
 ## In 30 seconds
@@ -34,15 +36,23 @@ throughline install     # registers hooks/skills and provisions the VS Code moni
 ```
 
 That's it. Open any Claude Code session and your turns flow into
-`~/.throughline/throughline.db` automatically. After 50 turns of work, just
-type `/clear` — the new session resumes mid-thought instead of starting from
-zero. (For non-`/clear` boundaries such as a brand-new chat or a VSCode
-restart, type `/tl` first to mark the predecessor.)
+`~/.throughline/throughline.db` automatically. In VS Code, `/clear` resumes
+through the `SessionStart source='clear'` auto path. Claude Desktop does not
+emit that source, so type `/tl` before `/clear` there. Use `/tl` before any
+other boundary, such as a brand-new chat or a VS Code restart, when you want
+to name the predecessor exactly.
 
 Grok Desktop is also a first-class host. `throughline install` writes
 `~/.grok/hooks/throughline.json`. On Grok, `/tl` does not inject into the
 current window — it starts a new Terminal seat. See below.
 
+Cursor is also a first-class host. `throughline install` upserts
+`sessionStart` / `beforeSubmitPrompt` / `stop` into `~/.cursor/hooks.json` and
+leaves factory hooks in place. Capture reads Cursor `agent-transcripts` jsonl.
+Handoff injection uses `sessionStart` `additional_context`. `/tl` does not
+auto-launch a successor Cursor chat — the next new conversation drinks the
+baton. See [ADR 0022](docs/adr/0022-cursor-host-capture.md).
+
 <details>
 <summary><b>Also using Codex?</b> Global install registers Codex hooks too — click for details.</summary>
 
@@ -107,7 +117,7 @@ one or two turns, then `/tl`.
 | **Memory after the boundary** | ✅ recent turns verbatim (whole, budget-packed) + everything older via `recall` pull + L3 on demand | ❌ zero | △ lossy single summary | △ lossy summary |
 | **Tool I/O handling** | retired to L3, retrievable by `/sc-detail HH:MM:SS` | gone | folded into summary, unreadable | folded into summary |
 | **Coding-assistant fit** | high — tool I/O is the heavy 80% | low — you lose the thread | medium — but irreversible | medium |
-| **Auto-inheritance risk** | low (typed `/clear` / `/tl` names the predecessor) | n/a | n/a | high |
+| **Auto-inheritance risk** | low (`/tl` names the predecessor; VS Code `/clear` freezes one transcript-backed candidate) | n/a | n/a | high |
 | **Runtime deps** | **zero** (Node 22.13+ built-in `node:sqlite`) | n/a | n/a | many |
 | **Multi-session token monitor** | ✅ real `message.usage` / Codex rollout `token_count` | — | — | — |
 
@@ -224,18 +234,19 @@ of tool inputs, tool outputs, and hook output captured at L3 for that turn.
 
 ---
 
-## Inheritance: typed `/clear` and `/tl` write a baton, source-`clear` is the fallback
+## Inheritance: `/tl` writes a baton; VS Code `/clear` uses `source='clear'`
 
-Throughline 0.4.1+ supports two inheritance paths. The **baton path is the
-primary route**; the source-`clear` auto path is the fallback for cases where
-the user's `/clear` does not reach the `UserPromptSubmit` hook (for example
-the VSCode extension's menu-driven `/clear`).
+Throughline supports two inheritance paths. A `/tl` baton names one predecessor
+exactly. If no eligible baton exists, the VS Code `/clear` path can use the
+`SessionStart source='clear'` signal to freeze one transcript-backed predecessor.
+The baton is checked first.
 
 ```mermaid
 flowchart LR
-    U["User types<br/>/clear or /tl"] -->|UserPromptSubmit| W["writeBaton<br/>(session_id + TTL 1h)"]
+    U["User types<br/>/tl"] -->|UserPromptSubmit| W["writeBaton<br/>(session_id + TTL 1h)"]
     W --> B[("handoff_batons<br/>SQLite")]
-    M["VSCode menu<br/>clear"] -->|no UserPromptSubmit| X["no baton"]
+    M["VS Code<br/>/clear"] -->|SessionStart source='clear'| X["freeze predecessor<br/>no baton"]
+    D["Claude Desktop<br/>/clear"] -->|source='startup'| N["no automatic handoff<br/>use /tl first"]
     NS["Next SessionStart<br/>(registers intent only)"] --> FP["First user prompt<br/>(proof the session is real)"]
     FP --> C{"baton<br/>present?"}
     B -.-> C
@@ -254,10 +265,10 @@ flowchart LR
     class P3,INJ neutral
 ```
 
-### baton path (primary): typed `/clear` or `/tl` → deterministic inheritance
+### baton path: `/tl` → deterministic inheritance
 
-When the user types `/clear` or `/tl` in the prompt, the `UserPromptSubmit`
-hook writes a handoff baton with **that session's `session_id`** into the
+When the user types `/tl`, the `UserPromptSubmit` hook writes a handoff baton
+with **that session's `session_id`** into the
 `handoff_batons` table. The next new session consumes the baton **at its
 first user prompt** (eligibility: the session must have been born within the
 1-hour TTL after the baton was written) and merges that exact predecessor's
@@ -274,28 +285,29 @@ started empty. Deferring consumption to the first user prompt closes this:
 a ghost never submits a prompt, so it can never take the baton (ADR 0014).
 
 This path is deterministic: it names the predecessor by id rather than
-guessing, so multi-window scenarios where "most recently updated session"
-does not equal "the session you just `/clear`-ed" still inherit correctly.
+guessing, so it is the explicit path for multi-window work and for hosts that
+do not emit `source='clear'`.
 
 ```
-typed /clear: Session A → /clear → Session B (consumes A's baton, merges A)
-typed /tl:    Session A → /tl    → (new chat / restart) → Session B (consumes baton, merges A)
+/tl: Session A → /tl → (/clear, new chat, or restart) → Session B (consumes A's baton)
 ```
 
-### auto path (fallback): `source='clear'` → heuristic inheritance
+### auto path: VS Code `source='clear'` → frozen predecessor
 
-Since Claude Code 2.1.128, the SessionStart hook receives `source='clear'`
-reliably after `/clear`. When no baton is present (for example because the
-`/clear` was triggered by the VSCode extension's menu and never reached
-`UserPromptSubmit`), Throughline resolves the most recent unmerged session
+The built-in `/clear` command does **not** reach `UserPromptSubmit` on the
+tested Claude Code clients. VS Code instead sends `SessionStart source='clear'`.
+When no baton is present, Throughline resolves the most recent unmerged session
 for the same project **at `SessionStart` time** (freezing that choice, and
 skipping candidates that have no transcript — i.e. ghosts) and performs the
 merge + injection at the session's first user prompt.
 
 Set `THROUGHLINE_DISABLE_AUTO_HANDOFF=1` in your environment to opt out of
-this fallback. **The env var only affects the fallback**; typed `/clear` and
-`/tl` still write a baton and inherit because the user explicitly signalled
-"continue this work".
+this path. The env var does not disable explicit `/tl` batons.
+
+Claude Desktop neither forwards built-in `/clear` to `UserPromptSubmit` nor
+emits `SessionStart source='clear'`; use `/tl` before `/clear` there. The
+cross-client measurements and upstream report are recorded in the archived
+[`docs/12_desktop_clear_handoff_plan.md`](docs/archive/12_desktop_clear_handoff_plan.md).
 
 ### What gets injected
 
@@ -328,7 +340,8 @@ pinning the latest exchange at the top of the injection prevents that drift.
 Each merged row keeps its `origin_session_id`, so repeated handoffs
 accumulate memory through chains:
 
-```
+```text
+VS Code:
 S1 (4 turns) --/clear--> S2 (auto-merges S1, adds 3 turns) --/clear--> S3 (auto-merges S2, adds 5 turns)
                          origin=S1×4                                   origin=S1×4, S2×3, S3×5
 ```
@@ -447,9 +460,10 @@ rollout text, not an exact host tokenizer measurement. If rollback candidate
 turns are `0`, there is no current trim saving under the active keep-recent
 setting.
 
-Claude-side rewind UI itself is not driven by Throughline. The auto-handoff
-flow is `/clear` → new session → automatic injection of curated memory at the
-session's first user prompt.
+Claude-side rewind UI itself is not driven by Throughline. In VS Code, the
+auto-handoff flow is `/clear` → new session → automatic injection of curated
+memory at the session's first user prompt. Claude Desktop requires `/tl`
+before `/clear`.
 Throughline does not invoke `/rewind` or any Claude Code internal command.
 
 Codex-primary setup has an installed Stop hook after global
@@ -803,17 +817,18 @@ entry to the `tasks` array yourself:
 
 ## Commands
 
-**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.
+**The current release is v0.10.5.** Throughline supports Claude Code, Codex,
+Grok, and Cursor as documented host adapters. The versioned, read-only
+`handoff-context` boundary opens only an existing database and leaves baton
+state, session ownership, and memory rows unchanged. 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                                                 |
 | ---------------------------------------------- | ------------------------------------------------------------ |
 | `throughline install`                          | Register Claude user hooks/slash commands, the global Codex UserPromptSubmit/PostToolUse/Stop hooks, the global `$throughline` Codex skill, `~/.grok/hooks/throughline.json`, and the current VS Code monitor task when applicable |
 | `throughline install --project`                | Register Claude hooks/slash commands in this repo only       |
+| `throughline self-update [--json]`             | Update the official npm package, verify that public PATH resolves to that new CLI/version, reapply product-owned integrations, migrate an existing database, and verify public diagnostics in one call |
 | `throughline uninstall`                        | Remove Throughline-managed Claude hooks/slash commands, only the Throughline-managed Codex hook, and the `$throughline` Codex skill |
 | `throughline monitor [--all] [--session <id>]` | Run the multi-session token monitor                          |
 | `throughline monitor --diag`                   | Dump TTY/columns/env diagnostics (for debugging monitor render bugs) |
@@ -827,7 +842,9 @@ local-only contracts.
 | `throughline doctor --codex`                   | Diagnose Codex primary entry state, captured DB sessions, context-refresh memory contract, new-thread handoff readiness, safe continuation status, and host primitive audit |
 | `throughline factory-diagnostics --json`       | Versioned read-only native factory readiness JSON for database schema/migration, connector hooks, and representative capture/restore/handoff; does not emit bodies, secrets, absolute paths, or raw state |
 | `throughline migrate --json`                   | Migrate only an existing Throughline database to the current schema and emit a versioned bounded result; a missing database is not created, while future schemas and migration failures exit non-zero |
-| `throughline runtime-errors snapshot --json`   | Read the bounded product-owned runtime error aggregate. Collection occurs only when canonical dotagents config explicitly sets `collection.enabled: true`; this command performs no network I/O |
+| `throughline runtime-errors enable --json`     | Enable product-owned local runtime error collection in Throughline's own config; default is disabled |
+| `throughline runtime-errors disable --json`    | Disable product-owned local runtime error collection |
+| `throughline runtime-errors snapshot --json`   | Read the bounded product-owned runtime error aggregate; this command performs no network I/O |
 | `throughline runtime-errors diagnostics --json` | Read bounded collection/store status without exposing the state path or raw errors |
 | `throughline runtime-errors ack <cursor> --json` | Explicitly acknowledge records through a monotonic cursor; unacknowledged records are never compacted |
 | `throughline runtime-errors resolve <fingerprint> --json` | Explicitly resolve an aggregate; observing the same fingerprint again reopens it |
@@ -858,6 +875,24 @@ local-only contracts.
 | `throughline status`                           | Print DB statistics (sessions, skeletons, bodies, details)   |
 | `throughline --version`                        | Print the installed version                                  |
 
+### Product-owned runtime error collection
+
+Collection is off by default. Enable it through Throughline's own CLI:
+
+```bash
+throughline runtime-errors enable --json
+throughline runtime-errors diagnostics --json
+```
+
+The product-owned config is
+`$XDG_CONFIG_HOME/throughline/runtime-errors.config.json` on macOS/Linux
+(`~/.config/throughline/...` when `XDG_CONFIG_HOME` is unset) and
+`%LOCALAPPDATA%\throughline\runtime-errors.config.json` on Windows. The CLI
+writes the versioned `throughline.runtime_error_config.v1` shape with private
+permissions. `disable --json` changes only this product config. Throughline
+does not read dotagents configuration; factory integration consumes the public
+`runtime-errors ... --json` contract.
+
 ### Read-only handoff context for local launchers
 
 Use this boundary when a local launcher needs Throughline memory without
@@ -879,21 +914,19 @@ Slash commands (invoked by the user in Claude Code):
 
 | Command       | What it does                                                      |
 | ------------- | ----------------------------------------------------------------- |
-| `/tl`         | Write a handoff baton (explicit inheritance signal across non-`/clear` boundaries — new chat / VSCode restart). On Grok, also launches `grok-continue` after a successful baton write |
-| `/clear`      | Built-in Claude Code reset. Throughline's `UserPromptSubmit` hook also writes a baton so the next session inherits the cleared session's memory |
+| `/tl`         | Write a handoff baton that names the predecessor exactly (use before a new chat, restart, or Claude Desktop `/clear`). On Grok, also launches `grok-continue` after a successful baton write |
+| `/clear`      | Built-in Claude Code reset. VS Code can auto-inherit through `SessionStart source='clear'`; Claude Desktop requires `/tl` first |
 | `/sc-detail <time>` | Retrieve L2 body text and L3 tool I/O for a past turn       |
 
-> Since v0.4.1, both `/clear` and `/tl` typed in the prompt write a baton
-> identifying the current session, so the next new session deterministically
-> inherits that exact predecessor (merge + injection happen at that session's
-> first user prompt — see ADR 0014). The `source='clear'` auto path remains as a
-> fallback for `/clear` triggered outside `UserPromptSubmit` (for example via
-> the VSCode extension menu); `THROUGHLINE_DISABLE_AUTO_HANDOFF=1` only opts
-> out of that fallback.
+> Built-in `/clear` does not reach the tested clients' `UserPromptSubmit` hook.
+> `/tl` is the deterministic baton path. VS Code `/clear` uses the separate
+> `source='clear'` auto path; `THROUGHLINE_DISABLE_AUTO_HANDOFF=1` disables only
+> that auto path.
 
 Hook subcommands (invoked by Claude Code, not by humans):
 `session-start` (SessionStart), `process-turn` (Stop),
-`prompt-submit` (UserPromptSubmit — detects `/tl` and `/clear` and writes a baton; Grok `/tl` also launches `grok-continue`).
+`prompt-submit` (UserPromptSubmit — executes pending handoff and writes `/tl`
+batons; Grok `/tl` also launches `grok-continue`).
 
 ### Observer completed-turn feed (development)
 
@@ -991,13 +1024,13 @@ plain `.mjs` files.
     └── <session_id>.json     Per-session activity state for the monitor
 ```
 
-Schema v8:
+Schema v9:
 
 - `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)`
 - `bodies` — L2 verbatim text (user + assistant), same key shape
 - `details` — L3 records with `kind` column (`tool_input` / `tool_output` / `system` / `image` / `thinking`) and `source_id` for idempotent re-processing
-- `handoff_batons` — one row per `project_path`, with `session_id` and `created_at`. Written by the `UserPromptSubmit` hook when the user types `/tl` or `/clear`. Consumed and deleted at the next new session's **first user prompt**, if that session was born within the 1-hour TTL. (v8 dropped the `memo_text` column when memo was retired in v0.4.0.)
+- `handoff_batons` — one row per `project_path`, with `session_id` and `created_at`. Written by the `UserPromptSubmit` hook for `/tl`. A compatibility `/clear` branch remains in the hook, but tested built-in `/clear` commands are not forwarded to it. The next new session consumes and deletes an eligible baton at its **first user prompt**, if it was born within the 1-hour TTL. (v8 dropped the `memo_text` column when memo was retired in v0.4.0.)
 - `pending_handoffs` — one row per newborn session (`session_id` PK, `project_path`, `source`, `auto_predecessor_id`, `created_at`). Registered by `SessionStart`, consumed exactly once by the session's first `UserPromptSubmit`. Rows belonging to ghost sessions are never consumed and stay behind harmlessly (a few hundred bytes each). Added in v9 (ADR 0014).
 - `injection_log` — audit trail of injection events
 
@@ -1154,23 +1187,21 @@ and `~/.throughline/state/*.json`. A fresh database with schema v9 is created on
 the next hook fire.
 
 **New session didn't inherit memory from the previous one**
-Since v0.4.1, both typed `/clear` and `/tl` write a baton, and the auto path
-falls back on `source='clear'` for menu-driven `/clear`. If inheritance still
-did not happen, the most likely cause is one of: (a) the previous session was
-never recorded (no Stop hook fired — check `throughline status`), (b) the
-1-hour baton TTL expired before the new session opened, (c) the new session's
-`project_path` (cwd) differs from the previous one, so they live in different
-session chains, or (d) you set `THROUGHLINE_DISABLE_AUTO_HANDOFF=1` and the
-`/clear` came from the VSCode menu which never reaches `UserPromptSubmit`.
-Memory is still in SQLite — you can retrieve specific turns with
-`/sc-detail <time>`.
+Use `/tl` before the boundary when you need deterministic inheritance. VS Code
+`/clear` can also use the `source='clear'` auto path; Claude Desktop cannot, so
+it requires `/tl` before `/clear`. Other likely causes are: (a) the previous
+session was never recorded (no Stop hook fired — check `throughline status`),
+(b) the 1-hour baton TTL expired before the new session opened, (c) the new
+session's `project_path` (cwd) differs from the previous one, or (d)
+`THROUGHLINE_DISABLE_AUTO_HANDOFF=1` disabled the VS Code auto path. Memory is
+still in SQLite — retrieve specific turns with `/sc-detail <time>`.
 
 ---
 
 ## Development
 
 ```bash
-git clone https://github.com/kitepon-rgb/Throughline.git
+git clone https://github.com/kitepon/Throughline.git
 cd Throughline
 npm link                              # Put `throughline` on PATH (dev only)
 throughline install --project         # Register hooks for this repo only
@@ -1196,9 +1227,8 @@ the first generation to pick up the auto-start task.
 - [`docs/01_l1_l2_l3_redesign.md`](docs/01_l1_l2_l3_redesign.md) — **core design
   spec** for the L1/L2/L3 differential layer model (schema v4 base + v5 L3
   classification extension). Authoritative for the memory layering rules.
-- [`docs/03_inheritance_on_clear_only.md`](docs/03_inheritance_on_clear_only.md) —
-  design record for the `/tl` baton handoff system (schema v6–v7). Explains
-  why the current inheritance is opt-in rather than heuristic.
+- [`docs/02_clear_auto_handoff_plan.md`](docs/02_clear_auto_handoff_plan.md) —
+  current `/clear` and `/tl` handoff contract.
 - [`docs/08_codex_dual_support.md`](docs/08_codex_dual_support.md) —
   architecture brief for adding Codex support without replacing the Claude
   Code hook/slash-command path.
@@ -1208,17 +1238,15 @@ the first generation to pick up the auto-start task.
 - [`docs/05_codex_first_roadmap.md`](docs/05_codex_first_roadmap.md) —
   current next-phase TODO plan: Codex primary first, Codex rewind-compatible
   trim next, Claude rewind finalization after that.
-- [`docs/07_codex_trim_implementation_plan.md`](docs/07_codex_trim_implementation_plan.md) —
-  historical integrated TODO plan and implementation record for Claude/Codex
-  dual support and rollback trim.
 - [`docs/04_public_release_plan.md`](docs/04_public_release_plan.md) — public
   release plan, implementation status by version, § 0 fallback rule, and
   remaining tasks.
-- [`docs/15_windows_ci_release_latency_plan.md`](docs/15_windows_ci_release_latency_plan.md) —
-  Windows CI performance gate and the ACL-preserving release workflow.
-- [`docs/archive/`](docs/archive/) — superseded design documents kept for
-  historical reference (original CONCEPT, session-linking experiments,
-  pre-publish action list).
+- [`docs/archive/12_desktop_clear_handoff_plan.md`](docs/archive/12_desktop_clear_handoff_plan.md) —
+  historical Claude Desktop measurements, NO-GO decision, and backfill acceptance.
+- [`docs/00_overview.md`](docs/00_overview.md) — current/history/evidence map and
+  document lifecycle rules.
+- [`docs/archive/`](docs/archive/) — completed plans and superseded designs,
+  kept only for historical reference.
 
 ---
 

package/bin/throughline.mjs

@@ -16,10 +16,12 @@
  *   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
- *   throughline runtime-errors snapshot --json # Product-owned runtime error aggregates
+ *   throughline self-update # Update package, integrations, database, and verify the result
+ *   throughline runtime-errors enable --json # Enable product-owned runtime error collection
+ *   throughline runtime-errors snapshot --json # Read product-owned runtime error aggregates
  *   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
+ *   throughline codex-hook user-prompt-submit # Codex rollout capture + monitor state hook
+ *   throughline codex-hook post-tool-use # Codex tool-loop capture + monitor state hook
  *   throughline codex-hook stop # Codex native Stop hook (capture + L1 summarize)
  *   throughline codex-summarize # Summarize captured Codex L2 turns into L1 via Codex CLI
  *   throughline codex-resume # Render Codex active-work context from DB
@@ -113,6 +115,11 @@ switch (cmd) {
     if (exitCode !== 0) process.exitCode = exitCode;
     break;
   }
+  case 'self-update': {
+    const exitCode = (await import('../src/cli/self-update.mjs')).run(rest);
+    if (exitCode !== 0) process.exitCode = exitCode;
+    break;
+  }
   case 'runtime-errors': {
     const exitCode = (await import('../src/cli/runtime-errors.mjs')).run(rest);
     if (exitCode !== 0) process.exitCode = exitCode;
@@ -186,6 +193,15 @@ switch (cmd) {
     console.log(pkg.version);
     break;
   }
+  case '--self-update-identity': {
+    if (rest.length > 0) {
+      process.exitCode = 2;
+      break;
+    }
+    const { buildSelfUpdateIdentity } = await import('../src/cli/self-update.mjs');
+    console.log(JSON.stringify(buildSelfUpdateIdentity()));
+    break;
+  }
   default:
     await showHelp();
 }
@@ -235,22 +251,25 @@ Usage:
                               session/prompt bodies, secrets, absolute paths, or raw state
   throughline migrate --json  Migrate the existing Throughline database only.
                               Does not create a missing database and emits a versioned JSON result
-  throughline runtime-errors snapshot --json
-                              Read bounded local runtime error aggregates. Also supports
-                              diagnostics, ack <cursor>, resolve <fingerprint>, and compact
+  throughline self-update [--json]
+                              Update the official npm package, reapply product-owned
+                              integrations, migrate an existing database, and verify
+                              the installed version and public diagnostics in one call
+  throughline runtime-errors enable --json
+                              Enable product-owned local runtime error collection.
+                              Also supports disable, snapshot, diagnostics, ack <cursor>,
+                              resolve <fingerprint>, reopen <fingerprint>, and compact
   throughline codex-capture     Capture active Codex rollout turns into DB
                               (requires --codex-thread-id or env thread id)
   throughline codex-hook user-prompt-submit
-                              Codex UserPromptSubmit hook: capture rollout and,
-                              at 75%, inject current-session $throughline
-                              instruction from verified rollout token_count
+                              Codex UserPromptSubmit hook: capture rollout and
+                              write monitor state; automatic refresh is disabled
   throughline codex-hook post-tool-use
                               Codex PostToolUse hook: during tool loops, capture
-                              rollout and inject the same 75% $throughline
-                              instruction from verified rollout token_count
+                              rollout and write monitor state; no instruction injection
   throughline codex-hook stop   Codex native Stop hook: capture rollout,
-                              summarize old L2 turns into L1, and run guarded
-                              auto-refresh when verified usage reaches 75%
+                              summarize old L2 turns into L1, and write monitor state;
+                              automatic current-thread refresh is disabled
   throughline codex-summarize   Summarize captured Codex L2 into L1 via Codex CLI
                               (requires a codex:<thread-id> session)
   throughline codex-resume      Render Codex active-work context from DB

package/docs/00_overview.md

@@ -1,58 +1,72 @@
 # Throughline Documentation Overview
 
-このディレクトリは Throughline の設計・計画・監査記録の入口です。実装判断は常に source を正とし、文書は現行実装へ追従させます。
+Throughline の文書は、現行契約・履歴・証拠を分ける。通常作業で読むのはこのページの
+「現行契約」だけであり、完了済み計画を無意識に読み込ませない。
 
-## Canonical Docs
+## 現行契約
 
 | 文書 | 役割 |
 |---|---|
-| [01_l1_l2_l3_redesign.md](01_l1_l2_l3_redesign.md) | L1/L2/L3 記憶レイヤーの設計記録 |
-| [02_clear_auto_handoff_plan.md](02_clear_auto_handoff_plan.md) | `/clear` / `/tl` handoff の現行仕様と計画 |
-| [03_inheritance_on_clear_only.md](03_inheritance_on_clear_only.md) | 2026-04 段階の継承方式検証履歴 |
-| [04_public_release_plan.md](04_public_release_plan.md) | 公開配布化、フォールバック禁止、リリース状態 |
-| [05_codex_first_roadmap.md](05_codex_first_roadmap.md) | Codex primary / trim / Claude finalization の実装順 |
-| [06_codex_trim_rollback_fix_plan.md](06_codex_trim_rollback_fix_plan.md) | Codex rollback / inject incident 後の修正計画 |
-| [07_codex_trim_implementation_plan.md](07_codex_trim_implementation_plan.md) | Codex 両対応 + rollback trim の旧統合計画と実装履歴 |
-| [08_codex_dual_support.md](08_codex_dual_support.md) | Claude primary を維持した Codex adapter 方針 |
-| [09_rollback_context_trim_insight.md](09_rollback_context_trim_insight.md) | rollback を context delete primitive と見る設計メモ |
-| [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の完了済み設計・受入記録。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で公開済み |
-| [plan_grok-successor-launch.md](plan_grok-successor-launch.md) | Grok `/tl` 後の後継席起動。v0.10.0で公開済み。正本は本ファイルと [ADR 0021](adr/0021-grok-host-capture.md) |
-| [BUGHUB_RUNTIME_ERROR_STORE_PLAN.md](BUGHUB_RUNTIME_ERROR_STORE_PLAN.md) | local runtime error aggregate store の契約と実装 TODO |
-
-## Supporting Records
+| [../README.md](../README.md) / [../README.ja.md](../README.ja.md) | 利用者向けの導入、設定、コマンド、状態、診断、復旧、更新 |
+| [CLAUDE.md](https://github.com/kitepon/Throughline/blob/main/CLAUDE.md) | Claude Code 作業者向けの製品正本 |
+| [AGENTS.md](https://github.com/kitepon/Throughline/blob/main/AGENTS.md) | Codex など Claude Code 以外の作業者向け入口 |
+| [01_l1_l2_l3_redesign.md](01_l1_l2_l3_redesign.md) | L1/L2/L3 記憶レイヤーの設計 |
+| [02_clear_auto_handoff_plan.md](02_clear_auto_handoff_plan.md) | `/clear` / `/tl` handoff の現行仕様 |
+| [04_public_release_plan.md](04_public_release_plan.md) | 公開配布、明示的失敗、release gate |
+| [05_codex_first_roadmap.md](05_codex_first_roadmap.md) | Codex primary / trim / Claude finalization の現行順序 |
+| [06_codex_trim_rollback_fix_plan.md](06_codex_trim_rollback_fix_plan.md) | Codex rollback / inject incident 後の現行判断 |
+| [08_codex_dual_support.md](08_codex_dual_support.md) | Claude primary を維持する Codex adapter 方針 |
+| [09_rollback_context_trim_insight.md](09_rollback_context_trim_insight.md) | rollback を context delete primitive と見る設計 |
+| [adr/](adr/) | 現行実装が依拠する不変の設計判断 |
+
+特に現行 host 契約は [ADR 0021](adr/0021-grok-host-capture.md) と
+[ADR 0022](adr/0022-cursor-host-capture.md)、二相 handoff と schema v9 は
+[ADR 0014](adr/0014-two-phase-handoff-ghost-baton.md)、製品所有 migration は
+[ADR 0018](adr/0018-product-owned-database-migration.md) を正とする。
+
+## 固定参照の互換入口
+
+次の短い文書は現行契約の正本ではない。旧pathを固定した計画・証拠・公開URLから、
+archiveと現行正本へ案内するためだけに残す。
+
+| 互換入口 | 現行正本 |
+|---|---|
+| [12_desktop_clear_handoff_plan.md](12_desktop_clear_handoff_plan.md) | [02_clear_auto_handoff_plan.md](02_clear_auto_handoff_plan.md) |
+| [15_windows_ci_release_latency_plan.md](15_windows_ci_release_latency_plan.md) | [04_public_release_plan.md](04_public_release_plan.md) / [ADR 0020](adr/0020-windows-ci-release-latency.md) |
+| [16_readonly_handoff_context_plan.md](16_readonly_handoff_context_plan.md) | [README.md](../README.md) / [公開JSON例](throughline-handoff-context.example.json) |
+| [plan_grok-successor-launch.md](plan_grok-successor-launch.md) | [ADR 0021](adr/0021-grok-host-capture.md) / [README.md](../README.md) |
+
+## 履歴
 
 | 場所 | 役割 |
 |---|---|
-| [adr/](adr/) | 根幹の設計判断 |
+| [archive/](archive/) | 完了済み計画、置換済み設計、過去の実装・受入記録。通常は読まない |
 | [audit-2026-05/](audit-2026-05/) | 2026-05 の監査・インシデント記録 |
-| [archive/](archive/) | 破棄または履歴扱いの旧設計 |
-| [../rag/INDEX.md](../rag/INDEX.md) | 外部仕様・調査の再利用棚 |
+| [adr/](adr/) | 判断時点の背景も保持する設計判断記録 |
+| [../CHANGELOG.md](../CHANGELOG.md) | 公開版ごとの変更履歴 |
 
-現行ADR:
+## 証拠
 
-- [ADR 0001](adr/0001-claude-primary-codex-adapter.md): Claude primaryを維持し、Codexをadapterとして追加する。
-- [ADR 0002](adr/0002-observer-claude-completion-receipt.md): Claude completed turnはThroughline所有のStop receiptで固定する。
-- [ADR 0003](adr/0003-observer-completed-chain-cursor.md): Observer cursorをhost固有のcompleted pair chainとprefix検証へ束縛する。
-- [ADR 0020](adr/0020-windows-ci-release-latency.md): Windows ACL契約を維持し、境界fixtureと実ACL検証を分離する。
-- [ADR 0021](adr/0021-grok-host-capture.md): Grok を first-class hook host にし、`/tl` 後の記憶再開は `grok-continue` に固定する。
+| 場所 | 役割 |
+|---|---|
+| [../rag/INDEX.md](../rag/INDEX.md) | 外部仕様・実機調査の索引 |
+| [evidence/](https://github.com/kitepon/Throughline/tree/main/evidence) | host受入などの固定証拠 |
+| [throughline-handoff-context.example.json](throughline-handoff-context.example.json) | 公開JSON契約の例 |
 
-Observerの公開境界は`throughline observer-read`／`throughline observer-wait`のJSON-only CLIである。
-ThroughlineはClaude Stop receiptとCodex rolloutの`task_complete`だけからcompleted cursorを構築し、
-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境界として使う。
+Throughline は単独で install、設定、状態保存、schema と migration、診断、復旧、更新、
+release 判定まで完結する。状態の正本は `~/.throughline/` と製品コードであり、他製品は
+公開CLI・JSON契約を介して連携する。dotagents は工場全体の配線と統合契約を管理するが、
+Throughline の状態を直接書き換えず、製品の単独運用やrelease判断を制御しない。
 
-## Entrypoints
+## 文書の寿命
 
-- [../CLAUDE.md](../CLAUDE.md): AI 作業者向けの正本。
-- [../README.md](../README.md): ユーザー向けの入口。
-- [../AGENTS.md](../AGENTS.md): Codex など Claude Code 以外のエージェント向け入口。
+- 現行値・操作・判断は既存の現行文書へ統合し、同じ意味の現行文書を増やさない。
+- 完了した計画、置換済み設計、当時の受入記録は `archive/` へ物理移動する。
+- 履歴・証拠は削除せず、通常の必読経路から外す。
+- source と文書が食い違う場合は source とfocused testで確認し、現行文書を同じ変更で直す。
+- 新しい文書は、現行契約・履歴・証拠のどれかを決めてから置く。
+- `npm run verify:docs` は全local link、top-level分類、archive索引、固定参照の互換stub、
+  公開npm tarball内Markdownの相対link/image閉包を検査する。Markdown-only変更でも
+  製品所有CIがこの入口を実行する。

package/docs/01_l1_l2_l3_redesign.md

@@ -1,6 +1,6 @@
 # 新 L1/L2/L3 設計（再定義）
 
-> **Status**: 実装完了（2026-04-16 時点）。この文書は **L1/L2/L3 再定義の設計記録**であり、schema v4-v5 相当の変更までを扱う。以後の `handoff_batons` (v6)・`memo_text` (v7)・state.usage スナップショット・VSCode 自動起動・monitor 診断機能は本仕様と独立で、[CLAUDE.md](../CLAUDE.md) と [04_public_release_plan.md](04_public_release_plan.md) に索引あり。
+> **Status**: 実装完了（2026-04-16 時点）。この文書は **L1/L2/L3 再定義の設計記録**であり、schema v4-v5 相当の変更までを扱う。以後の `handoff_batons` (v6)・`memo_text` (v7)・state.usage スナップショット・VSCode 自動起動・monitor 診断機能は本仕様と独立で、[CLAUDE.md](https://github.com/kitepon/Throughline/blob/main/CLAUDE.md) と [04_public_release_plan.md](04_public_release_plan.md) に索引あり。
 > 全ステップ (1〜8) 実装済み。L1/L2/L3 すべて書き込みパスが稼働。schema v5 で details に `kind` / `source_id` 列追加済み。
 > 進捗の詳細は「実装順序」セクション末尾の進捗表を参照。