@ryan_nookpi/pi-skill-tmux-terminal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonghak Seo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @ryan_nookpi/pi-skill-tmux-terminal
+
+TUI, REPL, stdin 입력, 선택 메뉴처럼 실제 터미널 화면이 필요한 프로그램을 전용 tmux 서버로 실행하고 화면 캡처와 키 입력으로 조작하는 스킬입니다. 세션은 Pi 세션 ID로 소유권을 나눠 다른 세션의 화면과 섞이지 않습니다.
+
+## 설치
+
+```bash
+pi install npm:@ryan_nookpi/pi-skill-tmux-terminal
+```
+
+같은 이름의 스킬이 `~/.pi/agent/skills/tmux-terminal` 등 다른 위치에 있으면 Pi는 먼저 찾은 쪽 하나만 씁니다. 기존 로컬 복사본은 지우고 설치하세요.
+
+## 따로 설치해야 하는 것
+
+`tmux`
+
+처음 한 번 설치하는 방법은 [skills/tmux-terminal/references/setup.md](skills/tmux-terminal/references/setup.md)에 있습니다. 스킬도 전제가 빠졌을 때 이 문서를 보고 안내합니다.
+
+## 사용 예
+
+```text
+/skill:tmux-terminal python REPL 띄워서 이 식 계산해줘
+```
+
+요청 내용이 스킬 설명과 맞으면 에이전트가 알아서 불러오므로, 명시적으로 `/skill:tmux-terminal`을 쓰지 않아도 됩니다.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ryan_nookpi/pi-skill-tmux-terminal",
+  "version": "0.1.0",
+  "description": "Pi skill for driving TUI, REPL, and stdin programs through an isolated tmux PTY helper.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jonghakseo/pi-extension.git",
+    "directory": "packages/skill-tmux-terminal"
+  },
+  "bugs": {
+    "url": "https://github.com/Jonghakseo/pi-extension/issues"
+  },
+  "homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/skill-tmux-terminal#readme",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-skill",
+    "tmux",
+    "terminal",
+    "pty"
+  ],
+  "files": [
+    "skills/tmux-terminal/SKILL.md",
+    "skills/tmux-terminal/scripts/tmux-terminal.mjs",
+    "skills/tmux-terminal/references/",
+    "README.md"
+  ],
+  "pi": {
+    "skills": [
+      "./skills/tmux-terminal"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test skills/tmux-terminal/scripts/tmux-terminal.test.mjs"
+  }
+}

