aiterm-mcp 0.7.1 → 0.9.0

package/dist/core.js

@@ -5,13 +5,14 @@
  * トークン削減して受け取る。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, randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import * as rtk from "./rtk.js";
 // Windows ネイティブには tmux が無い。その場合だけ全 tmux 呼び出しを WSL 経由へ橋渡しする
 // （POSIX = Linux/WSL2/macOS は従来どおり tmux を直接叩く）。
@@ -31,14 +32,37 @@ 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]+>>>/;
+const LAUNCH_ID_RE = /^[0-9a-f]{32}$/;
+const AGENT_DONE_POLL_MS = 100;
+const AGENT_DONE_SETTLE_MIN_MS = 250;
+const AGENT_DONE_SCREEN_SETTLE_POLL_MS = 100;
+const AGENT_DONE_SCREEN_SETTLE_MAX_POLLS = 5;
+const AGENT_DONE_SCREEN_SETTLE_MIN_SAMPLES = 3;
+const AGENT_SUBMIT_DELAY_MS = 250;
+const AGENT_EVENT_MAX_BYTES = 1024 * 1024;
+const AGENT_TUI_READY_TIMEOUT_MS = 30_000;
+const AGENT_TUI_READY_POLL_MS = 500;
+const AGENT_TUI_READY_LINES = 45;
 // 出力削減（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 +74,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 のキー名へ）
@@ -180,6 +205,141 @@ function assertSessionName(name) {
     if (!/^[A-Za-z0-9_-]{1,64}$/.test(name))
         throw new AitermError(`session 名は英数字と _ - のみ・64文字以内にしてください: ${JSON.stringify(name)}`, 2);
 }
+function currentUid() {
+    if (typeof process.getuid !== "function") {
+        throw new AitermError("agent_done は POSIX/macOS/Linux のみ対応です（native Windows は未対応）", 2);
+    }
+    return process.getuid();
+}
+function runtimeStateBase() {
+    const xdg = process.env.XDG_RUNTIME_DIR;
+    if (xdg) {
+        try {
+            if (fs.statSync(xdg).isDirectory())
+                return xdg;
+        }
+        catch {
+            /* XDG_RUNTIME_DIR が壊れている CI/非 login 環境では os.tmpdir() に戻す */
+        }
+    }
+    return os.tmpdir();
+}
+function stateRoot() {
+    const uid = currentUid();
+    const base = runtimeStateBase();
+    return path.join(base, `aiterm-mcp-${uid}`);
+}
+function ensureSecureStateRoot() {
+    const root = stateRoot();
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(root);
+    if (!st.isDirectory() || st.isSymbolicLink()) {
+        throw new AitermError(`agent state root が安全な directory ではありません: ${root}`, 2);
+    }
+    if (st.uid !== currentUid()) {
+        throw new AitermError(`agent state root の owner が現在ユーザーではありません: ${root}`, 2);
+    }
+    if ((st.mode & 0o077) !== 0) {
+        fs.chmodSync(root, 0o700);
+    }
+    const agents = path.join(root, "agents");
+    fs.mkdirSync(agents, { recursive: true, mode: 0o700 });
+    const ast = fs.lstatSync(agents);
+    if (!ast.isDirectory() || ast.isSymbolicLink() || ast.uid !== currentUid()) {
+        throw new AitermError(`agent state dir が安全な directory ではありません: ${agents}`, 2);
+    }
+    if ((ast.mode & 0o077) !== 0)
+        fs.chmodSync(agents, 0o700);
+    return root;
+}
+function agentsDir() {
+    return path.join(ensureSecureStateRoot(), "agents");
+}
+function agentEventPath(name, launchId) {
+    assertSessionName(name);
+    if (!LAUNCH_ID_RE.test(launchId))
+        throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
+    return path.join(agentsDir(), `${name}.${launchId}.events.jsonl`);
+}
+function agentMetadataPath(name, launchId) {
+    assertSessionName(name);
+    if (!LAUNCH_ID_RE.test(launchId))
+        throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
+    return path.join(agentsDir(), `${name}.${launchId}.agent.json`);
+}
+function agentWaitLockPath(name, launchId) {
+    assertSessionName(name);
+    if (!LAUNCH_ID_RE.test(launchId))
+        throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
+    return path.join(agentsDir(), `${name}.${launchId}.wait.lock`);
+}
+function agentManagedCodexHomePath(name, launchId) {
+    assertSessionName(name);
+    if (!LAUNCH_ID_RE.test(launchId))
+        throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
+    return path.join(agentsDir(), `${name}.${launchId}.codex-home`);
+}
+function agentManagedGrokHomePath(name, launchId) {
+    assertSessionName(name);
+    if (!LAUNCH_ID_RE.test(launchId))
+        throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
+    return path.join(agentsDir(), `${name}.${launchId}.grok-home`);
+}
+function agentManagedGrokUserHomePath(name, launchId) {
+    assertSessionName(name);
+    if (!LAUNCH_ID_RE.test(launchId))
+        throw new AitermError(`launch_id が不正です: ${launchId}`, 2);
+    return path.join(agentsDir(), `${name}.${launchId}.home`);
+}
+function existingAgentsDir() {
+    if (typeof process.getuid !== "function")
+        return null;
+    const root = path.join(runtimeStateBase(), `aiterm-mcp-${process.getuid()}`);
+    const dir = path.join(root, "agents");
+    try {
+        const rst = fs.lstatSync(root);
+        if (!rst.isDirectory() || rst.isSymbolicLink() || rst.uid !== process.getuid())
+            return null;
+        if ((rst.mode & 0o077) !== 0)
+            fs.chmodSync(root, 0o700);
+        const st = fs.lstatSync(dir);
+        if (!st.isDirectory() || st.isSymbolicLink() || st.uid !== process.getuid())
+            return null;
+        if ((st.mode & 0o077) !== 0)
+            fs.chmodSync(dir, 0o700);
+        return dir;
+    }
+    catch {
+        return null;
+    }
+}
+function cleanupAgentState(name) {
+    assertSessionName(name);
+    const dir = existingAgentsDir();
+    if (!dir)
+        return;
+    const prefix = `${name}.`;
+    try {
+        for (const f of fs.readdirSync(dir)) {
+            if (!f.startsWith(prefix))
+                continue;
+            const p = path.join(dir, f);
+            try {
+                if (f.endsWith(".agent.json") || f.endsWith(".events.jsonl") || f.endsWith(".wait.lock"))
+                    fs.unlinkSync(p);
+                else if (f.endsWith(".codex-home") || f.endsWith(".grok-home") || f.endsWith(".home")) {
+                    fs.rmSync(p, { recursive: true, force: true });
+                }
+            }
+            catch {
+                /* stale agent state cleanup is best-effort */
+            }
+        }
+    }
+    catch {
+        /* stale agent state cleanup is best-effort */
+    }
+}
 function logpath(name) {
     return path.join(SOCKDIR, name + ".log");
 }
