aiterm-mcp 0.29.30 → 0.30.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-09-04
+
+### Added
+
+- `pty_send`（agent dispatch）、`agent_steer`、`agent_launch`に`image`（画像ファイルの絶対パスの配列）を追加した。aitermが本文末尾へ添付行を付け、Claude Code／Codex／Grok／Cursorはいずれも自分のfile読取toolでそのpathを画像として開く（実測 2026-09-04）。呼出し側が入力欄へパスを先打鍵する等のharness別手順を持つ必要を無くす。相対パス・未対応拡張子・不在fileは送信前にtyped errorで拒否し、通常PTY送信とforce送信では指定できない。
+
+## [0.29.31] - 2026-09-04
+
+### Fixed
+
+- agent session への打鍵前に、pane tty 上の agent が前面プロセスグループでなければ `fg` で前面へ戻し、tty が cooked（icanon/echo）なら `raw -echo` へ戻してから送る（`pty_send` dispatch・起動時 prompt・`agent_steer`）。Codex 0.153 はツール実行後に前面を bash へ返したまま動き続ける／termios を cooked のまま残すことがあり、貼付本文が bash に落ちて `^[[200~` が生で残っていた（実測 2026-09-04）。dispatch receipt に `pane_input_recovery` を追加。判定は `ps -t` の STAT と `stty -a` だけを使う。
+
+### Changed
+
+- push時のCIをLinux 1環境へ絞り、WindowsはWindows固有ファイルの変更時だけ、3環境の全テストは週1回の定期実行だけにした。tag起点のnpm公開はmain CIの成功を待たず、既定ブランチの祖先確認だけで進める。
+- `npm run release -- <version>`でversion同期・CHANGELOG見出し・commit・tag・MCPB・GitHub Releaseを一回で行う。
+
 ## [0.29.30] - 2026-09-02
 
 ### Fixed
@@ -1529,7 +1546,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.29.30...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.31...v0.30.0
+[0.29.31]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.30...v0.29.31
 [0.29.30]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.29...v0.29.30
 [0.29.29]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.28...v0.29.29
 [0.29.28]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.27...v0.29.28

package/README.ja.md

@@ -153,7 +153,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.29.30** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.30.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
@@ -189,6 +189,8 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 `aiterm.agent-launch-result.v1`は正規`harness`を返し、旧`provider`は互換fieldとして残す。同じ`harness`はagent dispatch、`aiterm-wait`、`agent_configure`、`pty_list`のagent行にも載り、旧vendor／provider／agent fieldは互換用に残る。Codexは通常rollout、Grok CLIは通常session event、Claudeはlaunch固有Stop hook、Cursorは通常agent transcript末尾の`turn_ended`を完了正本に使う。`pty_send`は非ブロックdispatchで、vendor別完了境界を表すopaqueな整数`event_cursor`を返し、完了通知は`aiterm-wait`を親のターンを塞がない別processで受ける。Cursorのsubmitキーはadapterが現行CLIのextended keyboard protocolへ変換する。送信textがCursorのcomposerへ残った場合は成功receiptを返さず失敗する。
 
+`agent_launch`・`pty_send`（agent dispatch）・`agent_steer`は任意の`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。
 
 ```text
