fix(portless): force HTTPS proxy startup

docs/agent-playbooks/known-surprises.md

@@ -28,6 +28,16 @@ If uncertain, ask the developer before adding an entry.
 
 ## Entries
 
+### Portless 0.11 reuses legacy proxy state unless the launcher forces HTTPS
+
+- **Date:** 2026-04-28
+- **Observed by:** Tommaso + Codex
+- **Context:** Upgrading the normal `yarn start` flow from the old `http://5chan.localhost:1355` proxy URL to `https://5chan.localhost`.
+- **What was surprising:** Even with `portless@0.11.1` installed, Portless reused the existing `~/.portless/proxy.port = 1355` HTTP proxy and printed the legacy `:1355` URL.
+- **Impact:** Updating package versions and docs is not enough; `yarn start` can still advertise and use the old URL when a contributor has legacy Portless state running.
+- **Mitigation:** Keep `scripts/start-dev.js` explicitly starting the Portless HTTPS proxy on port `443` before registering the app route, so the runtime flow migrates away from persisted `1355` state instead of inheriting it.
+- **Status:** confirmed
+
 ### Android release signing still uses legacy keystore names
 
 - **Date:** 2026-04-23

scripts/start-dev.js

@@ -14,6 +14,13 @@ const viteBin = join(binDir, `vite${executableSuffix}`);
 const fallbackHost = '127.0.0.1';
 const fallbackUrlHost = 'localhost';
 const fallbackRequestedPort = Number(process.env.PORT) || 3000;
+const portlessProxyPort = process.env.PORTLESS_PORT || '443';
+const portlessEnv = {
+  ...process.env,
+  PORTLESS_PORT: portlessProxyPort,
+  PORTLESS_HTTPS: process.env.PORTLESS_HTTPS ?? '1',
+  PORTLESS_LAN: process.env.PORTLESS_LAN ?? '0',
+};
 
 function sanitizeLabel(value) {
   return value
@@ -92,11 +99,24 @@ function getPortlessAppName() {
   return `${preferredAppName}-${Date.now()}`;
 }
 
+function ensurePortlessProxy() {
+  const result = spawnSync(portlessBin, ['proxy', 'start', '--port', portlessProxyPort, '--https'], {
+    cwd: process.cwd(),
+    env: portlessEnv,
+    stdio: 'inherit',
+  });
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
 const command = usePortless && existsSync(portlessBin) ? portlessBin : viteBin;
 let args;
 let publicUrl = null;
 
 if (command === portlessBin) {
+  ensurePortlessProxy();
   const appName = getPortlessAppName();
 
   publicUrl = `https://${appName}.localhost`;
@@ -124,7 +144,7 @@ if (command === portlessBin) {
 
 const child = spawn(command, args, {
   stdio: 'inherit',
-  env: process.env,
+  env: command === portlessBin ? portlessEnv : process.env,
 });
 
 if (publicUrl && process.env.BROWSER !== 'none') {