fix(cli): don't invent a purchase link when the server withholds upgrade_url - #7031

What

reverse start no longer makes up a purchase link when the server deliberately sends upgrade_url: null. null now means no link anywhere: the JSON prints reverse.upgrade_url: null and reverse.subscribe_command: null, and under gate: "block" the refusal says "Reverse is part of HyperFrames Pro, and a plan can't be purchased right now." with no command or URL in the message or the fix. The reverse-any-video skill (references/start.md) says to tell the person that plainly and give no link. The CLI builds its own plans link (feature=reverse&rs=<session>) only when the field is absent (an older server). A string upgrade_url is used as is, as before. (Rebased onto main after #7046, which points Free accounts at billing subscribe: a null link now withholds that command too.)

Why

• Genesis nit on feat(cli): reverse start records a reverse run; cloud render carries its session #7016 (reverse.ts ~L57): parseSession dropped the null, so reverseUpgradeUrl fell back to the CLI's plans page.
• EF experiment-framework#63633 returns {session_id, plan, gate, upgrade_url} and sends upgrade_url: null on purpose when purchases are closed to that user. With the block refusal from feat(cli): reverse start stops a Free account when the server blocks it #7017, the CLI would have refused a Free user and pointed them at a page where they can't buy.

How

• packages/cli/src/heygen/reverse.ts: ReverseSession.upgradeUrl is string | null. parseSession keeps an explicit null. reverseUpgradeUrl returns null for it and falls back to pageUrl("plans", …) only when the field is missing.
• packages/cli/src/commands/reverse/start.ts: on Free, upgrade_url and subscribe_command are both null when the link is null (freeFields). The block refusal for a null link says a plan can't be purchased right now, names no billing subscribe command, and its fix is "Run reverse start again once this account is on Pro."
• Docs (docs/packages/cli.mdx), the skill reference (subscribe_command: null → say a plan can't be bought, give no link, run nothing), and skills-manifest.json (regenerated hash) are updated to match.

Test plan

• Unit tests (targeted only), one case per branch (null / absent / string):
  • heygen/reverse.test.ts: reads upgrade_url when it is a link | null | no field, and reverseUpgradeUrl is null when the server withholds the link.
  • commands/reverse/start.test.ts runs the real reverseUpgradeUrl (only startReverseSession and pageUrl are mocked). Record output: prints the upgrade link for Free: the server's link | … | no link when the server withholds it; names no subscribe command when the server withholds the link (JSON has upgrade_url: null, subscribe_command: null). Block: stops a Free account the server blocks, with the subscribe command as the fix… (link present) and names no link when the server blocks Free and withholds the link: no plan can be bought now (null; also checks the refusal has no billing subscribe).
  • Before the fix (sources restored, tests kept), the 5 null cases fail: the CLI printed a plans link (…?feature=reverse&rs=<session>) and a billing subscribe command, and the block refusal said "Reverse is part of HyperFrames Pro. Run npx hyperframes billing subscribe --feature reverse --session <id>, then run reverse start again." After the fix, 2 files / 37 tests pass (Genesis's local run at head 83323e4).
• Also run locally (pre-rebase head): tsc --noEmit, oxlint and oxfmt --check on packages/cli are clean; lint-skills, the skill-mirror check and the fallow audit pass on the changed files.
• Manual testing: not run against a real server.
• Documentation updated
• Comments follow CONTRIBUTING.md "Comments"

— wanbi

🤖 Generated with Claude Code