@ryan_nookpi/pi-skill-tmux-terminal 0.1.0 → 0.1.2

package/README.md

@@ -12,14 +12,26 @@ pi install npm:@ryan_nookpi/pi-skill-tmux-terminal
 
 ## 따로 설치해야 하는 것
 
-`tmux`
+- macOS 또는 Linux (Windows는 WSL 안에서 실행)
+- `tmux` (`brew install tmux`, `apt install tmux`)
 
-처음 한 번 설치하는 방법은 [skills/tmux-terminal/references/setup.md](skills/tmux-terminal/references/setup.md)에 있습니다. 스킬도 전제가 빠졌을 때 이 문서를 보고 안내합니다.
+Node는 Pi가 쓰는 런타임을 그대로 사용하므로 따로 설치하지 않습니다. 설치와 동작 확인 순서는 [skills/tmux-terminal/references/setup.md](skills/tmux-terminal/references/setup.md)에 있습니다. tmux가 없는 상태에서 스킬을 부르면 에이전트가 설치 명령만 짧게 알려 줍니다. macOS의 tmux 3.6a에서 검증했습니다.
 
 ## 사용 예
 
 ```text
-/skill:tmux-terminal python REPL 띄워서 이 식 계산해줘
+python REPL 띄워서 이 식 계산해줘
+psql 붙어서 이 테이블 스키마 확인해줘
+npm create vite 실행하고 React + TypeScript 골라줘
+ssh로 들어가서 비밀번호 입력하고 로그 꼬리 좀 봐줘
+top 화면 캡처해서 CPU 많이 쓰는 프로세스 알려줘
 ```
 
-요청 내용이 스킬 설명과 맞으면 에이전트가 알아서 불러오므로, 명시적으로 `/skill:tmux-terminal`을 쓰지 않아도 됩니다.
+요청 내용이 스킬 설명과 맞으면 에이전트가 알아서 불러옵니다. 직접 부르려면 `/skill:tmux-terminal <요청>`을 쓰세요.
+
+## 하지 않는 것
+
+- 사용자의 기본 tmux 서버와 `~/.tmux.conf`는 읽지도 않고 건드리지도 않습니다. 전용 소켓만 씁니다.
+- 다른 Pi 세션이 만든 세션은 들여다보거나 종료하지 않습니다.
+- 개발 서버, 빌드, 테스트처럼 화면 입력이 필요 없는 명령에는 쓰지 않습니다. 그쪽은 `bash_async`가 맞습니다.
+- 작업이 끝나면 세션을 남기지 않습니다. 큐, 완료 알림, 영속 로그 같은 기능은 없습니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-skill-tmux-terminal",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Pi skill for driving TUI, REPL, and stdin programs through an isolated tmux PTY helper.",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,8 @@
   ],
   "files": [
     "skills/tmux-terminal/SKILL.md",
-    "skills/tmux-terminal/scripts/tmux-terminal.mjs",
+    "skills/tmux-terminal/scripts/",
+    "!skills/tmux-terminal/scripts/*.test.mjs",
     "skills/tmux-terminal/references/",
     "README.md"
   ],

package/skills/tmux-terminal/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: tmux-terminal
-description: "TUI, REPL, stdin, selection menu처럼 실제 PTY 화면 캡처와 키 입력이 필요한 터미널을 전용 tmux helper로 안전하게 제어할 때 사용한다. 일반 빌드, 테스트, 서버, 유한 비대화형 명령에는 사용하지 않는다."
+description: "TUI·REPL처럼 화면 확인과 키 입력이 필요한 대화형 터미널을 제어할 때 사용한다."
+license: MIT
+compatibility: macOS와 Linux에서만 동작한다(Windows는 WSL 안에서 실행). `tmux` 실행 파일이 필요하고 tmux 3.6a에서 검증했다. Node는 Pi 런타임을 그대로 쓴다. `--command`는 기본적으로 `/bin/bash`에서 실행된다.
 ---
 
 # tmux-terminal
@@ -11,7 +13,7 @@ description: "TUI, REPL, stdin, selection menu처럼 실제 PTY 화면 캡처와
 
 ## 시작 전 확인
 
