feat(cli): warn when --port is outside discovery range

.changeset/feat-cli-port-discovery-warning.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Warn when `kilo console` or `kilo daemon` is invoked with an explicit `--port` outside the discovery range (4097–4116).

packages/opencode/src/kilocode/cli/cmd/console.ts

@@ -3,6 +3,7 @@ import { cmd } from "@/cli/cmd/cmd"
 import { withNetworkOptions, resolveNetworkOptions } from "@/cli/network"
 import { AppRuntime } from "@/effect/app-runtime"
 import { Daemon } from "@/kilocode/daemon/daemon"
+import { warnPort } from "@/kilocode/cli/port-warning"
 
 function publicUrl(state: Daemon.State) {
   return new URL("/console", state.url).toString()
@@ -41,6 +42,7 @@ export const KiloConsoleCommand = cmd({
   builder: (yargs) => withNetworkOptions(yargs),
   handler: async (args) => {
     const opts = await AppRuntime.runPromise(resolveNetworkOptions(args))
+    warnPort(opts.port)
     const result = await Daemon.start(opts)
     const state = result.state
     if (!state) throw new Error("Kilo daemon did not provide connection state")

packages/opencode/src/kilocode/cli/cmd/daemon.ts

@@ -3,6 +3,7 @@ import { cmd } from "@/cli/cmd/cmd"
 import { withNetworkOptions, resolveNetworkOptions } from "@/cli/network"
 import { AppRuntime } from "@/effect/app-runtime"
 import { Daemon } from "@/kilocode/daemon/daemon"
+import { warnPort } from "@/kilocode/cli/port-warning"
 
 function withJson<T>(yargs: Argv<T>) {
   return yargs.option("json", {
@@ -60,6 +61,7 @@ const StartCommand = cmd({
   builder: (yargs) => withJson(withNetworkOptions(yargs)),
   handler: async (args) => {
     const opts = await AppRuntime.runPromise(resolveNetworkOptions(args))
+    warnPort(opts.port)
     const result = await Daemon.start(opts)
     if (args.json) {
       print(result, true)
@@ -99,6 +101,7 @@ const RestartCommand = cmd({
   builder: (yargs) => withJson(withNetworkOptions(yargs)),
   handler: async (args) => {
     const opts = await AppRuntime.runPromise(resolveNetworkOptions(args))
+    warnPort(opts.port)
     const result = await Daemon.restart(opts)
     if (args.json) {
       print(result, true)

packages/opencode/src/kilocode/cli/port-warning.ts

@@ -0,0 +1,11 @@
+import { Daemon } from "@/kilocode/daemon/daemon"
+
+export function warnPort(port: number) {
+  if (port === 0) return
+  if (port < Daemon.PortRange.start || port > Daemon.PortRange.end) {
+    console.warn(
+      `\x1B[33mPort ${port} is outside the recommended daemon discovery range (${Daemon.PortRange.start}-${Daemon.PortRange.end}). ` +
+        `The console will work, but auto-discovery may not find this server.\x1B[0m`,
+    )
+  }
+}