@zhuxixi/pi-agent-board 0.10.2 → 0.11.1

package/CHANGELOG.md

@@ -5,6 +5,22 @@ conventional commits by `scripts/release_helper.mjs`. Entries are
 forward-only: they begin with the first release after this file landed —
 for earlier history, see the git log and the pull-request list.
 
+## [0.11.1] - 2026-10-13
+
+### Fixes
+
+- **attach**: defer color-scheme reports until child input is ready (#180)
+
+[0.11.1]: https://github.com/zhuxixi/pi-agent-board/compare/v0.11.0...v0.11.1
+
+## [0.11.0] - 2026-10-12
+
+### Features
+
+- **attach**: mirror pi's fullscreen selection into X11 PRIMARY + paste-source override (#177)
+
+[0.11.0]: https://github.com/zhuxixi/pi-agent-board/compare/v0.10.2...v0.11.0
+
 ## [0.10.2] - 2026-10-10
 
 ### Fixes

package/docs/superpowers/plans/2026-10-10-issue-174-selection-mirror-paste-source.md

@@ -0,0 +1,510 @@
+# Issue #174 Selection Mirror + Paste Source Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close the fullscreen select→middle-click-paste loop: mirror pi's (final) selection text into X11 PRIMARY when a selection gesture ends inside the attach view (B2), and add an opt-in `AGENT_BOARD_ATTACH_PASTE_SOURCE=primary|clipboard` paste-source override (C).
+
+**Architecture:** Two pure decision helpers in `src/core/pty-scroll.mjs` (`resolvePasteSelectionSource`, `shouldMirrorSelectionToPrimary`); `PtyAttachComponent.handleMouse` observes left release/click (returns `undefined`, consumes nothing) and schedules a `process.nextTick` mirror that reads `TuiAltScreen.getActiveSelectionText()` and reuses `writePrimarySelection`; `pastePrimarySelection` parameterizes its `-selection` argument from the env knob. pi's own selection behavior is untouched.
+
+**Tech Stack:** TypeScript (tabs), node:test + assert/strict, node --experimental-transform-types scenario with a PATH-stubbed bidirectional `xclip`.
+
+**Spec:** `docs/superpowers/specs/2026-10-10-issue-174-selection-mirror-paste-source-design.md` (acceptance IDs A1–A5, U1). Cross-review waived by user decision (recorded in the issue research dir).
+
+## Global Constraints
+
+- Work ONLY inside the worktree `<WT>` (branch `issue-174-selection-mirror-paste-source`); never touch main.
+- Tabs for indentation; English comments and commit messages; conventional commit subjects.
+- Pure-function split is a hard spec constraint: both helpers take resolved values (no `process.env` reads inside); must not be re-inlined into the component.
+- `handleMouse` must remain the ONLY mirror scheduling point; `writePrimarySelection`/`pastePrimarySelection` remain the only xclip touch points.
+- The mirror branch must return `undefined` (observe only) — pi's fullscreen selection keeps every left-button event. No changes to #169's ownership model, #171's paste decision behavior, or regular-mode behavior.
+- The kill switch `AGENT_BOARD_ATTACH_NATIVE_PASTE=0` must disable BOTH the mirror and the paste.
+- Tests use `node:test` with self-contained fixtures under temp dirs; never the host repository.
+- `test/` and `test-support/` are EXCLUDED from tsc — scenario files are runtime-transformed only; `src/` must stay `npm run typecheck`-clean.
+
+---
+
+### Task 1: Pure decision helpers (A1)
+
+**Files:**
+- Modify: `src/core/pty-scroll.mjs` (add exports next to `resolveAttachMouseAction` / `shouldOwnOuterMouseMode`)
+- Test: `test/pty-scroll.test.mjs` (extend the existing import block and append tests)
+
+**Interfaces:**
+- Consumes: none.
+- Produces: `resolvePasteSelectionSource(value) → "primary" | "clipboard"` (value = the raw `AGENT_BOARD_ATTACH_PASTE_SOURCE` env string or undefined; unknown → `"primary"`) and `shouldMirrorSelectionToPrimary(event, { nativePasteEnabled }) → "mirror-primary" | null`. Tasks 2–3 import both from `../core/pty-scroll.mjs`.
+
+- [ ] **Step 1: Write the failing tests**
+
+In `test/pty-scroll.test.mjs`, extend the existing import from `../src/core/pty-scroll.mjs` with `resolvePasteSelectionSource` and `shouldMirrorSelectionToPrimary`, then append:
+
+```js
+test("resolvePasteSelectionSource: clipboard opt-in, everything else primary", () => {
+	assert.equal(resolvePasteSelectionSource(undefined), "primary");
+	assert.equal(resolvePasteSelectionSource(""), "primary");
+	assert.equal(resolvePasteSelectionSource("primary"), "primary");
+	assert.equal(resolvePasteSelectionSource("clipboard"), "clipboard");
+	assert.equal(resolvePasteSelectionSource(" CLIPBOARD "), "clipboard");
+	assert.equal(resolvePasteSelectionSource("garbage"), "primary");
+});
+
+test("shouldMirrorSelectionToPrimary: only selection endings of the left button with paste enabled", () => {
+	assert.equal(shouldMirrorSelectionToPrimary(ev("release", "left"), { nativePasteEnabled: true }), "mirror-primary");
+	assert.equal(shouldMirrorSelectionToPrimary(ev("click", "left"), { nativePasteEnabled: true }), "mirror-primary");
+	assert.equal(shouldMirrorSelectionToPrimary(ev("release", "left"), { nativePasteEnabled: false }), null);
+	assert.equal(shouldMirrorSelectionToPrimary(ev("click", "left"), { nativePasteEnabled: false }), null);
+	const cases = [
+		["press", "left"],
+		["move", "left"],
+		["drag", "left"],
+		["wheel", "left"],
+		["release", "middle"],
+		["release", "right"],
+		["release", "none"],
+		["click", "middle"],
+		["click", "none"],
+	];
+	for (const [type, button] of cases) {
+		assert.equal(shouldMirrorSelectionToPrimary(ev(type, button), { nativePasteEnabled: true }), null, `${type}/${button}`);
+	}
+});
+```
+
+(`ev` helper already exists in this file from #171 — reuse it, do not redefine.)
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `node --test test/pty-scroll.test.mjs`
+Expected: FAIL — the two helpers are not exported.
+
+- [ ] **Step 3: Implement**
+
+In `src/core/pty-scroll.mjs`, next to `resolveAttachMouseAction`:
+
+```js
+/**
+ * Issue #174 (C): which X11 selection buffer middle-click paste reads.
+ * "primary" = classic X11 middle-click semantics (default); "clipboard" =
+ * escape hatch for environments where PRIMARY never updates (e.g. WSLg).
+ * Unknown or unset values fall back to "primary". Pure: the raw env value is
+ * read at the call site.
+ */
+export function resolvePasteSelectionSource(value) {
+	return typeof value === "string" && value.trim().toLowerCase() === "clipboard" ? "clipboard" : "primary";
+}
+
+/**
+ * Issue #174 (B2): whether a normalized mouse event ends a selection gesture
+ * we should mirror into the X11 PRIMARY selection. Only release/click of the
+ * left button with native paste enabled (pi's fullscreen selection owns the
+ * gesture; we observe without consuming). Pure by contract.
+ */
+export function shouldMirrorSelectionToPrimary(event, { nativePasteEnabled }) {
+	if (!nativePasteEnabled) return null;
+	if ((event.type === "release" || event.type === "click") && event.button === "left") return "mirror-primary";
+	return null;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `node --test test/pty-scroll.test.mjs`
+Expected: PASS (new + all pre-existing cases).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/pty-scroll.mjs test/pty-scroll.test.mjs
+git commit -m "feat(attach): pure decision helpers for selection mirror and paste source"
+```
+
+---
+
+### Task 2: B2 — mirror wiring + runner-free scenario (A2)
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (import line ~13; `handleMouse` :376; new private method near `writePrimarySelection` ~:1150)
+- Create: `test-support/pty-attach-selection-mirror-scenario.ts`
+- Test: `test/pty-attach-selection-mirror.test.mjs`
+
+**Interfaces:**
+- Consumes: `shouldMirrorSelectionToPrimary(event, { nativePasteEnabled })` from Task 1; `this.writePrimarySelection(text)` (existing private); `this.tui` cast `as { getActiveSelectionText?: () => string | undefined }`.
+- Produces: private `mirrorFullscreenSelectionToPrimary(): void`; the observe-branch in `handleMouse`.
+
+- [ ] **Step 1: Write the failing test + scenario**
+
+Create `test/pty-attach-selection-mirror.test.mjs`:
+
+```js
+import assert from "node:assert/strict";
+import test from "node:test";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+
+const ROOT_DIR = fileURLToPath(new URL("../", import.meta.url));
+const SCENARIO = join(ROOT_DIR, "test-support", "pty-attach-selection-mirror-scenario.ts");
+
+// Component-level coverage (issue #174 B2): the REAL PtyAttachComponent with a
+// fake fullscreen TUI (getActiveSelectionText fixture) and a PATH-stubbed
+// bidirectional xclip that records reads/writes to a log. Asserts the mirror
+// fires on left release/click (deferred one tick), never consumes the event,
+// skips empty selections, honors the kill switch, and ignores non-endings.
+test("attach selection mirror: left release/click mirrors pi's selection into PRIMARY", () => {
+	const out = execFileSync(process.execPath, ["--experimental-transform-types", SCENARIO], {
+		encoding: "utf8",
+		timeout: 60_000,
+	});
+	const parsed = JSON.parse(out.trim().split("\n").filter(Boolean).pop());
+	assert.equal(parsed.error, null, `scenario error: ${parsed.error}`);
+	assert.equal(parsed.releaseResultUndefined, true, "release(left) must return undefined (observe only)");
+	assert.equal(parsed.mirrorWrites, 1, "exactly one PRIMARY write for the drag-style release");
+	assert.equal(parsed.mirrorText, "mirror-fixture-text", "the mirrored text is getActiveSelectionText()'s value");
+	assert.equal(parsed.clickResultUndefined, true, "click(left) must return undefined");
+	assert.equal(parsed.clickMirrorWrites, 1, "the click case also mirrors (selection non-empty)");
+	assert.equal(parsed.emptyWrites, 0, "empty selection must not write");
+	assert.equal(parsed.killSwitchWrites, 0, "NATIVE_PASTE=0 must disable the mirror");
+	assert.equal(parsed.nonEndingWrites, 0, "press/move must not trigger the mirror");
+});
+```
+
+Create `test-support/pty-attach-selection-mirror-scenario.ts`:
+
+```ts
+// Component-level selection-mirror coverage (issue #174 B2): the REAL
+// PtyAttachComponent with a fake fullscreen TUI whose getActiveSelectionText
+// returns a controllable fixture, run against a nonexistent control socket,
+// with a PATH-stubbed bidirectional xclip that appends every invocation
+// (args + stdin for writes) to a log file and prints a read fixture for -o.
+// Run via `node --experimental-transform-types`.
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PtyAttachComponent } from "../src/ui/pty-attach.ts";
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+const READ_FIXTURE = "read-fixture-text";
+
+const root = mkdtempSync(join(tmpdir(), "agentview-sel-mirror-"));
+const binDir = join(root, "bin");
+mkdirSync(binDir);
+const logPath = join(root, "xclip.log");
+writeFileSync(logPath, "");
+writeFileSync(
+	join(binDir, "xclip"),
+	[
+		"#!/bin/sh",
+		`if [ "$1" = "-o" ]; then`,
+		`  echo "read $*" >> "${logPath}"`,
+		`  printf '%s' "${READ_FIXTURE}"`,
+		"else",
+		'  text="$(cat)"',
+		`  echo "write $* text=$text" >> "${logPath}"`,
+		"fi",
+	].join("\n"),
+);
+chmodSync(join(binDir, "xclip"), 0o755);
+process.env.PATH = `${binDir}:${process.env.PATH}`;
+
+// The selection pi would have finalized by the time the deferred mirror runs.
+let selectionText: string | undefined = "mirror-fixture-text";
+
+const writes = () =>
+	readFileSync(logPath, "utf8")
+		.split("\n")
+		.filter((l) => l.startsWith("write "));
+
+const leftEvent = (type: "release" | "click" | "press" | "move") => ({
+	type,
+	button: "left",
+	x: 3,
+	y: 3,
+	screenX: 3,
+	screenY: 3,
+	width: 80,
+	height: 22,
+	shift: false,
+});
+
+async function withComponent(env: Record<string, string> | undefined, fn: (c: PtyAttachComponent) => Promise<void>): Promise<void> {
+	const prevEnv: Record<string, string | undefined> = {};
+	for (const [k, v] of Object.entries(env ?? {})) {
+		prevEnv[k] = process.env[k];
+		process.env[k] = v;
+	}
+	const tui = {
+		mode: "fullscreen",
+		getActiveSelectionText: () => selectionText,
+		terminal: { rows: 24, cols: 80, columns: 80, write: () => {} },
+		requestRender: () => {},
+	};
+	const theme = { fg: (_c: string, t: string) => t, bold: (t: string) => t };
+	let component: PtyAttachComponent | null = null;
+	try {
+		component = new PtyAttachComponent(
+			tui as never,
+			theme as never,
+			{} as never,
+			() => {},
+			{ socketPath: join(root, "nonexistent.sock"), title: "sel mirror e2e" } as never,
+		);
+		await fn(component);
+	} finally {
+		try { component?.dispose(); } catch {}
+		await sleep(50);
+		for (const [k, v] of Object.entries(prevEnv)) {
+			if (v === undefined) delete process.env[k];
+			else process.env[k] = v;
+		}
+	}
+}
+
+const result = {
+	error: null as string | null,
+	releaseResultUndefined: false,
+	mirrorWrites: -1,
+	mirrorText: null as string | null,
+	clickResultUndefined: false,
+	clickMirrorWrites: -1,
+	emptyWrites: -1,
+	killSwitchWrites: -1,
+	nonEndingWrites: -1,
+};
+
+try {
+	// 1. Drag-style release mirrors the selection exactly once, unconsumed.
+	await withComponent(undefined, async (c) => {
+		const before = writes().length;
+		const r = (c as any).handleMouse(leftEvent("release"));
+		result.releaseResultUndefined = r === undefined;
+		await sleep(80); // nextTick + xclip spawn
+		const ws = writes();
+		result.mirrorWrites = ws.length - before;
+		result.mirrorText = ws.length > before ? ws[ws.length - 1].replace(/^write .*?text=/, "") : null;
+	});
+
+	// 2. Click ending (non-empty selection) mirrors too, unconsumed.
+	await withComponent(undefined, async (c) => {
+		const before = writes().length;
+		const r = (c as any).handleMouse(leftEvent("click"));
+		result.clickResultUndefined = r === undefined;
+		await sleep(80);
+		result.clickMirrorWrites = writes().length - before;
+	});
+
+	// 3. Empty selection: no write.
+	await withComponent(undefined, async (c) => {
+		const prev = selectionText;
+		selectionText = undefined;
+		const before = writes().length;
+		(c as any).handleMouse(leftEvent("release"));
+		await sleep(80);
+		result.emptyWrites = writes().length - before;
+		selectionText = prev;
+	});
+
+	// 4. Kill switch: no write.
+	await withComponent({ AGENT_BOARD_ATTACH_NATIVE_PASTE: "0" }, async (c) => {
+		const before = writes().length;
+		(c as any).handleMouse(leftEvent("release"));
+		await sleep(80);
+		result.killSwitchWrites = writes().length - before;
+	});
+
+	// 5. Non-endings (press/move): no write.
+	await withComponent(undefined, async (c) => {
+		const before = writes().length;
+		(c as any).handleMouse(leftEvent("press"));
+		(c as any).handleMouse(leftEvent("move"));
+		await sleep(80);
+		result.nonEndingWrites = writes().length - before;
+	});
+} catch (err) {
+	result.error = err instanceof Error ? err.message : String(err);
+}
+
+try {
+	rmSync(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 30 });
+} catch {}
+console.log(JSON.stringify(result));
+process.exit(0);
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `node --test test/pty-attach-selection-mirror.test.mjs`
+Expected: FAIL — `mirrorWrites` 0 (≠1), `releaseResultUndefined` still true (returns undefined today for everything), so the failing assertion is `mirrorWrites === 1` / `mirrorText`. The kill-switch/empty/non-ending cases pass trivially; the failure must be on the mirror fields.
+
+- [ ] **Step 3: Implement the mirror**
+
+In `src/ui/pty-attach.ts`:
+
+Import line (~13) — extend the core import (alphabetical):
+
+```ts
+import { clampInt, parseMouseInputChunk, resolveAttachMouseAction, resolveWheelLines, scrollViewportTop, selectionDragScrollLines, shouldMirrorSelectionToPrimary, shouldOwnOuterMouseMode } from "../core/pty-scroll.mjs";
+```
+
+`handleMouse` (:376) — hoist the flag, add the observe-branch before the paste logic:
+
+```ts
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		const nativePasteEnabled = process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0";
+		if (shouldMirrorSelectionToPrimary(event, { nativePasteEnabled })) {
+			// Observe only — pi's fullscreen selection keeps the event. Mirroring must
+			// run after TuiAltScreen finalizes the selection for this event (overlays
+			// are dispatched before the selection logic), hence the deferred tick.
+			process.nextTick(() => this.mirrorFullscreenSelectionToPrimary());
+			return undefined;
+		}
+		const action = resolveAttachMouseAction(event, { nativePasteEnabled });
+		if (action !== "paste-primary") return undefined;
+		this.clearPendingClick();
+		this.clearSelection();
+		this.pastePrimarySelection();
+		return { handled: true, render: false };
+	}
+```
+
+Near `writePrimarySelection` (~:1150), add:
+
+```ts
+	/** Issue #174 (B2): after a selection gesture ends inside this overlay, copy
+	 * pi's final selection text into the X11 PRIMARY selection so the classic
+	 * select-then-middle-click-paste loop works in fullscreen. Runs on nextTick
+	 * because overlays are dispatched before TuiAltScreen finalizes the
+	 * selection for the same event. No-op in regular mode (no
+	 * getActiveSelectionText) and under the native-paste kill switch. */
+	private mirrorFullscreenSelectionToPrimary(): void {
+		if (this.closed) return;
+		const alt = this.tui as { getActiveSelectionText?: () => string | undefined };
+		const text = alt.getActiveSelectionText?.();
+		if (typeof text === "string" && text.length > 0) this.writePrimarySelection(text);
+	}
+```
+
+Do NOT touch anything else (paste decision, ownership gating, legacy paths).
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `node --test test/pty-attach-selection-mirror.test.mjs`
+Expected: PASS.
+
+- [ ] **Step 5: Run the unit tests + typecheck**
+
+Run: `node --test test/pty-scroll.test.mjs && npm run typecheck`
+Expected: PASS both.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ui/pty-attach.ts test-support/pty-attach-selection-mirror-scenario.ts test/pty-attach-selection-mirror.test.mjs
+git commit -m "feat(attach): mirror pi's fullscreen selection into X11 PRIMARY (issue #174)"
+```
+
+---
+
+### Task 3: C — paste-source override + scenario case (A3)
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (`pastePrimarySelection` ~:1120, one line)
+- Modify: `test-support/pty-attach-selection-mirror-scenario.ts` (one more case)
+- Modify: `test/pty-attach-selection-mirror.test.mjs` (assertions for the new case)
+
+**Interfaces:**
+- Consumes: `resolvePasteSelectionSource(value)` from Task 1.
+- Produces: paste reads `-selection primary|clipboard` per `AGENT_BOARD_ATTACH_PASTE_SOURCE`.
+
+- [ ] **Step 1: Extend the scenario + test first**
+
+In `test-support/pty-attach-selection-mirror-scenario.ts`, add a reads-counter helper next to `writes` and one more case before the catch (after case 5):
+
+```ts
+const reads = () =>
+	readFileSync(logPath, "utf8")
+		.split("\n")
+		.filter((l) => l.startsWith("read "));
+```
+
+and inside the `result` object add `clipboardReads: -1, clipboardReadSource: null as string | null`. Then after case 5:
+
+```ts
+	// 6. Paste source override: middle paste reads CLIPBOARD when configured.
+	await withComponent({ AGENT_BOARD_ATTACH_PASTE_SOURCE: "clipboard" }, async (c) => {
+		const before = reads().length;
+		const r = (c as any).handleMouse({ type: "press", button: "middle", x: 3, y: 3, screenX: 3, screenY: 3, width: 80, height: 22, shift: false });
+		result.middleHandled = r?.handled === true;
+		await sleep(200); // xclip spawn + close
+		const rs = reads();
+		result.clipboardReads = rs.length - before;
+		result.clipboardReadSource = rs.length > before ? rs[rs.length - 1] : null;
+	});
+```
+
+(declare `middleHandled: false` in `result` too). In `test/pty-attach-selection-mirror.test.mjs`, append:
+
+```js
+	assert.equal(parsed.middleHandled, true, "middle press still pastes (handled)");
+	assert.equal(parsed.clipboardReads, 1, "PASTE_SOURCE=clipboard: exactly one clipboard read");
+	assert.equal(parsed.clipboardReadSource, "read -o -selection clipboard", "the read targets the clipboard selection");
+```
+
+- [ ] **Step 2: Run to verify the new assertions fail**
+
+Run: `node --test test/pty-attach-selection-mirror.test.mjs`
+Expected: FAIL — `clipboardReadSource` is `read -o -selection primary` (the hardcoded value).
+
+- [ ] **Step 3: Implement**
+
+In `pastePrimarySelection()` (~:1120), change the spawn line:
+
+```ts
+			const child = spawn("xclip", ["-o", "-selection", resolvePasteSelectionSource(process.env.AGENT_BOARD_ATTACH_PASTE_SOURCE)], { stdio: ["ignore", "pipe", "ignore"] });
+```
+
+(extend the existing `../core/pty-scroll.mjs` import with `resolvePasteSelectionSource` — alphabetical placement).
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/pty-attach-selection-mirror.test.mjs && node --test test/pty-attach-mouse.test.mjs`
+Expected: PASS (the #171 scenario pins the default primary source — still green).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ui/pty-attach.ts test-support/pty-attach-selection-mirror-scenario.ts test/pty-attach-selection-mirror.test.mjs
+git commit -m "feat(attach): AGENT_BOARD_ATTACH_PASTE_SOURCE paste-source override (issue #174)"
+```
+
+---
+
+### Task 4: Full verify + coverage gate (A4, A5)
+
+**Files:**
+- Modify: whatever Tasks 1–3 fallout requires (expected: none).
+
+- [ ] **Step 1: Run the full verify pipeline**
+
+Run: `npm run verify`
+Expected: PASS end-to-end (typecheck + perf gate + tests + coverage lines 85 / funcs 80 / branches 70 + pack:dry).
+
+- [ ] **Step 2: Fix any fallout, then re-run** (known pre-existing flake: `pty-runner.integration.test.mjs`, issue #95 — re-run once; still red → STOP and report BLOCKED)
+
+- [ ] **Step 3: Commit (only if fixes were needed)**
+
+```bash
+git add <changed files>
+git commit -m "test: verify fallout fixes for issue #174"
+```
+
+---
+
+## Acceptance traceability
+
+| Spec ID | Covered by |
+| --- | --- |
+| A1 (unit decision tables) | Task 1 |
+| A2 (B2 mirror wiring, integration) | Task 2 |
+| A3 (C paste source, integration) | Task 3 |
+| A4 (static/build) | Task 4 (+ typecheck in Tasks 2–3) |
+| A5 (existing suite regression) | Task 4 |
+| U1 (user manual: 5-step real-terminal checklist) | Post-implementation checklist for the user — executed after merge or from the worktree install |

package/docs/superpowers/specs/2026-10-10-issue-174-selection-mirror-paste-source-design.md

@@ -0,0 +1,154 @@
+Drafted: zai-coding-cn/glm-5.3 (selected) · zai-coding-cn/glm-5.3 (physical) @ 2026-10-10T00:31:00Z
+
+# Spec: #174 — middle-click paste in fullscreen reads a stale X11 PRIMARY: mirror pi's selection to PRIMARY (B2) + paste-source override (C)
+
+Status: DRAFT (awaiting spec-cross-review or user waiver, then user approval — github-issue-driven step 4 gates)
+Issue: https://github.com/zhuxixi/pi-agent-board/issues/174
+Repo state baseline: main @ `0fd1dc5` (post-#173)
+
+## Problem (root cause, verified live + from source)
+
+In fullscreen, drag-select belongs to `TuiAltScreen` and its copy-on-select writes
+**CLIPBOARD** only; nothing in a pi session ever writes X11 **PRIMARY**. Middle-click
+paste (#171) reads **PRIMARY** → serves a fossil (live evidence 2026-10-10: PRIMARY held
+`assert_contains(doc, contracts)` while the user's fresh selection sat in CLIPBOARD).
+Pre-1.0 the loop closed because the component's own selection mirrored to PRIMARY
+(`writePrimarySelection`, a1c5f08) — dead in fullscreen since pi owns left-drag.
+
+Design-critical ordering fact (pi-tui 1.1.0 `handleMouseEvent`): overlays are dispatched
+**before** pi's selection finalization for the same event, so the mirror must read the
+selection **deferred** (`process.nextTick` after the release/click).
+
+## Goal / non-goals
+
+**Goal**: (B2) when a selection gesture ends inside the attach view in fullscreen, mirror
+pi's final selection text into X11 PRIMARY so the classic select → middle-click-paste
+loop works again; (C) opt-in `AGENT_BOARD_ATTACH_PASTE_SOURCE=primary|clipboard` for
+environments where PRIMARY never updates. Both governed by the existing
+`AGENT_BOARD_ATTACH_NATIVE_PASTE` kill switch. pi's own selection behavior (visuals,
+CLIPBOARD copy) is untouched — B2 observes, never consumes.
+
+**Non-goals**:
+- Selections released outside the attach overlay (dashboard / other pi UI) — outside the
+  component's event window; pi-wide coverage belongs upstream (earendil-works/pi).
+- Any change to #169's ownership model, #171's paste decision table, or regular-mode
+  behavior (mirror is a no-op there: `getActiveSelectionText` doesn't exist on
+  regular-mode TUIs; paste source defaults to primary as today).
+
+## Design
+
+### 1. Pure decision helpers (`src/core/pty-scroll.mjs`)
+
+```js
+/** Issue #174 (C): which X11 selection buffer middle-click paste reads.
+ * "primary" (default, classic X11 semantics) | "clipboard" (escape hatch for
+ * environments where PRIMARY never updates, e.g. WSLg). Unknown values fall
+ * back to "primary". Pure: the env value is read at the call site. */
+resolvePasteSelectionSource(value) → "primary" | "clipboard"
+
+/** Issue #174 (B2): whether a normalized mouse event should trigger mirroring
+ * pi's (final) selection text into X11 PRIMARY. Only selection-gesture endings
+ * (release/click of the left button) with native paste enabled. Pure. */
+shouldMirrorSelectionToPrimary(event, { nativePasteEnabled }) → "mirror-primary" | null
+```
+
+Decision table for `shouldMirrorSelectionToPrimary`:
+
+| type | button | nativePasteEnabled | result |
+| --- | --- | --- | --- |
+| release / click | left | true | `"mirror-primary"` |
+| release / click | left | false | `null` |
+| press/move/drag/wheel | any | * | `null` |
+| release / click | middle/right/none | * | `null` |
+
+### 2. Component wiring (`src/ui/pty-attach.ts`)
+
+- `handleMouse(event)` gains one branch BEFORE the paste branch (order irrelevant; events
+  are disjoint): if `shouldMirrorSelectionToPrimary(event, {nativePasteEnabled})` →
+  schedule `process.nextTick(() => this.mirrorFullscreenSelectionToPrimary())` and
+  **return `undefined`** (observe only — pi keeps the event). The paste branch is
+  unchanged (`press + middle` → paste, `{handled:true, render:false}`).
+- New private method:
+
+```ts
+/** Issue #174 (B2): after a selection gesture ends inside this overlay, copy
+ * pi's final selection text into the X11 PRIMARY selection so the classic
+ * select-then-middle-click-paste loop works in fullscreen. Runs on nextTick
+ * because overlays are dispatched before TuiAltScreen finalizes the selection
+ * for the same event. No-op in regular mode (no getActiveSelectionText) and
+ * under the native-paste kill switch. */
+private mirrorFullscreenSelectionToPrimary(): void {
+	if (this.closed) return;
+	const alt = this.tui as { getActiveSelectionText?: () => string | undefined };
+	const text = alt.getActiveSelectionText?.();
+	if (typeof text === "string" && text.length > 0) this.writePrimarySelection(text);
+}
+```
+
+  (`writePrimarySelection` already guards `AGENT_BOARD_ATTACH_NATIVE_PASTE === "0"`;
+  the decision helper guards the scheduling side — belt and suspenders, no behavior
+  difference.)
+- `pastePrimarySelection()`: the spawn args become
+  `xclip -o -selection ${resolvePasteSelectionSource(process.env.AGENT_BOARD_ATTACH_PASTE_SOURCE)}`.
+  Everything else (800 ms kill timer, forward-as-input, silent no-op) unchanged.
+
+### Resulting behavior matrix
+
+| Scenario | Behavior |
+| --- | --- |
+| fullscreen: drag-select inside attach → middle-click in attach | selection lands in PRIMARY (B2) AND CLIPBOARD (pi); middle paste = the selection ✅ |
+| fullscreen: select in another X11 app → middle-click in attach | pastes that app's PRIMARY (unchanged, correct) |
+| fullscreen: select elsewhere in pi (dashboard) → middle-click in attach | NOT mirrored (no event window) — known limitation; middle paste reads whatever PRIMARY holds |
+| `AGENT_BOARD_ATTACH_PASTE_SOURCE=clipboard` | middle paste reads CLIPBOARD regardless of PRIMARY |
+| `AGENT_BOARD_ATTACH_NATIVE_PASTE=0` | no mirror, no paste (kill switch governs both sides) |
+| regular mode | mirror no-ops (no `getActiveSelectionText`), paste reads primary (default) — unchanged |
+
+## Acceptance matrix
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | 两个纯决策表（mirror 触发条件 × 开关；paste source 解析） | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs`（新增用例直接调两个 helper：mirror 表全部行 + source 的 unset/"primary"/"clipboard"/garbage） | 新增用例全绿，既有用例不回归 |
+| A2 | B2 接线：release/click(left) → nextTick 后 PRIMARY 收到 pi 的选中文本；observe 不消费；空选择不写；kill switch 不写 | 自动化验证（integration，组件级场景） | 新增 `test-support/pty-attach-selection-mirror-scenario.ts`（fake tui `mode:"fullscreen"` + `getActiveSelectionText` fixture + PATH-stub `xclip` 把 args/stdin 记日志），由 `test/pty-attach-selection-mirror.test.mjs` 运行断言 | ① `handleMouse({release,left})` 返回 `undefined` 且 nextTick 后 stub 日志含 `-selection primary` 写、stdin=fixture；② `getActiveSelectionText→undefined` 时无写；③ NATIVE_PASTE=0 无写；④ `press+left`/`move` 不触发 |
+| A3 | C 接线：paste source 覆盖 | 自动化验证（integration，同一场景文件加 case） | 同场景：`AGENT_BOARD_ATTACH_PASTE_SOURCE=clipboard` + `handleMouse({press,middle})` | stub 日志显示 `-o -selection clipboard`；fixture 文本经 socket 以 `{type:"input"}` 发出（复用 #171 场景缝） |
+| A4 | 类型与构建 | 自动化验证（static/build） | `npm run typecheck`、`npm run verify` | 全部通过 |
+| A5 | 既有行为不回归（#171 中键粘贴、#169 ownership、regular 路径） | 自动化验证（unit+integration，既有套件） | `npm test` / `npm run test:coverage` | 既有测试全绿，覆盖阈值不降 |
+| U1 | 真机：pi 内选中 → 中键粘贴闭环 | 用户实测 | ① fullscreen attach 内拖选一段文字；② 中键 → 应粘贴刚选的内容；③ 在别的 X11 应用选中 → 中键 → 粘贴该内容；④ `AGENT_BOARD_ATTACH_PASTE_SOURCE=clipboard` 后中键粘贴读剪贴板；⑤ `AGENT_BOARD_ATTACH_NATIVE_PASTE=0` 后中键无反应、选中不再镜像 PRIMARY | ①–⑤ 全部符合 |
+
+## Testability split design (hard constraint for implementation)
+
+- **Pure core**: `resolvePasteSelectionSource(value)` and
+  `shouldMirrorSelectionToPrimary(event, {nativePasteEnabled})` — plain functions, no env
+  reads inside, no side effects. Unit decision tables (A1).
+- **I/O shell**: `PtyAttachComponent.handleMouse` maps decisions to side effects
+  (`process.nextTick` scheduling → `mirrorFullscreenSelectionToPrimary()` → existing
+  `writePrimarySelection`; paste branch spawns xclip with the resolved source).
+  Component-level tests (A2/A3) drive only public seams (`handleMouse`, ticks,
+  `dispose()`) and observe the PATH-stubbed `xclip` log + attach-socket messages; the
+  stub handles both directions (`-o` prints a fixture; write mode records stdin/args).
+- The pure helpers must not be re-inlined into the component; `handleMouse` must remain
+  the only mirror scheduling point; `writePrimarySelection`/`pastePrimarySelection`
+  remain the only xclip touch points.
+
+## Risks / notes
+
+- nextTick timing assumes pi's release handling is synchronous in the same tick (verified
+  in tui-alt-screen.js: overlay dispatch → `handleSelectionMouseEvent` → copy, no awaits
+  before selection state is final; `copySelectionToClipboard` is async but only writes
+  CLIPBOARD — irrelevant to our read). If a future pi-tui defers selection state, the
+  mirror lags one gesture — acceptable degradation, not corruption.
+- `getActiveSelectionText` typing: structural cast in the component (declared private in
+  pi-tui 1.1.0's `tui-alt-screen.d.ts` but runtime-reachable, hence the cast; absent on
+  regular TUIs and old runtimes → optional access → no-op).
+- Double-click word / triple-click line selections: press path sets the full range
+  immediately; release/click mirror picks up the same text — covered by the same code
+  path, no special casing.
+- The stub-xclip scenario must restore PATH and clean temp dirs (self-contained).
+
+## Deliverables
+
+- `src/core/pty-scroll.mjs`: + `resolvePasteSelectionSource`, `shouldMirrorSelectionToPrimary`
+- `src/ui/pty-attach.ts`: mirror branch in `handleMouse`, `mirrorFullscreenSelectionToPrimary()`,
+  paste source in `pastePrimarySelection`
+- `test/pty-scroll.test.mjs`: decision-table cases
+- `test-support/pty-attach-selection-mirror-scenario.ts` + `test/pty-attach-selection-mirror.test.mjs`
+- CHANGELOG entry via release tooling at release time (not in this PR)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zhuxixi/pi-agent-board",
-	"version": "0.10.2",
+	"version": "0.11.1",
 	"description": "Agent-board dashboard for Pi: dispatch, monitor, peek/reply, and attach to background Pi sessions.",
 	"type": "module",
 	"main": "./index.ts",

package/src/core/pty-scroll.mjs

@@ -107,6 +107,29 @@ export function resolveAttachMouseAction(event, { nativePasteEnabled }) {
 	return null;
 }
 
+/**
+ * Issue #174 (C): which X11 selection buffer middle-click paste reads.
+ * "primary" = classic X11 middle-click semantics (default); "clipboard" =
+ * escape hatch for environments where PRIMARY never updates (e.g. WSLg).
+ * Unknown or unset values fall back to "primary". Pure: the raw env value is
+ * read at the call site.
+ */
+export function resolvePasteSelectionSource(value) {
+	return typeof value === "string" && value.trim().toLowerCase() === "clipboard" ? "clipboard" : "primary";
+}
+
+/**
+ * Issue #174 (B2): whether a normalized mouse event ends a selection gesture
+ * we should mirror into the X11 PRIMARY selection. Only release/click of the
+ * left button with native paste enabled (pi's fullscreen selection owns the
+ * gesture; we observe without consuming). Pure by contract.
+ */
+export function shouldMirrorSelectionToPrimary(event, { nativePasteEnabled }) {
+	if (!nativePasteEnabled) return null;
+	if ((event.type === "release" || event.type === "click") && event.button === "left") return "mirror-primary";
+	return null;
+}
+
 /**
  * Issue #169: whether the attach surface should manage the OUTER terminal's
  * mouse mode. Only in regular TUI mode — in fullscreen, TuiAltScreen owns

package/src/ui/pty-attach.ts

@@ -12,7 +12,7 @@ import { installImeCursorCoalesce } from "../core/ime-cursor-coalesce.mjs";
 import { createJiggleRetryController } from "../core/pty-attach-jiggle-controller.mjs";
 import { createTerminalAttachClient } from "../core/terminal-attach-client.mjs";
 import { backgroundRgbFromTerminalColors, buildSettleSchemePatch, colorSchemeForBackgroundRgb, extractOscQuerySequences, resolveProbeApi, toColorSchemeReport } from "../core/terminal-query-sequences.mjs";
-import { clampInt, parseMouseInputChunk, resolveAttachMouseAction, resolveWheelLines, scrollViewportTop, selectionDragScrollLines, shouldOwnOuterMouseMode } from "../core/pty-scroll.mjs";
+import { clampInt, parseMouseInputChunk, resolveAttachMouseAction, resolvePasteSelectionSource, resolveWheelLines, scrollViewportTop, selectionDragScrollLines, shouldMirrorSelectionToPrimary, shouldOwnOuterMouseMode } from "../core/pty-scroll.mjs";
 
 export type PtyAttachResult = { action: "detached" } | { action: "closed"; exitCode?: number | null };
 
@@ -240,6 +240,12 @@ export class PtyAttachComponent implements Component {
 	// null never matches the duplicate check, so a timeout-then-late sequence
 	// still delivers. Single-shot per attach — settle runs at most once.
 	private sentScheme: TerminalColorScheme | null = null;
+	// Pi enables bracketed paste AFTER entering raw mode and disables it at
+	// shutdown. Only current runner output/snapshots may establish readiness;
+	// the screen.log warm-start can belong to a previous child incarnation.
+	private childInputReady = false;
+	private childInputModeCarry = "";
+	private pendingSchemeReport: { scheme: TerminalColorScheme; api?: "colors" | "background" | "none"; late?: boolean } | null = null;
 	// Issue #128 D2: unsubscriber for the color-scheme bridge registered at
 	// attach settle; nulled on every terminal path so the TUI never keeps a
 	// listener pointing at a dead attach surface.
@@ -374,9 +380,15 @@ export class PtyAttachComponent implements Component {
 	 * middle-click paste is ours; every other event returns undefined so pi's
 	 * own fullscreen selection and the wheel defer path keep working. */
 	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
-		const action = resolveAttachMouseAction(event, {
-			nativePasteEnabled: process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0",
-		});
+		const nativePasteEnabled = process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0";
+		if (shouldMirrorSelectionToPrimary(event, { nativePasteEnabled })) {
+			// Observe only — pi's fullscreen selection keeps the event. Mirroring must
+			// run after TuiAltScreen finalizes the selection for this event (overlays
+			// are dispatched before the selection logic), hence the deferred tick.
+			process.nextTick(() => this.mirrorFullscreenSelectionToPrimary());
+			return undefined;
+		}
+		const action = resolveAttachMouseAction(event, { nativePasteEnabled });
 		if (action !== "paste-primary") return undefined;
 		this.clearPendingClick();
 		this.clearSelection();
@@ -463,7 +475,7 @@ export class PtyAttachComponent implements Component {
 		this.parserBuffer = "";
 		socket.on("connect", () => {
 			if (this.socket !== socket) {
-				try { socket.destroy(); } catch {}
+				try { socket.destroy(); } catch { /* best-effort stale-socket cleanup */ }
 				return;
 			}
 			this.clearRetry();
@@ -514,7 +526,7 @@ export class PtyAttachComponent implements Component {
 			// The error may belong to an old socket after reconnect. Dispose that
 			// socket, but do not alter the state of the current connection.
 			if (this.socket !== socket) {
-				try { socket.destroy(); } catch {}
+				try { socket.destroy(); } catch { /* best-effort stale-socket cleanup */ }
 				return;
 			}
 			this.socket = null;
@@ -523,7 +535,7 @@ export class PtyAttachComponent implements Component {
 			// stale-socket guard (this.socket no longer matches) and must not be
 			// the only path that cancels the probe deadline (CR R1 advisory).
 			this.attachClient.onDisconnect();
-			try { socket.destroy(); } catch {}
+			try { socket.destroy(); } catch { /* already handling socket failure */ }
 			this.disconnectedAt ??= Date.now();
 			if (this.closed) return;
 			this.status = `waiting for host… ${err.message}`;
@@ -647,8 +659,9 @@ export class PtyAttachComponent implements Component {
 		if (this.colorSchemeBridgeUnsubscribe) return;
 		try {
 			this.colorSchemeBridgeUnsubscribe = this.tui.onTerminalColorSchemeChange((scheme) => {
-				const data = toColorSchemeReport(scheme);
-				if (data) this.send({ type: "input", data });
+				if (!toColorSchemeReport(scheme)) return;
+				this.pendingSchemeReport = { scheme };
+				this.flushPendingSchemeReport();
 			});
 		} catch {
 			/* best-effort: an unbridgeable TUI keeps pre-#128 behavior */
@@ -658,6 +671,8 @@ export class PtyAttachComponent implements Component {
 	/** Called on every terminal path (close() covers detach/dispose; the exit
 	 * branch calls done() without close(), so it unsubscribes explicitly). */
 	private detachColorSchemeBridge(): void {
+		this.pendingSchemeReport = null;
+		this.childInputReady = false;
 		const unsubscribe = this.colorSchemeBridgeUnsubscribe;
 		this.colorSchemeBridgeUnsubscribe = null;
 		if (!unsubscribe) return;
@@ -722,7 +737,8 @@ export class PtyAttachComponent implements Component {
 		const rgb = backgroundRgbFromTerminalColors(colors as never);
 		const scheme = rgb ? colorSchemeForBackgroundRgb(rgb) ?? undefined : undefined;
 		if (!scheme) return;
-		if (this.sentScheme === scheme) {
+		if (this.sentScheme === scheme && this.childInputReady) {
+			this.pendingSchemeReport = null;
 			this.opts.onDiagnostic?.(buildSettleSchemePatch({ probeApi: api, outcome: "duplicate_skipped" }));
 			return;
 		}
@@ -742,6 +758,12 @@ export class PtyAttachComponent implements Component {
 			this.opts.onDiagnostic?.(buildSettleSchemePatch({ probeApi: api, outcome: "dropped_disconnected" }));
 			return;
 		}
+		if (!this.childInputReady) {
+			// Settle/probe completion is not a child-readiness handshake. Keep
+			// only the latest scheme, then send when the child enters raw mode.
+			this.pendingSchemeReport = { scheme, api, late };
+			return;
+		}
 		this.sentScheme = scheme;
 		this.send({ type: "input", data });
 		const details: { probeApi: "colors" | "background" | "none"; outcome: "reported"; report: string; late?: boolean } = {
@@ -753,6 +775,26 @@ export class PtyAttachComponent implements Component {
 		this.opts.onDiagnostic?.(buildSettleSchemePatch(details));
 	}
 
+	private updateChildInputReadiness(data: string): void {
+		// Scan only LIVE bytes, not warm-start history. A reused xterm buffer
+		// can still have the old child's paste mode enabled during cold boot.
+		const input = this.childInputModeCarry + data;
+		for (const match of input.matchAll(/\x1b\[\?2004([hl])/g)) {
+			this.childInputReady = match[1] === "h";
+		}
+		// Keep at most an incomplete eight-byte mode sequence across chunks.
+		this.childInputModeCarry = input.slice(-7);
+	}
+
+	private flushPendingSchemeReport(): void {
+		if (this.closed || !this.connected || !this.childInputReady) return;
+		const pending = this.pendingSchemeReport;
+		this.pendingSchemeReport = null;
+		if (!pending) return;
+		if (pending.api) this.deliverSettleScheme(pending.scheme, pending.api, pending.late ?? false);
+		else this.send({ type: "input", data: toColorSchemeReport(pending.scheme) });
+	}
+
 	private startDesyncProbe(): void {
 		this.stopDesyncProbe();
 		// The probe is deliberately NOT hooked into the render path: rendering is
@@ -1118,15 +1160,16 @@ export class PtyAttachComponent implements Component {
 	}
 
 	/**
-	 * Middle-click paste. Reads the X11 PRIMARY selection via xclip and forwards it to
-	 * the hosted session as input, mimicking the terminal-native middle-click paste that
-	 * mouse reporting (kept on for wheel scrolling) would otherwise swallow. Silent no-op
-	 * when xclip is absent or AGENT_BOARD_ATTACH_NATIVE_PASTE=0.
+	 * Middle-click paste. Reads the X11 selection (PRIMARY by default, or CLIPBOARD via
+	 * AGENT_BOARD_ATTACH_PASTE_SOURCE=clipboard) via xclip and forwards it to the hosted
+	 * session as input, mimicking the terminal-native middle-click paste that mouse
+	 * reporting (kept on for wheel scrolling) would otherwise swallow. Silent no-op when
+	 * xclip is absent or AGENT_BOARD_ATTACH_NATIVE_PASTE=0.
 	 */
 	private pastePrimarySelection(): void {
 		if (process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE === "0") return;
 		try {
-			const child = spawn("xclip", ["-o", "-selection", "primary"], { stdio: ["ignore", "pipe", "ignore"] });
+			const child = spawn("xclip", ["-o", "-selection", resolvePasteSelectionSource(process.env.AGENT_BOARD_ATTACH_PASTE_SOURCE)], { stdio: ["ignore", "pipe", "ignore"] });
 			let out = "";
 			const timer = setTimeout(() => {
 				try {
@@ -1148,6 +1191,19 @@ export class PtyAttachComponent implements Component {
 		}
 	}
 
+	/** Issue #174 (B2): after a selection gesture ends inside this overlay, copy
+	 * pi's final selection text into the X11 PRIMARY selection so the classic
+	 * select-then-middle-click-paste loop works in fullscreen. Runs on nextTick
+	 * because overlays are dispatched before TuiAltScreen finalizes the
+	 * selection for the same event. No-op in regular mode (no
+	 * getActiveSelectionText) and under the native-paste kill switch. */
+	private mirrorFullscreenSelectionToPrimary(): void {
+		if (this.closed) return;
+		const alt = this.tui as { getActiveSelectionText?: () => string | undefined };
+		const text = alt.getActiveSelectionText?.();
+		if (typeof text === "string" && text.length > 0) this.writePrimarySelection(text);
+	}
+
 	/** Write `text` to the X11 PRIMARY selection so other apps can middle-click-paste it. */
 	private writePrimarySelection(text: string): void {
 		if (process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE === "0") return;
@@ -1391,8 +1447,12 @@ export class PtyAttachComponent implements Component {
 			// constructor's screen.log warm-start must not outlive the protocol
 			// answer — a gated reset let the dead session's tail render as a
 			// cold-start ghost once the banner lifted (final-review F1).
-			if (typeof snap.frame === "string") this.pushOutput(snap.frame);
-			else if (snap.empty || snap.resnapshot) this.term.reset();
+			if (typeof snap.frame === "string") this.pushOutput(snap.frame, { authoritative: true });
+			else if (snap.empty || snap.resnapshot) {
+				this.childInputReady = false;
+				this.childInputModeCarry = "";
+				this.term.reset();
+			}
 			return;
 		}
 		if (event === "output") {
@@ -1402,6 +1462,10 @@ export class PtyAttachComponent implements Component {
 			if (typeof payload === "string") this.pushOutput(payload, { forwardProtocols: true });
 			return;
 		}
+		if (event === "epochReset") {
+			this.childInputReady = false;
+			this.childInputModeCarry = "";
+		}
 		// "resubscribing": recovery is client-internal (informational only).
 		// "protocolError": observability only — recovery is automatic until the
 		// legacy fallback, whose mode event the UI acts on above.
@@ -1480,11 +1544,19 @@ export class PtyAttachComponent implements Component {
 		}
 	}
 
-	private pushOutput(data: string, opts: { forwardProtocols?: boolean } = {}): void {
+	private pushOutput(data: string, opts: { forwardProtocols?: boolean; authoritative?: boolean } = {}): void {
 		if (data.length === 0) return;
 		// Recorded synchronously BEFORE term.write (whose callback is async): the
 		// desync quiet-window must measure when output ARRIVED, not when parsing finished.
 		this.lastOutputAt = this.nowFn();
+		// Current snapshots explicitly restore all modes, including paste mode.
+		// Read their readiness synchronously so an older parse callback cannot
+		// overwrite a newer live shutdown/reload signal.
+		if (opts.authoritative) {
+			this.childInputReady = false;
+			this.childInputModeCarry = "";
+		}
+		if (opts.forwardProtocols || opts.authoritative) this.updateChildInputReadiness(data);
 		if (opts.forwardProtocols) this.forwardTerminalProtocols(data);
 		// @xterm/headless parses asynchronously; the buffer is only populated once this
 		// callback fires. Mark the buffer as ready (so the project path can paint it), but
@@ -1493,6 +1565,7 @@ export class PtyAttachComponent implements Component {
 		// chunk also defers the settle window, so the banner holds until output actually
 		// stops arriving (i.e. the redraw finished), not just until the resize jiggle ends.
 		this.term.write(data, () => {
+			if (opts.forwardProtocols || opts.authoritative) this.flushPendingSchemeReport();
 			this.receivedOutput = true;
 			this.deferAttachSettle();
 			this.outputRenderScheduler.request();
@@ -1553,16 +1626,16 @@ export class PtyAttachComponent implements Component {
 		this.connected = false;
 		if (!socket) return;
 		if (!gracefulSocket) {
-			try { socket.destroy(); } catch {}
+			try { socket.destroy(); } catch { /* best-effort teardown */ }
 			return;
 		}
 		// socket.end() preserves the ordering of the already-buffered restore and
 		// detach packets. destroy() would discard buffered writes under backpressure.
 		socket.once("close", () => this.clearGracefulSocketCloseTimer());
-		try { socket.end(); } catch {}
+		try { socket.end(); } catch { /* fallback timer below forces cleanup */ }
 		this.gracefulSocketCloseTimer = setTimeout(() => {
 			this.gracefulSocketCloseTimer = null;
-			try { socket.destroy(); } catch {}
+			try { socket.destroy(); } catch { /* best-effort teardown */ }
 		}, GRACEFUL_SOCKET_CLOSE_MS);
 		this.gracefulSocketCloseTimer.unref?.();
 	}