docs: design issue 448 n1 exec observation

[kappaseijin4claude]

概要

Issue #448 の設計である。N1 は launcher PID のコマンドラインを 1 回だけ採る。そのため exec 前の launcher 自身を「args 不一致の fail」と判定していた。
これを、binding 観測後に別枠の上限時間まで観測する形へ直す。
文書は docs/decisions/2026-09-13T164649_issue-448-n1-exec-observation.md の 1 本だけで、実装は別 PR で行う。

Refs #448 #434 #407 #395 #444

断定

論点	決定
上限時間	別枠の N1_EXEC_TIMEOUT_SECONDS=10。起点は binding の観測時点。N1_START_TIMEOUT_SECONDS の残りに収める案は採らない。起点が定まらず、未到達の意味が launcher の欠陥と予算不足で区別できないため
観測	0.2 秒ごとに ps -ww -o command= を採り、launcher、claude、unrecognized、absent に分類する。claude は argv[0] と CLAUDE_BIN および CLAUDE_BIN_CANONICAL との一致で判定する。args の照合は claude に分類した後にだけ行う
判定	claude かつ args 一致で pass。claude かつ args 不一致だけが fail。それ以外（exec_not_observed、launcher_exited_before_exec、process_identity_unrecognized）は unknown
証跡	exec-observation.json に経過秒、分類の遷移、binding の mtime を残す。未到達なら launcher-stat.txt、process-command.raw、launcher-output-tail.txt（pty.raw の末尾）も残す。さらに、判定を変えない 5 秒の遅延観測で、遅れて exec したかを記録する

根拠

• binding の公開から exec までに、少なくとも node の起動 4 回と claim の再確認がある（scripts/pilot-launcher.sh:715-826）。runner は 1 秒間隔で binding を探し、validate-binding の後に 1 回だけ ps を採る（scripts/pilot-gate-runner.sh:951-975,1320）。どちらの時点になるかは競合で決まる
• run3（da7e002）と smoke（0c6faff）の差は競合で説明がつくが、実測はしていない。そのため、競合なのか launcher 側の別の欠陥なのかを証跡で切り分けられる形にした（§6.4）
• launcher は PTY の中で動くので、その stderr は stderr.raw ではなく pty.raw に出る。未到達時の証跡は pty.raw の末尾から採る

試験要件

N1E-01〜08（§7.1）。#448 本文が指定した負の対照を含む。

• N1E-02: launcher のコマンドラインを返し続ける stub → unknown になり、fail にならない
• N1E-03: args 不一致の claude → fail

実装 PR では、この 2 つがそれぞれ判定の変異で KILLED になることを示す。

範囲外の報告

インストール済みの Claude Code は 2.1.270 である。一方、#444 の実装は準備完了の検出を 2.1.268 に束縛している（N1_READY_VERIFIED_CLI_VERSIONS）。
本件を直しても、smoke は ready_patterns_unverified_for_cli_version で止まる見込みである（§8）。

README への影響

無。gate harness は開発・受入用の内部ツールである。

🤖 Generated with Claude Code

https://claude.ai/code/session_01QCtgi8wVJDRaMwXHZmkHqT