@myrialabs/clopen 0.2.2 → 0.2.4

package/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+logs
+.env
+.git

package/.env.example

@@ -1,6 +1,3 @@
-# Node Environment (development | production)
-NODE_ENV=production
-
 # Server configuration
 HOST=localhost
 
@@ -8,5 +5,5 @@ HOST=localhost
 PORT=9141
 
 # Development ports (two ports — Vite proxies to Elysia)
-PORT_BACKEND=9151
-PORT_FRONTEND=9141
+PORT_FRONTEND=9151
+PORT_BACKEND=9161

package/CONTRIBUTING.md

@@ -22,6 +22,10 @@ bun install
 bun run check
 ```
 
+### Data Directory
+
+When running `bun run dev`, Clopen stores data in `~/.clopen-dev` instead of `~/.clopen`. This keeps development data separate from any production instance — especially important since Clopen can be used to develop itself.
+
 ### Keep Updated
 
 ```bash

package/README.md

@@ -9,7 +9,7 @@
 
 ## Features
 
-- **Multi-Account Claude Code** - Manage multiple accounts (personal, work, team) and switch instantly per session, isolated under `~/.clopen/claude/user/` without touching system-level Claude config
+- **Multi-Account Claude Code** - Manage multiple accounts (personal, work, team) and switch instantly per session, isolated under `~/.clopen/claude/user/` (or `~/.clopen-dev/` in development) without touching system-level Claude config
 - **Multi-Engine Support** - Switch between Claude Code and OpenCode
 - **AI Chat Interface** - Streaming responses with tool use visualization
 - **Background Processing** - Chat, terminal, and other processes continue running even when you close the browser — come back later and pick up where you left off
@@ -92,6 +92,8 @@ bun run dev     # Start development server
 bun run check   # Type checking
 ```
 
+When running in development mode, Clopen uses `~/.clopen-dev` instead of `~/.clopen`, keeping dev data separate from any production instance.
+
 ---
 
 ## Architecture
@@ -123,7 +125,7 @@ Clopen uses an engine-agnostic adapter pattern — both engines normalize output
 ### Port 9141 Already in Use
 
 ```bash
-clopen --port 9150
+clopen --port 9145
 ```
 
 Or kill the existing process:

package/backend/database/queries/message-queries.ts

@@ -42,6 +42,48 @@ export const messageQueries = {
 		});
 	},
 
+	/**
+	 * Get minimal preview data for a session: first user msg, last assistant msg, and counts.
+	 * Used by the Sessions/History modal to avoid loading all messages.
+	 */
+	getSessionPreview(sessionId: string): {
+		firstUserMessage: DatabaseMessage | null;
+		lastAssistantMessage: DatabaseMessage | null;
+		userCount: number;
+		assistantCount: number;
+	} {
+		const db = getDatabase();
+
+		const firstUserMessage = db.prepare(`
+			SELECT * FROM messages
+			WHERE session_id = ? AND json_extract(sdk_message, '$.type') = 'user'
+			ORDER BY timestamp ASC
+			LIMIT 1
+		`).get(sessionId) as DatabaseMessage | null;
+
+		const lastAssistantMessage = db.prepare(`
+			SELECT * FROM messages
+			WHERE session_id = ? AND json_extract(sdk_message, '$.type') = 'assistant'
+			ORDER BY timestamp DESC
+			LIMIT 1
+		`).get(sessionId) as DatabaseMessage | null;
+
+		const counts = db.prepare(`
+			SELECT
+				SUM(CASE WHEN json_extract(sdk_message, '$.type') = 'user' THEN 1 ELSE 0 END) AS user_count,
+				SUM(CASE WHEN json_extract(sdk_message, '$.type') = 'assistant' THEN 1 ELSE 0 END) AS assistant_count
+			FROM messages
+			WHERE session_id = ?
+		`).get(sessionId) as { user_count: number; assistant_count: number } | null;
+
+		return {
+			firstUserMessage,
+			lastAssistantMessage,
+			userCount: counts?.user_count ?? 0,
+			assistantCount: counts?.assistant_count ?? 0
+		};
+	},
+
 	/**
 	 * Get all messages for a session including deleted ones (for timeline view)
 	 */

package/backend/database/utils/connection.ts

@@ -1,17 +1,17 @@
 import { join } from 'path';
-import { homedir } from 'os';
 import { Database } from 'bun:sqlite';
 import type { DatabaseConnection } from '$shared/types/database/connection';
 
 import { debug } from '$shared/utils/logger';
+import { getClopenDir } from '../../utils/index.js';
+
 export class DatabaseManager {
 	private static instance: DatabaseManager | null = null;
 	private db: DatabaseConnection | null = null;
 	private readonly dbPath: string;
 
 	private constructor() {
-		const clopenDir = join(homedir(), '.clopen');
-		this.dbPath = join(clopenDir, 'app.db');
+		this.dbPath = join(getClopenDir(), 'app.db');
 	}
 
 	static getInstance(): DatabaseManager {
@@ -29,8 +29,8 @@ export class DatabaseManager {
 		debug.log('database', '🔗 Connecting to database...');
 
 		try {
-			// Create ~/.clopen directory if it doesn't exist
-			const clopenDir = join(homedir(), '.clopen');
+			// Create clopen directory if it doesn't exist
+			const clopenDir = getClopenDir();
 			const dirFile = Bun.file(clopenDir);
 
 			// Check if directory exists, if not create it

package/backend/engine/adapters/claude/environment.ts

@@ -7,22 +7,21 @@
  * stream concurrently.
  */
 
-import { homedir } from 'os';
 import { join } from 'path';
 import { isWindows, findGitBash } from '../../../terminal/shell-utils.js';
 import { engineQueries } from '../../../database/queries';
 import { debug } from '$shared/utils/logger';
-import { getCleanSpawnEnv } from '../../../utils/env';
+import { getCleanSpawnEnv, getClopenDir } from '../../../utils/index.js';
 
 let _ready = false;
 let _initPromise: Promise<void> | null = null;
 let _envOverrides: Record<string, string> = {};
 
 /**
- * Returns the isolated Claude config directory under ~/.clopen/claude/user/
+ * Returns the isolated Claude config directory under {clopenDir}/claude/user/
  */
 export function getClaudeUserConfigDir(): string {
-  return join(homedir(), '.clopen', 'claude', 'user');
+  return join(getClopenDir(), 'claude', 'user');
 }
 
 /**

package/backend/engine/adapters/claude/stream.ts

@@ -8,6 +8,7 @@
 
 import { query, type SDKMessage, type EngineSDKMessage, type Options, type Query, type SDKUserMessage } from '$shared/types/messaging';
 import type { PermissionMode, PermissionResult } from "@anthropic-ai/claude-agent-sdk";
+import type { StructuredGenerationOptions } from '../../types';
 import { normalizePath } from './path-utils';
 import { setupEnvironmentOnce, getEngineEnv } from './environment';
 import { handleStreamError } from './error-handler';
@@ -238,4 +239,110 @@ export class ClaudeCodeEngine implements AIEngine {
     this.pendingUserAnswers.delete(toolUseId);
     return true;
   }
+
+  /**
+   * One-shot structured JSON generation.
+   * Uses query() with no tools, outputFormat, and maxTurns: 1.
+   */
+  async generateStructured<T = unknown>(options: StructuredGenerationOptions): Promise<T> {
+    const {
+      prompt,
+      model = 'haiku',
+      schema,
+      projectPath,
+      abortController,
+      claudeAccountId
+    } = options;
+
+    if (!this._isInitialized) {
+      await this.initialize();
+    }
+
+    const controller = abortController || new AbortController();
+    const normalizedPath = normalizePath(projectPath);
+
+    // Optimized for one-shot structured generation:
+    // - tools: [] prevents tool use (no agentic loops)
+    // - persistSession: false skips writing session to disk
+    // - effort: 'low' reduces processing overhead for simple tasks
+    // - thinking disabled removes reasoning overhead
+    // - minimal systemPrompt avoids loading heavy defaults
+    // - no maxTurns: structured output has its own retry limit
+    const sdkOptions: Options = {
+      permissionMode: 'bypassPermissions' as PermissionMode,
+      allowDangerouslySkipPermissions: true,
+      cwd: normalizedPath,
+      env: getEngineEnv(claudeAccountId),
+      systemPrompt: 'You are a structured data generator. Return JSON matching the provided schema.',
+      tools: [],
+      outputFormat: {
+        type: 'json_schema',
+        schema
+      },
+      persistSession: false,
+      effort: 'low',
+      thinking: { type: 'disabled' },
+      ...(model && { model }),
+      abortController: controller
+    };
+
+    // Use plain string prompt — simpler and faster than AsyncIterable
+    const queryInstance = query({
+      prompt,
+      options: sdkOptions
+    });
+
+    let structuredOutput: unknown = null;
+    let resultText = '';
+    let lastError = '';
+
+    try {
+      for await (const message of queryInstance) {
+        debug.log('engine', `[structured] message type=${message.type}, subtype=${'subtype' in message ? message.subtype : 'n/a'}`);
+
+        if (message.type === 'result') {
+          if (message.subtype === 'success') {
+            const result = message as any;
+            structuredOutput = result.structured_output;
+            resultText = result.result || '';
+            debug.log('engine', `[structured] success: structured_output=${!!structuredOutput}, resultLen=${resultText.length}`);
+          } else {
+            const errResult = message as any;
+            lastError = errResult.errors?.join('; ') || '';
+            const subtype = errResult.subtype || '';
+
+            // Map SDK error subtypes to user-friendly messages
+            if (subtype === 'error_max_structured_output_retries') {
+              lastError = 'Failed to generate valid structured output after multiple attempts';
+            } else if (subtype === 'error_max_turns') {
+              lastError = 'Generation exceeded turn limit';
+            } else if (!lastError) {
+              lastError = subtype || 'unknown error';
+            }
+
+            debug.error('engine', `[structured] result error: ${lastError}`);
+          }
+        }
+      }
+    } catch (error) {
+      handleStreamError(error);
+      // handleStreamError swallows AbortError — if we reach here without throw, it was cancelled
+      throw new Error('Generation was cancelled');
+    }
+
+    if (structuredOutput) {
+      return structuredOutput as T;
+    }
+
+    // Fallback: parse the text result as JSON
+    if (resultText) {
+      try {
+        return JSON.parse(resultText) as T;
+      } catch {
+        debug.warn('engine', `[structured] result text is not valid JSON: ${resultText.slice(0, 200)}`);
+      }
+    }
+
+    throw new Error(lastError || 'Claude Code did not return valid structured output');
+  }
 }

package/backend/engine/adapters/opencode/server.ts

@@ -11,6 +11,7 @@
 import type { OpencodeClient } from '@opencode-ai/sdk';
 import { getOpenCodeMcpConfig } from '../../../mcp';
 import { debug } from '$shared/utils/logger';
+import { findAvailablePort } from '../../../utils/port-utils';
 
 const OPENCODE_PORT = 4096;
 const OPENCODE_HOST = '127.0.0.1';
@@ -58,9 +59,14 @@ async function init(): Promise<void> {
 		}
 	}
 
+	const actualPort = await findAvailablePort(OPENCODE_PORT);
+	if (actualPort !== OPENCODE_PORT) {
+		debug.log('engine', `Open Code port ${OPENCODE_PORT} in use, using ${actualPort} instead`);
+	}
+
 	const result = await createOpencode({
 		hostname: OPENCODE_HOST,
-		port: OPENCODE_PORT,
+		port: actualPort,
 		...(Object.keys(mcpConfig).length > 0 && {
 			config: { mcp: mcpConfig },
 		}),

package/backend/engine/adapters/opencode/stream.ts

@@ -10,7 +10,7 @@
  */
 
 import type { SDKMessage, SDKUserMessage, EngineSDKMessage } from '$shared/types/messaging';
-import type { AIEngine, EngineQueryOptions } from '../../types';
+import type { AIEngine, EngineQueryOptions, StructuredGenerationOptions } from '../../types';
 import type { EngineModel } from '$shared/types/engine';
 import type {
 	Provider,
@@ -1010,4 +1010,84 @@ export class OpenCodeEngine implements AIEngine {
 
 		return [{ type: 'text', text: '' }];
 	}
+
+	/**
+	 * One-shot structured JSON generation.
+	 * Uses the v1 SDK client.session.prompt() (synchronous) with prompt
+	 * engineering for JSON output since v1 doesn't support format option.
+	 */
+	async generateStructured<T = unknown>(options: StructuredGenerationOptions): Promise<T> {
+		const {
+			prompt,
+			model = 'claude-sonnet',
+			schema,
+			projectPath,
+			abortController
+		} = options;
+
+		if (!this._isInitialized) {
+			await this.initialize();
+		}
+
+		const client = await ensureClient();
+
+		// Create a temporary session for this one-shot request
+		const sessionResult = await client.session.create({
+			query: { directory: projectPath }
+		});
+		const sessionId = sessionResult.data?.id;
+		if (!sessionId) {
+			throw new Error('Failed to create OpenCode session');
+		}
+
+		// Parse model into providerID/modelID
+		const [providerID, modelID] = model.includes('/') ? model.split('/', 2) : ['', model];
+
+		// Wrap prompt with JSON instruction since v1 doesn't support format option
+		const jsonPrompt = `${prompt}
+
+IMPORTANT: You MUST respond with ONLY a valid JSON object matching this schema, no other text:
+${JSON.stringify(schema, null, 2)}`;
+
+		debug.log('engine', `[OC structured] Sending prompt to session ${sessionId}, model=${model}`);
+
+		// Use v1 SDK synchronous prompt method — waits for completion
+		const response = await client.session.prompt({
+			path: { id: sessionId },
+			body: {
+				parts: [{ type: 'text', text: jsonPrompt }],
+				...(providerID && modelID ? { model: { providerID, modelID } } : {}),
+				tools: {}
+			},
+			query: { directory: projectPath },
+			...(abortController?.signal && { signal: abortController.signal })
+		});
+
+		const data = response.data;
+		if (!data) {
+			throw new Error('OpenCode returned empty response');
+		}
+
+		debug.log('engine', `[OC structured] Got response with ${data.parts?.length || 0} parts`);
+
+		// Extract text content from response parts and parse as JSON
+		const textParts = (data.parts || []).filter((p: any) => p.type === 'text');
+		const fullText = textParts.map((p: any) => p.text || '').join('');
+
+		if (!fullText) {
+			throw new Error('OpenCode returned no text content');
+		}
+
+		debug.log('engine', `[OC structured] Raw text: ${fullText.slice(0, 200)}`);
+
+		// Try to extract JSON from the response (may include markdown fences)
+		const jsonMatch = fullText.match(/```(?:json)?\s*([\s\S]*?)```/) || fullText.match(/(\{[\s\S]*\})/);
+		const jsonText = jsonMatch ? jsonMatch[1].trim() : fullText.trim();
+
+		try {
+			return JSON.parse(jsonText) as T;
+		} catch {
+			throw new Error(`OpenCode did not return valid JSON: ${jsonText.slice(0, 200)}`);
+		}
+	}
 }

package/backend/engine/types.ts

@@ -24,6 +24,16 @@ export interface EngineQueryOptions {
 	claudeAccountId?: number;
 }
 
+/** Options for one-shot structured generation (no tools, no streaming) */
+export interface StructuredGenerationOptions {
+	prompt: string;
+	model?: string;
+	schema: Record<string, unknown>;
+	projectPath: string;
+	abortController?: AbortController;
+	claudeAccountId?: number;
+}
+
 /** The contract every engine adapter must fulfil */
 export interface AIEngine {
 	/** Engine identifier */
@@ -61,4 +71,11 @@ export interface AIEngine {
 	 * Unblocks the canUseTool callback so the SDK can continue.
 	 */
 	resolveUserAnswer?(toolUseId: string, answers: Record<string, string>): boolean;
+
+	/**
+	 * One-shot structured JSON generation (no tools, no streaming).
+	 * Returns parsed JSON matching the provided schema.
+	 * Optional — engines that don't support it leave undefined.
+	 */
+	generateStructured?<T = unknown>(options: StructuredGenerationOptions): Promise<T>;
 }

package/backend/git/git-executor.ts

@@ -22,7 +22,8 @@ export async function execGit(
 ): Promise<GitExecResult> {
 	debug.log('git', `Executing: git ${args.join(' ')} in ${cwd}`);
 
-	const proc = Bun.spawn(['git', ...args], {
+	const safeCwd = cwd.replace(/\\/g, '/');
+	const proc = Bun.spawn(['git', '-c', `safe.directory=${safeCwd}`, ...args], {
 		cwd,
 		stdout: 'pipe',
 		stderr: 'pipe',

package/backend/git/git-service.ts

@@ -317,7 +317,8 @@ export class GitService {
 	}
 
 	async fetch(cwd: string, remote = 'origin'): Promise<string> {
-		const result = await execGit(['fetch', remote, '--prune'], cwd, 60000);
+		// Use explicit refspec to ensure all branches are fetched regardless of clone config
+		const result = await execGit(['fetch', remote, `+refs/heads/*:refs/remotes/${remote}/*`, '--prune'], cwd, 60000);
 		if (result.exitCode !== 0) {
 			throw new Error(`git fetch failed: ${result.stderr}`);
 		}

package/backend/index.ts

@@ -20,7 +20,6 @@ import { loggerMiddleware } from './middleware/logger';
 import { initializeDatabase, closeDatabase } from './database';
 import { disposeAllEngines } from './engine';
 import { debug } from '$shared/utils/logger';
-import { findAvailablePort } from './utils/port-utils';
 import { networkInterfaces } from 'os';
 import { resolve } from 'node:path';
 import { statSync } from 'node:fs';
@@ -45,7 +44,7 @@ wsRouter.setAuthMiddleware(async (conn, action) => {
 /**
  * Clopen - Elysia Backend Server
  *
- * Development: Elysia runs on port 9151, Vite dev server proxies /api and /ws from port 9141
+ * Development: Elysia runs on port 9161, Vite dev server proxies /api and /ws from port 9151
  * Production: Elysia runs on port 9141, serves static files from dist/ + API + WebSocket
  */
 
