[jrusso1020]

What

Use dedicated public HyperFrames CLI clients, consistent dev/production routing, and isolated HyperFrames credentials so verified CLI work can select HF billing.

Why

The existing CLI shares the HeyGen CLI registration and credential store. Its work can therefore select the HeyGen billing product, and another CLI can overwrite its login.

Related work

Backend classification: heygen-com/experiment-framework#61702. Deploy it to the public API and voice services before merging/releasing this CLI switch. Registration branding alone does not select billing. The OAuth Client Manager changes, EF #61657 and hg.dev #1795, are merged and deployed.

How

• Public prod client Zg3LF4FCLoeJoGs2YqMtZ17g; dev client 9QoaiwCZov9O0cAkC4OZbR4p. Both are registered with no secret. The dev device resource is verified as https://api2.dev.heygen.com; the corresponding production correction is still pending.
• HYPERFRAMES_ENV=dev selects matching OAuth/API/publish hosts and a separate credential directory. Refresh/revoke stay bound to the issuing client and token endpoint. Migration requires login again; expired OAuth cannot silently choose a saved API key.
• Media helpers get temporary access-only credentials and cannot read the separate HeyGen store. Near-expiry sessions refresh in the parent before helper execution. Standalone audio uses the same environment/store binding.
• Login, payer and telemetry documentation reflects the isolated store. Auth status no longer presents generic HeyGen balances as the HF balance; JSON preserves the raw account payload and explicitly scopes billing.

Test plan

• Prior feature validation: 316 focused CLI tests and 51 standalone audio/telemetry/parity tests passed; build, typecheck, lint/format, comments, Fallow and required hooks passed.
• Windows mode assertions follow the existing POSIX-only convention; isolation and cleanup remain tested on every platform.
• Live DEV device sign-in through the built CLI passed.
• Live DEV browser/PKCE callback and code exchange through the current auth source passed.
• Both sessions verified identity, refreshed with the dedicated client binding, logged out and removed the isolated store. Revoked access/refresh tokens returned 401/400. No tokens are included here.
• Companion branch integration against dev data verified free-render admission, five-render exhaustion returning 402 hf_subscription_required, unchanged alternate wallets and full reservation/token cleanup. It intentionally stopped before workflow submission.
• Native HF subscriber admission verified against the companion branch in dev: exhausted/no plan -> 402 hf_subscription_required; temporary native Pro -> observed hf_plan_unlimited with no free/HF usage debit; removing Pro -> 402 again. All reservations refunded, token revoked, owned plan ended and stack stopped. This intentionally stopped before upload/render/workflow/vendor work. The runner exited nonzero on a refund row-ID comparison; independent read-only verification confirmed balances and complete cleanup.
• Backend production deployment and production client audience correction remain release prerequisites. No completed render or live paid billing acceptance is claimed.

Current integration validation

Current head: 752f5308009fbf1af008d422201ca5d25c1b952f. Merged main at 5d437d5eecd65f05daa4ff451ebb85b71f88fdb9 normally, without rewriting history. The only content conflict was the generated skills manifest; regenerated it from merged sources. Main's audio-probe documentation correction and unrelated source changes remain intact. The branch retains its isolated OAuth guidance and client-bound fixtures. No authored OAuth logic or function/comment changed during conflict resolution.

Manifest freshness, 21 telemetry/parity/filter tests, CLI typecheck and every applicable commit hook passed, including Fallow with no new issues. Independent self-review found no additional issue. The preceding merge head 5910b193 also passed 65 focused CLI tests and actual hosted Test/CLI/support/Build/Typecheck and Windows render runs; that evidence is historical for this new head. Fresh hosted CI and exact-head Genesis approval are required. No live fixtures or consent were repeated.

Merge hold

James explicitly requested keeping this PR unmerged until the normal Thursday October 29, 2026 release in America/New_York. Auto-merge is off and the PR is not queued. After that release, actual public deployment of the billing backend to all three services and the independently authorized production audience correction remain required before landing. Code approval, midnight, a canary rollout, and device-stack frontend merges do not clear these gates.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 29, 2026, 8:27 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Edit accuracy: accurate 271 (base branch 271), smooth 142 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (1)

• seqplainkeys-none-pct-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true

[heygengenesis]

Verdict: REQUEST CHANGES · 2 blocker · 1 important · 0 nits · head ee7b111

