throughline 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -10,6 +10,29 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.4.4] — 2026-05-09
+
+### Changed
+
+- Token monitor now treats Claude transcript and Codex rollout files as live
+  inputs. State-file `usage` snapshots remain a fallback, but the display and
+  stale hiding no longer wait for Stop hook completion when the live files are
+  still changing.
+- `throughline install` now provisions or repairs the current project's VS Code
+  `Throughline Monitor` task when running under VS Code / Cursor / VSCodium, so
+  monitor auto-start setup no longer depends solely on the first hook event.
+
+## [0.4.3] — 2026-05-09
+
+### Changed
+
+- Changed the installed Codex `$throughline` skill so bare `$throughline` runs
+  the scripted current-thread refresh directly:
+  `throughline trim --execute --host codex --all --json`. Doctor, dry-run,
+  preflight, restore-safety analysis, host primitive audit, and fresh-thread
+  handoff remain available only when explicitly requested instead of being the
+  normal skill path.
+
 ## [0.4.2] — 2026-05-09
 
 ### Fixed

package/README.ja.md

@@ -188,7 +188,8 @@ adapter / projection として追加されます。
 Codex sidecar を使えます。使えない場合は、従来どおり Claude Haiku 経路を使います。
 
 Codex 側 trim (= same-thread context trim) は `throughline trim --execute --host codex`
-で発火します。Claude 側は `/clear` での auto path 引継ぎが本線になったため、
+で発火します。Codex の bare `$throughline` skill もこの scripted rollback + DB
+memory inject を直接実行します。Claude 側は `/clear` での auto path 引継ぎが本線になったため、
 `/tl-trim` slash command は v0.4.0 で廃止されました。current-work framing は
 SessionStart 注入の Reading Contract / Continuation Instruction で同じ意図を
 継承しています。
@@ -212,6 +213,10 @@ throughline monitor --session <id-prefix>
 ▶ Throughline       2ed5039c  ████░░░░░░░░░░░░░░░░  205.1k /  21%  残 794.9k  claude-opus-4-6
 ```
 
+監視中は Claude transcript / Codex rollout をライブに読み、Stop hook の state
+snapshot はライブ usage が取れない場合の控えとして使います。これにより表示更新は
+Stop 完了待ちではなくなります。
+
 詳細仕様 (resize 追従、1M context 検出、ステイル隠し、Stop hook の非同期化など) は
 [英語版 README](README.md#multi-session-token-monitor) を参照してください。
 
@@ -221,7 +226,7 @@ throughline monitor --session <id-prefix>
 
 | コマンド | 役割 |
 | --- | --- |
-| `throughline install` | `~/.claude/settings.json` (ユーザー全体) に hook を登録 |
+| `throughline install` | hook / Codex skill を登録し、VS Code 配下なら現プロジェクトの monitor task も配置 |
 | `throughline install --project` | 現リポジトリの `.claude/settings.json` だけに hook を登録 |
 | `throughline uninstall` | hook を削除 |
 | `throughline monitor` | マルチセッション監視を起動 |
@@ -233,7 +238,7 @@ throughline monitor --session <id-prefix>
 | `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 |
-| `throughline trim --execute --host codex` | Codex 同 thread の guarded rollback + DB memory inject |
+| `throughline trim --execute --host codex` | Codex 同 thread の scripted rollback + DB memory inject |
 | `throughline doctor --session <id-prefix>` | 特定セッションの state/transcript ズレを診断 |
 | `throughline status` | DB 統計表示 (sessions / skeletons / bodies / details) |
 | `throughline --version` | インストール済みバージョンを表示 |

package/README.md

@@ -18,7 +18,7 @@
 
 ```bash
 npm install -g throughline
-throughline install     # registers Claude hooks, Codex Stop hook, and Codex skill
+throughline install     # registers hooks/skills and provisions the VS Code monitor task
 ```
 
 That's it. Open any Claude Code session and your turns flow into
@@ -33,8 +33,10 @@ hook invokes the installed `bin/throughline.mjs` through an absolute Node path,
 so Codex App Server PATH differences do not hide the command. It is registered
 synchronously (`async: false`), matching the Codex hook behavior verified in
 Caveat. Existing non-Throughline Codex hooks are preserved. It also installs a
-global `$throughline` Codex skill, so in Codex you can ask for Throughline
-status, resume, summarize, or trim without typing the full guarded command.
+global `$throughline` Codex skill. Bare `$throughline` runs the scripted
+current-thread rollback + Throughline DB memory injection directly; ask
+explicitly for status, resume, summarize, diagnostics, or fresh-thread handoff
+when you want those read-only surfaces instead.
 
 ## How it compares
 
@@ -344,6 +346,7 @@ throughline trim --dry-run --host codex --codex-thread-id <id>
 throughline trim --dry-run --host codex --codex-thread-id <id> --preview-max-chars 4000
 throughline trim --preflight --host codex --codex-thread-id <id>
 CODEX_THREAD_ID=<id> throughline trim --preflight --host codex
+throughline trim --execute --host codex --all --json
 # read-only app-server process restart smoke; not full VS Code restart-safe proof:
 # THROUGHLINE_EXPERIMENTAL_CODEX_RESTORE_SMOKE=1 throughline codex-restore-smoke --codex-thread-id <id> --json
 # read-only local restore source inventory; not full VS Code restart-safe proof:
