toga-ai 1.0.846 → 1.0.848

package/knowledge/1.0/apps/library/features/netsuite-suiteql-rest-shim.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-21
 owners: [dfranks, jcardinal, kyalamarthi, rgirish]
 files:
   - library/app/api/netsuite/rest.php
@@ -57,6 +57,7 @@ Field semantics (verified on the live account):
 - **Line number = `transactionline.id`, NOT `linesequencenumber`.** `tl.id` equals the REST `item[].line` value (the stable SOAP-era line key); `linesequencenumber` is physical order and re-maps/collides when SOAP-era records are edited. Verified: sales orders 106 orders / 344 lines (2019–2029, incl. edited orders with line-id gaps), invoices + cash sales 62/62. `listSales` historically resolved line via `uniquekey → REST lineUniqueKey → line`; `tl.id` gives the same answer in bulk without the per-id GET. **Re-confirmed at scale 2026-08-27:** the two columns diverge on **2,061 of 4,387** lines (~47%), and `Forecast.OpenOrderItems.lineNumber` (which stores REST `$line->line`) matched `transactionline.id` on **99 of 99** randomly sampled prod rows plus all 7 multi-root orders, with zero join misses. So keying a NetSuite ↔ Forecast line join on `linesequencenumber` silently mismatches about half the book — always join on `transactionline.id`.
 - **ShipItem lines have `costestimate = NULL`** (100% of 42K+ lines, 2025–26). In any profit expression `SUM(-foreignamount + costestimate)`, a NULL cost makes the whole term NULL and SQL **drops the row from the SUM** — so shipping *revenue* still counts but shipping *profit* does not, silently understating NS profit. Always `NVL(tl.costestimate, 0)`. (Caused a fake $663K "gap" in the audit tools — see the reconciliation doc.)
 - **Cash refunds & credit memos carry extra COGS/inventory lines.** SuiteQL `transactionline` with `mainline='F' AND item>0` returns, per item, the customer line **plus** a `CUSTOMERRETURN` and an `ASSET` posting (all `item>0`), which REST's `item[].items` sublist omits. They are distinguished by **`tl.iscogs = 'T'`** (and `accountinglinetype` IN `CUSTOMERRETURN`/`ASSET`). Filter **`tl.iscogs = 'F'`** to get exactly the customer-facing lines. Invoices/cash sales do not have this (0 extra lines). Without the filter, bulk imports duplicate refund/memo lines.
