Cut native pane action latency from seconds to one frame of feedback (#1223)

* Deliver native pane action results without waiting for a poll

The inspector toolbar and the terminal canvas held separate copies of
TaskPaneState, so a split or layout click updated the toolbar and the
canvas only caught up on its 2500 ms poll. Route every pane read and
action through a single bus that broadcasts the server's own response,
with per-request tickets so a slow poll cannot reinstate pre-action
geometry, and hold the mutating controls for the duration of one action.

Also cut the ownership probing on that path: readProcessStartSignature
is async so a pane set classifies in one round trip instead of N blocking
forks, and the action dispatcher reads the layout instead of the full
state, dropping a per-pane ps pass nothing consumed.

* Stop the narrow pane carousel re-reading state in a loop

MobilePaneCarousel's poll effect depends on the navigate callback, whose
identity was derived from the pane ids in state. Every read produced a
fresh array, so the effect re-ran immediately and the 3s poll became a
~30 Hz read loop — visible in the browser as ~28 pane-state reads per
second, each one an ownership sweep. Resolve the ids through a ref.

Author: h0x91b

change-logs/2026/08/02/fix-native-pane-action-latency.md

@@ -0,0 +1,3 @@
+Short: Instant native pane splits and layouts
+
+Splitting a pane or picking a layout on a native-backend task no longer looks frozen for a couple of seconds: the toolbar and the terminal canvas now share one pane state, so the server's answer repaints the panes immediately instead of waiting for the next poll, and the clicked control greys out for the moment the action runs. The ownership probe that verifies each pane's processes also stopped blocking the event loop, cutting a six-pane layout change from 60 ms to 44 ms and a split from 228 ms to 168 ms.

decisions/192-native-pane-action-latency.md

@@ -0,0 +1,75 @@
+# 192 — Native pane actions answer through one state bus, and ownership probes are async
+
+## Context
+
+On a native-backend task, clicking Split or a layout preset looked inert for roughly
+2–3 seconds. The suspicion was slow backend work. Measurement said otherwise.
+
+## Investigation
+
+`scripts/measure-native-pane-latency.ts` (real hosts, macOS, idle) put the backend at
+20 ms for a 2-pane layout change and 130–230 ms for a split including the host spawn —
+nowhere near the reported delay. Two separate causes explained the rest:
+
+1. **Two unconnected copies of `TaskPaneState`.** `TaskPaneControls` (inspector) owned
+   the buttons and wrote the action's authoritative response into its own `useState`.
+   `TaskTerminal` draws the geometry and learned about the change only from its own
+   2500 ms poll. Click-to-settled was therefore *real work + 0–2500 ms of waiting*, and
+   there was no click-to-feedback at all: no busy state, no duplicate suppression.
+2. **`ps` on the click path, synchronously.** `classifyOwnership` proves a recorded PID
+   was not reused by reading `ps -p PID -o lstart=`, twice per pane. The probe used
+   `spawnSync`, so `Promise.all` over a pane set could not overlap anything — it also
+   blocked the whole Bun event loop. Profiling a 6-pane read: 121 ms total, of which
+   ~64 ms was one classification pass and ~64 ms the second one; the coordinator file
+   lock was 0.13 ms, i.e. not a factor.
+
+## Decision
+
+- `src/mainview/pane-state-bus.ts` is the single arrival point for a task's pane state.
+  Reads and actions go through `fetchPaneState` / `runPaneAction`, and the **server's own
+  response** is broadcast to every subscriber; polling stays purely as reconciliation.
+  Each request takes a ticket, and a response older than one already delivered is
+  dropped, so a slow poll cannot reinstate pre-action geometry. Nothing on this path
+  computes a tree locally — `renderer_only_layout_state` stays forbidden.
+- `TaskPaneControls` holds every mutating control (`disabled` + `aria-busy`) for the
+  duration of one action, keyed off a ref so two clicks in one frame cannot both fire.
+  Capability is kept separate from busy, so the "needs two panes" tooltip never fires
+  for a control that is merely in flight. No speculative pane slot is drawn.
+- `readProcessStartSignature` is async (`spawn`, not `spawnSync`), and
+  `classifyOwnership` starts the host and shell probes together. `recover()` and
+  `listPanes()` fan out over the pane set, bounded by the pane count.
+- `nativePaneAction` reads the layout only (`nativeTaskPaneLayout`) instead of the full
+  state: every action decides from the tree, so the per-pane ownership sweep the full
+  state carries was a second `ps` pass nothing read. Recovery still runs, so dead-pane
+  reconciliation is unchanged.
+
+Measured after (6 panes, same harness): layout p50 60 → 44 ms, split p50 228 → 168 ms,
+read p50 119 → 81 ms, single `ps` probe 4.9 → 0.5 ms.
+
+## Risks
+
+- The bus is `window`-scoped, so a state for the wrong task must be filtered by id; the
+  ticket counter is per task and reset only in tests.
+- Reading the layout instead of the full state means an action's decision no longer sees
+  per-pane liveness. No action consulted it — `close` used the pane count, which the tree
+  carries — but a future action that needs liveness must read the full state explicitly.
+- Async `ps` raises the number of simultaneous forks to twice the pane count. Bounded by
+  the pane set, and each fork is short-lived.
+- `readState` p50 at 6 panes is 81 ms, still above the 50 ms target, because a read
+  classifies the pane set twice: `describeSession` recovers (and reconciles), then
+  `listPanes` snapshots. Collapsing them into one pass would touch dead-pane
+  reconciliation, so it is deliberately left for its own change.
+
+## Alternatives considered
+
+- **Optimistic local geometry** on click: fastest to write, and exactly the
+  client-invented layout the native pane surface forbids — two viewers of one task would
+  disagree until the poll healed them.
+- **A push message from the main process** instead of a renderer bus: the action already
+  returns the authoritative state to the caller, so a push would be a second delivery of
+  data the renderer holds, with its own ordering problem.
+- **Caching ownership verdicts with a short TTL**: would have cut the probes without the
+  async conversion, at the cost of a window where a dead pane still reads as alive.
+- **A spinner or a placeholder pane for a split**: at 170 ms the geometry itself arrives
+  before a spinner would earn its animation; the existing terminal attach state already
+  covers the connection.

package.json

@@ -32,6 +32,7 @@
 		"test:native-shell-launch": "bunx vitest run --config vitest.config.bun.ts src/bun/native-terminal-registry/__tests__/shell-launch.test.ts src/bun/native-terminal-registry/__tests__/shell-probe.test.ts src/bun/native-terminal-registry/__tests__/windows-shell-runner.test.ts src/bun/native-terminal-registry/__tests__/windows-shell-evidence.test.ts src/bun/native-terminal-registry/__tests__/windows-shell-matrix-support.test.ts src/bun/native-terminal-registry/__tests__/host-config.test.ts src/bun/native-terminal-registry/__tests__/protocol.test.ts src/bun/native-terminal-registry/__tests__/registry.test.ts src/bun/native-terminal-registry/__tests__/recovery.test.ts src/bun/native-terminal-registry/__tests__/client.test.ts src/bun/native-terminal-registry/__tests__/isolation.test.ts",
 		"test:native-live-parser-e2e": "bun src/bun/native-terminal-registry/__tests__/live-parser.bun-e2e.ts",
 		"test:native-host-images-e2e": "bun src/bun/native-terminal-registry/host-images/__tests__/lifecycle.bun-e2e.ts",
+		"measure:native-pane-latency": "bun scripts/measure-native-pane-latency.ts",
 		"test:native-soak": "bun src/bun/native-terminal-soak/run-soak.ts",
 		"test:native-host-image": "bunx vitest run --config vitest.config.bun.ts src/bun/native-terminal-registry/host-images/__tests__/artifact-manifest.test.ts src/bun/native-terminal-registry/host-images/__tests__/artifact-manifest-cli.test.ts src/bun/native-terminal-registry/host-images/__tests__/packaged-image-manifest.test.ts src/bun/native-terminal-registry/host-images/__tests__/packaged-image.test.ts",
 		"package:win-archive": "bun scripts/generate-build-info.ts && bun scripts/generate-changelog.ts && vite build && bun run build:cli && electrobun build --env=canary",

scripts/measure-native-pane-latency.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env bun
+/**
+ * Backend latency of native task pane actions, against REAL hosts (seq 1382).
+ *
+ * Answers one question: how long does the server take to answer a pane action, by
+ * pane count. It is the machine half of click-to-settled; the renderer half is
+ * covered deterministically by `PaneActionPropagation.test.tsx`, because a
+ * wall-clock assertion on a shared dev machine is noise, not a gate.
+ *
+ * Run: `bun run measure:native-pane-latency` (writes JSON to stdout, logs to stderr).
+ * Everything lands in a tmpdir, so `~/.dev3.0/` is never touched.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { NATIVE_MULTIPANE_DIR_ENV } from "../src/bun/native-terminal-multipane/paths";
+
+/** Fixed id so repeated runs address the same deterministic session id. */
+const TASK_ID = "00000000-0000-4000-8000-00000013820f";
+const PANE_COUNTS = [1, 2, 4, 6];
+const REPS = 5;
+
+interface Stats { n: number; min: number; p50: number; p95: number; max: number }
+
+function stats(samples: number[]): Stats {
+	const sorted = [...samples].sort((a, b) => a - b);
+	const at = (q: number) => sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * q))]!;
+	const round = (value: number) => Math.round(value * 10) / 10;
+	return {
+		n: sorted.length,
+		min: round(sorted[0]!),
+		p50: round(at(0.5)),
+		p95: round(at(0.95)),
+		max: round(sorted[sorted.length - 1]!),
+	};
+}
+
+async function main(): Promise<void> {
+	const root = mkdtempSync(join(tmpdir(), "dev3-native-pane-latency-"));
+	const work = join(root, "work");
+	mkdirSync(work, { recursive: true });
+	process.env.DEV3_NATIVE_SESSIONS_DIR = join(root, "native-sessions");
+	process.env[NATIVE_MULTIPANE_DIR_ENV] = join(root, "native-multipane");
+	process.env.DEV3_NATIVE_HOST_IMAGES_DIR = join(root, "host-images");
+	process.env.DEV3_LOG_DIR = join(root, "logs");
+
+	// Imported after the redirects: the path modules read these on first use.
+	const panes = await import("../src/bun/native-task-panes");
+	const { defaultNativeShellLaunchSpec } = await import("../src/bun/native-terminal-registry/shell-launch");
+	const { restoreSplitTree } = await import("../src/shared/split-tree");
+	const { applySplitLayout, nextSplitLayoutPreset, SPLIT_LAYOUT_PRESETS } =
+		await import("../src/shared/split-tree-layouts");
+
+	const defaults = defaultNativeShellLaunchSpec({ platform: process.platform, cwd: work, env: process.env });
+	const launch = { executable: defaults.executable, argv: [...defaults.argv] };
+
+	const byPaneCount: Record<string, unknown> = {};
+	const startedAt = performance.now();
+	await panes.startNativeTaskPanes({ taskId: TASK_ID, cwd: work, env: {}, launch, cols: 120, rows: 40 });
+	const startMs = Math.round((performance.now() - startedAt) * 10) / 10;
+
+	try {
+		for (const target of PANE_COUNTS) {
+			for (;;) {
+				const state = await panes.nativeTaskPanesState(TASK_ID);
+				if (!state || state.panes.length >= target) break;
+				const from = state.panes[state.panes.length - 1]!.paneId;
+				await panes.splitNativeTaskPane(TASK_ID, from, "horizontal", { cwd: work, env: {}, launch });
+			}
+
+			const readState: number[] = [];
+			const layoutPreset: number[] = [];
+			const layoutCycle: number[] = [];
+			for (let rep = 0; rep < REPS; rep++) {
+				let mark = performance.now();
+				const state = await panes.nativeTaskPanesState(TASK_ID);
+				readState.push(performance.now() - mark);
+				const tree = restoreSplitTree(state!.layout)!;
+				if (state!.panes.length < 2) continue;
+
+				mark = performance.now();
+				await panes.setNativeTaskPaneLayout(TASK_ID, applySplitLayout(tree, "even-horizontal"));
+				layoutPreset.push(performance.now() - mark);
+
+				const next = nextSplitLayoutPreset(SPLIT_LAYOUT_PRESETS[rep % SPLIT_LAYOUT_PRESETS.length]!);
+				mark = performance.now();
+				await panes.setNativeTaskPaneLayout(TASK_ID, applySplitLayout(tree, next));
+				layoutCycle.push(performance.now() - mark);
+			}
+
+			// A split adds a pane, so measure it and close the extra one back off.
+			const splitSamples: number[] = [];
+			for (let rep = 0; rep < REPS; rep++) {
+				const before = (await panes.nativeTaskPanesState(TASK_ID))!;
+				const mark = performance.now();
+				const created = await panes.splitNativeTaskPane(TASK_ID, before.panes[0]!.paneId, "vertical", {
+					cwd: work,
+					env: {},
+					launch,
+				});
+				splitSamples.push(performance.now() - mark);
+				await panes.closeNativeTaskPane(TASK_ID, created.paneId);
+			}
+
+			byPaneCount[String(target)] = {
+				readState: stats(readState),
+				layoutPreset: layoutPreset.length ? stats(layoutPreset) : null,
+				layoutCycle: layoutCycle.length ? stats(layoutCycle) : null,
+				split: stats(splitSamples),
+			};
+			console.error(`  measured panes=${target}`);
+		}
+
+		console.log(JSON.stringify({ platform: process.platform, bun: Bun.version, startMs, byPaneCount }, null, 2));
+	} finally {
+		await panes.stopNativeTaskPanes(TASK_ID).catch(() => {});
+		rmSync(root, { recursive: true, force: true });
+	}
+	// The registry holds host sockets open; nothing else keeps this process useful.
+	process.exit(0);
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

src/bun/native-task-panes.ts

@@ -182,6 +182,20 @@ export async function nativeTaskPanesState(taskId: string): Promise<NativeTaskPa
 	return buildState(taskId);
 }
 
