区間の切れ目の再起動と次のコマンドの入力を前景の中継で自動にする（#895）

[takemi-ohama]

Summary

/goal /ndf:development-workflow の区間の切れ目で人が行っていた「/exit・起動し直し・次のコマンドの貼り付け」を、端末の前景に常駐する中継（plugins/ndf/scripts/relay.py）が行うようにした。人が入力するのは関門の答えだけになる。中継が使えないとき・止まると決めたときは、ndf-relay: の 1 行を出して今までどおりの運用へ落ちる。

• relay.py（新設）: run（claude を擬似端末の子として起動する。印を受けたら子へ /exit を入力し、プラグインを更新して次の区間を起動する。-p・副命令・パイプ・中継の下の起動は、本物の claude を exec して素通しする）/ stop / mark（Stop hook の本体）/ install（SessionStart hook の本体。安定した場所へ置き直し、bash / zsh の設定へ alias を 1 度だけ足す）
• hooks/claude.json: Stop に mark、SessionStart に install を 1 件ずつ足した。Codex / agy の hook の定義は変えていない
• token-guard.sh: 中継の直接の子の conductor では、1 度だけ通す扱いをやめ、上限を超えている限り止め続ける。止めたときの理由の文を ndf-next の形に直した
• 文書: context-window.md に ndf-next のブロックの形を定めた（形の定義はここ 1 か所）。relay.md を新設し、SKILL.md と README.md から参照を張った
• 決定の記録: 実装で決めた 5 件（決定 21〜25）を追記した。未確認の 3 件は実測で決めた。/goal は位置引数で働く / 背景のサブエージェントも background_tasks に running で載る / 目標の判定は記録の attachment.type: goal_status に書かれる

計画: issues/issue-895-plan.md。設計: issues/issue-895-design.md（設計 PR #908）。

関連する issue: Closes #895

Test plan

• uv run --project plugins/playwright-kit/skills/playwright-kit-ops --with pytest pytest . -q -n 4 → exit=0（5443 passed。head fd7a2a4 で再実行）。-n auto はメモリの制約のため使わず、-n 4 で実行した
• python3 scripts/check-skill-frontmatter.py → exit=0
• python3 scripts/check-doc-staleness.py → exit=0
• python3 scripts/check-markdown-links.py --root . → exit=0
• python3 scripts/check-skill-repo-assumptions.py → exit=0
• claude plugin validate . → exit=0（既知の policy / interface の警告だけ）
• 単体テスト plugins/ndf/scripts/tests/test_relay.py（72 件）と test_token_guard.py（中継の下の 4 件を追加）: AC3〜AC4b・AC6〜AC15・AC19〜AC21・AC23・AC24・AC26。子の claude は擬似端末の上で動く試験用のプログラム（tests/fixtures/relay_fake_claude.py）に差し替えた。install は一時の HOME だけで動かし、本物の ~/.bashrc は変えていない
• 実装を 1 か所ずつ壊して、該当のテストが落ちることを確かめた（目標の判定の待ち・空回り・1 日の上限・素通しの深さ・背景の処理・停止の印・作業ディレクトリの落とし先・install の足し直し・ロック・写しの比較の 10 か所）
• AC16・AC22: git diff origin/develop -- plugins/ndf/hooks/codex.json plugins/ndf/dev.agy が空。install を呼ぶのは hooks/claude.json の SessionStart だけ
• Stop の hook の定義のコマンドを、中継の有無の 2 通りで shell からそのまま動かした（無し: 何もせず exit=0 / 有り: next.json が書かれた）
• AC17・AC5・AC25 の通しの確かめ（本物の Claude Code 2.1.280・haiku、擬似端末の上。プラグインの更新は利用者の環境を変えないよう、差し替えのラッパーが受けた）。結果は下の「通しの確かめ」

通しの確かめ（2026-09-23 13:13〜13:39 UTC）

項目	合否	見たこと
AC17	合格	人の入力は 1 つ目の区間の最初の入力と AskUserQuestion の答えだけで、3 つ目の区間まで起動した。log.jsonl に start 3 行と ended_by: mark の end 2 行が残った
AC5	合格	質問の表示から 3 秒後と 20 秒後に next.json が無かった。答えた 1.9 秒後に印が現れ、11.4 秒後に区間 2 へ切り替わった
AC25	合格	NDF_CONTEXT_LIMIT=30000 で、実装: #895 の Agent の起動を 2 回とも止めた（文脈量 39,796 / 40,147）。claude が ndf-next のブロックを出し、区間 2 が起動した
背景の処理（AC24）	合格	背景のサブエージェントが running のあいだは、ブロック付きの応答でも next.json が書かれなかった（80 秒見た）

log.jsonl（AC17 の通し。作業ディレクトリのパスは省いた）:

{"event": "start", "at": "2026-09-23T13:18:09.642Z", "section": 1, "pid": 4187, "command": "", "from_session": "", "plugin_version": "10.17.3", "cwd": "…/runA/work"}
{"event": "end", "at": "2026-09-23T13:18:53.891Z", "section": 1, "pid": 4187, "seconds": 34.732, "ended_by": "mark"}
{"event": "start", "at": "2026-09-23T13:18:53.901Z", "section": 2, "pid": 8405, "command": "区間2: README2.md を読んで指示に従ってください", "from_session": "34fbad01-8e00-447b-bd08-a88b131b17db", "plugin_version": "10.17.3", "cwd": "…/runA/work"}
{"event": "end", "at": "2026-09-23T13:19:12.835Z", "section": 2, "pid": 8405, "seconds": 9.726, "ended_by": "mark"}
{"event": "start", "at": "2026-09-23T13:19:12.845Z", "section": 3, "pid": 11983, "command": "区間3: README3.md を読んで指示に従ってください", "from_session": "8aa69353-4dde-4e59-a9fe-d49845b288dd", "plugin_version": "10.17.3", "cwd": "…/runA/work"}
{"event": "end", "at": "2026-09-23T13:19:55.718Z", "section": 3, "pid": 11983, "seconds": 42.873, "ended_by": "no-mark"}

（最後の no-mark は、確かめを終えるときに /exit で閉じた区間 3 のもの）

未確認の項目の実測（設計の「未確認のまま残ること」）:

• 前の区間の画面: 生の出力には全区間が残るが、claude は区間ごとに代替画面を使う。そのため端末の履歴に残るのは Resume this session with: claude --resume <id> と区切りの 1 行だけになる。会話の記録は残る
• /goal の判定が met: false で止めを拒むと、続いた応答がブロックを出さずに印が消え、中継は待ち続けた（設計の想定どおり）

未検証の項目:

• macOS での親のたどり（ps の経路）は実機で確かめていない
• 本物の claude plugin update を挟んだ切り替え（古い版のディレクトリが消える場合）は確かめていない。確かめの中ではラッパーが受けた
• 利用者の本物の端末（VS Code の統合ターミナル）での見た目は確かめていない

既存の失敗: 無し

範囲外と判断したもの:

• 新しい会話の最初の応答の中で工程へ入る起動は、会話の記録に assistant の行がまだ無いため、文脈量の hook が止めない（導入済みの 10.17.3 も同じ）。新しい会話の最初の応答は文脈が小さく上限に届かないので、実害は無いと判断した
• 中継そのものが SIGTERM / SIGHUP で終わるときは、その区間の end の行が書かれない（子の claude は擬似端末が閉じて後から終わる）。設計は end を「区間の claude が実際に終わったとき」に書くと定めており、中継が先に終わる場合の行は求めていない

工程の記録

• 構造改善: 利用者の指示で省略（cross-refactoring: 変更範囲が狭くても 1 項目ごとに --baseline-test の全体テストを回し、1 項目あたりの待ちが全体テストの時間になる #880 ほか）
• 実装レビュー: /ndf:cross-review 921（codex + kiro、agy は --exclude agy）が 1 ラウンドで収束（codex=APPROVE / kiro=COMMENT で minor 2 件）。最終スイープで 2 件とも修正した（90054b09: _is_self は読めないファイルを中継と見なさない、relayed を local にする）。未解決の指摘は 0 件（verify-sweep で確認）
• CI 修正: 90054b0 の CI で test_run_max_starts_race_one_wins が 1 度落ちた。原因はテストの待ちで、HOME を共有する 2 つの中継のうち相手の stop の行で抜けていた。起動を遅らせる包みで 5/5 再現し、各中継の自分の記録だけを見て両方が決まるまで待つ形に直した（fd7a2a4c、遅延付きで 20/20 通過）。relay.py は変えていない
• 完了判定: head fd7a2a4 で継続的統合がすべて success。手元でも全体テストと CI と同じ静的検査（build-runtime-plugins --check / frontmatter / repo-assumptions / shell-vars / validate-runtime-plugins / markdown-links / doc-line-limit / instructions-check / pr-body-decisions / claude plugin validate .）がすべて exit=0

影響範囲

配布先	変わるか
Claude Code	変わる。bash / zsh の利用者には SessionStart が alias claude=... を 1 度だけ足す（NDF_RELAY_AUTO=0 で止まる）。-p・副命令・パイプは素通しで今までと同じ
Codex	変わらない（hook を足していない）
Kiro CLI	変わらない
agy	変わらない（hook を足していない）

版を上げる必要があるか

要る。hook と利用者のシェル設定への書き込みを足す機能の追加で、まとまりのマージが終わった後に /ndf:release で上げる。

🤖 Generated with Claude Code

https://claude.ai/code/session_01DhcogXCb1x3eStK4VoDDCy

[takemi-ohama]

🤖 cross-review | round 1 | codex | APPROVE

修正必須の指摘はありません。

[takemi-ohama]

🤖 cross-review | round 1 | kiro | COMMENT

relay.py と token-guard.sh の設計・テストは決定 1〜25 と AC に密に対応しており、擬似端末上の統合テストも網羅的である。ブロッキングな欠陥は見つからなかった。以下は小さな 2 点の修正提案。

[takemi-ohama]

🔧 /ndf:fix サマリ | commit 90054b0

対応件数: critical=0 / major=0 / minor=0（合計 0 件）
決着: 2 件 / 見送り: 0 件 / 却下: 0 件
CI: NONE