Repository navigation
Sign and bundle hex1bpty.exe for AppHost-owned terminals - #19984
Krishnendu Samanta (krishnendu-2003) wants to merge 4 commits into
Conversation
AppHost-owned terminals need Hex1b's Windows PTY host, hex1bpty.exe, but nothing in the build produced a signed copy of it or put it anywhere the AppHost could find it. Three gaps, closed here: - Aspire.Managed now sets PublishHex1bPtyHost=true for Windows RIDs, so hex1bpty.exe survives the publish filter added in microsoft#19554. A companion target marks it ExcludeFromSingleFile, otherwise IncludeNativeLibrariesForSelfExtract packs it inside aspire-managed.exe and there is nothing on disk left to sign or copy. - eng/Signing.props signs it as a third-party binary (3PartySHA2, same as Hex1b.dll) at its publish path, in the same pass that signs aspire-managed. - CreateLayout stages the signed copy at managed/hex1bpty.exe and fails with a clear message if a Windows bundle is missing it. BundleDiscovery gains the matching lookup so a separately launched C# AppHost resolves the same path from the layout root the CLI hands it. Wiring that into Hex1b's WindowsPtyHostPath option is left for when the terminal types from microsoft#19887 land. The CLI archive is unaffected: the bundle ships as a tar.gz embedded in aspire.exe, so hex1bpty.exe is not a second loose binary in the archive and the winget submission friction that motivated microsoft#19554 does not come back. Contributes to microsoft#19976 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PW1pn92QD5DQ94i8ML1XJD
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 19984Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 19984" |
There was a problem hiding this comment.
🟡 Changes recommended
The new discovery helper is not connected to any production runtime path.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds Windows PTY-host packaging support for AppHost-owned terminals.
Changes:
- Publishes, signs, and stages
hex1bpty.exe. - Adds bundle discovery helpers and tests.
- Documents the updated bundle layout.
File summaries
| File | Description |
|---|---|
tools/CreateLayout/Program.cs |
Stages the PTY host. |
tests/Aspire.Cli.Tests/Layout/Hex1bPtyHostDiscoveryTests.cs |
Tests discovery helpers. |
src/Shared/BundleDiscovery.cs |
Adds PTY-host path discovery. |
src/Directory.Build.targets |
Keeps the host outside single-file bundles. |
src/Aspire.Managed/Aspire.Managed.csproj |
Enables Windows PTY-host publishing. |
eng/Signing.props |
Adds signing configuration. |
docs/specs/bundle.md |
Documents the Windows asset. |
Review details
- Files reviewed: 7/7 changed files
- Comments generated: 1
- Review effort level: Balanced
| public static bool TryDiscoverWindowsPtyHostFromDirectory( | ||
| string baseDirectory, | ||
| out string? ptyHostPath) | ||
| { |
There was a problem hiding this comment.
Good catch — you're right, there was no caller. The types that would consume it
(TerminalService/Hex1bTerminalProcessOptions) haven't landed yet, so rather than ship an
unused API into the three assemblies that source-linkBundleDiscovery, I've removed the helper
and the test that only covered it. Bundle-relative discovery belongs with the change that actually
calls it, which #19976 already sequences after #19974/#19887. This PR is now just publish, sign,
and stage.
Review feedback on the PR: the discovery helper added to BundleDiscovery is not connected to any production runtime path. That is correct — there is no caller, because the types that would consume it (TerminalService / Hex1bTerminalProcessOptions) have not landed yet. Shipping an unused API into the three assemblies that source-link BundleDiscovery is not worth it, so remove it along with the test that covered only that helper. Bundle-relative discovery belongs with the change that actually calls it, which issue microsoft#19976 already sequences after microsoft#19974/microsoft#19887. This leaves the PR to the part that stands on its own: publish, sign, and stage hex1bpty.exe. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PW1pn92QD5DQ94i8ML1XJD
There was a problem hiding this comment.
🟡 Changes recommended
The PTY ownership rationale is contradictory, and the release-only signing behavior lacks focused PR-CI coverage.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 2
- Review effort level: Balanced
| <!-- Hex1b's Windows PTY host. Third-party native binary, so it signs like Hex1b.dll rather than | ||
| like our own executables. Only Windows RIDs carry it. --> | ||
| <FileSignInfo Include="hex1bpty.exe" CertificateName="3PartySHA2" /> |
There was a problem hiding this comment.
Fixed in 70f7e81 — and thanks for the pointer, I'd assumed no precedent existed for this and was
wrong.NpmCliPackageTests.AspireCliUsesMicrosoftCertificateparseseng/Signing.propsexactly
this way, so there was an idiomatic place to put it.Added
tests/Infrastructure.Tests/Pipelines/Hex1bPtyHostSigningTests.cswith the two assertions you
asked for:
PtyHostSignsWithThirdPartyCertificate— exactly oneFileSignInfoforhex1bpty.exe, mapped to
3PartySHA2with no collision scope. This is the one that matters most: it fails if the helper
ever gets signed asMicrosoft400, which would sign a third-party binary as Microsoft's.PtyHostIsStagedForSigningFromTheManagedPublishOutput— exactly oneItemsToSigncovering the
file, sourced fromAspire.Managed's publish output, gated onIsWindows().This lands in PR CI on the right trigger:
eng/github-ci/test-trigger-map.yml:381already routes
eng/Signing.propstotest:Infrastructure.Tests, so a deleted or altered rule fails the PR that
broke it rather than surfacing at release signing.
| The bundle is the one place that does need the PTY host. AppHost-owned terminals let the AppHost, | ||
| rather than DCP, own the pseudo-terminal, and on Windows Hex1b launches hex1bpty.exe to do that. | ||
| Aspire.Managed sets PublishHex1bPtyHost=true for that reason, which turns the removal above off. |
There was a problem hiding this comment.
You're right, and my first attempt at fixing this made it worse rather than better.
I'd rewritten the comments to say Hex1b owns the pseudo-terminal from inside the AppHost process.
That is not true of anything in this tree.TerminalReplica.cs:23-29calls DCP "the upstream PTY
owner" andTerminalResourceBuilderExtensions.cs:35-37says DCP allocates the PTY while the
terminal host only bridges it over HMP — both correct, and my comment contradicted them.To answer the direct question: there is no Hex1b path in this tree that launches
hex1bpty.exe.
Nothing does, today. The path that will is AppHost-owned terminals (#19887), where Hex1b owns the
PTY itself instead of bridging DCP's, and that hasn't landed. #19976 asks for the helper to be
built, signed and bundled ahead of it so the pipeline isn't the blocker when it does.So in 70f7e81 I restored the original
Nothing we ship takes that pathwording — it is accurate —
and the new comment now states the sequencing plainly instead of inventing a mechanism: nothing
launches it yet, DCP owns every PTY we currently surface, and the bundle stages it for #19887. Same
wording inAspire.Managed.csproj,CreateLayout, and the bundle spec.That does leave the honest trade-off on the table: until #19887 lands, this is ~5 MB in the Windows
bundle that nothing uses. It stays out of the CLI archive that winget consumes (the bundle is an
embedded tarball insideaspire.exe), so the #19554 friction doesn't return — but if you'd rather
this waited for the consuming feature, that's a reasonable call and I'm happy to hold it.
Review feedback: the rationale was contradictory. Two real problems. The comment above RemoveUnusedHex1bPtyHostFromPublish still claimed "Nothing we ship takes that path", which this change makes false -- Aspire.Managed now takes exactly that path. It reads as the exception it is, and points at the target below. The two blocks also named different owners of the pseudo-terminal: the original says Hex1b launches the helper when Hex1b owns the PTY, while the new text said the AppHost owns it. Hex1b is the owner; it runs inside the AppHost process, as opposed to DCP owning the PTY. Every comment now says that the same way -- in Directory.Build.targets, Aspire.Managed.csproj, CreateLayout, and the bundle spec. Comments only; no behaviour change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PW1pn92QD5DQ94i8ML1XJD
There was a problem hiding this comment.
🔵 Needs a closer look
The security-sensitive signing rules lack regression coverage despite existing tests for adjacent signing entries.
Review details
Suppressed comments (1)
eng/Signing.props:116
- Please add regression coverage for this signing rule.
eng/Signing.propsis routed only toInfrastructure.Tests, andNpmCliPackageTests.AspireCliUsesMicrosoftCertificatealready asserts the neighboring signing entries but does not verify either the new3PartySHA2mapping or thisItemsToSignglob. A later removal or path change could therefore leave PR CI green while official bundles contain an unsigned helper; extend that test to lock down both entries.
<!-- Hex1b's PTY host sits next to aspire-managed in the same publish output and gets signed in the
same pass, before CreateLayout copies it into the bundle as managed/hex1bpty.exe. -->
<ItemsToSign Condition="$([System.OperatingSystem]::IsWindows())" Include="$(ArtifactsBinDir)Aspire.Managed\**\publish\hex1bpty.exe" />
- Files reviewed: 5/5 changed files
- Comments generated: 0 new
- Review effort level: Balanced
Two review findings, both correct. The rationale was still wrong after the last attempt. TerminalReplica.cs calls DCP "the upstream PTY owner" and TerminalResourceBuilderExtensions says DCP allocates the PTY while the terminal host only bridges it over HMP. The comments claimed Hex1b owns the pseudo-terminal in the AppHost process, which is not true of any path in this tree -- AppHost-owned terminals have not landed yet. Nothing launches hex1bpty.exe today. So the original "Nothing we ship takes that path" is restored, because it is accurate, and the new comments say plainly what is actually going on: the helper is staged ahead of microsoft#19887, which is what microsoft#19976 asks for. The same wording now appears in Directory.Build.targets, Aspire.Managed.csproj, CreateLayout, and the bundle spec. The signing rules also had no PR-CI coverage, and there was an existing pattern for that which I had missed: NpmCliPackageTests parses eng/Signing.props and pins the CLI's certificate mappings. Hex1bPtyHostSigningTests does the same for the PTY host -- the 3PartySHA2 mapping and the Windows ItemsToSign glob -- so a deleted or altered rule fails the pull request instead of surfacing at release signing. eng/Signing.props is already routed to Infrastructure.Tests in eng/github-ci/test-trigger-map.yml. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PW1pn92QD5DQ94i8ML1XJD
The problem
AppHost-owned terminals (#19887) need Hex1b's Windows PTY host,
hex1bpty.exe. Hex1b launches it whenever the AppHost — rather than DCP — owns the pseudo-terminal, so on Windows the feature cannot work without that helper sitting somewhere the AppHost can find it.Right now it reaches the user in none of the three ways it needs to:
RemoveUnusedHex1bPtyHostFromPublish(added in Exclude unused hex1bpty.exe from published CLI archives #19554) stripshex1bptyfrom publish output everywhere undersrc/. That was correct at the time — nothing shipped took the PTY-host path, it was ~5 MB of dead weight in every Windows CLI archive, and it was a second executable that winget ran malware checks against, which became submission friction.eng/Signing.propshas no entry for it, so even if it were published it would ship unsigned inside a Microsoft-signed install.CreateLayout.CopyManaged()copiesaspire-managedandwwwrootand deliberately skips every other.exe, so it would never reachmanaged/hex1bpty.exe.Net effect: nothing in the pipeline produces a signed copy, and nothing puts it where an AppHost could locate it at runtime.
The constraint
#19554 should not be undone — its reasons still hold for the CLI archive. So the fix has to be scoped to the one artifact that actually needs the helper (the bundle) without putting a second loose binary back into the archive winget consumes.
The helper also has to come from the build rather than the NuGet cache: only a file sitting in a publish directory can be picked up by Arcade's signing pass, and only a signed copy should reach the bundle.
Finally,
aspire-managedpublishes as a single file withIncludeNativeLibrariesForSelfExtract=true.hex1bpty.exeis a native asset, so the SDK's default is to pack it insideaspire-managed.exe— leaving nothing on disk to sign and nothing to copy.The decision
Publish it —
src/Aspire.Managed/Aspire.Managed.csproj,src/Directory.Build.targetsAspire.ManagedsetsPublishHex1bPtyHost=truefor Windows RIDs, turning off the #19554 removal for exactly this project and nothing else. A companion target marks the fileExcludeFromSingleFile, so it stays a loose file next toaspire-managedinstead of disappearing into the single-file bundle.Sign it —
eng/Signing.propsA
FileSignInfoentry at3PartySHA2(a third-party binary from the Hex1b package, so the same certificate asHex1b.dll, not theMicrosoft400cert used for our own executables), plus anItemsToSignentry pointing at its publish path that mirrors the existingaspire-managedone. It is signed in the pass the pipeline already runs beforeCreateLayoutpacks the bundle.Stage it —
tools/CreateLayout/Program.csCopyManaged()copies the signed helper tomanaged/hex1bpty.exe. The blanket "skip other.exefiles" rule is about native host stubs leaking out of referenced Exe projects; this is a genuine runtime dependency, so it is handled explicitly. If a Windows bundle build cannot find it,CreateLayoutthrows and names the cause.The trade-offs
Runtime discovery is deliberately not here. An earlier revision added a bundle-relative lookup to
BundleDiscovery; review correctly pointed out it had no production caller, becauseTerminalService/Hex1bTerminalProcessOptionshave not landed. It is removed. That plumbing belongs with the change that calls it — #19976 already sequences it after #19974/#19887.The Windows bundle now hard-fails when the helper is missing, instead of quietly producing a bundle whose terminals fail to open at runtime. A broken build beats a broken ship, but it does mean a Hex1b package that ever drops the asset breaks every Windows bundle build rather than degrading.
One target depends on a private SDK target name.
KeepHex1bPtyHostOutOfSingleFileBundleis ordered withBeforeTargets="_ComputeFilesToBundle". If the SDK renames that, the ordering insurance is lost — thoughCreateLayoutthen fails loudly rather than silently shipping a missing or unsigned helper.What this does not cost: the winget friction from #19554 does not come back. The bundle ships as a
tar.gzembedded as a resource insideaspire.exe, sohex1bpty.exeis never a second loose binary in the submitted archive — it is extracted to~/.aspire/managed/at setup time.Aspire.Cli's own publish output is untouched and still strips it.Rollback
Dropping the
PublishHex1bPtyHostproperty inAspire.Managed.csprojrestores the previous behaviour on its own: the removal target takes over again, the helper stops being published, and theExcludeFromSingleFilecompanion target no-ops because its condition is false. TheItemsToSignglob then matches nothing and theFileSignInfoentry becomes inert. The only piece that must be reverted alongside it is theCreateLayoutcopy, which would otherwise throw on a Windows bundle build. Nothing here changes an existing artifact's contents or layout, so a revert leaves no migration behind.Validation status
I was unable to build this locally, so CI is its first compile. The riskiest piece is the target ordering above. The mechanism itself was checked against
Microsoft.NET.Publish.targets:_ComputeFilesToBundlehonoursExcludeFromSingleFileonResolvedFileToPublish, and native assets are bundled whenIncludeNativeLibrariesForSelfExtractis set. Markdownlint was run locally against thedocs/specs/bundle.mdchange and passes.The signing half cannot be exercised by PR checks at all —
eng/pipelines/templates/build_sign_native.ymlruns in the internal Azure DevOps pipeline — so that part needs a maintainer's eyes.A quick check that proves the riskiest part, on any machine with the .NET 10 SDK:
If that file exists, the target fired before the single-file bundler and everything downstream follows.
Contributes to #19976
Checklist
WindowsPtyHostPathwiring needs Migrate dashboard terminals from xterm.js to Hex1b web terminal #19974/Add AppHost terminals, dashboard docking, and terminal automation #19887 first.)CreateLayoutfailing loudly when a Windows bundle is missing the helper. The one test this PR did have covered only the discovery helper that review asked to remove, so it went with it.hex1bpty.execomes from the Hex1b package, so it signs as third-party (3PartySHA2), matching howHex1b.dllis already handled. It is signed at its publish path beforeCreateLayoutcopies it, so the bundle carries the signed copy.