fix(azure.ai.agents): doctor next-step accuracy + comment correctness (review fix-ups)

Three fix-ups from the 3-reviewer consensus pass on commit 48de7e8
(range 4617dd9..48de7e8). All three reached 3/3 CONFIRM during
cross-pollination.

G1 (medium): `azd ai agent doctor` trailing block was ambiguous in
mixed deployed/undeployed projects.

resolveDoctorTrailing filtered state.Services to deployed-only BEFORE
calling ResolveAfterDeploy. The resolver then computed
`singleAgent := len(state.Services) == 1` against the filtered slice.
In a project with 2 agent services where only 1 is deployed, the
filtered slice has length 1 → singleAgent=true → resolver emits no-arg
`azd ai agent show` and `azd ai agent invoke '<payload>'`. But at
runtime, both `show` and `invoke` call resolveAgentService against the
full azure.yaml (helpers.go:577-596), which still sees both services
and either prompts interactively (TTY) or errors with
"multiple azure.ai.agent services found" (--no-prompt). The doctor's
copy-pasteable suggestion is therefore ambiguous — a foot-gun for the
user.

Fix: add a variadic AfterDeployOpts{ForceQualified bool} parameter to
ResolveAfterDeploy. Doctor passes ForceQualified=true whenever the
pre-filter azure.yaml has multiple agent services (totalServices > 1),
regardless of how many are deployed. The resolver then emits
service-qualified `show <name>` / `invoke <name> ...` commands
unconditionally in that scenario. The existing post-deploy callsite
(service_target_agent.go) and all 8 existing resolver tests continue
to work with the unchanged 3-arg form because the new parameter is
variadic.

S1 (medium): Misleading comment at doctor.go:106-107 falsely claimed
that `os.Exit(code)` runs the deferred logCleanup + azdClient.Close
("Defers above run via the explicit Close + flushed stdout writer").
Per Go semantics, os.Exit terminates immediately and deferred
functions do not run. The practical impact today is zero (the OS
reclaims the gRPC socket and log fd; neither defer has on-disk state
to flush), but a future contributor reading this comment would be
silently misled when adding cleanup-critical defers (e.g., flushing
telemetry, releasing a lock, closing a temp file).

Fix: rewrite the comment to acknowledge defers don't run, document
why it's safe today, and warn against adding cleanup-critical defers
without an explicit pre-os.Exit call.

G2 (low): doctorCachedPayload looked up the cached OpenAPI spec
keyed by serviceName (azure.yaml service name). But remote invoke
rewrites `name` to info.AgentName (the deployed Foundry name from
AGENT_<KEY>_NAME) BEFORE caching (invoke.go:694-758). When deploy
appends a suffix (the divergence documented at show.go:40-46), the
two strings differ and the cache lookup misses, causing the doctor's
trailing block to fall back to the protocol-generic literal payload.

Fix: doctorCachedPayload now first tries the deployed agent name
resolved from AGENT_<SERVICE>_NAME, then falls back to the service
name when the env var is absent or matches the service name (no
divergence). Mirrors the pattern already used by show.go and avoids a
silent cache miss in the suffix-appending case.

Rejected: G3 (GPT-5.5: extend README casing check to include
{readme.md, README.MD}). Sonnet and Opus both rejected during cross-
pollination with the same rationale: the resolver hardcodes "README.md"
in the rendered hint (`see <relPath>/README.md`), so emitting the hint
when only a non-canonical casing exists on disk would create a broken
pointer on case-sensitive filesystems. Suppressing the hint is the
correct defensive behavior.

Tests:
- nextstep/resolver_test.go: 6 new subtests covering ForceQualified
  behavior (len==1+force, len==1+no-force, multi-agent force=no-op,
  cached payload composition, variadic-opts behavior).
- Existing 8 ResolveAfterDeploy subtests unchanged — backward compat
  verified.

Pre-flight:
- gofmt -s: clean
- go vet ./...: clean
- go build ./...: clean
- go test ./internal/cmd/...: pass (cmd 16.4s, doctor 6.7s, nextstep 6.2s)
- golangci-lint run ./...: 0 issues
- cspell: 0 issues

Smoke (single-service `hello-world-python-invocations`):
- `azd ai agent doctor`: 6 PASS, exit 0
- `azd ai agent doctor --output json`: valid envelope, schemaVersion 1.0

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Antriksh Jain

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor.go

@@ -103,8 +103,15 @@ Exit codes:
 			// and any non-nil return to exit 1, which collapses our
 			// three-state contract into a two-state one. We call
 			// os.Exit directly to preserve the 0/1/2 distinction.
