throughline 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -10,6 +10,17 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [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 で同じ意図を
 継承しています。
@@ -233,7 +234,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

@@ -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:
@@ -673,7 +676,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.3",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [

package/src/cli/install.test.mjs

@@ -133,10 +133,11 @@ 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();