@@ -117,11 +116,12 @@ if (!isDevelopment) {
 
 // Start server with proper initialization sequence
 async function startServer() {
-	// Find available port — auto-increment if desired port is in use
-	const actualPort = await findAvailablePort(PORT);
-	if (actualPort !== PORT) {
-		debug.log('server', `⚠️ Port ${PORT} in use, using ${actualPort} instead`);
-	}
+	// Port resolution is handled by the caller:
+	// - Development: scripts/dev.ts resolves ports and passes via PORT_BACKEND env
+	// - Production:  scripts/start.ts resolves port and passes via PORT env
+	// - CLI:         bin/clopen.ts resolves port and passes via PORT env
+	// This avoids double port-check race conditions (e.g. zombie processes on
+	// Windows causing silent desync between Vite proxy and backend).
 
 	// Initialize database first before accepting connections
 	try {
@@ -133,18 +133,18 @@ async function startServer() {
 
 	// Start listening after database is ready
 	app.listen({
-		port: actualPort,
+		port: PORT,
 		hostname: HOST
 	}, () => {
 		if (isDevelopment) {
 			console.log('🚀 Backend ready — waiting for frontend...');
 		} else {
-			console.log(`🚀 Clopen running at http://localhost:${actualPort}`);
+			console.log(`🚀 Clopen running at http://localhost:${PORT}`);
 		}
 		if (HOST === '0.0.0.0') {
 			const ips = getLocalIps();
 			for (const ip of ips) {
-				console.log(`🌐 Network access: http://${ip}:${actualPort}`);
+				console.log(`🌐 Network access: http://${ip}:${PORT}`);
 			}
 		}
 	});

package/backend/snapshot/blob-store.ts

@@ -11,12 +11,12 @@
  */
 
 import { join } from 'path';
-import { homedir } from 'os';
 import fs from 'fs/promises';
 import { gzipSync, gunzipSync } from 'zlib';
 import { debug } from '$shared/utils/logger';
+import { getClopenDir } from '../utils/index.js';
 
-const SNAPSHOTS_DIR = join(homedir(), '.clopen', 'snapshots');
+const SNAPSHOTS_DIR = join(getClopenDir(), 'snapshots');
 const BLOBS_DIR = join(SNAPSHOTS_DIR, 'blobs');
 const TREES_DIR = join(SNAPSHOTS_DIR, 'trees');
 

package/backend/utils/env.ts

@@ -22,12 +22,12 @@ const isDev = process.env.NODE_ENV !== 'production';
 
 export const SERVER_ENV = {
 	NODE_ENV: (process.env.NODE_ENV || 'development') as string,
-	/** Backend port — dev: PORT_BACKEND (default 9151), prod: PORT (default 9141) */
+	/** Backend port — dev: PORT_BACKEND (default 9161), prod: PORT (default 9141) */
 	PORT: isDev
-		? (process.env.PORT_BACKEND ? parseInt(process.env.PORT_BACKEND) : 9151)
+		? (process.env.PORT_BACKEND ? parseInt(process.env.PORT_BACKEND) : 9161)
 		: (process.env.PORT ? parseInt(process.env.PORT) : 9141),
 	/** Frontend port — only used in dev for Vite proxy coordination */
-	PORT_FRONTEND: process.env.PORT_FRONTEND ? parseInt(process.env.PORT_FRONTEND) : 9141,
+	PORT_FRONTEND: process.env.PORT_FRONTEND ? parseInt(process.env.PORT_FRONTEND) : 9151,
 	HOST: (process.env.HOST || 'localhost') as string,
 	isDevelopment: isDev,
 } as const;
@@ -35,15 +35,13 @@ export const SERVER_ENV = {
 // ── .env parsing ────────────────────────────────────────────────────
 
 /**
- * Parse .env file into key-value map.
- * Knowing both key AND value lets us compare against process.env
- * to determine if Bun's auto-load is still in effect or if the
- * system/runtime changed the value after loading.
+ * Parse a .env file at the given path into a key-value record.
+ * Returns an empty object if the file doesn't exist or can't be read.
  */
-function parseDotEnv(): Map<string, string> {
-	const entries = new Map<string, string>();
+export function loadEnvFile(envPath: string): Record<string, string> {
+	const result: Record<string, string> = {};
 	try {
-		const content = readFileSync(join(process.cwd(), '.env'), 'utf-8');
+		const content = readFileSync(envPath, 'utf-8');
 		for (const line of content.split('\n')) {
 			let trimmed = line.trim();
 			if (!trimmed || trimmed.startsWith('#')) continue;
@@ -51,22 +49,22 @@ function parseDotEnv(): Map<string, string> {
 			const eqIdx = trimmed.indexOf('=');
 			if (eqIdx <= 0) continue;
 			const key = trimmed.substring(0, eqIdx).trim();
-			// Strip surrounding quotes from value
 			let value = trimmed.substring(eqIdx + 1).trim();
 			if ((value.startsWith('"') && value.endsWith('"')) ||
 				(value.startsWith("'") && value.endsWith("'"))) {
 				value = value.slice(1, -1);
 			}
-			entries.set(key, value);
+			result[key] = value;
 		}
 	} catch {
 		// .env doesn't exist or can't be read
 	}
-	return entries;
+	return result;
 }
 
-// Capture once at import time
-const dotEnv = parseDotEnv();
+// Capture once at import time — read from CWD which is set to the clopen
+// installation directory when spawned via bin/clopen.ts (cwd: __dirname).
+const dotEnv = new Map(Object.entries(loadEnvFile(join(process.cwd(), '.env'))));
 
 // ── Filter definitions ──────────────────────────────────────────────
 

package/backend/utils/index.ts

@@ -2,4 +2,7 @@
 export * from './process-manager.js';
 
 // Export environment sanitizer
-export * from './env.js';
+export * from './env.js';
+
+// Export path utilities
+export * from './paths.js';

package/backend/utils/paths.ts

@@ -0,0 +1,11 @@
+import { join } from 'path';
+import { homedir } from 'os';
+
+/**
+ * Returns the Clopen data directory.
+ * - development: ~/.clopen-dev
+ * - everything else (production, undefined): ~/.clopen
+ */
+export function getClopenDir(): string {
+	return join(homedir(), process.env.NODE_ENV === 'development' ? '.clopen-dev' : '.clopen');
+}

package/backend/utils/port-utils.ts

@@ -1,14 +1,18 @@
 /**
  * Port utilities for checking ports before server start.
  * Bun-optimized: uses Bun.connect for fast cross-platform port check.
+ *
+ * Checks BOTH IPv4 (127.0.0.1) and IPv6 (::1) — on Windows, 'localhost'
+ * may resolve to either address. A zombie process listening on [::1] would
+ * go undetected by an IPv4-only check, causing the new server to bind to a
+ * port that can't actually serve traffic (connections hang indefinitely).
  */
 
-/** Check if a port is currently in use */
-export async function isPortInUse(port: number): Promise<boolean> {
+/** Try to connect to a specific host:port */
+async function tryConnect(hostname: string, port: number): Promise<boolean> {
 	try {
-		// Bun-native TCP connect — fast cross-platform check
 		const socket = await Bun.connect({
-			hostname: '127.0.0.1',
+			hostname,
 			port,
 			socket: {
 				data() {},
@@ -18,12 +22,21 @@ export async function isPortInUse(port: number): Promise<boolean> {
 			}
 		});
 		socket.end();
-		return true; // Connection succeeded = port in use
+		return true;
 	} catch {
-		return false; // Connection refused = port is free
+		return false;
 	}
 }
 
+/** Check if a port is currently in use on any localhost address (IPv4 + IPv6) */
+export async function isPortInUse(port: number): Promise<boolean> {
+	const [v4, v6] = await Promise.all([
+		tryConnect('127.0.0.1', port),
+		tryConnect('::1', port),
+	]);
+	return v4 || v6;
+}
+
 /** Find an available port starting from the given port, incrementing on collision */
 export async function findAvailablePort(startPort: number, maxAttempts = 8): Promise<number> {
 	let port = startPort;