-			// Defers above run via the explicit Close + flushed
-			// stdout writer; nothing else needs cleanup before exit.
+			//
+			// os.Exit does NOT run deferred functions. The deferred
+			// logCleanup and azdClient.Close above will not execute on
+			// the non-zero path. This is acceptable today because the
+			// process exits immediately and the OS reclaims the gRPC
+			// socket and (in --debug mode) the log fd; neither defer
+			// has on-disk state to flush. Do NOT add cleanup-critical
+			// defers to this RunE — call them explicitly before
+			// os.Exit instead.
 			code := doctor.ExitCode(report)
 			if code == 0 {
 				return nil
@@ -211,11 +218,25 @@ func resolveDoctorTrailing(ctx context.Context, azdClient *azdext.AzdClient) []n
 	}
 
 	if anyServiceDeployed(state.Services) {
+		// Capture the total agent-service count BEFORE filtering. The
+		// resolver's `len(state.Services) == 1` heuristic ordinarily
+		// keys "should I emit no-arg show/invoke commands?" off the
+		// total count of agent services in azure.yaml. Once we filter
+		// to deployed-only, that heuristic breaks: a 2-service project
+		// with 1 deployed would emit `azd ai agent show` (no name),
+		// but runtime `resolveAgentService` still sees both services
+		// in azure.yaml and would either prompt or error. Forcing
+		// qualified suggestions whenever azure.yaml has multiple
+		// services preserves copy-paste correctness in the partial-
+		// deploy case and is a no-op when all services are deployed
+		// (the resolver naturally qualifies len > 1 anyway).
+		totalServices := len(state.Services)
 		filtered := filterDeployedServices(state)
 		return nextstep.ResolveAfterDeploy(
 			filtered,
 			doctorCachedPayload(ctx, azdClient),
 			doctorReadmeExists(ctx, azdClient),
+			nextstep.AfterDeployOpts{ForceQualified: totalServices > 1},
 		)
 	}
 
