[purpshell]

Adds typed Number tier commands with Hybrid Link tier transitions. Before this PR the CLI had no tier-change command; the README pointed users to raw api calls.

polymorfa session tier quote SESSION --tier free|standard|pro|inherit \
  [--keep linked_devices|official_api | --split --stay linked_devices|official_api --new-number-name NAME | --merge-with NUMBER_UUID]
polymorfa session tier confirm SESSION --quote QUOTE_UUID --yes [--idempotency-key KEY]
polymorfa session tier status SESSION QUOTE_UUID
polymorfa session hybrid-merge-candidates --project PROJECT_UUID

• --keep, --split and --merge-with are mutually exclusive. --stay/--new-number-name work only with --split, and the name follows the API pattern. --merge-with needs --tier pro and a UUID. Every invalid combination exits 2 before a request. --project is sent as the body projectId.
• Human output shows the tier result, the Hybrid Link plan (keep / split / merge, surviving Number, new Number name and ID), the transition status separate from the tier status, the failure reason, and an "Action required" line when metaDisconnectRequired is true. It also prints the next command (confirm or status). --json prints {data, metadata} like the other Platform commands.
• hybrid_choice_required (409, exit 4) adds: "Choose --keep linked_devices|official_api, or --split --stay linked_devices|official_api --new-number-name NAME, and quote again." hybrid_transition_ineligible (exit 4) keeps the API's message, which carries the reason.
• session hybrid-merge-candidates labels each Number "can be absorbed" or "must be kept" (from canBeAbsorbed; a Number with hosted message storage must be kept). For an eligible pair it prints the exact merge command. For an ineligible pair it explains every reason, including transition_in_progress, pairing_in_progress and hms_enabled. Without Hybrid Link access, the API's 403 feature_unavailable exits 3.
• --merge-with is not refused locally for hosted storage, because the quote command cannot know it without a second request; the API decides. When the API rejects with hybrid_transition_ineligible: hms_enabled, the CLI adds: "A Number with hosted message storage must be kept: quote the merge on it and pass the other Number to --merge-with."
• The missing-choice code is hybrid_choice_required (API PR #381), replacing hybrid_resolution_required. It still exits 4 with the --keep/--split hint. session tier status explains a queued change rejected with failureReason: "hybrid_choice_required" and says to quote again with a choice.
• confirm requires --yes because it charges credit and records the connection change. It never creates or confirms a replacement quote.
• New session:tier topic. README "Number tier changes" section replaces the raw-API instructions.

SDK dependency

The commands need unpublished SDK changes from polymorfa/sdks#304 (6271f4734476c195b4a84d1863561222a8e515d1), which pins API contract polymorfa/polymorfa@fcf7b21015dd185e987b5aa3580e8af5f4c7f1a4 (branch t3code/hybrid-pro-downgrade, API PR #404, not yet merged). As in #33, CI temporarily checks out that exact SDK commit, builds it, packs it and installs it with --no-save. package.json/package-lock.json still pin the dev registry version (0.1.0-dev.20261001215108). Before merging: publish the SDK, bump the registry pin (package.json and lockfile) to the new 0.1.0-dev.*, and remove the CI source override.

Six-part assessment

Part	Status	Evidence
API	Companion, unmerged	polymorfa/polymorfa#404 @ fcf7b21 owns the routes, the 409/403 codes and the authority checks.
SDKs	Companion, unpublished	polymorfa/sdks#304. The registry pin must be bumped after publication (see above).
CLI	Updated	Four commands, error guidance, README, and tests. The MCP server exposes no session tier tools, so none were added.
Docs	Updated	README "Number tier changes". Public Mintlify docs belong to the API PR.
Feature releases	Blocked on API/SDK merge	CLI flags grant no access. The API gates merge on messaging.hybrid-link and keeps the downgrade resolution ungated. No flag or rollout change.
Admin controls	Unaffected here	The CLI has no staff surface. The API change extends the read-only admin-hybrid-link view.

Verification (Node 24.15, local SDK tarball from #304 @ 6271f47, after merging CLI dev as of 2026-10-02)

• The merge conflicted in src/services/call-analytics.ts. I resolved it by taking dev's version: dev now calls calls.retrieve directly, so this branch's earlier lint suppression is gone.
• format:check, lint, typecheck, build, npm pack --dry-run: pass
• audit:prod: 0 vulnerabilities. The brace-expansion advisory from the previous revision is resolved on dev.
• Full suite with --testTimeout=30000 (the host was heavily loaded): 104 files, 1001 tests pass. test/commands/number-tiers.test.ts has 26 tests.

No live API or deployment was exercised.

[coderabbitai]

Warning

Review limit reached

The included review limit has been reached and this organization has disabled usage-based review continuation. Wait for reviews to reset or ask a billing admin to change After included review limits.

• Ask an admin to enable usage-based reviews

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Next included review available in 3 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available. Your 69 included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: a26ebcd8-025e-445a-8d2a-a81c6b7bd97d

📥 Commits

Reviewing files that changed from the base of the PR and between ed6515c and 98a8b94.

📒 Files selected for processing (10)

• .github/workflows/ci.yml
• README.md
• package.json
• src/commands/session/hybrid-merge-candidates.ts
• src/commands/session/tier/confirm.ts
• src/commands/session/tier/quote.ts
• src/commands/session/tier/status.ts
• src/errors/present.ts
• src/services/number-tiers.ts
• test/commands/number-tiers.test.ts

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}

[purpshell]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.