@@ -496,10 +498,11 @@ npm test           # build してから node:test 回帰スイート（tmux ま
 npm link           # ローカルで `aiterm-mcp` を PATH に
 ```
 
-開発中は変更に直結するfocused testを先にローカルで実行します。GitHub Actionsは実装の依存関係から
-必要なテストを選び、依存を確定できない変更とrelease変更だけ3環境の全テストへ広げます。
-tag起点のnpm公開は、同じcommitのmain CIが3環境greenであり、tagged commitが`origin/main`の
-祖先であることを確認した後だけ実行します。tag側で同じ3環境試験は繰り返しません。
+開発中は変更に直結するfocused testを先にローカルで実行します。GitHub Actionsはpushごとにself-hostedの
+`linux-workstation` 1環境で試験を回し、Windows固有ファイルを触った変更だけ`windows-native`を加え、
+3環境（`macos-native`、`linux-workstation`、`windows-native`）の全テストは週1回の健康診断だけで回します。
+`npm run release -- <version>`がversion同期・commit・tag・GitHub Releaseを一回で行い、tag起点のnpm公開は
+tagged commitが`origin/main`の祖先であることだけを確認して、他のCI結果を待ちません。
 
 共通進行は`src/core.ts`、harness固有は`src/harnesses/`、OS差は`src/tmux-runtime.ts`／`src/agent-resolver.ts`、reducerは`src/rtk.ts`、公開面は`src/index.ts`が所有する。現行設計は[`docs/DESIGN.md`](docs/DESIGN.md)、release手順は[`docs/RELEASE.md`](docs/RELEASE.md)を正とする。`prototype/python/`はreducerの歴史的移植元であり、pytest reducerは本家rtk 0.42.0と一致する（上記の`FAILED`行の差異だけは意図的・回帰テストで固定）。
 

package/README.md

@@ -169,7 +169,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.29.30** · 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.30.0** · 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
 
@@ -211,6 +211,8 @@ The same primitive hosts another agent's TUI. `agent_launch` starts a selected e
 
 The human-readable launch text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt containing the canonical `harness`; the old `provider` field remains for compatibility. The same `harness` is carried by agent dispatch, `aiterm-wait`, `agent_configure`, and agent rows in `pty_list`, while their old vendor/provider/agent fields remain compatibility fields. Codex completion comes from its normal durable rollout transcript, Grok CLI from its normal session events, Claude Code from a launch-specific Stop hook settings addition, and Cursor from its normal agent transcript's terminal `turn_ended` record. Sending to any agent session is a non-blocking **dispatch** — the call returns immediately with an opaque, harness-specific integer `event_cursor`, and completion arrives via [`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait). The Cursor adapter translates submit into the current CLI's extended keyboard protocol. If submitted text remains in Cursor's composer, its dispatch fails instead of returning a successful receipt.
 
+`agent_launch`, `pty_send` (agent dispatch), and `agent_steer` 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.
 
 For a correlated Claude turn stopped at `Do you want to proceed?`, use `claude_approval(action: "inspect", ...)` to capture the active operation and SHA-256 screen digest, review the displayed command, then call `respond` with that exact digest and either `approve_once` or `deny`. The relay rechecks the operation and screen under the send lock, never exposes arbitrary input or permanent approval, keeps the active marker intact, and records a prompt-free owner-only receipt. `pty_send(force: true)` does not bypass this boundary.
