feat(mcp): harden Aspire CLI endpoint discovery

[rickylabs]

Summary

Production-hardens the F1(b) aspire-cli endpoint source so live endpoint discovery fails visibly on CLI, parse, identity, or torn-run faults. This is the P1-authorized re-scope of #1133; it emits no template manifest.

Scope

• Archetype / area: packages/mcp Archetype-2, Aspire tooling
• Closes [openapi-mcp S7] Endpoint-manifest emission from the P1-proven seam #1133
• Part of Epic: OpenAPI→MCP service introspection — agent-legible service APIs #1126

Slices

• S1 harness bootstrap and locked F1(b) design — 3c8bc785b
• S2 identity-bound drift-tolerant Aspire CLI adapter — 637431952
• S3 live scaffold directory gate and allocated-target hardening — 16fc9528c
• S4 rebase on merged S6 and route live gate through list_api_services — 5e11f1894

Validation

• MCP focused source+directory tests — 17/17 pass
• MCP package test task — 95/95 pass
• E2E gate registry/runtime definitions — 20/20 pass
• package check; scoped lint/fmt; quality scan; arch check; doc lint; publish dry-run — pass
• pre-S6-reconcile scaffold.runtime attempt 2 — 71/71 pass with cleanup; named adapter gate pass in 4.896s
• box-43 adapter capture — fresh fix(scaffold): randomize default listener ports #1211-randomized scaffold; aspire describe target PORT=45253 correlated to list_api_services live users base URL; foreign AppHost remained live

Harness

• Run dir: .llm/runs/feat-openapi-mcp-manifest-cli--1133/
• Phase: implementation evaluation; formal PLAN-EVAL is composed/not-local per milestone ruling D6.

Drift / Debt

• Qualified F1(b) replaces the issue's original manifest-template arm; recorded in drift.md.
• Real proxy collision selected Aspire's allocated executable target port; recorded in drift.md.
• D15 waives AppHost serialization for the adapter capture only; the full runtime suite remains serialized.
• Automatic composed evaluator surface was policy-skipped; separate sign-off remains pending and is recorded in drift.md.
• Debt: none currently.

Definition of Done

• CLI absence, non-zero exit, format drift, and partial/torn output are explicit source status rows.
• Project-root and AppHost run identity checks prevent stale or foreign describe output from reading as live.
• A scaffolded app's live ports resolve end to end through the adapter (list_api_services if S6 lands; directory fixture otherwise). Evidence
• Archetype-2 full-column, framework quality, and package JSR gates pass.
• Separate composed implementation evaluation passes. Composed per milestone-run.md § Evaluator protocol + ruling D6: draft→ready augment, review-thread gate, and the orchestrator pre-merge gate (latest-per-name contexts + evidence verification on 14db53ace, recorded in the release-0.0.5 orchestration worklog).

issue: 1133
entries:
  - box: "gate: scaffold.runtime evidence — a scaffolded app run produces the manifest (or CLI-adapter equivalent) and `list_api_services` resolves live ports through it"
    evidence: "[Box-43 live adapter capture](https://github.com/rickylabs/netscript/pull/1206#issuecomment-5178346127): fresh #1211-randomized scaffold; exact AppHost describe target PORT=45253 matched list_api_services live users base URL while a foreign AppHost remained live."

[rickylabs]

[PHASE: RESEARCH]

Re-baselined #1133 to qualified F1(b) on current main after S5/#1194. The real Aspire 13.4.6 surface exposes exact appHostPath, appHostPid, and executable workDir, enabling path/run binding without template emission. S6 remains open; the E2E fallback is a direct directory call. Baseline verification currently owns the serialized AppHost slot.

[rickylabs]

[PHASE: PLAN]

Locked Archetype-2 design in .llm/runs/feat-openapi-mcp-manifest-cli--1133/plan.md: pre/post aspire ps binds one stable AppHost run around describe; real paths bind AppHost/resources to the project; balanced JSON parsing tolerates benign banners/field drift but rejects torn output. Per milestone ruling D6, plan-eval.md records COMPOSED_NOT_LOCAL; no local formal PLAN-EVAL is launched.

