aiterm-mcp 0.12.1 → 0.12.2

package/README.ja.md

@@ -22,7 +22,12 @@
 
 **言葉でなく実測で:** このリポジトリ自身の 203 テストで、`pty_read` はコンテキストに載るトークンを生ログの **約 7.1 分の 1** に減らす。しかも pass/fail の判定は畳んでも残る。→ [組み込みシェルツールとの使い分け](#組み込みシェルツールとの使い分け)
 
-9 ツール: 6 つの **PTY ツール**（`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`）で 1 本の永続端末を開き・操作し・読む。加えて 3 つの **エージェント起動ツール**（`codex_agent` / `grok_agent` / `composer_agent`）が、別のコーディングエージェントの TUI を新しい端末の中に起動する。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
+10 ツール: 6 つの **PTY ツール**（`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`）で 1 本の永続端末を開き・操作し・読む。加えて 3 つの **エージェント起動ツール**（`codex_agent` / `grok_agent` / `composer_agent`）が、別のコーディングエージェントの TUI を新しい端末の中に起動し、`diagnostics` が安全な factory readiness を返す。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
+
+**v0.12.2 は release candidate（公開待ち）です。** factory diagnostics と local
+runtime-error store は canonical dotagents config の `collection.enabled: true` が明示された
+場合だけ収集し、既定OFF、network送信は行いません。npm公開、tag、CI、registry登録、registry由来install
+の確認は未実施です。
 
 **状態:** 開発継続中 · この分野では新参で、別の形に賭けている（[既存手段との比較](#既存手段との比較)参照）· 動作対象は Linux · WSL2 · macOS · Windows ネイティブ（core PTY ツール。`agent_done` は現時点では POSIX/WSL/macOS のみ）· MIT · [変更履歴](CHANGELOG.md)。
 
@@ -129,7 +134,7 @@ claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 Claude Code を再起動して、接続を確認:
 
 ```bash
-/mcp        # aiterm が connected・9 ツール公開、と出る
+/mcp        # aiterm が connected・10 ツール公開、と出る
 ```
 
 最初のセッション——4 回の呼び出しで、1 個の永続端末:
@@ -167,7 +172,7 @@ MCP クライアントが aiterm を stdio 越しにプログラムから駆動
 
 ```mermaid
 flowchart LR
-    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · codex_agent<br/>grok_agent · composer_agent"| S["aiterm-mcp<br/>stdio MCP · 9 tools"]
+    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · codex_agent<br/>grok_agent · composer_agent · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 10 tools"]
     S -->|"pty_read<br/>token-reduced"| AI
     S -->|"tmux send-keys<br/>capture-pane"| P["persistent PTYs<br/>tmux · survive restarts"]
     P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
@@ -248,6 +253,15 @@ aiterm は同じ核心の洞察——端末を出会いの場にする——を
 | `pty_key` | 制御キーを送る | `session_id`, `key`（`C-c`/`Enter`/`Up`…） |
 | `pty_close` | セッションを閉じる | `session_id` |
 | `pty_list` | セッション一覧 | （なし） |
+| `diagnostics` | 機械可読 JSON による read-only factory readiness | （なし） |
+
+`diagnostics` は PTY やエージェントを起動しない。パッケージ版、MCP 呼出 readiness、read-only な PTY 一覧要約、bounded runtime-error-store status、任意 vendor launcher の可用性だけを返す。path・環境値・認証情報・コマンド本文・PTY 出力・raw log は意図的に返さない。通常未設定の任意依存は `not_applicable`、安全に確定できない状態は `unverified` と表す。
+
+### ローカル runtime error snapshot
+
+`aiterm-runtime-errors snapshot` は dotagents factory adapter 向けに、製品所有のローカル snapshot を機械可読 JSON で返す。canonical dotagents factory-reporter config が schema-exact、host profile が実行 OS と一致し、`collection.enabled` が JSON boolean `true` の時だけ収集する。reporting field は schema 検証するが endpoint/credential file へ接続・読取せず network I/O も行わない。観測 API は core owner layer の固定3 code（PTY dependency・persistence・任意 vendor launcher）だけを受け、保存するのも固定 template と aggregate metadata（SHA-256 fingerprint、count、first/last、status、monotonic sequence）だけ。exception、stderr/stdout、stack、prompt、PTY/transcript/event body、path、任意 context は受け付けない。保存済み JSON も top/record exact・固定定義一致・fingerprint 再計算を通し、明示 DTO だけを返す。
+
+consumer は `aiterm-runtime-errors snapshot` を読み、durable ingestion 後に `aiterm-runtime-errors ack --cursor N` を呼ぶ。運用上の明示操作は `resolve|reopen --fingerprint SHA256`。MCP からの収集・diagnostic read は timeout 付き child process に隔離し、FIFOや停止 filesystem が端末本体を止めない。store mutation は期限付き bakery ticket queue で直列化する。各waiterは PID＋process start identity＋owner token を持つ再利用されない固有ticketを所有するため、死んだownerだけを固有名で除去でき、固定path回収のABAを作らない。POSIX state は `$XDG_STATE_HOME/aiterm-mcp/`（既定 `~/.local/state/aiterm-mcp/`）へ atomic replacement で置き、every read で owner/mode を再検証する。Windows native は `%LOCALAPPDATA%\aiterm-mcp\` で current SID の非継承 FullControl ACE 1件だけへ DACL を再構築し readback する。今回 Windows は path/DACL/timeout の純粋テストだけであり、新しい実機統合成功は主張しない。
 
 ### 対話エージェント起動ツール
 

package/README.md

@@ -22,7 +22,13 @@
 
 **Measured, not claimed:** on this repo's own 203-test suite, a `pty_read` puts **~7.1× fewer tokens** in your context than the raw log — and the pass/fail verdict survives the fold. → [When to reach for it vs. the built-in shell](#when-to-reach-for-it-vs-the-built-in-shell)
 
-Nine tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, plus three **agent launchers** — `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
+Ten tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, three **agent launchers** — `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
+
+**v0.12.2 is a release candidate (pending).** Factory diagnostics and the local
+runtime-error store collect only when canonical dotagents config explicitly sets
+`collection.enabled: true`; collection is off by default and performs no network
+I/O. Publication, tag, CI, registry registration, and registry-install verification
+are pending.
 
 **Status:** actively maintained · the newcomer here, betting on a different shape (see [vs. the alternatives](#vs-the-alternatives)) · runs on Linux · WSL2 · macOS · native Windows for the core PTY tools (`agent_done` is POSIX/WSL/macOS only for now) · MIT · see the [CHANGELOG](CHANGELOG.md).
 
@@ -129,7 +135,7 @@ claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
 Restart Claude Code, then verify the connection:
 
 ```bash
-/mcp        # aiterm should show as connected, exposing 9 tools
+/mcp        # aiterm should show as connected, exposing 10 tools
 ```
 
 Your first session — four calls, one persistent terminal:
@@ -167,7 +173,7 @@ The terminal is real and shared, so a human *can* jump in ([A human can watch](#
 
 ```mermaid
 flowchart LR
-    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · codex_agent<br/>grok_agent · composer_agent"| S["aiterm-mcp<br/>stdio MCP · 9 tools"]
+    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · codex_agent<br/>grok_agent · composer_agent · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 10 tools"]
     S -->|"pty_read<br/>token-reduced"| AI
     S -->|"tmux send-keys<br/>capture-pane"| P["persistent PTYs<br/>tmux · survive restarts"]
     P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
@@ -250,6 +256,15 @@ On top of that sits a productized layer a raw tmux bridge doesn't have: **token-
 | `pty_key` | Send a control key | `session_id`, `key` (`C-c`/`Enter`/`Up`…) |
 | `pty_close` | Close a session | `session_id` |
 | `pty_list` | List sessions (agent rows carry `agent=<kind>` metadata) | (none) |
+| `diagnostics` | Read-only factory readiness as machine-readable JSON | (none) |
+
+`diagnostics` never starts a PTY or agent. It reports package version, MCP call readiness, a read-only PTY-list summary, bounded runtime-error-store status, and optional vendor-launcher availability. It deliberately excludes paths, environment values, credentials, command text, PTY output, and raw logs; normal unset optional dependencies are `not_applicable`, while an indeterminate probe is `unverified`.
+
+### Local runtime error snapshot
+
+`aiterm-runtime-errors snapshot` exposes a machine-readable, product-owned local snapshot for the dotagents factory adapter. Collection is fail-closed unless the canonical dotagents factory-reporter config is schema-exact, its host profile matches the executing OS, and it contains the JSON boolean `collection.enabled: true`; reporting fields are schema-validated but endpoints and credential files are never contacted, and the store performs no network I/O. The only accepted observations are three fixed codes owned by the core boundary (PTY dependency, persistence, and optional vendor launcher). Stored data is limited to fixed templates and aggregate metadata (SHA-256 fingerprint, count, first/last seen, status, and monotonic sequence); exceptions, stderr/stdout, stacks, prompts, terminal/transcript/event bodies, paths, and arbitrary context cannot enter the API. Persisted JSON is revalidated with exact top/record fields and a recomputed fingerprint before explicit DTO projection.
+
+Consumer flow is `aiterm-runtime-errors snapshot`, then `aiterm-runtime-errors ack --cursor N` after durable ingestion. Operators can use `resolve|reopen --fingerprint SHA256`. MCP collection and diagnostic reads run in timeout-bounded child processes, so a FIFO or stalled filesystem cannot block terminal work; child failure emits only the fixed store diagnostic. Store mutation uses a bounded bakery ticket queue: every waiter owns a never-reused ticket containing PID, process-start identity, and an owner token, so dead owners are removed by unique filename without fixed-path reclaim ABA. Worker deadlines use forced termination so a SIGTERM-ignoring child cannot mutate state after timeout. POSIX state is atomically replaced under `$XDG_STATE_HOME/aiterm-mcp/` (default `~/.local/state/aiterm-mcp/`) with owner/mode rechecked on every read. Windows native uses `%LOCALAPPDATA%\aiterm-mcp\`; each DACL is rebuilt and read back as one non-inherited FullControl ACE for the current SID. Windows path/DACL/timeout behavior is covered by pure tests in this change; no new Windows integration success is claimed.
 
 ### Interactive agent launchers
 

package/dist/core.js

@@ -14,6 +14,7 @@ import * as os from "node:os";
 import { createHash, randomBytes } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import * as rtk from "./rtk.js";
+import { recordRuntimeError } from "./runtime-error-store.js";
 // Windows ネイティブには tmux が無い。その場合だけ全 tmux 呼び出しを WSL 経由へ橋渡しする
 // （POSIX = Linux/WSL2/macOS は従来どおり tmux を直接叩く）。
 const isWin = process.platform === "win32";
@@ -98,6 +99,33 @@ export class AitermError extends Error {
         this.code = code;
     }
 }
+class TelemetryOwnedError extends AitermError {
+    telemetryCode;
+    constructor(message, code, telemetryCode, cause) {
+        super(message, code);
+        this.name = "TelemetryOwnedError";
+        this.telemetryCode = telemetryCode;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+function telemetryOwnedFailure(telemetryCode, error, fallbackCode = 1) {
+    if (error instanceof TelemetryOwnedError)
+        return error;
+    recordRuntimeError(telemetryCode);
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof AitermError ? error.code : fallbackCode;
+    return new TelemetryOwnedError(message, code, telemetryCode, error);
+}
+function ownTelemetryFailure(telemetryCode, error, fallbackCode = 1) {
+    throw telemetryOwnedFailure(telemetryCode, error, fallbackCode);
+}
+function ptyDependencyError(message, observe = true) {
+    const error = new AitermError(message, 2);
+    if (observe)
+        ownTelemetryFailure("AITERM.PTY_DEPENDENCY_UNAVAILABLE", error, 2);
+    throw error;
+}
 // Windows のドライブパス (C:\a\b) を WSL から見える /mnt/c/a/b へ変換する。
 // 一時領域は常にドライブ直下なので UNC は想定外＝弾く（黙って壊れた //server パスを作らない）。
 export function toWslPath(p) {
@@ -109,22 +137,22 @@ export function toWslPath(p) {
 // Windows で最初の tmux 呼び出し前に一度だけ WSL+tmux の可用性を確かめ、失敗は原因別に投げる。
 // -e（ログインシェル非経由）＋短い timeout で、初回セットアップ未完了の wsl によるハングも防ぐ。
 let winBridgeOk = false;
-function ensureWinBridge() {
+function ensureWinBridge(observe = true) {
     if (winBridgeOk)
         return;
     const r = spawnSync("wsl.exe", ["-e", "tmux", "-V"], { encoding: "utf8", timeout: 10000 });
     if (r.error) {
         const code = r.error.code;
         if (code === "ETIMEDOUT")
-            throw new AitermError("WSL が応答しません（初回セットアップ未完了の可能性）。一度 `wsl` を起動してから再実行してください。", 2);
+            ptyDependencyError("WSL が応答しません（初回セットアップ未完了の可能性）。一度 `wsl` を起動してから再実行してください。", observe);
         if (code === "ENOENT")
-            throw new AitermError("wsl.exe が見つかりません。Windows では WSL 上の tmux 経由で動作します。WSL と tmux を導入してください。", 2);
-        throw new AitermError(`wsl.exe を起動できませんでした（${code ?? "unknown"}）。`, 2);
+            ptyDependencyError("wsl.exe が見つかりません。Windows では WSL 上の tmux 経由で動作します。WSL と tmux を導入してください。", observe);
+        ptyDependencyError(`wsl.exe を起動できませんでした（${code ?? "unknown"}）。`, observe);
     }
     // wsl.exe は System32 にあるので「起動」は成功するが、ディストリ未導入や distro 内に tmux が無いと
     // 非ゼロで終わる。両方を区別せず（wsl の出力は UTF-16 で文字化けし得るため）正直に表す。
     if (r.status !== 0)
-        throw new AitermError("WSL 経由で tmux を起動できませんでした。WSL のディストリ未導入、または distro 内に tmux が無い可能性があります。`wsl tmux -V` が通るか確認してください（tmux 導入例: sudo apt install tmux）。", 2);
+        ptyDependencyError("WSL 経由で tmux を起動できませんでした。WSL のディストリ未導入、または distro 内に tmux が無い可能性があります。`wsl tmux -V` が通るか確認してください（tmux 導入例: sudo apt install tmux）。", observe);
     winBridgeOk = true;
 }
 // tmux が見つからないときの説明。macOS は tmux を同梱せず、Homebrew の bin は GUI 起動時の PATH に
@@ -143,7 +171,7 @@ function tmuxMissingMessage() {
 // 解決順: AITERM_TMUX（明示指定）→ PATH 上の tmux → Homebrew 既定パス。一度だけ実行しキャッシュする。
 // 見つからなければ tmuxMissingMessage で投げる（黙ってフォールバックせず、原因が見えるようにする）。
 let tmuxBin = null;
-function resolveTmux() {
+function resolveTmux(observe = true) {
     if (tmuxBin)
         return tmuxBin;
     const override = process.env.AITERM_TMUX;
@@ -151,7 +179,7 @@ function resolveTmux() {
         const r = spawnSync(override, ["-V"], { encoding: "utf8", timeout: 5000 });
         if (!r.error && r.status === 0)
             return (tmuxBin = override);
-        throw new AitermError(`AITERM_TMUX に指定された tmux を起動できません: ${override}（\`${override} -V\` が通りません）`, 2);
+        ptyDependencyError(`AITERM_TMUX に指定された tmux を起動できません: ${override}（\`${override} -V\` が通りません）`, observe);
     }
     // CLI/開発時は PATH 上の tmux をそのまま使う（最優先）。
     const onPath = spawnSync("tmux", ["-V"], { encoding: "utf8", timeout: 5000 });