@@ -514,9 +517,10 @@ Example output:
   (`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`).
   No `length / 4` approximation.
 - **Codex token counts use the rollout `token_count` event when present.** The
-  Codex Stop hook writes `codex:<thread_id>` monitor state and snapshots the
-  latest verified rollout `token_count` sample. If a Codex rollout has no
-  token-count event, Throughline can store an explicit estimate with
+  Codex Stop hook writes `codex:<thread_id>` monitor state with the rollout
+  path. While the monitor is running it reads the live rollout every tick and
+  prefers the latest verified `token_count` sample. If a Codex rollout has no
+  token-count event, Throughline can show an explicit estimate with
   `estimated: true` and the monitor marks it with `est`; it is not presented as
   exact usage.
 - **Codex auto-refresh mutates at the verified 90% threshold.** The Codex Stop
@@ -551,17 +555,17 @@ Example output:
   frame so the previous, wrongly-sized frame can't stack beneath it.
 - **Per-row "last updated" stamp.** Each session row carries an 8-cell
   `just now` / `24m ago` stamp right after the session id, placed before the
-  bar so narrow terminals don't truncate it. It resets to `just now` on every
-  Stop hook, so a growing stamp means the session is truly idle — not the
-  monitor stuck. When you need more detail,
+  bar so narrow terminals don't truncate it. It follows the newest state,
+  transcript, or Codex rollout mtime, so active sessions stay visible and the
+  stamp can move before the next Stop hook completes. When you need more detail,
   `throughline doctor --session <id-prefix>` compares the state file against
   the actual transcript JSONL and flags drift, idle time, and
   `/clear`-induced transcript path staleness.
-- **State-backed usage snapshot.** When the Stop hook finishes a turn it
-  persists the latest `tokens / model / contextWindowSize` back into the state
-  file. The monitor prefers this snapshot over re-reading the JSONL, which
-  removes a source of flicker when the transcript path in state drifts from
-  the one Claude Code is currently appending to.
+- **Live usage first, state snapshot as fallback.** When the Stop hook finishes
+  a turn it persists the latest `tokens / model / contextWindowSize` back into
+  the state file. The monitor now prefers live Claude transcript / Codex rollout
+  reads and uses the snapshot only when the live file cannot provide usage, so
+  the display no longer waits for Stop to update.
 - **Host-aware state.** Missing `host` means an older Claude state file.
   Codex states use `host: "codex"`, keep `transcriptPath: null`, and store the
   Codex rollout path separately as `rolloutPath` so the Claude transcript parser
@@ -578,15 +582,17 @@ Example output:
 
 ### VS Code auto-start (automatic)
 
-After `throughline install`, any VS Code / Cursor / VSCodium project you work in
-gets `.vscode/tasks.json` provisioned automatically on the first session event.
-The file configures `runOn: folderOpen` so the monitor appears in a dedicated
-terminal panel the next time you open that folder.
+After `throughline install`, the current VS Code / Cursor / VSCodium project
+gets `.vscode/tasks.json` provisioned immediately when VS Code environment
+variables are present. Any other VS Code project you work in also gets the file
+on the first session event. The file configures `runOn: folderOpen` so the
+monitor appears in a dedicated terminal panel the next time you open that
+folder.
 
-**How it works.** `ensureMonitorTaskFile` is called from **all three hooks
-(SessionStart, UserPromptSubmit, Stop)** as of v0.3.18. Whichever one fires
-first in your environment creates the file; the rest are idempotent no-ops.
-Once per project it inspects `.vscode/tasks.json`:
+**How it works.** `ensureMonitorTaskFile` is called from `throughline install`
+and from **all three hooks (SessionStart, UserPromptSubmit, Stop)**. Whichever
+one fires first in your environment creates the file; the rest are idempotent
+no-ops. Once per project it inspects `.vscode/tasks.json`:
 
 - **No file yet** → creates one with a single `Throughline Monitor` task, and
   emits a one-time `<system-reminder>` to stdout so Claude tells you a
@@ -644,7 +650,7 @@ entry to the `tasks` array yourself:
 
 | Command                                        | What it does                                                 |
 | ---------------------------------------------- | ------------------------------------------------------------ |