-Pi가 로드한 이 `SKILL.md`의 절대 경로에서 skill 디렉터리를 구한다. 현재 프로젝트 cwd에 `skills/tmux-terminal`이 있다고 가정하지 않는다.
+스크립트는 Pi가 로드한 이 `SKILL.md`의 절대 경로를 기준으로 실행한다. 현재 프로젝트 cwd에 `skills/tmux-terminal`이 있다고 가정하지 않는다.
 
 ```bash
 # <loaded-skill-dir>는 이 SKILL.md가 들어 있는 절대 디렉터리다.
@@ -21,10 +23,22 @@ test -f "$HELPER"
 node "$HELPER" doctor --owner "$PI_SESSION_ID"
 ```
 
-`doctor`가 실패하면 이 환경은 지원되지 않는다. 일반 `bash`를 PTY인 것처럼 사용하지 말고, 사용자에게 tmux가 없다고 알린 뒤 [references/setup.md](references/setup.md)의 최초 설치 방법을 안내한다.
+서브커맨드와 옵션 전체는 `node "$HELPER" help`로 볼 수 있다.
 
 모든 세션은 `PI_SESSION_ID` 또는 명시적 `--owner`가 필요하다. 호출마다 같은 owner를 전달한다. 전용 tmux 서버와 owner 메타데이터가 다른 Pi 세션의 화면과 입력을 격리한다.
 
+## 실패했을 때 사용자에게 할 말
+
+아래에 해당하면 재시도하지 말고 짧게 안내한 뒤 기다린다. 일반 `bash`를 PTY인 것처럼 대신 쓰지 않는다. 설치 절차는 [references/setup.md](references/setup.md)에 있다.
+
+| 증상 | 사용자에게 할 말 |
+| --- | --- |
+| `doctor`가 `"supported":false` | "`brew install tmux`(Linux는 `apt install tmux`)로 tmux를 설치해 주세요." |
+| Windows 네이티브 환경 | "이 스킬은 macOS·Linux에서만 동작합니다. Windows라면 WSL 안에서 Pi를 실행해 주세요." |
+| `session_not_found` | 세션이 이미 끝났다. `list`로 남은 세션을 확인하고, 필요하면 `start`로 다시 띄운다. |
+| `ownership` | 다른 Pi 세션의 세션이다. 건드리지 않고 자기 owner로 새로 `start`한다. |
+| `invalid_key` | 리터럴 문자열을 `send-keys`로 보냈다. `paste`로 바꿔 보낸다. |
+
 ## Workflow
 
 ### 1. 인터랙티브 프로그램 시작
@@ -48,7 +62,14 @@ 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`로 전달한다.
+`--lines N`은 화면 **아래쪽부터** N줄을 돌려준다. 화면 밑에 남은 빈 줄은 먼저 버리므로 작은 값을 줘도 최신 출력이 빠지지 않는다. 1~200이며 기본값은 200이다. 전체 화면을 봐야 하는 TUI는 기본값을 쓰고, 마지막 프롬프트 한두 줄만 필요하면 `--lines 5`처럼 줄여 컨텍스트를 아낀다.
+
+`send-keys`는 `Enter`, `Escape`, 화살표, `C-c`, `C-d`, function key 같은 이름 있는 키만 허용한다. 키는 두 가지로 지정한다.
+
+- `--key Enter`: 키 하나. 여러 번 반복해 순서대로 보낼 수 있다.
+- `--keys Down,Enter`: 콤마로 구분한 여러 키를 한 번에 보낸다.
+
+일반 문자열이나 비밀번호, 여러 줄 입력은 반드시 `paste`로 전달한다.
 
 ```bash
 node "$HELPER" paste --owner "$PI_SESSION_ID" --session "$SESSION" --text 'select now();'
@@ -67,17 +88,21 @@ printf 'first line\n둘째 줄\n' | node "$HELPER" paste --owner "$PI_SESSION_ID
 
 ```bash
 node "$HELPER" status --owner "$PI_SESSION_ID" --session "$SESSION"
+# 세션 이름을 잃어버렸을 때
+node "$HELPER" list --owner "$PI_SESSION_ID"
 node "$HELPER" kill --owner "$PI_SESSION_ID" --session "$SESSION"
 # 이 작업에서 만든 owner 세션이 남지 않도록 마지막에 실행
 node "$HELPER" cleanup --owner "$PI_SESSION_ID"
 ```
 