@@ -542,11 +544,12 @@ npm test           # build, then the node:test regression suite (requires tmux o
 npm link           # put `aiterm-mcp` on PATH locally
 ```
 
-Development uses focused local tests first. GitHub Actions selects tests from the changed implementation's
-dependency graph and expands unknown or release changes to the full suite on the self-hosted
-`macos-native`, `linux-workstation`, and `windows-native` runners. Tag-triggered npm publishing reuses
-the successful main CI for the same commit instead of repeating it, and runs only after the tagged commit
-is confirmed on `origin/main`. The native
+Development uses focused local tests first. GitHub Actions runs the suite on the self-hosted
+`linux-workstation` runner for every push, adds `windows-native` only when Windows-specific files change,
+and runs all three runners (`macos-native`, `linux-workstation`, `windows-native`) once a week as a health
+check. `npm run release -- <version>` syncs the version, commits, tags, and publishes the GitHub Release in
+one command; tag-triggered npm publishing checks only that the tagged commit is on `origin/main` and does not
+wait for another CI run. The native
 Windows runner needs psmux ≥ 3.3.8 and Git for Windows on its PATH, and must run as an
 interactive Windows user; `NETWORK SERVICE` lacks the per-user environment the pane shell and
 harness CLIs rely on and is not a valid runner identity.

package/dist/core.js

@@ -108,6 +108,129 @@ function paneCurrentCommand(name) {
         return "";
     return normalizePaneCommand(r.stdout.trim());
 }
+// ---- pane 入力の到達性（agent が tty の前面か・tty が raw か）----
+// 打鍵が届く先は pane tty の前面プロセスグループだけであり、TUI は raw termios で読む。
+// Codex 0.153 はツール実行のあと、①前面を子 shell（bash）へ返したまま agent が背面（STAT S）で
+// 動き続ける、②前面へ戻っても termios を子 shell の cooked（icanon/echo）のまま残す、の2形を出す
+// （実測 2026-09-04: Codex 席3つが順に該当。貼付本文が bash に落ちて `^[[200~` が生で残り、
+// 打鍵が行バッファに溜まって `^L` が echo された）。どちらも PTY の状態であり aiterm が所有する。
+// 停止（T）だけでなく背面で動く（S）agent も `fg` で前面へ戻せる。判定は OS が直接教える
+// `ps -t <tty>` の STAT `+`／`T` と `stty -f <tty> -a` だけを使い、画面の文字列で推測しない。
+const PANE_TTY_SHELLS = new Set([...SHELLS, "tcsh", "csh", "ksh"]);
+const AGENT_FOREGROUND_RECOVERY_TIMEOUT_MS = 3_000;
+const AGENT_FOREGROUND_RECOVERY_POLL_MS = 200;
+// harness の実プロセスを command 行から見分ける。agent が起動した子（bash -lc、ssh、git 等）は agent ではない。
+const AGENT_COMMAND_PATTERNS = {
+    codex: /(^|[\s/])codex([\s]|$)/,
+    claude: /(^|[\s/])claude([\s]|$)/,
+    grok: /(^|[\s/])grok(-[^\s/]+)?([\s]|$)/,
+    composer: /(^|[\s/])(composer|grok(-[^\s/]+)?)([\s]|$)/,
+    cursor: /(^|[\s/])(cursor-agent|agent)([\s]|$)/,
+};
+/**
+ * `ps -t <tty> -o stat=,command=` の出力を分類する（純粋関数）。
+ * ログイン shell は command が `-zsh` のように先頭 `-` 付きで出るので剥がして判定する。
+ */
+export function classifyPaneTtyProcesses(psOutput, agentPattern = /./) {
+    const state = {
+        agentPresent: false, agentForeground: false, agentStopped: false, toolForeground: false, foregroundShell: null,
+    };
+    for (const raw of psOutput.split("\n")) {
+        const m = raw.trim().match(/^(\S+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const stat = m[1];
+        const command = m[2];
+        const base = ((command.split(/\s+/, 1)[0] ?? "").split("/").pop() ?? "").replace(/^-/, "");
+        if (PANE_TTY_SHELLS.has(base)) {
+            // session leader（STAT の `s`）が pane の login shell。agent が起動した子 shell（`bash -lc …`）は
+            // `s` を持たない。前面の子 shell は「ツール実行中」であり、fg も stty も触らない。
+            if (stat.includes("+")) {
+                if (stat.includes("s"))
+                    state.foregroundShell = base;
+                else
+                    state.toolForeground = true;
+            }
+            continue;
+        }
+        if (!agentPattern.test(command)) {
+            if (stat.includes("+"))
+                state.toolForeground = true;
+            continue;
+        }
+        state.agentPresent = true;
+        if (stat.includes("+"))
+            state.agentForeground = true;
+        if (stat.startsWith("T"))
+            state.agentStopped = true;
+    }
+    return state;
+}
+/** `stty -a` の出力が cooked（icanon または echo が有効）かを判定する（純粋関数）。 */
+export function termiosIsCooked(sttyOutput) {
+    const tokens = sttyOutput.split(/[\s;]+/);
+    return tokens.includes("icanon") || tokens.includes("echo");
+}
+function paneTtyOf(name) {
+    const r = tmux("display-message", "-p", "-t", name, "#{pane_tty}");
+    if (r.code !== 0)
+        return null;
+    const tty = r.stdout.trim();
+    return tty.startsWith("/dev/") ? tty : null;
+}
+/**
+ * agent session への打鍵前に、agent が tty の前面で raw で読める状態にする。
+ * 戻り値は行った回復（"fg" / "fg_stopped" / "stty_raw"）。何もしなければ空。
+ * agent が tty 上に実在しない時は触らない（ready gate が入力受付不能として止める）。
+ */
+export async function ensureAgentOwnsPaneInput(name, kind) {
+    if (isWin)
+        return [];
+    const tty = paneTtyOf(name);
+    if (!tty)
+        return [];
+    const ttyId = tty.replace(/^\/dev\//, "");
+    const psEnv = { ...process.env, LC_ALL: "C" };
+    const observe = () => classifyPaneTtyProcesses(spawnSync("/bin/ps", ["-t", ttyId, "-o", "stat=,command="], { encoding: "utf8", timeout: 5000, env: psEnv }).stdout ?? "", AGENT_COMMAND_PATTERNS[kind]);
+    const recovery = [];
+    let state = observe();
+    // agent が起動したツール／子 shell が前面なら、その tty 状態はツールの物。fg も stty も触らず ready gate に任せる。
+    if (state.toolForeground)
+        return [];
+    if (state.agentPresent && !state.agentForeground) {
+        const wasStopped = state.agentStopped;
+        tmux("send-keys", "-t", name, "C-u");
+        tmux("send-keys", "-l", "-t", name, "fg");
+        tmux("send-keys", "-t", name, "Enter");
+        const deadline = performance.now() + AGENT_FOREGROUND_RECOVERY_TIMEOUT_MS;
+        for (;;) {
+            await sleep(AGENT_FOREGROUND_RECOVERY_POLL_MS);
+            state = observe();
+            if (state.agentForeground)
+                break;
+            if (performance.now() >= deadline) {
+                throw new AitermError(`AGENT_TUI_BACKGROUNDED session=${name} foreground=${state.foregroundShell ?? "不明"}\n` +
+                    "pane tty 上に agent が実在するが前面プロセスグループでなく、fg でも前面へ戻りません。" +
+                    "打鍵は shell に落ちるため送信していません。pty_read(screen:true) で画面を確認してください。", 2);
+            }
+        }
+        recovery.push(wasStopped ? "fg_stopped" : "fg");
+    }
+    if (state.agentPresent && !state.toolForeground) {
+        // 別 tty を指す flag は macOS/BSD が `-f`、Linux（coreutils）が `-F`。OS 差はここ一箇所で吸収する。
+        const ttyFlag = process.platform === "linux" ? "-F" : "-f";
+        const stty = spawnSync("/bin/stty", [ttyFlag, tty, "-a"], { encoding: "utf8", timeout: 5000, env: psEnv });
+        if (stty.status === 0 && termiosIsCooked(stty.stdout ?? "")) {
+            const set = spawnSync("/bin/stty", [ttyFlag, tty, "raw", "-echo"], { encoding: "utf8", timeout: 5000, env: psEnv });
+            if (set.status !== 0) {
+                throw new AitermError(`AGENT_TTY_COOKED session=${name}\n` +
+                    `tty が icanon/echo のままで raw へ戻せません: ${(set.stderr ?? "").trim() || `code=${set.status}`}。送信していません。`, 2);
+            }
+            recovery.push("stty_raw");
+        }
+    }
+    return recovery;
+}
 function paneCurrentCommandForMark(name) {
     const foreground = paneCurrentCommand(name);
     if (!isWin || foreground === "powershell" || foreground === "pwsh")
@@ -2658,6 +2781,9 @@ export async function sendInitialAgentPrompt(name, text, o = {}) {
         throw new AitermError(`agent session '${name}' は起動時 prompt の完了待ちです。初回応答完了後に再度操作してください。`, 2);
     }
     setInitialPromptState(meta, "not_sent");
+    // 起動直後の hooks 実行で bash が前面に残ると ready gate が恒久 false になり、brief 未送信で
+    // 席が巻き戻る（実測 2026-09-04: Codex 0.153 の初回起動が3回中2回）。打鍵の前に前面と raw を整える。
+    await ensureAgentOwnsPaneInput(name, meta.kind);
     let ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
     // 無人Claude起動でCLI自身が順に出す、bypass mode確認とworkspace trustだけを
     // 起動処理の一部として進める。通常turn中の権限確認やMCP承認には触れない。
@@ -2923,6 +3049,37 @@ export function __testCodexConfigureChoices(screen, model, effort) {
 // v0.16.0: 親をブロックする wait 経路は廃止した。send は ready gate と submit 分離を内蔵した
 // dispatch として即返り、event_cursor（送信直前のharness完了正本境界）を receipt で返す。
 // 完了通知は aiterm-wait（--cursor で境界を渡す）、回収は pty_read / claude_turn recover が担う。
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+/**
+ * 画像添付。Claude Code／Codex／Grok／Cursorの4 harnessは、本文に書かれた画像ファイルの絶対パスを
+ * 自分のfile読取toolで開いて画像として見る（実測 2026-09-04: 赤青の試験画像を全harnessが正しく答えた）。
+ * 入力欄へパスを先打鍵する等のharness別操作は不要であり、呼出し側にharnessの癖を覚えさせない。
+ * 添付の表現とpath検査はこの1箇所だけが所有する。検査は外部入力（呼出し側が渡すpath）の境界。
+ */
+export function attachImages(text, images) {
+    if (!images || images.length === 0)
+        return text;
+    const lines = images.map((image, index) => {
+        if (typeof image !== "string" || !path.isAbsolute(image)) {
+            throw new AitermError(`image[${index}] は画像ファイルの絶対パスで指定してください: ${String(image)}`, 2);
+        }
+        if (!IMAGE_EXTENSIONS.has(path.extname(image).toLowerCase())) {
+            throw new AitermError(`image[${index}] の拡張子に対応していません（png/jpg/jpeg/gif/webp）: ${image}`, 2);
+        }
+        let st;
+        try {
+            st = fs.statSync(image);
+        }
+        catch {
+            throw new AitermError(`image[${index}] が読めません: ${image}`, 2);
+        }
+        if (!st.isFile())
+            throw new AitermError(`image[${index}] はfileではありません: ${image}`, 2);
+        return `[aiterm 添付画像 ${index + 1}/${images.length}] ${image}`;
+    });
+    const body = text.trim().length > 0 ? text : "添付画像を確認してください。";
+    return `${body}\n\n${lines.join("\n")}\n添付画像は上のファイルを読んで確認する。`;
+}
 export async function dispatchAgentTurn(name, text, o = {}) {
     assertSessionName(name);
     const meta = loadAgentMetadata(name);
@@ -2941,6 +3098,7 @@ export async function dispatchAgentTurn(name, text, o = {}) {
     const claudeColdStart = meta.kind === "claude"
         && agentCompletionCursor(meta) === 0
         && readClaudeOperationMarker(meta) === null;
+    const paneInputRecovery = await ensureAgentOwnsPaneInput(name, meta.kind);
     if (meta.kind !== "claude" || claudeColdStart) {
         const ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
         if (!ready.ready) {
@@ -3001,6 +3159,7 @@ export async function dispatchAgentTurn(name, text, o = {}) {
         event_cursor: startOffset,
         operation_id: operationId,
         submit_residue: residue.residue,
+        pane_input_recovery: paneInputRecovery,
     };
 }
 export async function steerAgentTurn(name, text) {
@@ -3016,8 +3175,11 @@ export async function steerAgentTurn(name, text) {
         vendor: meta.kind,
         harness: agentHarness(meta.kind),
     };
-    if (!isAgentTuiBusy(meta.kind, captureScreen(name, AGENT_TUI_READY_LINES)))
-        return { ...receipt, delivery: "idle" };
+    // 前面回復は busy 判定より先（bash 前面のままだと画面の実行中マーカーを読んでも打鍵が届かない）。
+    const paneInputRecovery = await ensureAgentOwnsPaneInput(name, meta.kind);
+    if (!isAgentTuiBusy(meta.kind, captureScreen(name, AGENT_TUI_READY_LINES))) {
+        return { ...receipt, delivery: "idle", pane_input_recovery: paneInputRecovery };
+    }
     send(name, text, {
         enter: false,
         force: true,
@@ -3028,7 +3190,7 @@ export async function steerAgentTurn(name, text) {
     });
     await sleep(AGENT_SUBMIT_DELAY_MS);
     sendKey(name, "Enter");
-    return { ...receipt, delivery: "steered" };
+    return { ...receipt, delivery: "steered", pane_input_recovery: paneInputRecovery };
 }
 export async function runClaudeOperation({ session_id: name, action, operation_id: operationIdInput, text, }) {
     assertSessionName(name);

package/dist/index.js

@@ -136,6 +136,11 @@ server.registerTool("pty_send", {
             .describe("非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"),
         rtk: z.boolean().default(false).describe("既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）"),
         raw: z.boolean().default(false).describe("送信前サニタイズを無効化"),
+        image: z
+            .array(z.string())
+            .optional()
+            .describe("添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）。agent session への dispatch だけで使え、" +
+            "harness別の添付手順はaitermが吸収する。通常PTY送信やforce送信では指定できない"),
     },
     outputSchema: {
         schema: z.literal("aiterm.pty-send-result.v1"),
@@ -149,8 +154,10 @@ server.registerTool("pty_send", {
         // dispatch後のsubmit座礁観測（additive）。true=composerに送信textの残存を確認（submit未成立の疑い）/
         // false=残存を観測せず（成立の保証ではない）/ null=通常送信・判定不能。
         submit_residue: z.boolean().nullable(),
+        // 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 }) => {
+}, async ({ session_id, text, enter, mark, force, rtk, raw, image }) => {
     try {
         if (!force && core.isAgentSession(session_id)) {
             if (enter === false)
@@ -159,7 +166,7 @@ server.registerTool("pty_send", {
                 throw new Error("agent session への dispatch は mark:true と併用できません");
             if (rtk)
                 throw new Error("agent session への dispatch は rtk:true と併用できません");
-            const receipt = await core.dispatchAgentTurn(session_id, text, { raw });
+            const receipt = await core.dispatchAgentTurn(session_id, core.attachImages(text, image), { raw });
             const waitProcess = core.agentWaitProcess(receipt.session_id, receipt.event_cursor);
             return {
                 content: [
@@ -180,9 +187,13 @@ server.registerTool("pty_send", {
                     vendor: receipt.vendor,
                     harness: receipt.harness,
                     submit_residue: receipt.submit_residue,
+                    pane_input_recovery: receipt.pane_input_recovery,
                 },
             };
         }
+        if (image && image.length > 0) {
+            throw new Error("image は agent session への dispatch（forceなし）だけで使えます。通常PTY送信では本文にpathを書いてください");
+        }
         const out = core.send(session_id, text, { enter, mark, force, rtk, raw });
         return {
             content: [{ type: "text", text: out }],
@@ -209,6 +220,7 @@ server.registerTool("agent_steer", {
     inputSchema: {
         session_id: z.string(),
         text: z.string().describe("現在のターンへ追加する文字列。UTF-8で最大64KiB"),
+        image: z.array(z.string()).optional().describe("添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）"),
     },
     outputSchema: {
         schema: z.literal("aiterm.agent-steer.v1"),
@@ -218,9 +230,9 @@ server.registerTool("agent_steer", {
         harness: z.enum(["codex-cli", "grok-cli"]),
         delivery: z.enum(["steered", "idle"]),
     },
-}, async ({ session_id, text }) => {
+}, async ({ session_id, text, image }) => {
     try {
-        const receipt = await core.steerAgentTurn(session_id, text);
+        const receipt = await core.steerAgentTurn(session_id, core.attachImages(text, image));
         return {
             content: [{ type: "text", text: `${receipt.delivery} ${receipt.session_id}` }],
             structuredContent: receipt,
@@ -544,13 +556,14 @@ const agentEnvironmentDesc = `通常CLIと同じHOME・cwd・project/user/local
     `delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。`;
 async function launchAgent(kind, args) {
     const supportsWriteScope = kind !== "claude";
-    const { prompt, throughline_source_session, throughline_supplement_file, model, reasoning_effort, env_vars, cwd, session_name, launch_operation_id, write_scope } = args;
+    const { prompt, image, throughline_source_session, throughline_supplement_file, model, reasoning_effort, env_vars, cwd, session_name, launch_operation_id, write_scope } = args;
     try {
         if (!supportsWriteScope && write_scope !== undefined) {
             throw new core.AitermError("claude-code harnessはwrite_scopeに対応していません。指定を外してください", 2);
         }
+        const initialPrompt = image && image.length > 0 ? core.attachImages(prompt ?? "", image) : prompt ?? undefined;
         const [sid, hint, eventCursor, submitResidue] = await core.openAgentWithInitialPrompt(kind, {
-            prompt: prompt ?? undefined,
+            prompt: initialPrompt,
             throughline_source_session,
             throughline_supplement_file,
             model: model ?? undefined,
@@ -660,6 +673,7 @@ server.registerTool("agent_launch", {
     inputSchema: {
         harness: z.enum(["claude-code", "codex-cli", "grok-cli", "cursor-cli"]).describe("agent loop・session・hook・transcript・認証を所有する実行基盤"),
         prompt: z.string().nullish().describe("起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る"),
+        image: z.array(z.string()).optional().describe("初手プロンプトへ添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）"),
         throughline_source_session: z.string().min(1).optional().describe("同一端末のThroughline sessionから読み取り専用contextを初手へ注入する"),
         throughline_supplement_file: z.string().min(1).optional().describe("Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path"),
         model: z.string().nullish().describe("harnessが選ぶモデル。provider名ではなくlive catalog上のmodel ID"),

package/docs/RELEASE.md

@@ -1,53 +1,43 @@
 # Release
 
-Aitermのreleaseはこのrepositoryが所有する。`.github/workflows/product-full-ci.yml`が変更影響選択、3環境runnerと
+Aitermのreleaseはこのrepositoryが所有する。`.github/workflows/product-full-ci.yml`が変更影響選択、runnerと
 製品gateの正本であり、dotagentsの工場CIは横断受入のconsumerであってreleaseを制御しない。
 
-## Version同期
+## CIの範囲
 
-新versionでは次を同じ値へ更新する。
+- push／pull request: `linux-workstation` 1環境。変更した実装の依存graphから試験を選び、依存を確定できない変更は
+  Linuxの全テストへ広げる。Windows固有ファイル（`src/windows-powershell.ts`、`src/psmux-send-worker.ts`、
+  `test/windows-*.test.mjs`）を触った変更だけ`windows-native`を加える。
+- 週1回の定期実行（月曜 03:00 JST）と手動実行だけが、`macos-native`、`linux-workstation`、`windows-native`の
+  3環境で全テストを回す。
+- tag push: 所有確認と、tagged commitが`origin/main`の祖先であることの確認だけを行い、npmへprovenance付きで
+  publishする。同じcommitのmain CIの結果は待たない。
 
-- `package.json`と`package-lock.json`
-- `server.json`
-- `mcpb/manifest.json`
-- `README.md`と`README.ja.md`の現行公開版
-- `CHANGELOG.md`の新version見出し、`Unreleased`比較先、新version比較link
+実測（2026-09-02）: Linux 2分、macOS 2分、Windows 6分。全環境展開ではWindowsが常にcritical pathになる。
 
-同じversionのtagやnpm packageを移動・上書きしない。失敗版はそのまま残し、修正版を次のversionで出す。
-
-## Local gate
+## Release手順
 
-変更に直結するfocused testを通した後、最終確認を一度だけ行う。
+1. 変更に直結するfocused testを手元で通す。full regressionは手元で回さず、CIに任せる。
+2. `CHANGELOG.md`の`## [Unreleased]`へ内容を書き、mainへcommitしてpushする。
+3. 一回で公開する。
 
-```bash
-npm ci
-npm test
-npm pack --dry-run
-npm run mcpb:build
-```
+   ```bash
+   npm run release -- <version>
+   ```
 
-MCPBのstaged serverでversion、16 tools、stderr 0、必要なruntime JavaScriptの同梱を確認する。
+   scriptはversion同期（`package.json`、`package-lock.json`、`server.json`、`mcpb/manifest.json`、`README.md`と`README.ja.md`の現行公開版）、
+   CHANGELOG見出しと比較link、metadata検査、release commit、main push、`v<version>` tag push、
+   MCPB build、GitHub Release作成までを行う。tag pushがnpm publish、Release作成がOfficial MCP Registry登録を起動する。
+   scriptはその完了を待たない。
 
-## Mainと公開
+4. 後で確認する: `npm view aiterm-mcp@<version> version`、Official Registryの`io.github.kitepon/aiterm-mcp`。
 
-1. release commitを`main`へpushする。version・manifest・workflowを含むrelease変更は未分類変更として`macos-native`、`linux-workstation`、`windows-native`の全テストへ広がり、3環境をgreenにする。
-2. `npm run verify:release-commit`で対象commitが`origin/main`の祖先かつworktree cleanであることを確認する。
-3. 同じcommitへ`v<version>` tagを付けてpushする。tag CIは同じcommitのmain CI成功を確認し、3環境試験を再実行せずnpmへprovenance付きでpublishする。
-4. build済みMCPBを添付したGitHub Releaseを公開する。release eventがOfficial MCP Registry登録を起動する。
-5. npm、GitHub Release、Official Registryが同じversionを返すまで確認する。
-
-CI callerは同じrepositoryの`./.github/workflows/product-full-ci.yml`だけを呼ぶ。製品側の変更影響選択、
-全テストへの明示的な拡張、3環境runner、release gateを外部repositoryへ移さず、dotagentsの変更や停止からAitermの受入を独立させる。
+同じversionのtagやnpm packageを移動・上書きしない。失敗版はそのまま残し、修正版を次のversionで出す。
 
 ## 公開後smoke
 
-公式npm packageを隔離またはglobal installし、次を確認する。
-
-- `aiterm-mcp`、`aiterm-wait`、`aiterm-runtime-errors`の3 bins。
-- MCP initializeのversion、16 tools、stderr 0。
-- POSIXはtmux、Windows nativeはpsmux 3.3.8以上とPowerShell 7。
-- 変更に触れたharnessの起動、non-blocking dispatch、wait outcome、transcript回収、`pty_close`後の残骸ゼロ。
-- Official Registryが`io.github.kitepon/aiterm-mcp`の同じversionをactive／latestとして返す。
+公式npm packageを隔離またはglobal installし、変更に触れたharnessの起動、non-blocking dispatch、wait outcome、
+transcript回収、`pty_close`後の残骸ゼロを確認する。
 
 ## 利用者の更新と巻き戻し
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.29.30",
+  "version": "0.30.0",
   "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": [
@@ -60,6 +60,7 @@
     "build": "node scripts/clean-build.mjs && tsc",
     "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",
     "prepublishOnly": "npm run verify:release-commit && npm run build",
     "start": "node dist/index.js",