WithTerminal: per-replica terminal hosts all group under a single parent in the dashboard

[mitchdenny]

Summary

When WithTerminal() is applied to a resource with multiple replicas, the per-replica TerminalHostResource instances ({parent}-terminalhost-0, {parent}-terminalhost-1, …) all appear nested under the single parent resource entry in the dashboard rather than being distributed one-per-replica-instance.

Surfaced during review of #17866 by @mitchdenny:

"in the case of replicas, the terminal hosts for all replicas ends up under one resource. Quick fix or systemic issue in Aspire that we should file an issue for?"

Why it happens

TerminalHostResource is correctly modeled per replica — MaterializeTerminalHosts creates replicaCount distinct resources with unique names and the proper ParentReplicaIndex. However the parent linkage uses IResourceWithParent<IResource> returning the singular parent IResource:

// src/Aspire.Hosting/ApplicationModel/TerminalHostResource.cs
public sealed class TerminalHostResource : ExecutableResource, IResourceWithParent<IResource>

The dashboard groups children by parent resource name (CustomResourceSnapshot.cs:484):

relationships.Add(new(resourceWithParent.Parent.Name, KnownRelationshipTypes.Parent));

The relationship references the model-level parent IResource, not a specific runtime replica instance. So all N TerminalHostResources end up listed as children of the same parent entry.

Why this is systemic, not a quick fix

Aspire has no first-class concept of "child of a specific replica instance":

• Replicas are DCP runtime instances, not modeled IResources.
• ResourceRelationshipAnnotation / IResourceWithParent<T> both take an IResource, which means "the model resource", not "this specific replica named myapp-abc12".
• The dashboard's parent grouping (CustomResourceSnapshot.GetResourceSnapshot → relationship resolution by name) has no notion of replica suffix matching.

Doing this properly likely requires either:

1. A ResourceReplicaRelationshipAnnotation (or extension to ResourceRelationshipAnnotation) that carries a replica-instance discriminator (parentReplicaIndex or DCP replica name suffix), plus dashboard support for matching child-relationship targets against replica instances rather than just resource names; or
2. Modeling DCP replicas as first-class IResources in the app model, which is a larger design effort.

Repro

var backend = builder.AddProject<Projects.Api>("api")
    .WithReplicas(3)
    .WithTerminal(options => options.ShowTerminalHost = true);

Expected: each of api-0, api-1, api-2 shows its own nested api-terminalhost-N child.
Actual: api-terminalhost-0/1/2 all appear nested under the singular api group in the dashboard.

Workaround

None on the Aspire side currently. Users diagnosing a single replica's terminal-host can rely on aspire terminal ps + aspire terminal attach from the CLI, which is replica-aware via --replica-index.

Out of scope for #17866

This is not blocking the initial WithTerminal() ship — single-replica resources (the dominant case) behave correctly. Filing for follow-up after the broader replica-aware-child-resource design is in place.

[joperezr]

🤖 Aspire triage pass — 2026-06-04 01:32 UTC

Area: area-dashboard, area-app-model, area-terminal
Kind: bug
Repro: yes-minimal — see "Repro" section in the issue body
Affected version(s): pre-release (follow-up to #17866, WithTerminal() not yet shipped)
Severity: S3 — edge scenario (WithTerminal() + replicas); single-replica resources (the common case) behave correctly. Workaround documented: aspire terminal ps / aspire terminal attach with --replica-index from the CLI.

Urgency: ⚪ backlog — no milestone
Reason: Author explicitly parks this as a follow-up requiring a broader design (first-class per-replica child-resource relationships, either a new ResourceReplicaRelationshipAnnotation or modeling DCP replicas as IResources). Not a regression — feature has not shipped.

Suggested owner(s): @JamesNK (score ~38), backup @adamint (score ~8)
Evidence:

• JamesNK authored the bulk of recent area-dashboard PRs: Fix telemetry streaming to wait for resource to appear #17821, Add timestamp search qualifier for telemetry filtering #17816, Improve dashboard summary log formatting #17595, Improve text searching with structured filtering #17482, Update blazor.web.js to latest version in 11p4 #17445, Add install CLI link to AI Agents dialog descriptions #17331, Fix stack overflow when opening child dialog from notification center #17261, Fix Manage button overlapping Close button in Settings dialog at high zoom #17258, Always log dashboard startup summary across auth modes #17206, Keep canceled resource commands in dashboard notification center #17204, Calculate VerticalThreshold dynamically based on menu/popover content #17196, Improve version log messages in CLI, AppHost and dashboard #17163, Fix flaky test: Subscription_MultipleUpdates_MinExecuteIntervalApplied #16975, Fix traces != (not equals) filter returning empty results #16932, Enable static web assets in all environments for dashboard #16931 (last 30d alone)
• JamesNK authored recent area-app-model PRs: Fix DistributedApplicationTestingBuilder dashboard with dynamic ports #17729, Use KnownConfigNames for resource service endpoint URL with legacy fallback #17385, Use OrdinalIgnoreCase for EnvironmentVariableName comparer #17194, CLI: Print app host CLI log path when connected to a running app host #17168, Improve version log messages in CLI, AppHost and dashboard #17163, Use ASPIRE_APPHOST_LOGLEVEL instead of cascading Logging__LogLevel__Default #17071, Use arguments for built-in resource commands #17021, Handle non-interactive interaction service availability for resource commands #16973 (last 30d)
• CODEOWNERS lists @JamesNK @adamint for /src/Aspire.Dashboard and @JamesNK @karolz-ms @danegsta @mitchdenny @davidfowl for /src/Aspire.Hosting
• Issue author @mitchdenny excluded per workflow rules

Confidence: high
Needs human?: no

Dry-run mode — no labels or milestone applied. Reply /triage apply to promote, or edit and reapply.