fix(setup): align PORT default on 3090 across .env.example, wizard, and JSDoc (#1152) (#1271)

The server's getPort() fallback changed from 3000 to 3090 in the Hono
migration (#318), but .env.example, the setup wizard's generated .env,
and the JSDoc describing the fallback were not updated — leaving three
different sources of truth for "the default PORT."

When the wizard writes PORT=3000 to ~/.archon/.env (which the Hono
server loads with override: true, while Vite only reads repo-local
.env), the two processes can land on different ports silently. That
mismatch is the real mechanism behind the failure described in #1152.

- .env.example: comment out PORT, document 3090 as the default
- packages/cli/src/commands/setup.ts: wizard no longer writes PORT=3000
  into the generated .env; fix the "Additional Options" note
- packages/cli/src/commands/setup.test.ts: assert no bare PORT= line and
  the commented default is present
- packages/core/src/utils/port-allocation.ts: fix stale JSDoc "default
  3000" -> "default 3090"
- deploy/.env.example: keep Docker default at 3000 (compose/Caddy target
  that) but annotate it so users don't copy it for local dev

Single source of truth for the local-dev default is now basePort in
port-allocation.ts.

.env.example

@@ -152,7 +152,7 @@ GITEA_ALLOWED_USERS=
 # GITEA_BOT_MENTION=archon
 
 # Server
-PORT=3000
+# PORT=3090  # Default: 3090. Uncomment to override — must match between server and Vite proxy.
 # HOST=0.0.0.0  # Bind address (default: 0.0.0.0). Set to 127.0.0.1 to restrict to localhost only.
 
 # Cloud Deployment (for --profile cloud with Caddy reverse proxy)

deploy/.env.example

@@ -46,7 +46,7 @@ TELEGRAM_BOT_TOKEN=123456789:ABC...
 # ============================================
 # Optional
 # ============================================
-PORT=3000
+PORT=3000  # Docker deployment default (the included compose/Caddy configs target :3000). For local dev (no Docker), omit PORT — server and Vite proxy both default to 3090.
 # TELEGRAM_STREAMING_MODE=stream
 # DISCORD_STREAMING_MODE=batch
 

packages/cli/src/commands/setup.test.ts

@@ -150,7 +150,9 @@ CODEX_ACCOUNT_ID=account1
       expect(content).toContain('# Using SQLite (default)');
       expect(content).toContain('CLAUDE_USE_GLOBAL_AUTH=true');
       expect(content).toContain('DEFAULT_AI_ASSISTANT=claude');
-      expect(content).toContain('PORT=3000');
+      // PORT is intentionally commented out — server and Vite both default to 3090 when unset (#1152).
+      expect(content).toContain('# PORT=3090');
+      expect(content).not.toMatch(/^PORT=/m);
       expect(content).not.toContain('DATABASE_URL=');
     });
 

packages/cli/src/commands/setup.ts

@@ -1290,8 +1290,12 @@ export function generateEnvContent(config: SetupConfig): string {
   }
 
   // Server
+  // PORT is intentionally omitted: both the Hono server (packages/core/src/utils/port-allocation.ts)
+  // and the Vite dev proxy (packages/web/vite.config.ts) default to 3090 when unset, which keeps
+  // them in sync. Writing a fixed PORT here risked a mismatch if ~/.archon/.env leaks a PORT that
+  // the Vite proxy (which only reads repo-local .env) never sees — see #1152.
   lines.push('# Server');
-  lines.push('PORT=3000');
+  lines.push('# PORT=3090  # Default: 3090. Uncomment to override.');
   lines.push('');
 
   // Concurrency
@@ -1769,7 +1773,7 @@ export async function setupCommand(options: SetupOptions): Promise<void> {
   // Additional options note
   note(
     'Other settings you can customize in ~/.archon/.env:\n' +
-      '  - PORT (default: 3000)\n' +
+      '  - PORT (default: 3090)\n' +
       '  - MAX_CONCURRENT_CONVERSATIONS (default: 10)\n' +
       '  - *_STREAMING_MODE (stream | batch per platform)\n\n' +
       'These defaults work well for most users.',

packages/core/src/utils/port-allocation.ts

@@ -30,7 +30,7 @@ export function calculatePortOffset(path: string): number {
  * Get the port for the Hono server
  * - If PORT env var is set: use it (explicit override, validated)
  * - If running in worktree: auto-allocate deterministic port based on path hash
- * - Otherwise: use default 3000
+ * - Otherwise: use default 3090 (matches the Vite proxy fallback in packages/web/vite.config.ts)
  *
  * Note: Exits process with code 1 if PORT env var is set but invalid (not 1-65535)
  */