Skip to content

Sign and bundle hex1bpty.exe for AppHost-owned terminals - #19984

Open
Krishnendu Samanta (krishnendu-2003) wants to merge 4 commits into
microsoft:mainfrom
krishnendu-2003:hex1bpty-sign-and-bundle
Open

Krishnendu Samanta (krishnendu-2003) wants to merge 4 commits into
microsoft:mainfrom
krishnendu-2003:hex1bpty-sign-and-bundle

Conversation

@krishnendu-2003

@krishnendu-2003 Krishnendu Samanta (krishnendu-2003) commented Sep 8, 2026 •

Copy link
Copy Markdown

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:

  1. It isn't published. RemoveUnusedHex1bPtyHostFromPublish (added in Exclude unused hex1bpty.exe from published CLI archives #19554) strips hex1bpty from publish output everywhere under src/. 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.
  2. It isn't signed. eng/Signing.props has no entry for it, so even if it were published it would ship unsigned inside a Microsoft-signed install.
  3. It isn't in the bundle. CreateLayout.CopyManaged() copies aspire-managed and wwwroot and deliberately skips every other .exe, so it would never reach managed/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-managed publishes as a single file with IncludeNativeLibrariesForSelfExtract=true. hex1bpty.exe is a native asset, so the SDK's default is to pack it inside aspire-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.targets

Aspire.Managed sets PublishHex1bPtyHost=true for Windows RIDs, turning off the #19554 removal for exactly this project and nothing else. A companion target marks the file ExcludeFromSingleFile, so it stays a loose file next to aspire-managed instead of disappearing into the single-file bundle.

Sign it — eng/Signing.props

A FileSignInfo entry at 3PartySHA2 (a third-party binary from the Hex1b package, so the same certificate as Hex1b.dll, not the Microsoft400 cert used for our own executables), plus an ItemsToSign entry pointing at its publish path that mirrors the existing aspire-managed one. It is signed in the pass the pipeline already runs before CreateLayout packs the bundle.

Stage it — tools/CreateLayout/Program.cs

CopyManaged() copies the signed helper to managed/hex1bpty.exe. The blanket "skip other .exe files" 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, CreateLayout throws 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, because TerminalService / Hex1bTerminalProcessOptions have 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. KeepHex1bPtyHostOutOfSingleFileBundle is ordered with BeforeTargets="_ComputeFilesToBundle". If the SDK renames that, the ordering insurance is lost — though CreateLayout then 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.gz embedded as a resource inside aspire.exe, so hex1bpty.exe is 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 PublishHex1bPtyHost property in Aspire.Managed.csproj restores the previous behaviour on its own: the removal target takes over again, the helper stops being published, and the ExcludeFromSingleFile companion target no-ops because its condition is false. The ItemsToSign glob then matches nothing and the FileSignInfo entry becomes inert. The only piece that must be reverted alongside it is the CreateLayout copy, 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: _ComputeFilesToBundle honours ExcludeFromSingleFile on ResolvedFileToPublish, and native assets are bundled when IncludeNativeLibrariesForSelfExtract is set. Markdownlint was run locally against the docs/specs/bundle.md change and passes.

The signing half cannot be exercised by PR checks at all — eng/pipelines/templates/build_sign_native.yml runs 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:

dotnet publish src/Aspire.Managed/Aspire.Managed.csproj -c Release -r win-x64 --self-contained
ls artifacts/bin/Aspire.Managed/Release/net10.0/win-x64/publish/hex1bpty.exe

If that file exists, the target fired before the single-file bundler and everything downstream follows.

Contributes to #19976

Checklist

  • Is this feature complete?
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No — what remains is build, signing, and layout configuration, which has no test project in the repo to hang off. The behavioural guard is CreateLayout failing 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.
  • Did you add public API?
    • Yes
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes — it adds a binary to the Authenticode signing set. hex1bpty.exe comes from the Hex1b package, so it signs as third-party (3PartySHA2), matching how Hex1b.dll is already handled. It is signed at its publish path before CreateLayout copies it, so the bundle carries the signed copy.
      • If yes, have you done a threat model and had a security review?
        • Yes
        • No — worth review from whoever owns the signing configuration, since it is a new entry in it.
    • No

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
Copilot AI balanced review requested due to automatic review settings September 8, 2026 16:47
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 19984

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 19984"

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread src/Shared/BundleDiscovery.cs Outdated
Comment on lines +209 to +212
public static bool TryDiscoverWindowsPtyHostFromDirectory(
string baseDirectory,
out string? ptyHostPath)
{

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-link BundleDiscovery, 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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread eng/Signing.props
Comment on lines +34 to +36
<!-- 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" />

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 70f7e81 — and thanks for the pointer, I'd assumed no precedent existed for this and was
wrong. NpmCliPackageTests.AspireCliUsesMicrosoftCertificate parses eng/Signing.props exactly
this way, so there was an idiomatic place to put it.

Added tests/Infrastructure.Tests/Pipelines/Hex1bPtyHostSigningTests.cs with the two assertions you
asked for:

  • PtyHostSignsWithThirdPartyCertificate — exactly one FileSignInfo for hex1bpty.exe, mapped to
    3PartySHA2 with no collision scope. This is the one that matters most: it fails if the helper
    ever gets signed as Microsoft400, which would sign a third-party binary as Microsoft's.
  • PtyHostIsStagedForSigningFromTheManagedPublishOutput — exactly one ItemsToSign covering the
    file, sourced from Aspire.Managed's publish output, gated on IsWindows().

This lands in PR CI on the right trigger: eng/github-ci/test-trigger-map.yml:381 already routes
eng/Signing.props to test:Infrastructure.Tests, so a deleted or altered rule fails the PR that
broke it rather than surfacing at release signing.

Comment thread src/Directory.Build.targets Outdated
Comment on lines +41 to +43
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.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-29 calls DCP "the upstream PTY
owner" and TerminalResourceBuilderExtensions.cs:35-37 says 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 path wording — 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 in Aspire.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 inside aspire.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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 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.props is routed only to Infrastructure.Tests, and NpmCliPackageTests.AspireCliUsesMicrosoftCertificate already asserts the neighboring signing entries but does not verify either the new 3PartySHA2 mapping or this ItemsToSign glob. 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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The Authenticode flow and private SDK target ordering require successful internal pipeline validation.

Review details
  • Files reviewed: 6/6 changed files
  • Comments generated: 0 new
  • Review effort level: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants