box/docs/INVITE-HANDLER.md

Invite Code + Usage Handler

bin/invite.py drives Muse.ai invite codes and usage limits through the agent browsers, exposed as box invite / box usage.

Flows

• Find (get_invite): GET /api/hatch/invite via in-page fetch (primary), falling back to the main-chat Invite popover parse (hatch-invite-friends-button -> [data-slot="popover-content"] -> Invite code revealed: XXXXXX) when the API fails.
• Redeem (redeem_invite): POST /api/hatch/invite-code/redeem {code, supportsRedemptionStatus: true} via in-page fetch. Server reasons pass through verbatim: already_redeemed, invalid, used_up, revoked, window_expired, rate_limited, unavailable, unknown.
• Usage (get_usage): Settings > General DOM read through the hatch_menu tree (dialog open/tab/text + tabs/general.py parse, adapted to the flat CLI keys). Real mouse events open the radix dock menu (hatch-dock-more; synthetic clicks do not work), then the settings_nav_click item, then the General tab.

open_settings() / click_settings_tab() are public shims over hatch_menu.dialog (single copy; see docs/HATCH-MENU.md).

Eligibility & Lifecycle (observed live, 2026-10-06)

• One redemption per account (already_redeemed).
• 48h window from joining (window_expired).
• Codes carry limited uses (used_up, e.g. 30) and can be revoked.
• Inviter rewards accrue regardless of the inviter's own redemption state (opm earned 4B from 4 redemptions while already redeemed).
• When account B redeems account A's code: BOTH accounts immediately receive 1 billion Muse tokens.

UI Quirks & Binary Attribution

• Redeem field disappearance: In Settings > General, the Redeem invite code item is only present for fresh accounts (< 48 hours, has not redeemed). Once redeemed, the field disappears completely and is replaced by the Additional tokens ticker bar (Never expires / X% used).
• Asynchronous DOM Loading: In the React/Radix UI tree, usage statistics and the redeem button render asynchronously after the dialog opens. RPA drivers must poll briefly for usage text and progress bars rather than evaluating on the first tick.

Onboarding & Feeding Pipeline (box onboard)

To feed token-deprived or blocked agents, the fleet automates onboarding of fresh client profiles:

• box onboard feed-matrix: Lists all agents ranked by composite feeding weight: Urgency (Blocked/Limit) + Work Done Over Time (cumulative messages processed) + Active Job Volume + Role Criticality.
• box onboard start <new_node> --email <client_email> [--for <agent>]: Provisions WireGuard tunnel, dedicated netns (warp-<node>), chrome-box profile, initiates headless login, and queues the top-ranked beneficiary's invite code.
• box onboard submit-otp <node> <otp>: Submits transient verification code; once the session is active, automatically redeems the queued code in Settings, granting 1B tokens to both agents, and injects operational DRIVE.
• box onboard salvage-wo <node>: Dispatches a cryptographically signed Work Order ([WO]) to the prompting sidechat.
• Loop Modulation: InputType.SALVAGE is registered in box loop strat with CRITICAL priority, 600s timeout, and 3 auto-nudges escalating to opm.

Fleet State (2026-10-06)

• 646: Unblocked! Restored via dev's redemption of REDCJ7. Currently ~1B tokens banked.
• dev: Redeemed REDCJ7, currently ~1B tokens banked.
• def: Active, 0 redemptions (A4OS1F, window expired).
• muse: ~925M tokens banked (81MDIR).
• pip: ~897M tokens banked (F4BGHN).
• opm: 3.5B tokens banked (14OGF2, 4 friends redeemed).