@@ -189,6 +349,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);
@@ -337,16 +501,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;
@@ -354,13 +537,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"];
@@ -375,10 +594,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"];
@@ -394,10 +614,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 +=
@@ -453,7 +673,19 @@ export function openSession(name, shell = "bash") {
         nm = nonceName();
         assertSessionName(nm);
     }
-    fs.closeSync(fs.openSync(logpath(nm), "a")); // touch
+    // 新規セッションの .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 */
+        }
+    }
+    cleanupAgentState(nm);
     // pipe-pane の引数は tmux 内部の /bin/sh -c で再解釈される（argv ではない）。パスは単一引用符で包み、
     // パス自身の ' は '\'' イディオムでエスケープする（名前は検証済みだが、Windows ユーザー名 O'Brien 等が
     // 一時パスに ' を持ち込み redirect を壊すのを防ぐ。空白対策も兼ねる）。Windows は WSL から見える /mnt/c 形へ。
@@ -463,6 +695,12 @@ export function openSession(name, shell = "bash") {
     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);
@@ -484,11 +722,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");
@@ -503,50 +767,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;
-    }
-    let status = null;
-    if (o.wait) {
-        const [, st] = await waitCompletion(name, o.until ?? null, timeout);
-        status = st;
+        return body + "\n" + meta + (status ? completionSuffix(status) : "");
     }
-    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) {
@@ -577,8 +912,11 @@ export function listSessions() {
 }
 export function closeSession(name) {
     assertSessionName(name);
+    if (agentWaitLocks.has(name)) {
+        throw new AitermError(`agent session '${name}' は agent_done 待機中のため close できません`, 2);
+    }
     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);
         }
@@ -586,20 +924,769 @@ export function closeSession(name) {
             /* noop */
         }
     }
+    cleanupAgentState(name);
     return `closed ${name}`;
 }
 export function killAll() {
+    if (agentWaitLocks.size > 0) {
+        throw new AitermError(`agent_done 待機中の session があるため killAll できません: ${Array.from(agentWaitLocks).join(",")}`, 2);
+    }
     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 不在等は無視 */
+    }
+    const adir = existingAgentsDir();
+    if (adir) {
+        try {
+            for (const f of fs.readdirSync(adir)) {
+                if (f.endsWith(".agent.json") ||
+                    f.endsWith(".events.jsonl") ||
+                    f.endsWith(".wait.lock") ||
+                    f.endsWith(".codex-home") ||
+                    f.endsWith(".grok-home") ||
+                    f.endsWith(".home")) {
+                    try {
+                        fs.rmSync(path.join(adir, f), { recursive: true, force: true });
+                    }
+                    catch {
+                        /* noop */
+                    }
+                }
+            }
+        }
+        catch {
+            /* agent state dir 不在等は無視 */
+        }
+    }
     return "killed all sessions on this socket";
 }
