aiterm-mcp 0.51.3 → 0.52.1

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.52.1] - 2026-10-05
+
+### 修正
+
+- 同じagent sessionへの`pty_send`が重なると、後の1通が断られる事があった（ADR 0088）。Aitermは送る時点の子の状態を見て
+  差し込みか新しいturnかを決めるが、見てから送り終えるまでの間に起動直後の入力受付待ち（最長30秒）が挟まり、
+  その区間を守るものが無かった。Claude Codeでは2通ともturnの印が無いと読み、後の1通が
+  「operation_idなしのClaude turn が未解決です」で断られた（文は打たれない）。Codex・Grok・Cursorでは断りにならず、
+  同じ入力欄へ2通が続けて貼られ、1行につながって届いた。同じsessionへの送信（`pty_send`、`claude_turn issue`、起動時prompt）を
+  1本ずつ通し、後の1通は前の1通が終わってから振り分け直す。順に送った時と同じ結果になり、Claude Codeへ重なった後の1通は
+  `mode=agent_steer`で返る。前の1通を待つ分だけ返りが遅れる。待つ上限（POSIX 60秒、Windows 180秒）を越えたら、
+  打鍵前に`AGENT_SEND_BUSY`と「文字列は送信していません」を返す。送信の途中で終了したprocessのlockは、次の送信が片付ける。
+  公開toolの返却形式とstate schemaは変えていない。旧版へ戻す時の手当ては要らない。
+
+## [0.52.0] - 2026-10-04
+
+### 修正
+
+- 席の中で起動した試験が`AITERM_STATE_BASE`を本番から引き継ぎ、`killAll`で他のsocketのagent登録まで
+  削除していた（ADR 0087）。BellTeamで複数席の送信が通常PTYの`mode=sent`となり、完了待ちと回答の表示が
+  失敗した。`killAll`は現在のsocketのsessionと控えに属する登録だけを消し、他のsocketの待機lockも保持する。
+  試験入口は本番の保存場所・系譜・tmux環境を外して一時領域を指定する。既に失った登録は対象sessionを
+  閉じて同じIDで起動し直して復旧する。登録の形式と公開toolの返却形式は変えていない。
+- `pty_send`に`require_agent:true`を追加した。agent登録が無いsessionには打鍵せず、
+  `AGENT_SESSION_REQUIRED`と「文字列は送信していません」を返す。連携元は、登録消失後の二重送信を避けて復旧できる。
+  省略時は従来の通常PTY送信を維持する。`force:true`との併用は未送信で拒否する。
+
 ## [0.51.3] - 2026-10-04
 
 ### 修正