package/skills/tmux-terminal/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: tmux-terminal
+description: "TUI, REPL, stdin, selection menu처럼 실제 PTY 화면 캡처와 키 입력이 필요한 터미널을 전용 tmux helper로 안전하게 제어할 때 사용한다. 일반 빌드, 테스트, 서버, 유한 비대화형 명령에는 사용하지 않는다."
+---
+
+# tmux-terminal
+
+`bash_async`는 유한한 비대화형 작업용이다. 이 helper는 TUI, REPL, stdin, 선택 메뉴처럼 PTY 입력과 화면 캡처가 필요한 경우에만 쓴다. 짧은 동기 `bash` 호출로 이 스크립트를 실행한다.
+
+이 도구는 native overlay, attach view, `/attach`, `/dismiss`, 위젯, reattach UI를 제공하지 않는다.
+
+## 시작 전 확인
+
+Pi가 로드한 이 `SKILL.md`의 절대 경로에서 skill 디렉터리를 구한다. 현재 프로젝트 cwd에 `skills/tmux-terminal`이 있다고 가정하지 않는다.
+
+```bash
+# <loaded-skill-dir>는 이 SKILL.md가 들어 있는 절대 디렉터리다.
+SKILL_DIR="<loaded-skill-dir>"
+HELPER="$SKILL_DIR/scripts/tmux-terminal.mjs"
+test -f "$HELPER"
+node "$HELPER" doctor --owner "$PI_SESSION_ID"
+```
+
+`doctor`가 실패하면 이 환경은 지원되지 않는다. 일반 `bash`를 PTY인 것처럼 사용하지 말고, 사용자에게 tmux가 없다고 알린 뒤 [references/setup.md](references/setup.md)의 최초 설치 방법을 안내한다.
+
+모든 세션은 `PI_SESSION_ID` 또는 명시적 `--owner`가 필요하다. 호출마다 같은 owner를 전달한다. 전용 tmux 서버와 owner 메타데이터가 다른 Pi 세션의 화면과 입력을 격리한다.
+
+## Workflow
+
+### 1. 인터랙티브 프로그램 시작
+
+명령은 `--command` 하나에 원문 그대로 전달한다. helper는 mode `0700` 스크립트에 저장한 뒤 gate를 열어 실행하므로 `;`, `&&`, 파이프, 인용, 줄바꿈이 보존된다.
+
+```bash
+node "$HELPER" start --owner "$PI_SESSION_ID" \
+  --title "database prompt" \
+  --command 'psql -d app'
+```
+
+결과 JSON의 `result.session`을 이후 호출에 사용한다. 개발 서버, 빌드, 테스트, headless 유한 명령에는 이 helper를 쓰지 말고 `bash_async`를 사용한다.
+
+### 2. 화면을 확인하고 입력
+
+키를 보내기 전에 항상 capture한다. 커서 위치를 가정하지 말고, `READY`, 메뉴 제목, `>` 같은 안정적인 prompt 텍스트를 찾는다.
+
+```bash
+node "$HELPER" capture --owner "$PI_SESSION_ID" --session "$SESSION" --lines 80
+node "$HELPER" send-keys --owner "$PI_SESSION_ID" --session "$SESSION" --keys Down,Enter
+```
+
+`send-keys`는 `Enter`, `Escape`, 화살표, `C-c`, `C-d`, function key 같은 이름 있는 키만 허용한다. 일반 문자열이나 비밀번호, 여러 줄 입력은 반드시 `paste`로 전달한다.
+
+```bash
+node "$HELPER" paste --owner "$PI_SESSION_ID" --session "$SESSION" --text 'select now();'
+node "$HELPER" send-keys --owner "$PI_SESSION_ID" --session "$SESSION" --key Enter
+```
+
+긴 텍스트는 stdin 또는 파일로 넘길 수 있다. `paste` 입력은 UTF-8 기준 최대 5 MiB이며, 초과한 `--text`, 파일, stdin은 tmux buffer나 임시 파일을 만들기 전에 거절된다.
+
+```bash
+printf 'first line\n둘째 줄\n' | node "$HELPER" paste --owner "$PI_SESSION_ID" --session "$SESSION"
+```
+
+### 3. 상태 확인과 정리
+
+`status`는 pane 종료 여부와 종료 상태를, `capture`는 최대 200줄과 5KB의 화면 텍스트를 JSON `text` 필드로 돌려준다.
+
+```bash
+node "$HELPER" status --owner "$PI_SESSION_ID" --session "$SESSION"
+node "$HELPER" kill --owner "$PI_SESSION_ID" --session "$SESSION"
+# 이 작업에서 만든 owner 세션이 남지 않도록 마지막에 실행
+node "$HELPER" cleanup --owner "$PI_SESSION_ID"
+```
+
+작업에서 만든 세션은 항상 `kill` 또는 `cleanup`한다. `list`와 `cleanup`은 현재 owner의 세션만 대상으로 하며, 다른 owner의 세션을 전역 정리하지 않는다.
+
+## Boundaries
+
+- dedicated tmux server만 사용한다. 사용자의 기본 tmux server를 읽거나 죽이지 않는다.
+- `capture`, `status`, 입력, `kill`은 정확한 owner 메타데이터를 다시 확인한다.
+- owner 검사는 Pi 세션 간 실수 방지 경계다. 같은 OS 사용자가 다른 `--owner`를 사칭하거나 전용 socket에 직접 접근하는 것을 막는 보안 인증 경계는 아니다.
+- 이 helper는 큐, 자동 완료 알림, 영속 로그, 서버 관리 기능이 없다.
+- `TMUX_BIN=/path/to/tmux`로 테스트용 binary를 지정할 수 있다.

package/skills/tmux-terminal/references/setup.md

