Re-restore integrations when another CLI replaced the assets

[Jonas Flodén (flojon)]

Fixes #19603.

Root cause

obj/aspire-restore.stamp records only the inputs of the last restore performed by PrebuiltAppHostServer, and CanSkipIntegrationRestore treats a matching fingerprint as proof that obj/project.assets.json still corresponds to those inputs. Nothing binds the stamp to the assets, so any other writer of the restore directory can replace them while the stamp keeps asserting the earlier fingerprint.

Switching CLI versions is exactly such a writer, which is why the reported failure needs two switches to show up:

1. 13.6.0-pr restores cleanly and writes stamp = A.
2. 13.5.1 restores the same synthesized project against its own package versions. It rewrites project.assets.json and bin/, and leaves the stamp alone — so the stamp still says A.
3. 13.6.0-pr regenerates a byte-identical IntegrationRestore.csproj and therefore recomputes fingerprint A. It matches the stale stamp, restore is skipped, and the build runs against 13.5.1's closure — including Aspire.Hosting.CodeGeneration.TypeScript.dll — while reporting ✅ SDK code restored successfully.

That also explains the asymmetry in the issue: going down works because the older CLI has no skip logic and always restores.

Verified against the reported repro with both CLIs installed (13.5.1 and 13.6.0-pr.19577.gfa0aea2c). After step 3 the csproj read 13.6.0-pr while project.assets.json and the generator assembly were still 13.5.1; deleting just the stamp made the same command restore correctly, confirming the stamp was the only gate.

The issue's first suggestion — folding the CLI version into the stamp — does not fix this: the synthesized csproj already encodes the CLI version, so the input fingerprint already differs per version. The problem is that the stamp outlives a foreign restore and the fingerprint returns to a previously stamped value.

Fix

The stamp now records a fingerprint of the assets file it produced alongside the input fingerprint, and a skip requires the assets on disk to still be the ones it vouches for:

<input fingerprint>
<project.assets.json fingerprint>

• A stamp carrying only the inputs (written by an earlier CLI) is treated as stale, costing one restore after an upgrade — the safe direction.
• If the assets cannot be read at write time, no stamp is written at all rather than one that vouches only for the inputs.
• Hashing is XxHash3 over the assets stream, consistent with the existing input fingerprint and negligible next to the ~5.6s restore it guards.

This also covers the general case the stamp never handled: any external dotnet restore/dotnet build against the same directory, or a partially cleaned obj/.

No warning was added for the version-skew case — with the stamp bound to its assets the state self-corrects on the next command, so there is nothing left to warn about.

Tests

Three new tests in PrebuiltAppHostServerTests, each verified to fail against the pre-fix logic:

• CanSkipIntegrationRestore_RestoresWhenAnotherRestoreReplacedTheAssets — the reported scenario: inputs match again but the assets were replaced.
• CanSkipIntegrationRestore_RestoresWhenTheStampDoesNotVouchForTheAssets — an inputs-only stamp from an earlier CLI.
• WriteRestoreStampAsync_WritesNoStampWhenTheAssetsAreMissing.

The WriteRestoreState helper now writes through the production writer so the tests cannot drift from the stamp format.

Full Aspire.Cli.Tests suite passes (5401 passed, 30 skipped Windows-only, 0 failed).

🤖 Generated with Claude Code

[github-actions]

🚀 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 -- 19604

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 19604"

[Copilot]

Pull request overview

Binds integration restore stamps to project.assets.json, preventing stale CLI assets from being reused after version switches.

Changes:

• Stores both input and assets fingerprints.
• Validates both fingerprints before skipping restore.
• Adds regression and legacy-stamp tests.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/Aspire.Cli/Projects/PrebuiltAppHostServer.cs	Adds assets fingerprinting and stamp validation.
tests/Aspire.Cli.Tests/Projects/PrebuiltAppHostServerTests.cs	Covers replaced assets, legacy stamps, and missing assets.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Jonas Flodén (flojon)]

Reproduced #19603 end to end to confirm this fix actually closes it. It does —
evidence below, plus three follow-ups pushed on top.

One remark worth rewording

"Switching back reproduces a byte-identical project file" reads naturally as
identical between the two CLI versions, and on that reading the fix looks like it
cannot work, since the pin demonstrably changes. It means identical to the project
file this CLI itself wrote earlier, which is right, and is what makes this CLI's
own stamp match. I misread it on the first pass and spent a while chasing a hole
that is not there, so I have reworded it.

The repro, confirmed

TypeScript AppHost with a project reference, released 13.5.1 and the
13.6.0-pr.19577.gfa0aea2c dogfood build, aspire restore -l Debug each step:

Step	CLI	csproj pin	assets declared	built generator	stamp	log
1	13.6.0-pr	13.6.0-pr	13.6.0-pr	13.6.0-pr	written DCB5A63D60E2445D	restore requested
2	13.5.1	13.5.1	13.5.1	13.5.1	untouched	restore requested
3	13.6.0-pr	13.6.0-pr	13.5.1	13.5.1	untouched	restore skipped

Step 3 printed ✅ SDK code restored successfully. mtimes land in the order the
issue reported — stamp oldest, project.assets.json next, IntegrationRestore.csproj
newest — because step 3 rewrote the csproj and then skipped restore.

The writer that replaces the assets without refreshing the stamp is simply a CLI
version that has no stamp logic at all: 13.5.1 restores unconditionally and never
writes the stamp, so step 1's stamp survives step 2 intact and step 3 reproduces
step 1's inputs exactly. Binding the stamp to the assets closes it: step 3 hashes
13.5.1's assets, mismatches stampLines[1], and re-restores.

Pushed on top (2c03362)

Three things that stand independent of the mechanism, plus a wording fix:

• WriteRestoreStampAsync was gated on !skipRestore, which only means "the
  first attempt skipped restore". When ShouldRetryWithRestore fires the retry
  does restore and rewrites the assets, and skipping the stamp there left it
  describing assets that restore had replaced — failing its own check next launch
  and paying a full restore. Now tracked as restoreRan.
• An unreadable assets file was reported as a replaced one, logging "the assets
  were replaced" straight after TryComputeAssetsFingerprint logged that it
  couldn't read them. A null fingerprint now returns without naming a writer, the
  stale-stamp check is split so the log says which reason fired, and the helper
  no longer says "restoring" on the write path.
• CanSkipIntegrationRestore_RestoresWhenTheAssetsAreMissing asked
  WriteRestoreState not to write the assets — but that writes no stamp either, so
  the test left neither file and was equivalent to the nothing-restored-yet test
  above it. It now keeps the stamp and deletes the assets. Worth noting it pins the
  scenario, not the File.Exists(assetsPath) clause: I mutation-tested that clause
  and the test still passes without it, because the null-fingerprint path returns
  the same answer. It's a cold-start fast path, now documented as one.
• Reworded the remark above.

Aspire.Cli.Tests — 123/123 in PrebuiltAppHostServerTests, 5412/5459 overall;
the 17 failures are pre-existing on Linux (12 need pwsh, 3 macOS-only, 1
Windows path, 1 Windows file-locking).

Marking ready for review.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.