@@ -260,7 +281,28 @@ func filterDeployedServices(state *nextstep.State) *nextstep.State {
 // for the deployed agent (`azd ai agent invoke <agent>`); the local
 // cache (suffix "local") is from `azd ai agent invoke --local` and is
 // not appropriate here.
+//
+// Key resolution: the on-disk cache is keyed by the deployed Foundry
+// agent name (see invoke.go:694-758 — invoke rewrites `name` to
+// `info.AgentName` BEFORE caching). That can differ from the azure.yaml
+// service name when deploy appends a suffix (documented in
+// show.go:40-46). The closure first tries the deployed name via the
+// `AGENT_<SERVICE>_NAME` env var, then falls back to the service name
+// when the env value is absent (e.g., never-deployed service, or older
+// deploys that did not populate the var). The fallback also covers the
+// non-divergent case where the two names are identical.
 func doctorCachedPayload(ctx context.Context, azdClient *azdext.AzdClient) func(string) string {
+	// Resolve the active env name once for the closure's lifetime.
+	// A nil/error response leaves envName empty, which short-circuits
+	// the deployed-name lookup path inside the closure.
+	var envName string
+	if azdClient != nil {
+		if envResp, err := azdClient.Environment().GetCurrent(ctx, &azdext.EmptyRequest{}); err == nil &&
+			envResp != nil && envResp.Environment != nil {
+			envName = envResp.Environment.Name
+		}
+	}
+
 	return func(serviceName string) string {
 		if azdClient == nil || serviceName == "" {
 			return ""
@@ -269,7 +311,27 @@ func doctorCachedPayload(ctx context.Context, azdClient *azdext.AzdClient) func(
 		if err != nil {
 			return ""
 		}
-		spec, err := nextstep.ReadCachedOpenAPISpec(filepath.Dir(configPath), serviceName, "remote")
+		configDir := filepath.Dir(configPath)
+
+		// Try the deployed agent name first.
+		if envName != "" {
+			nameKey := fmt.Sprintf("AGENT_%s_NAME", toServiceKey(serviceName))
+			if v, err := azdClient.Environment().GetValue(ctx, &azdext.GetEnvRequest{
+				EnvName: envName,
+				Key:     nameKey,
+			}); err == nil && v != nil && v.Value != "" && v.Value != serviceName {
+				if spec, err := nextstep.ReadCachedOpenAPISpec(configDir, v.Value, "remote"); err == nil {
+					if payload := nextstep.ExtractInvokeExample(spec); payload != "" {
+						return payload
+					}
+				}
+			}
+		}
+
+		// Fall back to service-name keyed cache for the non-divergent
+		// case (and for projects whose AGENT_<SERVICE>_NAME var is
+		// absent for any reason).
+		spec, err := nextstep.ReadCachedOpenAPISpec(configDir, serviceName, "remote")
 		if err != nil {
 			return ""
 		}

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver.go

@@ -288,6 +288,22 @@ func ResolveAfterShow(state *State, serviceName string) []Suggestion {
 	}}
 }
 
+// AfterDeployOpts configures ResolveAfterDeploy. Optional — the
+// zero-value matches the historical post-deploy call site behavior.
+type AfterDeployOpts struct {
+	// ForceQualified, when true, makes ResolveAfterDeploy emit
+	// service-qualified `azd ai agent show <name>` / `invoke <name> ...`
+	// commands even when len(state.Services) == 1.
+	//
+	// Use this when the input State has been filtered down from a
+	// larger multi-agent project (e.g., doctor showing only deployed
+	// services). The default `len(state.Services) == 1` heuristic
+	// would otherwise emit no-arg commands that ambiguity-prompt or
+	// error at runtime because resolveAgentService sees ALL azure.yaml
+	// services, not just the filtered subset.
+	ForceQualified bool
+}
+
 // ResolveAfterDeploy produces the Next: block embedded in the post-deploy
 // artifact note. The block is rendered per agent service: one
 // `azd ai agent show <name>` plus one `azd ai agent invoke '<payload>'`
@@ -301,17 +317,26 @@ func ResolveAfterShow(state *State, serviceName string) []Suggestion {
 // readmeExists, also injected, controls whether the "See <relPath>/README.md
 // for a sample payload" line is appended. The resolver does not touch the
 // filesystem directly.
+//
+// opts is variadic for backward compatibility. Only the first element is
+// consulted; additional elements are ignored.
 func ResolveAfterDeploy(
 	state *State,
 	cachedPayload func(serviceName string) string,
 	readmeExists func(relativePath string) bool,
+	opts ...AfterDeployOpts,
 ) []Suggestion {
 	if state == nil || len(state.Services) == 0 {
 		return nil
 	}
 
+	var forceQualified bool
+	if len(opts) > 0 {
+		forceQualified = opts[0].ForceQualified
+	}
+
 	out := make([]Suggestion, 0, len(state.Services)*3)
-	singleAgent := len(state.Services) == 1
+	singleAgent := !forceQualified && len(state.Services) == 1
 	priority := 10
 
 	for _, svc := range state.Services {

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver_test.go

@@ -479,6 +479,66 @@ func TestResolveAfterDeploy(t *testing.T) {
 		require.Len(t, out, 2)
 		assert.Equal(t, `azd ai agent invoke '{"q":"don'\''t"}'`, out[1].Command)
 	})
+
+	t.Run("ForceQualified=true on len==1 → service-qualified commands", func(t *testing.T) {
+		t.Parallel()
+		state := &State{Services: []ServiceState{
+			{Name: "echo", RelativePath: "./src/echo", Protocol: ProtocolInvocations},
+		}}
+		out := ResolveAfterDeploy(state, nil, nil, AfterDeployOpts{ForceQualified: true})
+		require.Len(t, out, 2)
+		assert.Equal(t, "azd ai agent show echo", out[0].Command)
+		assert.Equal(t, `azd ai agent invoke echo '{"message": "Hello!"}'`, out[1].Command)
+	})
+
+	t.Run("ForceQualified=false on len==1 → unqualified (matches default)", func(t *testing.T) {
+		t.Parallel()
+		state := &State{Services: []ServiceState{
+			{Name: "echo", RelativePath: "./src/echo", Protocol: ProtocolInvocations},
+		}}
+		out := ResolveAfterDeploy(state, nil, nil, AfterDeployOpts{ForceQualified: false})
+		require.Len(t, out, 2)
+		assert.Equal(t, "azd ai agent show", out[0].Command)
+		assert.Equal(t, `azd ai agent invoke '{"message": "Hello!"}'`, out[1].Command)
+	})
+
+	t.Run("ForceQualified=true with cached payload → qualified invoke uses payload", func(t *testing.T) {
+		t.Parallel()
+		state := &State{Services: []ServiceState{{Name: "echo", RelativePath: "./src/echo"}}}
+		cached := func(_ string) string { return `{"q":"x"}` }
+		out := ResolveAfterDeploy(state, cached, nil, AfterDeployOpts{ForceQualified: true})
+		require.Len(t, out, 2)
+		assert.Equal(t, "azd ai agent show echo", out[0].Command)
+		assert.Equal(t, `azd ai agent invoke echo '{"q":"x"}'`, out[1].Command)
+	})
+
+	t.Run("ForceQualified=true on multi-agent → qualified (already-qualified case unaffected)", func(t *testing.T) {
+		t.Parallel()
+		state := &State{Services: []ServiceState{
+			{Name: "alpha", Protocol: ProtocolInvocations},
+			{Name: "beta", Protocol: ProtocolResponses},
+		}}
+		out := ResolveAfterDeploy(state, nil, nil, AfterDeployOpts{ForceQualified: true})
+		require.Len(t, out, 4)
+		assert.Equal(t, "azd ai agent show alpha", out[0].Command)
+		assert.Equal(t, `azd ai agent invoke alpha '{"message": "Hello!"}'`, out[1].Command)
+		assert.Equal(t, "azd ai agent show beta", out[2].Command)
+		assert.Equal(t, `azd ai agent invoke beta "Hello!"`, out[3].Command)
+	})
+
+	t.Run("extra opts elements beyond [0] are ignored", func(t *testing.T) {
+		t.Parallel()
+		state := &State{Services: []ServiceState{
+			{Name: "echo", RelativePath: "./src/echo", Protocol: ProtocolInvocations},
+		}}
+		out := ResolveAfterDeploy(
+			state, nil, nil,
+			AfterDeployOpts{ForceQualified: true},
+			AfterDeployOpts{ForceQualified: false}, // should be ignored
+		)
+		require.Len(t, out, 2)
+		assert.Equal(t, "azd ai agent show echo", out[0].Command)
+	})
 }
 
 func TestFindService(t *testing.T) {