A team that setup creates or picks gets the trial when it binds, with the email,
GitHub user and ip abuse keys. Teams that can't get one go through T3 and
Checkout.
Billing Worker:
- trials + trial_claims (migration 0005): 2 sandbox hours per new team, no card, no Stripe.
- POST /v1/billing/trial grants it (idempotent, any member); grantTrial/trialOffer exported for
the setup session. offers.trial on GET entitlements only when this caller could still claim it.
- Abuse limits: once per team, Orca user, normalized verified email, GitHub user (token claim)
and GitHub owner (POST /v1/internal/trial/github from the binding; a reused identity revokes),
disposable-domain blocklist, 3 grants per IP per day. Keys stored as SHA-256 hashes.
- Entitlement trial {includedSeconds, usedSeconds, remainingSeconds, exhausted}; metered from
usage_events, concurrency 1, never overage; trial_used_up (suspendRunning) / trial_unavailable.
- Any subscription ends the trial; unused trial hours lapse.
- e2e: trial path (grant, no Stripe customer, concurrency, metering to used up, once per user,
plan ends it) with cleanup of the run's abuse keys.
Desktop: trial_used_up / trial_unavailable classify as 'plan'; copy in billing, phone and CLI;
"Trial" badge, TrialPlanSummary in Plan & billing and the plans page strip, account menu row
"Trial · {{count}} sandbox hours left" (Choose plan for owners/admins); billingClaimTrial IPC
and claimOrcaCloudTrial() for the composer.
Usage alerts only fired on a billing read, so a team crossing 75/90/100% mid-session
wasn't alerted until a restart, a team switch or opening a billing view. Main now owns one
app-wide schedule: the hosted recipe's onReady (create and resume success) asks the main
window for a forced billing re-read, and the session registry's sync (already run on every
lifecycle change and on the existing 30 s beat) reports whether any cloud workspace is
running, which drives a 30-minute poll with no timer of its own. Requests go only to the
trusted main window so extra windows never stack reads; the per-level ledger still dedupes.
Billing's setup chain now passes the GitHub identity that Orca Cloud auth
verified from a GitHub sign-in (githubUserId, githubLogin). The install URL's
signed state carries it, and the setup URL checks it against the installation
with the App's own credentials: the user's own account, or an active org admin
(members:read installation token). A match binds with method 'idp' and skips
GitHub's separate Authorize page. Anything else falls back to the OAuth step
(A4b) as before.
- Signed out, Set up and start opens one tab. The authorize page shows the
setup account step (A2). Once the code is exchanged, the loopback holds the tab,
creates the billing setup session and 302s the same tab into the setup pages.
- Signed in, the session is created and its start URL is opened.
- IPC: orcaProfiles.cloudSetupStart / cloudSetupGet / cloudSetupLink (Copy setup
link mints a fresh one-time link).
- Renderer: cloud-setup-session.ts polls the session (2 s for 3 min, then 10 s),
keeps a snapshot for the composer and tracker, and switches the profile to the
team setup chose.
- Plans dialog: Checkout joins the open setup session. A personal account
(409 team_required) goes through setup instead, which makes or picks a team
first.
- Billing: POST /v1/cloud-setup/sessions/:id/link.
Setup session API on the billing Worker: the desktop creates a session after
sign-in and polls its steps (account, team, plan/trial, github); the setup pages
on Orca Cloud auth redeem a one-time browser ticket, bind the team (granting the
trial through a port np4-trial's module plugs into), open Checkout that returns
to the setup pages, and ask the control plane for the GitHub install URL. The
control plane flips the GitHub step via POST /v1/internal/cloud-setup/github.
Checkout now refuses personal accounts with 409 team_required: a user: plan
could never move to a team later.
- Desktop notification (title "Orca Cloud", body reuses the in-app usage sentence) when a
billing read crosses 75, 90 or 100%, once per level per account and billing period. Main
owns the ledger (userData/orca-billing-usage-alerts.json), so reloads, re-renders and
second windows never repeat it; a new period starts over. Members are never notified.
- Click opens Settings > Orca account (Plan & billing) via ui:openSettings with a target.
- The in-app usage notice (account menu, billing panel, plans page) is now owners/admins only.
- Billing panel: muted note under the Overage description that owners and admins are alerted
at 75%, 90% and 100%.
- Fixtures: account menu at 90% (admin and member), billing panel member at 90%.
- N9: orca://cloud/setup/return?session=cs_… is routed (open-url + second
instance), validated, focuses Orca and fans out to renderer listeners
(onCloudSetupReturn) so the setup session re-reads at once.
- N10: cloud_setup_step_{started,done,failed}, cloud_setup_first_sandbox and
cloud_setup_plan_chosen, enum-only, derived from the setup rows.
- X1: setup error kinds (timed_out, checkout_canceled, bank_step,
trial_unavailable, team_create_failed, wrong_account) and their actions.
- B2: billing POST /v1/billing/team-plans returns other teams' plan state with
the caller's own token; auth confirms membership from that token (no new
credential). Desktop IPC billingTeamPlans + useSwitchToPlannedTeam. The team
switch logic moves out of SidebarTeamSubmenu so the composer can reuse it.
Per design-squad on #244. The Agent API keys editor gets one muted line under the host scope choice,
'Not used in Orca Cloud. Save a key to your Orca account to use it in cloud workspaces.', instead of
changing #40303's own label.
Verified on a dev sandbox (Claude Code 2.1.319, codex-cli 0.166.0): runCommand runs as ubuntu with
HOME=/vercel (same user as orcad); `claude auth logout` and `codex logout` exist and exit 0; the
script reported {loggedOut:2,left:0}, removed both credential files and kept other ~/.claude.json keys.
With nothing configured, OpenCode picked its GitHub Copilot provider (GITHUB_TOKEN is the workspace
GitHub App stand-in: 'Authorization header is badly formatted') or OpenCode Zen (opencode.ai is not
on the egress allowlist). The VM seeding keeps both in OpenCode's disabled_providers unless the user
connected them in OpenCode (auth.json); the user's own list is kept (ledger of what Orca added).
Checked on a dev VM: the composer opens on 'Connect a provider'.