aiterm-mcp 0.4.1 → 0.8.0

package/dist/core.js

@@ -5,13 +5,13 @@
  * トークン削減して受け取る。SSH/docker は専用機能にせず send(id, "ssh host") で中に入る（ネスト）。
  * セッションは tmux サーバ常駐ゆえ、本プロセスが毎回終了しても次回 read で再接続できる。
  *
- * 設計: docs/ai-terminal-design-plan.md / docs/mcp-server-plan.md。出力削減は rag/ の RTK を移植。
+ * 設計: docs/01_design-plan.md / docs/02_mcp-plan.md。出力削減は rag/ の RTK を移植。
  */
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import * as rtk from "./rtk.js";
 // Windows ネイティブには tmux が無い。その場合だけ全 tmux 呼び出しを WSL 経由へ橋渡しする
 // （POSIX = Linux/WSL2/macOS は従来どおり tmux を直接叩く）。
@@ -31,14 +31,26 @@ export const DEFAULT_TIMEOUT = 10.0;
 const POLL = 0.25;
 const STABLE_POLLS = 2; // 連続でログサイズ不変ならば静止とみなす回数
 const SHELLS = new Set(["bash", "sh", "zsh", "fish", "dash"]);
+// mark の sentinel は POSIX シェル構文（; と "$?"）に依存する。これらの非 POSIX 対話シェルが
+// 前面のときは "$?" が正しく展開されず sentinel が壊れるので mark を拒否する（B8）。ssh/docker で
+// リモート POSIX シェルに入っている場合は前面が "ssh"/"docker" 等で本集合に含まれず＝許可される。
+const NON_POSIX_MARK_SHELLS = new Set(["fish", "csh", "tcsh"]);
+// mark:true が付ける完了 sentinel の検出正規表現。printf の実出力は rc=<数字>、コマンド行の
+// エコーは rc=%d(リテラル)。数字アンカーでエコーに免疫化し、部分一致による早期誤完了を防ぐ（B1）。
+// send の printf 書式（`rc=%d`）と対で保守すること。
+const MARK_DONE_RE = /<<<AITERM_DONE rc=[0-9]+>>>/;
 // 出力削減（RTK の CAP 思想を移植）
 const MAX_LINES_BEFORE_ELIDE = 60;
 const HEAD_LINES = 30;
 const TAIL_LINES = 20;
 const DEDUP_MIN_RUN = 3; // 同一行がこれ以上連続したら 1 行＋件数に畳む
