fix(cli,aspire): generated apps report Healthy only once they can server-render

[rickylabs]

Summary

A generated Fresh app was reported Healthy by Aspire while every request to it returned 500. The
Aspire helper generator registered no health check of any kind for generated resources, and
Aspire treats a resource with no registered health check as ready the moment its process reaches
Running — so "the process started" was the entire health contract. This PR gives app resources
an HTTP health probe against their own server-rendered /health route, and extends
scaffold.runtime so the suite actually asks the running app for a page.

Scope

• Archetype / area: Archetype 6 (CLI / Tooling), scope overlay service — packages/cli Aspire
  helper generators + CLI E2E suite, plus one constant and one optional schema field in
  packages/aspire.
• Closes fix(aspire): resource reports Healthy while SSR returns 500 — probe checks the port, not the app #954

Root cause

Not a probe that was checking the wrong thing — there was no probe at all.

generateRegisterApps emitted withHttpEndpoint({ port, env: 'PORT' }) and stopped. Aspire's
documented fallback is explicit: "If no health checks are registered for a resource, the AppHost
waits for the resource to be in the Running state." For an addExecutable resource, Running
means the process was spawned. aspire wait <app> --non-interactive therefore returned healthy for
an app that could not render a single page.

What changed

• packages/aspire — RESOURCE_DEFAULTS.AppHealthCheckPath = '/health' (beside the existing
  HttpEndpointName, which the probe reuses as its endpoint name), and an optional
  AppEntry.HealthCheckPath (string | false).
• generate-register-apps.ts — emits
  await <app>.withHttpHealthCheck({ path, endpointName: 'http' }) for app entries with a port,
  registered after the endpoint whose base address it resolves against.
• routes/health.tsx.template — doc comment now states the SSR contract the probe depends on.
  No behaviour change.
• scaffold.runtime — two new paired gates (see Regression guard).

Why /health and not /

The issue's suggested direction — "an HTTP health probe that renders a minimal SSR route" — is what
this implements. The scaffold already writes apps/<app>/routes/health.tsx, which renders through
definePage() and the app shell and only short-circuits to JSON when the caller sends
Accept: application/json without text/html. Aspire's probe sends no Accept header, so it
takes the SSR branch: a broken render pipeline fails the probe. Probing / instead would
false-negative on any app whose home page is auth-gated or redirects.

One correction to the upstream docs

Aspire's docs show withHttpHealthCheck('/health'). The TypeScript SDK that aspire restore
generates for SDK 13.4.6 — the version the scaffold pins — declares
withHttpHealthCheck(options?: WithHttpHealthCheckOptions) on ExecutableResource. I verified this
by running a real aspire restore against a throwaway apphost and reading the generated
.aspire/modules/aspire.mts. The generator emits the options-object form; the documented positional
form would throw at AppHost start.

Regression guard

The check that was looking past the problem is scaffold.runtime. It started the whole AppHost,
waited on every database, cache, and plugin resource and probed their /health — but never waited
on the generated app and never issued a single HTTP request to any app route. The only app-shaped
gate, behavior.ui-render, renders AI payload components in-process and never touches the running
server. An app that returned 500 to every request passed the suite cleanly.

Two paired gates close that:

• runtime.wait.dashboard — aspire wait on the app resource, which is only meaningful now that
  the probe exists. 300s timeout, covering Vite cold start and first render.
• behavior.app-home — fetches the app's home page and requires a 2xx that is actually HTML.
  Asserting the status alone would not do: a 500 error page is text/html too.

Plus unit-level guards that fail before the fix and pass after it:

• generators-background-app_test.ts — probe emitted, emitted after the endpoint, honours a
  custom HealthCheckPath, omitted for HealthCheckPath: false, and never emitted for
  tauri/desktop/task.
• route-templates_test.ts — the health route still renders through the page layer, and the JSON
  branch remains the guarded exception rather than the fall-through.
• suite-registry_test.ts — both new gates are registered in scaffold.runtime, in order.

Definition of Done

• Root cause identified and fixed at the generator, not worked around at the call site
• Regression guard extends the check that let the defect through (scaffold.runtime)
• A test that fails before the fix and passes after it
• fmt:check, lint, check, test, arch:check all green
• scaffold.runtime executed end to end (needs a runtime host — not available in this session)
• Behaviour change and deliberate non-scope stated explicitly

Slices

• S1 Run artifacts + Design checkpoint — 568ffe11d
• S2 Probe path contract in @netscript/aspire — d77932249
• S3 Generator emits withHttpHealthCheck for app resources — 446a47813
• S4 Pin SSR as the fall-through of the scaffolded health route — 37c295966
• S5 scaffold.runtime waits on the app and fetches its home page — 1780ffda7

Validation

