feat(config): support PORT env override

src/config/loader.test.ts

@@ -102,6 +102,68 @@ telegram:
 
     rmSync(testDir, { recursive: true });
   });
+
+  it('overrides server.port from PORT env var when set', () => {
+    mkdirSync(testDir, { recursive: true });
+    const configPath = join(testDir, 'config.yaml');
+
+    const prevPort = process.env.PORT;
+    process.env.PORT = '3777';
+
+    writeFileSync(configPath, `
+telegram:
+  bot_token: "test-token"
+  allowed_chat_ids: [123]
+server:
+  port: 18800
+models:
+  default:
+    provider: anthropic
+    model: claude-sonnet
+`);
+
+    const config = loadConfig(configPath);
+    expect(config.server.port).toBe(3777);
+
+    if (prevPort !== undefined) {
+      process.env.PORT = prevPort;
+    } else {
+      delete process.env.PORT;
+    }
+
+    rmSync(testDir, { recursive: true });
+  });
+
+  it('ignores invalid PORT env var values', () => {
+    mkdirSync(testDir, { recursive: true });
+    const configPath = join(testDir, 'config.yaml');
+
+    const prevPort = process.env.PORT;
+    process.env.PORT = 'not-a-number';
+
+    writeFileSync(configPath, `
+telegram:
+  bot_token: "test-token"
+  allowed_chat_ids: [123]
+server:
+  port: 18800
+models:
+  default:
+    provider: anthropic
+    model: claude-sonnet
+`);
+
+    const config = loadConfig(configPath);
+    expect(config.server.port).toBe(18800);
+
+    if (prevPort !== undefined) {
+      process.env.PORT = prevPort;
+    } else {
+      delete process.env.PORT;
+    }
+
+    rmSync(testDir, { recursive: true });
+  });
 });
 
 describe('loadConfig with overlay', () => {

src/config/loader.ts

@@ -81,5 +81,18 @@ export function loadConfig(configPath: string, overlayPath?: string): Config {
   }
 
   const expandedConfig = expandEnvVarsInObject(rawConfig);
-  return configSchema.parse(expandedConfig);
+  const config = configSchema.parse(expandedConfig);
+
+  // PaaS convention: if PORT is set, bind the gateway to it.
+  // This is intentionally an override (even if config.server.port is set)
+  // to make deployments on Fly/Railway/Render/Heroku-style platforms work.
+  const envPort = process.env.PORT;
+  if (envPort && /^\d+$/.test(envPort)) {
+    const port = Number(envPort);
+    if (Number.isFinite(port) && port > 0 && port <= 65535) {
+      config.server.port = port;
+    }
+  }
+
+  return config;
 }