+/**
+ * The layout half of the state only: the shared tree plus its active pane. Skips
+ * the per-pane `ps` ownership sweep that {@link buildState} needs, which no pane
+ * ACTION reads — every action decides from the tree. Recovery still runs, so dead
+ * panes are reconciled exactly as before.
+ */
+export async function nativeTaskPaneLayout(taskId: string): Promise<SplitTree | null> {
+	const backend = getBackend();
+	const coordId = coordinatorId(taskId);
+	const sessionState = await backend.describeSession(coordId);
+	if (!sessionState) return null;
+	return backend.paneLayout(coordId);
+}
+
 /**
  * Split an existing pane, spawning a new independent shell in the task's own
  * cwd and env — both required, so a split can never land in `/tmp` with an empty
@@ -303,11 +317,19 @@ export async function stopNativeTaskPanes(taskId: string): Promise<void> {
  * Panes whose record is unreadable are reported with an empty command rather
  * than dropped, so the caller still sees the pane exists.
  */
-export async function nativeTaskPaneCommands(
-	taskId: string,
-): Promise<Array<{ paneId: string; sessionId: string; command: string[]; shellPid: number; alive: boolean }>> {
-	const state = await nativeTaskPanesState(taskId);
-	if (!state) return [];
+export interface NativeTaskPaneCommand {
+	paneId: string;
+	sessionId: string;
+	command: string[];
+	shellPid: number;
+	alive: boolean;
+}
+
+/**
+ * Same, from a state the caller already read. A pane action rebuilds the state once
+ * and needs the labels off it; re-reading would double the ownership sweep.
+ */
+export function nativeTaskPaneCommandsOf(state: NativeTaskPanesState): NativeTaskPaneCommand[] {
 	return state.panes.map((pane) => ({
 		paneId: pane.paneId,
 		sessionId: pane.sessionId,
@@ -317,6 +339,11 @@ export async function nativeTaskPaneCommands(
 	}));
 }
 
+export async function nativeTaskPaneCommands(taskId: string): Promise<NativeTaskPaneCommand[]> {
+	const state = await nativeTaskPanesState(taskId);
+	return state ? nativeTaskPaneCommandsOf(state) : [];
+}
+
 /**
  * True when the coordinator record exists and contains at least one owned pane.
  * Read-only: does NOT register or cache the recovered coordinator as a side effect.

src/bun/native-terminal-multipane/__tests__/coordinator.test.ts

@@ -325,3 +325,58 @@ describe("native multipane coordinator capturePane", () => {
 		await expect(coordinator.capturePane("ghost", false)).rejects.toBeInstanceOf(PaneNotFoundError);
 	});
 });
+
+// ── Ownership fan-out on the click path (seq 1382) ────────────────────────────
+
+describe("native multipane coordinator ownership fan-out", () => {
+	let root: string;
+	let deps: FakeRegistry;
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "dev3-multipane-fanout-"));
+		process.env[NATIVE_MULTIPANE_DIR_ENV] = root;
+		deps = createFakeRegistry();
+	});
+
+	afterEach(() => {
+		delete process.env[NATIVE_MULTIPANE_DIR_ENV];
+		rmSync(root, { recursive: true, force: true });
+	});
+
+	/** Count how many classifications are in flight at the same moment. */
+	function gateClassify(deps: FakeRegistry): { peak: () => number; release: () => void } {
+		const original = deps.classifyPane;
+		let inFlight = 0;
+		let peak = 0;
+		let release!: () => void;
+		const gate = new Promise<void>((resolve) => { release = resolve; });
+		deps.classifyPane = async (record, token) => {
+			inFlight++;
+			peak = Math.max(peak, inFlight);
+			await gate;
+			inFlight--;
+			return original(record, token);
+		};
+		return { peak: () => peak, release };
+	}
+
+	it("classifies every pane at once when listing a 6-pane set", async () => {
+		const coordinator = await createWithPanes(deps, 6);
+		const gate = gateClassify(deps);
+		const listing = coordinator.listPanes();
+		await Promise.resolve();
+		expect(gate.peak()).toBe(6);
+		gate.release();
+		expect(await listing).toHaveLength(6);
+	});
+
+	it("classifies every pane at once while recovering a 6-pane set", async () => {
+		await createWithPanes(deps, 6);
+		const gate = gateClassify(deps);
+		const recovering = NativeMultipaneCoordinator.recover(ID, deps);
+		await Promise.resolve();
+		expect(gate.peak()).toBe(6);
+		gate.release();
+		expect((await recovering)?.paneIds()).toHaveLength(6);
+	});
+});

