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 & Missing Field Resiliency

• 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).
• Missing Entrypoint Recovery & API Fallback: If the Redeem invite code row is absent (or sub-dialog input box NativeAuthCodeBoxes fails to mount):
  1. Box polls up to 2.5s for React hydration.
  2. If still unrendered, Box automatically falls back to in-page API redemption (POST /api/hatch/invite-code/redeem).
  3. If API redemption succeeds, Box returns success transparently.
  4. If API also fails, Box records the exact server reason (already_redeemed, window_expired, etc.).
  5. Box cleanly dismisses all open modals via Escape to avoid orphaned UI state.
• Asynchronous DOM Loading & Unloaded Stats: In the React/Radix UI tree, usage statistics render asynchronously after the dialog opens. If network requests stall or quota bars fail to render, read_usage() and box usage gracefully tag the result as UNLOADED (stats_loaded: false) rather than throwing uncaught RuntimeErrors.
• DM Loopback & Transparent Agent Feedback: To keep agents in the loop without causing confusion:
  • Any missing expected field or failed redemption can trigger an automated loopback DM via box invite redeem <node> <code> --notify <sidechat> [--notify-agent <agent>].
  • Onboard and salvage pipelines automatically post diagnostic notices ([ONBOARD-SALVAGE-LOOPBACK] / [BOX-INVITE-LOOPBACK]) to the agent's task sidechat, providing clear, actionable root cause.

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).