@@ -169,20 +197,20 @@ function resolveTmux() {
             /* 次の候補へ */
         }
     }
-    throw new AitermError(tmuxMissingMessage(), 2);
+    ptyDependencyError(tmuxMissingMessage(), observe);
 }
-function tmux(...args) {
+function tmuxCommand(observe, ...args) {
     // maxBuffer は既定 1MiB。capture-pane（大きなスクロールバック）や多セッションの list-sessions で
     // 頭打ちになり stdout が切れる/空になる。Python の subprocess.run は無制限だったので 64MiB へ広げる。
     // Windows は同じ tmux を WSL 経由（-e でログインシェル非経由＝$ 展開やクオート崩れを防ぐ）で叩く。
     let r;
     if (isWin) {
-        ensureWinBridge();
+        ensureWinBridge(observe);
         r = spawnSync("wsl.exe", ["-e", "tmux", "-S", SOCK, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
     }
     else {
         // resolveTmux() は tmux を解決できなければ明確な AitermError を投げる（POSIX 版の事前確認）。
-        r = spawnSync(resolveTmux(), ["-S", SOCK, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+        r = spawnSync(resolveTmux(observe), ["-S", SOCK, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
     }
     // ENOBUFS（出力が 64MiB 超）を「code=1 の失敗」へ握り潰すと部分/空 stdout を正常扱いしてしまう。区別して投げる。
     // EXPECTED-FAILURE: 外部システム境界（tmux 出力過大）
@@ -193,10 +221,16 @@ function tmux(...args) {
     // 通常は resolveTmux() が事前に弾くため発火しないが、mid-run 消滅に対する正直な防御。
     if (!isWin && r.error && r.error.code === "ENOENT") {
         tmuxBin = null; // 次回 resolveTmux で再解決を許す
-        throw new AitermError(tmuxMissingMessage(), 2);
+        ptyDependencyError(tmuxMissingMessage(), observe);
     }
     return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
 }
+function tmux(...args) {
+    return tmuxCommand(true, ...args);
+}
+function tmuxCleanup(...args) {
+    return tmuxCommand(false, ...args);
+}
 function sessionExists(name) {
     return tmux("has-session", "-t", name).code === 0;
 }
@@ -685,7 +719,12 @@ function assertNotDestructive(text, code, context = "") {
 }
 // ---------------------------------------------------------------- 操作（return で返す / 失敗は AitermError）
 export function openSession(name, shell = "bash") {
-    fs.mkdirSync(SOCKDIR, { recursive: true });
+    try {
+        fs.mkdirSync(SOCKDIR, { recursive: true });
+    }
+    catch (error) {
+        ownTelemetryFailure("AITERM.PERSISTENCE_WRITE_FAILED", error);
+    }
     // macOS の /bin/bash は 3.2 で、起動時に zsh 移行バナーを出して最初の read を汚す。darwin かつ bash の
     // ときだけ -e で環境変数を渡して抑止する。-e は tmux>=3.2 が必要だが macOS の Homebrew tmux は常に該当。
     // （古い tmux<3.2 が残る Linux/WSL で -e を渡すと new-session が落ちるため、darwin 限定にする。）
@@ -720,7 +759,12 @@ export function openSession(name, shell = "bash") {
     // 新規セッションの .log は必ず truncate する。"a"（追記）だと外部 kill / killAll / クラッシュで
     // 同名 session だけ消えて .log が残った場合、offset=0 と相まって旧出力を新規として返す（B5）。
     // break は new-session 成功後にのみ到達＝作りたての空 session ゆえ切り詰めは安全。lastcmd/mark 残骸も掃除。
-    fs.writeFileSync(logpath(nm), "");
+    try {
+        fs.writeFileSync(logpath(nm), "");
+    }
+    catch (error) {
+        ownTelemetryFailure("AITERM.PERSISTENCE_WRITE_FAILED", error);
+    }
     for (const p of [lastcmdpath(nm), markpath(nm)]) {
         try {
             fs.unlinkSync(p);
@@ -738,16 +782,24 @@ export function openSession(name, shell = "bash") {
     const pr = tmux("pipe-pane", "-t", nm, "-o", `cat >> ${quoted}`);
     if (pr.code !== 0) {
         // 配管に失敗した session は pty_read が永遠に空を返す＝成功を装わない。作った session を片付けて明示エラー。
-        tmux("kill-session", "-t", nm);
+        try {
+            tmuxCleanup("kill-session", "-t", nm);
+        }
+        catch { /* cleanup failure is not a second observation */ }
         try {
             fs.unlinkSync(logpath(nm)); // B14: 直前に作った空 .log も残さない
         }
         catch {
             /* noop */
         }
-        throw new AitermError("tmux pipe-pane 失敗（出力ログを配管できないため session を破棄）: " + pr.stderr.trim(), 2);
+        ownTelemetryFailure("AITERM.PERSISTENCE_WRITE_FAILED", new AitermError("tmux pipe-pane 失敗（出力ログを配管できないため session を破棄）: " + pr.stderr.trim(), 2), 2);
+    }
+    try {
+        writeOffset(nm, 0);
+    }
+    catch (error) {
+        ownTelemetryFailure("AITERM.PERSISTENCE_WRITE_FAILED", error);
     }
-    writeOffset(nm, 0);
     return [nm, attachHint(nm)];
 }
 export function send(name, text, o = {}) {
@@ -979,7 +1031,29 @@ export function listSessions() {
     }
     return "(セッション無し)";
 }
-export function closeSession(name) {
+/**
+ * `pty_list` 相当を read-only に照会し、内容を返さず session 件数だけを返す。
+ * session 名・前面コマンド・PTY 出力を診断応答へ持ち出さないため、factory が安全に readiness を
+ * 見られる。socket 不在は「セッション未設定」であって障害ではない。
+ */
+export function readOnlyPtyListDiagnostic() {
+    try {
+        const r = tmux("list-sessions", "-F", "#{session_name}");
+        if (r.code === 0) {
+            return { status: "ready", session_count: r.stdout.split(/\r?\n/).filter(Boolean).length };
+        }
+        // tmux は専用 socket に server がいない通常状態を exit 1 で返す。その他の失敗を「空」と
+        // 偽装しないため、メッセージを公開せず unverified に留める。
+        if (/no server running|failed to connect/i.test(r.stderr)) {
+            return { status: "not_applicable", session_count: 0 };
+        }
+    }
+    catch {
+        // tmux 未導入・WSL bridge 不全等。絶対 path や生 stderr を診断 JSON に出さない。
+    }
+    return { status: "unverified", session_count: null };
+}
+function closeSessionInternal(name, observeDependency = true) {
     assertSessionName(name);
     if (agentWaitLocks.has(name)) {
         throw new AitermError(`agent session '${name}' は agent_done 待機中のため close できません`, 2);
@@ -992,7 +1066,7 @@ export function closeSession(name) {
             throw new AitermError(`agent session '${name}' は別プロセス${d.pid != null ? `（pid ${d.pid}）` : ""}の agent_done 待機中のため close できません`, 2);
         }
     }
-    tmux("kill-session", "-t", name);
+    (observeDependency ? tmux : tmuxCleanup)("kill-session", "-t", name);
     for (const p of [logpath(name), offsetpath(name), lastcmdpath(name), markpath(name)]) {
         try {
             fs.unlinkSync(p);
@@ -1004,6 +1078,9 @@ export function closeSession(name) {
     cleanupAgentState(name);
     return `closed ${name}`;
 }
+export function closeSession(name) {
+    return closeSessionInternal(name, true);
+}
 export function killAll() {
     if (agentWaitLocks.size > 0) {
         throw new AitermError(`agent_done 待機中の session があるため killAll できません: ${Array.from(agentWaitLocks).join(",")}`, 2);
@@ -2288,21 +2365,46 @@ function resolveAgentBin(kind) {
         // 明示指定 env は実在を検証する。存在しないパスを黙って返すと、session を作って
         // `'/typo' ...` を送信し bash が command not found を出すだけで openAgent は「起動した」と
         // 偽成功を返す（既定パス/PATH 経路は検証するのに env だけ無検証だった非対称の解消・A3）。
-        if (fs.existsSync(fromEnv))
+        if (isUsableExecutableFile(fromEnv))
             return fromEnv;
         throw new AitermError(`${envVar} に指定された ${name} が存在しません: ${fromEnv}`, 2);
     }
     const cand = path.join(home, ...rel);
-    if (fs.existsSync(cand))
+    if (isUsableExecutableFile(cand))
         return cand;
     const w = spawnSync(isWin ? "where" : "which", [name], {
         encoding: "utf8",
         timeout: 5000,
     });
-    if (w.status === 0 && (w.stdout ?? "").trim())
-        return w.stdout.trim().split(/\r?\n/)[0];
+    if (w.status === 0 && (w.stdout ?? "").trim()) {
+        const resolved = w.stdout.trim().split(/\r?\n/)[0];
+        if (isUsableExecutableFile(resolved))
+            return resolved;
+    }
     return null;
 }
+function isUsableExecutableFile(candidate) {
+    try {
+        if (!fs.statSync(candidate).isFile())
+            return false;
+        if (isWin)
+            return /\.(?:exe|cmd|bat|com)$/i.test(candidate);
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** vendor CLI の存在だけを安全に要約する。認証状態・実行出力・解決先 path は返さない。 */
+export function vendorLauncherDiagnostic(kind) {
+    try {
+        return resolveAgentBin(kind) ? "ready" : "not_applicable";
+    }
+    catch {
+        return "unverified";
+    }
+}
 // 単一引用符で安全に包む（' は '\'' で脱出）。send は raw:true で送るため自前で quote する。
 function shq(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
@@ -2427,10 +2529,16 @@ export function openAgent(kind, opts = {}) {
             "（モデルカタログ supports_reasoning_effort=false）", 2);
     }
     const agentDone = !!opts.agent_done;
-    const bin = resolveAgentBin(kind);
+    let bin;
+    try {
+        bin = resolveAgentBin(kind);
+    }
+    catch (error) {
+        ownTelemetryFailure("AITERM.VENDOR_LAUNCHER_FAILED", error, 2);
+    }
     if (!bin) {
         const where = kind === "codex" ? "~/.local/bin/codex" : "~/.grok/bin/grok";
-        throw new AitermError(`${label} の CLI が見つかりません（${where} か PATH が必要）`, 2);
+        ownTelemetryFailure("AITERM.VENDOR_LAUNCHER_FAILED", new AitermError(`${label} の CLI が見つかりません（${where} か PATH が必要）`, 2), 2);
     }
     // cwd 検証（session を作る前に。cd 失敗はシェル内で静かに死に「起動した」と偽成功を返すため）。
     let cwd = null;
@@ -2481,14 +2589,15 @@ export function openAgent(kind, opts = {}) {
         send(sid, full, { enter: true, mark: false, force: true, rtk: false, raw: true });
     }
     catch (e) {
+        const failure = telemetryOwnedFailure("AITERM.VENDOR_LAUNCHER_FAILED", e);
         // 起動コマンドを投入できなかった session は空のまま残る＝残骸を作らない。片付けてから元エラーを伝える。
         try {
-            closeSession(sid);
+            closeSessionInternal(sid, false);
         }
         catch {
             /* 片付け失敗より元エラーの伝達を優先 */
         }
-        throw e;
+        throw failure;
     }
     return [
         sid,

package/dist/index.js

@@ -12,6 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import * as core from "./core.js";
+import { runtimeErrorStoreDiagnostic } from "./runtime-error-store.js";
 import { createRequire } from "node:module";
 // package.json の version を実行時に読み、MCP initialize で配るサーバ版と一致させる。
 // createRequire を使うのは、import 属性 `with { type: "json" }` が Node 18.20+ 限定で
@@ -26,6 +27,41 @@ function fail(e) {
     const msg = e instanceof Error ? e.message : String(e);
     return { content: [{ type: "text", text: "aiterm: " + msg }], isError: true };
 }
+/**
+ * Factory 向けの read-only 診断。JSON の field は意図的に allowlist 制で、絶対 path、環境変数、
+ * token、コマンド本文、PTY 出力、raw log、認証状態を公開しない。
+ */
+async function factoryDiagnostics() {
+    const ptyList = core.readOnlyPtyListDiagnostic();
+    const codex = core.vendorLauncherDiagnostic("codex");
+    const grok = core.vendorLauncherDiagnostic("grok");
+    const runtimeErrors = await runtimeErrorStoreDiagnostic();
+    const overall = ptyList.status === "unverified" || runtimeErrors.status === "unverified" ? "unverified" : "ready";
+    return JSON.stringify({
+        diagnostic_schema: "aiterm-mcp.factory-diagnostics.v1",
+        version: pkg.version,
+        overall,
+        mcp: { transport: "stdio", initialize: "ready", tool_call: "ready" },
+        pty_list: { access: "read_only", ...ptyList },
+        runtime_error_store: runtimeErrors,
+        vendor_dependencies: {
+            codex: {
+                status: codex,
+                optional: true,
+                required_for: ["codex_agent"],
+            },
+            grok: {
+                status: grok,
+                optional: true,
+                required_for: ["grok_agent", "composer_agent"],
+            },
+        },
+    });
+}
+server.registerTool("diagnostics", {
+    description: "Factory 向け read-only 診断。安全な状態語彙だけを機械可読 JSON で返す（PTY 内容・認証情報・path・環境値は返さない）。",
+    inputSchema: {},
+}, async () => ok(await factoryDiagnostics()));
 server.registerTool("pty_open", {
     description: "ローカル永続端末(tmux セッション)を1個開き、session_id を返す。tmux サーバ常駐ゆえ本サーバや " +
         "クライアントが再起動してもセッションは生存する。リモート操作は専用ツールにせず、開いた端末の中で " +