Gate	Result
deno task fmt:check	PASS — 1869 files, 0 findings
deno task lint	PASS — 1724 files, 0 occurrences
deno lint packages/cli/{templates,e2e} (cli is excluded from the root lint task)	PASS — 95 files
deno task check	PASS — 2457 files, 0 occurrences
deno task test	PASS — 2230 passed, 0 failed, 12 ignored (3m22s)
deno task arch:check	PASS — exit 0, no FAIL= rows; pre-existing WARN/INFO only
run-deno-doc-lint.ts --root packages/aspire	PASS — 0 errors, 0 missing JSDoc
deno task e2e:cli run scaffold.runtime	NOT RUN — see below

scaffold.runtime was not executed. This environment has no database containers or full
runtime, so the two new E2E gates are proven by registration tests only, not by an actual run. They
need the OpenHands / merge-readiness pass before this merges. Flagging rather than quietly skipping.

Fail-before evidence for the generator guard (generator change stashed):

should register an HTTP health probe for app resources ... FAILED
should probe a custom path when HealthCheckPath is configured ... FAILED
FAILED | 1 passed (35 steps) | 1 failed (2 steps)

What I deliberately did not change

• The SSR failure itself (fix(sdk,fresh): jsr: specifiers for beta.11 SDK subpaths fail to load under Vite #953). It is the reproduction vehicle for "healthy while 500", not
  this defect. Left open.
• Services, plugins, and background processors. They have the same missing-probe gap, but
  first-party plugin health paths are heterogeneous — workers/sagas/auth serve /health/live,
  triggers serves /health — so a single defaulted path would be wrong for several of them and
  would newly gate aspire wait on those resources against an unverified path. That needs declared
  per-resource paths, which is its own change. Follow-up issue below.
• tauri / desktop / task app types. No HTTP page contract; desktop gets no endpoint at
  all.

Behaviour change to be aware of

An existing project whose app has no /health route will now show Unhealthy instead of a false
green, and aspire wait <app> will block on it. That is the intended correction, and
HealthCheckPath: false is the opt-out. The scaffold has always written routes/health.tsx, so
scaffolded projects are unaffected. .helpers/*.mts are regenerated by netscript generate, so
existing projects pick the probe up on their next generate.

Follow-up worth filing

Health probes for generated services, plugins, and background processors, with each resource
declaring its own path rather than inheriting a default. Same root cause, different blast radius.

Harness

• Run dir: .llm/runs/fix-aspire-app-health-probe--954/
• Phase: impl — research, plan, and Design checkpoint are committed in S1.
• Process deviation (recorded in drift.md D-1): this is a single-session run, so PLAN-EVAL and
  IMPL-EVAL were not run as separate evaluator sessions. PR review is the reviewing pass.

Drift / Debt

• D-1 Single-session run; no separate evaluator sessions.
• D-2 Aspire docs disagree with the generated SDK on withHttpHealthCheck's signature — options
  object wins. Re-verify if the SDK pin moves.
• D-3 scaffold.runtime did not exercise the generated app at all; behavior.ui-render does not
  count.
• D-4 scaffold.runtime not executed in this environment.
• No new arch-debt entries; none closed.

[rickylabs]

[PHASE: IMPL]

Five slices landed; #954 root-caused to a missing Aspire health check, not a mis-aimed one.

What the root cause turned out to be

The Aspire helper generator registered no health check at all for generated resources.
generateRegisterApps emitted withHttpEndpoint({ port, env: 'PORT' }) and stopped. Aspire's
documented fallback then applies: "If no health checks are registered for a resource, the AppHost
waits for the resource to be in the Running state." For an addExecutable resource that means
"the process was spawned" — so aspire wait <app> returned healthy for an app that could not render
a single page.

Slices

1. 568ffe11d — run artifacts + Design checkpoint
2. d77932249 — RESOURCE_DEFAULTS.AppHealthCheckPath + optional AppEntry.HealthCheckPath
3. 446a47813 — generator emits withHttpHealthCheck({ path, endpointName }) for app resources
4. 37c295966 — pin SSR as the fall-through of the scaffolded /health route
5. 1780ffda7 — scaffold.runtime waits on the app and fetches its home page
6. 335570f69 — gate evidence

Two things worth a reviewer's attention

1. The upstream docs are wrong for this SDK version. Aspire documents
   withHttpHealthCheck('/health'). I ran a real aspire restore against a throwaway apphost pinned
   to SDK 13.4.6 and read the generated .aspire/modules/aspire.mts: ExecutableResource declares
   withHttpHealthCheck(options?: WithHttpHealthCheckOptions) with { path?, statusCode?, endpointName? }. The positional form would have thrown at AppHost start. Recorded as drift D-2.

2. scaffold.runtime never touched the running app. It started the whole AppHost, waited on
   every database, cache, and plugin resource and probed their /health — but issued zero HTTP
   requests to any app route. behavior.ui-render, the only app-shaped gate, renders AI payload
   components in-process. That is why "Healthy while every request returns 500" passed the
   merge-readiness suite. Recorded as drift D-3.

Gates

Gate	Result
deno task fmt:check	PASS — 1869 files, 0 findings
deno task lint	PASS — 1724 files, 0 occurrences
deno lint packages/cli/{src/kernel/templates,e2e}	PASS — 95 files (cli is excluded from the root lint task)
deno task check	PASS — 2457 files, 0 occurrences
deno task test	PASS — 2230 passed, 0 failed, 12 ignored (3m22s)
deno task arch:check	PASS — exit 0, no FAIL= rows
run-deno-doc-lint.ts --root packages/aspire	PASS — 0 errors, 0 missing JSDoc
deno task e2e:cli run scaffold.runtime	NOT RUN — no database containers on this host

Fail-before evidence for the new generator guard (generator change stashed):

should register an HTTP health probe for app resources ... FAILED
should probe a custom path when HealthCheckPath is configured ... FAILED
FAILED | 1 passed (35 steps) | 1 failed (2 steps)

Next

• scaffold.runtime must run before merge — the two new E2E gates are proven by registration tests
  only. That is the one unchecked DoD box.
• Follow-up worth filing: the same probe for generated services, plugins, and background
  processors, with declared per-resource paths (workers/sagas/auth serve /health/live, triggers
  serves /health, so a single default would be wrong). Deliberately out of scope here.
• Process note: single-session run, so no separate PLAN-EVAL / IMPL-EVAL sessions (drift D-1). PR
  review is the reviewing pass.

[augmentcode]

🤖 Augment PR Summary

Summary: This PR fixes Aspire “false healthy” reporting for generated Fresh apps by registering an HTTP health probe that exercises the app’s SSR pipeline.

Changes:

• Adds RESOURCE_DEFAULTS.AppHealthCheckPath = "/health" and an optional AppEntry.HealthCheckPath override (or false to opt out) in @netscript/aspire.
• Updates the CLI Aspire helper generator to emit withHttpHealthCheck({ path, endpointName: "http" }) for app resources after their HTTP endpoint is registered.
• Clarifies the scaffolded /health route’s contract: SSR is the fall-through, JSON is only returned for JSON-only Accept requests.
• Extends the scaffold.runtime E2E suite to (1) aspire wait on the app resource and (2) fetch the app home page and require a 2xx HTML response.
• Adds/updates focused unit tests covering generator emission, health-route behavior, and suite registration/order.

Technical Notes: The probe targets the app’s own server-rendered /health route so SSR failures surface as Unhealthy instead of “process is Running ⇒ Healthy”.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[augmentcode]

packages/cli/e2e/src/application/gates/scaffold/runtime-gates.ts:21 — APP_HOME_URL hardcodes 8000 while the doc comment says it’s on PORT_RANGES.APP.start, so a future default-port change would make this gate probe the wrong URL. If the app port can vary by scaffold options, this would also become a false failure/pass depending on what’s running on 8000.

Severity: low

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

packages/cli/src/kernel/templates/aspire/helpers/register/generate-register-apps.ts:248 — HealthCheckPath is interpolated into a single-quoted string literal without escaping, so a configured path containing ' would generate invalid TypeScript in the emitted helper. Since this is user-supplied config, it may be worth ensuring it can’t break codegen output.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[rickylabs]

[PHASE: IMPL] [SLICE: S6]

scaffold.runtime ran for the first time and found a defect in this PR's own new gate — not in the app, and not in #953.

What failed and why

behavior.app-home probed a hardcoded http://127.0.0.1:8000/, commented as PORT_RANGES.APP.start. The scaffold publishes the app on PORT_RANGES.APP.start + 10 — 8010 — offset on purpose since the TS AppHost landed so the Aspire proxy does not collide with Vite's own default of 8000 (plan-init.ts carries the rationale in a comment). Nothing has ever listened on 8000.

The timing said so before the code did: 60182 ms is exactly 60 iterations of the probe's 1000 ms sleep plus process start, so every fetch failed instantly. That is connection-refused — not a 500, not a slow render. And runtime.wait.dashboard PASSED in 53 s in the same run, which means the health probe added in S3 had already proven the app server-renders /health.

Confirmed against a generated project on a runtime host:

Evidence	Result
.helpers/register-apps.mts (generated)	await dashboard.withHttpEndpoint({ port: 8010, env: 'PORT' })
appsettings.json (generated)	NetScript.Apps.dashboard.Port = 8010
ss -lntp with the AppHost up	127.0.0.1:8010 bound by dcp; nothing on 8000
curl the running app	status=200 type=text/html size=130170 — the home page renders
probe → port 8000	HTTP 0 (): fetch failed after 1m0.483s — CI's 60182 ms, reproduced
probe → the app's real port	app home page rendered: HTTP 200 (130162 bytes), 0.4 s

#953 / #957 are not prerequisites for this PR. scaffold.ui-local-source maps every @netscript/* specifier to the workspace member, so the unresolvable JSR subpath in #953 cannot occur in this suite — and generated.deno-check would have failed first if it could. #957's own scaffold-runtime failure is a cancelled runner (The runner has received a shutdown signal) at behavior.workers-health; its previous run passed the same lane. The two PRs are independent and neither blocks the other.

Fix — 2835d7b76

The probe carries no port at all. behavior.app-home now runs probe-app-home.ts <projectRoot> <appName>, which resolves the URL from the project's own appsettings.json — the same file the helper generator reads when it emits withHttpEndpoint({ port }). A literal cannot drift from the artifact it describes if there is no literal.

Moving the probe from an inline deno eval string to a script module (the durable-cli-parity.ts pattern) also keeps the gate's command factory pure. Resolving the port inside the factory broke suite runner skips cleanup phase when cleanup is disabled, which builds the real scaffold.runtime definition against a faked executor — a gate definition that reads the filesystem is not constructible without one.

SCAFFOLD_APP_PORT replaces the PORT_RANGES.APP.start + 10 expression that was written out three times (plan-init.ts, render-ts-apphost.ts, write-app-files.ts). Generated output is unchanged — a fresh netscript init still writes Port: 8010 and a '8010' fallback in main.ts.

Regression guard

The check that let this through is scaffold.runtime itself, which drift.md D-4 recorded as never executed. The guards now fail at unit speed:

• runtime-gates_test.ts — asserts the app-home command whole, and that no argument contains PORT_RANGES.APP.start. The shipped gate fails this test.
• generated-app-endpoint_test.ts — the resolver returns a deliberately unusual declared port (9137, proving nothing is hardcoded); returns SCAFFOLD_APP_PORT from an appsettings.json produced by the CLI's real generateAppsettings(), with SCAFFOLD_APP_PORT asserted to differ from PORT_RANGES.APP.start; and names the file and the app when the port is missing, unreadable, or unparseable rather than guessing.

Gates

Gate	Result
deno task fmt:check	PASS — 1869 files, 0 findings
deno fmt --check --ext ts over the touched packages/cli roots (excluded from the root task)	PASS — 94 files
deno task lint	PASS — 1724 files, 0 occurrences
deno lint packages/cli/e2e …	PASS — 107 files
deno task check	PASS — 2460 files, 0 failed batches
deno task test	PASS — 2235 passed, 0 failed, 12 ignored (3m35s)
deno task arch:check	PASS — exit 0, no FAIL= rows
deno task quality:scan	PASS — ok:true, findings [], 7 pre-existing allowances
deno test packages/cli/e2e/tests/	PASS — 53 passed
deno task e2e:cli run scaffold.runtime	PARTIAL — environmental, see below

scaffold.runtime reached runtime.wait.dashboard and timed out there after 300 s because two unrelated Aspire AppHosts from other projects on that host already held 127.0.0.1:8010, so this run's app proxy could never bind. Those were not this repository's processes and were left alone. The suite aborts on the first critical failure, so behavior.app-home was not reached in-suite; it was verified directly against the running generated app instead (table above). A clean-host scaffold.runtime on CI is the remaining verdict — which is the whole point of the gate this PR adds.

Drift

• D-5 — D-4 came true: a gate written without ever executing the suite it extends is not a gate.
• D-6 — gate command factories must stay pure functions of the run context.
• D-7 — every scaffolded project defaults to the same app port, so two local projects cannot run at once. Worth its own issue; not filed from this session.

[rickylabs]

[PHASE: IMPL] [SLICE: S6 — confirmed]

Clean-host CI verdict on 2835d7b76 — the outstanding gate from the comment above:

> runtime.wait.dashboard: Wait for dashboard
  PASSED 53239ms
> behavior.app-home: Generated app serves its home page
  PASSED 225ms
Summary: passed=62 failed=0

scaffold-runtime PASS (5m28s); every other check green. drift.md D-4 and D-7 are now closed — this is the first end-to-end execution of scaffold.runtime for this PR, and it is the run that proves both new gates.

225 ms for the home page is the pair working as designed: runtime.wait.dashboard blocks on the health probe until the app can server-render, so by the time behavior.app-home asks for / the app is already warm. The 60-attempt budget is headroom, not the path.

For completeness on the other branch: #957's scaffold-runtime also passes on re-run (job, 4m30s). Both PRs are green independently, which settles it — they were never coupled.