@@ -0,0 +1,21 @@
+# tmux-terminal 최초 설정
+
+helper는 전용 tmux 서버를 띄워 PTY 화면을 캡처하고 키를 보낸다. `tmux` 실행 파일이 필요하다. Node는 Pi가 이미 쓰고 있으므로 따로 설치하지 않는다.
+
+## 확인
+
+```bash
+node "<이 스킬 디렉터리>/scripts/tmux-terminal.mjs" doctor --owner "$PI_SESSION_ID"
+```
+
+`"ok":true`가 나오면 설정할 것이 없다.
+
+## 설치 (1회)
+
+```bash
+brew install tmux
+```
+
+Homebrew가 없으면 https://brew.sh 의 설치 명령을 먼저 실행한다. Linux는 배포판 패키지(`apt install tmux`, `dnf install tmux`)를 쓴다.
+
+설치 뒤 위 `doctor`를 다시 실행한다. 이 helper는 사용자의 기존 tmux 세션이나 `~/.tmux.conf`와 섞이지 않도록 별도 소켓을 쓴다.

package/skills/tmux-terminal/scripts/tmux-terminal.mjs

@@ -0,0 +1,533 @@
+#!/usr/bin/env node
+import { execFile as execFileCallback, execFileSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { constants as fsConstants, realpathSync } from "node:fs";
+import { access, chmod, mkdir, readFile, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+export const SOCKET_NAME = "pi-tmux-terminal";
+export const MAX_CAPTURE_LINES = 200;
+export const MAX_CAPTURE_BYTES = 5 * 1024;
+export const MAX_PASTE_BYTES = 5 * 1024 * 1024;
+const KEY_NAMES = new Set([
+	"Enter",
+	"Escape",
+	"Tab",
+	"BTab",
+	"Space",
+	"BSpace",
+	"DC",
+	"IC",
+	"Up",
+	"Down",
+	"Left",
+	"Right",
+	"Home",
+	"End",
+	"PPage",
+	"NPage",
+	"C-c",
+	"C-d",
+	"C-z",
+	"C-l",
+	"C-r",
+	"C-u",
+	"C-w",
+	"F1",
+	"F2",
+	"F3",
+	"F4",
+	"F5",
+	"F6",
+	"F7",
+	"F8",
+	"F9",
+	"F10",
+	"F11",
+	"F12",
+]);
+
+export class TerminalError extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+}
+
+export function ownerHash(owner) {
+	return createHash("sha256").update(owner).digest("hex").slice(0, 16);
+}
+
+export function sanitizeSegment(value) {
+	const cleaned = String(value)
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return (cleaned || "owner").slice(0, 32);
+}
+
+export function sessionName(owner, helperId = randomId()) {
+	return `pi-${sanitizeSegment(owner)}-${helperId}`;
+}
+
+export function randomId() {
+	return randomBytes(12).toString("hex");
+}
+
+/** Quote a helper-generated path for the shell tmux uses to launch a pane. */
+export function shellQuote(value) {
+	return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+export function isNamedKey(key) {
+	return KEY_NAMES.has(key);
+}
+
+export function newPasteBuffer(owner) {
+	return `pi-paste-${ownerHash(owner)}-${randomId()}`;
+}
+
+export function truncateCapture(value, maxLines = MAX_CAPTURE_LINES, maxBytes = MAX_CAPTURE_BYTES) {
+	const lines = String(value)
+		.split("\n")
+		.slice(-Math.max(1, Math.min(MAX_CAPTURE_LINES, maxLines)));
+	const text = lines.join("\n");
+	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+
+	const codePoints = Array.from(text);
+	const suffix = [];
+	let bytes = 0;
+	for (let index = codePoints.length - 1; index >= 0; index -= 1) {
+		const width = Buffer.byteLength(codePoints[index], "utf8");
+		if (bytes + width > maxBytes) break;
+		suffix.push(codePoints[index]);
+		bytes += width;
+	}
+	return suffix.reverse().join("");
+}
+
+export function parseTmuxStatus(line) {
+	const [session, owner, helperId, tempPath, title, createdAt, paneDead, paneDeadStatus, panePid, command] = String(
+		line,
+	)
+		.trimEnd()
+		.split("\t");
+	if (!session || owner === undefined)
+		throw new TerminalError("tmux_format", "tmux returned an incomplete status record");
+	return {
+		session,
+		owner,
+		helperId,
+		tempPath,
+		title,
+		createdAt,
+		paneDead: paneDead === "1",
+		paneDeadStatus: paneDeadStatus === "" ? null : Number(paneDeadStatus),
+		panePid: panePid === "" ? null : Number(panePid),
+		command,
+	};
+}
+
+export function parseTmuxList(output) {
+	if (!output.trim()) return [];
+	return output
+		.trimEnd()
+		.split("\n")
+		.map((line) => {
+			const [session, owner, helperId, tempPath, title, createdAt] = line.split("\t");
+			return { session, owner, helperId, tempPath, title, createdAt };
+		});
+}
+
+function tmuxBinary(value = process.env.TMUX_BIN || "tmux") {
+	return value;
+}
+
+async function runTmux(args, options = {}) {
+	const binary = tmuxBinary(options.tmuxBin);
+	try {
+		return await execFile(binary, ["-L", SOCKET_NAME, ...args], { encoding: "utf8", maxBuffer: 1024 * 1024 });
+	} catch (error) {
+		const detail = error.stderr?.trim() || error.message;
+		throw new TerminalError("tmux", detail);
+	}
+}
+
+function resolveOwner(owner) {
+	const value = owner || process.env.PI_SESSION_ID;
+	if (!value) throw new TerminalError("owner_required", "PI_SESSION_ID or --owner is required");
+	if (/[\0\n\t]/.test(value)) throw new TerminalError("invalid_owner", "owner contains an unsupported character");
+	return value;
+}
+
+function ownerRoot(owner) {
+	return join(tmpdir(), "pi-tmux-terminal", ownerHash(owner));
+}
+
+function assertManagedTempPath(owner, tempPath) {
+	const root = resolve(ownerRoot(owner));
+	const candidate = resolve(tempPath);
+	const remaining = relative(root, candidate);
+	if (!remaining || remaining.startsWith("..") || remaining.includes("..")) {
+		throw new TerminalError("temp_path", "session metadata has an unsafe temporary path");
+	}
+	return candidate;
+}
+
+async function removeTempPath(owner, tempPath) {
+	if (!tempPath) return;
+	await rm(assertManagedTempPath(owner, tempPath), { recursive: true, force: true });
+}
+
+async function removeOwnerRootIfEmpty(owner) {
+	try {
+		await rmdir(ownerRoot(owner));
+	} catch (error) {
+		if (error.code !== "ENOENT" && error.code !== "ENOTEMPTY" && error.code !== "EEXIST") throw error;
+	}
+}
+
+async function existingSessions(options = {}) {
+	try {
+		const result = await runTmux(
+			[
+				"list-sessions",
+				"-F",
+				"#{session_name}\t#{@pi_owner}\t#{@pi_helper_id}\t#{@pi_temp_path}\t#{@pi_original_title}\t#{@pi_created_at}",
+			],
+			options,
+		);
+		return parseTmuxList(result.stdout);
+	} catch (error) {
+		if (error instanceof TerminalError && /no server running|no sessions|failed to connect/i.test(error.message))
+			return [];
+		throw error;
+	}
+}
+
+export async function doctor(options = {}) {
+	const binary = tmuxBinary(options.tmuxBin);
+	try {
+		const version = execFileSync(binary, ["-V"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+		let executable = binary;
+		if (!binary.includes("/")) {
+			executable =
+				execFileSync("/usr/bin/which", [binary], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim() ||
+				binary;
+		}
+		return { supported: true, executable, version, socket: SOCKET_NAME };
+	} catch (error) {
+		return {
+			supported: false,
+			executable: binary,
+			reason: `tmux is unavailable: ${error.message.split("\n")[0]}`,
+			socket: SOCKET_NAME,
+		};
+	}
+}
+
+async function statusUnchecked(session, options = {}) {
+	const target = `${session}:0.0`;
+	const result = await runTmux(
+		[
+			"display-message",
+			"-p",
+			"-t",
+			target,
+			"#{session_name}\t#{@pi_owner}\t#{@pi_helper_id}\t#{@pi_temp_path}\t#{@pi_original_title}\t#{@pi_created_at}\t#{pane_dead}\t#{pane_dead_status}\t#{pane_pid}\t#{pane_current_command}",
+		],
+		options,
+	);
+	return parseTmuxStatus(result.stdout);
+}
+
+async function ownedStatus(owner, session, options = {}) {
+	if (!session) throw new TerminalError("session_required", "--session is required");
+	const status = await statusUnchecked(session, options);
+	if (status.owner !== owner) throw new TerminalError("ownership", "session is not owned by this PI session");
+	return status;
+}
+
+function shellPath(shell) {
+	const chosen = shell || "/bin/bash";
+	if (!chosen.startsWith("/") || chosen.includes("\n") || chosen.includes("\0")) {
+		throw new TerminalError("invalid_shell", "--shell must be an absolute executable path");
+	}
+	return chosen;
+}
+
+async function writeExecutable(file, contents) {
+	await writeFile(file, contents, { mode: 0o700, flag: "wx" });
+	await chmod(file, 0o700);
+}
+
+export async function startSession({ owner: inputOwner, command, title = "", shell, tmuxBin } = {}) {
+	const owner = resolveOwner(inputOwner);
+	if (typeof command !== "string" || command.length === 0)
+		throw new TerminalError("command_required", "--command is required");
+	if (typeof title !== "string" || /[\u0000\n\t]/.test(title))
+		throw new TerminalError("invalid_title", "--title cannot contain a tab or newline");
+	const interpreter = shellPath(shell);
+	try {
+		await access(interpreter, fsConstants.X_OK);
+	} catch {
+		throw new TerminalError("invalid_shell", `configured shell is not executable: ${interpreter}`);
+	}
+
+	const helperId = randomId();
+	const session = sessionName(owner, helperId);
+	const root = ownerRoot(owner);
+	const tempPath = join(root, helperId);
+	const commandPath = join(tempPath, "command.sh");
+	const gatePath = join(tempPath, "gate.sh");
+	const markerPath = join(tempPath, "release");
+	let sessionCreated = false;
+	let released = false;
+
+	try {
+		await mkdir(tempPath, { recursive: true, mode: 0o700 });
+		await chmod(tempPath, 0o700);
+		await writeExecutable(commandPath, `#!${interpreter}\n${command}\n`);
+		await writeExecutable(
+			gatePath,
+			`#!/bin/sh\nwhile [ ! -e ${shellQuote(markerPath)} ]; do sleep 0.01; done\nexec ${shellQuote(commandPath)}\n`,
+		);
+
+		// The only shell-parsed pane command is a quote-tested, helper-generated path.
+		await runTmux(["new-session", "-d", "-s", session, shellQuote(gatePath)], { tmuxBin });
+		sessionCreated = true;
+		await runTmux(["set-window-option", "-t", `${session}:0`, "remain-on-exit", "on"], { tmuxBin });
+		const metadata = [
+			["@pi_owner", owner],
+			["@pi_helper_id", helperId],
+			["@pi_temp_path", tempPath],
+			["@pi_original_title", title],
+			["@pi_created_at", new Date().toISOString()],
+		];
+		for (const [key, value] of metadata) {
+			await runTmux(["set-option", "-t", session, key, value], { tmuxBin });
+		}
+		await writeFile(markerPath, "", { mode: 0o600, flag: "wx" });
+		released = true;
+		return { session, owner, helperId, tempPath, title };
+	} catch (error) {
+		if (!released) {
+			if (sessionCreated) {
+				try {
+					await runTmux(["kill-session", "-t", session], { tmuxBin });
+				} catch {
+					/* best effort for only this new session */
+				}
+			}
+			await rm(tempPath, { recursive: true, force: true });
+			// A concurrent same-owner start may have populated the root after our snapshot.
+			await removeOwnerRootIfEmpty(owner);
+		}
+		throw error;
+	}
+}
+
+export async function statusSession({ owner: inputOwner, session, tmuxBin } = {}) {
+	const owner = resolveOwner(inputOwner);
+	return ownedStatus(owner, session, { tmuxBin });
+}
+
+export async function captureSession({ owner: inputOwner, session, lines = MAX_CAPTURE_LINES, tmuxBin } = {}) {
+	const owner = resolveOwner(inputOwner);
+	const status = await ownedStatus(owner, session, { tmuxBin });
+	const requestedLines = Math.max(1, Math.min(MAX_CAPTURE_LINES, Number(lines) || MAX_CAPTURE_LINES));
+	const result = await runTmux(["capture-pane", "-p", "-t", `${status.session}:0.0`, "-S", `-${requestedLines}`], {
+		tmuxBin,
+	});
+	return { ...status, text: truncateCapture(result.stdout, requestedLines, MAX_CAPTURE_BYTES) };
+}
+
+export async function sendKeys({ owner: inputOwner, session, keys, tmuxBin } = {}) {
+	const owner = resolveOwner(inputOwner);
+	const status = await ownedStatus(owner, session, { tmuxBin });
+	if (!Array.isArray(keys) || keys.length === 0) throw new TerminalError("keys_required", "--keys is required");
+	for (const key of keys) {
+		if (!isNamedKey(key))
+			throw new TerminalError(
+				"invalid_key",
+				`literal or unsupported key ${JSON.stringify(key)} rejected, use paste for text`,
+			);
+	}
+	await runTmux(["send-keys", "-t", `${status.session}:0.0`, ...keys], { tmuxBin });
+	return { session: status.session, keys };
+}
+
+export function assertPasteTextSize(text) {
+	if (typeof text !== "string") throw new TerminalError("text_required", "paste text is required");
+	const bytes = Buffer.byteLength(text, "utf8");
+	if (bytes > MAX_PASTE_BYTES) {
+		throw new TerminalError("paste_too_large", `paste input exceeds the ${MAX_PASTE_BYTES}-byte limit`);
+	}
+	return bytes;
+}
+
+export async function pasteSession({ owner: inputOwner, session, text, tmuxBin } = {}) {
+	const bytes = assertPasteTextSize(text);
+	const owner = resolveOwner(inputOwner);
+	const status = await ownedStatus(owner, session, { tmuxBin });
+	const pasteFile = join(assertManagedTempPath(owner, status.tempPath), `.paste-${randomId()}`);
+	const buffer = newPasteBuffer(owner);
+	let loaded = false;
+	try {
+		await writeFile(pasteFile, text, { mode: 0o600, flag: "wx" });
+		await chmod(pasteFile, 0o600);
+		await runTmux(["load-buffer", "-b", buffer, pasteFile], { tmuxBin });
+		loaded = true;
+		await runTmux(["paste-buffer", "-d", "-b", buffer, "-t", `${status.session}:0.0`], { tmuxBin });
+		loaded = false; // -d deletes it after a successful paste
+		return { session: status.session, bytes };
+	} finally {
+		await unlink(pasteFile).catch(() => {});
+		if (loaded) await runTmux(["delete-buffer", "-b", buffer], { tmuxBin }).catch(() => {});
+	}
+}
+
+export async function listOwned({ owner: inputOwner, tmuxBin } = {}) {
+	const owner = resolveOwner(inputOwner);
+	const sessions = await existingSessions({ tmuxBin });
+	return sessions.filter((session) => session.owner === owner);
+}
+
+export async function killSession({ owner: inputOwner, session, tmuxBin } = {}) {
+	const owner = resolveOwner(inputOwner);
+	const status = await ownedStatus(owner, session, { tmuxBin });
+	await runTmux(["kill-session", "-t", status.session], { tmuxBin });
+	await removeTempPath(owner, status.tempPath);
+	return { session: status.session, killed: true };
+}
+
+export async function cleanupOwner({ owner: inputOwner, tmuxBin } = {}) {
+	const owner = resolveOwner(inputOwner);
+	const sessions = await listOwned({ owner, tmuxBin });
+	const removed = [];
+	for (const session of sessions) {
+		// Re-check ownership immediately before destructive work.
+		await killSession({ owner, session: session.session, tmuxBin });
+		removed.push(session.session);
+	}
+	// Never recursively remove the owner root. A same-owner start may have created
+	// a new session directory after listOwned() took its snapshot.
+	await removeOwnerRootIfEmpty(owner);
+	return { owner, removed };
+}
+
+function usage() {
+	return "usage: tmux-terminal.mjs <doctor|start|capture|status|send-keys|paste|list|kill|cleanup> [--owner OWNER]";
+}
+
+function parseCli(argv) {
+	const [action, ...rest] = argv;
+	if (!action) throw new TerminalError("action_required", usage());
+	const options = { action, keys: [] };
+	for (let index = 0; index < rest.length; index += 1) {
+		const token = rest[index];
+		if (!token.startsWith("--")) throw new TerminalError("invalid_argument", `unexpected argument: ${token}`);
+		const key = token.slice(2);
+		const value = rest[index + 1];
+		if (["owner", "session", "command", "title", "shell", "lines", "text", "file", "keys", "key"].includes(key)) {
+			if (value === undefined) throw new TerminalError("invalid_argument", `${token} requires a value`);
+			index += 1;
+			if (key === "key") options.keys.push(value);
+			else if (key === "keys") options.keys.push(...value.split(",").filter(Boolean));
+			else options[key] = value;
+		} else throw new TerminalError("invalid_argument", `unknown option: ${token}`);
+	}
+	return options;
+}
+
+export async function readPasteText(options, stdin = process.stdin) {
+	if (options.text !== undefined) {
+		assertPasteTextSize(options.text);
+		return options.text;
+	}
+	if (options.file) {
+		const file = await stat(options.file);
+		if (file.size > MAX_PASTE_BYTES) {
+			throw new TerminalError("paste_too_large", `paste input exceeds the ${MAX_PASTE_BYTES}-byte limit`);
+		}
+		const text = await readFile(options.file, "utf8");
+		assertPasteTextSize(text);
+		return text;
+	}
+	if (!stdin.isTTY) {
+		const chunks = [];
+		let bytes = 0;
+		for await (const chunk of stdin) {
+			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			bytes += buffer.length;
+			if (bytes > MAX_PASTE_BYTES) {
+				throw new TerminalError("paste_too_large", `paste input exceeds the ${MAX_PASTE_BYTES}-byte limit`);
+			}
+			chunks.push(buffer);
+		}
+		return Buffer.concat(chunks, bytes).toString("utf8");
+	}
+	throw new TerminalError("text_required", "provide --text, --file, or stdin for paste");
+}
+
+export async function main(argv = process.argv.slice(2)) {
+	const options = parseCli(argv);
+	let result;
+	switch (options.action) {
+		case "doctor":
+			result = await doctor(options);
+			process.stdout.write(`${JSON.stringify({ ok: result.supported, ...result })}\n`);
+			if (!result.supported) process.exitCode = 1;
+			return result;
+		case "start":
+			result = await startSession(options);
+			break;
+		case "capture":
+			result = await captureSession(options);
+			break;
+		case "status":
+			result = await statusSession(options);
+			break;
+		case "send-keys":
+			result = await sendKeys(options);
+			break;
+		case "paste":
+			result = await pasteSession({ ...options, text: await readPasteText(options) });
+			break;
+		case "list":
+			result = await listOwned(options);
+			break;
+		case "kill":
+			result = await killSession(options);
+			break;
+		case "cleanup":
+			result = await cleanupOwner(options);
+			break;
+		default:
+			throw new TerminalError("invalid_action", `unsupported action: ${options.action}`);
+	}
+	process.stdout.write(`${JSON.stringify({ ok: true, result })}\n`);
+	return result;
+}
+
+function isDirectExecution(moduleUrl, argvPath) {
+	if (!argvPath) return false;
+	try {
+		return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);
+	} catch {
+		return false;
+	}
+}
+
+if (isDirectExecution(import.meta.url, process.argv[1])) {
+	main().catch((error) => {
+		process.stdout.write(
+			`${JSON.stringify({ ok: false, error: { code: error.code || "error", message: error.message } })}\n`,
+		);
+		process.exitCode = 1;
+	});
+}