-| `throughline install`                          | Register Claude user hooks/slash commands, the global Codex Stop hook, and the global `$throughline` Codex skill |
+| `throughline install`                          | Register Claude user hooks/slash commands, the global Codex Stop hook, the global `$throughline` Codex skill, and the current VS Code monitor task when applicable |
 | `throughline install --project`                | Register Claude hooks/slash commands in this repo only       |
 | `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                          |
@@ -673,7 +679,7 @@ entry to the `tasks` array yourself:
 | `throughline codex-sidecar-dry-run`            | Print a normalized read-only sidecar request without running the app server |
 | `throughline trim --dry-run --host codex`      | Preview Codex same-thread context trim memory and host boundary; does not rollback automatically |
 | `throughline trim --preflight --host codex`    | Read/resume the explicit Codex thread and verify turn-count guards without rollback/inject |
-| `throughline trim --execute --host codex`      | Explicit Codex rollback-inject path; requires Codex thread identity, injectable DB memory, and rollout/app-server turn-count agreement |
+| `throughline trim --execute --host codex`      | Scripted Codex current-thread rollback + Throughline DB memory inject; this is what bare `$throughline` runs in Codex |
 | `throughline status`                           | Print DB statistics (sessions, skeletons, bodies, details)   |
 | `throughline --version`                        | Print the installed version                                  |
 

package/codex/skills/throughline/SKILL.md

@@ -8,20 +8,21 @@ description: Use when the user asks to use Throughline from Codex, continue or r
 Use this skill to operate Throughline from Codex without making the user type long
 commands.
 
-If the user invokes `$throughline` by itself, treat that as a request to inspect
-the current Codex context and prepare a refresh plan. Codex rollback / inject is
-enabled again after controlled rollback model-visible smokes failed to reproduce
-rollback marker resurrection.
+If the user invokes `$throughline` by itself, treat that as a request to run the
+scripted current-thread refresh now. The normal path is not an AI planning
+exercise: it rolls back the current Codex thread and injects Throughline DB
+memory using the original `/tl` contract.
 
 ## Core Rule
 
 Do not ask the user for a Codex thread id when the current environment can
 provide it. Prefer the current `CODEX_THREAD_ID` / `THROUGHLINE_CODEX_THREAD_ID`
-identity and verify it with `throughline doctor --codex`.
+identity.
 
-Do not manually capture payloads before checking natural Stop hook capture.
-If natural capture looks wrong, inspect `doctor --codex`, the latest rollout,
-and hook logs first.
+For bare `$throughline`, do not run doctor / dry-run / handoff / preflight first
+and do not ask for confirmation. Execute the script command directly. If it
+fails, report the error plainly instead of silently falling back to another
+memory source or a fresh-thread handoff.
 
 ## Common Requests
 
@@ -30,27 +31,21 @@ and hook logs first.
 Run:
 
 ```bash
-throughline doctor --codex
-throughline trim --dry-run --host codex --all --json
-throughline codex-handoff-start --session codex:<current-thread-id> --json
-throughline trim --preflight --host codex --all --json
+throughline trim --execute --host codex --all --json
 ```
 
-This is the safe Codex context-refresh inspection flow. `--all` previews a
-rollback-based reset of the model-visible thread. `codex-handoff-start` is an
-optional fresh-thread continuation surface: it validates the handoff, shows the
-model-smoke dry-run boundary, and can render the prompt with `--print-prompt`
-without mutating the current thread. Report the preflight result, handoff-start
-status, and context reduction estimate from the dry-run. Do not claim the
-refresh happened unless `trim --execute` or auto-refresh actually ran.
+This is the scripted Codex context-refresh flow. It mutates the current Codex
+thread by sending rollback + Throughline DB memory injection. Report only the
+execution status, whether rollback / inject were sent, whether durable evidence
+was observed, and the selected memory session.
 
 The injected memory must preserve the original `/tl` memory contract:
 
-- older turns: L1 summaries
 - recent work: L2 full bodies for the latest 20 turns
+- older turns: L1 summaries
 - L3: detail references only; L3 bodies / tool payloads are not injected
 
-If the dry-run reports no captured turns or no injectable memory, say that
+If there are no captured turns or no injectable Throughline DB memory, say that
 clearly.
 
 ### "Throughline status" / "doctor"
@@ -104,9 +99,19 @@ back to Claude Haiku.
 
 ### "trim" / "rewind" / "rollback" / "context cleanup"
 
-Default to the same inspection flow as bare `$throughline` when the user
+Default to the same scripted execute flow as bare `$throughline` when the user
 asks to trim, rewind, rollback, clean up context, or use Throughline memory.
 
+Execute:
+
+```bash
+throughline trim --execute --host codex --all --json
+```
+
+Report only the essential outcome. Do not introduce fresh-thread handoff,
+restore-safety analysis, host primitive audit, or dry-run planning unless the
+user explicitly asks for those diagnostics.
+
 Preview:
 
 ```bash