src/bun/native-terminal-multipane/coordinator.ts

@@ -211,10 +211,13 @@ export class NativeMultipaneCoordinator {
 				const tree = restoreSplitTree(record.layout);
 				if (!tree) return null;
 
-				const dead: MultipanePaneEntry[] = [];
-				for (const pane of record.panes) {
-					if (!(await isPaneOwned(pane.sessionId, deps))) dead.push(pane);
-				}
+				// One classification per pane, all in flight at once: each probe shells out
+				// to `ps`, so doing them in sequence made recovery cost grow linearly with
+				// the pane count on the click path (seq 1382).
+				const ownership = await Promise.all(
+					record.panes.map(async (pane) => ({ pane, owned: await isPaneOwned(pane.sessionId, deps) })),
+				);
+				const dead = ownership.filter((entry) => !entry.owned).map((entry) => entry.pane);
 				if (dead.length === 0) {
 					return new NativeMultipaneCoordinator(coordinatorId, record.epoch, tree, deps);
 				}
@@ -252,26 +255,27 @@ export class NativeMultipaneCoordinator {
 
 	/** Per-pane host/shell identity, read from each pane's own registry record. */
 	async listPanes(): Promise<PaneSnapshot[]> {
-		const out: PaneSnapshot[] = [];
-		for (const paneId of this.paneIds()) {
-			const sessionId = paneSessionId(this.coordinatorId, paneId);
-			const record = this.deps.readPaneRecord(sessionId);
-			if (!record) {
-				out.push({ paneId, sessionId, hostPid: -1, shellPid: -1, cols: 0, rows: 0, state: "dead" });
-				continue;
-			}
-			const verdict = await this.deps.classifyPane(record, this.deps.readPaneToken(sessionId));
-			out.push({
-				paneId,
-				sessionId,
-				hostPid: record.host.pid,
-				shellPid: record.shell.pid,
-				cols: record.cols,
-				rows: record.rows,
-				state: verdict === "owned" ? "running" : verdict,
-			});
-		}
-		return out;
+		// Fan out over the pane set, bounded by the pane count: every snapshot needs
+		// its own `ps` probe, and in sequence that dominated every pane action.
+		return Promise.all(
+			this.paneIds().map(async (paneId): Promise<PaneSnapshot> => {
+				const sessionId = paneSessionId(this.coordinatorId, paneId);
+				const record = this.deps.readPaneRecord(sessionId);
+				if (!record) {
+					return { paneId, sessionId, hostPid: -1, shellPid: -1, cols: 0, rows: 0, state: "dead" };
+				}
+				const verdict = await this.deps.classifyPane(record, this.deps.readPaneToken(sessionId));
+				return {
+					paneId,
+					sessionId,
+					hostPid: record.host.pid,
+					shellPid: record.shell.pid,
+					cols: record.cols,
+					rows: record.rows,
+					state: verdict === "owned" ? "running" : verdict,
+				};
+			}),
+		);
 	}
 
 	/**