Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

Document the approved fifty-cent Compass transition rollout

Barack Sokullu3ae4a2e491f9
diff --git a/docs/compass-quota-rollout.md b/docs/compass-quota-rollout.md
index e5cca2812..0be60b322 100644
--- a/docs/compass-quota-rollout.md
+++ b/docs/compass-quota-rollout.md
@@ -1,17 +1,17 @@
# Compass weekly allowance and sharing reward rollout
-Implementation spans `webbrain2` and sibling `webbrain-cloud`. The constructor default and example configuration are now **$0.375 per UTC week**, resetting Monday at **00:00 UTC**. Production activation is a separate rollout step; no production deployment was performed during implementation or PR preparation.
+Implementation spans `webbrain2` and sibling `webbrain-cloud`. The constructor default and example configuration are now **$0.50 per UTC week**, resetting Monday at **00:00 UTC**. Production activation is a separate rollout step; no production deployment was performed during implementation or PR preparation.
## Release order
-1. **Backend compatibility first.** Back up the entire usage JSON while the service is stopped or while holding its store lock. Keep `WEEKLY_FREE_USD=0.75` explicitly set in the active backend environment before releasing this backend. The new constructor default would otherwise reduce the allowance immediately. Keep that temporary override through the extension release. Ship the additive usage fields, `/usage` (`/v1/usage` alias), promotion endpoints, persistent ledger, review CLI, and telemetry first. Verify a free-quota 402 still includes the device-linked `subscribe_url`, and paid/payment-failure responses still point to the existing upgrade/account flows. Confirm the CLI and web workers resolve the same `USAGE_PATH`, and that all workers share the same filesystem lock.
+1. **Backend compatibility first.** Back up the entire usage JSON while the service is stopped or while holding its store lock. Set `WEEKLY_FREE_USD=0.50` explicitly in the active backend environment for the approved transition while clients update. The constructor default also matches $0.50. Ship the additive usage fields, `/usage` (`/v1/usage` alias), promotion endpoints, persistent ledger, review CLI, and telemetry first. Older clients retain their existing Subscribe card until they update. Verify a free-quota 402 still includes the device-linked `subscribe_url`, and paid/payment-failure responses still point to the existing upgrade/account flows. Confirm the CLI and web workers resolve the same `USAGE_PATH`, and that all workers share the same filesystem lock.
2. **Extension next.** Ship both Chrome and Firefox together. Check the three quota choices, narrow panels, keyboard focus, claim submission/status, restored conversations, and a return from checkout. Confirm an approval or provider switch leaves browser actions stopped until the explicit Continue/Retry button is selected. Confirm pending claims say manual review, approved/redeemed devices have no offer to earn again, and existing payment recovery and Plus upgrades still work. Confirm the backend returns promotion state before enabling the new experience to users.
-3. **Allowance reduction last.** After the new recovery choices are available in both stores, change the active `WEEKLY_FREE_USD` override to **0.375**. Check environment variables in the actual web-worker/service/container configuration as well as `.env`: exported variables take precedence over `.env`. Reload workers as required by the hosting setup. Query `/usage` from the running service with the extension's `X-WebBrain-Device-Id`; both `base_weekly_allowance_usd` and `weekly_limit_usd` must be `0.375`, and `next_reset_at` must be the next Monday 00:00 UTC. Verify an exhausted free device's 402 reports the same amount. Do not rely on the example file or a CLI process with a different environment.
-4. **Observe for 14 full days after activation.** Record the UTC activation time, active amount, extension versions, and expected review staffing. Review the report daily and reassess the amount after two full UTC weeks. If recovery choices are unavailable or the allowance proves too small, restore the override to `0.75` while leaving the backend ledger and extension controls in place. A rollback must preserve lifetime awards and remaining balances.
+3. **Verify the transition amount.** Check the actual web-worker/service/container environment as well as `.env`: exported variables take precedence over `.env`. Query `/usage` from the running service with `X-WebBrain-Device-Id`; both `base_weekly_allowance_usd` and `weekly_limit_usd` must be `0.50`, and `next_reset_at` must be the next Monday 00:00 UTC. Verify an exhausted free device's 402 reports the same amount and retains `subscribe_url`. Do not rely on the example file or a CLI process with a different environment. Keep the explicit $0.50 override while clients adopt the update. A later reduction to $0.375 requires a separate rollout decision after reviewing extension availability, adoption, and consumption; it is not activated automatically.
+4. **Observe for 14 full days at $0.50.** Record the UTC activation time, active amount, extension versions, and expected review staffing. Review the report daily and reassess the amount after two full UTC weeks. If recovery choices are unavailable or the allowance proves too small, restore the override to `0.75` while leaving the backend ledger and extension controls in place. A rollback must preserve lifetime awards and remaining balances.
-Local configuration inspected on 2026-10-05: neither the process environment nor the local cloud `.env` sets `WEEKLY_FREE_USD`; the effective local value is `0.375`. The production environment was not accessed or changed.
+Local configuration inspected on 2026-10-05: neither the process environment nor the local cloud `.env` sets `WEEKLY_FREE_USD`; the effective local value is now `0.50`. Production activation must be verified separately using the running web service.
-The backend now uses a stable **`USAGE_PATH.lock`** and atomically replaces the usage JSON. For the first upgrade from the old in-place writer, stop and drain **all** old web workers and review/report CLI processes before starting the new version; do not mix the two lock protocols. Confirm the store owner can create the lock and temporary files and replace the JSON on the same filesystem. Never remove the lock file while any worker is running. Keep the `0.75` override throughout this backend migration and the extension release.
+The backend now uses a stable **`USAGE_PATH.lock`** and atomically replaces the usage JSON. For the first upgrade from the old in-place writer, stop and drain **all** old web workers and review/report CLI processes before starting the new version; do not mix the two lock protocols. Confirm the store owner can create the lock and temporary files and replace the JSON on the same filesystem. Never remove the lock file while any worker is running. Keep the explicit `0.50` transition override throughout this backend migration and client adoption.
Production storage must support POSIX directory `fsync`: verify file and parent-directory syncing on the actual usage-store filesystem. Windows PHP cannot sync directory handles; its local validation covers process interruptions, while the Linux durability test exercises directory-sync failures and idempotent retries. Client telemetry is best-effort and globally capped at 10,000 retained device/day observations; excess events return `recorded: false`. Actual metered consumption and lifetime awards are independent of that telemetry cap.
@@ -57,9 +57,9 @@ php scripts/report-social-promotion.php --days=14
The report contains quota-card views, checkout opens, server-recorded claim submissions and successful grants, explicit continuation after a reward, provider switches, and subscription conversions. A conversion is counted once when a device that opened checkout is observed with a paid entitlement on `/usage`; checkout opens alone do not count as conversions. Client counts are capped per device/day and are event totals rather than unique-person counts.
-Metered consumption is recorded under the same store lock from actual completed token usage, including visual sidecars. Numeric samples use hashed device/session identifiers and retain 30 UTC days; no prompt, post body, or page content is added to these samples. Each consumption map retains at most 10,000 observations across retained dates; existing samples continue accumulating, and new keys contribute to overflow totals. Exact metered aggregates remain intact. The report discloses observation counts and overflow USD/requests in `sampling`; inspect that coverage before using the sampled distributions to change the allowance. The 14-day report shows free-session and free-device/week p50/p75/p90/p95 costs and the share exceeding $0.375. Calls without a session identifier contribute to `unattributed_usd`, so report that coverage gap. Device/week distributions use completed Monday–Sunday UTC weeks independently of the rolling event/session window. With `--days=14`, verify `device_week_window` reports two completed weeks after activation, inspect its retained overflow/untagged coverage totals, and wait until both weeks have full instrumentation. A partly expired retention-boundary week is omitted; reports shorter than seven days have no completed weekly distribution. Admission-week tags keep requests that finish after reset in their original UTC week. Lifetime claims/indexes are not subject to sample retention.
+Metered consumption is recorded under the same store lock from actual completed token usage, including visual sidecars. Numeric samples use hashed device/session identifiers and retain 30 UTC days; no prompt, post body, or page content is added to these samples. Each consumption map retains at most 10,000 observations across retained dates; existing samples continue accumulating, and new keys contribute to overflow totals. Exact metered aggregates remain intact. The report discloses observation counts and overflow USD/requests in `sampling`; inspect that coverage before using the sampled distributions to change the allowance. The 14-day report shows free-session and free-device/week p50/p75/p90/p95 costs and `fraction_over_allowance` for the active amount. It retains `fraction_over_0_375` for evaluating the previously proposed reduction. Calls without a session identifier contribute to `unattributed_usd`, so report that coverage gap. Device/week distributions use completed Monday–Sunday UTC weeks independently of the rolling event/session window. With `--days=14`, verify `device_week_window` reports two completed weeks after activation, inspect its retained overflow/untagged coverage totals, and wait until both weeks have full instrumentation. A partly expired retention-boundary week is omitted; reports shorter than seven days have no completed weekly distribution. Admission-week tags keep requests that finish after reset in their original UTC week. Lifetime claims/indexes are not subject to sample retention.
-Reassess whether $0.375 covers useful completed sessions, how many device/weeks exhaust it, how often rewards lead to explicit continuation, how many users switch providers or subscribe, and how long pending reviews take. Use actual consumption distributions and recovery/conversion behavior to decide whether to keep or raise the allowance. Do not equate views or composer opens with published posts or successful tasks.
+Reassess whether $0.50 covers useful completed sessions, how many device/weeks exhaust it, how often rewards lead to explicit continuation, how many users switch providers or subscribe, and how long pending reviews take. Use actual consumption distributions and recovery/conversion behavior to decide whether to keep or raise the allowance. Do not equate views or composer opens with published posts or successful tasks.
## Validation
diff --git a/docs/compass-quota-validation.md b/docs/compass-quota-validation.md
index 431eacd25..61320363d 100644
--- a/docs/compass-quota-validation.md
+++ b/docs/compass-quota-validation.md
@@ -7,7 +7,7 @@ Both repositories were clean before implementation. No applicable `AGENTS.md` wa
| Check | Result |
| --- | --- |
| Cloud `composer run test:promotions` | Passed accounting/concurrency, write durability, and real HTTP/CLI integration |
-| Cloud weekly usage | Passed, including `$0.375` and legacy usage aliases |
+| Cloud weekly usage | Passed, including the `$0.50` default, configured `$0.375` precision, and legacy usage aliases |
| Cloud Plus, portal subscription recovery, renewal notices | Passed |
| Cloud PHP syntax | Passed for service, promotion trait, routes, and both new CLI scripts |
| Extension `npm run test:compass-quota` | 19 tests passed across Chrome and Firefox |
@@ -55,4 +55,4 @@ Fresh Codex reviews and GitHub checks are recorded on each PR.
Browser screenshots are generated in `%TEMP%/webbrain-compass-review` (override with `QUOTA_UI_OUTPUT`). The latest complete extension log is `%TEMP%/webbrain-compass-review-npm-test.log`; the cloud aggregate log is `%TEMP%/webbrain-cloud-compass-review-check.log`. Unpacked artifacts are `build/chrome` and `build/firefox`.
-Local cloud configuration has no `WEEKLY_FREE_USD` process or `.env` override, so the inspected effective value is `0.375`. Production was not inspected or activated. Follow [the rollout checklist](compass-quota-rollout.md): backend compatibility pinned at `0.75`, both extensions, then live-worker override verification and activation at `0.375`. Reassess the actual consumption report after two complete UTC weeks.
+The approved transition changes the default to $0.50 and verifies that a configured $0.375 allowance remains exact. The consumption report compares to the active amount and preserves the $0.375 comparison field. Production deployment uses an explicit `WEEKLY_FREE_USD=0.50` override and verifies it through the live web worker; a later reduction needs a separate decision after client adoption. Follow [the rollout checklist](compass-quota-rollout.md), including writer draining and ledger backup. Reassess actual consumption and adoption after two complete UTC weeks at $0.50.