@@ -141,17 +146,17 @@ Execute path:
 throughline trim --execute --host codex --all
 ```
 
-Run this only when the user explicitly wants the current thread trimmed. It sends
-rollback + Throughline DB memory injection after the app-server guard checks.
+This is the same command used by bare `$throughline`.
 
 ## User-Facing Explanation
 
 Explain the behavior simply:
 
 - normal Codex turn end: Stop hook captures DB memory and writes monitor state
-- `$throughline` / context refresh: doctor, dry-run, preflight, and optional
-  execute; execute mutates the current Codex thread
-- Stop hook auto-refresh attempts rollback / inject when verified usage reaches
-  90%; estimate usage does not trigger mutation
-- dry-run reports estimated savings when there are rollback candidate turns, but
-  exact host-visible token reduction is not yet measured with the host tokenizer
+- `$throughline` / context refresh: one script command mutates the current Codex
+  thread by rollback + memory inject
+- injected memory is L2 latest 20 full bodies + older L1 summaries + L3
+  references only
+- diagnostics such as doctor, dry-run, preflight, fresh-thread handoff, restore
+  safety, and host primitive audit are optional tools, not the normal
+  `$throughline` path

package/codex/skills/throughline/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Throughline"
   short_description: "Operate Throughline memory, Codex capture, resume, and trim"
-  default_prompt: "Use $throughline to check capture, resume memory, summarize, inspect guarded Codex trim, or prepare a safe fresh-thread handoff without typing long commands."
+  default_prompt: "Use $throughline to run the scripted current-thread rollback + Throughline memory inject, or explicitly ask for status, resume, summarize, diagnostics, or fresh-thread handoff."
 
 policy:
   allow_implicit_invocation: true

package/docs/THROUGHLINE_CODEX_FIRST_ROADMAP.md

@@ -440,7 +440,7 @@ Phase 5 implementation status (2026-05-06):
 - [x] `doctor --codex` は Claude settings を変更しない。Codex primary entrypoint の診断に限定する。
 - [x] 実セッションで `doctor --codex` -> `codex-capture` -> `codex-resume --format item-json` -> `doctor --codex` の local smoke を実施した。`codex-resume` は developer message item JSON を描画し、再診断で captured DB session が 1 件として表示された。
 - [x] 実セッションで `codex-visibility-smoke` を実施した。`THROUGHLINE_EXPERIMENTAL_CODEX_MODEL_VISIBLE_SMOKE=1` を必須にし、長い model turn に備えて `--request-timeout-ms 150000` / `--timeout-ms 180000` を使えるようにした。
-- [x] Codex primary の setup / install 手順は README に記録した。global install は Codex Stop hook と `$throughline` skill を自動登録する。2026-05-08 以降、skill は diagnostics / dry-run / preflight を既定の確認 flow とし、ユーザーが current-thread trim を明示した場合は `trim --execute --host codex --all` を案内する。
+- [x] Codex primary の setup / install 手順は README に記録した。global install は Codex Stop hook と `$throughline` skill を自動登録する。2026-05-09 以降、bare `$throughline` は AI による診断 flow ではなく `trim --execute --host codex --all --json` を直接走らせる scripted current-thread refresh とする。diagnostics / dry-run / preflight / fresh-thread handoff は明示要求時だけ使う。
 - [x] `codex-summarize` を明示診断・運用 flow に追加した。Codex CLI backend を使い、Claude Haiku へ fallback しない。
 - [x] Codex primary の summarize / guarded execute まで含む end-to-end smoke を実施した。2026-05-07 correction では guarded execute を live app-server smoke としてのみ扱った。2026-05-08 unblock 後は、controlled rollback model-visible smoke の `not-reproduced` と current-thread live run の `execute-durable-verified` を合わせて、Codex current-thread trim 完了条件に含める。
   - `codex-capture`: `capturedTurns = 41`, `capturedRows = 75`, `capturedDetails = 2424`
@@ -459,8 +459,8 @@ Phase 5 implementation status (2026-05-06):
   - 絶対パス型の再実測: `npm install -g .` -> `throughline install` 後、`~/.codex/hooks.json` の Stop 先頭は `/usr/bin/node /home/kite/projects/Throughline/bin/throughline.mjs codex-hook stop`、`async: false`、`timeoutSec: 300` になり、Caveat / Spotter hooks は 2 番目以降に保持された。`doctor --codex` は `Codex hooks feature: enabled` / `Codex Stop hook: registered` を表示した。`codex exec --json -C /home/kite/projects/Throughline "Reply exactly: TL_CODEX_ABSOLUTE_STOP_SMOKE_20260506"` で child thread `019dfd5e-1248-7c11-8ddc-97e1b0701e10` が作られ、直後の `throughline doctor --codex` で latest DB session が `codex:019dfd5e-1248-7c11-8ddc-97e1b0701e10` に進んだ。
   - 追加確認: current VSCode-origin parent thread `019dfd38-c530-71c3-b7b8-180bdd3054bc` は hook shape 変更前に開始していたため、変更後の自然 Stop smoke としては不適格。assistant final 後に rollout は `task_complete` まで進んだが latest DB session は exec child のままだった。次に VSCode-origin を見る場合は、hook shape 変更後に新しく開始した Codex session で確認する。
   - 最終確認: hook shape 変更後に新しく開始した VSCode-origin Codex session で 1 turn 完了後、`throughline doctor --codex` を実行した。`current Codex thread` は `019dfd62-9a9d-7211-bf91-89d8e3fc908e`、`latest DB session` は `codex:019dfd62-9a9d-7211-bf91-89d8e3fc908e` で一致し、`Codex hooks feature: enabled`、`Codex Stop hook: registered`、command は `/usr/bin/node /home/kite/projects/Throughline/bin/throughline.mjs codex-hook stop`、`async: false`、`timeoutSec: 300` だった。VSCode-origin の自然 Stop hook による DB capture も解決済みとして扱う。
-  - 2026-05-07 correction: 以下の Codex trim smoke は live app-server primitive の履歴として残す。ただし 2026-05-06 incident 後、restart / reconnect 越しの durable context trim 成功とは扱わない。現在の正は [THROUGHLINE_CODEX_TRIM_ROLLBACK_FIX_PLAN.md](THROUGHLINE_CODEX_TRIM_ROLLBACK_FIX_PLAN.md) であり、`$throughline` / Codex Stop hook は mutation を自動実行しない。
-  - UX 修正: 手動 trim の長い `throughline trim --execute --host codex --codex-thread-id <id>` をユーザーに直接打たせるのではなく、global install で `$throughline` Codex skill を配置する。ただし 2026-05-06 incident 後、skill の既定動作は `doctor --codex`、`trim --dry-run --all`、`trim --preflight --all` までに制限する。bare `$throughline` は rollback + curated memory inject を実行する context refresh ではなく、安全な現状確認として扱う。
+  - historical 2026-05-07 correction: 以下の Codex trim smoke は live app-server primitive の履歴として残す。ただし 2026-05-06 incident 後、restart / reconnect 越しの durable context trim 成功とは一時的に扱わず、`$throughline` / Codex Stop hook の automatic mutation を止めていた。
+  - 2026-05-09 UX 修正: bare `$throughline` は `doctor --codex` / `trim --dry-run --all` / `trim --preflight --all` を AI に順番実行させる説明 surface ではなく、`throughline trim --execute --host codex --all --json` を直接実行する scripted current-thread refresh に戻す。注入 memory は L2 最新 20 full bodies + L1 older summaries + L3 references only。diagnostics / dry-run / preflight / fresh-thread handoff は明示要求時だけ使う。
   - memory contract 修正: Codex guarded trim でも注入 memory は元の `/tl` 思想を正とする。古い turn は L1 summaries、直近 20 turn は L2 full bodies、L3 は reference only で、L3 bodies / tool payloads は注入しない。rollout source は rollback candidate / app-server turn count guard の根拠であり、Throughline DB memory がある場合に rollout active work preview を注入 memory として使わない。DB memory が無い execute は rollout preview を注入せず、mutation 前に拒否する。
   - doctor visibility 修正: `doctor --codex` は旧 context refresh readiness として rollback source、inject memory source、memory contract、L1 summaries / recent L2 bodies / L3 references-only count、heuristic reduction estimate を表示していた。実 thread `019dfd62-9a9d-7211-bf91-89d8e3fc908e` では live readiness として `context refresh: ready`、`rollback source: codex-rollout`、`inject memory source: throughline-db`、`memory contract: older L1 + latest 20 L2 full bodies + L3 references only` を確認した。ただし incident 後は restart-safe readiness ではない。
   - 削減量の記録: `trim --dry-run --host codex` は rollout text がある場合に `contextReductionEstimate` を返す。2026-05-06 の現在 thread `019dfd62-9a9d-7211-bf91-89d8e3fc908e` では通常 keep-recent preview だと `capturedTurns = 14` / `keepRecent = 20` のため `rollbackTurns = 0`、推定削減量も 0 だった。旧 bare `$throughline` context refresh は `--all` を使っていたため、この keep-recent preview の 0 は「Codex で削減できない」という意味ではない。

package/docs/throughline-rollback-context-trim-insight.md

@@ -21,6 +21,8 @@
 
 2026-05-08 unblock: その後の切り分けで、incident thread の retained text は app-server response 上では `aggregatedOutput` など quoted/tool-output field に分類され、controlled rollback model-visible smoke は app-server restart 境界と VS Code reload/reconnect 境界の両方で `not-reproduced` だった。これを受け、Codex `trim --execute --host codex` と Stop hook auto-refresh の過剰 blocker は解除する。`compacted.replacement_history` retention、restore-safety risk、host primitive audit は引き続き diagnostics だが、単独では mutation 前 refusal にしない。DB memory 不在と rollout/app-server turn-count 不一致は引き続き mutation 前 blocker。
 
+2026-05-09 skill UX: bare `$throughline` は diagnostics / dry-run / preflight を AI に順番実行させる surface ではなく、`throughline trim --execute --host codex --all --json` を直接走らせる scripted current-thread refresh とする。目的は rollback と、Throughline DB の L2 最新 20 full bodies + older L1 summaries + L3 references-only memory injection のみ。doctor / dry-run / preflight / fresh-thread handoff / restore-safety / host primitive audit は明示診断用であり、通常 `$throughline` の前段にはしない。
+
 2026-05-07 host primitive audit: `throughline codex-host-primitive-audit` で installed Codex app-server schema を機械監査した。`thread/rollback` / `thread/inject_items` / `thread/compact/start` / `thread/start` / `thread/fork` / `thread/resume` は存在するが、rollback 済み user text を current-thread の model-visible input へ復活させない deletion / isolation / projection primitive は見つからなかった。`thread/resume(history)` は schema 上 `[UNSTABLE] FOR CODEX CLOUD - DO NOT USE` で、`thread_id` も ignored になるため、Throughline の current-thread repair primitive には採用しない。
 
 ## 概要

package/package.json

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

package/src/cli/install.mjs

@@ -15,6 +15,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFi
 import { join, dirname, resolve, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
+import { ensureMonitorTaskFile, shouldRecommendGitignore } from '../vscode-task.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const SLASH_COMMANDS_SRC = join(PACKAGE_ROOT, '.claude', 'commands');
@@ -400,6 +401,10 @@ export async function run(args = []) {
   const { installed: installedCommands, skipped } = installSlashCommands(commandsDir);
   const codex = args.includes('--project') ? null : installCodexHooks();
   const codexSkills = args.includes('--project') ? { installed: [], skipped: null } : installCodexSkills(codexSkillsDir);
+  const monitorTask = ensureMonitorTaskFile({
+    cwd: process.cwd(),
+    env: { ...process.env, THROUGHLINE_SUPPRESS_VSCODE_NOTICES: '1' },
+  });
 
   const scope = args.includes('--project') ? 'プロジェクトローカル' : 'グローバル（全プロジェクト）';
   console.log(`Throughline hooks をインストールしました [${scope}]`);
@@ -436,6 +441,15 @@ export async function run(args = []) {
     console.log('注意: パッケージ内に Codex skills のソースが見つからないためスキップしました。');
     console.log('');
   }
+  if (monitorTask.action === 'created' || monitorTask.action === 'merged' || monitorTask.action === 'repaired') {
+    console.log(`VSCode monitor task を${monitorTask.action === 'repaired' ? '修復' : '配置'}しました:`);
+    console.log(`  ${monitorTask.path}`);
+    console.log('  既に VSCode でこのフォルダを開いている場合は Developer: Reload Window を 1 回実行してください。');
+    if (shouldRecommendGitignore(process.cwd())) {
+      console.log('  共有リポジトリでは .vscode/tasks.json を .gitignore に追加することを推奨します。');
+    }
+    console.log('');
+  }
   console.log('  アンインストール: throughline uninstall');
 
   if (!resolveThroughlineOnPath()) {

package/src/cli/install.test.mjs

@@ -30,13 +30,16 @@ function silence() {
   const origLog = console.log;
   const origErr = console.error;
   const origStderrWrite = process.stderr.write.bind(process.stderr);
+  const origStdoutWrite = process.stdout.write.bind(process.stdout);
   console.log = () => {};
   console.error = () => {};
   process.stderr.write = () => true;
+  process.stdout.write = () => true;
   return () => {
     console.log = origLog;
     console.error = origErr;
     process.stderr.write = origStderrWrite;
+    process.stdout.write = origStdoutWrite;
   };
 }
 
@@ -133,16 +136,48 @@ test('global install copies Throughline Codex skill to ~/.codex/skills/', async
     const metadataBody = readFileSync(metadata, 'utf8');
     assert.match(skillBody, /name: throughline/);
     assert.match(skillBody, /Bare "\$throughline"/);
-    assert.match(skillBody, /throughline codex-handoff-start --session codex:<current-thread-id> --json/);
     assert.match(skillBody, /throughline trim --execute --host codex --all/);
-    assert.match(metadataBody, /inspect guarded Codex trim/);
+    assert.match(skillBody, /do not run doctor \/ dry-run \/ handoff \/ preflight first/);
+    assert.match(metadataBody, /scripted current-thread rollback \+ Throughline memory inject/);
     assert.doesNotMatch(metadataBody, /preview blocked Codex trim/);
+    assert.doesNotMatch(metadataBody, /inspect guarded Codex trim/);
   } finally {
     unsilence();
     home.restore();
   }
 });
 
+test('global install provisions VSCode monitor task for the current project when running under VSCode', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const projectDir = mkdtempSync(join(tmpdir(), 'tl-install-monitor-'));
+  const origCwd = process.cwd();
+  const origVscodePid = process.env.VSCODE_PID;
+  process.chdir(projectDir);
+  process.env.VSCODE_PID = '12345';
+  const unsilence = silence();
+  try {
+    await run([]);
+    const tasksPath = join(projectDir, '.vscode', 'tasks.json');
+    assert.ok(existsSync(tasksPath), 'install should create current-project VSCode tasks.json');
+    const tasks = JSON.parse(readFileSync(tasksPath, 'utf8'));
+    const task = tasks.tasks.find((t) => t.label === 'Throughline Monitor');
+    assert.ok(task, 'Throughline Monitor task should be present');
+    assert.deepEqual(task.args.slice(1), ['monitor']);
+    assert.deepEqual(task.runOptions, { runOn: 'folderOpen' });
+  } finally {
+    unsilence();
+    if (origVscodePid === undefined) delete process.env.VSCODE_PID;
+    else process.env.VSCODE_PID = origVscodePid;
+    process.chdir(origCwd);
+    home.restore();
+    rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
 test('global install preserves existing Codex hooks and is idempotent', async () => {
   const home = makeTempHome();
   if (home.resolved !== home.dir) {

package/src/state-file.mjs

@@ -47,10 +47,9 @@ export function normalizeProjectPath(p) {
  *   host?: 'claude'|'codex',
  * }} data
  *
- * usage: monitor が表示する tokens/model/contextWindowSize をここに固定保存する。
- * Stop hook が readLatestUsage の結果を載せることで、monitor 側が毎フレーム JSONL を
- * 再スキャンする必要がなくなる。旧バージョン互換のため optional (無ければ monitor が
- * transcriptPath を読んでフォールバック)。
+ * usage: Stop hook 完了時点の tokens/model/contextWindowSize fallback snapshot。
+ * monitor はライブ transcript / rollout を優先して読み、ライブ usage が取れない場合だけ
+ * この snapshot を使う。旧バージョン互換のため optional。
  */
 export function writeSessionState({
   sessionId,

package/src/token-monitor.mjs

@@ -13,16 +13,18 @@
  *   - 状態ファイルはセッション単位 (~/.throughline/state/<session_id>.json)
  *   - setInterval (1s) + mtime 差分検知で更新を捕捉
  *   - updatedAt 降順ソート、先頭行を ▶ でハイライト
- *   - stale は PID 生存チェックで判定
+ *   - stale は state 更新時刻 + live transcript / rollout mtime で判定
  *   - Claude は transcript JSONL の最新 assistant usage を直読
- *   - Codex は Stop hook が state.usage に固定した rollout usage / estimate を表示
+ *   - Codex は rollout JSONL の token_count / active-text estimate を直読
+ *   - state.usage は live ファイルが読めない場合の最後の既知値としてだけ使う
  */
 
 import { basename, dirname, join } from 'node:path';
 import { stripVTControlCharacters } from 'node:util';
 import { statSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { getStateDir, readAllSessionStates, snapshotStateMtimes, normalizeProjectPath } from './state-file.mjs';
+import { getStateDir, readAllSessionStates, snapshotStateMtimes, normalizeProjectPath, STALE_HIDE_MS } from './state-file.mjs';
+import { buildCodexMonitorUsage } from './codex-usage.mjs';
 import { readLatestUsage } from './transcript-usage.mjs';
 import { startSizeQuery } from './terminal-size.mjs';
 
@@ -332,6 +334,44 @@ function formatLine({ state, usage, isActive, now = Date.now() }) {
   return `${marker} ${projectCol} ${hostCol} ${idCol} ${agoCol} ${barCol} ${tokCol}  ${modelCol}${warn}`;
 }
 
+function statFile(path) {
+  if (!path || !existsSync(path)) return null;
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+}
+
+function liveActivityMs(state) {
+  const transcript = statFile(state.transcriptPath);
+  const rollout = statFile(state.rolloutPath);
+  return Math.max(
+    Number(state.updatedAt) || 0,
+    transcript?.mtimeMs ?? 0,
+    rollout?.mtimeMs ?? 0,
+  );
+}
+
+function withLiveActivity(state, now = Date.now()) {
+  const updatedAt = liveActivityMs(state);
+  return {
+    ...state,
+    updatedAt,
+    stale: now - updatedAt > STALE_HIDE_MS,
+  };
+}
+
+function resolveMonitorUsage(state) {
+  if (state.host === 'codex' && state.rolloutPath) {
+    return buildCodexMonitorUsage(state.rolloutPath) ?? state.usage ?? null;
+  }
+  if (state.transcriptPath) {
+    return readLatestUsage(state.transcriptPath) ?? state.usage ?? null;
+  }
+  return state.usage ?? null;
+}
+
 // --- フィルタ ---
 /**
  * セッション一覧に表示フィルタを適用する。
@@ -356,12 +396,12 @@ let lastRenderedLines = 0;
 let lastRenderKey = '';
 
 /**
- * 再描画要否の判定キー。state ファイル群の mtime と transcript JSONL の size を
+ * 再描画要否の判定キー。state ファイル群の mtime と transcript / rollout JSONL の
+ * size + mtime を
  * 1 本の文字列にまとめてハッシュキーとする。キーが前回と同じなら描画スキップ。
  *
- * 注: transcript は JSONL append-only なので size 変化 = 新しい usage エントリ到来と
- * 同義。mtime だけでは transcript 更新を検出できない（state-file の mtime は
- * Stop hook のタイミングで更新され、transcript は Claude の stream 中に太る）。
+ * 注: state-file の mtime は Stop hook のタイミングで更新されるが、
+ * transcript / rollout は実行中に太る。その live file 変化も render key に含める。
  */
 function computeRenderKey() {
   const parts = [];
@@ -369,16 +409,18 @@ function computeRenderKey() {
   const mtimes = snapshotStateMtimes();
   const names = Array.from(mtimes.keys()).sort();
   for (const name of names) parts.push(`s:${name}:${mtimes.get(name)}`);
-  // transcript sizes（state ファイルを読まずに直接 stat、IO 最小化）
+  // live transcript / rollout sizes（state ファイルを読まずに直接 stat、IO 最小化）
   try {
     const states = readAllSessionStates();
     for (const st of states) {
-      if (!st.transcriptPath || !existsSync(st.transcriptPath)) continue;
-      try {
-        const size = statSync(st.transcriptPath).size;
-        parts.push(`t:${st.sessionId}:${size}`);
-      } catch {
-        // stat 失敗は無視（次フレームで回復）
+      for (const [kind, path] of [['t', st.transcriptPath], ['r', st.rolloutPath]]) {
+        if (!path || !existsSync(path)) continue;
+        try {
+          const stat = statSync(path);
+          parts.push(`${kind}:${st.sessionId}:${stat.size}:${stat.mtimeMs}`);
+        } catch {
+          // stat 失敗は無視（次フレームで回復）
+        }
       }
     }
   } catch {
@@ -405,7 +447,8 @@ function resetRenderKeyCache() {
 }
 
 function renderFrame(args) {
-  const states = readAllSessionStates();
+  const now = Date.now();
+  const states = readAllSessionStates().map((state) => withLiveActivity(state, now));
   const filtered = filterStates(states, args, process.cwd()).sort(
     (a, b) => b.updatedAt - a.updatedAt,
   );
@@ -428,15 +471,9 @@ function renderFrame(args) {
       `[Throughline] ${filtered.length} セッション${args.all ? ' (--all)' : ''}`,
     );
     lines.push(header);
-    const now = Date.now();
     for (let i = 0; i < filtered.length; i++) {
       const state = filtered[i];
-      // Stop hook が state.usage に固定値を入れていればそれを使う（JSONL 再スキャン不要）。
-      // 旧バージョンが書いた Claude state や usage スナップショットが取れなかったターンでは
-      // transcriptPath を直読。state 側の情報が 1 本化されると
-      // 「state が古い JSONL を指している」時の表示ブレが減る。
-      const usage = state.usage
-        ?? (state.transcriptPath ? readLatestUsage(state.transcriptPath) : null);
+      const usage = resolveMonitorUsage(state);
       lines.push(formatLine({ state, usage, isActive: i === 0, now }));
     }
   }
@@ -698,6 +735,9 @@ export const _internal = {
   shouldForceFullRedraw,
   resolveColumns,
   setMeasuredColumns,
+  liveActivityMs,
+  withLiveActivity,
+  resolveMonitorUsage,
 };
 
 // --- エントリポイント自動起動 ---

package/src/token-monitor.test.mjs

@@ -1,5 +1,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
 import { _internal } from './token-monitor.mjs';
 import { normalizeProjectPath } from './state-file.mjs';
@@ -17,6 +20,8 @@ const {
   shouldForceFullRedraw,
   resolveColumns,
   setMeasuredColumns,
+  withLiveActivity,
+  resolveMonitorUsage,
 } = _internal;
 
 // state-file は projectPath を resolve + lowercase 正規化する。
@@ -128,6 +133,117 @@ test('filterStates: cwd 不一致は除外（--session も --all もなし）',
   assert.equal(result[0].sessionId, 'a');
 });
 
+test('withLiveActivity: transcript mtime keeps a long-running session visible before Stop', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-monitor-live-activity-'));
+  try {
+    const transcript = join(dir, 'session.jsonl');
+    writeFileSync(transcript, '{"type":"user","message":{"content":"working"}}\n');
+    const now = Date.now();
+    const old = now - (20 * 60 * 1000);
+    const state = withLiveActivity({
+      sessionId: 'live-session',
+      host: 'claude',
+      projectPath: CWD_FOO,
+      transcriptPath: transcript,
+      rolloutPath: null,
+      updatedAt: old,
+      stale: true,
+    }, now);
+
+    assert.equal(state.stale, false);
+    assert.ok(state.updatedAt > old);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveMonitorUsage: live Claude transcript overrides stale Stop snapshot', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-monitor-live-usage-'));
+  try {
+    const transcript = join(dir, 'session.jsonl');
+    writeFileSync(transcript, [
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          model: 'claude-opus-4-6',
+          usage: {
+            input_tokens: 1234,
+            cache_creation_input_tokens: 200,
+            cache_read_input_tokens: 300,
+            output_tokens: 10,
+          },
+        },
+      }),
+      '',
+    ].join('\n'));
+
+    const usage = resolveMonitorUsage({
+      sessionId: 'claude-session',
+      host: 'claude',
+      projectPath: CWD_FOO,
+      transcriptPath: transcript,
+      rolloutPath: null,
+      updatedAt: Date.now(),
+      usage: {
+        tokens: 1,
+        model: 'old-snapshot',
+        contextWindowSize: 200_000,
+        outputTokens: 0,
+      },
+    });
+
+    assert.equal(usage.tokens, 1734);
+    assert.equal(usage.model, 'claude-opus-4-6');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveMonitorUsage: live Codex rollout overrides stale Stop snapshot', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-monitor-live-codex-'));
+  try {
+    const rollout = join(dir, 'rollout.jsonl');
+    writeFileSync(rollout, [
+      JSON.stringify({
+        type: 'turn_context',
+        payload: { model: 'gpt-5.5' },
+      }),
+      JSON.stringify({
+        type: 'event_msg',
+        payload: {
+          type: 'token_count',
+          info: {
+            last_token_usage: { input_tokens: 4567, output_tokens: 89 },
+            model_context_window: 258400,
+          },
+        },
+      }),
+      '',
+    ].join('\n'));
+
+    const usage = resolveMonitorUsage({
+      sessionId: 'codex:thread',
+      host: 'codex',
+      projectPath: CWD_FOO,
+      transcriptPath: null,
+      rolloutPath: rollout,
+      updatedAt: Date.now(),
+      usage: {
+        tokens: 1,
+        model: 'old-snapshot',
+        contextWindowSize: 200_000,
+        outputTokens: 0,
+      },
+    });
+
+    assert.equal(usage.tokens, 4567);
+    assert.equal(usage.model, 'gpt-5.5');
+    assert.equal(usage.estimated, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 // ─── cellWidth ─────────────────────────────────────────────────────
 
 test('cellWidth: ASCII は 1 セル', () => {

package/src/turn-processor.mjs

@@ -279,9 +279,8 @@ export async function run() {
     }
   }
 
-  // monitor が JSONL を毎フレーム再スキャンせずに済むよう、現在確定している usage を
-  // state ファイルに固定する。Stop 完了時点で assistant エントリは transcript に
-  // 書き出し済みなので readLatestUsage が最新値を返す。
+  // monitor の fallback 用に、Stop 完了時点で確定している usage を state ファイルにも
+  // 保存する。通常表示はライブ transcript を優先し、読めない時だけ snapshot を使う。
   // 取得失敗は致命ではないので try/catch で握る（stderr には出す）。
   try {
     const usage = transcript_path ? readLatestUsage(transcript_path) : null;