fix(dev server): fall forward from port 1355 without portless

README.md

@@ -104,7 +104,7 @@ To have your board appear in a directory on the 5chan homepage:
 2. Install dependencies: `yarn install`
 3. Start the web client: `yarn start`
 
-The dev server runs at http://5chan.localhost:1355 via [Portless](https://port1355.dev/), which gives each Bitsocial project a stable, named URL instead of a random port. To bypass Portless and use a plain Vite dev server: `PORTLESS=0 yarn start`
+The dev server runs at http://5chan.localhost:1355 via [Portless](https://port1355.dev/), which gives each Bitsocial project a stable, named URL instead of a random port. To bypass Portless and use a plain Vite dev server, run `PORTLESS=0 yarn start`; it will start at `http://5chan.localhost:1355` and automatically fall forward to the next free port if `1355` is already in use.
 
 For device testing on a USB-connected Android phone (without relying on `5chan.localhost` DNS from the device):
 

docs/agent-playbooks/known-surprises.md

@@ -57,3 +57,13 @@ If uncertain, ask the developer before adding an entry.
 - **Impact:** The local RPC server on `ws://localhost:9138` never starts, so the desktop app cannot load boards, posts, or comments even though node stats look healthy.
 - **Mitigation:** Before any Electron package/build job, run `yarn electron:prepare-package` so `better-sqlite3` is rebuilt for Electron and immediately verified via `ELECTRON_RUN_AS_NODE=1 electron`.
 - **Status:** confirmed
+
+### Plain Vite fallback used to hard-fail on port 1355
+
+- **Date:** 2026-03-30
+- **Observed by:** Codex
+- **Context:** Running `PORTLESS=0 yarn start` while another local service already owned port `1355`
+- **What was surprising:** The non-Portless dev fallback forced Vite onto `5chan.localhost:1355` with `--strictPort`, so the fallback path could fail immediately even though the main Portless flow is collision-safe.
+- **Impact:** Contributors could lose the fallback dev path or interrupt their startup flow when `1355` was already busy.
+- **Mitigation:** Keep the fallback behind `scripts/start-dev.js`, which now probes from `1355` upward and starts Vite on the next free port instead of exiting.
+- **Status:** confirmed

scripts/start-dev.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
+import { resolvePort } from './dev-server-utils.mjs';
 
 const isWindows = process.platform === 'win32';
 const usePortless = process.env.PORTLESS !== '0' && !isWindows;
@@ -8,15 +9,30 @@ const binDir = join(process.cwd(), 'node_modules', '.bin');
 const executableSuffix = isWindows ? '.cmd' : '';
 const portlessBin = join(binDir, `portless${executableSuffix}`);
 const viteBin = join(binDir, `vite${executableSuffix}`);
+const fallbackHost = '127.0.0.1';
+const fallbackUrlHost = '5chan.localhost';
+const fallbackRequestedPort = 1355;
 
 const command = usePortless && existsSync(portlessBin) ? portlessBin : viteBin;
-const args =
+let args;
-  command === portlessBin
+
-    ? ['5chan', 'vite']
+if (command === portlessBin) {
-    : ['--host', '5chan.localhost', '--port', '1355', '--strictPort'];
+  args = ['5chan', 'vite'];
+} else {
+  const port = await resolvePort(fallbackRequestedPort);
+  const fallbackUrl = `http://${fallbackUrlHost}:${port}`;
+
+  args = ['--host', fallbackHost, '--port', String(port), '--strictPort'];
 
   if (command !== portlessBin && process.env.PORTLESS !== '0') {
-  console.warn('portless unavailable on this platform, using vite directly on http://5chan.localhost:1355');
+    console.warn(`portless unavailable on this platform, using vite directly on ${fallbackUrl}`);
+  } else {
+    console.log(`Starting Vite directly at ${fallbackUrl}`);
+  }
+
+  if (port !== fallbackRequestedPort) {
+    console.log(`Preferred port ${fallbackRequestedPort} is busy, so this run will use ${fallbackUrl}.`);
+  }
 }
 
 const child = spawn(command, args, {
@@ -32,4 +48,3 @@ child.on('exit', (code, signal) => {
 
   process.exit(code ?? 0);
 });
-