Delete the /api/v3 alias once the CLI fleet is on 0.4.0 #216

Unblocked by the #215 decision, and the scope is unchanged: delete the alias.

#215 resolved that gh is not a supported client, so nothing makes /api/v3 permanent. Measured against gh 2.89.0, its ported commands run on GraphQL (POST /api/graphql) and GET /api/v3/meta, neither of which this application serves, and the gh api passthrough already reaches /api/v1 when given a full URL. See docs/decisions/0009-serve-a-github-shaped-api-not-a-gh-compatible-one.md.

The deletion is now a one-file change plus tests, and FORGEAPI-002 (INVARIANTS.md) keeps it that way: no route is declared at the old prefix, no response emits it, and test/openagents_web/api_version_posture_test.exs proves lib/openagents_web/plugs/api_v3_rewrite.ex is the only file under lib/ that names it. When the fleet is on CLI 0.4.0, delete the plug, its line in lib/openagents_web/endpoint.ex, test/openagents_web/plugs/api_v3_rewrite_test.exs, and the @alias_plug exemption in the posture test, then drop the alias paragraph from priv/docs/rest-api.md and mark FORGEAPI-002 amended.

One residue was already cleared in 1666117: POST /api/v1/traces was returning a url field naming /api/v3/traces/{id}, which this issue would have broken.

Assessed 2026-08-25. Still blocked, but on a different thing than the issue said.

#215 is cleared

ADR 0009 (docs/decisions/0009-serve-a-github-shaped-api-not-a-gh-compatible-one.md,
accepted 2026-08-25) settled the gh posture against permanence: "/api/v3 stays a
dated migration alias for released clients, and it gets deleted on the schedule issue
#216 describes. Nothing about gh makes it permanent." It states outright that
"Issue #216 proceeds." The unless the gh-posture decision made it permanent clause in
this issue's outcome is resolved: it did not. I have dropped the #215 edge.

The ADR also shrank the job. INVARIANTS.md FORGEAPI-002 now holds
OpenAgentsWeb.Plugs.ApiV3Rewrite as the only place in lib/ naming the old prefix,
and test/openagents_web/api_version_posture_test.exs proves it. Measured today, the
whole deletion surface is:

• lib/openagents_web/plugs/api_v3_rewrite.ex and its endpoint line
• test/openagents_web/plugs/api_v3_rewrite_test.exs
• the @legacy_prefix "api/v3" arm of test/openagents_web/api_version_posture_test.exs
• the FORGEAPI-002 paragraph and the docs/taxonomy.md:95 sentence

#212 is closed, but its downstream condition is not met

This issue's gate is not "#212 merged", it is "the CLI fleet is on 0.4.0". It is not.

• @openagentsinc/cli dist-tags.latest on the npm registry is 0.3.5
  (published 2026-08-24T06:37:52Z). 0.4.0 is not in the registry at all — the
  published version list ends at 0.3.5.
• The packed @openagentsinc/cli@0.3.5 artifact contains 61 occurrences of
  api/v3 and zero of api/v1.
• The CLI installed on the host administering this tracker is 0.3.4, whose dist/
  carries 44 api/v3 references. This comment was filed over the alias.
• CLI 0.4.0 exists only as monorepo source at 655689a480, where
  src/constants.ts sets API_BASE_PATH = "/api/v1/".

#213 closed honestly about this — "Publishing the package to npm is the one remaining
step and stays an owner action" — but nothing open was tracking that step, which is how
this issue came to look ready while its real precondition had no owner. Filed as #247
and added as the blocker.

Verdict

Do not delete the alias. Every install made from the documented instruction
(npm install --global @openagentsinc/cli@latest) speaks only /api/v3 today, so
deleting the plug now breaks the entire installed fleet, this tracker's own tooling
included. Unblocks when #247 publishes 0.4.0 and installs have moved.

Unblocked as of 2026-08-25: @openagentsinc/cli@0.4.0 is published and latest points at it (#247). The packed artifact speaks /api/v1 only — 74 references, zero api/v3 — and was verified by installing from the registry and running a real command against the live forge.

Still not safe to delete the alias today. Publishing makes the upgrade possible; it does not move the installed fleet. Anything still on 0.3.x reaches this forge over /api/v3, and that included this machine's own CLI until minutes ago. What this issue now needs is a way to know the fleet has moved — the alias's own request counts by client version would answer it — rather than a date.

Per ADR 0009 the alias stays temporary and is not made permanent for gh, and FORGEAPI-002 has already reduced its deletion to one plug, one endpoint line, two test files, and a docs paragraph.