Story 32: Multi-Instance Worktree Support

Add configurable port via STORYKIT_PORT env var (default 3001). Server
prints machine-readable STORYKIT_PORT=<port> on startup and writes
.story_kit_port file for discovery. Frontend proxy and WebSocket read
VITE_STORYKIT_PORT env var instead of hardcoding port 3001.

7 new tests (4 backend, 3 frontend) all passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

frontend/src/api/client.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { api } from "./client";
+import { api, resolveWsHost } from "./client";
 
 const mockFetch = vi.fn();
 
@@ -135,4 +135,22 @@ describe("api client", () => {
 			expect(result.exit_code).toBe(0);
 		});
 	});
+
+	describe("resolveWsHost", () => {
+		it("uses env port in dev mode", () => {
+			expect(resolveWsHost(true, "4200", "example.com")).toBe("127.0.0.1:4200");
+		});
+
+		it("defaults to 3001 in dev mode when no env port", () => {
+			expect(resolveWsHost(true, undefined, "example.com")).toBe(
+				"127.0.0.1:3001",
+			);
+		});
+
+		it("uses location host in production", () => {
+			expect(resolveWsHost(false, "4200", "myapp.com:8080")).toBe(
+				"myapp.com:8080",
+			);
+		});
+	});
 });

frontend/src/api/client.ts

@@ -57,6 +57,14 @@ export interface CommandOutput {
 const DEFAULT_API_BASE = "/api";
 const DEFAULT_WS_PATH = "/ws";
 
+export function resolveWsHost(
+	isDev: boolean,
+	envPort: string | undefined,
+	locationHost: string,
+): string {
+	return isDev ? `127.0.0.1:${envPort || "3001"}` : locationHost;
+}
+
 function buildApiUrl(path: string, baseUrl = DEFAULT_API_BASE): string {
 	return `${baseUrl}${path}`;
 }
@@ -225,9 +233,11 @@ export class ChatWebSocket {
 		ChatWebSocket.refCount += 1;
 
 		const protocol = window.location.protocol === "https:" ? "wss" : "ws";
-		const wsHost = import.meta.env.DEV
-			? "127.0.0.1:3001"
-			: window.location.host;
+		const wsHost = resolveWsHost(
+			import.meta.env.DEV,
+			import.meta.env.VITE_STORYKIT_PORT,
+			window.location.host,
+		);
 		const wsUrl = `${protocol}://${wsHost}${wsPath}`;
 
 		if (

frontend/vite.config.ts

@@ -2,19 +2,22 @@ import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 
 // https://vite.dev/config/
-export default defineConfig(() => ({
-  plugins: [react()],
-  server: {
-    port: 5173,
-    proxy: {
-      "/api": {
-        target: "http://127.0.0.1:3001",
-        timeout: 120000,
+export default defineConfig(() => {
+  const backendPort = process.env.VITE_STORYKIT_PORT || "3001";
+  return {
+    plugins: [react()],
+    server: {
+      port: 5173,
+      proxy: {
+        "/api": {
+          target: `http://127.0.0.1:${backendPort}`,
+          timeout: 120000,
+        },
       },
     },
-  },
-  build: {
-    outDir: "dist",
-    emptyOutDir: true,
-  },
-}));
+    build: {
+      outDir: "dist",
+      emptyOutDir: true,
+    },
+  };
+});