@agentuity/opencode 0.1.42 → 0.1.43

package/src/tmux/executor.ts

@@ -1,18 +1,7 @@
 import type { PaneAction, WindowState, TmuxConfig } from './types';
 import { runTmuxCommand, runTmuxCommandSync } from './utils';
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { spawn, spawnSync } from 'bun';
 
-/**
- * Path to persist the agents window ID for crash recovery.
- * Uses ~/.config/agentuity/coder/cache/ which is consistent with other Agentuity paths
- * and likely exists for any Agentuity user.
- */
-const CACHE_DIR = join(homedir(), '.config', 'agentuity', 'coder', 'cache');
-const AGENTS_WINDOW_FILE = join(CACHE_DIR, 'agents-window-id');
-
 /**
  * Escape a string for safe use in shell commands.
  * Wraps in single quotes and escapes any internal single quotes.
@@ -25,6 +14,25 @@ function shellEscape(str: string): string {
 /** Maximum retries for recursive spawn attempts to prevent infinite loops */
 const MAX_SPAWN_RETRIES = 3;
 
+const OPENCODE_TAG = '@agentuity.opencode';
+const OPENCODE_SERVER_TAG = '@agentuity.opencode.server';
+const OPENCODE_OWNER_TAG = '@agentuity.opencode.ownerPid';
+const OPENCODE_INSTANCE_TAG = '@agentuity.opencode.instance';
+const OPENCODE_SESSION_TAG = '@agentuity.opencode.session';
+
+type OwnershipContext = {
+	instanceId: string;
+	ownerPid: number;
+	serverKey: string;
+	tmuxSessionId?: string;
+};
+
+type OwnershipLookup = {
+	serverKey: string;
+	instanceId: string;
+	tmuxSessionId?: string;
+};
+
 export interface ActionResult {
 	success: boolean;
 	paneId?: string;
@@ -45,7 +53,7 @@ function isProcessAlive(pid: number): boolean {
 	}
 }
 
-async function getPanePid(paneId: string): Promise<number | undefined> {
+export async function getPanePid(paneId: string): Promise<number | undefined> {
 	if (!paneId) return undefined;
 	const result = await runTmuxCommand(['display', '-p', '-t', paneId, '#{pane_pid}']);
 	if (!result.success) return undefined;
@@ -54,6 +62,185 @@ async function getPanePid(paneId: string): Promise<number | undefined> {
 	return pid;
 }
 
+export function getPanePidSync(paneId: string): number | undefined {
+	if (!paneId) return undefined;
+	const result = runTmuxCommandSync(['display', '-p', '-t', paneId, '#{pane_pid}']);
+	if (!result.success) return undefined;
+	const pid = Number(result.output.trim());
+	if (!Number.isFinite(pid) || pid <= 0) return undefined;
+	return pid;
+}
+
+async function resolvePanePidWithRetry(
+	paneId: string,
+	maxAttempts = 3,
+	delayMs = 75
+): Promise<number | undefined> {
+	let pid = await getPanePid(paneId);
+	if (pid) return pid;
+	for (let attempt = 1; attempt < maxAttempts; attempt += 1) {
+		await new Promise((resolve) => setTimeout(resolve, delayMs));
+		pid = await getPanePid(paneId);
+		if (pid) return pid;
+	}
+	return pid;
+}
+
+async function setWindowTags(windowId: string, ownership: OwnershipContext): Promise<void> {
+	await runTmuxCommand(['set-option', '-w', '-t', windowId, OPENCODE_TAG, '1']);
+	await runTmuxCommand([
+		'set-option',
+		'-w',
+		'-t',
+		windowId,
+		OPENCODE_SERVER_TAG,
+		ownership.serverKey,
+	]);
+	await runTmuxCommand([
+		'set-option',
+		'-w',
+		'-t',
+		windowId,
+		OPENCODE_OWNER_TAG,
+		String(ownership.ownerPid),
+	]);
+	await runTmuxCommand([
+		'set-option',
+		'-w',
+		'-t',
+		windowId,
+		OPENCODE_INSTANCE_TAG,
+		ownership.instanceId,
+	]);
+}
+
+async function setPaneTags(
+	paneId: string,
+	ownership: OwnershipContext,
+	sessionId?: string
+): Promise<void> {
+	await runTmuxCommand([
+		'set-option',
+		'-p',
+		'-t',
+		paneId,
+		OPENCODE_INSTANCE_TAG,
+		ownership.instanceId,
+	]);
+	if (sessionId) {
+		await runTmuxCommand(['set-option', '-p', '-t', paneId, OPENCODE_SESSION_TAG, sessionId]);
+	}
+}
+
+async function findOwnedAgentsWindow(
+	serverKey: string,
+	instanceId: string,
+	tmuxSessionId?: string
+): Promise<string | undefined> {
+	const result = await runTmuxCommand([
+		'list-windows',
+		'-a',
+		'-F',
+		`#{window_id}\t#{window_name}\t#{${OPENCODE_TAG}}\t#{${OPENCODE_SERVER_TAG}}\t#{${OPENCODE_INSTANCE_TAG}}\t#{session_id}`,
+	]);
+	if (!result.success || !result.output) return undefined;
+
+	for (const line of result.output.split('\n')) {
+		const [windowId, windowName, isOpencode, windowServerKey, windowInstanceId, sessionId] =
+			line.split('\t');
+		if (!windowId) continue;
+		if (windowName !== 'Agents') continue;
+		if (isOpencode !== '1') continue;
+		if (windowServerKey !== serverKey) continue;
+		if (windowInstanceId !== instanceId) continue;
+		// If tmuxSessionId is provided, only match windows in that session
+		if (tmuxSessionId && sessionId !== tmuxSessionId) continue;
+		return windowId;
+	}
+
+	return undefined;
+}
+
+function findOwnedAgentsWindowSync(
+	serverKey: string,
+	instanceId: string,
+	tmuxSessionId?: string
+): string | undefined {
+	const result = runTmuxCommandSync([
+		'list-windows',
+		'-a',
+		'-F',
+		`#{window_id}\t#{window_name}\t#{${OPENCODE_TAG}}\t#{${OPENCODE_SERVER_TAG}}\t#{${OPENCODE_INSTANCE_TAG}}\t#{session_id}`,
+	]);
+	if (!result.success || !result.output) return undefined;
+
+	for (const line of result.output.split('\n')) {
+		const [windowId, windowName, isOpencode, windowServerKey, windowInstanceId, sessionId] =
+			line.split('\t');
+		if (!windowId) continue;
+		if (windowName !== 'Agents') continue;
+		if (isOpencode !== '1') continue;
+		if (windowServerKey !== serverKey) continue;
+		if (windowInstanceId !== instanceId) continue;
+		// If tmuxSessionId is provided, only match windows in that session
+		if (tmuxSessionId && sessionId !== tmuxSessionId) continue;
+		return windowId;
+	}
+
+	return undefined;
+}
+
+export async function findOwnedAgentPanes(
+	serverKey: string
+): Promise<Array<{ paneId: string; panePid?: number; sessionId?: string; instanceId?: string }>> {
+	const windowsResult = await runTmuxCommand([
+		'list-windows',
+		'-a',
+		'-F',
+		`#{window_id}\t#{${OPENCODE_SERVER_TAG}}`,
+	]);
+	if (!windowsResult.success || !windowsResult.output) return [];
+
+	const serverWindowIds = new Set<string>();
+	for (const line of windowsResult.output.split('\n')) {
+		const [windowId, windowServerKey] = line.split('\t');
+		if (!windowId) continue;
+		if (windowServerKey !== serverKey) continue;
+		serverWindowIds.add(windowId);
+	}
+	if (serverWindowIds.size === 0) return [];
+
+	const result = await runTmuxCommand([
+		'list-panes',
+		'-a',
+		'-F',
+		`#{pane_id}\t#{pane_pid}\t#{window_id}\t#{${OPENCODE_INSTANCE_TAG}}\t#{${OPENCODE_SESSION_TAG}}`,
+	]);
+	if (!result.success || !result.output) return [];
+
+	const panes: Array<{
+		paneId: string;
+		panePid?: number;
+		sessionId?: string;
+		instanceId?: string;
+	}> = [];
+
+	for (const line of result.output.split('\n')) {
+		const [paneId, panePidRaw, windowId, paneInstanceId, paneSessionId] = line.split('\t');
+		if (!paneId) continue;
+		if (!windowId || !serverWindowIds.has(windowId)) continue;
+		const panePid = Number(panePidRaw);
+		panes.push({
+			paneId,
+			panePid: Number.isFinite(panePid) && panePid > 0 ? panePid : undefined,
+			sessionId: paneSessionId || undefined,
+			instanceId: paneInstanceId || undefined,
+		});
+	}
+
+	return panes;
+}
+
 /**
  * Kill a process and all its children (the entire process tree).
  *
@@ -114,53 +301,34 @@ export async function killProcessByPid(pid: number): Promise<boolean> {
 
 /**
  * State for separate-window mode - tracks the dedicated "Agents" window
+ * Keyed by `${serverKey}:${instanceId}:${tmuxSessionId}` to support multiple
+ * opencode instances running in different tmux sessions.
  */
-let agentsWindowId: string | undefined;
-
-/**
- * Ensure the cache directory exists
- */
-function ensureCacheDir(): void {
-	if (!existsSync(CACHE_DIR)) {
-		mkdirSync(CACHE_DIR, { recursive: true });
-	}
-}
+const agentsWindowIdByKey = new Map<string, string>();
 
 /**
- * Persist the agents window ID to disk for crash recovery
+ * Get the cache key for the agents window
  */
-function persistAgentsWindowId(windowId: string): void {
-	try {
-		ensureCacheDir();
-		writeFileSync(AGENTS_WINDOW_FILE, windowId, 'utf-8');
-	} catch {
-		// Ignore write errors - persistence is best-effort
-	}
+function getAgentsWindowCacheKey(ownership: OwnershipContext): string {
+	return `${ownership.serverKey}:${ownership.instanceId}:${ownership.tmuxSessionId ?? 'default'}`;
 }
 
 /**
- * Load the agents window ID from disk (for crash recovery)
+ * Get the cached agents window ID for the given ownership context
  */
-function loadPersistedAgentsWindowId(): string | undefined {
-	try {
-		if (!existsSync(AGENTS_WINDOW_FILE)) return undefined;
-		const windowId = readFileSync(AGENTS_WINDOW_FILE, 'utf-8').trim();
-		return windowId || undefined;
-	} catch {
-		return undefined;
-	}
+function getCachedAgentsWindowId(ownership: OwnershipContext): string | undefined {
+	return agentsWindowIdByKey.get(getAgentsWindowCacheKey(ownership));
 }
 
 /**
- * Clear the persisted agents window ID
+ * Set the cached agents window ID for the given ownership context
  */
-function clearPersistedAgentsWindowId(): void {
-	try {
-		if (existsSync(AGENTS_WINDOW_FILE)) {
-			unlinkSync(AGENTS_WINDOW_FILE);
-		}
-	} catch {
-		// Ignore delete errors
+function setCachedAgentsWindowId(ownership: OwnershipContext, windowId: string | undefined): void {
+	const key = getAgentsWindowCacheKey(ownership);
+	if (windowId) {
+		agentsWindowIdByKey.set(key, windowId);
+	} else {
+		agentsWindowIdByKey.delete(key);
 	}
 }
 
@@ -171,11 +339,19 @@ function clearPersistedAgentsWindowId(): void {
  */
 export async function executeAction(
 	action: PaneAction,
-	ctx: { config: TmuxConfig; serverUrl: string; windowState: WindowState }
+	ctx: {
+		config: TmuxConfig;
+		serverUrl: string;
+		windowState: WindowState;
+		ownership: OwnershipContext;
+	}
 ): Promise<ActionResult> {
 	switch (action.type) {
 		case 'spawn':
-			return spawnInAgentsWindow(action, { serverUrl: ctx.serverUrl });
+			return spawnInAgentsWindow(action, {
+				serverUrl: ctx.serverUrl,
+				ownership: ctx.ownership,
+			});
 		case 'close':
 			return closePane(action);
 		case 'replace':
@@ -188,7 +364,12 @@ export async function executeAction(
  */
 export async function executeActions(
 	actions: PaneAction[],
-	ctx: { config: TmuxConfig; serverUrl: string; windowState: WindowState }
+	ctx: {
+		config: TmuxConfig;
+		serverUrl: string;
+		windowState: WindowState;
+		ownership: OwnershipContext;
+	}
 ): Promise<{
 	success: boolean;
 	spawnedPaneId?: string;
@@ -226,7 +407,7 @@ async function closePane(action: Extract<PaneAction, { type: 'close' }>): Promis
 export async function closePaneById(paneId: string, pid?: number): Promise<ActionResult> {
 	let resolvedPid = pid;
 	if (!resolvedPid) {
-		resolvedPid = await getPanePid(paneId);
+		resolvedPid = await resolvePanePidWithRetry(paneId);
 	}
 
 	if (resolvedPid) {
@@ -246,18 +427,21 @@ export async function closePaneById(paneId: string, pid?: number): Promise<Actio
  */
 async function replacePane(
 	action: Extract<PaneAction, { type: 'replace' }>,
-	ctx: { serverUrl: string }
+	ctx: { serverUrl: string; ownership: OwnershipContext }
 ): Promise<ActionResult> {
-	// Pane kills itself when opencode attach exits (for any reason)
+	// Use exec to replace bash with opencode attach directly.
+	// This ensures signals go directly to opencode attach (no wrapper process).
+	// When opencode attach exits, the pane closes automatically (tmux remain-on-exit off).
 	// Use shellEscape to prevent shell injection via session IDs
 	const escapedServerUrl = shellEscape(ctx.serverUrl);
 	const escapedSessionId = shellEscape(action.newSessionId);
-	const command = `opencode attach ${escapedServerUrl} --session ${escapedSessionId}; tmux kill-pane`;
+	const command = `exec opencode attach ${escapedServerUrl} --session ${escapedSessionId}`;
 	const result = await runTmuxCommand(['respawn-pane', '-k', '-t', action.paneId, command]);
 	if (!result.success) {
 		return { success: false, error: result.output };
 	}
-	const pid = await getPanePid(action.paneId);
+	await setPaneTags(action.paneId, ctx.ownership, action.newSessionId);
+	const pid = await resolvePanePidWithRetry(action.paneId);
 	return { success: true, paneId: action.paneId, pid };
 }
 
@@ -275,7 +459,7 @@ async function replacePane(
  */
 async function spawnInAgentsWindow(
 	action: Extract<PaneAction, { type: 'spawn' }>,
-	ctx: { serverUrl: string },
+	ctx: { serverUrl: string; ownership: OwnershipContext },
 	retryCount = 0
 ): Promise<ActionResult> {
 	// Prevent infinite recursion if tmux keeps failing
@@ -286,41 +470,77 @@ async function spawnInAgentsWindow(
 		};
 	}
 
-	// Pane kills itself when opencode attach exits (session complete, server died, etc.)
+	// Use exec to replace bash with opencode attach directly.
+	// This ensures signals go directly to opencode attach (no wrapper process).
+	// When opencode attach exits, the pane closes automatically (tmux remain-on-exit off).
 	// Use shellEscape to prevent shell injection via session IDs
 	const escapedServerUrl = shellEscape(ctx.serverUrl);
 	const escapedSessionId = shellEscape(action.sessionId);
-	const command = `opencode attach ${escapedServerUrl} --session ${escapedSessionId}; tmux kill-pane`;
+	const command = `exec opencode attach ${escapedServerUrl} --session ${escapedSessionId}`;
 	const layout = 'tiled'; // Always use tiled layout for grid arrangement
 
 	// Check if we have a cached agents window ID and if it still exists
-	if (agentsWindowId) {
+	let cachedWindowId = getCachedAgentsWindowId(ctx.ownership);
+	if (cachedWindowId) {
 		const checkResult = await runTmuxCommand([
-			'list-panes',
+			'display',
+			'-p',
 			'-t',
-			agentsWindowId,
-			'-F',
-			'#{pane_id}',
+			cachedWindowId,
+			`#{${OPENCODE_TAG}}\t#{${OPENCODE_SERVER_TAG}}\t#{${OPENCODE_INSTANCE_TAG}}`,
 		]);
 
-		if (!checkResult.success) {
-			// Window no longer exists, clear the cache
-			agentsWindowId = undefined;
+		if (!checkResult.success || !checkResult.output) {
+			setCachedAgentsWindowId(ctx.ownership, undefined);
+			cachedWindowId = undefined;
+		} else {
+			const [isOpencode, windowServerKey, windowInstanceId] = checkResult.output
+				.trim()
+				.split('\t');
+			if (
+				isOpencode !== '1' ||
+				windowServerKey !== ctx.ownership.serverKey ||
+				windowInstanceId !== ctx.ownership.instanceId
+			) {
+				setCachedAgentsWindowId(ctx.ownership, undefined);
+				cachedWindowId = undefined;
+			}
+		}
+	}
+
+	if (!cachedWindowId) {
+		cachedWindowId = await findOwnedAgentsWindow(
+			ctx.ownership.serverKey,
+			ctx.ownership.instanceId,
+			ctx.ownership.tmuxSessionId
+		);
+		if (cachedWindowId) {
+			setCachedAgentsWindowId(ctx.ownership, cachedWindowId);
 		}
 	}
 
 	// If no agents window exists, create one
-	if (!agentsWindowId) {
-		const createResult = await runTmuxCommand([
-			'new-window',
+	if (!cachedWindowId) {
+		// Build the new-window command args
+		// CRITICAL: Use -t <session>: to target the correct tmux session
+		// Without this, tmux may create the window in the wrong session when
+		// multiple opencode instances run in different tmux sessions
+		const newWindowArgs = ['new-window'];
+		if (ctx.ownership.tmuxSessionId) {
+			// Target the specific tmux session (the colon after session_id is important)
+			newWindowArgs.push('-t', `${ctx.ownership.tmuxSessionId}:`);
+		}
+		newWindowArgs.push(
 			'-d', // Don't switch to new window
 			'-P',
 			'-F',
 			'#{window_id}:#{pane_id}',
 			'-n',
 			'Agents',
-			command,
-		]);
+			command
+		);
+
+		const createResult = await runTmuxCommand(newWindowArgs);
 
 		if (!createResult.success) {
 			return { success: false, error: createResult.output };
@@ -329,19 +549,23 @@ async function spawnInAgentsWindow(
 		// Parse window_id:pane_id from output
 		const output = createResult.output?.trim() || '';
 		const [windowId, paneId] = output.split(':');
-		agentsWindowId = windowId;
+		cachedWindowId = windowId;
 
-		// Persist for crash recovery
-		if (agentsWindowId) {
-			persistAgentsWindowId(agentsWindowId);
+		if (cachedWindowId) {
+			setCachedAgentsWindowId(ctx.ownership, cachedWindowId);
+			await setWindowTags(cachedWindowId, ctx.ownership);
 		}
 
 		// Apply initial layout (useful when more panes are added later)
-		if (agentsWindowId && layout) {
-			await runTmuxCommand(['select-layout', '-t', agentsWindowId, layout]);
+		if (cachedWindowId && layout) {
+			await runTmuxCommand(['select-layout', '-t', cachedWindowId, layout]);
+		}
+
+		if (paneId) {
+			await setPaneTags(paneId, ctx.ownership, action.sessionId);
 		}
 
-		const pid = paneId ? await getPanePid(paneId) : undefined;
+		const pid = paneId ? await resolvePanePidWithRetry(paneId) : undefined;
 		return { success: true, paneId, windowId, pid };
 	}
 
@@ -350,21 +574,21 @@ async function spawnInAgentsWindow(
 	const listResult = await runTmuxCommand([
 		'list-panes',
 		'-t',
-		agentsWindowId,
+		cachedWindowId,
 		'-F',
 		'#{pane_id}',
 	]);
 
 	if (!listResult.success || !listResult.output) {
 		// Fallback: create new window (with retry counter)
-		agentsWindowId = undefined;
+		setCachedAgentsWindowId(ctx.ownership, undefined);
 		return spawnInAgentsWindow(action, ctx, retryCount + 1);
 	}
 
 	const targetPaneId = listResult.output.split('\n')[0]?.trim();
 	if (!targetPaneId) {
 		// Fallback: create new window (with retry counter)
-		agentsWindowId = undefined;
+		setCachedAgentsWindowId(ctx.ownership, undefined);
 		return spawnInAgentsWindow(action, ctx, retryCount + 1);
 	}
 
@@ -385,234 +609,371 @@ async function spawnInAgentsWindow(
 	}
 
 	const paneId = splitResult.output?.trim();
+	if (cachedWindowId) {
+		await setWindowTags(cachedWindowId, ctx.ownership);
+	}
+	if (paneId) {
+		await setPaneTags(paneId, ctx.ownership, action.sessionId);
+	}
 
 	// Apply the configured layout to the agents window (e.g., tiled for grid)
-	if (agentsWindowId && layout) {
-		await runTmuxCommand(['select-layout', '-t', agentsWindowId, layout]);
+	if (cachedWindowId && layout) {
+		await runTmuxCommand(['select-layout', '-t', cachedWindowId, layout]);
 	}
 
-	const pid = paneId ? await getPanePid(paneId) : undefined;
+	const pid = paneId ? await resolvePanePidWithRetry(paneId) : undefined;
 	return {
 		success: true,
 		paneId: paneId || undefined,
-		windowId: agentsWindowId,
+		windowId: cachedWindowId,
 		pid,
 	};
 }
 
+function killProcessByPidSync(pid: number): void {
+	if (!Number.isFinite(pid) || pid <= 0) return;
+
+	try {
+		spawnSync(['pkill', '-TERM', '-P', String(pid)]);
+	} catch {
+		// Ignore errors - children may not exist
+	}
+
+	try {
+		process.kill(pid, 'SIGTERM');
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === 'ESRCH') return;
+	}
+
+	try {
+		const buffer = new SharedArrayBuffer(4);
+		const view = new Int32Array(buffer);
+		Atomics.wait(view, 0, 0, PROCESS_TERM_WAIT_MS);
+	} catch {
+		// ignore sleep errors
+	}
+
+	try {
+		process.kill(pid, 0);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === 'ESRCH') return;
+	}
+
+	try {
+		spawnSync(['pkill', '-KILL', '-P', String(pid)]);
+	} catch {
+		// Ignore errors
+	}
+
+	try {
+		process.kill(pid, 'SIGKILL');
+	} catch {
+		// ignore errors
+	}
+}
+
 /**
  * Reset the agents window state (for cleanup)
  */
-export function resetAgentsWindow(): void {
-	agentsWindowId = undefined;
-	clearPersistedAgentsWindowId();
+export function resetAgentsWindow(ownership?: OwnershipContext): void {
+	if (ownership) {
+		setCachedAgentsWindowId(ownership, undefined);
+	} else {
+		agentsWindowIdByKey.clear();
+	}
 }
 
 /**
  * Close the agents window if it exists
  * This kills the entire window, which closes all panes within it
+ *
+ * SAFETY: Verifies the window is named "Agents" before killing to prevent
+ * accidentally killing user windows if the cached ID is stale.
  */
-export async function closeAgentsWindow(): Promise<void> {
-	// Try to recover window ID from disk if not in memory
-	const windowId = agentsWindowId ?? loadPersistedAgentsWindowId();
+export async function closeAgentsWindow(ownership?: OwnershipLookup): Promise<void> {
+	// Build a pseudo-ownership context for cache lookup
+	const cacheKey = ownership
+		? {
+				serverKey: ownership.serverKey,
+				instanceId: ownership.instanceId,
+				ownerPid: 0,
+				tmuxSessionId: ownership.tmuxSessionId,
+			}
+		: undefined;
+	const cachedId = cacheKey ? getCachedAgentsWindowId(cacheKey) : undefined;
+	const windowId =
+		cachedId ??
+		(ownership
+			? await findOwnedAgentsWindow(
+					ownership.serverKey,
+					ownership.instanceId,
+					ownership.tmuxSessionId
+				)
+			: undefined);
 	if (!windowId) return;
 
-	// Kill the entire window (closes all panes within it)
+	const checkFormat = ownership
+		? `#{window_name}\t#{${OPENCODE_TAG}}\t#{${OPENCODE_SERVER_TAG}}\t#{${OPENCODE_INSTANCE_TAG}}`
+		: '#{window_name}';
+	const checkResult = await runTmuxCommand(['display', '-p', '-t', windowId, checkFormat]);
+
+	if (!checkResult.success) {
+		if (cacheKey) setCachedAgentsWindowId(cacheKey, undefined);
+		return;
+	}
+
+	const parts = checkResult.output?.trim().split('\t') ?? [];
+	const windowName = parts[0];
+	if (windowName !== 'Agents') {
+		if (cacheKey) setCachedAgentsWindowId(cacheKey, undefined);
+		return;
+	}
+	if (ownership) {
+		const [, isOpencode, windowServerKey, windowInstanceId] = parts;
+		if (
+			isOpencode !== '1' ||
+			windowServerKey !== ownership.serverKey ||
+			windowInstanceId !== ownership.instanceId
+		) {
+			if (cacheKey) setCachedAgentsWindowId(cacheKey, undefined);
+			return;
+		}
+	}
+
 	await runTmuxCommand(['kill-window', '-t', windowId]);
-	agentsWindowId = undefined;
-	clearPersistedAgentsWindowId();
+	if (cacheKey) setCachedAgentsWindowId(cacheKey, undefined);
 }
 
 /**
  * Synchronously close the agents window (for shutdown)
- * Uses spawnSync to ensure it completes before process exit
+ * Uses runTmuxCommandSync to ensure it completes before process exit
+ *
+ * SAFETY: Verifies the window is named "Agents" before killing to prevent
+ * accidentally killing user windows if the cached ID is stale.
  */
-export function closeAgentsWindowSync(): void {
-	// Try to recover window ID from disk if not in memory
-	const windowId = agentsWindowId ?? loadPersistedAgentsWindowId();
+export function closeAgentsWindowSync(ownership?: OwnershipLookup): void {
+	// Build a pseudo-ownership context for cache lookup
+	const cacheKey = ownership
+		? {
+				serverKey: ownership.serverKey,
+				instanceId: ownership.instanceId,
+				ownerPid: 0,
+				tmuxSessionId: ownership.tmuxSessionId,
+			}
+		: undefined;
+	const cachedId = cacheKey ? getCachedAgentsWindowId(cacheKey) : undefined;
+	const windowId =
+		cachedId ??
+		(ownership
+			? findOwnedAgentsWindowSync(
+					ownership.serverKey,
+					ownership.instanceId,
+					ownership.tmuxSessionId
+				)
+			: undefined);
 	if (!windowId) return;
 
-	// Kill the entire window synchronously
+	const checkFormat = ownership
+		? `#{window_name}\t#{${OPENCODE_TAG}}\t#{${OPENCODE_SERVER_TAG}}\t#{${OPENCODE_INSTANCE_TAG}}`
+		: '#{window_name}';
+	const checkResult = runTmuxCommandSync(['display', '-p', '-t', windowId, checkFormat]);
+
+	if (!checkResult.success) {
+		if (cacheKey) setCachedAgentsWindowId(cacheKey, undefined);
+		return;
+	}
+
+	const parts = checkResult.output?.trim().split('\t') ?? [];
+	const windowName = parts[0];
+	if (windowName !== 'Agents') {
+		if (cacheKey) setCachedAgentsWindowId(cacheKey, undefined);
+		return;
+	}
+	if (ownership) {
+		const [, isOpencode, windowServerKey, windowInstanceId] = parts;
+		if (
+			isOpencode !== '1' ||
+			windowServerKey !== ownership.serverKey ||
+			windowInstanceId !== ownership.instanceId
+		) {
+			if (cacheKey) setCachedAgentsWindowId(cacheKey, undefined);
+			return;
+		}
+	}
+
 	runTmuxCommandSync(['kill-window', '-t', windowId]);
-	agentsWindowId = undefined;
-	clearPersistedAgentsWindowId();
+	if (cacheKey) setCachedAgentsWindowId(cacheKey, undefined);
 }
 
 /**
  * Get the current agents window ID (for testing/debugging)
- * Also checks persisted file for crash recovery
  */
-export function getAgentsWindowId(): string | undefined {
-	return agentsWindowId ?? loadPersistedAgentsWindowId();
+export function getAgentsWindowId(ownership?: OwnershipContext): string | undefined {
+	if (ownership) {
+		return getCachedAgentsWindowId(ownership);
+	}
+	// Return first cached window ID (for backwards compatibility in tests)
+	const values = agentsWindowIdByKey.values();
+	const first = values.next();
+	return first.done ? undefined : first.value;
 }
 
 /**
- * Kill all orphaned opencode attach processes for a given server URL.
- * This is a fallback cleanup method when PID-based cleanup fails.
- *
- * @param serverUrl - The server URL to match (optional, kills all if not provided)
- * @param logger - Optional logging function for debug output
- * @returns Number of processes killed
+ * Clean up owned tmux windows/panes using ownership tags.
  */
-export async function killOrphanedAttachProcesses(
-	serverUrl?: string,
-	logger?: (msg: string) => void
-): Promise<number> {
-	const log = logger ?? (() => {});
-
-	try {
-		// Use pkill with pattern matching for opencode attach
-		const { spawn } = await import('bun');
-
-		// First, find matching processes to log what we're killing
-		const psProc = spawn(['ps', 'aux'], { stdout: 'pipe', stderr: 'pipe' });
-		await psProc.exited;
-		const psOutput = await new Response(psProc.stdout).text();
-		const lines = psOutput.split('\n');
-
-		const matchingPids: number[] = [];
-		for (const line of lines) {
-			if (!line.includes('opencode attach')) continue;
-			if (serverUrl && !line.includes(serverUrl)) continue;
-			// Don't kill ourselves
-			if (line.includes(String(process.pid))) continue;
-
-			const parts = line.trim().split(/\s+/);
-			const pid = Number(parts[1]);
-			if (Number.isFinite(pid) && pid > 0) {
-				matchingPids.push(pid);
+export async function cleanupOwnedResources(
+	serverKey: string,
+	instanceId: string
+): Promise<{ panesClosed: number; windowClosed: boolean }> {
+	if (!instanceId) return { panesClosed: 0, windowClosed: false };
+
+	const windowsResult = await runTmuxCommand([
+		'list-windows',
+		'-a',
+		'-F',
+		`#{window_id}\t#{window_name}\t#{${OPENCODE_TAG}}\t#{${OPENCODE_SERVER_TAG}}\t#{${OPENCODE_INSTANCE_TAG}}`,
+	]);
+	const windowsToClose = new Set<string>();
+	const serverWindowIds = new Set<string>();
+
+	if (windowsResult.success && windowsResult.output) {
+		for (const line of windowsResult.output.split('\n')) {
+			const [windowId, windowName, isOpencode, windowServerKey, windowInstanceId] =
+				line.split('\t');
+			if (!windowId) continue;
+			if (windowServerKey === serverKey) {
+				serverWindowIds.add(windowId);
 			}
+			if (windowName !== 'Agents') continue;
+			if (isOpencode !== '1') continue;
+			if (windowServerKey !== serverKey) continue;
+			if (windowInstanceId !== instanceId) continue;
+			windowsToClose.add(windowId);
 		}
+	}
 
-		if (matchingPids.length === 0) {
-			log('No orphaned opencode attach processes found');
-			return 0;
-		}
+	const panesResult = await runTmuxCommand([
+		'list-panes',
+		'-a',
+		'-F',
+		`#{pane_id}\t#{pane_pid}\t#{window_id}\t#{${OPENCODE_INSTANCE_TAG}}`,
+	]);
 
-		log(`Found ${matchingPids.length} orphaned processes: ${matchingPids.join(', ')}`);
-
-		// Kill each process individually for better control
-		let killed = 0;
-		for (const pid of matchingPids) {
-			try {
-				// Try SIGTERM first
-				process.kill(pid, 'SIGTERM');
-				log(`Sent SIGTERM to PID ${pid}`);
-				killed++;
-			} catch (error) {
-				const code = (error as NodeJS.ErrnoException).code;
-				if (code !== 'ESRCH') {
-					log(`Failed to kill PID ${pid}: ${code}`);
-				}
-			}
+	const panesToClose: Array<{ paneId: string; panePid?: number; windowId: string }> = [];
+	if (panesResult.success && panesResult.output) {
+		for (const line of panesResult.output.split('\n')) {
+			const [paneId, panePidRaw, windowId, paneInstanceId] = line.split('\t');
+			if (!paneId) continue;
+			if (!windowId || !serverWindowIds.has(windowId)) continue;
+			if (paneInstanceId !== instanceId) continue;
+			const panePid = Number(panePidRaw);
+			panesToClose.push({
+				paneId,
+				panePid: Number.isFinite(panePid) && panePid > 0 ? panePid : undefined,
+				windowId,
+			});
 		}
+	}
 
-		// Wait a bit then SIGKILL any survivors
-		await new Promise((resolve) => setTimeout(resolve, PROCESS_TERM_WAIT_MS));
-
-		for (const pid of matchingPids) {
-			if (!isProcessAlive(pid)) continue;
-			try {
-				process.kill(pid, 'SIGKILL');
-				log(`Sent SIGKILL to PID ${pid}`);
-			} catch {
-				// Ignore errors on SIGKILL
-			}
+	for (const pane of panesToClose) {
+		if (pane.panePid) {
+			await killProcessByPid(pane.panePid);
 		}
+	}
 
-		log(`Cleanup complete: killed ${killed} processes`);
-		return killed;
-	} catch (error) {
-		log(`Fallback cleanup failed: ${error}`);
-		return 0;
+	let windowClosed = false;
+	for (const windowId of windowsToClose) {
+		await runTmuxCommand(['kill-window', '-t', windowId]);
+		windowClosed = true;
 	}
+
+	let panesClosed = 0;
+	for (const pane of panesToClose) {
+		if (windowsToClose.has(pane.windowId)) continue;
+		await runTmuxCommand(['kill-pane', '-t', pane.paneId]);
+		panesClosed += 1;
+	}
+
+	return { panesClosed, windowClosed };
 }
 
 /**
- * Synchronous version of killOrphanedAttachProcesses for shutdown handlers.
- * Uses spawnSync to ensure completion before process exit.
- *
- * @param serverUrl - The server URL to match (optional, kills all if not provided)
- * @param logger - Optional logging function for debug output
- * @returns Number of processes killed
+ * Synchronous cleanup for owned tmux windows/panes.
  */
-export function killOrphanedAttachProcessesSync(
-	serverUrl?: string,
-	logger?: (msg: string) => void
-): number {
-	const log = logger ?? (() => {});
-
-	try {
-		// Find matching processes
-		const psResult = spawnSync(['ps', 'aux'], { timeout: 2000 });
-		if (psResult.exitCode !== 0) {
-			log('Failed to list processes');
-			return 0;
-		}
-
-		const psOutput = psResult.stdout?.toString() ?? '';
-		const lines = psOutput.split('\n');
-
-		const matchingPids: number[] = [];
-		for (const line of lines) {
-			if (!line.includes('opencode attach')) continue;
-			if (serverUrl && !line.includes(serverUrl)) continue;
-			// Don't kill ourselves
-			if (line.includes(String(process.pid))) continue;
-
-			const parts = line.trim().split(/\s+/);
-			const pid = Number(parts[1]);
-			if (Number.isFinite(pid) && pid > 0) {
-				matchingPids.push(pid);
+export function cleanupOwnedResourcesSync(
+	serverKey: string,
+	instanceId: string
+): { panesClosed: number; windowClosed: boolean } {
+	if (!instanceId) return { panesClosed: 0, windowClosed: false };
+
+	const windowsResult = runTmuxCommandSync([
+		'list-windows',
+		'-a',
+		'-F',
+		`#{window_id}\t#{window_name}\t#{${OPENCODE_TAG}}\t#{${OPENCODE_SERVER_TAG}}\t#{${OPENCODE_INSTANCE_TAG}}`,
+	]);
+	const windowsToClose = new Set<string>();
+	const serverWindowIds = new Set<string>();
+
+	if (windowsResult.success && windowsResult.output) {
+		for (const line of windowsResult.output.split('\n')) {
+			const [windowId, windowName, isOpencode, windowServerKey, windowInstanceId] =
+				line.split('\t');
+			if (!windowId) continue;
+			if (windowServerKey === serverKey) {
+				serverWindowIds.add(windowId);
 			}
+			if (windowName !== 'Agents') continue;
+			if (isOpencode !== '1') continue;
+			if (windowServerKey !== serverKey) continue;
+			if (windowInstanceId !== instanceId) continue;
+			windowsToClose.add(windowId);
 		}
+	}
 
-		if (matchingPids.length === 0) {
-			log('No orphaned opencode attach processes found');
-			return 0;
-		}
-
-		log(`Found ${matchingPids.length} orphaned processes: ${matchingPids.join(', ')}`);
-
-		// Kill each process
-		let killed = 0;
-		for (const pid of matchingPids) {
-			try {
-				process.kill(pid, 'SIGTERM');
-				log(`Sent SIGTERM to PID ${pid}`);
-				killed++;
-			} catch (error) {
-				const code = (error as NodeJS.ErrnoException).code;
-				if (code !== 'ESRCH') {
-					log(`Failed to kill PID ${pid}: ${code}`);
-				}
-			}
+	const panesResult = runTmuxCommandSync([
+		'list-panes',
+		'-a',
+		'-F',
+		`#{pane_id}\t#{pane_pid}\t#{window_id}\t#{${OPENCODE_INSTANCE_TAG}}`,
+	]);
+	const panesToClose: Array<{ paneId: string; panePid?: number; windowId: string }> = [];
+
+	if (panesResult.success && panesResult.output) {
+		for (const line of panesResult.output.split('\n')) {
+			const [paneId, panePidRaw, windowId, paneInstanceId] = line.split('\t');
+			if (!paneId) continue;
+			if (!windowId || !serverWindowIds.has(windowId)) continue;
+			if (paneInstanceId !== instanceId) continue;
+			const panePid = Number(panePidRaw);
+			panesToClose.push({
+				paneId,
+				panePid: Number.isFinite(panePid) && panePid > 0 ? panePid : undefined,
+				windowId,
+			});
 		}
+	}
 
-		// Brief wait using SharedArrayBuffer (sync sleep)
-		try {
-			const buffer = new SharedArrayBuffer(4);
-			const view = new Int32Array(buffer);
-			Atomics.wait(view, 0, 0, PROCESS_TERM_WAIT_MS);
-		} catch {
-			// Ignore sleep errors
+	for (const pane of panesToClose) {
+		if (pane.panePid) {
+			killProcessByPidSync(pane.panePid);
 		}
+	}
 
-		// SIGKILL survivors
-		for (const pid of matchingPids) {
-			if (!isProcessAlive(pid)) continue;
-			try {
-				process.kill(pid, 'SIGKILL');
-				log(`Sent SIGKILL to PID ${pid}`);
-			} catch {
-				// Ignore errors
-			}
-		}
+	let windowClosed = false;
+	for (const windowId of windowsToClose) {
+		runTmuxCommandSync(['kill-window', '-t', windowId]);
+		windowClosed = true;
+	}
 
-		log(`Cleanup complete: killed ${killed} processes`);
-		return killed;
-	} catch (error) {
-		log(`Fallback cleanup failed: ${error}`);
-		return 0;
+	let panesClosed = 0;
+	for (const pane of panesToClose) {
+		if (windowsToClose.has(pane.windowId)) continue;
+		runTmuxCommandSync(['kill-pane', '-t', pane.paneId]);
+		panesClosed += 1;
 	}
+
+	return { panesClosed, windowClosed };
 }