+const MAX_FULL_BYTES = 8 * 1024 * 1024; // full/range 読取で一度にメモリへ載せる上限（B7）
 // 安全: send 前に弾く破壊的コマンド（外部システム境界の防御）
 const DESTRUCTIVE = [
-    /\brm\s+-[rfRF]*[rf][rfRF]*\s+(\/|~|\$HOME|\/\*|\.\s*$|\*\s*$)/i,
+    // rm -rf の危険な対象形（best-effort・force で越えられる）。先頭の任意クオート ['"]? で
+    // `rm -rf "/"` / `'/'` / `"~"` を捕捉。`\.\/\*`=./*（相対 glob）、`\.\.?\/?\s*$`=. / .. / ./ / ../
+    // （カレント/親そのもの）。`./build` 等の相対サブディレクトリは末尾でないので非該当（過剰ブロック回避）。
+    /\brm\s+-[rfRF]*[rf][rfRF]*\s+['"]?(\/|~|\$HOME|\.\/\*|\.\.?\/?\s*$|\*\s*$)/i,
     /\bmkfs(\.\w+)?\b/i,
     /\bdd\b[^\n]*\bof=\/dev\//i,
     />\s*\/dev\/(sd|nvme|hd|mmcblk)/i,
@@ -50,7 +62,8 @@ const DESTRUCTIVE = [
     /\bgit\s+reset\s+--hard\b/i,
 ];
 // CSI/OSC/ESC エスケープ・制御文字
-const ANSI_RE = /\x1b\[[0-9;?]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-_]/g;
+// CSI / OSC(BEL or ST 終端) / DCS・PM・APC・SOS(ESC P/^/_/X … BEL or ST 終端。ペイロード本文ごと除去=B10) / 残る2文字エスケープ
+const ANSI_RE = /\x1b\[[0-9;?]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[P^_X][\s\S]*?(?:\x07|\x1b\\)|\x1b[@-_]/g;
 const CTRL_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g; // \t(09) \n(0a) は残す
 const PASTE_MARKERS_RE = /\x1b\[20[01]~/g;
 // よく使う制御キーの別名（tmux のキー名へ）
@@ -189,6 +202,10 @@ function offsetpath(name) {
 function lastcmdpath(name) {
     return path.join(SOCKDIR, name + ".lastcmd");
 }
+// mark:true 送信中フラグ。存在すれば waitCompletion が sentinel 完了検出（MARK_DONE_RE）を有効化する。
+function markpath(name) {
+    return path.join(SOCKDIR, name + ".mark");
+}
 function readOffset(name) {
     try {
         const n = parseInt(fs.readFileSync(offsetpath(name), "utf8").trim(), 10);
@@ -305,6 +322,11 @@ function autoName() {
         i++;
     return `t${i}`;
 }
+// 衝突リトライ用の乱数名。線形 t{i} は高並行だと全員が同じ「最小の空き番号」を見て衝突し続ける
+// （TOCTOU）ため、2回目以降は 1600万通りの nonce 名に切り替えてリトライ上限内で実質確実に確保する。
+function nonceName() {
+    return `t-${randomBytes(3).toString("hex")}`;
+}
 function captureScreen(name, lines) {
     const args = ["capture-pane", "-p", "-J", "-t", name];
     if (lines)
@@ -332,16 +354,35 @@ async function settleWinLog(name) {
         await sleep(POLL * 1000);
     }
 }
-/** 完了境界: dead / until 一致 / (出力静止 ∧ シェル復帰)=quiescent / (ネスト中＋until無しで出力静止)=nested(未確定・早期返却) / timeout。 */
-async function waitCompletion(name, untilRe, timeout) {
+/** 完了境界: dead / mark sentinel 一致 / until 一致 / (出力静止 ∧ シェル復帰)=quiescent / (ネスト中＋until/mark無しで出力静止)=nested(未確定・早期返却) / timeout。 */
+async function waitCompletion(name, untilStr, untilRegex, timeout) {
     // 締切は単調時計で測る。Date.now() は NTP 補正やサスペンドで巻き戻り、長時間待ちで誤判定する（Python は time.monotonic）。
     const deadline = performance.now() + timeout * 1000;
     const start = readOffset(name);
     let lastSize = null;
     let stable = 0;
-    const until = untilRe ? new RegExp(untilRe) : null;
+    // until は既定でリテラル部分一致（`$ ` や `[sudo]` 等がメタ化して永遠に待つ footgun を避ける・B4）。
+    // untilRegex:true のときだけ正規表現として解釈し、不正パターンは明示エラーにする（B13 の until 部分）。
+    let until = null;
+    if (untilStr) {
+        if (untilRegex) {
+            let re;
+            try {
+                re = new RegExp(untilStr);
+            }
+            catch (e) {
+                throw new AitermError(`until 正規表現が不正です: ${JSON.stringify(untilStr)}（${e.message}）`, 2);
+            }
+            until = (s) => re.test(s);
+        }
+        else {
+            until = (s) => s.includes(untilStr);
+        }
+    }
+    // mark:true 送信中なら sentinel 完了検出を有効化する。エコー（rc=%d）でなく実出力（rc=<数字>）だけに
+    // 一致する数字アンカー MARK_DONE_RE を使うため、until のようにエコー部分一致で早期誤完了しない（B1）。
+    const markActive = fs.existsSync(markpath(name));
     for (;;) {
-        const alive = sessionExists(name);
         let size = 0;
         try {
             size = fs.statSync(logpath(name)).size;
@@ -349,13 +390,49 @@ async function waitCompletion(name, untilRe, timeout) {
         catch {
             size = 0;
         }
-        if (until && size > start) {
-            const buf = fs.readFileSync(logpath(name));
-            const neu = buf.subarray(start).toString("utf8");
-            if (until.test(stripControl(neu)))
+        if ((until || markActive) && size > start) {
+            // 増分 [start, size] だけを fd で読む（毎 poll で全ファイルを読む O(n^2) を避ける・B6）。
+            let neu = "";
+            let fd;
+            try {
+                fd = fs.openSync(logpath(name), "r");
+                const len = size - start;
+                const buf = Buffer.alloc(len);
+                const n = fs.readSync(fd, buf, 0, len, start);
+                neu = stripControl(buf.subarray(0, Math.max(0, n)).toString("utf8"));
+            }
+            catch {
+                neu = ""; // close 等でログが消えた: 次周回の !alive/statSync で決着させる
+            }
+            finally {
+                if (fd !== undefined) {
+                    try {
+                        fs.closeSync(fd);
+                    }
+                    catch {
+                        /* noop */
+                    }
+                }
+            }
+            // mark を until より先に判定（sentinel は確証つき完了。until はユーザ指定でエコー誤爆余地あり）。
+            if (markActive && MARK_DONE_RE.test(neu)) {
+                try {
+                    fs.unlinkSync(markpath(name)); // 同一 sentinel での再発火を防ぐ
+                }
+                catch {
+                    /* noop */
+                }
+                if (isWin)
+                    await settleWinLog(name);
+                return [true, "mark"];
+            }
+            if (until && until(neu))
                 return [true, "until"];
         }
-        if (!alive) {
+        // 出力が伸びている間は生存確認(tmux has-session の spawn)を省く＝伸長は生存の証（B6）。
+        // 静止時のみ has-session を叩いて dead を判定する。dead 検出は最大 1 poll 遅れるだけ。
+        const growing = lastSize !== null && size > lastSize;
+        if (!growing && !sessionExists(name)) {
             if (isWin)
                 await settleWinLog(name);
             return [true, "dead"];
@@ -370,10 +447,11 @@ async function waitCompletion(name, untilRe, timeout) {
                     return [true, "quiescent"]; // 出力静止 ∧ シェル復帰 ＝ 確証つき完了
                 }
                 // ネスト中（前面が ssh/docker/REPL 等でシェル集合外）は quiescence の「シェル復帰」条件を
-                // 原理的に満たせない。until 未指定ならこれ以上待っても確証は増えない（until/dead/quiescent の
-                // いずれも発火し得ない）ので、出力が静止した時点で「未確定」のまま早期返却し until/mark を促す。
+                // 原理的に満たせない。until も mark も無ければこれ以上待っても確証は増えない（until/dead/
+                // quiescent/mark のいずれも発火し得ない）ので、出力静止時点で「未確定」のまま早期返却する。
+                // markActive のときは sentinel を待つべく早期返却せず、非シェル前面（sleep 等）でも待ち続ける。
                 // fg==="" は前面コマンド取得失敗＝ネスト断定不可なので早期返却せず従来どおり timeout まで待つ。
-                if (!until && fg !== "") {
+                if (!until && !markActive && fg !== "") {
                     if (isWin)
                         await settleWinLog(name);
                     return [false, "nested"];
@@ -389,10 +467,10 @@ async function waitCompletion(name, untilRe, timeout) {
         await sleep(POLL * 1000);
     }
 }
-// 完了ステータス → is_complete 表記。確証のある層のみ True（until/dead/quiescent）。
+// 完了ステータス → is_complete 表記。確証のある層のみ True（mark/until/dead/quiescent）。
 // timeout と nested（ネスト中・出力静止だが確証なし）は False。nested は until/mark を促す注記を添える。
 function completionSuffix(status) {
-    const complete = status === "until" || status === "dead" || status === "quiescent";
+    const complete = status === "mark" || status === "until" || status === "dead" || status === "quiescent";
     let s = ` [is_complete=${complete ? "True" : "False"} via ${status}]`;
     if (status === "nested")
         s +=
@@ -417,26 +495,66 @@ function rtkRewrite(text) {
 // ---------------------------------------------------------------- 操作（return で返す / 失敗は AitermError）
 export function openSession(name, shell = "bash") {
     fs.mkdirSync(SOCKDIR, { recursive: true });
-    const nm = name || autoName();
-    assertSessionName(nm);
-    if (sessionExists(nm))
-        throw new AitermError(`session '${nm}' は既に存在します（list で確認）`, 2);
     // 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 限定にする。）
     const banner = process.platform === "darwin" && path.basename(shell) === "bash"
         ? ["-e", "BASH_SILENCE_DEPRECATION_WARNING=1"]
         : [];
-    const r = tmux("new-session", "-d", "-s", nm, ...banner, "-f", "/dev/null", shell);
-    if (r.code !== 0)
-        throw new AitermError("tmux new-session 失敗: " + r.stderr.trim(), 2);
-    fs.closeSync(fs.openSync(logpath(nm), "a")); // touch
+    // 並行性対策: 複数エージェントが同時に名前なし open すると autoName が同じ t{i} を返し得る（TOCTOU）。
+    // 自動採番は初回のみ読みやすい t{i}、衝突したら乱数 nonce 名でリトライする（線形リトライは高並行で
+    // 全員が同じ空き番号に殺到してスケールしない）。明示名は既存ならエラー（呼び手責任＝意図的共有と区別）。
+    const explicit = !!name;
+    let nm = name || autoName();
+    assertSessionName(nm);
+    for (let attempt = 0;; attempt++) {
+        if (attempt >= 20)
+            throw new AitermError("openSession: 自動採番のリトライ上限（tmux new-session が重複以外で失敗し続けている可能性）", 2);
+        if (sessionExists(nm)) {
+            if (explicit)
+                throw new AitermError(`session '${nm}' は既に存在します（list で確認）`, 2);
+        }
+        else {
+            const r = tmux("new-session", "-d", "-s", nm, ...banner, "-f", "/dev/null", shell);
+            if (r.code === 0)
+                break;
+            // 自動採番かつ「重複名」由来の失敗（他エージェントが同名を先に取った）なら次名でリトライ。
+            const dup = /duplicate|already exists/i.test(r.stderr);
+            if (explicit || !dup)
+                throw new AitermError("tmux new-session 失敗: " + r.stderr.trim(), 2);
+        }
+        nm = nonceName();
+        assertSessionName(nm);
+    }
+    // 新規セッションの .log は必ず truncate する。"a"（追記）だと外部 kill / killAll / クラッシュで
+    // 同名 session だけ消えて .log が残った場合、offset=0 と相まって旧出力を新規として返す（B5）。
+    // break は new-session 成功後にのみ到達＝作りたての空 session ゆえ切り詰めは安全。lastcmd/mark 残骸も掃除。
+    fs.writeFileSync(logpath(nm), "");
+    for (const p of [lastcmdpath(nm), markpath(nm)]) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            /* noop */
+        }
+    }
     // pipe-pane の引数は tmux 内部の /bin/sh -c で再解釈される（argv ではない）。パスは単一引用符で包み、
     // パス自身の ' は '\'' イディオムでエスケープする（名前は検証済みだが、Windows ユーザー名 O'Brien 等が
     // 一時パスに ' を持ち込み redirect を壊すのを防ぐ。空白対策も兼ねる）。Windows は WSL から見える /mnt/c 形へ。
     const pipeTarget = isWin ? toWslPath(logpath(nm)) : logpath(nm);
     const quoted = `'${pipeTarget.replace(/'/g, "'\\''")}'`;
-    tmux("pipe-pane", "-t", nm, "-o", `cat >> ${quoted}`);
+    const pr = tmux("pipe-pane", "-t", nm, "-o", `cat >> ${quoted}`);
+    if (pr.code !== 0) {
+        // 配管に失敗した session は pty_read が永遠に空を返す＝成功を装わない。作った session を片付けて明示エラー。
+        tmux("kill-session", "-t", nm);
+        try {
+            fs.unlinkSync(logpath(nm)); // B14: 直前に作った空 .log も残さない
+        }
+        catch {
+            /* noop */
+        }
+        throw new AitermError("tmux pipe-pane 失敗（出力ログを配管できないため session を破棄）: " + pr.stderr.trim(), 2);
+    }
     writeOffset(nm, 0);
     return [nm, attachHint(nm)];
 }
@@ -456,11 +574,37 @@ export function send(name, text, o = {}) {
             }
         }
     }
+    if (o.mark) {
+        // mark の sentinel は POSIX シェル構文。前面が fish/csh/tcsh 等の非 POSIX 対話シェルだと "$?" が
+        // 壊れて sentinel が成立しない。黙って壊れた完了検出を作らず、明示エラーで until を促す（B8）。
+        const fg = paneCurrentCommand(name);
+        if (NON_POSIX_MARK_SHELLS.has(fg)) {
+            throw new AitermError(`mark は POSIX シェル(bash/sh/zsh/dash)前提です。前面が ${fg} のため sentinel の "$?" が` +
+                `正しく展開されません。until で完了パターンを指定してください。`, 2);
+        }
+    }
     writeLastcmd(name, text); // read rtk の reducer 分類用（書換/mark 前の素のコマンド）
     if (o.rtk)
         text = rtkRewrite(text);
-    if (o.mark)
+    if (o.mark) {
+        // 実出力は rc=<数字>、この行のエコーは rc=%d(リテラル)。MARK_DONE_RE は数字アンカーで後者に免疫。
         text = text + `; printf '\\n<<<AITERM_DONE rc=%d>>>\\n' "$?"`;
+        try {
+            fs.writeFileSync(markpath(name), "1"); // waitCompletion に sentinel 完了検出を有効化させる
+        }
+        catch {
+            /* noop（フラグ書けなくても until/quiescence 経路は生きる） */
+        }
+    }
+    else {
+        // 非 mark 送信は、未消化の古い mark 完了待ちを無効化する（前コマンドの sentinel を待ち続けない）。
+        try {
+            fs.unlinkSync(markpath(name));
+        }
+        catch {
+            /* noop */
+        }
+    }
     tmux("send-keys", "-t", name, "-l", "--", text);
     if (enter)
         tmux("send-keys", "-t", name, "Enter");
@@ -475,50 +619,121 @@ export function sendKey(name, key) {
     tmux("send-keys", "-t", name, k);
     return `sent key ${k} to ${name}`;
 }
+// end 以下で最大の UTF-8 文字境界を返す（B3）。末尾が不完全なマルチバイト列なら、その開始位置まで
+// 戻す。pipe-pane が多バイト文字の途中でフラッシュした瞬間の増分読みで先頭/末尾が U+FFFD 化するのを防ぐ。
+export function utf8SafeEnd(buf, end) {
+    if (end <= 0)
+        return 0;
+    const isCont = (b) => (b & 0xc0) === 0x80; // 継続バイト 10xxxxxx
+    let i = end - 1;
+    let steps = 0;
+    while (i >= 0 && isCont(buf[i]) && steps < 3) {
+        i--;
+        steps++;
+    }
+    if (i < 0)
+        return end; // 継続バイトのみの異常列: そのまま
+    const lead = buf[i];
+    let need;
+    if (lead < 0x80)
+        need = 1;
+    else if ((lead & 0xe0) === 0xc0)
+        need = 2;
+    else if ((lead & 0xf0) === 0xe0)
+        need = 3;
+    else if ((lead & 0xf8) === 0xf0)
+        need = 4;
+    else
+        return end; // 不正な先行バイト: そのまま（stripControl 等に委ねる）
+    return end - i >= need ? end : i; // 末尾文字が完結していれば end、不完全なら開始位置まで戻す
+}
 export async function readOutput(name, o = {}) {
     assertSessionName(name);
     const timeout = o.timeout ?? DEFAULT_TIMEOUT;
     if (!sessionExists(name) && !fs.existsSync(logpath(name)))
         throw new AitermError(`session '${name}' が無い`, 2);
+    // wait は screen より先に処理する。従来 screen は wait ブロックの手前で return し、screen+wait で
+    // 完了検出が黙殺されていた（B11）。先に待ってから最終スクリーンを撮る＝TUI の描画完了後に読める。
+    let status = null;
+    if (o.wait) {
+        const [, st] = await waitCompletion(name, o.until ?? null, o.untilRegex ?? false, timeout);
+        status = st;
+    }
     if (o.screen) {
         const rawTxt = captureScreen(name, o.lines || 0);
         if (o.raw)
             return rawTxt;
         const [body, meta] = reduceOutput(rawTxt, name, true);
-        return body + "\n" + meta;
+        return body + "\n" + meta + (status ? completionSuffix(status) : "");
     }
-    let status = null;
-    if (o.wait) {
-        const [, st] = await waitCompletion(name, o.until ?? null, timeout);
-        status = st;
-    }
-    let data;
+    // ログ全体を毎回メモリに載せず、必要な範囲だけ fd で読む（B7）。size は statSync で取る。
+    let size = 0;
     try {
-        data = fs.readFileSync(logpath(name));
+        size = fs.statSync(logpath(name)).size;
     }
     catch {
-        data = Buffer.alloc(0);
+        size = 0;
     }
+    const readRange = (from, to) => {
+        const len = Math.max(0, to - from);
+        if (len === 0)
+            return Buffer.alloc(0);
+        let fd;
+        try {
+            fd = fs.openSync(logpath(name), "r");
+            const buf = Buffer.alloc(len);
+            const n = fs.readSync(fd, buf, 0, len, from);
+            return n === len ? buf : buf.subarray(0, Math.max(0, n));
+        }
+        catch {
+            return Buffer.alloc(0);
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    /* noop */
+                }
+            }
+        }
+    };
     let text;
+    let nextOffset = size; // 既定/full は offset を末尾へ
     if (o.full || o.range) {
-        text = data.toString("utf8");
+        // full/range は全体が対象だが、巨大ログは末尾 MAX_FULL_BYTES に制限してメモリを守る（B7）。
+        let from = 0;
+        if (size > MAX_FULL_BYTES)
+            from = size - MAX_FULL_BYTES;
+        text = readRange(from, size).toString("utf8");
+        if (from > 0)
+            text = `[… 先頭 ${from} バイトを省略（ログがサイズ上限を超過。close で破棄されます）…]\n` + text;
         if (o.range) {
             const [lo, hi] = o.range;
             text = text.split("\n").slice(lo, hi ?? undefined).join("\n");
         }
+        else if (o.lines) {
+            // full + lines は末尾 N 行にする（従来は full 経路で lines を黙殺していた footgun・B11）。
+            text = text.split("\n").slice(-o.lines).join("\n");
+        }
     }
     else {
         let off = readOffset(name);
         // WSL 再起動等でログが作り直されると、Windows 側に残った旧 offset が新ログ長を超え、
-        // subarray が空を返して「何も読めない」状態になる。末尾越えは先頭から読み直す（POSIX では no-op）。
-        if (off > data.length)
+        // 空を返して「何も読めない」状態になる。末尾越えは先頭から読み直す（POSIX では no-op）。
+        if (off > size)
             off = 0;
-        text = data.subarray(off).toString("utf8");
+        const buf = readRange(off, size); // 増分のみをメモリに載せる
+        // 末尾の不完全マルチバイト列は次回へ持ち越す（B3）。off は前回この分岐が safeEnd を書くので先頭は割れない。
+        const safeLen = utf8SafeEnd(buf, buf.length);
+        text = buf.subarray(0, safeLen).toString("utf8");
+        nextOffset = off + safeLen;
         if (o.lines)
             text = text.split("\n").slice(-o.lines).join("\n");
     }
     if (!o.range)
-        writeOffset(name, data.length); // 既定/full は offset を末尾へ
+        writeOffset(name, nextOffset);
     if (o.raw)
         return text.endsWith("\n") ? text : text + "\n";
     if (o.rtk) {
@@ -550,7 +765,7 @@ export function listSessions() {
 export function closeSession(name) {
     assertSessionName(name);
     tmux("kill-session", "-t", name);
-    for (const p of [logpath(name), offsetpath(name), lastcmdpath(name)]) {
+    for (const p of [logpath(name), offsetpath(name), lastcmdpath(name), markpath(name)]) {
         try {
             fs.unlinkSync(p);
         }
@@ -562,5 +777,145 @@ export function closeSession(name) {
 }
 export function killAll() {
     tmux("kill-server");
+    // B9: SOCKDIR 内の .log/.offset/.lastcmd/.mark 残骸も掃除する（残すと B5 の stale-log 復活の温床）。
+    try {
+        for (const f of fs.readdirSync(SOCKDIR)) {
+            if (/\.(log|offset|lastcmd|mark)$/.test(f)) {
+                try {
+                    fs.unlinkSync(path.join(SOCKDIR, f));
+                }
+                catch {
+                    /* noop */
+                }
+            }
+        }
+    }
+    catch {
+        /* SOCKDIR 不在等は無視 */
+    }
     return "killed all sessions on this socket";
 }
+function resolveAgentBin(kind) {
+    const home = process.env.HOME ?? os.homedir();
+    const [envVar, rel, name] = kind === "codex"
+        ? ["CODEX_BIN", [".local", "bin", "codex"], "codex"]
+        : ["GROK_BIN", [".grok", "bin", "grok"], "grok"];
+    const fromEnv = process.env[envVar];
+    if (fromEnv) {
+        // 明示指定 env は実在を検証する。存在しないパスを黙って返すと、session を作って
+        // `'/typo' ...` を送信し bash が command not found を出すだけで openAgent は「起動した」と
+        // 偽成功を返す（既定パス/PATH 経路は検証するのに env だけ無検証だった非対称の解消・A3）。
+        if (fs.existsSync(fromEnv))
+            return fromEnv;
+        throw new AitermError(`${envVar} に指定された ${name} が存在しません: ${fromEnv}`, 2);
+    }
+    const cand = path.join(home, ...rel);
+    if (fs.existsSync(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];
+    return null;
+}
+// 単一引用符で安全に包む（' は '\'' で脱出）。send は raw:true で送るため自前で quote する。
+function shq(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function buildAgentCmd(kind, bin, effort, prompt) {
+    const parts = [shq(bin)];
+    if (kind === "codex") {
+        // codex は config override で reasoning effort（例: low/medium/high）を渡す。
+        if (effort)
+            parts.push("-c", `model_reasoning_effort=${shq(effort)}`);
+    }
+    else {
+        // grok / composer は同じ grok CLI をモデル違いで起動。effort は low/medium/high/xhigh/max。
+        parts.push("--model", kind === "composer" ? "grok-composer-2.5-fast" : "grok-build");
+        if (effort)
+            parts.push("--effort", shq(effort));
+    }
+    if (prompt)
+        parts.push(shq(prompt)); // 初手プロンプト（任意）
+    return parts.join(" ");
+}
+function agentLabel(kind) {
+    return kind === "composer"
+        ? "Grok Build(Composer)"
+        : kind === "grok"
+            ? "Grok Build(Grok)"
+            : "Codex";
+}
+// grok CLI の --effort が受ける値集合（codex は CLI 側の値集合が版で変わるため縛らない）。
+const GROK_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+export function openAgent(kind, opts = {}) {
+    const label = agentLabel(kind);
+    // 前提検証は session を作る前に全部済ませる（失敗の残骸 session を作らない）。
+    // effort → bin → cwd の順: effort 検証は CLI 不在の端末でも同じ結果になる（テスト可能性）。
+    const effort = opts.reasoning_effort ?? null;
+    if (effort && kind !== "codex" && !GROK_EFFORTS.has(effort)) {
+        throw new AitermError(`reasoning_effort '${effort}' は不正です（${label} は low/medium/high/xhigh/max）`, 2);
+    }
+    const bin = resolveAgentBin(kind);
+    if (!bin) {
+        const where = kind === "codex" ? "~/.local/bin/codex" : "~/.grok/bin/grok";
+        throw new AitermError(`${label} の CLI が見つかりません（${where} か PATH が必要）`, 2);
+    }
+    // cwd 検証（session を作る前に。cd 失敗はシェル内で静かに死に「起動した」と偽成功を返すため）。
+    let cwd = null;
+    if (opts.cwd != null) {
+        if (!opts.cwd.trim()) {
+            throw new AitermError("cwd が空文字です（省略するか有効なディレクトリを指定してください）", 2); // A6
+        }
+        if (opts.cwd.startsWith("~")) {
+            // statSync は ~ を展開しない。「存在しません」でなく展開されない旨を正直に伝える（A6）。
+            throw new AitermError(`cwd の ~ は展開されません。絶対パスで指定してください: ${opts.cwd}`, 2);
+        }
+        let st = null;
+        try {
+            st = fs.statSync(opts.cwd);
+        }
+        catch {
+            st = null;
+        }
+        if (!st || !st.isDirectory()) {
+            throw new AitermError(`cwd '${opts.cwd}' がディレクトリとして存在しません`, 2);
+        }
+        cwd = opts.cwd;
+    }
+    // Windows は起動コマンドが WSL 内 bash で走る（tmux ブリッジ）。bin/cwd を /mnt/c/... 形へ変換して
+    // 渡す（ログの toWslPath と対称・A1）。前提: Windows 側に CLI を導入（resolveAgentBin が Windows
+    // パスで解決）。toWslPath は session を作る前に呼ぶ＝変換失敗（非ドライブパス）で残骸 session を残さない。
+    // 未検証リスク: npm グローバル導入の codex.cmd/.bat シムや WSL interop 上の対話 TUI 描画は実 Windows
+    // でしか確認できない（CI 非対象。docs/03_audit-sweep-2026-07.md 参照）。
+    const binForCmd = isWin ? toWslPath(bin) : bin;
+    const cwdForCmd = cwd && isWin ? toWslPath(cwd) : cwd;
+    const [sid, hint] = openSession(opts.session_name ?? null, "bash");
+    const cmd = buildAgentCmd(kind, binForCmd, effort, opts.prompt ?? null);
+    const full = cwdForCmd ? `cd ${shq(cwdForCmd)} && ${cmd}` : cmd;
+    try {
+        // force:true で送る。起動骨格は `bin '...'` の固定形で、prompt/cwd/effort は shq でクオート済みの
+        // 引数＝シェルは決して破壊コマンドとして実行しない。破壊ゲート（生シェルコマンド想定）を prompt に
+        // 掛けるのは純誤検知で、`codex 'rm -rf / を説明して'` 等の正当な起動を塞いでしまう（A4）。
+        send(sid, full, { enter: true, mark: false, force: true, rtk: false, raw: true });
+    }
+    catch (e) {
+        // 起動コマンドを投入できなかった session は空のまま残る＝残骸を作らない。片付けてから元エラーを伝える。
+        try {
+            closeSession(sid);
+        }
+        catch {
+            /* 片付け失敗より元エラーの伝達を優先 */
+        }
+        throw e;
+    }
+    return [
+        sid,
+        `${label} を session ${sid} で起動した。\n${hint}\n` +
+            `TUI の描画には数秒かかる。少し置いてから pty_read(${sid}, screen:true) で画面を読み、` +
+            `pty_send(${sid}, "...") で入力・pty_key(${sid}, "Enter"/"Up"/"C-c" 等) で操作する（対話）。` +
+            `起動直後に増分 pty_read すると空/半描画になり得るので screen:true を使う。`,
+    ];
+}