# Task: Integrate expiring reset-card wallet into Makelore desktop

## Identity

- Task ID: 20260908-reset-card-wallet-client-6c3e8a1f
- Mode: Feature
- Branch: main
- Worktree: D:\Datas\OthersProjects\makelore
- Base commit: 91ae7912ab15559c7fe8859974bfe1da9e4e7451
- Owner: codex
- Status: Ready for Integration

## Scope

- Add Electron Main-owned Works Square proxy routes for listing and redeeming expiring reset-card grants.
- Strictly project the public reset-card DTO before it reaches Renderer and preserve only a closed set of redemption error codes.
- Add a reset-card wallet to the existing account menu with available, expired, and redeemed states, explicit expiry, and manual redemption.
- Refresh both the reset-card wallet and authoritative Token Point V2 balance after successful redemption.
- Add focused Main route, Renderer API, component, and user-visible interaction coverage.

## Intent And Constraints

- Keep Works credentials and upstream response shaping behind the existing Host API/Main route boundary; do not add direct Renderer-to-Works requests or new IPC contracts.
- Treat Works Square `/api/billing/reset-cards` and `/api/billing/reset-cards/{card_id}/redeem` as the authority; the client must not calculate reset allowances or mutate card state optimistically.
- Operations-granted cards are manually redeemed inventory with an explicit expiry. Existing paid reset-card immediate fulfilment is unchanged and is not represented as desktop inventory.
- Allow a self-owned youth entitlement to redeem its card, but disable redemption while the current balance is family-shared; the server remains the final ownership authority.
- Derive an available card as expired when its `expires_at` is no longer in the future so stale UI cannot invite a known-invalid redemption.
- A successful or idempotently replayed redemption must refresh the card and balance authorities. Definitive failures must remain retryable by the user without inventing a new mutation identity or local success.
- Use the existing Makelore light visual system, compact account-menu disclosure, tabular dates, specific transitions, and at least 40px redemption targets.
- Preserve and do not commit the three adopted foreign task records from 20260901-20260902.

## Outcome

- Added Main-owned reset-card list/redeem routes that authenticate upstream with the existing Works token, strictly project the public card DTO, derive elapsed available cards as expired, and expose only a closed set of safe redemption errors to Renderer.
- Added typed Renderer helpers for the Host API routes without introducing direct Renderer-to-Works requests or a new IPC contract.
- Added an account-menu reset-card wallet with lazy loading, available-card count, explicit local-time expiry, available/expired/redeemed states, retry handling, and a 40px manual redemption action.
- Kept operations-granted cards separate from the existing Token Point balance rows and existing immediate paid reset-card flow.
- Prevented known-expired or family-shared-wallet redemptions in the client while retaining the server as the final authority; successful server fulfillment refreshes both the authoritative card list and Token Point V2 balance.
- Added Main route, Renderer helper, component, and Electron interaction coverage, including strict projection, safe error mapping, local expiry, shared-wallet behavior, single redemption, and post-redemption balance refresh.

## Verification

- `pnpm exec vitest run tests/unit/works-routes.test.ts tests/unit/works-square.test.ts tests/unit/sidebar-token-points.test.tsx --maxWorkers=2` — 3 files / 78 tests passed.
- `pnpm exec eslint electron/api/routes/works.ts src/lib/works-square.ts src/components/layout/Sidebar.tsx tests/unit/works-routes.test.ts tests/unit/works-square.test.ts tests/unit/sidebar-token-points.test.tsx tests/e2e/reset-card-wallet.spec.ts` — passed with no warnings or errors.
- `pnpm run typecheck` — passed.
- `pnpm run lint:check` — passed with 0 errors and the repository's 5 existing warnings in unchanged Home/Makelore files.
- `pnpm run build:vite` — Renderer, Main, Preload, and utility production builds passed; only the repository's existing Browserslist/import/chunk-size warnings were emitted.
- `pnpm exec playwright test tests/e2e/reset-card-wallet.spec.ts --repeat-each=3` — 3/3 Electron runs passed.
- `pnpm test` — 224 files / 1,952 tests passed and 2 skipped before the existing Pi real-process cold timing assertion measured 2,124ms against its 2,000ms threshold; the same file then passed 6/6 in isolation with one worker, and the separately invoked pressure test passed 1/1. This recurring unrelated timing shape is already recorded in prior project tasks and does not intersect the reset-card paths.
- `git diff --check` — passed.

## Follow-ups

- Deploy the Works Square reset-card backend and apply Alembic revision `20260908_reset_card_grants_0087` before shipping or enabling this client wallet against that environment.
- Rebuild/release Makelore together with the compatible server version, then smoke-test one Operations grant, one desktop redemption, and the resulting authoritative weekly balance refresh.

## Promotion Candidates

- During Integration, update the canonical desktop billing data-flow/current-state documentation with the Main-owned reset-card proxy boundary and account-menu wallet behavior.