+- **⚠ `listSales()` takes a `$recordTypes` allowlist — pass `RECORD_TYPE_*` CONSTANTS, never raw SuiteQL codes (2026-09-21).** `listSales(...)`'s trailing `array $recordTypes` **defaults to all four** `RECORD_TYPE_INVOICE`/`_CASH_SALE`/`_CASH_REFUND`/`_CREDIT_MEMO`, which the **forecast import** (`worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php`, `periodic_forecast_discrepancy_fix.php`) relies on. `listSales` maps each constant to its SuiteQL code internally (`RECORD_TYPE_INVOICE`→`CustInvc`, `_CASH_SALE`→`CashSale`, `_CASH_REFUND`→`CashRfnd`, `_CREDIT_MEMO`→`CustCred`) and **throws on an unknown/empty type**. The **togasupply sync passes `[RECORD_TYPE_INVOICE]` — INVOICES only** — because a credit memo's `createdFrom` is the invoice it credits (not a sales order) and dead-ended `syncInvoiceFromNetsuite`; see the [per-client-sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
 - **Sign conventions are per-type and self-consistent.** SuiteQL returns `foreignamount`/`quantity`/`costestimate` **negative for invoices & cash sales, positive for credit memos & cash refunds**. A uniform `-foreignamount` therefore yields **positive** revenue for invoices and **negative** for reversals — the agreed Forecast2 convention. Do NOT also apply a per-type factor (it double-negates reversals back to positive). The shim flips `amount = -foreignamount`, `costEstimate = -costestimate`.
 - **⚠ `->holdInvoice` on a sales-order shim is NOT a native NetSuite field — it is normalised from the custom checkbox `custbody_asi_hold` (internal id 4082), and that field is SHARED by all clients.** NetSuite REST exposes no top-level `holdInvoice`. The `"asi"` prefix is **Agilant Solutions Inc** (the company), *not* a client prefix — do not read it as client-specific. The read lives **inside the shim**, in all three fetch paths: `buildSalesOrderShims()` (~L533, feeding both `listSalesOrders()` and `fetchSalesOrderByIdFull()`) and `fetchSalesOrderById()` (~L1537), so callers such as `App_Api_Toga2::isTransferOrder()` read an already-normalised boolean. (An earlier version read `$nsOrder->holdInvoice` in the caller with a `custbody_hold_invoice` fallback — the wrong field name; commit `07c31e24`, 2026-08-19, found the real one and moved the read down here.) `worker/crons/toga2/compass/edi/2_create_so_netsuite.php` **writes** the same field. **⚠ The SOAP client `library/app/netsuite.php` never sets `holdInvoice` at all**, so any detection that depends on it (e.g. the `zero_dollar_hold` transfer-order mode — see [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)) is **silently always-false** on a SOAP path. Verified not a live risk: the togasupply engine calls `App_Api_Netsuite_Rest::` on every sales-order/receipt/fulfillment path.
 - **`createdFrom` is not a usable SuiteQL column.** `transaction.createdfrom` is **always NULL** in SuiteQL (26/26). It is recoverable from `previoustransactionlinelink.previousdoc` excluding `previoustype = 'Opprtnty'` (an invoice links to both its SO and its opportunity; REST's `createdFrom` is the SO). **But this is non-deterministic for multi-link transactions** (credit memos return several non-Opprtnty `previousdoc` rows in arbitrary order) — two runs can pick different values. REST `createdFrom` (per-id GET) is the only deterministic source. Treat the link table as best-effort, not authoritative.
@@ -93,6 +94,9 @@ Field semantics (verified on the live account):
 - Field availability varies by NetSuite account **and** record type — probe the live account before assuming a column/relationship exists.
 - **`App_NetSuite::getCustomFieldValue()` (`library/app/netsuite.php`) must be warning-safe.** 1.0 runs on PHP 7.2 in an unguarded path, so any PHP warning → `exit()` (kills the cron). It was hardened 2026-08-27 with `?? []` / `?? null` guards on the custom-field-list traversal. Keep that discipline when touching it.
 
+## Change history
+- 2026-09-21 — `listSales()` gained a `$recordTypes` allowlist param (defaults to all 4 for the forecast import); callers pass `RECORD_TYPE_*` constants, not raw SuiteQL codes; throws on unknown/empty. Lets the togasupply sync request INVOICES only. (jcardinal)
+
 ## Related
 
 - `netsuite-suiteql-api-reference.md` — the broad API reference (auth, SuiteQL mechanics, table schemas, type/status codes, custom-field map, performance) these semantics sit on top of.

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-21
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -163,7 +163,7 @@ Signature takes `$integrationType` (`TICKETS` or `REPAIR_ORDERS`) plus **seven i
 ## Gotchas
 
 - **A 2.0 GET silently TRUNCATES a nested child collection — never trust a single response for a count.** When you read a parent with a nested `hasMany` collection in one GET, api2 can return the collection **partial** (observed: a fulfillment's nested `itemFulfillmentItemUnits` came back **45 of 70**) with no error and no obvious signal — so any verification that counts off the nested array is silently wrong. **Read the collection flat and fully paginated** (query the child resource directly with the universal `meta->nextPage` loop) and take counts from **`meta.totalRecordCount`**, not from a single nested response. Surfaced building the NYCHH fulfillment asset-tag verifier (`worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php`). **Confirmed again on the fulfillment reconcile (2026-09-13):** the `salesOrderItems` nested collection truncated at **25**, and a fulfillment's `itemFulfillmentItemUnits` re-created 25,766 links for 1,192 real units. The reconcile now reads both flat + fully paginated via two new private helpers, `getItemFulfillmentItemUnitsByItemFulfillmentUuid()` and `getSalesOrderItemsBySalesOrderUuid()` (`recordsPerPage` 1000, page-cap 500, `nextPage ?? null`) — detail on the [per-client sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
-- **🔐 Hardcoded credentials.** Every client's `CLIENT_UUID_*`, `API_UUID_*`, and `API_SECRET_*` (plus the "True Workers" master keys) are committed as plaintext class constants at the top of `toga2.php`. Treat them as **compromised-if-leaked**; do not reproduce the values in the KB, tickets, or logs. Long-term they should move to config/SSM. (Observed 2026-06-23.)
+- **🔐 Hardcoded credentials.** Every client's `CLIENT_UUID_*`, `API_UUID_*`, and `API_SECRET_*` (plus the "True Workers" master keys) are committed as plaintext class constants at the top of `toga2.php`. Treat them as **compromised-if-leaked**; do not reproduce the values in the KB, tickets, or logs. Long-term they should move to config/SSM. (Observed 2026-06-23.) **⚠ Also (found 2026-09-21, NOT fixed): a committed JWT (a dev/NYCHH token) sits inline at `library/app/api/toga2.php:641`, inside `App_Api_Toga2::send()` — the live sync call path.** Pre-existing, not introduced this session. **Rotate the token and delete the line;** record its location only, never the value.
 - **Two unrelated `sync_togasupply_<client>.php` families.** Files under `worker/crons/toga2/netsuite/` are the **NetSuite supply importer** (`require` the common engine). Files under `worker/crons/toga2/<client>/` (e.g. `aig/`, `wje/`) are this **bridge** (`syncWithToga`/`syncWithTogadesk`). Same filename, different integration, different parameter keys — they coexist harmlessly. Confirm which folder before editing.
 - **`syncWithToga` and the bridge build SQL by hand** with `App_Database::sqlEscape()` rather than the `App_Model` layer; follow the surrounding escaping discipline when modifying.
 - **Per-record error isolation** in the TOGaDesk sync is via `try/catch` → `\Sentry\captureException`; a thrown exception elsewhere (transport, checkpoint read) still aborts the whole run.
@@ -179,6 +179,9 @@ Signature takes `$integrationType` (`TICKETS` or `REPAIR_ORDERS`) plus **seven i
 - **This logic IS testable without a database — and there is a harness.** `App_Database::sqlEscape()` needs **no DB connection** (pure `str_replace`), so the email transform can be exercised statically. The TRUE-79401 transform is inlined in the DB-writing `private static syncContactToToga1Customer()`, so the harness **mirrors** it and guards against drift by asserting the production statements verbatim — see [static no-DB regression harness](../../test/features/static-no-db-regression-harness.md). **If you edit those 5 statements, the harness will refuse to report until it is updated.** The clean fix if you are already in there: extract the transform to a `public static` helper so the mirror disappears.
 - **Pre-existing (low severity, out of scope): a raw-vs-escaped comparison causes a redundant UPDATE every sync.** At the update path (~line 8584) `syncContactToToga1Customer` compares `$existingCustomer['emailAddress'] !== $emailAddress` — the DB value from `App_Database::fetchRow()` is **unescaped**, while `$emailAddress` has already been through `App_Database::sqlEscape()`. For any value containing `'`, `"` or `\` the two can **never** compare equal, so that column is rewritten on **every** run. Same pattern applies to `businessName` and `phoneNumber` just above. **Predates TRUE-79401**, is a redundant write (not data loss), and was deliberately left out of that ticket's scope — recorded here so a future reader knows it is known.
 
+## Change history
+- 2026-09-21 — Recorded a pre-existing committed JWT (dev/NYCHH token) at `toga2.php:641` inside `send()` (the sync call path); flagged to rotate + delete, location-only. (jcardinal)
+
 ## Related
 
 - [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md) — the importer that uses this class's transport and `*FromNetsuite()` methods.

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-18
+updated: 2026-09-21
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -834,10 +834,10 @@ then at header level:
 Prod check: 391 rows TO-side, 293 SO-side, **0 with both, 0 with neither**.
 
 **It throws — never skips — on:** more than one SalesOrder for the NetSuite id; a TO with no
-lines; an SO line with no matching TO line; a line carrying `InvoiceItems` (**`InvoiceItems` has no
-`transferOrderItemId`**, so they physically cannot be moved); or any bridge whose existence check
+lines; an SO line with no matching TO line; or any bridge whose existence check
 returns no `totalRecordCount` (see the ACL shape below). Consistent with the 2026-08-27 fail-loud
-policy.
+policy. **A stale transfer-order Invoice no longer freezes the run — it is now DELETED up front
+(2026-09-21, below);** the old per-line `InvoiceItems` throw is kept only as a safety net.
 
 **Bridge direction is PO-FIRST, confirmed from NYCHH data rather than guessed.** The naming rule is
 `<source>_<created from it>`. `Client_Nychh` populates `PurchaseOrderItems_TransferOrderItems` (98
@@ -922,6 +922,56 @@ actually have to write code for** — the schema alone would have sent us after
 | `PurchaseOrders_TransferOrders` | 17 → **104** |
 | `PurchaseOrderItems_TransferOrderItems` | 28 → **163** |
 
+#### ⚠ A stale transfer-order Invoice froze SALES_ORDERS — the retirement now DELETES it up front (fixed + deployed + prod-verified 2026-09-21, NYCHH)
+
+The retirement's old "throw on any `InvoiceItems`" rule froze NYCHH `SALES_ORDERS` at `1-RUNNING`
+(`Logs.Issue` **813**, `clientId 3`). NetSuite order **4680233** (number **172445**) was reclassified
+`SalesOrder`→`TransferOrder`; the stale `SalesOrder` **65** carried `Invoice` **297781** (id **1143**).
+`Invoices`/`InvoiceItems` have **no `transferOrderId`/`transferOrderItemId`**, so the retirement could
+not move them and threw *"resolve manually"* every run.
+
+**Team decision (jcardinal): a transfer-order's invoices are NOT imported, so a stale one is deleted,
+not preserved.** New `private static deleteStaleTransferOrderInvoicesForSalesOrder()` runs **first** in
+the retirement (before the line/header moves):
+
+- Deletes, in FK order, the stale TO invoice's **`InvoiceItems` → `InvoiceTrackingNumbers` → the
+  `Invoice` header** — both children are FK **RESTRICT**, so children first.
+- `Invoices` has **no soft-delete/void flag**, so it is a **hard delete**.
+- **Throws (refuses)** if the invoice also bills a **different** SalesOrder (a shared invoice) — never
+  deletes another order's billing.
+- The old per-line `InvoiceItems` throw is kept as a **safety net** for anything the up-front delete
+  didn't clear.
+- All GETs use `recordsPerPage` 1000 + `isset($meta->totalRecordCount)` guards; fail-loud preserved.
+
+Reviews: php-reviewer clean, cso SAFE TO SHIP, cto AGREE (cto caught the second FK child,
+`InvoiceTrackingNumbers`). **Verified prod:** SalesOrder 65 + Invoice 1143 deleted, TransferOrder 1929
+kept, `NETSUITE_EXECUTION_MODE_SALES_ORDERS` `1-RUNNING → 1-IDLE`, cursor advanced past `…|4680233`.
+
+#### ⚠ The togasupply sync imports INVOICES ONLY — a credit memo froze INVOICES (fixed + deployed + prod-verified 2026-09-21, NYCHH)
+
+NYCHH `INVOICES` froze at `1-RUNNING` (`Logs.Issue` **804**) because `syncInvoiceFromNetsuite` refused a
+**credit memo** (NetSuite **4446850**, type `CustCred`). A credit memo's `createdFrom` is the **INVOICE
+it credits, not a sales order** — chain: credit memo `4446850` → invoice `176645` (`CustInvc`) → sales
+order `2603333`. `syncInvoiceFromNetsuite` only resolves `createdFrom` as a sales/transfer order or
+RtnAuth, so a credit memo dead-ends and throws forever.
+
+**Root cause: the INVOICES header fetch was pulling four transaction types.** `App_Api_Netsuite_Rest::listSales()`
+returned `CustInvc`, `CashSale`, `CashRfnd`, `CustCred`; credit memos + cash refunds were never in scope
+for the togasupply sync. **Team decision (jcardinal): the togasupply sync imports INVOICES ONLY.**
+
+- **Fix (worker):** `common_sync_togasupply.php` (INVOICES section, ~L978) now calls `listSales()` with
+  `[App_Api_Netsuite_Rest::RECORD_TYPE_INVOICE]`.
+- **Fix (library):** `listSales()` gained a trailing `array $recordTypes` param defaulting to all four
+  `RECORD_TYPE_*` constants (so the **forecast import** —
+  `worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php` +
+  `periodic_forecast_discrepancy_fix.php` — is unaffected via the default). Callers pass **`RECORD_TYPE_*`
+  constants, never raw SuiteQL codes**; `listSales` maps constant→code internally and **throws on an
+  unknown/empty type**. Detail on the [SuiteQL/REST shim](../../library/features/netsuite-suiteql-rest-shim.md).
+
+php-reviewer clean (additive; forecast callers unaffected), sql-reviewer SAFE TO MERGE (allowlist
+mapping, no injection). **Verified prod:** `NETSUITE_EXECUTION_MODE_INVOICES` `1-RUNNING → 1-IDLE`
+(window still 1s; self-heals ×3 from 2024-02-22).
+
 ### ⚠ TWO code paths create `PurchaseOrderItems` — only one stamped `fulfillmentType` (fixed 2026-09-17)
 
 `fulfillmentType` was stamped by `syncPurchaseOrderFromNetsuite()` (from the order-level
@@ -1283,7 +1333,9 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   **`lastmodifieddate`, NOT `trandate`** — `App_Api_Netsuite_Rest::listSales()` defaults
   `$dateField='lastmodifieddate'` and the engine calls it without the 4th arg. So a backdated
   `trandate` is irrelevant to whether an invoice imports, and a just-modified invoice still won't
-  import until it is >24h old (the upper-bound cap).
+  import until it is >24h old (the upper-bound cap). **The engine also now passes
+  `[RECORD_TYPE_INVOICE]` (INVOICES only — 2026-09-21); credit memos / cash refunds are out of scope
+  and a credit memo threw here — see the credit-memo freeze subsection above.**
 - **⚠ DEPLOY ORDER: the cursor-rename migration MUST run on EVERY client DB before the worker/library
   deploy — there is NO old-key fallback in code.** `Client/2026-09-02b - NetsuiteSyncCursorRename.sql`
   renames `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` → `NETSUITE_LAST_SYNC_CURSOR_<SECTION>`. If the code
@@ -1995,6 +2047,15 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   [NetSuite Sync Alert Monitor](../../library/features/netsuite-sync-alert-monitor.md).
 
 ## Change history
+- 2026-09-21 — **Two NYCHH sync freezes fixed, deployed (library + worker together) and prod-verified.**
+  (1) SALES_ORDERS froze (`Logs.Issue` 813) on a stale transfer-order invoice the retirement couldn't
+  move (`Invoices` has no `transferOrderId`). New `deleteStaleTransferOrderInvoicesForSalesOrder()`
+  deletes the stale TO invoice up front — `InvoiceItems` → `InvoiceTrackingNumbers` → header (both FK
+  RESTRICT), hard delete (no void flag), throws only if the invoice also bills a different SalesOrder;
+  team decision that TO invoices aren't imported. (2) INVOICES froze (`Logs.Issue` 804) on a credit
+  memo whose `createdFrom` is the invoice it credits, not a sales order; the sync now imports INVOICES
+  only — `listSales()` gained a `$recordTypes` param (defaults to all 4 for the forecast import) and the
+  engine passes `[RECORD_TYPE_INVOICE]`. Both verified `1-RUNNING → 1-IDLE`. (jcardinal)
 - 2026-09-18 — **Three corrections and one deployed fix.** (1) The stale-SalesOrder retirement
   method shipped **missing four FK dependencies** and failed on each in turn: `ItemFulfillments`
   **header** `salesOrderId` (all 218 orders), the **upstream** `PurchaseOrders_SalesOrders` header

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -13,12 +13,13 @@
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Per-tenant/language/role JSON config that drives almost all commerce UI text, fields, and login fetches (Layer A global + Layer B FIELDS registry); open before |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | Expedited shipping options are config-gated to show only when the cart holds a computer kit; open when touching cart shipping-method options or the gate config. |
 | [Filter / Search-Results Page & the Two Search Entry Points](features/filter-search-results-page.md) | Two search entry points (Home in-place vs Header→/filter) render the same card via different code paths and FIELDS files; open for any search-results or kit-car |
-| [Header "Order for <Name>" dropdown + the pending-pick hand-off to the cart](features/header-order-for-dropdown.md) | Header pill that lets a buyer pick who they are ordering for from any page, and the in-memory store that hands that pick to the cart's order-for cascade; open b |
+| [Header "Order for <Name>" dropdown + the persisted pick handed to the cart](features/header-order-for-dropdown.md) | Header pill that lets a buyer pick who they are ordering for from any page, and the persisted store that hands that pick to the cart's order-for cascade; open b |
 | [Inactive-item purchase gating (standalone lines only — kits are exempt by design)](features/inactive-item-purchase-gating.md) | `Items.isActive = 0` blocks standalone purchase but means something different on kit components, so the gate keys on purchase CONTEXT not the flag; open when to |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | How the hostname resolves the tenant and fans out to API base URL, theme (CSS variables), and fields; open when adding a tenant or debugging wrong-theme/wrong-A |
 | [Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel](features/order-submit-sync-sequencing.md) | The item sync must finish before the header sync on order submit, or concurrent line deletes race a depth-3 response into an uncaught api2 500; open when touchi |
 | [Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)](features/shipping-cost-waiver-gating.md) | Config-driven cost waiver making Standard Ground free for a bare computer kit (Compass USA); open when touching shipping cost gates or the Compass free-freight |
 | [Storefront persona gating — the Home page's kit / category / item counts, and the persona switcher](features/storefront-persona-gating-and-home-counts.md) | What a storefront user sees on the Home page is decided **in the front end**, from `user._personaIds`, not by the API's ACL. |
+| [View-as another user — parked admin tokens & return-to-self](features/view-as-session-tokens.md) | How an admin impersonates another user and gets back: the delegated token pair, the parked admin pair in localStorage, and the return path. |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How toga2-commerce builds/deploys on AWS Amplify (one dynamic amplify.yml, branch-per-env, per-env blox channel); open to deploy, stand up an env, resolve a blo |
 | [Cart e2e — Cypress conventions & harness (toga2-commerce)](workflows/cypress-testing.md) | Cypress e2e conventions + the Cart harness (cartV2.cy.ts) for toga2-commerce; read before adding any spec here, and note it doubles as the config-cart refactor |
 | [Diagnosing ERR_HTTP2_PROTOCOL_ERROR (one client fails, everyone else is fine)](workflows/http2-protocol-error-diagnosis.md) | Diagnose ERR_HTTP2_PROTOCOL_ERROR when one client/network fails a togacommerce tenant but everyone else works (usually the client's TLS-inspection proxy, not ou |

package/knowledge/2.0/apps/toga2-commerce/architecture.md

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: architecture
 status: active
-updated: 2026-09-17
+updated: 2026-09-21
 owners: ["apeterson", "tcox"]
 files:
   - src/main.tsx
@@ -15,6 +15,7 @@ files:
   - src/contexts/AuthContext.tsx
   - src/contexts/helpers/getLoginSettings.ts
   - src/api/axiosInstance.ts
+  - src/api/sessionTokens.ts
   - src/stores/
   - src/themeConfig/ThemeContext.tsx
   - src/fieldsConfig/index.ts
@@ -27,6 +28,7 @@ related:
   - 2.0/apps/toga2-commerce/workflows/amplify-build-and-deploy.md
   - 2.0/apps/api2/architecture.md
   - 2.0/apps/toga2-commerce/features/filter-search-results-page.md
+  - 2.0/apps/toga2-commerce/features/view-as-session-tokens.md
 ---
 
 Whole-repo map of the toga2-commerce React storefront (bootstrap, routing, MVVM pages, state, API, multi-tenant resolution); open when working anywhere in this repo.
@@ -124,7 +126,7 @@ Most use the `persist` middleware (localStorage). Verified files:
 | `useEditOrderZu` | "Edit existing order" mode flag + original snapshot |
 | `useEditOrderUuidStore` | UUID of the order being edited |
 | `useSelectedUserZu` | "Order for" user selected in cart |
-| `useOrderForZu` | Header "order for" **pending pick** handed to the cart cascade — **in memory only, never `persist`ed** |
+| `useOrderForZu` | Header "order for" pick — **persisted** (`order-for-zu`), owner-scoped: always read via `getOrderForUserFor(pick, ownerUuid)` (see header-order-for-dropdown) |
 | `useReturnOriginalUserFromViewAsStore` | "View as another user" return-to-self tracking |
 | `useEmailOptionsStore` | Notification CC email options (see cart-notification-emails) |
 | `useBundleBuilderZu` | Bundle-builder wizard selections |
@@ -146,7 +148,8 @@ Most use the `persist` middleware (localStorage). Verified files:
 - **Transaction id:** a request interceptor stamps every call with `params.transactionId = uuidv4()`.
 - **Auth token:** a second request interceptor attaches `Authorization: Bearer <token>` — using the stored `accessToken` if a `user` exists in localStorage, otherwise fetching a **public token** via `POST {baseURL}/auth/public`.
 - **1 ms delay interceptor:** a third request interceptor `await delay(1)` before sending.
-- **401 handling:** response interceptor attempts `POST {baseURL}/auth/refresh` (Bearer refresh token) once (`_retry`), retries the original request on success, else calls `performLogout()` (clears all auth + cart + `commerce` cache keys and redirects to `/`).
+- **401 handling:** response interceptor attempts `POST {baseURL}/auth/refresh` (Bearer refresh token) once (`_retry`), retries the original request on success, else calls `performLogout()` (clears all auth + cart + `commerce` cache keys and redirects to `/`). The refresh is **single-flight** (one module-level promise) and **identity-bound** — it returns `null` if `localStorage.refreshToken` changed while in flight, so it cannot overwrite a just-minted delegated pair.
+- **Token storage lives in `src/api/sessionTokens.ts`** (host from `src/api/apiBaseUrl.ts`). Besides `accessToken` / `refreshToken` it owns **`originalAuthTokens`** — the admin's own pair parked during view-as and restored on return; `/auth/encrypted` is never called to re-mint. See [view-as-session-tokens](features/view-as-session-tokens.md).
 - Failures are reported to **Sentry** with `errorType: "API"` tags.
 
 The backend (`api2`) returns the standard 2.0 envelope (`success`/`data`/`errors`; see api2 arch); generic CRUD helpers live in `src/api/genericApi.ts` (paginated `getData`, `saveData`, `updateData`, `deleteData`, optional `?depth=-1` for nested responses).

package/knowledge/2.0/apps/toga2-commerce/features/header-order-for-dropdown.md

@@ -1,17 +1,16 @@
 ---
-title: Header "Order for <Name>" dropdown + the pending-pick hand-off to the cart
+title: Header "Order for <Name>" dropdown + the persisted pick handed to the cart
 framework: "2.0"
 repo: toga2-commerce
 project: TOGa Commerce
 client: shared
 type: feature
-status: draft
+status: active
 updated: 2026-09-17
 owners: [tcox]
 files:
   - src/components/OrderForDropdown/OrderForDropdown.tsx
   - src/components/OrderForDropdown/useOrderForDropdownViewModel.ts
-  - src/components/OrderForDropdown/types.ts
   - src/stores/useOrderForZu.ts
   - src/components/Header/Header.tsx
   - src/pages/Cart/view/cartForm/EditCart.tsx
@@ -25,77 +24,81 @@ related:
   - 2.0/apps/toga2-commerce/features/client-fields.md
   - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
   - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+  - 2.0/apps/toga2-commerce/features/view-as-session-tokens.md
   - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
 ---
 
-Header pill that lets a buyer pick who they are ordering for from any page, and the in-memory store that hands that pick to the cart's order-for cascade; open before touching the header pill, `useOrderForZu`, or the cart `orderFor` field.
+Header pill that lets a buyer pick who they are ordering for from any page, and the persisted store that hands that pick to the cart's order-for cascade; open before touching the header pill, `useOrderForZu`, or the cart `orderFor` field.
 
 ## Summary
 
-TRUE-81851. Before this, "order for someone else" existed **only** on the cart form. The header now renders an **"Order for <Name>"** pill (next to the logo on desktop, inside the mobile `SlideMenu`) that sets the same pick from any page. The header does **not** run the order-for cascade — it parks the pick in a new in-memory Zustand store and the **cart stays the single owner** of the cascade.
+TRUE-81851 (pill) + TRUE-81852 (persistence). Before this, "order for someone else" existed **only** on the cart form. The header now renders an **"Order for <Name>"** pill (next to the logo on desktop, inside the mobile `SlideMenu`) that sets the same pick from any page. The header does **not** run the order-for cascade — it stores the pick and the **cart stays the single owner** of the cascade.
 
-**Status: built on branch `TRUE-81851` (cut from `_production`), staged, not committed or merged.** The Cypress spec type-checks but was never run.
+**The pick is sticky.** Developer requirement: *"Order for needs to be persistent once chosen until the user changes it back to themself or logs out."* The store is persisted to localStorage and survives order submit, edit-order exit, view-as return, and page reload.
 
-**Per-role, per-tenant gated.** Copy and the on/off switch live in `HEADERFIELDS.json` under a new `orderFor` key, Compass USA only: `isEnabled` true for ADMIN / MANAGER / SUPERUSER, false for USER. Compass Canada and Quad have no key, so the component renders nothing (see gotchas).
+**Per-role, per-tenant gated.** Copy and the on/off switch live in `HEADERFIELDS.json` under an `orderFor` key, Compass USA only: `isEnabled` true for ADMIN / MANAGER / SUPERUSER, false for USER. Compass Canada and Quad have no key, so the component renders nothing (see gotchas).
 
 ## How it works
 
 ### 1. The pill (`src/components/OrderForDropdown/`)
 
-MVVM split: `OrderForDropdown.tsx` (view), `useOrderForDropdownViewModel.ts` (state + queries), `types.ts`, `index.ts`. Rendered from `src/components/Header/Header.tsx`; hidden in edit-order mode.
+MVVM split: `OrderForDropdown.tsx` (view), `useOrderForDropdownViewModel.ts` (state + queries), `types.ts`, `index.ts`. Rendered from `Header.tsx`; hidden in edit-order mode.
 
 - Trigger label: **"Order for Myself"** when ordering for yourself, else **"Order for <Name>"**.
-- Styling matches the Figma export: 18px/12px padding, radius 8, white, **no border in the base state**; a teal `#00B9A8` 1px outline + inset glow `rgba(64,203,190,0.20)` on hover, when open, and when someone other than the signed-in user is picked (`data-active="yes"`).
-- Icons are the **exact Figma SVG paths inlined** (24x24 user, 12.64x6.82 chevron) — not FontAwesome.
+- Teal `#00B9A8` outline + inset glow on hover, when open, and when someone other than the signed-in user is picked (`data-active="yes"`). Icons are the inlined Figma SVG paths, not FontAwesome.
 - Menu: search box → yourself first as **"<Name> (Myself)"** → the user list → **Load more** past 100. Check mark on the current pick. `aria` listbox/option roles, Escape closes and returns focus to the trigger, outside click closes.
 - Copy keys under `orderFor`: `isEnabled`, `label`, `searchPlaceholder`, `myselfLabel`, `loadingMessage`, `noOptionsFoundMessage`, `loadMoreLabel` — in all four COMPASS/ENGLISH role files.
 
 ### 2. There is no "delegation" API — it is the cart's own user list
 
-Verified 2026-09-17 across `toga2-commerce`, `api2`, `_underscore`, `dbchanges2` and the client-sandbox + prod databases (`%elegat%`): **no delegation endpoint or table exists.** api2's `/auth/delegator` is the view-as token, unrelated.
+Verified 2026-09-17 across `toga2-commerce`, `api2`, `_underscore`, `dbchanges2` and the client-sandbox + prod databases: **no delegation endpoint or table exists.** api2's `/auth/delegator` is the view-as token, unrelated (see [view-as-session-tokens](view-as-session-tokens.md)).
 
-The list is the same `GET /users` the cart already uses, via `getUserOptions()` / `getSearchValuesFromAdvancedInput()` in `src/pages/Cart/api/CartApi.ts`:
+The list is the same `GET /users` the cart uses, via `getUserOptions()` / `getSearchValuesFromAdvancedInput()` in `src/pages/Cart/api/CartApi.ts`:
 
 - **Admins** get all active users; server-side search when `CARTPAGE settings.isSearchAnyoneEnabled`.
 - **Supervisors** get their direct reports through the `Users@supervisor` join, filtered locally.
-- Field lists come from the per-tenant `CARTPAGE.ts` (`getUserOptionsFields`, `getSearchValuesFromAdvancedInputFields`), read through `useAssignClientFields(fieldKey, language, user).fields.CARTPAGEFIELDS`.
+- Field lists come from the per-tenant `CARTPAGE.ts`, read through `useAssignClientFields(fieldKey, language, user).fields.CARTPAGEFIELDS`.
 
 Hook queries: `useInfiniteQuery(["orderForDelegationList", user.uuid, fieldKey])` in pages of 100, and `useQuery(["orderForDelegationSearch", user.uuid, fieldKey, text])` debounced 400 ms with a 3-character minimum.
 
-### 3. The hand-off — `useOrderForZu` (decided, CTO-reviewed)
+### 3. `useOrderForZu` — persisted, owner-scoped
 
-The cart owns the cascade: `EditCart.tsx` watches the react-hook-form field `orderFor`, fetches the full user, then sets the sales-quote contact, manager name, cost center and notification emails, and stores the full user in `useSelectedUserZu`. The header **must not duplicate that** (~100 lines) and **must not write `useSelectedUserZu` directly** — the cascade needs the *previous* value and a *full* user object.
+`src/stores/useOrderForZu.ts` uses Zustand `persist` with localStorage key **`order-for-zu`**. Stored shape `{ uuid, name, email, ownerUuid }`, where `ownerUuid` is the **signed-in user's** uuid at pick time. Picking yourself is stored too, so the cart knows to reset.
 
-`src/stores/useOrderForZu.ts` instead holds a hand-off only:
+- `getOrderForUserFor(pick, ownerUuid)` returns the pick **only** when `pick.ownerUuid === ownerUuid`. A different login, or a view-as target, never inherits it. A stale pick (ownerUuid mismatch) is cleared on cart mount.
+- **Cleared only by:** picking yourself in the header · the cart's clear-user action (`CartPage.handleClearUser` → `clearOrderForUser()`) · logout (`AuthContext.logout`).
+- **Kept across:** order submit (`useSubmitOrder.ts`, `createNewSalesOrderSubmit.ts`), edit-order exit (`exitEditOrderModeGlobalSyncReset.ts`), view-as return (`AuthLayout.returnToYourViewOnClick`), and full page reload. The clears that used to live in those four places were removed.
 
-- `pendingOrderForUser: { uuid, name, email, ownerUuid } | null`, **in memory — deliberately no `persist`.** Every flow between a pick and the cart (view-as, login, 401 refresh failure, submit) reloads the page, and the pick must not outlive that.
-- `ownerUuid` is the signed-in user who made the pick. `getPendingOrderForUserFor(pending, ownerUuid)` returns `null` for anyone else, so a view-as switch or a new login can never inherit someone else's pick.
-- `EditCart.tsx` applies the pick to `orderFor` as **"Name (email)"** — the exact label shape the cart's own input produces — then clears the store.
-- An `appliedHeaderPickRef` is set **before** `setValue` and checked **both before and after** the mount seed's `await fetchUserByContactUuid(...)`, so a pick made while that fetch is in flight is not overwritten by the saved contact.
-- Header display order: pending pick (newest) → `useSelectedUserZu.selectedUser` → self.
+### 4. Header ↔ cart sync
 
-**Cleared on:** logout (`src/contexts/AuthContext.tsx`), order submit (`src/pages/OrderDetails/hooks/useSubmitOrder.ts` `clearAllCartStores` and `helpers/createNewSalesOrderSubmit.ts`), cart "clear user" (`CartPage.tsx` `handleClearUser`), leaving view-as (`src/components/AuthLayout/AuthLayout.tsx` `returnToYourViewOnClick`), and leaving edit-order mode (`src/utils/exitEditOrderModeGlobalSyncReset.ts`).
+The cart owns the cascade: `EditCart.tsx` watches the react-hook-form field `orderFor`, fetches the full user, then sets the sales-quote contact, manager name, cost center and notification emails, and stores the full user in `useSelectedUserZu`. The header must **not** duplicate that (~100 lines) and must **not** write `useSelectedUserZu` directly — the cascade needs the *previous* value and a *full* user object.
 
-Rejected: header writes `useSelectedUserZu` directly; header runs its own copy of the cascade.
-
-### 4. Failed user load now clears the cart, not just Sentry
+- `EditCart.tsx` applies the saved pick as **"Name (email)"** (the exact label shape the cart's own input produces) whenever the form's `orderFor` uuid differs from the stored pick. `appliedHeaderPickRef` is set **before** `setValue` and checked **both before and after** the mount seed's `await fetchUserByContactUuid(...)`, so the saved contact cannot overwrite a pick applied while that fetch is in flight.
+- The cart's user-load cascade writes back: `onSuccess` calls `setOrderForUser({ uuid, name: _name, email, ownerUuid: user.uuid })` so header and cart never drift.
+- `onError` calls `handleClearUser()` (required `EditCartTypes` prop passed from `CartPage.tsx`) and raises an error toast from the `CARTPAGE.ts` key `orderFor.settings.loadUserErrorMessage`, with the same string hardcoded as a fallback for tenants without the key.
+- Header display order: stored pick → `useSelectedUserZu.selectedUser` → self.
 
-`singleUsersData.mutate` `onError` in `EditCart.tsx` used to report to Sentry and leave a half-applied order-for. It now calls CartPage's full `handleClearUser()` (new **required** prop `handleClearUser` on `EditCartTypes` in `src/pages/Cart/types.ts`, passed from `CartPage.tsx`) and raises an error toast. Toast copy is the new `CARTPAGE.ts` key `orderFor.settings.loadUserErrorMessage` ("We could not load that user. Please choose the user again.") in the four COMPASS/ENGLISH role files, with the same string hardcoded as a fallback for tenants without the key.
+Rejected: header writes `useSelectedUserZu` directly; header runs its own copy of the cascade.
 
-### 5. e2e spec (written, not run)
+### 5. e2e spec
 
-`cypress/e2e/homePage/orderForDropdown.cy.ts`, Compass tenant only, `compassAdminLogin` + the existing `users?recordsPerPage=**` `bulkUsers` stub. Covers: default trigger shows "Myself"; open → list → pick sets `data-active="yes"`; the pick survives a route change to `/get-support` but **not** a reload (proving the store is in-memory); admin server search stubbed empty asserts "No options found"; picking yourself turns active off; Escape returns focus to the trigger; outside click closes.
+`cypress/e2e/homePage/orderForDropdown.cy.ts` — 4 tests, Compass tenant, **4/4 green**. Asserts the pick survives a route change (via the `account-icon` router Link) and `cy.reload()`, and reads `localStorage['order-for-zu'].state.orderForUser.uuid` / `.ownerUuid` directly.
 
 Test ids: `order-for-dropdown`, `order-for-trigger`, `order-for-current-name`, `order-for-menu`, `order-for-search`, `order-for-option`, `order-for-load-more` (mobile variants add `-mobile`).
 
 ## Gotchas
 
-- **Never `persist` `useOrderForZu`.** A persisted pick survives login, view-as and submit reloads and silently orders for the wrong person. The `ownerUuid` guard is the second line of defence, not a licence to persist.
+- **The `ownerUuid` guard is what makes persistence safe — never drop it.** A persisted pick with no owner check is inherited by the next login or by a view-as target and silently orders for the wrong person. Read the store through `getOrderForUserFor(pick, ownerUuid)`, never raw.
 - **Do not set `useSelectedUserZu` from the header.** The cascade reads the *previous* selected user out of the store (see [cart-notification-emails](cart-notification-emails.md)); writing it early makes the previous-user email cleanup a no-op and strands the old person's notification emails on the order.
-- **A missing `orderFor` key renders nothing, by design.** `useAssignClientFields` has no fallback for a missing key, so Compass Canada and Quad get `undefined` and the component returns `null` — a safe default-off, not a bug. Adding the tenant means adding the key to every role file for that tenant.
+- **A missing `orderFor` key renders nothing, by design.** `useAssignClientFields` has no fallback for a missing key, so Compass Canada and Quad get `undefined` and the component returns `null` — safe default-off. Adding a tenant means adding the key to every role file for that tenant.
 - **`appliedHeaderPickRef` must be checked after the awaited mount fetch too.** Checking only before the `await fetchUserByContactUuid(...)` lets the saved contact overwrite a pick made while the fetch was in flight.
-- **`_production` and `_sandbox-client` have diverged in `EditCart.tsx`** — `_production` lacks the sandbox delegate-manager code, so a stashed patch will not apply cleanly to that file. To move uncommitted work between branches (GitHub Desktop auto-stashes on branch switch as `!!GitHub_Desktop<branch>`): `git diff stash@{0}^1 stash@{0} > patch`, dry-run with `git apply --check --3way patch`, then `git apply --3way --exclude=<conflicting file> patch` and hand-port the conflicting file. Keep the stash until the work is committed.
-- **Tailwind: `max-h-300px` is not a token** (300px exists only on the height/width scales) — use `max-h-[300px]`. `w-345px`, `h-300px`, `border-1` and `shadow-subMenu` do exist.
+- **`_production` and `_sandbox-client` have diverged in `EditCart.tsx`** — `_production` lacks the sandbox delegate-manager code, so a stashed patch will not apply cleanly to that file. To move uncommitted work between branches: `git diff stash@{0}^1 stash@{0} > patch`, dry-run with `git apply --check --3way patch`, then `git apply --3way --exclude=<conflicting file> patch` and hand-port the conflicting file. Keep the stash until the work is committed.
+- **Tailwind: `max-h-300px` is not a token** — use `max-h-[300px]`. `w-345px`, `h-300px`, `border-1` and `shadow-subMenu` do exist.
+
+## Change history
+
+- 2026-09-17 — Pick is now persisted to `localStorage["order-for-zu"]` with an `ownerUuid` guard (TRUE-81852); the submit / edit-order-exit / view-as-return / reload clears were removed, and the cart writes the loaded user back to the store. Spec now 4/4 green. (tcox)
+- 2026-09-17 — Header order-for pill added (TRUE-81851), in-memory hand-off store, cart clears on failed user load. (tcox)
 
 ## Related
 
@@ -103,4 +106,5 @@ Test ids: `order-for-dropdown`, `order-for-trigger`, `order-for-current-name`, `
 - [client-fields](client-fields.md)
 - [cart-notification-emails](cart-notification-emails.md)
 - [cart-page-config-architecture](cart-page-config-architecture.md)
+- [view-as-session-tokens](view-as-session-tokens.md)
 - [cypress-testing](../workflows/cypress-testing.md)

package/knowledge/2.0/apps/toga2-commerce/features/view-as-session-tokens.md

@@ -0,0 +1,90 @@
+---
+title: View-as another user — parked admin tokens & return-to-self
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-09-17
+owners: [tcox]
+files:
+  - src/api/sessionTokens.ts
+  - src/api/apiBaseUrl.ts
+  - src/api/axiosInstance.ts
+  - src/contexts/AuthContext.tsx
+  - src/components/AuthLayout/AuthLayout.tsx
+  - src/components/NavIcons/NavIconList.tsx
+  - cypress/e2e/viewAs/viewAsUser.cy.ts
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/header-order-for-dropdown.md
+  - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
+  - 2.0/apps/api2/architecture.md
+---
+
+How an admin impersonates another user and gets back: the delegated token pair, the parked admin pair in localStorage, and the return path. Open before touching auth tokens, the axios refresh, or the view-as button.
+
+## Summary
+
+TRUE-81852 (commit `a8c3a537`). An admin can browse the storefront **as** another user. Previously, returning to yourself re-minted the admin's tokens through the privileged `/auth/encrypted` call. Now the admin's **own** token pair is parked in localStorage when delegation starts and put back on return — `/auth/encrypted` is no longer called on return at all.
+
+All token plumbing lives in **`src/api/sessionTokens.ts`** (new). `src/api/apiBaseUrl.ts` (new) exports `apiBaseUrl` so both the axios instance and the token helpers resolve the same host. `src/utils/auth.ts` and `handleClientAuthentication` / `UserData` in `Login/api/LoginApi.tsx` were dead and were deleted.
+
+## How it works
+
+### Entering view-as (`NavIconList.tsx` onSuccess)
+
+1. `fetchUserTokens(uuid, "/auth/delegator")` mints the delegated pair for the target user.
+2. `beginDelegation(delegatedPair, adminUuid)` parks the admin's current pair under localStorage key **`originalAuthTokens`** as `{ v: 1, access, refresh, userUuid, apiHost, savedAt }`, then writes the delegated pair into `accessToken` / `refreshToken`.
+3. It **never overwrites an existing parked pair** — view-as is one level deep. `isViewAsEnabled` also hides the button when `hasSavedOriginalTokens()` is true.
+4. On any error entering view-as, it rolls back: `restoreOriginalTokens` if a pair is parked, plus `clearOriginalUser()`.
+
+### Returning (`AuthLayout.returnToYourViewOnClick`)
+
+`restoreOriginalTokens(adminUuid)`:
+
+1. Checks `userUuid` **and** `apiHost` match, and age ≤ `PARKED_PAIR_MAX_AGE_MS` (**12h**). It **always removes** the parked key, pass or fail.
+2. On success: puts the admin pair back; if the access JWT is expired (`isAccessTokenExpired` decodes `exp`), calls `refreshAuthTokens()` once **before** the cache clear.
+3. On failure: logs a Sentry warning, clears the view-as store, logs out, navigates to `/`. There is **no** `/auth/encrypted` fallback.
+4. Removes `localStorage["commerce"]` (the persisted react-query cache) so the impersonated user's rows cannot rehydrate under the admin.
+
+### Where else the parked pair is cleared
+
+`login()` clears it (and the view-as store) first; `fetchPublicToken` and `performLogout` clear it; module load sweeps it when there is no `accessToken`.
+
+### Refresh safety (`axiosInstance.ts`)
+
+The 401 refresh is **single-flight** (one module-level promise shared by concurrent 401s) and **identity-bound**: `requestRefreshedTokens` returns `null` if `localStorage.refreshToken` changed while the refresh was in flight. That stops an in-flight admin refresh from overwriting a just-minted delegated pair (or the reverse).
+
+### Decisions (CSO review — SHIP WITH FIXES)
+
+Identity-bound refresh · one-level view-as · 12h max parked age · no `/auth/encrypted` fallback (log out instead) · never put error objects in `JSON.parse` failure logs · match on `apiHost` only (clientId dropped).
+
+### e2e (`cypress/e2e/viewAs/viewAsUser.cy.ts`)
+
+Seeds a long-lived `ADMIN_ACCESS_JWT`; stubs `/auth/delegator` → `mock-delegated-access-token` / `-refresh`, and `**/v2/pages/meta?page=home-page&app=commerce*`; the fetchUser stub matches on a RegExp over the `?fields=uuid,_name,...` list. Asserts: delegated pair active + parked pair present; after return, `accessToken === ADMIN_ACCESS_JWT`, parked key null, and **zero** calls to `/auth/encrypted`. 1/1 green.
+
+## Gotchas
+
+- **Never re-mint the admin's tokens on return.** The old `/auth/encrypted` path was a privileged call made from the browser. Restore the parked pair, or log out — those are the only two outcomes.
+- **Always remove `originalAuthTokens`, even on a failed restore.** Leaving a stale parked pair blocks the next view-as (`beginDelegation` refuses to overwrite) and keeps an old admin refresh token on disk.
+- **Clear `localStorage["commerce"]` on return.** The persisted query cache is shared; without the clear, the impersonated user's data rehydrates under the admin identity (see the 24h persisted-cache gotcha in [architecture](../architecture.md)).
+- **Keep the refresh identity-bound.** A refresh that resolves after the identity changed must return `null`, not write tokens.
+- **A view-as test must stub `/v2/pages/meta?page=home-page&app=commerce`.** Unstubbed, the real call fails and triggers the enter-view-as rollback, so the spec sees a return-to-admin it did not ask for.
+
+## Open items (out of ticket, not fixed)
+
+- `SENTRY_AUTH_TOKEN` is committed in 25 tracked `.env*` files — treat it as compromised and rotate it. (Never store the value in this KB.)
+- Confirm api2 authorizes `/auth/delegator` **server-side** as admin-only; the client-side gate is not a control.
+
+## Change history
+
+- 2026-09-17 — Created. Admin pair parked in `originalAuthTokens` on delegation and restored on return; `/auth/encrypted` re-mint removed; single-flight identity-bound refresh (TRUE-81852, commit a8c3a537). (tcox)
+
+## Related
+
+- [architecture](../architecture.md)
+- [header-order-for-dropdown](header-order-for-dropdown.md)
+- [cypress-testing](../workflows/cypress-testing.md)
+- [api2 architecture](../../api2/architecture.md)

package/knowledge/2.0/apps/toga2-commerce/workflows/cypress-testing.md

@@ -11,12 +11,12 @@ owners: [tcox]
 files:
   - toga2-commerce/cypress/e2e/cartPage/cartV2.cy.ts
   - toga2-commerce/cypress/e2e/homePage/orderForDropdown.cy.ts
+  - toga2-commerce/cypress/e2e/viewAs/viewAsUser.cy.ts
   - toga2-commerce/cypress/fixtures/cart/fetchUserShippingMethods.json
   - toga2-commerce/cypress/support/commands.ts
   - toga2-commerce/cypress/support/e2e.ts
   - toga2-commerce/src/pages/Cart/CartPage.tsx
   - toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx
-  - toga2-commerce/src/pages/Cart/view/cartForm/CartFormSection.tsx
   - toga2-commerce/src/pages/Cart/view/cartTable/CartContentsTable.tsx
   - toga2-commerce/src/pages/Cart/view/cartTable/CartTableItem.tsx
   - toga2-commerce/src/components/Inputs/AdvancedInput.tsx
@@ -27,6 +27,7 @@ related:
   - 2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - 2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md
   - 2.0/apps/toga2-commerce/features/header-order-for-dropdown.md
+  - 2.0/apps/toga2-commerce/features/view-as-session-tokens.md
   - 2.0/apps/toga25-supply/workflows/cypress-testing.md
 ---
 
@@ -100,7 +101,12 @@ The cart UI was instrumented with `data-testid` attributes so specs anchor on **
 
 ### Other active specs
 
-- `cypress/e2e/homePage/orderForDropdown.cy.ts` (2026-09-17, branch `TRUE-81851`) — the header order-for pill; COMPASS only, `compassAdminLogin` + the existing `users?recordsPerPage=**` `bulkUsers` stub. **Written and type-checked but never executed** — run it before trusting it. Ids `order-for-*` (see [header-order-for-dropdown](../features/header-order-for-dropdown.md)).
+- `cypress/e2e/homePage/orderForDropdown.cy.ts` — the header order-for pill, COMPASS only, 4 tests, **4/4 green**. Asserts the pick survives a route change and `cy.reload()` by reading `localStorage['order-for-zu']`. Ids `order-for-*` (see [header-order-for-dropdown](../features/header-order-for-dropdown.md)).
+- `cypress/e2e/viewAs/viewAsUser.cy.ts` — admin view-as enter/return, **1/1 green**. Seeds a long-lived admin JWT, stubs `/auth/delegator` and `**/v2/pages/meta?page=home-page&app=commerce*` (see [view-as-session-tokens](../features/view-as-session-tokens.md)).
+
+### Known-red specs (pre-existing, not yours)
+
+On prod base `aedd1f7a`, Compass tenant: **13 failures** — `getSupportV2` (4), `homePageContentV2` (7), `firstTimeLoggingIn` (2). Reproduced identically on an untouched `git archive aedd1f7a` copy, so they are **not** caused by feature work. Likely cause: the login command's `/users/{uuid}` stub field list no longer matches the app's request, so the call falls through to the real API and 401s. Full Compass suite on the TRUE-81852 feature branch: **54 pass / 13 fail** — the same 13.
 
 **Not yet covered — slice 2 work-list:**
 - **Bundle scenarios** — blocked on the stale bundle seeds (rebuild `seedCartBundle` / `seedSalesQuoteBundle` first, above).
@@ -114,13 +120,24 @@ The cart UI was instrumented with `data-testid` attributes so specs anchor on **
 2. Start the **dev server separately** first: `npm run compass` | `npm run compasscanada` | `npm run quad`.
 3. **Windows invocation:** `$env:TENANT="compass"; npm run cypress` — `cross-env` is **not** installed, so set the env var in the shell.
 4. Requires **hosts-file entries** `127.0.0.1 compass|compasscanada|quad.togacommerce` (present on this machine but **undocumented in the README** — a new dev must add them).
+5. Headless run (works despite there being no npm script): `Remove-Item Env:ELECTRON_RUN_AS_NODE` first (see gotcha), then `$env:TENANT="compass"; npx cypress run --env TENANT=compass` with vite dev serving `http://compass.togacommerce:5173`.
 
 ## Gotchas
 
+- **`ELECTRON_RUN_AS_NODE=1` breaks every spec in a VS Code terminal.** VS Code's integrated terminals set it, and `npx cypress run` then fails verification on every spec with `Cypress.exe ... bad option: --smoke-test`. Fix: `Remove-Item Env:ELECTRON_RUN_AS_NODE` in that shell before running. Reinstalling the Cypress binary does **not** help.
+- **The users API URL-encodes hyphens as `%2D`.** A glob like `**/v2/users?*no-such*` never matches — use a hyphen-free search term in the test, or match with a RegExp.
+- **"Get Support" in the header is a plain `<a>`** (full page reload). To test that state survives a *route change*, click `account-icon` — that one is a router `Link`.
+- **The `EnvironmentBadge` covers the header corner.** For outside-click tests, click `header-search-input` instead of the corner.
+- **A later `cy.intercept` wins over an earlier one for the same URL** — define the narrow override after the general stub, not before.
 - **`BaseButton` never sets the native `disabled` attribute (test-critical).** `src/components/BaseButton/BaseButton.tsx` sets `aria-disabled="true"|"false"` and suppresses `onClick` inside `handleClick` — it deliberately leaves the element enabled so a disabled button (e.g. **Proceed to Checkout**) still receives mouse events and its `BaseTooltip` (*"Please complete all required fields to proceed."*) works. Cypress assertions **MUST** use `.should('have.attr', 'aria-disabled', 'true'|'false')`, **never** `.should('be.disabled')` — `be.disabled` times out even though the button is visually/functionally disabled. (This cost the only 2 first-run failures.)
 - **Seed → then `cy.visit('/cart')`.** The persist stores rehydrate on load only; seeding `localStorage` and navigating in-app leaves the stores stale (see seeding section).
 - **Bundle seeds are on the legacy shape** — do not write a bundle spec against them until they are rebuilt to the `bundleZuCartUuid` + `bundleProgressContents` contract.
-- **ESLint fails repo-wide in a fresh checkout** because `.eslintrc.cjs` references `eslint-plugin-react-compiler`, which is not installed; `npm install --save-dev eslint-plugin-react-compiler` fixes it. To lint without touching the checkout, run `eslint --no-eslintrc` with the `react-hooks` and `no-unused-vars` rules instead. This is a local-environment issue, not a spec problem.
+- **ESLint fails repo-wide in a fresh checkout** because `.eslintrc.cjs` references `eslint-plugin-react-compiler`, which is not installed; `npm install --save-dev eslint-plugin-react-compiler` fixes it. To lint without touching the checkout, run `npx eslint --no-eslintrc --plugin react-hooks --plugin @typescript-eslint <files>`. This is a local-environment issue, not a spec problem.
+
+## Change history
+
+- 2026-09-17 — Added `viewAsUser.cy.ts`; orderForDropdown now green; recorded the `ELECTRON_RUN_AS_NODE` failure, the intercept pitfalls, and the 13 pre-existing red specs on base `aedd1f7a`. (tcox)
+- 2026-09-17 — Created with the V2 convention set and the `cartV2.cy.ts` cart harness (slice 1). (tcox)
 
 ## Related
 
@@ -128,4 +145,6 @@ The cart UI was instrumented with `data-testid` attributes so specs anchor on **
 - [cart-notification-emails](../features/cart-notification-emails.md)
 - [expedited-shipping-gating](../features/expedited-shipping-gating.md)
 - [cart-bundle-submission-and-identity](../features/cart-bundle-submission-and-identity.md)
+- [header-order-for-dropdown](../features/header-order-for-dropdown.md)
+- [view-as-session-tokens](../features/view-as-session-tokens.md)
 - [toga25-supply Cypress harness](../../toga25-supply/workflows/cypress-testing.md)

package/knowledge/INDEX.md

@@ -31,7 +31,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos-backend** (TOGa IQ Backend) — 1 doc(s) → [2.0/apps/talos-backend/INDEX.md](2.0/apps/talos-backend/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 23 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 24 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 21 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 14 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.846",
+  "version": "1.0.848",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",