+const DEFAULT_AGENT_DONE_TIMEOUT = 600;
+const agentWaitLocks = new Set();
+function codexHookScriptPath() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "codex-stop-hook.js");
+}
+function grokHookScriptPath() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "grok-stop-hook.js");
+}
+function safeStatSize(p) {
+    try {
+        return fs.statSync(p).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function readFileRange(p, from, to) {
+    const len = Math.max(0, to - from);
+    if (len === 0)
+        return Buffer.alloc(0);
+    let fd;
+    try {
+        fd = fs.openSync(p, "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 */
+            }
+        }
+    }
+}
+function writeJson0600(p, v) {
+    fs.writeFileSync(p, JSON.stringify(v, null, 2) + "\n", { mode: 0o600 });
+    try {
+        fs.chmodSync(p, 0o600);
+    }
+    catch {
+        /* noop */
+    }
+}
+function writeText0600(p, text) {
+    fs.writeFileSync(p, text, { mode: 0o600 });
+    try {
+        fs.chmodSync(p, 0o600);
+    }
+    catch {
+        /* noop */
+    }
+}
+function createEmpty0600NoFollow(p) {
+    const nofollow = fs.constants.O_NOFOLLOW ?? 0;
+    const fd = fs.openSync(p, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | nofollow, 0o600);
+    fs.closeSync(fd);
+}
+function realCodexHome() {
+    return process.env.CODEX_HOME || path.join(process.env.HOME ?? os.homedir(), ".codex");
+}
+function createManagedCodexHome(name, launchId) {
+    const srcHome = realCodexHome();
+    let srcSt;
+    try {
+        srcSt = fs.statSync(srcHome);
+    }
+    catch {
+        throw new AitermError(`Codex home が見つかりません: ${srcHome}`, 2);
+    }
+    if (!srcSt.isDirectory())
+        throw new AitermError(`Codex home が directory ではありません: ${srcHome}`, 2);
+    const managedHome = agentManagedCodexHomePath(name, launchId);
+    fs.mkdirSync(managedHome, { recursive: false, mode: 0o700 });
+    fs.chmodSync(managedHome, 0o700);
+    let authLinked = false;
+    for (const entry of fs.readdirSync(srcHome)) {
+        if (entry === "hooks.json" || entry.startsWith("hooks.json."))
+            continue;
+        const src = path.join(srcHome, entry);
+        const dst = path.join(managedHome, entry);
+        if (entry === "auth.json") {
+            const st = fs.statSync(src);
+            if (!st.isFile())
+                throw new AitermError(`Codex auth.json が通常ファイルではありません: ${src}`, 2);
+            fs.symlinkSync(src, dst);
+            authLinked = true;
+        }
+        else if (entry === "config.toml") {
+            const st = fs.statSync(src);
+            if (st.isFile()) {
+                fs.copyFileSync(src, dst);
+                fs.chmodSync(dst, 0o600);
+            }
+        }
+        else {
+            fs.symlinkSync(src, dst);
+        }
+    }
+    if (!authLinked)
+        throw new AitermError(`Codex auth.json が見つかりません。先に codex login が必要です: ${srcHome}`, 2);
+    const hookScript = codexHookScriptPath();
+    if (!fs.existsSync(hookScript)) {
+        throw new AitermError(`Codex Stop hook wrapper が見つかりません。npm run build を実行してください: ${hookScript}`, 2);
+    }
+    writeJson0600(path.join(managedHome, "hooks.json"), {
+        hooks: {
+            Stop: [
+                {
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `${shq(process.execPath)} ${shq(hookScript)}`,
+                            timeoutSec: 10,
+                            async: false,
+                            statusMessage: null,
+                        },
+                    ],
+                },
+            ],
+        },
+    });
+    return managedHome;
+}
+function realGrokHome() {
+    return process.env.GROK_HOME || path.join(process.env.HOME ?? os.homedir(), ".grok");
+}
+function validateGrokAuthLock(lockPath) {
+    let st;
+    try {
+        st = fs.lstatSync(lockPath);
+    }
+    catch (e) {
+        throw e;
+    }
+    if (st.isSymbolicLink())
+        throw new AitermError(`Grok auth lock が symlink です: ${lockPath}`, 2);
+    if (!st.isFile())
+        throw new AitermError(`Grok auth lock が通常ファイルではありません: ${lockPath}`, 2);
+    if (st.nlink !== 1)
+        throw new AitermError(`Grok auth lock が hard link です: ${lockPath}`, 2);
+    try {
+        fs.chmodSync(lockPath, 0o600);
+    }
+    catch {
+        /* lock file permission tightening is best-effort */
+    }
+}
+function ensureGrokAuthLock(srcHome) {
+    const lockPath = path.join(srcHome, "auth.json.lock");
+    try {
+        validateGrokAuthLock(lockPath);
+        return lockPath;
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    try {
+        createEmpty0600NoFollow(lockPath);
+    }
+    catch (e) {
+        if (e.code !== "EEXIST")
+            throw e;
+    }
+    validateGrokAuthLock(lockPath);
+    return lockPath;
+}
+function linkGrokOauthFiles(srcHome, grokHome) {
+    const srcAuth = path.join(srcHome, "auth.json");
+    let authExists = false;
+    try {
+        const authSt = fs.statSync(srcAuth);
+        if (!authSt.isFile())
+            throw new AitermError(`Grok auth.json が通常ファイルではありません: ${srcAuth}`, 2);
+        authExists = true;
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    if (!authExists) {
+        if (process.env.XAI_API_KEY)
+            return;
+        throw new AitermError(`Grok auth.json が見つかりません。先に grok login が必要です: ${srcHome}`, 2);
+    }
+    const srcLock = ensureGrokAuthLock(srcHome);
+    fs.symlinkSync(srcAuth, path.join(grokHome, "auth.json"));
+    fs.symlinkSync(srcLock, path.join(grokHome, "auth.json.lock"));
+}
+function writeManagedGrokConfig(grokHome) {
+    fs.mkdirSync(path.join(grokHome, "hooks"), { recursive: false, mode: 0o700 });
+    writeText0600(path.join(grokHome, "config.toml"), [
+        "[cli]",
+        "auto_update = false",
+        "",
+        "[features]",
+        "remote_fetch = false",
+        "managed_config = false",
+        "",
+        "[compat.claude]",
+        "skills = false",
+        "rules = false",
+        "agents = false",
+        "mcps = false",
+        "hooks = false",
+        "",
+        "[compat.cursor]",
+        "skills = false",
+        "rules = false",
+        "agents = false",
+        "mcps = false",
+        "hooks = false",
+        "",
+    ].join("\n"));
+}
+function createManagedGrokHome(name, launchId) {
+    const srcHome = realGrokHome();
+    let srcSt;
+    try {
+        srcSt = fs.statSync(srcHome);
+    }
+    catch {
+        throw new AitermError(`Grok home が見つかりません: ${srcHome}`, 2);
+    }
+    if (!srcSt.isDirectory())
+        throw new AitermError(`Grok home が directory ではありません: ${srcHome}`, 2);
+    const grokHome = agentManagedGrokHomePath(name, launchId);
+    const fakeHome = agentManagedGrokUserHomePath(name, launchId);
+    fs.mkdirSync(grokHome, { recursive: false, mode: 0o700 });
+    fs.mkdirSync(fakeHome, { recursive: false, mode: 0o700 });
+    fs.chmodSync(grokHome, 0o700);
+    fs.chmodSync(fakeHome, 0o700);
+    fs.symlinkSync(grokHome, path.join(fakeHome, ".grok"));
+    // OAuth refresh token rotation は auth.json だけでなく vendor lock と同じ実体を共有させる。
+    // per-launch GROK_HOME 隔離は維持し、通常 Grok home の hook/config/session は読ませない。
+    linkGrokOauthFiles(srcHome, grokHome);
+    const hookScript = grokHookScriptPath();
+    if (!fs.existsSync(hookScript)) {
+        throw new AitermError(`Grok Stop hook wrapper が見つかりません。npm run build を実行してください: ${hookScript}`, 2);
+    }
+    writeManagedGrokConfig(grokHome);
+    writeJson0600(path.join(grokHome, "hooks", "aiterm-stop.json"), {
+        hooks: {
+            Stop: [
+                {
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `${shq(process.execPath)} ${shq(hookScript)}`,
+                            timeout: 10,
+                        },
+                    ],
+                },
+            ],
+        },
+    });
+    // Grok 0.2.87 は compat false でも ~/.claude/plugins の hook file を拾う。HOME を一時化して
+    // plugin/hook source を完全に 0 にする。実 HOME は必要なら hook/agent 側で参照できるよう env で渡す。
+    return { grokHome, home: fakeHome };
+}
+function writeAgentMetadata(meta) {
+    writeJson0600(agentMetadataPath(meta.aiterm_session, meta.launch_id), meta);
+}
+function acquireAgentWaitFileLock(meta) {
+    const p = agentWaitLockPath(meta.aiterm_session, meta.launch_id);
+    const nofollow = fs.constants.O_NOFOLLOW ?? 0;
+    let fd;
+    try {
+        fd = fs.openSync(p, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | nofollow, 0o600);
+    }
+    catch (e) {
+        if (e.code === "EEXIST") {
+            throw new AitermError(`agent session '${meta.aiterm_session}' は別プロセスの agent_done 待機中です`, 2);
+        }
+        throw e;
+    }
+    try {
+        fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }) + "\n", undefined, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.chmodSync(p, 0o600);
+    }
+    catch {
+        /* noop */
+    }
+    return () => {
+        try {
+            const st = fs.lstatSync(p);
+            if (st.isFile() && !st.isSymbolicLink() && st.uid === currentUid())
+                fs.unlinkSync(p);
+        }
+        catch {
+            /* noop */
+        }
+    };
+}
+function createCodexAgentMetadata(name, cwd, initialPrompt) {
+    const launchId = randomBytes(16).toString("hex");
+    const eventFile = agentEventPath(name, launchId);
+    createEmpty0600NoFollow(eventFile);
+    const codexHome = createManagedCodexHome(name, launchId);
+    const meta = {
+        kind: "codex",
+        aiterm_session: name,
+        launch_id: launchId,
+        event_file: eventFile,
+        created_at: new Date().toISOString(),
+        cwd,
+        vendor_session_id: null,
+        initial_prompt: initialPrompt,
+        hook_route: "managed_codex_home",
+        node_platform: process.platform,
+        codex_home: codexHome,
+    };
+    writeAgentMetadata(meta);
+    return meta;
+}
+function createGrokAgentMetadata(kind, name, cwd, initialPrompt) {
+    const launchId = randomBytes(16).toString("hex");
+    const eventFile = agentEventPath(name, launchId);
+    createEmpty0600NoFollow(eventFile);
+    const managed = createManagedGrokHome(name, launchId);
+    const meta = {
+        kind,
+        aiterm_session: name,
+        launch_id: launchId,
+        event_file: eventFile,
+        created_at: new Date().toISOString(),
+        cwd,
+        vendor_session_id: null,
+        initial_prompt: initialPrompt,
+        hook_route: "managed_grok_home",
+        node_platform: process.platform,
+        grok_home: managed.grokHome,
+        home: managed.home,
+    };
+    writeAgentMetadata(meta);
+    return meta;
+}
+function loadAgentMetadata(name) {
+    assertSessionName(name);
+    const dir = agentsDir();
+    const files = fs
+        .readdirSync(dir)
+        .filter((f) => f.startsWith(`${name}.`) && f.endsWith(".agent.json"));
+    if (files.length === 0) {
+        throw new AitermError(`session '${name}' は agent_done 管理セッションではありません。codex_agent(agent_done:true) で起動してください。`, 2);
+    }
+    if (files.length !== 1) {
+        throw new AitermError(`session '${name}' の agent metadata が複数あります。閉じて起動し直してください。`, 2);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(path.join(dir, files[0]), "utf8"));
+    }
+    catch (e) {
+        throw new AitermError(`agent metadata を読めません: ${e.message}`, 2);
+    }
+    const m = raw;
+    if ((m.kind !== "codex" && m.kind !== "grok" && m.kind !== "composer") ||
+        m.aiterm_session !== name ||
+        typeof m.launch_id !== "string" ||
+        !LAUNCH_ID_RE.test(m.launch_id)) {
+        throw new AitermError(`agent metadata が不正です: ${files[0]}`, 2);
+    }
+    const expectedEvent = agentEventPath(name, m.launch_id);
+    if (m.event_file !== expectedEvent) {
+        throw new AitermError("agent metadata の path が現在の secure state root と一致しません", 2);
+    }
+    if (m.kind === "codex") {
+        const expectedHome = agentManagedCodexHomePath(name, m.launch_id);
+        if (m.hook_route !== "managed_codex_home" || m.codex_home !== expectedHome) {
+            throw new AitermError("agent metadata の path が現在の secure state root と一致しません", 2);
+        }
+        return {
+            kind: "codex",
+            aiterm_session: name,
+            launch_id: m.launch_id,
+            event_file: expectedEvent,
+            created_at: typeof m.created_at === "string" ? m.created_at : "",
+            cwd: typeof m.cwd === "string" ? m.cwd : null,
+            vendor_session_id: typeof m.vendor_session_id === "string" ? m.vendor_session_id : null,
+            initial_prompt: m.initial_prompt === true,
+            hook_route: "managed_codex_home",
+            node_platform: process.platform,
+            codex_home: expectedHome,
+        };
+    }
+    const expectedGrokHome = agentManagedGrokHomePath(name, m.launch_id);
+    const expectedHome = agentManagedGrokUserHomePath(name, m.launch_id);
+    if (m.hook_route !== "managed_grok_home" || m.grok_home !== expectedGrokHome || m.home !== expectedHome) {
+        throw new AitermError("agent metadata の path が現在の secure state root と一致しません", 2);
+    }
+    return {
+        kind: m.kind,
+        aiterm_session: name,
+        launch_id: m.launch_id,
+        event_file: expectedEvent,
+        created_at: typeof m.created_at === "string" ? m.created_at : "",
+        cwd: typeof m.cwd === "string" ? m.cwd : null,
+        vendor_session_id: typeof m.vendor_session_id === "string" ? m.vendor_session_id : null,
+        initial_prompt: m.initial_prompt === true,
+        hook_route: "managed_grok_home",
+        node_platform: process.platform,
+        grok_home: expectedGrokHome,
+        home: expectedHome,
+    };
+}
+function parseAgentDoneEvent(line, meta) {
+    let obj;
+    try {
+        obj = JSON.parse(line);
+    }
+    catch {
+        return { event: null, malformed: true };
+    }
+    const ev = obj;
+    if (ev.type !== "agent_done" ||
+        ev.vendor !== meta.kind ||
+        ev.aiterm_session !== meta.aiterm_session ||
+        ev.launch_id !== meta.launch_id ||
+        ev.done_status !== "turn_done") {
+        return { event: null, malformed: false };
+    }
+    if (meta.vendor_session_id && ev.vendor_session_id !== meta.vendor_session_id) {
+        return { event: null, malformed: false };
+    }
+    return {
+        event: {
+            type: "agent_done",
+            vendor: meta.kind,
+            aiterm_session: meta.aiterm_session,
+            launch_id: meta.launch_id,
+            vendor_session_id: typeof ev.vendor_session_id === "string" ? ev.vendor_session_id : null,
+            turn_id: typeof ev.turn_id === "string" ? ev.turn_id : null,
+            reason: typeof ev.reason === "string" ? ev.reason : "Stop",
+            done_status: "turn_done",
+            stop_hook_active: !!ev.stop_hook_active,
+            at: typeof ev.at === "string" ? ev.at : new Date().toISOString(),
+        },
+        malformed: false,
+    };
+}
+function scanAgentDoneLines(lines, meta) {
+    let malformedEvents = 0;
+    let candidate = null;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        if (Buffer.byteLength(line, "utf8") > 64 * 1024) {
+            malformedEvents++;
+            continue;
+        }
+        const parsed = parseAgentDoneEvent(line, meta);
+        if (parsed.malformed) {
+            malformedEvents++;
+            continue;
+        }
+        const ev = parsed.event;
+        if (!ev)
+            continue;
+        if (meta.vendor_session_id)
+            return { event: ev, malformedEvents, ambiguousVendorSession: false };
+        if (candidate?.vendor_session_id &&
+            ev.vendor_session_id &&
+            candidate.vendor_session_id !== ev.vendor_session_id) {
+            return { event: null, malformedEvents, ambiguousVendorSession: true };
+        }
+        if (!candidate)
+            candidate = ev;
+    }
+    return { event: candidate, malformedEvents, ambiguousVendorSession: false };
+}
+function bindAgentVendorSession(meta, ev) {
+    if (!meta.vendor_session_id && ev.vendor_session_id) {
+        meta.vendor_session_id = ev.vendor_session_id;
+    }
+}
+function bindCompletedInitialPrompt(meta) {
+    if (!meta.initial_prompt || meta.vendor_session_id)
+        return;
+    const size = safeStatSize(meta.event_file);
+    if (size === 0) {
+        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了待ちです。初回応答完了後に再度 pty_send(wait:"agent_done") してください。`, 2);
+    }
+    const text = readFileRange(meta.event_file, 0, size).toString("utf8");
+    const lines = text.split("\n");
+    const tail = lines.pop() ?? "";
+    const scanned = scanAgentDoneLines(lines, meta);
+    if (scanned.ambiguousVendorSession) {
+        throw new AitermError("agent event file に複数の vendor_session_id が混在しています。該当セッションを閉じて起動し直してください。", 2);
+    }
+    if (!scanned.event) {
+        const malformed = scanned.malformedEvents ? ` malformed_events=${scanned.malformedEvents}` : "";
+        const partial = tail.trim() ? " partial_event=true" : "";
+        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了 event をまだ確認できません。初回応答完了後に再度 pty_send(wait:"agent_done") してください。${malformed}${partial}`, 2);
+    }
+    bindAgentVendorSession(meta, scanned.event);
+    meta.initial_prompt = false;
+    writeAgentMetadata(meta);
+}
+async function waitAgentDoneEvent(meta, startOffset, timeout) {
+    const deadline = performance.now() + timeout * 1000;
+    let cursor = startOffset;
+    let carry = "";
+    let malformedEvents = 0;
+    for (;;) {
+        const size = safeStatSize(meta.event_file);
+        if (size < cursor) {
+            cursor = 0;
+            carry = "";
+        }
+        if (size > cursor) {
+            if (size - cursor > AGENT_EVENT_MAX_BYTES) {
+                throw new AitermError("agent event file の増分が大きすぎます。該当セッションを閉じて起動し直してください。", 2);
+            }
+            carry += readFileRange(meta.event_file, cursor, size).toString("utf8");
+            cursor = size;
+            const parts = carry.split("\n");
+            carry = parts.pop() ?? "";
+            const scanned = scanAgentDoneLines(parts, meta);
+            malformedEvents += scanned.malformedEvents;
+            if (scanned.ambiguousVendorSession) {
+                throw new AitermError("agent event file に複数の vendor_session_id が混在しています。該当セッションを閉じて起動し直してください。", 2);
+            }
+            if (scanned.event) {
+                bindAgentVendorSession(meta, scanned.event);
+                if (meta.vendor_session_id)
+                    writeAgentMetadata(meta);
+                return { event: scanned.event, malformedEvents };
+            }
+        }
+        if (performance.now() >= deadline)
+            return { event: null, malformedEvents };
+        await sleep(AGENT_DONE_POLL_MS);
+    }
+}
+function agentDoneSuffix(wait, vendor) {
+    const ev = wait.event;
+    if (!ev) {
+        const malformed = wait.malformedEvents ? ` malformed_events=${wait.malformedEvents}` : "";
+        return ` [is_complete=False via agent_timeout vendor=${vendor}${malformed}]`;
+    }
+    const bits = [
+        "is_complete=True",
+        "via agent_done",
+        `vendor=${ev.vendor}`,
+        ev.turn_id ? `turn_id=${ev.turn_id}` : null,
+        ev.vendor_session_id ? `vendor_session_id=${ev.vendor_session_id}` : null,
+        `done_status=${ev.done_status}`,
+    ].filter(Boolean);
+    return ` [${bits.join(" ")}]`;
+}
+function isAgentTuiReady(kind, screen) {
+    if (kind === "codex") {
+        return screen.includes("OpenAI Codex") && /(^|\n)\s*[›>]/.test(screen);
+    }
+    return screen.includes("Grok Build") && /(^|\n|\s)❯/.test(screen);
+}
+async function waitAgentTuiReadyImpl(kind, sample, sleepFn, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? AGENT_TUI_READY_TIMEOUT_MS;
+    const pollMs = opts.pollMs ?? AGENT_TUI_READY_POLL_MS;
+    const deadline = performance.now() + timeoutMs;
+    let samples = 0;
+    let lastScreen = "";
+    for (;;) {
+        lastScreen = sample();
+        samples++;
+        if (isAgentTuiReady(kind, lastScreen))
+            return { ready: true, samples, lastScreen };
+        if (performance.now() >= deadline)
+            return { ready: false, samples, lastScreen };
+        await sleepFn(pollMs);
+    }
+}
+async function waitAgentTuiReady(name, meta, timeoutMs = AGENT_TUI_READY_TIMEOUT_MS) {
+    return waitAgentTuiReadyImpl(meta.kind, () => captureScreen(name, AGENT_TUI_READY_LINES), sleep, { timeoutMs });
+}
+async function settleAgentDoneScreenImpl(sample, sleepFn, opts = {}) {
+    const minDelayMs = opts.minDelayMs ?? AGENT_DONE_SETTLE_MIN_MS;
+    const pollMs = opts.pollMs ?? AGENT_DONE_SCREEN_SETTLE_POLL_MS;
+    const maxPolls = opts.maxPolls ?? AGENT_DONE_SCREEN_SETTLE_MAX_POLLS;
+    const minSamples = opts.minSamples ?? AGENT_DONE_SCREEN_SETTLE_MIN_SAMPLES;
+    if (minDelayMs > 0)
+        await sleepFn(minDelayMs);
+    let prev = sample();
+    let samples = 1;
+    let stableStreak = 1;
+    for (let i = 0; i < maxPolls; i++) {
+        if (pollMs > 0)
+            await sleepFn(pollMs);
+        const current = sample();
+        samples++;
+        if (current.screen === prev.screen && current.logSize === prev.logSize) {
+            stableStreak++;
+            if (samples >= minSamples && stableStreak >= 2)
+                return { unstable: false, samples };
+        }
+        else {
+            stableStreak = 1;
+        }
+        prev = current;
+    }
+    return { unstable: true, samples };
+}
+async function settleAgentDoneScreen(name, lines) {
+    return settleAgentDoneScreenImpl(() => ({
+        screen: captureScreen(name, lines),
+        logSize: safeStatSize(logpath(name)),
+    }), sleep);
+}
+export async function __testSettleAgentDoneScreen(samples, opts = {}) {
+    if (samples.length === 0)
+        throw new AitermError("screen settle test samples が空です", 2);
+    let i = 0;
+    const sleeps = [];
+    const result = await settleAgentDoneScreenImpl(() => samples[Math.min(i++, samples.length - 1)], async (ms) => {
+        sleeps.push(ms);
+    }, opts);
+    return { ...result, sleeps };
+}
+export function __testIsAgentTuiReady(kind, screen) {
+    return isAgentTuiReady(kind, screen);
+}
+export async function __testWaitAgentTuiReady(kind, samples, opts = {}) {
+    if (samples.length === 0)
+        throw new AitermError("agent ready test samples が空です", 2);
+    let i = 0;
+    const sleeps = [];
+    const result = await waitAgentTuiReadyImpl(kind, () => samples[Math.min(i++, samples.length - 1)], async (ms) => {
+        sleeps.push(ms);
+    }, opts);
+    return { ...result, sleeps };
+}
+export async function sendAndWaitAgentDone(name, text, o = {}) {
+    assertSessionName(name);
+    if (o.enter === false)
+        throw new AitermError('wait:"agent_done" は enter:false と併用できません', 2);
+    if (o.mark)
+        throw new AitermError('wait:"agent_done" と mark:true は併用できません', 2);
+    if (o.rtk)
+        throw new AitermError('wait:"agent_done" と rtk:true は併用できません', 2);
+    const meta = loadAgentMetadata(name);
+    if (agentWaitLocks.has(name))
+        throw new AitermError(`agent session '${name}' は別の agent_done 待機中です`, 2);
+    const releaseFileLock = acquireAgentWaitFileLock(meta);
+    const timeout = o.timeout ?? DEFAULT_AGENT_DONE_TIMEOUT;
+    const screen = o.screen ?? true;
+    agentWaitLocks.add(name);
+    try {
+        bindCompletedInitialPrompt(meta);
+        if (!meta.vendor_session_id) {
+            const ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
+            if (!ready.ready) {
+                throw new AitermError(`agent session '${name}' の ${agentLabel(meta.kind)} TUI が入力受付状態になりません。文字列は送信していません。` +
+                    "少し後で pty_read(screen:true) を確認し、TUI が起動済みなら再度 pty_send(wait:\"agent_done\") してください。", 2);
+            }
+        }
+        const startOffset = safeStatSize(meta.event_file);
+        send(name, text, {
+            enter: false,
+            force: o.force,
+            raw: o.raw,
+            mark: false,
+            rtk: false,
+        });
+        // Codex TUI は literal text 投入直後の Enter を取り落とすことがある。agent 経路だけ submit を分離する。
+        await sleep(AGENT_SUBMIT_DELAY_MS);
+        sendKey(name, "Enter");
+        const wait = await waitAgentDoneEvent(meta, startOffset, timeout);
+        const settled = wait.event
+            ? await settleAgentDoneScreen(name, o.lines ?? 0)
+            : { unstable: false, samples: 0 };
+        const out = await readOutput(name, {
+            screen,
+            lines: o.lines ?? null,
+            timeout: 0,
+        });
+        writeOffset(name, safeStatSize(logpath(name)));
+        return out + agentDoneSuffix(wait, meta.kind) + (settled.unstable ? " [agent_done_but_screen_unstable]" : "");
+    }
+    finally {
+        agentWaitLocks.delete(name);
+        releaseFileLock();
+    }
+}
+// ── 対話型エージェント起動（Codex / Grok Build(Grok) / Grok Build(Composer)）──────
+// aiterm の永続端末に、指定モデルの対話エージェント TUI を起動する。以後は pty_read で画面を
+// 読み、pty_send で操作する＝aiterm の対話パラダイムそのもの。モデルはツールごとに固定し、
+// reasoning effort は引数で渡す。CLI 未導入環境は明示エラー（動くフリをしない）。
 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)
