fix(azure.ai.agents): scope deploy-hook Next: block to deployed service + canonical README

Two consensus findings from the 3-reviewer pass on commits 3.1+3.2:

(1) multi-service state leak — GPT-5.5 (originator), confirmed by Sonnet 4.6
    and Opus 4.7. In a multi-agent project, deploying one service caused
    ResolveAfterDeploy to emit show/invoke rows for EVERY service in the
    project, all attached to the deployed service's artifact note. Fix:
    filter state.Services to serviceConfig.Name at the deploy-hook call site
    via a new filterServicesByName helper. ResolveAfterDeploy itself is left
    untouched — show/doctor callers still get the project-wide view.

(2) README casing mismatch — Sonnet 4.6 (originator), confirmed by GPT-5.5
    and Opus 4.7. readmeExists accepted README.md / readme.md / README.MD,
    but ResolveAfterDeploy always emits the literal "see <path>/README.md"
    pointer. On case-sensitive filesystems (Linux, WSL) with only a
    lowercase readme.md on disk, the collision rule would fire on the
    canonical-casing suggestion, REPLACE the aka.ms fallback, and leave the
    user with a pointer that does not resolve. Fix: tighten readmeExists to
    only check the canonical "README.md" — same casing the resolver emits.

Regression tests:
- TestAugmentDeployNote_LowercaseReadme_DoesNotReplaceFallback (skipped on
  case-insensitive filesystems via a runtime probe; runs on Linux CI)
- TestAugmentDeployNote_MultiServiceState_ScopedToDeployedService
- TestFilterServicesByName

Pre-flight green: gofmt, vet, build, full extension test suite, golangci-lint
0 issues. Live smoke against the hello-world-python-invocations sample shows
unchanged output (single-service project with canonical README — neither
fix's scenario applies; the existing happy path is preserved).

Refs PR Azure#8057 critique items C2 and 3-reviewer consensus on phase-3 wiring.

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

Author: Antriksh Jain

cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent.go

@@ -976,6 +976,12 @@ func (p *AgentServiceTargetProvider) finalizeDeploy(
 	// aka.ms link emitted by deployArtifacts is preserved when the
 	// enrichment is skipped or short-circuits.
 	if state, _ := nextstep.AssembleState(ctx, p.azdClient); state != nil {
+		// Scope to the service just deployed. ResolveAfterDeploy renders a
+		// show/invoke pair per state.Services entry; without this filter a
+		// multi-agent project would attach guidance for other services to
+		// this artifact's note.
+		state.Services = filterServicesByName(state.Services, serviceConfig.Name)
+
 		projectRoot := ""
 		if proj, err := p.azdClient.Project().Get(ctx, nil); err == nil && proj.Project != nil {
 			projectRoot = proj.Project.Path
@@ -1589,12 +1595,13 @@ func augmentDeployNote(state *nextstep.State, artifacts []*azdext.Artifact, proj
 		if projectRoot == "" || relativePath == "" {
 			return false
 		}
-		for _, name := range []string{"README.md", "readme.md", "README.MD"} {
-			if _, err := os.Stat(filepath.Join(projectRoot, relativePath, name)); err == nil {
-				return true
-			}
-		}
-		return false
+		// Only consider the canonical casing — ResolveAfterDeploy emits
+		// "see <relPath>/README.md" verbatim. Accepting other casings here
+		// would yield a broken pointer on case-sensitive filesystems and,
+		// because suggestionsIncludeReadme triggers the replace branch,
+		// would silently discard the working aka.ms fallback.
+		_, err := os.Stat(filepath.Join(projectRoot, relativePath, "README.md"))
+		return err == nil
 	}
 
 	suggestions := nextstep.ResolveAfterDeploy(state, cachedPayload, readmeExists)
@@ -1650,6 +1657,22 @@ func suggestionsIncludeReadme(suggestions []nextstep.Suggestion) bool {
 	return false
 }
 
+// filterServicesByName narrows the assembled state's service slice to a
+// single entry by name. Used by the deploy hook so the rendered "Next:"
+// block reflects only the service whose artifact note is being augmented,
+// not every agent service in the project.
+func filterServicesByName(services []nextstep.ServiceState, name string) []nextstep.ServiceState {
+	if name == "" {
+		return services
+	}
+	for i := range services {
+		if services[i].Name == name {
+			return services[i : i+1]
+		}
+	}
+	return nil
+}
+
 // protocolEndpointInfo holds a displayable protocol label and its invocation URL.
 type protocolEndpointInfo struct {
 	Protocol string

cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent_test.go

@@ -1277,3 +1277,106 @@ func TestAugmentDeployNote_NoServicesIsNoOp(t *testing.T) {
 	augmentDeployNote(&nextstep.State{}, []*azdext.Artifact{artifact}, "/tmp", "")
 	require.Equal(t, "static aka.ms link", artifact.Metadata["note"])
 }
+
+// TestAugmentDeployNote_LowercaseReadme_DoesNotReplaceFallback locks the
+// casing-mismatch guard: when only a lowercase readme.md exists on a
+// case-sensitive filesystem, the resolver would still emit a literal
+// "README.md" pointer that does not resolve on disk  and the aka.ms
+// fallback would be lost. The fix tightens readmeExists to the canonical
+// casing so the append branch fires and the static link is preserved.
+func TestAugmentDeployNote_LowercaseReadme_DoesNotReplaceFallback(t *testing.T) {
+	t.Parallel()
+
+	tmp := t.TempDir()
+	// Detect case-sensitivity at runtime; the fix is meaningful only on
+	// case-sensitive filesystems (Linux, WSL). On Windows NTFS and default
+	// macOS APFS the OS resolves "README.md" → "readme.md" transparently,
+	// which would make readmeExists return true even after the fix.
+	probe := filepath.Join(tmp, "case-probe.txt")
+	require.NoError(t, os.WriteFile(probe, nil, 0o600))
+	if _, err := os.Stat(filepath.Join(tmp, "CASE-PROBE.TXT")); err == nil {
+		t.Skip("case-insensitive filesystem — readmeExists casing guard is a no-op here")
+	}
+
+	servicePath := filepath.Join(tmp, "src", "echo")
+	require.NoError(t, os.MkdirAll(servicePath, 0o750))
+	// Only lowercase readme.md exists; canonical README.md does not.
+	require.NoError(t, os.WriteFile(filepath.Join(servicePath, "readme.md"), []byte("sample"), 0o600))
+
+	state := &nextstep.State{
+		Services: []nextstep.ServiceState{
+			{
+				Name:         "echo",
+				RelativePath: "src/echo",
+				Protocol:     "invocations",
+				IsDeployed:   true,
+			},
+		},
+	}
+
+	artifact := &azdext.Artifact{
+		Kind: azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{
+			"label": "Agent endpoint (invocations)",
+			"note":  "static aka.ms link",
+		},
+	}
+
+	augmentDeployNote(state, []*azdext.Artifact{artifact}, tmp, "")
+
+	got := artifact.Metadata["note"]
+	require.Contains(t, got, "static aka.ms link",
+		"aka.ms fallback must survive when only lowercase readme.md exists on disk")
+	require.NotContains(t, got, "see src/echo/README.md",
+		"resolver must not emit a README pointer that does not match what is on disk")
+}
+
+// TestAugmentDeployNote_MultiServiceState_ScopedToDeployedService locks
+// the deploy-hook contract that the rendered Next: block reflects only
+// the service whose artifact note is being augmented. The hook applies
+// filterServicesByName to the assembled state before invoking the
+// resolver.
+func TestAugmentDeployNote_MultiServiceState_ScopedToDeployedService(t *testing.T) {
+	t.Parallel()
+
+	state := &nextstep.State{
+		Services: []nextstep.ServiceState{
+			{Name: "alpha", RelativePath: "src/alpha", Protocol: "invocations", IsDeployed: true},
+			{Name: "beta", RelativePath: "src/beta", Protocol: "invocations", IsDeployed: true},
+		},
+	}
+	state.Services = filterServicesByName(state.Services, "alpha")
+
+	artifact := &azdext.Artifact{
+		Kind: azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{
+			"label": "Agent endpoint (invocations)",
+			"note":  "static aka.ms link",
+		},
+	}
+
+	augmentDeployNote(state, []*azdext.Artifact{artifact}, "/tmp", "")
+
+	got := artifact.Metadata["note"]
+	require.NotContains(t, got, "beta",
+		"other-service guidance must not leak into the deployed service's note")
+	require.Contains(t, got, "Next:", "Next: block should be present for the deployed service")
+}
+
+// TestFilterServicesByName covers the helper used at the deploy-hook call site.
+func TestFilterServicesByName(t *testing.T) {
+	t.Parallel()
+
+	services := []nextstep.ServiceState{
+		{Name: "alpha"},
+		{Name: "beta"},
+		{Name: "gamma"},
+	}
+
+	require.Equal(t, []nextstep.ServiceState{{Name: "beta"}}, filterServicesByName(services, "beta"),
+		"match returns single-element slice")
+	require.Nil(t, filterServicesByName(services, "missing"),
+		"no match returns nil  caller short-circuits on empty Services")
+	require.Equal(t, services, filterServicesByName(services, ""),
+		"empty name returns input unchanged (defensive)")
+}