• blocker: media-use setup instructions still send users to the HeyGen CLI login. skills/media-use/SKILL.md:34 tells agents to sign in with heygen auth login --oauth, and says that session carries the free allowance. After this PR, media-use resolve gives the Go helper an empty temporary HEYGEN_CONFIG_DIR, so a HeyGen CLI login has no effect and resolve keeps reporting not authenticated. The code already says hyperframes auth login (HEYGEN_AUTH_COMMAND). The direct recipes there and in references/operations.md (heygen video-agent create, heygen video create, voice clone, lipsync, ...) still run under the separate HeyGen CLI login, which bills HeyGen, not the HyperFrames subscription. State that, or route those calls through the same wrapper. The same stale "shared ~/.heygen" claim is in skills/hyperframes-cli/references/cloud.md:19,33 ("sign in with one and the other picks up the session"), skills/media-use/audio/references/{requirements,tts,bgm}.md, commands/auth/status.ts:268-269, commands/auth/status-guidance.ts:61,83, and media-use/lib/telemetry.mjs:123, which still reads the ~/.heygen user block for the distinct id.

CI triage and scope

• Branch-caused: Tests on windows-latest: engine-cli failed on both runs (40736704157, 40737616482), in the PR's new media-environment.test.ts:28: expected 438 to be 384. See the inline comment.
• Not branch-caused: Producer: unit tests renderOrchestrator.stall.test.ts failed with expected [] to deeply equal [2]. The PR touches nothing in packages/producer, and the job passed on the second CI run (40737616513). The cancelled regression and CI runs belong to the superseded first trigger. The second regression run passed.
• Checked: the env/host/client/store selection all goes through HYPERFRAMES_ENV. The refresh and revoke binding is asserted against the stored client and token endpoint. Expired or foreign OAuth no longer falls back to the saved API key, in the resolver or in heygen.mjs. Under media-use, an expired login runs anonymously, and the Go helper cannot reach ~/.heygen. I checked heygen-cli's file resolver: API key beats OAuth, its skew is 60 s, and it does not read HEYGEN_ACCESS_TOKEN. Every refreshTokens caller passes the stored refresh token.
• Pre-existing, not gating: HEYGEN_API_KEY / HYPERFRAMES_API_KEY in the environment, and a project .env for the standalone audio scripts, still outrank the stored HyperFrames OAuth and bill the API wallet. This is documented, and logout warns about it.
• Live sign-in and billing were not exercised.

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 0 nits · head 42ac7bf

All three findings from ee7b111 are fixed:

• The Windows mode assertions are guarded.
• The helper now refreshes when the token has less than 10 min left (the --wait window).
• The skill, status and telemetry text now point at the isolated ~/.hyperframes store, and direct heygen recipes are labelled as using HeyGen/API billing.

auth status no longer shows HeyGen balances as the HF balance. Required CI is green at this head, including Tests on windows-latest. The cancelled Windows render verification and PR captures runs belong to a superseded duplicate trigger. The first engine-cli job stalled in checkBrowser.test.ts and was cancelled; the second run passed. The merge gate stays as stated: backend #61702 deployed, plus dev E2E. Approval covers this SHA only.

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 0 nits · head 169f297

The delta from 42ac7bf is test-only (status-user.test.ts). The temp prefix now always contains 99, and the billing assertions are scoped to the rendered Wallet: row. The negative OAuth check isn't vacuous: it uses the same unindented label value rendering as the API-key case, which passes. Required CI is green at this head, including the flake gate on both CI runs and Tests on windows-latest. The one cancelled PR captures run is a superseded duplicate; its twin passed. Approval covers this SHA only.

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 0 nits · head f468051

Since 169f297, this head merges main 1c3fcf4 and changes two files.

• Merge resolution: checked with git show --remerge-diff. Main's HyperFrames user-ID and traits behavior is kept, and both telemetry.mjs copies (they are identical) read the isolated ~/.hyperframes[/dev] store.
• Main code: #6703's new signedInUser.ts reads through credentialPath(), so it follows the selected environment as well. No production read of HEYGEN_CONFIG_DIR or ~/.heygen remains, apart from the temporary helper directory in media-environment.ts.
• 3f0098f failures: both came from the merge and are fixed here: signedInUser.test.ts used the old HeyGen directory, and the edit-accuracy filter lacked auth/{config,errors}.ts.
• CI: required checks are green on this head, including both Windows runs. The cancelled first CI run was superseded by its duplicate, which passed.

This approval is a code verdict only. The release hold, backend rollout and production client correction gates still apply. Approval covers this SHA only.

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 0 nits · head 752f530

Since f468051, this head has two normal main merges (fa97f9d, then 5d437d5). In both, the only conflict was the generated skills-manifest.json, regenerated from the merged sources (checked with --remerge-diff). Main's incoming auth-related change is a one-line publish.test.ts assertion and doesn't interact with the OAuth fixtures. No production read of ~/.heygen / HEYGEN_CONFIG_DIR was reintroduced, apart from the temporary helper directory. Required CI is green at this head: both CI runs and both Windows runs passed. The cancelled PR captures run is a superseded duplicate.

Code verdict only. The release hold, public backend rollout and production audience correction gates still apply. Approval covers this SHA only.