-        return fromEnv;
+    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;
@@ -615,23 +1702,60 @@ function resolveAgentBin(kind) {
 function shq(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
-function buildAgentCmd(kind, bin, effort, prompt) {
+function buildAgentCmd(kind, bin, effort, prompt, meta = null) {
     const parts = [shq(bin)];
     if (kind === "codex") {
+        if (meta?.kind === "codex")
+            parts.push("--dangerously-bypass-hook-trust");
         // 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("--no-auto-update");
+        if (meta?.kind === "grok" || meta?.kind === "composer")
+            parts.push("--no-alt-screen");
         parts.push("--model", kind === "composer" ? "grok-composer-2.5-fast" : "grok-build");
         if (effort)
             parts.push("--effort", shq(effort));
+        if ((meta?.kind === "grok" || meta?.kind === "composer") && prompt)
+            parts.push("--verbatim");
     }
     if (prompt)
         parts.push(shq(prompt)); // 初手プロンプト（任意）
     return parts.join(" ");
 }
+function agentEnvPrefix(meta, sid) {
+    if (!meta)
+        return "";
+    const common = [
+        `AITERM_AGENT_KIND=${shq(meta.kind)}`,
+        `AITERM_SESSION_ID=${shq(sid)}`,
+        `AITERM_AGENT_SESSION_ID=${shq(sid)}`,
+        `AITERM_AGENT_LAUNCH_ID=${shq(meta.launch_id)}`,
+    ];
+    if (meta.kind === "codex") {
+        return [`CODEX_HOME=${shq(meta.codex_home ?? "")}`, ...common].join(" ") + " ";
+    }
+    return [
+        `HOME=${shq(meta.home ?? "")}`,
+        `GROK_HOME=${shq(meta.grok_home ?? "")}`,
+        "GROK_DISABLE_AUTOUPDATER=1",
+        "GROK_CLAUDE_HOOKS_ENABLED=false",
+        "GROK_CURSOR_HOOKS_ENABLED=false",
+        "GROK_CLAUDE_SKILLS_ENABLED=false",
+        "GROK_CURSOR_SKILLS_ENABLED=false",
+        "GROK_CLAUDE_RULES_ENABLED=false",
+        "GROK_CURSOR_RULES_ENABLED=false",
+        "GROK_CLAUDE_AGENTS_ENABLED=false",
+        "GROK_CURSOR_AGENTS_ENABLED=false",
+        "GROK_CLAUDE_MCPS_ENABLED=false",
+        "GROK_CURSOR_MCPS_ENABLED=false",
+        `AITERM_REAL_HOME=${shq(process.env.HOME ?? os.homedir())}`,
+        ...common,
+    ].join(" ") + " ";
+}
 function agentLabel(kind) {
     return kind === "composer"
         ? "Grok Build(Composer)"
@@ -649,14 +1773,22 @@ export function openAgent(kind, opts = {}) {
     if (effort && kind !== "codex" && !GROK_EFFORTS.has(effort)) {
         throw new AitermError(`reasoning_effort '${effort}' は不正です（${label} は low/medium/high/xhigh/max）`, 2);
     }
+    const agentDone = !!opts.agent_done;
     const bin = resolveAgentBin(kind);
     if (!bin) {
         const where = kind === "codex" ? "~/.local/bin/codex" : "~/.grok/bin/grok";
         throw new AitermError(`${label} の CLI が見つかりません（${where} か PATH が必要）`, 2);
     }
-    if (opts.cwd) {
-        // cd 失敗はシェル内で静かに死に、エージェント未起動のまま「起動した」と偽の成功を返してしまう。
-        // session を作る前に実在を検証して明示エラーにする。
+    // 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);
@@ -667,12 +1799,29 @@ export function openAgent(kind, opts = {}) {
         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, bin, effort, opts.prompt ?? null);
-    const full = opts.cwd ? `cd ${shq(opts.cwd)} && ${cmd}` : cmd;
     try {
-        send(sid, full, { enter: true, mark: false, force: false, rtk: false, raw: true });
+        const meta = agentDone
+            ? kind === "codex"
+                ? createCodexAgentMetadata(sid, cwd, !!opts.prompt)
+                : createGrokAgentMetadata(kind, sid, cwd, !!opts.prompt)
+            : null;
+        const cmd = buildAgentCmd(kind, binForCmd, effort, opts.prompt ?? null, meta);
+        const envPrefix = agentEnvPrefix(meta, sid);
+        const full = cwdForCmd ? `cd ${shq(cwdForCmd)} && ${envPrefix}${cmd}` : `${envPrefix}${cmd}`;
+        // 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 は空のまま残る＝残骸を作らない。片付けてから元エラーを伝える。
@@ -686,7 +1835,10 @@ export function openAgent(kind, opts = {}) {
     }
     return [
         sid,
-        `${label} を session ${sid} で起動した。\n${hint}\n` +
-            `pty_read(${sid}) で TUI を読み、pty_send(${sid}, "...") で操作する（対話）。`,
+        `${label} を session ${sid} で起動した。${agentDone ? "agent_done 待機が有効。" : ""}` +
+            `${agentDone && kind !== "codex" ? " hook 汚染防止のため Grok 実行中は一時 HOME を使う。" : ""}\n${hint}\n` +
+            `TUI の描画には数秒かかる。少し置いてから pty_read(${sid}, screen:true) で画面を読み、` +
+            `pty_send(${sid}, "...") で入力・pty_key(${sid}, "Enter"/"Up"/"C-c" 等) で操作する（対話）。` +
+            `起動直後に増分 pty_read すると空/半描画になり得るので screen:true を使う。`,
     ];
 }