aiterm-mcp 0.31.2 → 0.32.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.32.0] - 2026-09-09
+
+### Added
+
+- `aiterm-setup`を追加した。公式package managerによる依存準備、MCP経由の端末実行、検出したClaude Code・Codex・Grok・Cursorへの登録と確認を製品が所有する。対応外・未検出・失敗は公開JSONで区別する。
+
+### Fixed
+
+- Windowsでスラッシュ区切りのcwdを指定したGrok／Composerの完了通知と回答を取得できない問題を修正した。Grok CLIと同じ絶対パスへ正規化して両方の記録を読む。
+- Grok／Composerの次turn開始後に、途中の回答を前turnの完了ID付きで返す問題を修正した。
+- psmuxの最低版を実際のpsmux版数で検証し、winget導入直後の既存PATHからも公式配置を解決する。
+- Windowsでrelease中のnpm起動がENOENTになる問題を修正し、起動元npmのJS入口をNodeで呼ぶ。
+
 ## [0.31.2] - 2026-09-08
 
 ### Fixed
@@ -1570,7 +1583,8 @@ 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.31.2...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.32.0...HEAD
+[0.32.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.2...v0.32.0
 [0.31.2]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.1...v0.31.2
 [0.31.1]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.0...v0.31.1
 [0.31.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.30.0...v0.31.0

package/README.ja.md

@@ -28,6 +28,24 @@
 
 ## MCPクライアントへ導入
 
+検出したClaude Code・Codex・Grok・Cursorのユーザー設定へ登録する標準入口:
+
+```bash
+npm install -g aiterm-mcp@latest
+aiterm-setup --json
+```
+
+`aiterm-setup`は端末の依存準備、MCP経由の端末実行、登録と読戻しまでを一回で行う。
+WindowsはwingetでPowerShell 7・Git for Windows・psmux、macOSはHomebrewでtmux、
+Ubuntu／Debianはsudoとaptでtmuxを準備する。必要な公式package managerと実行権限は事前に必要。
+他のLinuxでも既存tmuxを利用できるが、自動導入は`unsupported`で停止する。
+既存設定の他サーバーを保持し、JSON設定は変更前の`.aiterm-backup`を残す。
+結果の`status`は`ready`／`unsupported`／`failed`。未検出のAIは`not_detected`とし、全AI未検出は成功にしない。
+登録先はglobal packageのNodeとMCP入口の絶対パスで、npm一時cacheやsource checkoutは登録しない。
+更新後も同じ入口を実行し、MCP clientを再起動する。npm install自体はユーザー設定を変更しない。
+公開JSONは`schema: "aiterm.setup-result.v1"`、全体の`status`、端末の`backend`、
+AI別の`integrations`を持つ。失敗時は`reason_code`を付け、終了コードはreadyなら0、それ以外は2となる。
+
 cloneもビルドも不要。どのクライアントでも公開パッケージを次のコマンドで起動する:
 
 ```bash
@@ -153,13 +171,13 @@ runtime-error store は canonical dotagents config の `collection.enabled: true
 場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
 Publishing）で公開し、GitHub Release が Official MCP Registry を再登録します。
 
-**状態:** 開発継続中 · 現行公開版 **v0.31.2** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.32.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
 npm packageが単独配布の正本であり、dotagentsは介在しません。global installは
-`npm install -g aiterm-mcp@latest`で更新します。巻き戻す時は
-`npm install -g "aiterm-mcp@<known-good-version>"`のように既知の正常versionを明示し、MCP clientを再起動します。
+`npm install -g aiterm-mcp@latest`で更新し、`aiterm-setup --json`を再実行します。巻き戻す時は
+`npm install -g "aiterm-mcp@<known-good-version>"`のように既知の正常versionを明示します。setupを持つ版では同じ入口を再実行し、MCP clientを再起動します。
 `npx`設定では`aiterm-mcp@latest`へ変えると更新でき、`aiterm-mcp@<version>`へ変えると固定・巻き戻し
 できます。downgrade前に[変更履歴](CHANGELOG.md)でstate／schema互換を確認してください。maintainer向けの
 公開物とreleaseの巻き戻しは、製品所有の[release手順](docs/RELEASE.md)を正とします。
@@ -293,7 +311,7 @@ Throughline自体が不要である。
 
 ## 最初の実行（約60秒）
 
-Claude Code を再起動して、接続を確認:
+`aiterm-setup --json`が`ready`になったら、利用するMCP clientを再起動して接続を確認する。Claude Codeの場合:
 
 ```bash
 /mcp        # aiterm が connected・16 ツール公開、と出る
@@ -504,9 +522,9 @@ npm test           # build してから node:test 回帰スイート（tmux ま
 npm link           # ローカルで `aiterm-mcp` を PATH に
 ```
 
-開発中は変更に直結するfocused testを先にローカルで実行します。GitHub Actionsはpushごとにself-hostedの
-`linux-workstation` 1環境で試験を回し、Windows固有ファイルを触った変更だけ`windows-native`を加え、
-3環境（`macos-native`、`linux-workstation`、`windows-native`）の全テストは週1回の健康診断だけで回します。
+開発中は変更に直結する試験を先に実行する。GitHub Actionsは共通実装・CI自身・未分類の変更をMac・Linux・Windowsで検証し、
+Windows固有だけの変更はLinuxとWindowsを選ぶ。版番号だけの変更はLinuxの配布情報・pack確認、文書だけなら文書検査を行う。
+試験内容とOSの選択、週次・手動実行の範囲は[公開手順](docs/RELEASE.md)に従う。
 `npm run release -- <version>`がversion同期・commit・tag・GitHub Releaseを一回で行い、tag起点のnpm公開は
 tagged commitが`origin/main`の祖先であることだけを確認して、他のCI結果を待ちません。
 
@@ -514,10 +532,11 @@ tagged commitが`origin/main`の祖先であることだけを確認して、他
 
 ## 試す
 
-1 コマンド、clone もビルドも不要:
+公開packageを導入して、検出したAIへ登録する。cloneやビルドは不要:
 
 ```bash
-claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+npm install -g aiterm-mcp@latest
+aiterm-setup --json
 ```
 
 aiterm が、あなたの AI に別のエージェントへ仕事を渡させたなら——あるいはトークンの往復を 1 回でも省けたなら——**[リポジトリに star](https://github.com/kitepon/aiterm-mcp)** を。他の人に見つけてもらう一番安い方法です。

package/README.md

@@ -28,6 +28,24 @@ Built and maintained by [Quo at kitepon.dev](https://kitepon.dev/en).
 
 ## Install in your MCP client
 
+検出したClaude Code・Codex・Grok・Cursorのユーザー設定へ登録する標準入口:
+
+```bash
+npm install -g aiterm-mcp@latest
+aiterm-setup --json
+```
+
+`aiterm-setup`は端末の依存準備、MCP経由の端末実行、登録と読戻しまでを一回で行う。
+WindowsはwingetでPowerShell 7・Git for Windows・psmux、macOSはHomebrewでtmux、
+Ubuntu／Debianはsudoとaptでtmuxを準備する。必要な公式package managerと実行権限は事前に必要。
+他のLinuxでも既存tmuxを利用できるが、自動導入は`unsupported`で停止する。
+既存設定の他サーバーを保持し、JSON設定は変更前の`.aiterm-backup`を残す。
+結果の`status`は`ready`／`unsupported`／`failed`。未検出のAIは`not_detected`とし、全AI未検出は成功にしない。
+登録先はglobal packageのNodeとMCP入口の絶対パスで、npm一時cacheやsource checkoutは登録しない。
+更新後も同じ入口を実行し、MCP clientを再起動する。npm install自体はユーザー設定を変更しない。
+公開JSONは`schema: "aiterm.setup-result.v1"`、全体の`status`、端末の`backend`、
+AI別の`integrations`を持つ。失敗時は`reason_code`を付け、終了コードはreadyなら0、それ以外は2となる。
+
 No clone or build is required. Each client launches the published package with:
 
 ```bash
@@ -169,13 +187,13 @@ 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.31.2** · 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.32.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
 
 The npm package is the standalone distribution; dotagents is not involved. For a global install,
-update with `npm install -g aiterm-mcp@latest`. To roll back, install a known-good immutable version,
-for example `npm install -g "aiterm-mcp@<known-good-version>"`, then restart the MCP client. For an `npx` configuration,
+update with `npm install -g aiterm-mcp@latest` and `aiterm-setup --json`. To roll back, install a known-good immutable version,
+for example `npm install -g "aiterm-mcp@<known-good-version>"`, then restart the MCP client. setupを持つ版では再起動前に`aiterm-setup --json`を再実行する。For an `npx` configuration,
 use `aiterm-mcp@latest` to update or replace it with `aiterm-mcp@<version>` to pin or roll back.
 Check the [CHANGELOG](CHANGELOG.md) for state/schema compatibility before downgrading. Maintainer
 release and artifact rollback are specified in the product-owned [release procedure](docs/RELEASE.md).
@@ -323,7 +341,7 @@ The only edits to the captures above are the two `⋮` lines (a long head/tail r
 
 ## First run (≈60 seconds)
 
-Restart Claude Code, then verify the connection:
+`aiterm-setup --json`が`ready`になったら、利用するMCP clientを再起動して接続を確認する。Claude Codeの場合:
 
 ```bash
 /mcp        # aiterm should show as connected, exposing 16 tools
@@ -550,10 +568,10 @@ 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 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
+開発中は変更に直結する試験を先に実行する。GitHub Actionsは共通実装・CI自身・未分類の変更をMac・Linux・Windowsで検証し、
+Windows固有だけの変更はLinuxとWindowsを選ぶ。版番号だけの変更はLinuxの配布情報・pack確認、文書だけなら文書検査を行う。
+試験内容とOSの選択、週次・手動実行の範囲は[公開手順](docs/RELEASE.md)に従う。
+`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
@@ -564,10 +582,11 @@ Logic lives in `src/core.ts` (tmux control, reduction, completion detection, saf
 
 ## Try it
 
-One command, no clone, no build:
+公開packageを導入して、検出したAIへ登録する。cloneやビルドは不要:
 
 ```bash
-claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp
+npm install -g aiterm-mcp@latest
+aiterm-setup --json
 ```
 
 If aiterm let your AI hand a task to another agent — or saved you a round-trip of tokens — **[star the repo](https://github.com/kitepon/aiterm-mcp)**. It's the cheapest way to help others find it.

package/dist/core.js

@@ -2169,6 +2169,8 @@ export async function readAgentTranscriptResult(name, o = {}) {
         text = codexTranscriptText(meta, turnId, readTranscriptLines, transcriptUnavailable);
     }
     else {
+        if (!done)
+            transcriptUnavailable();
         text = grokTranscriptText(meta, readTranscriptLines, transcriptUnavailable);
     }
     if (!text.trim())

package/dist/harnesses/grok.js

@@ -71,7 +71,8 @@ export function assertGrokModelAvailable(bin, cwd, model) {
 export function grokSessionDirectory(meta) {
     if ((meta.kind !== "grok" && meta.kind !== "composer") || !meta.grok_home || !meta.vendor_session_id)
         return null;
-    const cwd = meta.cwd ?? process.cwd();
+    // Grok CLIは起動cwdをOSの絶対パスへ正規化して保存する。
+    const cwd = path.resolve(meta.cwd ?? process.cwd());
     return path.join(meta.grok_home, "sessions", encodeURIComponent(cwd), meta.vendor_session_id);
 }
 export function grokEventsTranscript(meta) {
@@ -109,7 +110,9 @@ export function latestGrokCompletion(meta, readTranscriptLines) {
         if (!line.trim())
             continue;
         try {
-            latest = grokCompletionEvent(meta, JSON.parse(line)) ?? latest;
+            const record = JSON.parse(line);
+            // 次のturn開始後は前の完了eventを現在の回答に結び付けない。
+            latest = record?.type === "turn_started" ? null : grokCompletionEvent(meta, record) ?? latest;
         }
         catch {
             // 末尾書込み中のlineは次の観測で完結してから読む。
@@ -321,12 +324,10 @@ export function grokFooterHasConfiguration(screen, model, effort) {
 }
 // 最後のuser発話以降に確定した最後のassistantメッセージをchat_history.jsonlから抽出する。
 export function grokTranscriptText(meta, readTranscriptLines, transcriptUnavailable) {
-    if (!meta.grok_home || !meta.vendor_session_id)
+    const directory = grokSessionDirectory(meta);
+    if (!directory)
         transcriptUnavailable();
-    // cwd 未指定で起動した TUI はサーバープロセスの cwd を継承する。metadata に null が残る既存
-    // launch との互換のため、その実際の起動 cwd を path 導出に使う（launch 側は変更しない）。
-    const cwd = meta.cwd ?? process.cwd();
-    const transcript = path.join(meta.grok_home, "sessions", encodeURIComponent(cwd), meta.vendor_session_id, "chat_history.jsonl");
+    const transcript = path.join(directory, "chat_history.jsonl");
     const lines = readTranscriptLines(transcript);
     let lastUser = -1;
     const records = [];

package/dist/setup-cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runSetup } from "./setup.js";
+const args = process.argv.slice(2);
+if (args.length === 1 && ["--help", "-h"].includes(args[0])) {
+    process.stdout.write("使い方: aiterm-setup [--json]\n製品の依存準備、検出したAIへの登録、MCPと端末の実動作確認を行います。結果はJSONで返します。\n");
+}
+else if (args.length > 1 || (args.length === 1 && args[0] !== "--json")) {
+    process.stderr.write("使い方: aiterm-setup [--json]\n");
+    process.exitCode = 2;
+}
+else {
+    const result = await runSetup();
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = result.status === "ready" ? 0 : 2;
+}

package/dist/setup-integrations.js

@@ -0,0 +1,107 @@
+// AI clientごとの登録形式をここに閉じ込め、setup共通処理へ漏らさない。
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { resolveAgentBin } from "./agent-resolver.js";
+import { SetupError, runSetupCommand } from "./setup-platform.js";
+export { powershellInvocation } from "./setup-platform.js";
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export function mergeJsonMcp(file, registration) {
+    let current = {};
+    let target = file;
+    if (existsSync(file)) {
+        target = realpathSync(file);
+        try {
+            current = JSON.parse(readFileSync(target, "utf8"));
+        }
+        catch {
+            throw new SetupError("config_invalid", "既存設定のJSONを読めません");
+        }
+        if (!record(current) || (current.mcpServers !== undefined && !record(current.mcpServers))) {
+            throw new SetupError("config_invalid", "既存設定とmcpServersはobjectである必要があります");
+        }
+    }
+    else {
+        try {
+            if (lstatSync(file).isSymbolicLink())
+                throw new SetupError("config_invalid", "設定symlinkの参照先がありません");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const servers = (current.mcpServers ?? {});
+    const previous = record(servers.aiterm) ? servers.aiterm : {};
+    const updated = { ...previous, ...registration };
+    if (isDeepStrictEqual(servers.aiterm, updated))
+        return "unchanged";
+    const next = { ...current, mcpServers: { ...servers, aiterm: updated } };
+    mkdirSync(dirname(target), { recursive: true });
+    const temporary = `${target}.aiterm-${randomUUID()}`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        if (existsSync(target))
+            copyFileSync(target, `${target}.aiterm-backup`);
+        renameSync(temporary, target);
+    }
+    finally {
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+    const observed = JSON.parse(readFileSync(target, "utf8"));
+    if (!isDeepStrictEqual(observed.mcpServers?.aiterm, updated)) {
+        throw new SetupError("config_readback_failed", "aiterm登録の読戻しが一致しません");
+    }
+    return "configured";
+}
+export function configureIntegrations(home, registration, run = runSetupCommand, resolveClient = resolveAgentBin) {
+    const results = {};
+    for (const client of ["claude", "codex", "grok", "cursor"]) {
+        try {
+            const executable = resolveClient(client);
+            if (!executable && !(client === "cursor" && existsSync(join(home, ".cursor")))) {
+                results[client] = { status: "not_detected" };
+                continue;
+            }
+            if (client === "claude" || client === "cursor") {
+                const file = client === "cursor" ? join(home, ".cursor", "mcp.json")
+                    : process.env.CLAUDE_CONFIG_DIR ? join(process.env.CLAUDE_CONFIG_DIR, ".claude.json") : join(home, ".claude.json");
+                mergeJsonMcp(file, client === "claude" ? { type: "stdio", ...registration } : registration);
+            }
+            else if (client === "codex") {
+                const servers = JSON.parse(run(executable, ["mcp", "list", "--json"]));
+                if (!Array.isArray(servers))
+                    throw new SetupError("config_readback_failed", "CodexのMCP一覧形式を確認できません");
+                const existing = servers.find((entry) => entry.name === "aiterm");
+                const envArgs = Object.entries(existing?.transport?.env ?? {}).flatMap(([key, value]) => ["--env", `${key}=${value}`]);
+                run(executable, ["mcp", "add", "aiterm", ...envArgs, "--", registration.command, ...registration.args]);
+                const value = JSON.parse(run(executable, ["mcp", "get", "aiterm", "--json"]));
+                if (value.transport?.command !== registration.command || !isDeepStrictEqual(value.transport?.args, registration.args)) {
+                    throw new SetupError("config_readback_failed", "Codexのaiterm登録が一致しません");
+                }
+            }
+            else {
+                const servers = JSON.parse(run(executable, ["mcp", "list", "--json"]));
+                if (!Array.isArray(servers))
+                    throw new SetupError("config_readback_failed", "GrokのMCP一覧形式を確認できません");
+                const existing = servers.find((entry) => entry.name === "aiterm" && entry.scope === "user");
+                const envArgs = Object.entries(existing?.env ?? {}).flatMap(([key, value]) => ["--env", `${key}=${value}`]);
+                run(executable, ["mcp", "add", "--scope", "user", "aiterm", ...envArgs, "--", registration.command, ...registration.args]);
+                const value = JSON.parse(run(executable, ["mcp", "list", "--json"]));
+                // 公開CLIのJSON応答を照合する。未知schemaを成功へ丸めない。
+                const item = Array.isArray(value) ? value.find((entry) => entry.name === "aiterm") : null;
+                if (!item || item.command !== registration.command || !isDeepStrictEqual(item.args, registration.args)) {
+                    throw new SetupError("config_readback_failed", "Grokのaiterm登録が一致しません");
+                }
+            }
+            results[client] = { status: "ready" };
+        }
+        catch (error) {
+            process.stderr.write(`aiterm-setup: ${client}: ${error instanceof Error ? error.message : String(error)}\n`);
+            results[client] = { status: "failed", reason_code: error instanceof SetupError ? error.code : "integration_failed" };
+        }
+    }
+    return results;
+}

package/dist/setup-platform.js

@@ -0,0 +1,77 @@
+// setupのOS差と公式package managerの呼出しを所有する。
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolveWindowsPowerShell7 } from "./windows-powershell.js";
+import { resolveWinPaneShell } from "./agent-resolver.js";
+import { ensureWinPsmux, resolveTmux } from "./tmux-runtime.js";
+export class SetupError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function powershellInvocation(command, args) {
+    const literal = (value) => `'${value.replaceAll("'", "''")}'`;
+    const script = `& ${[command, ...args].map(literal).join(" ")}; if ($null -eq $LASTEXITCODE) { exit 1 }; exit $LASTEXITCODE`;
+    return ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")];
+}
+export const runSetupCommand = (command, args) => {
+    const batch = process.platform === "win32" && /\.(?:cmd|bat)$/iu.test(command);
+    const result = spawnSync(batch ? resolveWindowsPowerShell7() : command, batch ? powershellInvocation(command, args) : args, { encoding: "utf8", windowsHide: true, timeout: 300_000, maxBuffer: 4 * 1024 * 1024 });
+    if (result.error || result.status !== 0) {
+        throw new SetupError("command_failed", `${command}: ${result.error?.message ?? result.stderr?.trim() ?? `exit ${result.status}`}`);
+    }
+    return result.stdout;
+};
+export function dependencyInstallCommand(platform, dependency, linuxId = "") {
+    if (platform === "win32") {
+        const ids = { psmux: "marlocarlo.psmux", pwsh: "Microsoft.PowerShell", git: "Git.Git" };
+        if (ids[dependency])
+            return ["winget.exe", ["install", "--id", ids[dependency], "--exact", "--source", "winget", "--accept-source-agreements", "--accept-package-agreements", "--disable-interactivity"]];
+    }
+    if (dependency === "tmux" && platform === "darwin") {
+        const brew = ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"].find(existsSync) ?? "brew";
+        return [brew, ["install", "tmux"]];
+    }
+    if (dependency === "tmux" && platform === "linux" && ["ubuntu", "debian"].includes(linuxId)) {
+        return ["sudo", ["-n", "apt-get", "install", "--no-remove", "-y", "tmux"]];
+    }
+    throw new SetupError("platform_unsupported", `${platform}/${linuxId}の${dependency}自動導入には対応していません`);
+}
+export function prepareBackend(run = runSetupCommand) {
+    const platform = process.platform;
+    const linuxId = platform === "linux" ? /^ID=["']?([^"'\r\n]+)/mu.exec(readFileSync("/etc/os-release", "utf8"))?.[1] ?? "" : "";
+    const ensure = (name, probe) => {
+        try {
+            probe();
+            return;
+        }
+        catch (error) {
+            // 失敗を隠さず、製品の正規導入で修復してから同じprobeを再実行する。
+            process.stderr.write(`aiterm-setup: ${name}を準備します（${error instanceof Error ? error.message : String(error)}）\n`);
+        }
+        const [command, args] = dependencyInstallCommand(platform, name, linuxId);
+        if (platform === "linux")
+            run("sudo", ["-n", "apt-get", "update"]);
+        run(command, args);
+        probe();
+    };
+    if (platform === "win32") {
+        ensure("pwsh", () => resolveWindowsPowerShell7());
+        ensure("git", () => resolveWinPaneShell("bash"));
+        if (process.env.AITERM_PSMUX)
+            ensureWinPsmux(false);
+        else
+            ensure("psmux", () => ensureWinPsmux(false));
+    }
+    else if (platform === "darwin" || platform === "linux") {
+        if (process.env.AITERM_TMUX)
+            resolveTmux(false);
+        else
+            ensure("tmux", () => resolveTmux(false));
+    }
+    else {
+        throw new SetupError("platform_unsupported", `${platform}には対応していません`);
+    }
+}

package/dist/setup.js

@@ -0,0 +1,88 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { prepareBackend, runSetupCommand, SetupError } from "./setup-platform.js";
+import { configureIntegrations } from "./setup-integrations.js";
+export function globalRegistration(run = runSetupCommand) {
+    const root = run(process.platform === "win32" ? "npm.cmd" : "npm", ["root", "-g"]).trim();
+    if (!isAbsolute(root) || /[\r\n]/u.test(root))
+        throw new SetupError("global_package_required", "npm global rootを確認できません");
+    const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const installedRoot = join(root, "aiterm-mcp");
+    if (realpathSync(installedRoot) !== realpathSync(packageRoot)) {
+        throw new SetupError("global_package_required", "npm install -g aiterm-mcp後にaiterm-setupを実行してください。一時npm cacheやsource checkoutは登録しません");
+    }
+    return { command: process.execPath, args: [join(installedRoot, "dist", "index.js")] };
+}
+export async function verifySetupRuntime(registration) {
+    const client = new Client({ name: "aiterm-setup", version: "1.0.0" });
+    const transport = new StdioClientTransport({ ...registration, stderr: "pipe" });
+    transport.stderr?.on("data", (chunk) => process.stderr.write(chunk));
+    const name = `setup-${randomUUID().slice(0, 12)}`;
+    const call = async (tool, args) => {
+        const result = await client.request({ method: "tools/call", params: { name: tool, arguments: args } }, CallToolResultSchema, { timeout: 25_000 });
+        if (result.isError)
+            throw new SetupError("runtime_probe_failed", `${tool}が失敗しました`);
+        return result;
+    };
+    await client.connect(transport);
+    try {
+        await call("pty_open", { name, shell: process.platform === "win32" ? "pwsh" : "bash" });
+        try {
+            const text = process.platform === "win32" ? "Write-Output ('aiterm-' + 'ready')" : "printf 'aiterm-%s\\n' ready";
+            await call("pty_send", { session_id: name, text, mark: true });
+            const result = await call("pty_read", { session_id: name, wait: true, until: "aiterm-ready", timeout: 15, raw: true });
+            const output = result.content.filter((item) => item.type === "text").map((item) => item.text).join("\n");
+            if (!output.includes("aiterm-ready"))
+                throw new SetupError("runtime_probe_failed", "端末の実行結果を確認できません");
+        }
+        finally {
+            await call("pty_close", { session_id: name });
+        }
+    }
+    finally {
+        await client.close();
+    }
+}
+export async function runSetup(options = {}) {
+    const result = { schema: "aiterm.setup-result.v1", status: "failed", backend: { kind: process.platform === "win32" ? "psmux" : "tmux", status: "failed" }, integrations: {} };
+    const progress = options.progress ?? ((message) => process.stderr.write(`aiterm-setup: ${message}\n`));
+    let stage = "backend";
+    try {
+        progress("端末の依存製品を確認します");
+        (options.prepare ?? prepareBackend)();
+        // Windowsのnpm.cmd実行に必要なPowerShell 7も、global root照会より先に導入する。
+        stage = "global_package";
+        const registration = (options.registration ?? globalRegistration)();
+        stage = "backend";
+        progress("MCP経由で端末を開き、実行結果と終了を確認します");
+        await (options.verify ?? verifySetupRuntime)(registration);
+        result.backend.status = "ready";
+        stage = "integrations";
+        progress("検出したAI clientのaiterm登録を更新して確認します");
+        result.integrations = (options.configure ?? configureIntegrations)(process.env.HOME ?? homedir(), registration);
+        if (Object.values(result.integrations).some((item) => item.status === "failed")) {
+            result.reason_code = "integration_failed";
+        }
+        else if (!Object.values(result.integrations).some((item) => item.status === "ready")) {
+            result.status = "unsupported";
+            result.reason_code = "clients_not_detected";
+        }
+        else
+            result.status = "ready";
+    }
+    catch (error) {
+        const code = error instanceof SetupError ? error.code : `${stage}_failed`;
+        result.status = code === "platform_unsupported" ? "unsupported" : "failed";
+        result.reason_code = code;
+        if (stage === "backend")
+            result.backend = { ...result.backend, status: result.status, reason_code: code };
+        progress(error instanceof Error ? error.message : String(error));
+    }
+    return result;
+}

package/dist/tmux-runtime.js

@@ -24,10 +24,20 @@ export const WIN_NS = `aiterm-${createHash("sha1").update(SOCKDIR).digest("hex")
 // psmux は tmux CLI 互換の Windows ネイティブ実装（ConPTY・WSL 不要）。AITERM_PSMUX で
 // バイナリを明示上書きできる（POSIX の AITERM_TMUX に対応）。
 function psmuxBin() {
-    return process.env.AITERM_PSMUX || "psmux";
+    if (process.env.AITERM_PSMUX)
+        return process.env.AITERM_PSMUX;
+    const wingetLink = process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, "Microsoft", "WinGet", "Links", "psmux.exe");
+    return wingetLink && fs.existsSync(wingetLink) ? wingetLink : "psmux";
+}
+export function psmuxVersionSupported(output) {
+    const match = /^psmux (\d+)\.(\d+)\.(\d+)(?:\s|$)/mu.exec(output);
+    if (!match)
+        return false;
+    const [major, minor, patch] = match.slice(1).map(Number);
+    return major > 3 || (major === 3 && (minor > 3 || (minor === 3 && patch >= 8)));
 }
 let winPsmuxOk = false;
-function ensureWinPsmux(observe = true) {
+export function ensureWinPsmux(observe = true) {
     if (winPsmuxOk)
         return;
     const r = spawnSync(psmuxBin(), ["-V"], { encoding: "utf8", timeout: 10000 });
@@ -39,6 +49,8 @@ function ensureWinPsmux(observe = true) {
     }
     if (r.status !== 0)
         ptyDependencyError("psmux -V が失敗しました。`psmux -V` が通るか確認してください。", observe);
+    if (!psmuxVersionSupported(r.stdout ?? ""))
+        ptyDependencyError("psmux 3.3.8以上が必要です。winget upgrade --id marlocarlo.psmux --source winget で更新してください。", observe);
     winPsmuxOk = true;
 }
 // tmux が見つからないときの説明。macOS は tmux を同梱せず、Homebrew の bin は GUI 起動時の PATH に

package/dist/windows-powershell.js

@@ -16,12 +16,11 @@ export function resolveWindowsPowerShell7(probe = defaultProbe) {
     const located = probe("where.exe", [WINDOWS_POWERSHELL_7_COMMAND]);
     const resolved = located.stdout?.split(/\r?\n/u)
         .find(candidate => path.win32.isAbsolute(candidate)
-        && path.win32.basename(candidate).toLowerCase() === WINDOWS_POWERSHELL_7_COMMAND);
+        && path.win32.basename(candidate).toLowerCase() === WINDOWS_POWERSHELL_7_COMMAND)
+        ?? path.win32.join(process.env.ProgramFiles ?? "C:\\Program Files", "PowerShell", "7", WINDOWS_POWERSHELL_7_COMMAND);
     const fail = () => {
         throw new AitermError(`PowerShell 7が必要です。Microsoft公式経路で導入してください: ${WINDOWS_POWERSHELL_7_INSTALL}`, 2);
     };
-    if (located.status !== 0 || typeof resolved !== "string")
-        fail();
     const executable = resolved;
     const version = probe(executable, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command",
         '[ordered]@{ edition = $PSVersionTable.PSEdition; major = $PSVersionTable.PSVersion.Major } | ConvertTo-Json -Compress']);

package/docs/00_overview.md

@@ -5,7 +5,7 @@ dotagentsは任意の工場統合を担うが、Aitermの製品正典や実行
 
 ## 現行正典
 
-- [README](../README.md)／[日本語README](../README.ja.md): 公開API、install、利用、復旧。
+- [README](../README.md)／[日本語README](../README.ja.md): 公開API、`aiterm-setup`による依存準備とAI登録、利用、復旧。
 - [AGENTS](https://github.com/kitepon/aiterm-mcp/blob/main/AGENTS.md): AI作業者向けの製品境界と変更規律。
 - [DESIGN](DESIGN.md): 現行アーキテクチャと不変条件。
 - [RELEASE](RELEASE.md): version同期、検証、公開、公開後smoke、巻き戻し。

package/docs/DESIGN.md

@@ -6,6 +6,16 @@ Aitermは、AIがローカルshell、SSH、container、REPL、別agentの対話T
 操作するstdio MCP serverである。install、session、state、schema、diagnostics、recovery、releaseは
 このrepositoryが所有し、外部の工場管理製品がなくても単独で動く。
 
+## 導入と登録
+
+`aiterm-setup`はglobal packageからだけ実行し、依存準備、公開MCP経由の端末実行、
+検出したAIのユーザー設定への登録と読戻しを連続実行する。npm lifecycleでユーザー設定を変更しない。
+共通の順序と結果は`src/setup.ts`、公式package managerとOS差は`src/setup-platform.ts`、
+各AIの登録形式は`src/setup-integrations.ts`が所有する。既存の他サーバーは保持し、
+Claude／CursorのJSONは参照先を原子的に更新して変更前backupを残す。Codex／Grokは公式CLIで登録・確認する。
+各AIの読戻しは登録内容の確認であり、端末の実動作はその前の公開MCP試験で確認する。
+失敗は理由付きJSONと非ゼロ終了で返す。対応外の自動導入と全AI未検出を成功扱いしない。
+
 ## Terminal model
 
 プリミティブはlocal PTYを1つ開き、text／keyを送り、画面を読み、閉じることだけである。
@@ -26,6 +36,7 @@ Throughlineの補足記憶はpathを透過搬送するだけで、内容、proje
 agent turnは常に非ブロックdispatchである。receiptの`event_cursor`がturn境界、`wait_process`が
 platform nativeな別process起動情報を返す。waiterは純readerで、親のforeground turnを塞がない。
 回答はharness所有transcriptから同じturnへ相関して回収し、欠落・曖昧・timeout時にpromptを再送しない。
+Grok／Composerの記録先はCLIと同じOS絶対パスへcwdを正規化して導出し、完了通知と回答で同じ関数を使う。
 `agent_steer`は実行中のCodex／Grok turnへ追加textを差し込み、idleなら送信せず状態を返す。
 Cursorのsubmitはadapterがextended keyboard protocolのEnterへ変換し、呼び出し側は通常のdispatchだけを使う。
 起動直後のClaude sessionへの初回dispatchは、他harnessと同じくTUIの入力受付を確認してから貼付とEnterを送る。

package/docs/RELEASE.md

@@ -5,16 +5,15 @@ Aitermのreleaseはこのrepositoryが所有する。`.github/workflows/product-
 
 ## CIの範囲
 
-- 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環境で全テストを回す。
+- push／pull request: 共通実装・CI自身・未分類の変更は`macos-native`、`linux-workstation`、`windows-native`を選ぶ。
+  Windows固有ファイル（`src/windows-powershell.ts`、`src/psmux-send-worker.ts`、`test/windows-*.test.mjs`）だけの変更は
+  LinuxとWindowsを選ぶ。共通変更が混ざっても対象OSを落とさない。試験は依存graphから選び、依存を確定できない変更だけ全テストへ広げる。
+- 版番号だけの変更はJSONの実差分で識別し、Linuxでbuildと配布metadata・pack・文書確認を行う。依存や実行設定の変更は省略しない。
+  文書だけなら文書検査、実装と文書の混在なら関連試験と文書検査を行う。
+- 週1回の定期実行（月曜 03:00 JST）と手動実行は、指定された環境で全テストを回す。定期実行の対象は3環境である。
 - tag push: 所有確認と、tagged commitが`origin/main`の祖先であることの確認だけを行い、npmへprovenance付きで
   publishする。同じcommitのmain CIの結果は待たない。
 
-実測（2026-09-02）: Linux 2分、macOS 2分、Windows 6分。全環境展開ではWindowsが常にcritical pathになる。
-
 ## Release手順
 
 1. 変更に直結するfocused testを手元で通す。full regressionは手元で回さず、CIに任せる。
@@ -36,6 +35,10 @@ Aitermのreleaseはこのrepositoryが所有する。`.github/workflows/product-
 
 ## 公開後smoke
 
+setupを変更した場合は、公開packageのglobal install後に`aiterm-setup --json`を実行し、
+端末実行と検出した各AIの登録結果を確認する。初回と再実行は一時設定領域でも試験し、所有外の設定保持を確かめる。
+WindowsのGrokパス変更ではスラッシュ区切りcwdで起動し、同じturnの完了通知と回答回収を確認する。
+
 公式npm packageを隔離またはglobal installし、変更に触れたharnessの起動、non-blocking dispatch、wait outcome、
 transcript回収、`pty_close`後の残骸ゼロを確認する。
 
@@ -46,13 +49,21 @@ timeoutや再送案内へ変わらないことを確認する。拒否を検証
 
 ## 利用者の更新と巻き戻し
 
-global installはnpmの公開packageだけで完結する。
+更新はnpmの公開packageから行う。
 
 ```bash
 npm install -g aiterm-mcp@latest
+aiterm-setup --json
+```
+
+巻き戻しは既知の正常版を指定する。
+
+```bash
 npm install -g "aiterm-mcp@<known-good-version>"
 ```
 
+setupを持つ版では`aiterm-setup --json`を再実行する。どちらもMCP clientを再起動する。
+
 `npx`をMCP設定から使う場合は、package引数を`aiterm-mcp@latest`へ変えると更新でき、
 `aiterm-mcp@<known-good-version>`へ変えると固定・巻き戻しできる。変更後はMCP clientを再起動する。
 dotagentsの導入・更新は不要である。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.31.2",
+  "version": "0.32.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": [
@@ -40,6 +40,7 @@
   "type": "module",
   "bin": {
     "aiterm-mcp": "dist/index.js",
+    "aiterm-setup": "dist/setup-cli.js",
     "aiterm-runtime-errors": "dist/runtime-errors-cli.js",
     "aiterm-wait": "dist/aiterm-wait-cli.js"
   },