A cursor-paged API list answers `?page=` with 400 naming `cursor`, instead of page one again #8396

Cursor-paged API lists now answer ?page= or ?offset= with 400 { error: "invalid_query", message: "This list pages by cursor: pass next_cursor as ?cursor=." }, instead of quietly returning page one again.

What changed

• src/http/offset_page.ts holds the one shared check, pagedByNumber, and the message text. offsetQuery returns invalid_query when either parameter is present, and offsetRefused in src/http/api.ts turns that into the 400.
• Lists that use offsetQuery (admin accounts, invites, people, milestones, and the others on it) get the 400 through that path.
• The repository issues and pulls list handlers don't use offsetQuery, so they call the same check through pageParamRefused in src/http/api.ts, right after the repo loads.
• Each of those routes' OpenAPI entries now names the 400 as a refusals entry.
• Other unknown parameters are still ignored, as the issue asked.

Tests

• test/api-page-param.test.ts is new. For the issues, pulls, milestones and admin invites lists it asserts that page=2 and offset=50 give 400 with the exact body, that ?cursor= still gives 200, and that an unrelated parameter still gives 200.
• Run: that file passes (4 tests), the three OpenAPI test files I ran pass, and tsc is clean. scripts/gate.ts printed nothing, which I read as clean. I did not run the full suite; the forge's check does that on push.

To try it Request GET /api/v1/repos/trevato/forge/issues?page=2 on this pull's preview. It should answer 400 with the message above.

Closes #8386

Cursor-paged API lists now answer ?page= or ?offset= with 400 { error: "invalid_query", message: "This list pages by cursor: pass next_cursor as ?cursor=." }, instead of quietly returning page one again.

What changed

• src/http/offset_page.ts holds the one shared check, pagedByNumber, and the message text. offsetQuery returns invalid_query when either parameter is present, and offsetRefused in src/http/api.ts turns that into the 400.
• Lists that use offsetQuery (admin accounts, invites, people, milestones, and the others on it) get the 400 through that path.
• The repository issues and pulls list handlers don't use offsetQuery, so they call the same check through pageParamRefused in src/http/api.ts, right after the repo loads.
• Each of those routes' OpenAPI entries now names the 400 as a refusals entry.
• Other unknown parameters are still ignored, as the issue asked.

Tests

• test/api-page-param.test.ts is new. For the issues, pulls, milestones and admin invites lists it asserts that page=2 and offset=50 give 400 with the exact body, that ?cursor= still gives 200, and that an unrelated parameter still gives 200.
• Run: that file passes (4 tests), the three OpenAPI test files I ran pass, and tsc is clean. scripts/gate.ts printed nothing, which I read as clean. I did not run the full suite; the forge's check does that on push.

To try it Request GET /api/v1/repos/trevato/forge/issues?page=2 on this pull's preview. It should answer 400 with the message above.

Every GET route whose contract declares a cursor now answers ?page= or ?offset= with 400 { error: "invalid_query", message: "This list pages by cursor: pass next_cursor as ?cursor=." }. One guard does it, so a new list can't forget. The new test file passes, along with 39 related contract and OpenAPI test files. tsc is clean and scripts/gate.ts printed nothing, which I read as clean. I did not run the full suite: scripts/fast.ts found the diff too broad to name tests, so I ran those related files myself.

What changed

• One guard: src/http/cursor_lists.ts builds the set of cursor-paged routes from the OpenAPI contract and refuses page and offset on them. src/http/server.ts calls it once after auth and rate limits, before any handler runs. This covers the spots you named (explore, user.ts:507, issues.ts:237, the events page) and the admin lists, with no per-handler edits.
• Removed the second path: I took out pageParamRefused in api.ts, the invalid_query branch in offsetRefused, and the offsetQuery change. Nothing in offsetQuery reads a named offset any more, so your concern there is gone.
• Contract: src/contract/openapi.ts now adds a 400 response and an invalid_query refusal to every cursor route, so no per-route refusals entries are needed. I reverted my earlier hand-written ones.
• Two gaps found: the tags and milestones routes paged by cursor but didn't declare it in the contract. I added query: { limit, cursor } to both so they are guarded.
• Docs: one paragraph on the 400 in docs/features/api-reference.md.
• Tests:

- test/api-page-param.test.ts now covers eight lists over HTTP: issues, pulls, tags, milestones, admin accounts, people and invites, and explore. Each gets page and offset and must answer 400 with the exact body. - Each list also gets an unrelated parameter and must still answer 200. - A contract walk checks that the guard fires on exactly the cursor routes and that each one names the 400 in the document. - The plain ?cursor= case from my earlier version is no longer asserted. The cursor routes are now covered through the contract walk rather than a request per list.

What I chose not to do

• Forges, prompts, drills, app env and domains, secrets, agents, egress grants, waves and assigned: I left these unguarded. They return the whole list with next_cursor: null and take no cursor, so "pass next_cursor as ?cursor=" would be wrong for them. A client looping on page sees next_cursor: null and stops. If you want them to refuse page anyway, it needs a different message and a different flag.
• Other unknown parameters: still ignored.