kandev/docs/plans/go-dev-launcher/task-04-dev-command.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
04-dev-command	dev command, web port, and dev env wiring	done	2	01-dev-paths	plan.md	../../specs/platform/requirements/go-dev-launcher.md

Task 04: dev command, web port, and dev env wiring

Teach the launcher's arg parser, port picker, and env builder about dev mode.

Acceptance

• parseArgs accepts dev and --dev (→ CommandDev), --web-internal-port <n> and --web-internal-port=<n>, and rejects --web-port with the existing message "--web-port has been removed; use --web-internal-port for dev mode" and --web-internal-port outside dev mode with "only applies to dev mode". Port values keep the 1–65535 validation and the existing ParseError exit code 2.
• pickDevPorts resolves the web port from the flag then KANDEV_WEB_PORT, defaults to 37429, and guarantees backend, web, and agentctl ports are mutually distinct. An explicitly requested but occupied web port is a hard error naming the port and whether it came from the flag or the env var, matching the backend-port preflight from PR #2394.
• backendEnv sets KANDEV_WEB_INTERNAL_URL=http://localhost:<webPort> when a web port is present and KANDEV_DEBUG_DEV_MODE=true in dev mode, and leaves start/run output byte-identical to today when it is not.
• cli.Help() documents dev and --web-internal-port.

Verification

Use TDD across the existing suites, then:

cd apps/backend && go test ./internal/launcher/ -race

Files

• apps/backend/internal/launcher/options.go, options_test.go
• apps/backend/internal/launcher/ports.go, ports_test.go
• apps/backend/internal/launcher/env.go, env_test.go
• apps/backend/internal/launcher/cli/help.go
• apps/backend/internal/launcher/launcher.go — dispatch CommandDev to runDev (a stub returning "not implemented" is acceptable here; task 05 fills it in).

Inputs

• apps/cli/src/args.ts:22-138 — the exact flag surface and error strings to preserve.
• apps/cli/src/cli.ts:13-58 — the help text wording for dev and --web-internal-port.
• apps/backend/internal/launcher/ports.go:65-91 — pickPorts and the used map; extend rather than fork it.
• apps/backend/internal/launcher/supervisor.go:169-190 — allowedSupervisorEnv already allowlists KANDEV_WEB_INTERNAL_URL and KANDEV_DEBUG_DEV_MODE; confirm, do not duplicate.

Risks

• portConfig.WebPort must be optional. start and run have no web port and backendEnv must not emit an empty KANDEV_WEB_INTERNAL_URL for them — the TypeScript version explicitly deletes the key in that case (apps/cli/src/shared.ts:85-87).
• Watch the Go complexity limits in apps/backend/.golangci.yml; parseArgAt is already a dispatch chain, so add a parseWebPortArg helper rather than growing it.