[rickylabs]

[PHASE: IMPL]

Slice 2 landed as 1179c79a1. The adapter now brackets describe with exact-path ps snapshots, rejects AppHost process changes as run_id_mismatch, real-path binds AppHost/resource ownership to projectRoot, tolerates banner/trailer/casing drift, and rejects torn output. Fixtures pass 17/17; the full MCP package passes 95/95 plus check, scoped lint/fmt, quality scan, arch check, doc lint, and publish dry-run. Live read-only proof rejected a removed baseline AppHost and accepted the still-current one. scaffold.runtime remains queued behind the baseline AppHost slot.

[rickylabs]

[PHASE: IMPL]

S3 landed as dfcf2b23a. The canonical live gate first demonstrated the negative case: a fixed proxy URL on port 3001 belonged to foreign service products, and the adapter refused it as identity_mismatch. The adapter now prefers Aspire's described executable target PORT, retaining exact AppHost/project/run and service identity checks. The named behavior.mcp-endpoint-directory gate is wired into scaffold.runtime. Local canonical attempts cleaned up but later encountered unrelated baseline users DB-health and workers-api readiness failures; fresh branch CI is the decisive target-port verdict.

Static evidence: MCP package 95/95; focused source+directory 17/17; E2E registry/runtime definitions 20/20; scoped check/lint/fmt and publish assets green. No run-owned survivors.

[rickylabs]

[PHASE: IMPL]

Rebased on current main after S6/#1204 landed and upgraded behavior.mcp-endpoint-directory to invoke createListApiServicesFlow (list_api_services) over the live Aspire-backed directory. Targeted check passes and E2E registry/runtime definitions pass 20/20.

The prior serialized canonical run passed the direct-directory form 71/71, including the named gate in 4.896s. Current-head CI attempt 1 never reached AppHost or S7: runtime.aspire-restore timed out twice at 900s, cleanup passed. Attempt 2 was cancelled while pending behind another global-slot holder. The next serialized proof remains queued until the holder releases. Separate composed evaluator sign-off also remains pending; the automatic OpenHands check was policy-skipped. PR stays status:impl-eval with both boxes honestly unchecked.

[rickylabs]

[PHASE: IMPL] — box 43 live evidence (D15)

Fresh scaffold on the #1211-rebased head:

netscript-dev init s7-box43-live --path .llm/tmp/s7-box43 --db none --service --service-name users ...
project.targetPath=/home/codex/repos/ns005-s7/.llm/tmp/s7-box43/s7-box43-live
filesCreated=202; aspire.resourceCount=2
standalone randomized fallback: services/users/src/main.ts PORT || 60778

The exact AppHost ran alongside foreign AppHosts under orchestrator ruling D15. aspire describe --format Json --apphost /home/codex/repos/ns005-s7/.llm/tmp/s7-box43/s7-box43-live/aspire/apphost.mts reported:

{"displayName":"users","state":"Running","healthStatus":"Healthy","urls":[{"name":"http","url":"http://localhost:45889"}],"properties":{"executable.workDir":"/home/codex/repos/ns005-s7/.llm/tmp/s7-box43/s7-box43-live/services/users"},"environment":{"PORT":"45253"}}

Public MCP tools/call → list_api_services against that project root returned:

{"name":"users","status":"running","source":"aspire-cli","baseUrl":"http://127.0.0.1:45253","specUrl":"http://127.0.0.1:45253/api/openapi.json","operationCount":3}

The Aspire source row was outcome: used; its users candidate was http://127.0.0.1:45253. Thus the tool selected this exact AppHost’s allocated target PORT, not its proxy 45889 and not a foreign AppHost. A foreign sagas AppHost was present in aspire ps before and after the call. Cleanup stopped only the exact S7 AppHost; the foreign AppHost remained running.

Positive result: box 43 PASS. The earlier S3 identity_mismatch negative-case evidence remains unchanged.