agentcore dev -p <port> is silently offset by runtime index when running multiple runtimes in parallel

[masaha03]

Description

When running multiple agentcore dev instances in parallel, getAgentPort() in
src/cli/operations/dev/config.ts silently offsets the port passed via
-p by the runtime's index in agentcore.json (basePort + runtimeIndex). The shift is not logged and the flag's help text ("Port for development server") gives no hint that -p is a base port.

Why this is a problem

The actual bound port depends on which other runtimes are configured in agentcore.json and which ones happen to be running, not just on the -p value.
This breaks local development and integration testing in practical ways:

• Downstream services (backend servers, integration tests, scripts) that target http://localhost:<-p value>/invocations silently talk to the wrong port —
  or get connection errors — depending on which runtimes are up.
• Which runtime owns which port changes if someone reorders, adds, or removes entries in agentcore.json. A config-only change silently breaks every
  developer's local setup.
• To hit a specific port, a user has to compute -p = desiredPort - runtimeIndex and keep that in sync with agentcore.json. The -p value in
  package.json / README / CI scripts no longer means what it says.
• A second free-port search (findFreePort in src/cli/operations/dev/utils.ts) can shift the port again if basePort + index is occupied, and only
  that shift is announced. The first, index-based shift is invisible.

Suggested Fixes (any one resolves the surprise)

1. Treat -p as the literal port; fail fast on conflict.
2. Add a per-runtime devPort field in agentcore.json so the mapping is explicit and stable across reorderings.
3. Log the offset whenever getAgentPort shifts the port, mirroring the existing Port ${ee} in use, using ${re} message.
4. At minimum, document the current behavior in --help and the README.

Steps to Reproduce

1. agentcore.json with two runtimes:

   { "runtimes": [{ "name": "AgentA", ... }, { "name": "AgentB", ... }] }

2. Run both in parallel with the ports you actually want:

   agentcore dev -r AgentA -p 8787 &
   agentcore dev -r AgentB -p 8788 &

3. lsof -iTCP -sTCP:LISTEN -n -P — AgentB is on 8789, not 8788.

Expected Behavior

AgentB binds to 8788 (the value passed via -p).

Actual Behavior

AgentB binds to 8789 (8788 + index(AgentB) = 8788 + 1). No log line explains why.

CLI Version

@aws/agentcore@0.12.0; logic still on main / v0.13.0.

Operating System

macOS

Additional Context

No response

[avi-alpert]

Thank you for the report, validated. Will update here with fix