-작업에서 만든 세션은 항상 `kill` 또는 `cleanup`한다. `list`와 `cleanup`은 현재 owner의 세션만 대상으로 하며, 다른 owner의 세션을 전역 정리하지 않는다.
+작업에서 만든 세션은 항상 `kill` 또는 `cleanup`한다. `list`와 `cleanup`은 현재 owner의 세션만 대상으로 하며, 다른 owner의 세션을 전역 정리하지 않는다. 이미 사라진 세션을 가리키면 `session_not_found`가 돌아온다.
 
 ## Boundaries
 
 - dedicated tmux server만 사용한다. 사용자의 기본 tmux server를 읽거나 죽이지 않는다.
 - `capture`, `status`, 입력, `kill`은 정확한 owner 메타데이터를 다시 확인한다.
 - owner 검사는 Pi 세션 간 실수 방지 경계다. 같은 OS 사용자가 다른 `--owner`를 사칭하거나 전용 socket에 직접 접근하는 것을 막는 보안 인증 경계는 아니다.
+- `--command`는 `/bin/bash`에서 실행된다. 사용자의 zsh 함수나 alias는 적용되지 않으므로 실행 파일 경로나 완전한 명령을 넘긴다. 다른 인터프리터가 필요하면 `--shell /bin/zsh`처럼 절대 경로로 지정한다.
+- macOS와 Linux에서만 동작한다. Windows 네이티브에는 tmux가 없으므로 WSL 안에서 실행해야 한다.
 - 이 helper는 큐, 자동 완료 알림, 영속 로그, 서버 관리 기능이 없다.
 - `TMUX_BIN=/path/to/tmux`로 테스트용 binary를 지정할 수 있다.

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

@@ -2,20 +2,44 @@
 
 helper는 전용 tmux 서버를 띄워 PTY 화면을 캡처하고 키를 보낸다. `tmux` 실행 파일이 필요하다. Node는 Pi가 이미 쓰고 있으므로 따로 설치하지 않는다.
 
-## 확인
+macOS와 Linux에서만 동작한다. Windows 네이티브에는 tmux가 없으므로 WSL 안에서 Pi를 실행한 뒤 아래 Linux 절차를 따른다.
+
+## 1. 확인
+
+스크립트는 스킬 디렉터리 기준 절대 경로로 실행한다.
 
 ```bash
 node "<이 스킬 디렉터리>/scripts/tmux-terminal.mjs" doctor --owner "$PI_SESSION_ID"
 ```
 
-`"ok":true`가 나오면 설정할 것이 없다.
+`"ok":true`가 나오면 설정할 것이 없다. 3번으로 넘어간다.
+
+## 2. 설치 (1회)
+
+```bash
+brew install tmux        # macOS
+sudo apt install tmux    # Debian, Ubuntu, WSL
+sudo dnf install tmux    # Fedora, RHEL
+```
+
+Homebrew가 없으면 https://brew.sh 의 설치 명령을 먼저 실행한다. 설치 뒤 1번 `doctor`를 다시 실행한다.
+
+## 3. 동작 확인
 
-## 설치 (1회)
+실제로 세션을 띄워 화면이 읽히는지 한 번 확인한다. `HELPER`와 `OWNER`를 각자 값으로 바꾼다.
 
 ```bash
-brew install tmux
+HELPER="<이 스킬 디렉터리>/scripts/tmux-terminal.mjs"
+OWNER="${PI_SESSION_ID:-setup-check}"
+
+node "$HELPER" start --owner "$OWNER" --title setup-check --command 'python3 -q'
+# 위 출력의 result.session 값을 SESSION에 넣는다
+node "$HELPER" paste   --owner "$OWNER" --session "$SESSION" --text '1+1'
+node "$HELPER" send-keys --owner "$OWNER" --session "$SESSION" --key Enter
+node "$HELPER" capture --owner "$OWNER" --session "$SESSION" --lines 5
+node "$HELPER" cleanup --owner "$OWNER"
 ```
 
-Homebrew가 없으면 https://brew.sh 의 설치 명령을 먼저 실행한다. Linux는 배포판 패키지(`apt install tmux`, `dnf install tmux`)를 쓴다.
+`capture`의 `text`에 `>>> 1+1`과 `2`가 보이면 정상이다. 마지막 `cleanup`까지 실행해 세션을 남기지 않는다.
 
-설치 뒤 위 `doctor`를 다시 실행한다. 이 helper는 사용자의 기존 tmux 세션이나 `~/.tmux.conf`와 섞이지 않도록 별도 소켓을 쓴다.
+이 helper는 사용자의 기존 tmux 세션이나 `~/.tmux.conf`와 섞이지 않도록 별도 소켓을 쓴다. 서브커맨드와 옵션 전체는 `node "$HELPER" help`로 볼 수 있다.

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