@@ -2090,7 +2117,9 @@ prototype (preserved under `prototype/python/` as the porting source and referen
   `ubuntu-latest` for Node 18/20/22, publishing to npm on `v*` tags with
   provenance.
 
-[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.51.3...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.52.1...HEAD
+[0.52.1]: https://github.com/kitepon/aiterm-mcp/compare/v0.52.0...v0.52.1
+[0.52.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.51.3...v0.52.0
 [0.51.3]: https://github.com/kitepon/aiterm-mcp/compare/v0.51.2...v0.51.3
 [0.51.2]: https://github.com/kitepon/aiterm-mcp/compare/v0.51.1...v0.51.2
 [0.51.1]: https://github.com/kitepon/aiterm-mcp/compare/v0.51.0...v0.51.1

package/README.ja.md

@@ -209,7 +209,7 @@ runtime-error store は canonical dotagents config の `collection.enabled: true
 場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
 Publishing）で公開し、GitHub Release が Official MCP Registry を再登録します。
 
-**状態:** 開発継続中 · 現行公開版 **v0.51.3** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.52.1** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
@@ -259,6 +259,10 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 ClaudeがAPIエラーや安全判定の拒否で終了した時は、Stop hookが発火しなくても次の`pty_send`を新しいturnとして扱う。現在のturn開始後のエラー記録だけを確認し、過去のエラーで実行中のturnを解除しない。上流の拒否はエラーのまま返す。
 
+agent配送だけを期待する連携では、`pty_send`に`require_agent:true`を指定する。agent登録が無ければ、打鍵前に`AGENT_SESSION_REQUIRED`と「文字列は送信していません」を返す。省略時は通常PTY送信を維持する。`force:true`との併用は未送信で拒否する。
+
+同じagent sessionへの`pty_send`が重なった時は、1本ずつ通す。後の1通は、前の1通を送り終えてから振り分け直すので、順に送った時と同じ結果になる（起動直後のClaude Codeへ重なった後の1通は`mode=agent_steer`で返る）。前の1通が起動直後の入力受付待ちなら、その分だけ返りが遅れる。待つ上限（POSIX 60秒、Windows 180秒）を越えた時は、打鍵前に`AGENT_SEND_BUSY`と「文字列は送信していません」を返す。送信の途中で終了したprocessのlockは、次の送信が片付けて進む。
+
 `agent_launch`・`pty_send`（agent session宛て）は任意の`image`（画像ファイルの絶対パスの配列。png/jpg/jpeg/gif/webp）を受ける。aitermが本文末尾へ添付行を付け、どのharnessも自分のfile読取toolでそのpathを画像として開く。呼出し側はharness別の添付手順を覚えない。不正なpathは送信前に拒否する。
 
 `agent_launch`は任意の`write_scope`も受ける。Codex／Grokのread-onlyは`--sandbox read-only`、Cursorは公式`--mode ask`で実効化する。path説明は同等CLI引数がないためdeclaration-only。
@@ -550,7 +554,7 @@ Claudeの相関済み承認は既存の`claude_approval`を使う。
 | ツール | 役割 | 主な引数 |
 | --- | --- | --- |
 | `pty_open` | 端末を1個開き`session_id`を返す | `name?`, `shell?`, `env_vars?` |
-| `pty_send` | テキストを送る。agent sessionでは子のturnが実行中なら現在のturnへ差し込み（`agent_steer`）、それ以外は非ブロックdispatchとして`event_cursor`を返す（`agent_dispatch`）。差し込みでGrokが待ち行列へ入れない時とCursorの入力欄に残った時は失敗する | `session_id`, `text`, `enter=true`, `mark`, `force`, `rtk`, `raw` |
+| `pty_send` | テキストを送る。agent sessionでは子のturnが実行中なら現在のturnへ差し込み（`agent_steer`）、それ以外は非ブロックdispatchとして`event_cursor`を返す（`agent_dispatch`）。差し込みでGrokが待ち行列へ入れない時とCursorの入力欄に残った時は失敗する | `session_id`, `text`, `enter=true`, `mark`, `force`, `require_agent=false`, `rtk`, `raw` |
 | `pty_read` | 出力を削減して読む（既定は増分） | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk`, `agent_transcript`, `operation_id` |
 | `pty_key` | 制御キーを送る | `session_id`, `key`（`C-c`/`Enter`/`Up`…） |
 | `pty_close` | 冪等に閉じ、`closed` / `already_closed`を返す | `session_id` |

package/README.md

@@ -223,7 +223,7 @@ collection is off by default and performs no network I/O. It ships via
 tag-triggered CI with npm provenance (OIDC Trusted Publishing); the GitHub
 Release re-registers the Official MCP Registry entry.
 
-**Status:** actively maintained · current public release **v0.51.3** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
+**Status:** actively maintained · current public release **v0.52.1** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
 
 ### Update and rollback
 
@@ -280,6 +280,10 @@ The same primitive hosts another agent's TUI. `agent_launch` starts a selected e
 
 起動結果には正規`harness`を含む`aiterm.agent-launch-result.v1`が付き、旧`provider`は互換fieldとして残る。同じ`harness`はagent dispatch、`aiterm-wait`、`agent_configure`、`pty_list`にも載る。Codexは通常rollout、Grokは通常session event、Claudeはlaunch固有Stop hook、Cursorは通常agent transcriptの`turn_ended`を完了正本に使う。agentへの送信は`pty_send`だけで行い、Aitermが送る時点で子の状態を見て振り分ける。Claudeは画面の実行中表示ではなくStopまで残るturnの印で判定する。実行中のturnへは差し込み（`mode=agent_steer`、新しい`event_cursor`と配送は作らない）、それ以外は非ブロックdispatch（`mode=agent_dispatch`）で、harnessごとの完了境界を表す整数`event_cursor`を返す。Codex親は選択に応じて公式Steerまたはqueue、Claude Code親は公式非同期hookで本文を自動受信する。他の親は[`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait)を使う。CursorのsubmitはadapterがCLIのextended keyboard protocolへ変換し、送信本文がcomposerへ残る場合は明示errorにする。
 
+Set `require_agent:true` on `pty_send` when the integration requires agent delivery. If the agent registration is missing, Aiterm refuses before sending any text and returns `AGENT_SESSION_REQUIRED` with an explicit unsent message. The default preserves ordinary PTY sends; combining it with `force:true` is rejected before sending.
+
+Overlapping `pty_send` calls to the same agent session are handled one at a time. A later call picks its route only after the earlier one has been sent, so the result matches calls made in sequence (a call that overlaps the first send to a freshly started Claude Code session returns `mode=agent_steer`). It returns later by however long the earlier call waits for the session to accept input. If its turn does not come within the limit (60 seconds on POSIX, 180 seconds on Windows), Aiterm refuses before sending any text and returns `AGENT_SEND_BUSY` with an explicit unsent message. A lock left by a process that exited mid-send is cleared by the next send.
+
 `agent_launch` and `pty_send` (to an agent session) accept an optional `image`: an array of absolute paths to image files (png/jpg/jpeg/gif/webp). Aiterm appends an attachment block to the prompt, and every harness opens the path with its own file-reading tool and sees the image; the caller never learns harness-specific attachment tricks. Invalid paths are rejected before anything is sent.
 
 `agent_launch` accepts an optional `write_scope`: either `"read-only"` or a human-readable description of writable paths. Codex/Grok use `--sandbox read-only`; Cursor uses its official read-only `--mode ask`. A path description remains declaration-only because these CLI launch surfaces provide no equivalent path allowlist flag.
@@ -587,7 +591,7 @@ continue to use `claude_approval`.
 | Tool | Role | Key args |
 | --- | --- | --- |
 | `pty_open` | Open one terminal and return a `session_id` | `name?`, `shell?`, `env_vars?` |
-| `pty_send` | Send text. On an agent session Aiterm picks the route when it sends: if the child's turn is running, it steers the text into that turn (`agent_steer`); otherwise it is a non-blocking **dispatch** returning an `event_cursor` (`agent_dispatch`). Steering fails when Grok does not queue the text or Cursor leaves it in the composer | `session_id`, `text`, `enter=true`, `mark`, `force`, `rtk`, `raw` |
+| `pty_send` | Send text. On an agent session Aiterm picks the route when it sends: if the child's turn is running, it steers the text into that turn (`agent_steer`); otherwise it is a non-blocking **dispatch** returning an `event_cursor` (`agent_dispatch`). Steering fails when Grok does not queue the text or Cursor leaves it in the composer | `session_id`, `text`, `enter=true`, `mark`, `force`, `require_agent=false`, `rtk`, `raw` |
 | `pty_read` | Read output, token-reduced (incremental by default) | `session_id`, `wait`, `until`, `until_regex`, `timeout`, `screen`, `full`, `lines`, `line_range`, `raw`, `rtk`, `agent_transcript`, `operation_id` |
 | `pty_key` | Send a control key | `session_id`, `key` (`C-c`/`Enter`/`Up`…) |
 | `pty_close` | Close idempotently; return `closed` / `already_closed` | `session_id` |

package/dist/core.js

@@ -86,6 +86,10 @@ const PTY_PASTE_CHUNK_PAUSE_MS = 10;
 const PTY_PASTE_PAUSE_BUFFER = new Int32Array(new SharedArrayBuffer(4));
 const SESSION_SEND_LOCK_WAIT_MS = isWin ? 130_000 : 10_000;
 const SESSION_SEND_LOCK_POLL_MS = 25;
+// 同じagent sessionへの送信が重なった時に、前の1通を待つ上限（ADR 0088）。
+// 起動から最初の描画を待つ上限と、貼り付けの上限の和。前の1通が正常に進んでいる間は待ち切れる長さにする。
+const AGENT_SEND_LOCK_WAIT_MS = AGENT_TUI_FIRST_DRAW_TIMEOUT_MS + SESSION_SEND_LOCK_WAIT_MS;
+const AGENT_SEND_LOCK_POLL_MS = 50;
 // CSI/OSC/ESC エスケープ・制御文字
 // 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;
@@ -349,6 +353,15 @@ function sendLockPath(name) {
     assertSessionName(name);
     return path.join(SOCKDIR, name + ".send.lock");
 }
+// agent sessionへの送信1本（振り分け〜Enterの確認）を守るlock。貼り付け1回ぶんの`.send.lock`とは別に持つ。
+function agentSendLockPath(name) {
+    assertSessionName(name);
+    return path.join(SOCKDIR, name + ".agent-send.lock");
+}
+// 持ち主が終了した`.agent-send.lock`を片付ける役の印。
+function agentSendReapPath(name) {
+    return agentSendLockPath(name) + ".reap";
+}
 function readOffset(name) {
     try {
         const n = parseInt(fs.readFileSync(offsetpath(name), "utf8").trim(), 10);
@@ -1345,6 +1358,7 @@ function closeSessionInternal(name, observeDependency = true) {
             /* noop */
         }
     }
+    cleanupAgentSendLock(name);
     cleanupAgentState(name);
     agentLaunchLines.delete(name);
     return `closed ${name}`;
@@ -1370,9 +1384,33 @@ export function closeSessionResult(name) {
     };
 }
 export function killAll() {
+    // agentsはAITERM_STATE_BASEを共有する別socketの席も含み得る。終了対象はこのsocketから確定する。
+    const sessions = new Set();
+    const listed = tmux("list-sessions", "-F", "#{session_name}");
+    if (listed.code !== 0 && !/no server running|No such file or directory|failed to connect/i.test(listed.stderr)) {
+        throw new AitermError("killAllの対象sessionを取得できません: " + listed.stderr.trim(), 2);
+    }
+    if (listed.code === 0)
+        for (const name of listed.stdout.trim().split(/\r?\n/).filter(Boolean)) {
+            assertSessionName(name);
+            sessions.add(name);
+        }
+    // serverが外から終了した時の控えも、このsocketの中に残る名前だけ片付ける。
+    let socketFiles = [];
+    try {
+        socketFiles = fs.readdirSync(SOCKDIR);
+    }
+    catch {
+        /* socketの置き場が無い */
+    }
+    for (const file of socketFiles) {
+        const name = file.replace(/\.(?:log|offset|lastcmd|mark|send\.lock|agent-send\.lock(?:\.reap)?)$/, "");
+        if (name !== file && /^[A-Za-z0-9_-]{1,64}$/.test(name))
+            sessions.add(name);
+    }
     {
         // 別プロセスの待機（file lock が生きているもの）も巻き添えにしない
-        const foreign = liveWaitLocks(null);
+        const foreign = liveWaitLocks(null).filter((lock) => sessions.has(lock.session));
         if (foreign.length > 0) {
             const list = foreign.map((d) => `${d.session}${d.pid != null ? `(pid ${d.pid})` : ""}`).join(",");
             throw new AitermError(`agent_done 待機中の session があるため killAll できません: ${list}`, 2);
@@ -1385,11 +1423,14 @@ export function killAll() {
             throw new AitermError(`送信中の session があるため killAll できません: ${list}`, 2);
         }
     }
-    tmux("kill-server");
-    // B9: SOCKDIR 内の .log/.offset/.lastcmd/.mark/.send.lock 残骸も掃除する。
+    const killed = tmux("kill-server");
+    if (killed.code !== 0 && !/no server running|No such file or directory|failed to connect/i.test(killed.stderr)) {
+        throw new AitermError("このsocketのserverを終了できません: " + killed.stderr.trim(), 2);
+    }
+    // B9: SOCKDIR 内の .log/.offset/.lastcmd/.mark/.send.lock/.agent-send.lock 残骸も掃除する。
     try {
         for (const f of fs.readdirSync(SOCKDIR)) {
-            if (/\.(log|offset|lastcmd|mark)$/.test(f) || f.endsWith(".send.lock")) {
+            if (/\.(log|offset|lastcmd|mark)$/.test(f) || f.endsWith(".send.lock") || /\.agent-send\.lock(?:\.reap)?$/.test(f)) {
                 try {
                     fs.unlinkSync(path.join(SOCKDIR, f));
                 }
@@ -1402,37 +1443,8 @@ export function killAll() {
     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(".claude-settings.json") ||
-                    f.endsWith(".claude-mcp.json") ||
-                    f.endsWith(".claude-result.json") ||
-                    f.endsWith(".claude-operation.json") ||
-                    f.endsWith(".claude-dispatch") ||
-                    f.endsWith(".interim.json") ||
-                    f.endsWith(".auth.json") ||
-                    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 不在等は無視 */
-        }
-    }
-    agentMetadataNegativeCache.clear();
+    for (const name of sessions)
+        cleanupAgentState(name);
     return "killed all sessions on this socket";
 }
 function readAgentLineageSeed() {
@@ -1967,6 +1979,159 @@ function acquireSessionSendFileLock(name) {
         }
     };
 }
+// ── 同じagent sessionへの送信を1本ずつ通す（ADR 0088） ────
+// 振り分け（差し込みか新しいturnか）から送り終えるまでの間に、入力受付待ちなどの待ちが挟まる。
+// その間に次の1通が同じ状態を読むと、Claudeはturnの印の取り合いで後の1通が断られ、他のharnessは同じ入力欄へ2回貼る。
+// 同じprocessの中は着いた順の待ち行列、別のprocessの間はfileで排他し、後の1通は前の1通が終わってから振り分け直す。
+const agentSendQueues = new Map();
+const agentSendHeld = new Set();
+let agentSendLockWaitMs = AGENT_SEND_LOCK_WAIT_MS;
+export function __testSetAgentSendLockWaitMs(value) {
+    if (value !== null && (!Number.isSafeInteger(value) || value < 0))
+        throw new Error("wait must be a non-negative integer");
+    agentSendLockWaitMs = value ?? AGENT_SEND_LOCK_WAIT_MS;
+}
+// `O_EXCL`で作れた時だけ持ち主になる。既に在れば null。
+function tryCreateOwnedLock(p) {
+    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) {
+        const code = e.code;
+        // Windowsは、消している途中のfile（他のprocessがまだ開いている）と同じ名前を作るとEPERM／EACCESになる。
+        if (code === "EEXIST" || (isWin && (code === "EPERM" || code === "EACCES")))
+            return null;
+        throw e;
+    }
+    const token = randomBytes(16).toString("hex");
+    try {
+        // 書けなかったlockは中身が読めないまま残り、鮮度猶予の後に持ち主なしとして片付く。
+        fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString(), token }) + "\n", "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return token;
+}
+function releaseOwnedLock(p, token) {
+    try {
+        const st = fs.lstatSync(p);
+        if (!st.isFile() || st.isSymbolicLink())
+            return;
+        const current = JSON.parse(fs.readFileSync(p, "utf8").split("\n", 1)[0]);
+        if (current.token === token)
+            fs.unlinkSync(p);
+    }
+    catch {
+        /* 別の持ち主のlockや置換済みpathは消さない */
+    }
+}
+// 同じprocessの送信は待ち行列で1本になっているので、自分のpidのlockは外し損ねた残骸と読める（probeWaitLock）。
+// このprocessが持っている最中のlockだけは、その読みから外す。
+function probeAgentSendLock(name) {
+    const probe = probeWaitLock(agentSendLockPath(name));
+    return probe.pid === process.pid && agentSendHeld.has(name) ? { ...probe, live: true } : probe;
+}
+// 持ち主が終了したlockを片付ける。確かめてから消すまでの間に別のprocessが新しいlockを作ると生きたlockを消すので、
+// 消す役を`.reap`の`O_EXCL`で1つに絞り、その中でもう一度確かめてから消す。lockが在る間は誰も新しいlockを作れない。
+// done=片付けた（または片付ける物が無かった）／busy=別のprocessが片付け中／stuck=片付けの印が持ち主なしで残っている
+function reapDeadAgentSendLock(name) {
+    const guard = agentSendReapPath(name);
+    const token = tryCreateOwnedLock(guard);
+    if (token === null)
+        return probeWaitLock(guard).live ? "busy" : "stuck";
+    try {
+        if (!probeAgentSendLock(name).live) {
+            try {
+                fs.unlinkSync(agentSendLockPath(name));
+            }
+            catch {
+                /* 既に無い */
+            }
+        }
+    }
+    finally {
+        releaseOwnedLock(guard, token);
+    }
+    return "done";
+}
+function agentSendBusyError(name, pid, waitMs) {
+    return new AitermError(`AGENT_SEND_BUSY: agent session '${name}' は${pid != null ? `別プロセス（pid ${pid}）` : "先に受け付けた送信"}の処理中です。` +
+        `${waitMs}ms待っても順番が来ませんでした。文字列は送信していません。少し後で再度 pty_send してください。`, 2);
+}
+async function acquireAgentSendFileLock(name, deadline, waitMs) {
+    const p = agentSendLockPath(name);
+    for (;;) {
+        const token = tryCreateOwnedLock(p);
+        if (token !== null)
+            return () => releaseOwnedLock(p, token);
+        const probe = probeAgentSendLock(name);
+        if (!probe.live && reapDeadAgentSendLock(name) === "stuck") {
+            throw new AitermError(`agent session '${name}' に、終了した送信のlockを片付ける途中で残った印があります。` +
+                `自動回収は並行送信の混線を招くため行いません。文字列は送信していません。` +
+                `pty_listで対象を確認し、pty_closeでsessionを閉じてから同じIDで再作成してください`, 2);
+        }
+        if (performance.now() >= deadline)
+            throw agentSendBusyError(name, probe.live ? probe.pid : null, waitMs);
+        await sleep(AGENT_SEND_LOCK_POLL_MS);
+    }
+}
+async function withAgentSendLock(name, run) {
+    const waitMs = agentSendLockWaitMs;
+    const deadline = performance.now() + waitMs;
+    const previous = agentSendQueues.get(name) ?? Promise.resolve();
+    let leave;
+    const mine = new Promise((resolve) => {
+        leave = resolve;
+    });
+    // 待ち切れずに抜けた送信の後ろも、前の送信が終わるまで待つ。行列の控えは、ここまでの送信が全部終わってから消す。
+    const tail = previous.then(() => mine);
+    agentSendQueues.set(name, tail);
+    void tail.then(() => {
+        if (agentSendQueues.get(name) === tail)
+            agentSendQueues.delete(name);
+    });
+    let timer;
+    try {
+        const myTurn = await Promise.race([
+            previous.then(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), waitMs);
+            }),
+        ]);
+        clearTimeout(timer);
+        if (!myTurn)
+            throw agentSendBusyError(name, null, waitMs);
+        const release = await acquireAgentSendFileLock(name, deadline, waitMs);
+        agentSendHeld.add(name);
+        try {
+            return await run();
+        }
+        finally {
+            agentSendHeld.delete(name);
+            release();
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        leave();
+    }
+}
+// pty_closeの掃除。生きた持ち主のlockは残す（その送信はsessionが無くなった所で失敗し、自分のlockを外す）。
+function cleanupAgentSendLock(name) {
+    const guard = agentSendReapPath(name);
+    try {
+        if (fs.existsSync(guard) && !probeWaitLock(guard).live)
+            fs.unlinkSync(guard);
+        if (fs.existsSync(agentSendLockPath(name)))
+            reapDeadAgentSendLock(name);
+    }
+    catch {
+        /* 掃除の失敗で閉じる処理を止めない */
+    }
+}
 // close/killAll 用: 生きた別プロセス待機の wait lock を列挙する（stale 残骸は数えない）。
 function liveWaitLocks(name) {
     const dir = existingAgentsDir();
@@ -3293,6 +3458,11 @@ async function prepareAgentInput(name, meta, options) {
 }
 export async function sendInitialAgentPrompt(name, text, o = {}) {
     assertSessionName(name);
+    loadAgentMetadata(name);
+    // 起動時promptの準備中に届いたpty_sendは、起動時promptを送り終えてから振り分ける（ADR 0088）。
+    return withAgentSendLock(name, () => sendInitialAgentPromptInLock(name, text, o));
+}
+async function sendInitialAgentPromptInLock(name, text, o) {
     const meta = loadAgentMetadata(name);
     if (meta.initial_prompt === "done") {
         throw new AitermError(`agent session '${name}' の起動時 prompt は既に完了しています`, 2);
@@ -3895,6 +4065,10 @@ async function assertCursorPromptNotHookBlocked(name) {
 }
 export async function dispatchAgentTurn(name, text, o = {}) {
     assertSessionName(name);
+    loadAgentMetadata(name);
+    return withAgentSendLock(name, () => dispatchAgentTurnInLock(name, text, o));
+}
+async function dispatchAgentTurnInLock(name, text, o) {
     const meta = loadAgentMetadata(name);
     const operationId = o.operation_id == null ? null : validateOperationId(o.operation_id);
     if (operationId && meta.kind !== "claude") {
@@ -4042,9 +4216,14 @@ export function __testSteerQueued(kind, screen) {
  * agent sessionへの唯一の送信口。呼び出し側は子の状態を知らないまま呼び、Aitermがこの時点の画面で振り分ける。
  * 実行中なら現在のturnへ差し込み（steer）、そうでなければ新しいturnとしてdispatchする。
  * 振り分けを呼び出し側へ任せると、状態を見てから呼ぶまでの間に子のturnが変わり、選んだ入口が外れる。
+ * 同じsessionへの送信は1本ずつ通し、重なった後の1通は前の1通が終わってから振り分け直す（ADR 0088）。
  */
 export async function sendAgentMessage(name, text, o = {}) {
     assertSessionName(name);
+    loadAgentMetadata(name);
+    return withAgentSendLock(name, () => sendAgentMessageInLock(name, text, o));
+}
+async function sendAgentMessageInLock(name, text, o) {
     const meta = loadAgentMetadata(name);
     // 前面回復は busy 判定より先（bash 前面のままだと画面の実行中マーカーを読んでも打鍵が届かない）。
     const paneInputRecovery = await ensureAgentOwnsPaneInput(name, meta.kind);
@@ -4064,7 +4243,7 @@ export async function sendAgentMessage(name, text, o = {}) {
     if (running) {
         return steerRunningTurn(name, meta, text, { raw: o.raw, pane_input_recovery: paneInputRecovery });
     }
-    return dispatchAgentTurn(name, text, { raw: o.raw, before_send: o.before_send, pane_input_recovery: paneInputRecovery });
+    return dispatchAgentTurnInLock(name, text, { raw: o.raw, before_send: o.before_send, pane_input_recovery: paneInputRecovery });
 }
 /**
  * 実行中turnへ追加の指示を渡す。各harnessの標準操作だけを使い、完了境界は1つに保つ。

package/dist/index.js

@@ -273,6 +273,7 @@ registerRemoteAwareTool("pty_send", {
         "receipt の event_cursor を返す。" +
         NON_BLOCKING_RULE +
         "自動配送以外の結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。" +
+        "require_agent:true はagent登録が無いsessionへ打鍵せず、AGENT_SESSION_REQUIREDで未送信を返す。" +
         "force:true は非Claude agent sessionへの手動介入用の素送信。aiterm相関付きClaudeの承認UIはclaude_approvalを使う。",
     inputSchema: {
         session_id: z.string(),
@@ -291,6 +292,7 @@ registerRemoteAwareTool("pty_send", {
             .boolean()
             .default(false)
             .describe("非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"),
+        require_agent: z.boolean().default(false).describe("agent登録が無いsessionは打鍵前に拒否する。force:trueとは併用できない"),
         rtk: z.boolean().default(false).describe("既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）"),
         raw: z.boolean().default(false).describe("送信前サニタイズを無効化"),
         image: z
@@ -315,10 +317,17 @@ registerRemoteAwareTool("pty_send", {
         // dispatch前に行った pane 入力の回復（"fg" / "fg_stopped" / "stty_raw"）。通常送信では省略（additive）。
         pane_input_recovery: z.array(z.string()).optional(),
     },
-}, async ({ session_id, text, enter, mark, force, rtk, raw, image }, extra) => {
+}, async ({ session_id, text, enter, mark, force, require_agent, rtk, raw, image }, extra) => {
     let delivery = null;
     try {
-        if (!force && core.isAgentSession(session_id)) {
+        if (require_agent && force) {
+            throw new Error("require_agent:true は force:true と併用できません。文字列は送信していません。");
+        }
+        const agentSession = !force && core.isAgentSession(session_id);
+        if (require_agent && !agentSession) {
+            throw new Error(`AGENT_SESSION_REQUIRED: session '${session_id}' のagent登録がありません。文字列は送信していません。`);
+        }
+        if (agentSession) {
             if (enter === false)
                 throw new Error("agent session への dispatch は enter:false と併用できません（手動介入は force:true）");
             if (mark)

package/docs/DESIGN.md

@@ -47,6 +47,16 @@ psmuxが出力した余分な環境値を返さない。通常PTYとagentへ`AIT
 sessionの表には環境が丸ごと入るので、名指しで登録した名前をsessionのoption `@aiterm_env_keys`に控え、
 `env_keys`はその名前だけを返す。psmuxは元から端末ごとに呼び出し元の環境を継ぐ。
 
+内部の`killAll`は終了するsocketのsession一覧と、そのsocketのログ等に残るsession名だけを対象にする。
+別socketが同じ`AITERM_STATE_BASE`を使っていても、他のsessionの登録・完了記録・待機lockを削除しない。
+対象の一覧取得やserver終了が失敗した場合は登録を削除しない（ADR 0087）。
+試験の正規入口（`npm test`とCI）は`test/seat-env.mjs`を前処理として読み、席の保存場所・系譜・tmux環境を外し、
+試験processごとの一時領域を指定する。個別試験が指定する`TMPDIR`と`XDG_RUNTIME_DIR`もそのまま利用できる。
+
+agent配送だけを期待する連携元は`pty_send(require_agent:true)`を指定する。agent登録が無ければ、通常PTYへ送る前に
+`AGENT_SESSION_REQUIRED`と「文字列は送信していません」を返す。未送信を確定してから対象sessionを復旧できる。
+省略時の通常PTY送信は維持し、`force:true`との併用は打鍵前に拒否する。
+
 `pty_observe`は存在、pane／harnessの生存、画面状態と理由、native process identityを分ける。
 PIDは開始識別子・argv digestと組にし、paneとharnessを同一視しない。特定できないidentityはnull。
 同じlaunchに属するnpm shimとnative本体は、中間の非候補processも含めた祖先関係から一つの起動として扱う。
@@ -85,6 +95,9 @@ agent sessionへの送信口は`pty_send`だけとする。子の状態は呼び
 実行中なら現在のturnへ追加textを差し込み、新しい完了境界と配送は作らない。完了境界は差し込み後も1つに保つ。
 Claude Codeはtool処理中に画面の実行中表示が消え、Stop hookの実行中には表示が残る。turnの印を実行中判定の正本とする。Stopが発火しないAPIエラー終了では、次の送信時に印の作成後の会話記録にある`isApiErrorMessage`を確認し、終了したturnの印だけを解除する。過去のエラーで新しい印を解除しない。waiterは印を変更せず、読取専用のままエラーを返す。
 それ以外は新しいturnとしてdispatchする。
+振り分けから送り終えるまでの間には、起動直後の入力受付待ちなどの待ちが挟まる。同じsessionへの送信（`pty_send`、`claude_turn issue`、起動時prompt）は1本ずつ通し、
+重なった後の1通は前の1通が終わってから振り分け直す。同じprocessの中は着いた順の待ち行列、別のprocessの間はsocketの置き場の`<name>.agent-send.lock`で排他する。
+待つ上限は、起動から最初の描画を待つ上限と貼り付けの上限の和で、越えたら`AGENT_SEND_BUSY`で未送信を返す。判断の記録はADR 0088（`docs/adr/0088-one-agent-send-per-session.md`）。
 CodexとClaude Codeは次のtool境界で同じturnへ取り込む。Cursorは「follow-ups」枠へ入った文を「enter steer」で現在turnへ移し、`turn_ended`は最後に1回書く。
 待ち行列の表示は5秒待ち、子のturnが続いている間だけ30秒まで延ばす（表示が遅い端末がある。turnが終わっていれば、文は新しいturnとして始まっている）。
 Grokは待ち行列へ入れた後に「send now」を押す。旧turnは`cancelled`（`cancellation_context.trigger=send_now`）で閉じ、
@@ -299,6 +312,8 @@ ADR 0074（repositoryの`docs/adr/0074-agent-model-catalog.md`）。
 境界失敗は明示errorにする。retry、別model、別harness、別backendへ自動fallbackしない。
 stale send lockは並行processとのABAを避けるため自動削除せず、公開APIでは対象sessionを`pty_close`して
 同じIDで再作成する。全session一括停止は公開しない。
+agent sessionへの送信1本を守る`<name>.agent-send.lock`は持つ時間が長いので、持ち主が終了した残骸を次の送信が片付ける。消す役を`<name>.agent-send.lock.reap`の排他作成で1つに絞り、
+その中でもう一度確かめてから消すので、確かめた後で別のlockに入れ替わらない。消す役の印そのものが残った時だけは自動で消さず、`pty_close`を案内する。
 
 Grokのread-only sandbox起動拒否は、`src/harnesses/grok.ts`の
 `assertGrokSandboxNotRejected`がCLIのエラー表示から検出する。`src/core.ts`の共通入力受付待機は

package/docs/RELEASE.md

@@ -17,6 +17,7 @@ Aitermのreleaseはこのrepositoryが所有する。`.github/workflows/product-
 ## Release手順
 
 1. 変更に直結するfocused testを手元で通す。full regressionは手元で回さず、CIに任せる。
+   個別試験も`node --import ./test/seat-env.mjs --test ...`で起動する。稼働中の席の保存場所を試験へ継承しない。
 2. `CHANGELOG.md`の`## [Unreleased]`へ内容を書き、mainへcommitしてpushする。
 3. 一回で公開する。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.51.3",
+  "version": "0.52.1",
   "mcpName": "io.github.kitepon/aiterm-mcp",
   "description": "Persistent terminal MCP with one harness-based launcher for Claude Code, Codex CLI, Grok CLI, and Cursor Agent CLI, plus durable PTYs for SSH, containers, and REPLs.",
   "keywords": [
@@ -64,10 +64,10 @@
     "mcpb:build": "npm run build && node scripts/build-mcpb.mjs && npm ci --omit=dev --ignore-scripts --no-audit --no-fund --prefix dist/mcpb-stage/server && npx --yes @anthropic-ai/mcpb@2.1.2 validate dist/mcpb-stage/manifest.json && npx --yes @anthropic-ai/mcpb@2.1.2 pack dist/mcpb-stage dist/aiterm-mcp.mcpb",
     "verify:release-commit": "node scripts/verify-release-commit.mjs",
     "release": "node scripts/release.mjs",
-    "test:docs": "node --test test/repository-contract.test.mjs",
+    "test:docs": "node --import ./test/seat-env.mjs --test test/repository-contract.test.mjs",
     "prepublishOnly": "npm run verify:release-commit && npm run build",
     "start": "node dist/index.js",
-    "test": "npm run build && node --test scripts/verify-release-commit.test.mjs test/*.test.mjs"
+    "test": "npm run build && node --import ./test/seat-env.mjs --test scripts/verify-release-commit.test.mjs test/*.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",