@@ -92,9 +92,14 @@ export function newPasteBuffer(owner) {
 }
 
 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 limit = Math.max(1, Math.min(MAX_CAPTURE_LINES, maxLines));
+	// tmux always returns the full pane height and `-S -N` prepends scrollback on top
+	// of it, so the tail of the capture is the pane's unused bottom rows. Drop those
+	// before slicing, otherwise a small maxLines yields a screen of blank lines.
+	const all = String(value).split("\n");
+	let end = all.length;
+	while (end > 0 && all[end - 1].trim() === "") end -= 1;
+	const lines = all.slice(Math.max(0, end - limit), end);
 	const text = lines.join("\n");
 	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
 
@@ -232,16 +237,26 @@ export async function doctor(options = {}) {
 
 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,
-	);
+	let result;
+	try {
+		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,
+		);
+	} catch (error) {
+		// The dedicated server exits once its last session is killed.
+		if (error instanceof TerminalError && /no server running|no sessions|failed to connect/i.test(error.message))
+			throw new TerminalError("session_not_found", `no session named ${session}`);
+		throw error;
+	}
+	// tmux exits 0 with empty stdout when the target session no longer exists.
+	if (!result.stdout.trim()) throw new TerminalError("session_not_found", `no session named ${session}`);
 	return parseTmuxStatus(result.stdout);
 }
 
@@ -421,7 +436,33 @@ export async function cleanupOwner({ owner: inputOwner, tmuxBin } = {}) {
 }
 
 function usage() {
-	return "usage: tmux-terminal.mjs <doctor|start|capture|status|send-keys|paste|list|kill|cleanup> [--owner OWNER]";
+	return [
+		"usage: tmux-terminal.mjs <action> [options]",
+		"",
+		"actions:",
+		"  doctor                 report tmux availability for this environment",
+		"  start                  launch --command in a new owned session",
+		"  capture                read the current screen text",
+		"  status                 report pane liveness and exit status",
+		"  send-keys              send named keys (Enter, Down, C-c, ...)",
+		"  paste                  send literal text from --text, --file, or stdin",
+		"  list                   list sessions owned by this owner",
+		"  kill                   kill one owned session",
+		"  cleanup                kill every session owned by this owner",
+		"  help                   print this message",
+		"",
+		"options:",
+		"  --owner OWNER          required, defaults to $PI_SESSION_ID",
+		"  --session NAME         session returned by start",
+		"  --command CMD          start: the command line to run, passed through verbatim",
+		"  --title TEXT           start: human-readable label",
+		"  --shell PATH           start: interpreter for --command (default /bin/bash)",
+		`  --lines N              capture: screen lines to return, 1-${MAX_CAPTURE_LINES} (default ${MAX_CAPTURE_LINES})`,
+		"  --key NAME             send-keys: one named key, repeatable",
+		"  --keys A,B             send-keys: comma-separated named keys",
+		"  --text TEXT            paste: literal text",
+		"  --file PATH            paste: literal text read from a file",
+	].join("\n");
 }
 
 function parseCli(argv) {
@@ -478,6 +519,9 @@ export async function main(argv = process.argv.slice(2)) {
 	const options = parseCli(argv);
 	let result;
 	switch (options.action) {
+		case "help":
+			process.stdout.write(`${usage()}\n`);
+			return { usage: usage() };
 		case "doctor":
 			result = await doctor(options);
 			process.stdout.write(`${JSON.stringify({ ok: result.supported, ...result })}\n`);

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

@@ -0,0 +1,362 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { access, mkdir, mkdtemp, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import {
+	assertPasteTextSize,
+	captureSession,
+	cleanupOwner,
+	doctor,
+	isNamedKey,
+	killSession,
+	listOwned,
+	MAX_PASTE_BYTES,
+	newPasteBuffer,
+	ownerHash,
+	parseTmuxList,
+	parseTmuxStatus,
+	pasteSession,
+	readPasteText,
+	sanitizeSegment,
+	sendKeys,
+	sessionName,
+	shellQuote,
+	startSession,
+	statusSession,
+	TerminalError,
+	truncateCapture,
+} from "./tmux-terminal.mjs";
+
+const owner = (suffix) => `tmux-terminal-test-${suffix}-${process.pid}`;
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function waitForDead(input) {
+	for (let attempt = 0; attempt < 100; attempt += 1) {
+		const status = await statusSession(input);
+		if (status.paneDead) return status;
+		await delay(10); // Poll process scheduling only, never an assumed command duration.
+	}
+	throw new Error(`pane did not exit: ${input.session}`);
+}
+
+function defaultServerSnapshot() {
+	try {
+		return execFileSync("tmux", ["list-sessions", "-F", "#{session_name}"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+	} catch {
+		return "";
+	}
+}
+
+async function start(ownerName, command) {
+	const started = await startSession({ owner: ownerName, command });
+	return started;
+}
+
+test("pure helpers keep owner and generated-shell boundaries deterministic", () => {
+	assert.equal(sanitizeSegment("PI Session / 01"), "pi-session-01");
+	assert.equal(sanitizeSegment("---"), "owner");
+	assert.equal(ownerHash("a"), ownerHash("a"));
+	assert.notEqual(ownerHash("a"), ownerHash("b"));
+	assert.match(sessionName("PI Session", "abc123"), /^pi-pi-session-abc123$/);
+	assert.equal(shellQuote("/tmp/a b/'c'"), "'/tmp/a b/'\"'\"'c'\"'\"''");
+	assert.equal(isNamedKey("Enter"), true);
+	assert.equal(isNamedKey("C-c"), true);
+	assert.equal(isNamedKey("F12"), true);
+	assert.equal(isNamedKey("literal text"), false);
+	assert.notEqual(newPasteBuffer("same"), newPasteBuffer("same"));
+});
+
+test("paste input accepts exactly 5 MiB and rejects larger text, files, and stdin", async (t) => {
+	const exact = "x".repeat(MAX_PASTE_BYTES);
+	assert.equal(assertPasteTextSize(exact), MAX_PASTE_BYTES);
+	assert.throws(
+		() => assertPasteTextSize(`${exact}x`),
+		(error) => error instanceof TerminalError && error.code === "paste_too_large",
+	);
+
+	const directory = await mkdir(join(tmpdir(), `tmux-terminal-paste-limit-${process.pid}`), { recursive: true }).then(
+		() => join(tmpdir(), `tmux-terminal-paste-limit-${process.pid}`),
+	);
+	const exactFile = join(directory, "exact.txt");
+	const oversizedFile = join(directory, "oversized.txt");
+	await writeFile(exactFile, exact);
+	await writeFile(oversizedFile, `${exact}x`);
+	t.after(() => rm(directory, { recursive: true, force: true }));
+	assert.equal((await readPasteText({ file: exactFile })).length, MAX_PASTE_BYTES);
+	await assert.rejects(
+		readPasteText({ file: oversizedFile }),
+		(error) => error instanceof TerminalError && error.code === "paste_too_large",
+	);
+
+	const stdin = {
+		isTTY: false,
+		async *[Symbol.asyncIterator]() {
+			yield Buffer.alloc(MAX_PASTE_BYTES);
+			yield Buffer.from("x");
+		},
+	};
+	await assert.rejects(
+		readPasteText({}, stdin),
+		(error) => error instanceof TerminalError && error.code === "paste_too_large",
+	);
+});
+
+test("capture truncation is line-bounded, byte-bounded, and UTF-8 safe", () => {
+	assert.equal(truncateCapture("one\ntwo\nthree", 2, 1024), "two\nthree");
+	const output = truncateCapture("x한글🙂", 200, 7);
+	assert.ok(Buffer.byteLength(output, "utf8") <= 7);
+	assert.equal(output.includes("�"), false);
+});
+
+test("capture truncation keeps content when the pane's unused bottom rows are blank", () => {
+	// tmux pads every capture to the full pane height, so slicing before dropping the
+	// blank tail used to return an empty screen for any small line budget.
+	const padded = `one\ntwo\nthree${"\n   ".repeat(21)}`;
+	assert.equal(truncateCapture(padded, 2, 1024), "two\nthree");
+	assert.equal(truncateCapture(padded, 1, 1024), "three");
+	assert.equal(truncateCapture("\n\n\n", 5, 1024), "");
+});
+
+test("tmux format parsers retain metadata and dead status", () => {
+	assert.deepEqual(parseTmuxList("s\to\th\t/tmp/x\tt\t2026\n"), [
+		{ session: "s", owner: "o", helperId: "h", tempPath: "/tmp/x", title: "t", createdAt: "2026" },
+	]);
+	const status = parseTmuxStatus("s\to\th\t/tmp/x\tt\t2026\t1\t7\t123\tbash\n");
+	assert.equal(status.paneDead, true);
+	assert.equal(status.paneDeadStatus, 7);
+	assert.equal(status.panePid, 123);
+});
+
+test("doctor reports a usable tmux and a clear unavailable capability", async () => {
+	const available = await doctor();
+	assert.equal(available.supported, true);
+	assert.match(available.version, /^tmux /);
+	const unavailable = await doctor({ tmuxBin: "/definitely/missing/tmux" });
+	assert.equal(unavailable.supported, false);
+	assert.match(unavailable.reason, /unavailable/);
+});
+
+test("CLI entrypoint works through a symlink and preserves doctor exit codes", async (t) => {
+	const directory = await mkdtemp(join(tmpdir(), "tmux-terminal-cli-symlink-"));
+	const script = fileURLToPath(new URL("./tmux-terminal.mjs", import.meta.url));
+	const linkedScript = join(directory, "tmux-terminal.mjs");
+	await symlink(script, linkedScript);
+	t.after(() => rm(directory, { recursive: true, force: true }));
+
+	const available = spawnSync(process.execPath, [linkedScript, "doctor", "--owner", owner("cli")], {
+		encoding: "utf8",
+	});
+	assert.equal(available.status, 0, available.stderr);
+	assert.equal(JSON.parse(available.stdout).supported, true);
+
+	const unavailable = spawnSync(process.execPath, [linkedScript, "doctor", "--owner", owner("cli")], {
+		encoding: "utf8",
+		env: { ...process.env, TMUX_BIN: "/definitely/missing/tmux" },
+	});
+	assert.equal(unavailable.status, 1, unavailable.stderr);
+	const unavailableResult = JSON.parse(unavailable.stdout);
+	assert.equal(unavailableResult.ok, false);
+	assert.equal(unavailableResult.supported, false);
+
+	const help = spawnSync(process.execPath, [linkedScript, "help"], { encoding: "utf8" });
+	assert.equal(help.status, 0, help.stderr);
+	assert.match(help.stdout, /^usage: tmux-terminal\.mjs/);
+	assert.match(help.stdout, /--lines N/);
+});
+
+test("capture returns the newest screen lines even when --lines is below the pane height", async (t) => {
+	const currentOwner = owner("capture-lines");
+	t.after(() => cleanupOwner({ owner: currentOwner }));
+	const started = await start(currentOwner, "printf 'FIRST\\nSECOND\\nTHIRD\\n'; while :; do sleep 1; done");
+	for (let attempt = 0; attempt < 100; attempt += 1) {
+		if ((await captureSession({ owner: currentOwner, session: started.session })).text.includes("THIRD")) break;
+		await delay(10);
+	}
+	// A default pane is 24 rows tall; line budgets below that used to return only blank rows.
+	const narrow = await captureSession({ owner: currentOwner, session: started.session, lines: 3 });
+	assert.deepEqual(narrow.text.split("\n"), ["FIRST", "SECOND", "THIRD"]);
+	assert.equal((await captureSession({ owner: currentOwner, session: started.session, lines: 1 })).text, "THIRD");
+});
+
+test("a missing session reports session_not_found rather than a format failure", async (t) => {
+	const currentOwner = owner("missing-session");
+	t.after(() => cleanupOwner({ owner: currentOwner }));
+	// Keep the dedicated server alive: tmux then answers with empty stdout and exit 0.
+	await start(currentOwner, "sleep 30");
+	const missing = `pi-missing-${process.pid}`;
+	for (const operation of [
+		() => statusSession({ owner: currentOwner, session: missing }),
+		() => captureSession({ owner: currentOwner, session: missing }),
+		() => sendKeys({ owner: currentOwner, session: missing, keys: ["Enter"] }),
+		() => killSession({ owner: currentOwner, session: missing }),
+	]) {
+		await assert.rejects(
+			operation,
+			(error) =>
+				error instanceof TerminalError && error.code === "session_not_found" && error.message.includes(missing),
+		);
+	}
+});
+
+test("gated start preserves compound shell command semantics and immediate exit statuses", async (t) => {
+	const currentOwner = owner("compound");
+	t.after(() => cleanupOwner({ owner: currentOwner }));
+	const zero = await start(currentOwner, "printf one; printf two");
+	const zeroStatus = await waitForDead({ owner: currentOwner, session: zero.session });
+	assert.equal(zeroStatus.paneDeadStatus, 0);
+	assert.match((await captureSession({ owner: currentOwner, session: zero.session })).text, /onetwo/);
+
+	const semantics = await start(currentOwner, "printf 'a b' && printf ' $HOME' | tr a-z A-Z\nprintf '\\n한글'");
+	const semanticStatus = await waitForDead({ owner: currentOwner, session: semantics.session });
+	assert.equal(semanticStatus.paneDeadStatus, 0);
+	const captured = (await captureSession({ owner: currentOwner, session: semantics.session })).text;
+	assert.match(captured, /a b \$HOME/);
+	assert.match(captured, /한글/);
+
+	const seven = await start(currentOwner, "exit 7");
+	assert.equal((await waitForDead({ owner: currentOwner, session: seven.session })).paneDeadStatus, 7);
+});
+
+test("raw selector receives Down then Enter", async (t) => {
+	const currentOwner = owner("selector");
+	t.after(() => cleanupOwner({ owner: currentOwner }));
+	const command =
+		"python3 -u -c \"import sys,tty; tty.setraw(sys.stdin.fileno()); print('READY', flush=True); value=sys.stdin.buffer.read(4); print('SELECTED' if value == b'\\x1b[B\\r' else repr(value), flush=True)\"";
+	const started = await start(currentOwner, command);
+	for (let attempt = 0; attempt < 50; attempt += 1) {
+		if ((await captureSession({ owner: currentOwner, session: started.session })).text.includes("READY")) break;
+		await delay(10);
+	}
+	await sendKeys({ owner: currentOwner, session: started.session, keys: ["Down", "Enter"] });
+	await waitForDead({ owner: currentOwner, session: started.session });
+	assert.match((await captureSession({ owner: currentOwner, session: started.session })).text, /SELECTED/);
+});
+
+test("REPL-style input accepts literal paste, Enter, and Ctrl-C", async (t) => {
+	const currentOwner = owner("repl");
+	t.after(() => cleanupOwner({ owner: currentOwner }));
+	const started = await start(
+		currentOwner,
+		`trap 'printf INT; exit 0' INT; printf READY; IFS= read -r value; printf "GOT:%s" "$value"; while :; do sleep 1; done`,
+	);
+	await pasteSession({ owner: currentOwner, session: started.session, text: "literal $ text" });
+	await sendKeys({ owner: currentOwner, session: started.session, keys: ["Enter"] });
+	for (let attempt = 0; attempt < 50; attempt += 1) {
+		if ((await captureSession({ owner: currentOwner, session: started.session })).text.includes("GOT:literal $ text"))
+			break;
+		await delay(10);
+	}
+	await sendKeys({ owner: currentOwner, session: started.session, keys: ["C-c"] });
+	await waitForDead({ owner: currentOwner, session: started.session });
+	const text = (await captureSession({ owner: currentOwner, session: started.session })).text;
+	assert.match(text, /GOT:literal \$ text/);
+	assert.match(text, /INT/);
+});
+
+test("multiline Unicode paste arrives exactly once and concurrent buffers do not cross", async (t) => {
+	const currentOwner = owner("paste");
+	t.after(() => cleanupOwner({ owner: currentOwner }));
+	const multi = await start(currentOwner, 'IFS= read -r a; IFS= read -r b; printf \'<%s>|<%s>\' "$a" "$b"');
+	await pasteSession({ owner: currentOwner, session: multi.session, text: "하나\n둘\n" });
+	await waitForDead({ owner: currentOwner, session: multi.session });
+	const multiText = (await captureSession({ owner: currentOwner, session: multi.session })).text;
+	assert.equal((multiText.match(/<하나>\|<둘>/g) || []).length, 1);
+
+	const first = await start(currentOwner, "IFS= read -r v; printf 'VALUE:%s' \"$v\"");
+	const second = await start(currentOwner, "IFS= read -r v; printf 'VALUE:%s' \"$v\"");
+	await Promise.all([
+		pasteSession({ owner: currentOwner, session: first.session, text: "alpha\n" }),
+		pasteSession({ owner: currentOwner, session: second.session, text: "bravo\n" }),
+	]);
+	await Promise.all([
+		waitForDead({ owner: currentOwner, session: first.session }),
+		waitForDead({ owner: currentOwner, session: second.session }),
+	]);
+	assert.match((await captureSession({ owner: currentOwner, session: first.session })).text, /VALUE:alpha/);
+	assert.match((await captureSession({ owner: currentOwner, session: second.session })).text, /VALUE:bravo/);
+});
+
+test("owner isolation blocks inspect, input, paste, kill, and cleanup of another owner", async (t) => {
+	const ownerA = owner("owner-a");
+	const ownerB = owner("owner-b");
+	t.after(async () => {
+		await cleanupOwner({ owner: ownerA });
+		await cleanupOwner({ owner: ownerB });
+	});
+	const b = await start(ownerB, "sleep 30");
+	for (const operation of [
+		() => statusSession({ owner: ownerA, session: b.session }),
+		() => captureSession({ owner: ownerA, session: b.session }),
+		() => sendKeys({ owner: ownerA, session: b.session, keys: ["Enter"] }),
+		() => pasteSession({ owner: ownerA, session: b.session, text: "nope" }),
+		() => killSession({ owner: ownerA, session: b.session }),
+	]) {
+		await assert.rejects(operation, (error) => error instanceof TerminalError && error.code === "ownership");
+	}
+	await cleanupOwner({ owner: ownerA });
+	assert.equal((await statusSession({ owner: ownerB, session: b.session })).owner, ownerB);
+});
+
+test("failed start after session creation removes its session and temporary directory", async (t) => {
+	const failedOwner = owner("failed-after-create");
+	const wrapper = join(tmpdir(), `tmux-terminal-fail-wrapper-${process.pid}.sh`);
+	const available = await doctor();
+	await writeFile(
+		wrapper,
+		`#!/bin/sh\nif [ "$3" = set-window-option ]; then echo forced failure >&2; exit 23; fi\nexec ${shellQuote(available.executable)} "$@"\n`,
+		{ mode: 0o700 },
+	);
+	t.after(async () => {
+		await cleanupOwner({ owner: failedOwner });
+		await rm(wrapper, { force: true });
+	});
+
+	await assert.rejects(
+		startSession({ owner: failedOwner, command: "sleep 1", tmuxBin: wrapper }),
+		(error) => error instanceof TerminalError && /forced failure/.test(error.message),
+	);
+	assert.deepEqual(await listOwned({ owner: failedOwner }), []);
+	const failedRoot = join(tmpdir(), "pi-tmux-terminal", ownerHash(failedOwner));
+	const remaining = await readdir(failedRoot).catch((error) => (error.code === "ENOENT" ? [] : Promise.reject(error)));
+	assert.deepEqual(remaining, []);
+});
+
+test("cleanup preserves same-owner temp paths created outside its session snapshot", async (t) => {
+	const currentOwner = owner("cleanup-race");
+	const root = join(tmpdir(), "pi-tmux-terminal", ownerHash(currentOwner));
+	const concurrentPath = join(root, "concurrent-start");
+	await mkdir(concurrentPath, { recursive: true, mode: 0o700 });
+	t.after(() => rm(root, { recursive: true, force: true }));
+
+	await cleanupOwner({ owner: currentOwner });
+	await access(concurrentPath);
+});
+
+test("cleanup is owner-scoped and removes owned temporary files", async (t) => {
+	const failedOwner = owner("cleanup-empty");
+	const goodOwner = owner("good");
+	t.after(async () => {
+		await cleanupOwner({ owner: failedOwner });
+		await cleanupOwner({ owner: goodOwner });
+	});
+	const good = await start(goodOwner, "sleep 30");
+	await cleanupOwner({ owner: failedOwner });
+	assert.equal((await statusSession({ owner: goodOwner, session: good.session })).owner, goodOwner);
+	await cleanupOwner({ owner: goodOwner });
+	await assert.rejects(access(good.tempPath), /ENOENT/);
+});
+
+test("dedicated socket leaves default tmux sessions untouched", async (t) => {
+	const before = defaultServerSnapshot();
+	const currentOwner = owner("default-server");
+	t.after(() => cleanupOwner({ owner: currentOwner }));
+	const started = await start(currentOwner, "printf done");
+	await waitForDead({ owner: currentOwner, session: started.session });
+	assert.equal(defaultServerSnapshot(), before);
+});