toga-ai 1.0.508 → 1.0.509

package/knowledge/1.0/apps/library/INDEX.md

@@ -8,7 +8,7 @@
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | Two "View Recommended Services" buttons exist in the TOGa Refresh 2026 SR view: 1. | library/app/model/toga/diagnostic.php, library/app/model/servicerequest.php |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
-| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). | library/app/error/capture.php, library/app/error.php, library/app/exception/business.php, library/app/cloud.php, worker/config.worker.ini, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php |
+| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). | library/app/error/capture.php, library/app/error.php, library/app/exception/business.php, library/app/api/toga2.php, library/app/cloud.php, worker/config.worker.ini, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
 | [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |

package/knowledge/1.0/apps/library/features/error-capture-1-0.md

@@ -12,11 +12,13 @@ files:
   - library/app/error/capture.php
   - library/app/error.php
   - library/app/exception/business.php
+  - library/app/api/toga2.php
   - library/app/cloud.php
   - worker/config.worker.ini
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
 related:
   - ../architecture.md
+  - ./toga2-api-client-and-bridge.md
   - ../../../2.0/apps/_underscore/features/error-reporting-issue-event.md
   - ../../../2.0/apps/worker2/features/error-escalation-cron.md
   - ../../tools/features/errors-curation-console.md
@@ -76,13 +78,42 @@ whichever occurrence happened to be seen first — i.e. one arbitrary order numb
 
 Compass USA's sales-order → MITS transmit rejection was the first business-exception use case.
 
-### Client attribution
+### Client attribution — resolved from the API client uuid at `App_Api_Toga2::authenticate()`
 
 `App_Error::setCurrentClientId()` exists in 1.0 for parity with 2.0's ambient current-client, but
-**1.0 has no central hook** equivalent to `_Database::registerClientDatabases()`. Client-scoped
-1.0 crons therefore **set it explicitly** (see
-`worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php`). Capture
-prefers an explicit `clientId` argument and falls back to the ambient value.
+**1.0 has no central hook** equivalent to `_Database::registerClientDatabases()`. Because of that,
+the explicit setter was only ever called by **one** hand-edited Compass cron, so
+**every other 1.0 cron recorded `clientId` NULL**. Evidence: `Logs.Event` held **2,093 rows with
+`clientId` NULL** against **107** with a client (all of them 2.0/api2 JWT traffic); issue `1Q`
+traced back to the 1.0 cron `crons/toga2/quad/import_po_and_asn.php`.
+
+**`App_Api_Toga2::authenticate()` is 1.0's true choke point.** `send()` authenticates before every
+call, and every 1.0→2.0 cron arrives there holding its `UUID_CLIENT`. It now calls
+`App_Error_Capture::setCurrentClientUuid($uuid)` — a **store only, no lookup**, because
+`authenticate()` is a happy-path function and must not take on a query.
+
+`App_Error_Capture` then resolves uuid → `Core.Clients.id` **lazily**, only when an error is
+actually captured, cached per process (`resolveClientIdFromUuid()`, private). It walks
+**`CORE_DATABASE_LINK_CANDIDATES = ['db_toga2core', 'db_prod_toga2core', 'db_core']`** because 1.0
+apps register the same Core connection under different link names. **Every failure path returns
+`null` and records no client rather than throwing.**
+
+Precedence is unchanged: an explicit `clientId` argument wins, then an explicit
+`setCurrentClientId()`, then the ambient uuid.
+
+> **⚠ The resolution must run INSIDE the existing
+> `App_Error::setThrowExceptionsEnabled(false)` guard.** An unconfigured DB link **warns** before
+> it fails, and in 1.0 a warning outside that guard terminates the cron (see the first gotcha
+> below). Do not hoist the lookup out of the guarded block.
+
+### The reference encoder is a byte-identical mirror of 2.0's
+
+`capture.php` carries its own copy of `encodeReference()` plus `REFERENCE_ALPHABET`
+(`'0123456789ACDEFGHJKMNPQRSTUVWXYZ'`) and `REFERENCE_OFFSET` (`128`), matching
+`_Model_Core_Logs_Issue` **byte for byte**. Both write the same **UNIQUE** `Issue.reference`
+column in the same shared table, so a divergence between them is a failed INSERT and a **lost**
+error. Change one, change both, deploy together. Rationale for the alphabet and the offset lives in
+the [2.0 doc](../../../2.0/apps/_underscore/features/error-reporting-issue-event.md#the-quotable-reference--base-32-over-an-unambiguous-alphabet-reworked-2026-08-04).
 
 ### Fingerprint fallback (no usable stack)
 
@@ -151,6 +182,17 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Change history
 
+- 2026-08-04 (later, **uncommitted/undeployed** at time of writing) — **Fixed: 1.0 errors recorded
+  `clientId` NULL on every cron but one** (2,093 NULL `Logs.Event` rows vs 107 with a client; issue
+  `1Q` from `crons/toga2/quad/import_po_and_asn.php`). `App_Api_Toga2::authenticate()` — 1.0's real
+  choke point, since `send()` authenticates before every call — now records the ambient client uuid
+  (store only, no lookup), and `App_Error_Capture` resolves uuid → `Core.Clients.id` lazily and
+  per-process on capture, walking `CORE_DATABASE_LINK_CANDIDATES`
+  (`db_toga2core`/`db_prod_toga2core`/`db_core`) because 1.0 apps name the Core link differently;
+  every failure path returns null rather than throwing, and the lookup deliberately runs inside the
+  `setThrowExceptionsEnabled(false)` guard because an unconfigured link *warns* before it fails.
+  Also mirrored 2.0's **base-32 reference encoder** (`REFERENCE_ALPHABET` + `REFERENCE_OFFSET = 128`)
+  byte-for-byte. (jcardinal)
 - 2026-08-04 — Built the 1.0 side of TRUE-78188: `App_Error_Capture` writing occurrences into the
   shared 2.0 `Logs` DB (opt-in via `[database_toga2logs]`, hand-written escaped SQL);
   `App_Exception_Business` with a fingerprint string byte-identical to 2.0's so one `issueKey`

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-08-03
+updated: 2026-08-04
 owners: [jcardinal, mhammontree]
 files:
   - library/app/api/toga2.php
@@ -22,6 +22,7 @@ related:
   - netsuite-suiteql-rest-shim.md
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
   - ../architecture.md
+  - ./error-capture-1-0.md
 ---
 
 ## Summary
@@ -77,6 +78,18 @@ belong to the NetSuite importer — documented in the per-client-sync doc, not h
 - Returns the decoded response object; callers read `->data->{resource}`, `->meta->nextPage`,
   `->isSuccess`, `->status`, `->messages[].code`.
 
+> **`authenticate()` is also 1.0's ambient-client choke point for error reporting** (added
+> 2026-08-04). Every 1.0→2.0 cron passes through it holding its `UUID_CLIENT`, so it calls
+> `App_Error_Capture::setCurrentClientUuid()` — **store only, no lookup**: this is a happy-path
+> function and must not acquire a query. The uuid → `Core.Clients.id` resolution happens lazily
+> inside error capture. Keep it that way; see
+> [error-capture-1-0](./error-capture-1-0.md).
+
+> **Latent, pre-existing, uninvestigated:** several `self::$togaClientUuid` references sit in
+> methods of this class (roughly lines 2880–4250) with **no such property declared** — an
+> undefined-property bug waiting to fire (and in 1.0, a warning inside an unguarded path
+> terminates the cron). Not introduced by, and not fixed by, the 2026-08-04 error-reporting work.
+
 ### Options DSL (how 1.0 expresses 2.0 queries)
 
 `$options` is an assoc array assembled into the 2.0 query string:
@@ -340,6 +353,11 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-04 (**uncommitted/undeployed** at time of writing) — `authenticate()` now records the
+  ambient client uuid for error reporting (`App_Error_Capture::setCurrentClientUuid()`, store-only)
+  because it is the one place every 1.0→2.0 cron passes through holding its `UUID_CLIENT` — this is
+  what fixed 1.0 errors recording `clientId` NULL. Also noted the pre-existing undeclared
+  `self::$togaClientUuid` references (~L2880–4250) as a latent undefined-property bug. (jcardinal)
 - 2026-08-03 (later pass) — TRUE-79401 **static regression harness + one correction.** BUILT a
   no-DB PHP harness (`test/@Mark/AIG/test_multi_email.php`, 12 cases, PHP 7.2.33, `php -l` clean)
   that feeds mocked `/contacts` fragments through the email transform and asserts the delimited

package/knowledge/1.0/apps/tools/features/errors-curation-console.md

@@ -72,6 +72,48 @@ curated text, affected clients) right, with an always-present Type chip.
   time.
 - Hourly-occurrence chart; fingerprints table re-sized for the narrow column with an icon-only
   Move button.
+- Header chip order is **Issue / Environment / Type / Urgency** — Type was moved ahead of Urgency so
+  urgency finishes the row at the far right.
+
+### Table presentation rules (established 2026-08-04)
+
+**Stacked datetimes in every table on both pages** — listing *Last seen*; detail *Events → When*,
+*Affected clients → Last*, *ClickUp episodes → Opened/Resolved*, *Fingerprints → First seen*. A
+shared `$datetime` closure emits
+`<span class="dt"><span class="dt-date">…</span><span class="dt-time">…</span></span>`, each part
+`nowrap`, split on the single space MySQL puts between date and time; a blank value renders an em
+dash. Tabular figures keep digits aligned down the column.
+
+> **Why:** letting a datetime wrap naturally let the browser pick its own break point, and the point
+> it picked was **inside the day of the month** (`2026-08-` / `04`). This replaced the old
+> `.wrap-date` / `.wrap-anywhere` approach, whose now-dead CSS rule was removed.
+
+**The summary column has a 100px floor via table overflow, not a cell `min-width`.** The summary
+`<col>` is deliberately left **unwidthed** so it absorbs leftover space — which is also why *every
+other* column must declare a width, or `col-type` absorbs it instead. The floor comes from
+`.issue-listing { min-width: 1026px }` inside a new `.table-scroll { overflow-x: auto }` wrapper.
+
+> **⚠ Under `table-layout: fixed` a browser compresses ALL columns proportionally at narrow
+> viewports and ignores `min-width` on a cell.** A cell-level `min-width` therefore cannot work —
+> the table has to overflow and scroll. `col-when` narrowed 168px → 104px now that dates stack (the
+> 64px went to the summary), and a duplicate `.col-type` rule was removed in favour of the
+> pre-existing 104px one. **The pager sits outside the scroll wrapper.**
+
+**Whole-row click replaced the two per-cell links** (Issue ID and Summary). The `<tr>` carries
+`class="row-link"`, `data-href`, `tabindex="0"` and an `aria-label`; `.issue-id-link` was renamed
+`.issue-id` (keeping the accent colour as the affordance) and `tr.row-link` got cursor/hover/
+`focus-visible` rules.
+
+This page was deliberately **JavaScript-free**, and this is the one thing that cannot be done
+without it: no element but an anchor is clickable, and an anchor cannot wrap a `<tr>`. A small
+**delegated** click+keydown handler was added. Ctrl/Cmd/Shift-click still opens a new tab;
+Enter/Space work because removing the anchors removed the tab stop; clicks on `a`, `button`,
+`input`, `select`, `textarea`, `summary` or `label` are ignored so future in-row controls keep their
+own behaviour.
+
+> **Known trade-off:** a screen reader now announces these as **labelled rows, not links**.
+> `role="link"` was deliberately **not** applied, because it would stop the element being a table
+> row.
 
 **This page notifies nobody.** Escalation, ClickUp ticketing, and email are owned entirely by
 `_Worker_Infrastructure_Errors::Escalate`. Adding a notify action here would create a second,
@@ -128,6 +170,21 @@ They were renamed from plural on 2026-08-01, after the pipeline was already in p
 
 ## Change history
 
+- 2026-08-04 (later, **uncommitted/undeployed** at time of writing) — UI pass on both `/errors`
+  pages: **stacked datetimes** in every table via a shared `$datetime` closure emitting
+  `.dt`/`.dt-date`/`.dt-time` (a naturally wrapping datetime broke inside the day of the month), and
+  the dead `.wrap-date`/`.wrap-anywhere` rules removed; a **100px floor on the summary column**
+  delivered as `.issue-listing { min-width: 1026px }` inside a new `.table-scroll` overflow wrapper
+  (with the pager outside it), because `table-layout: fixed` ignores a cell `min-width` and
+  compresses all columns proportionally — `col-when` narrowed 168px → 104px and a duplicate
+  `.col-type` rule removed; the two per-cell links replaced by a **whole-row click**
+  (`tr.row-link` + `data-href` + `tabindex` + `aria-label` and one small delegated click/keydown
+  handler — the single unavoidable use of JS on this deliberately JS-free page, since an anchor
+  cannot wrap a `<tr>`), honouring Ctrl/Cmd/Shift-click and ignoring clicks on interactive
+  descendants, with the accepted trade-off that screen readers announce labelled rows rather than
+  links (`role="link"` would stop the element being a row); and issue-detail header order changed to
+  Issue / Environment / Type / Urgency. Note **`library` and `tools` must both deploy** for any of
+  this to be visible. (jcardinal)
 - 2026-08-04 — Console build-out: the listing gained real pagination (25/page with a filtered
   `COUNT`, replacing a silent `LIMIT 200`), an EB Environment column **and filter**, a
   BUSINESS/TECHNICAL Type column derived from `issueKey` (no new DB column), and a 3-column filter

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -190,15 +190,47 @@ A uniform shape is what lets a viewer render context **generically** (see the To
 card/JSON-tree renderer). Consumers must read **both** the old and new key positions during the
 7-day `Event` retention overlap.
 
-### The quotable reference
+### The quotable reference — base-32 over an unambiguous alphabet (reworked 2026-08-04)
 
-`Issues.reference` is a Sentry-style base-26 encoding of `Issues.id`: 1 → `1A`, 26 → `1Z`,
-27 → `2A`. Because `AUTO_INCREMENT` never reuses ids, gaps are expected and permanent — a
-reference can never be recycled onto a different problem, so it is safe to quote to a customer.
+`Issue.reference` encodes `Issue.id` in **base 32** over
+`REFERENCE_ALPHABET = '0123456789ACDEFGHJKMNPQRSTUVWXYZ'`, most-significant character first, no
+padding (`_Model_Core_Logs_Issue::encodeReference()`). **All ten digits are kept; `O`, `I`, `L`
+and `B` are removed** because in the contexts a reference actually gets used — read aloud on a
+call, typed from a screenshot, pasted into a ClickUp title — they impersonate `0`, `1`, `1` and
+`8`. A reference exists to be quoted, so ambiguity is the one defect it cannot have.
+
+It replaced a decimal-counter + letter, base-26 scheme (`1A`, `2Q`, `3O`).
+
+> **⚠ `REFERENCE_OFFSET = 128` exists to stop the new scheme from OVERWRITING the old one —
+> do not remove it.** `Issue.reference` is **UNIQUE**, and every legacy value begins `1`–`3`.
+> With no offset, new id 75 encodes to `2A`, which id 27 already holds — the INSERT fails and the
+> error is **lost instead of recorded**, precisely the failure mode this pipeline exists to
+> prevent. The offset burns the first 128 (= 4 × 32) code points so every new reference starts at
+> `4` or later and both generations coexist forever. Verified by script over 200,000 ids: no
+> collisions among themselves, none against the legacy values, no banned characters.
+
+The column is `varchar(16)`, so the growth to 3 characters (≈ id 897) and 4 (≈ id 29,000) cannot
+truncate. Because `AUTO_INCREMENT` never reuses ids, gaps are expected and permanent — a reference
+can never be recycled onto a different problem.
+
+**The 1.0 encoder in `library/app/error/capture.php` must stay byte-identical** — both write the
+same UNIQUE column in the same shared table. Change one, change the other, deploy together.
 
 The reference is written by PHP in a second statement (see MySQL constraints below), which is
 why the column is nullable even though it is always populated.
 
+#### Existing data is NOT being truncated (decided 2026-08-04)
+
+Nothing needs deleting to adopt the new scheme. References are **stored, never re-derived from
+the id at read time**: the listing search, the Tools Move-fingerprint prompt (which accepts a
+reference *or* a numeric id) and every display path read the stored string, so both generations
+work side by side. Accepted cost: 10 of the 68 existing issues keep ambiguous references (`1B`,
+`1I`, `2B`, `2I`, `2L`, `2O`, `3B`, `3I`, `3L`, `3O`) until they age out through the normal GC.
+
+> **If you ever do truncate `Logs.Issue`:** `TRUNCATE` **resets `AUTO_INCREMENT`**, and
+> `IssueFingerprint`, `IssueEmailAddress`, `IssueClickupTask` and `Event` all reference
+> `Issue.id` — they must be cleared in the **same** operation or they orphan onto reused ids.
+
 ### Shutdown handler
 
 `register_shutdown_function` is registered with a **pre-allocated memory reserve**. Before this,
@@ -249,6 +281,13 @@ DB, so the pipeline is no longer 2.0-only; see
 has to opt in by adding a `[database_toga2logs]` config section, so Sentry must remain for any 1.0
 app that has not been wired up yet.
 
+## Deploy order for a change that spans this pipeline
+
+`_underscore` **first** (api2 and worker2 clone it at prebuild), then api2, worker2, `library`,
+`worker`, `tools`. Anything touching the reference encoder or a shared `Logs` table name must land
+in `_underscore` and `library` in the **same** release, and the `/errors` console work needs
+**both** `library` and `tools` deployed before it is visible.
+
 ## Gotchas / known issues
 
 - **Read-your-writes: reads go to the READ host and cannot see an uncommitted write.** A
@@ -379,6 +418,16 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-04 (later, **uncommitted/undeployed** at time of writing) — **Reference encoding reworked
+  to base 32** over `'0123456789ACDEFGHJKMNPQRSTUVWXYZ'` (all digits kept; `O`/`I`/`L`/`B` dropped
+  as impersonators of `0`/`1`/`1`/`8`), replacing the base-26 decimal-counter+letter scheme, with
+  **`REFERENCE_OFFSET = 128`** so new values start at `4` and cannot collide with the legacy `1`–`3`
+  values on the UNIQUE column — a collision would fail the INSERT and *lose* the error. Verified
+  over 200,000 ids. The 1.0 encoder in `library/app/error/capture.php` mirrors it byte-for-byte.
+  **Decided: existing Issue/Event data is not truncated** — references are stored and never
+  re-derived, so both generations coexist; 10 of 68 issues keep ambiguous references until GC.
+  Recorded the TRUNCATE warning (it resets `AUTO_INCREMENT` and four child tables reference
+  `Issue.id`). Next production reference will be `68` (max id 72). (jcardinal)
 - 2026-08-04 — **Decided: `_Exception_Business` extends `_Exception_Validation`** so api2 answers
   4xx for a business condition while still recording it — with the ordering trap that every
   `catch (_Exception_Validation …)` must now test business **first** (api2's controller and the

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -18,7 +18,7 @@
 | [Compass VIP Support Importer (worker2)](features/compass-vip-support-importer.md) | A worker2 action that ingests Compass's quarterly VIP spreadsheet and assigns each VIP user's support technician by setting `Users.c_supportedByUserId` in `Clie | worker2/Worker/Client/Compass/VipSupport.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
-| [Error Escalation Cron (Errors::Escalate → ClickUp / email)](features/error-escalation-cron.md) | `_Worker_Infrastructure_Errors::Escalate` (renamed from `SyncWithClickup`) is the sole owner of **escalation, de-escalation, ClickUp ticketing, reminders, busin | worker2/Worker/Infrastructure/Errors.php, worker2/Worker/Clickup/ErrorTask.php, worker2/Worker/Clickup.php, worker2/Controller/Index.php, worker2/Config/production.ini, _underscore/Model/Core/Logs/Issue.php, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql, dbchanges2/Logs/2026-08-03a - Issue clickupPriority.sql |
+| [Error Escalation Cron (Errors::Escalate → ClickUp / email)](features/error-escalation-cron.md) | `_Worker_Infrastructure_Errors::Escalate` (renamed from `SyncWithClickup`) is the sole owner of **escalation, de-escalation, ClickUp ticketing, reminders, busin | worker2/Worker/Infrastructure/Errors.php, worker2/Worker/Notification/Email.php, worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, worker2/Worker/Clickup/ErrorTask.php, worker2/Worker/Clickup.php, worker2/Controller/Index.php, worker2/Config/production.ini, _underscore/Model/Core/Logs/Issue.php, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql, dbchanges2/Logs/2026-08-03a - Issue clickupPriority.sql |
 | [Etilize Catalog Item Import & Refresh](features/etilize-catalog-item-import.md) | Client-generic catalog onboarding from an S3 CSV plus an Etilize re-pull. | worker2/Worker/Etilize/Items.php |
 | [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |

package/knowledge/2.0/apps/worker2/features/error-escalation-cron.md

@@ -10,6 +10,9 @@ updated: 2026-08-04
 owners: ["jcardinal"]
 files:
   - worker2/Worker/Infrastructure/Errors.php
+  - worker2/Worker/Notification/Email.php
+  - worker2/Worker/Notification/EmailTemplate.php
+  - worker2/Worker/Client/True.php
   - worker2/Worker/Clickup/ErrorTask.php
   - worker2/Worker/Clickup.php
   - worker2/Controller/Index.php
@@ -23,6 +26,8 @@ related:
   - ../../../1.0/apps/library/features/error-capture-1-0.md
   - ./creating-worker-actions.md
   - ./clickup-project-routing.md
+  - ./notification-email.md
+  - ./notification-email-template.md
 ---
 
 ## Summary
@@ -107,10 +112,64 @@ which is safe only because the automation never sets status itself.
 > stamping `dtAcknowledged` ~1s after `dtCreated` and permanently disabling the neglect axis for
 > that issue. Status webhooks arriving within 60s of creation are ignored.
 
+### ⚠ Escalation email had never been sent once — two independent causes (fixed 2026-08-04)
+
+Evidence: `Logs_True.Email` contained **zero** error-escalation rows *ever*, while unrelated
+worker2 mail (merge-conflict notices, sprint reports) delivered within ~60s — so the mail pipeline
+itself was healthy. Every `Infrastructure/Errors/Escalate` run reported `"emailsSent":0` alongside
+`"failures":0` and therefore **read as healthy**. All 48 HIGH/URGENT issues sat at
+`notificationCount` 4 — the last rung of the ladder — having sent nothing.
+
+**Root cause A (structural — the important one).** `processTechnicalIssue()` returned early when
+the ClickUp task would read identically (priority already correct **and** count unchanged), and
+**that `return` sat before the `if ($shouldNotify)` block.** `persistIssueState()` still ran on the
+way out with `didNotify: $shouldNotify`, stamping `dtLastNotified` and incrementing
+`notificationCount`. So a run that sent nothing still **consumed a rung** of the
+30/60/240/1440-minute `REMINDER_INTERVAL_MINUTES` ladder — and since a live issue normally sits at
+a settled priority with an unchanged count, that was **nearly every run**.
+
+Fix: the ClickUp write is now skipped on its own merits, inside
+`if ($needsPriorityWrite || $hasCountChanged)`, and the notification decision is made
+**independently, below it**.
+
+> **Lesson worth generalizing: "does ClickUp need writing?" and "does anyone need telling?" are two
+> separate questions.** Conflating them into one early return silenced the entire reminder ladder
+> while every metric reported success.
+
+**Root cause B.** Both send paths built a `_Email` and called `->send()` **inline inside the cron's
+open `DB_LOGS` transaction**. `_Email::send()` resolves the client's log database, registers a
+second connection and toggles the read host from in there; anything it threw was caught into
+`error_log` only — invisible in the console *and* in the run summary. Both paths now **enqueue via
+`_Worker::runTask`**, so a failure is a visible failed `WorkerJobs` row.
+
+### `emailFailures` in the run summary
+
+`Escalate()`'s JSON gained **`emailFailures`**, threaded through `processIssue()` /
+`processTechnicalIssue()`'s outcome arrays and counting notifications that were *meant* to go out
+and did not. It is reported **separately from `failures`** (which counts issues that threw). It
+exists specifically so the failure mode above — `emailsSent:0` with `failures:0` reading as
+healthy — cannot recur silently.
+
 ### Notification and task presentation
 
 - The technical escalation email to **devteam@togatech.com** now **coexists** with the ClickUp
   update. It was an `elseif`, so only one of the two ever fired.
+- **The technical escalation email uses the TOGA Technology stored email template.**
+  `sendTechnicalEscalationEmail()` enqueues **`Notification/EmailTemplate/Send`** with
+  `clientIdentifier` `'True'` and
+  `_Worker_Client_True::EMAIL_TEMPLATE_UUID__TOGA_TECHNOLOGY`
+  (`232d4edb-c2fa-4a8b-b5b9-d5800c962e19`) — the same pattern `Team/Transcripts.php` uses. Verified
+  against `Client_True.EmailTemplates`: `isActive = 1`; `{subject}` appears in **both** the subject
+  line and the branded header banner; `{body}` sits inside a **600px-wide** content cell that
+  already sets Plus Jakarta Sans 16px; the row carries its own `sendFromEmailAddress`
+  (`noreply@togatech.com`) and a single priority column (`NORMAL`).
+  - **`buildTechnicalEmailBody()` is therefore a FRAGMENT, not a document.** Its wrapper was
+    changed from `max-width:680px` + its own `font-family` to `max-width:100%` and no font —
+    680px would overflow the template's 600px cell.
+  - **Per-send priority is not available on the template path**, so urgency rides in the subject
+    and body instead.
+- **Business-issue emails moved to `Notification/Email/Send`**, which *does* keep per-client log
+  attribution and per-send priority.
 - ClickUp titles carry the **reference only** — `[1E]`, not `[1E-1]`. Including the occurrence
   number made the title churn on every escalation.
 - **Occurrences** and **Last Occurrence** custom fields are synced, and task bodies open with a
@@ -172,6 +231,13 @@ this controller needs the same treatment.**
 
 ## Gotchas / known issues
 
+- **Never send email inline inside this cron's open transaction — enqueue it.** `_Email::send()`
+  registers a second connection and toggles the read host, and a throw from in there was only ever
+  `error_log`'d. Use `_Worker::runTask` so a failure becomes a visible failed `WorkerJobs` row.
+- **A "nothing changed, return early" shortcut must not sit above the notification block.** It
+  consumed reminder-ladder rungs without sending anything, for months, while reporting
+  `emailsSent:0 / failures:0` as success. Decide the outbound write and the notification
+  independently.
 - **Persist state before, or independently of, any outbound call.** A regression chain took the
   whole run down every minute: `syncCustomFields()` read `$issue->dtLastOccurred`, which
   `loadWorkingSet()` never selected; `_Error::errorHandler()` promotes the undefined-property
@@ -207,6 +273,25 @@ this controller needs the same treatment.**
 
 ## Change history
 
+- 2026-08-04 (later, **uncommitted/undeployed** at time of writing) — **Fixed: escalation email had
+  never been sent, ever**, for two independent reasons. (A) `processTechnicalIssue()` returned early
+  when the ClickUp task would read identically, and that return sat *above* the `if ($shouldNotify)`
+  block while `persistIssueState()` still stamped `dtLastNotified`/`notificationCount` on the way
+  out — so nearly every run silently consumed a rung of the 30/60/240/1440-minute ladder; all 48
+  HIGH/URGENT issues had reached rung 4 having sent zero mail. The ClickUp write is now gated on its
+  own merits (`$needsPriorityWrite || $hasCountChanged`) and the notification decision is made
+  independently below it. (B) Both send paths built `_Email` and called `->send()` **inline inside
+  the open `DB_LOGS` transaction**, where a throw was only `error_log`'d — both now enqueue via
+  `_Worker::runTask`. **Built:** the technical escalation email now goes through the stored TOGA
+  Technology template (`Notification/EmailTemplate/Send`, clientIdentifier `True`,
+  `_Worker_Client_True::EMAIL_TEMPLATE_UUID__TOGA_TECHNOLOGY`), which makes
+  `buildTechnicalEmailBody()` a fragment (`max-width:100%`, no font — 680px would overflow the
+  template's 600px cell) and removes per-send priority (urgency moves into the subject/body);
+  business emails moved to `Notification/Email/Send`, which keeps per-client log attribution and
+  priority. **Built:** an **`emailFailures`** counter in `Escalate()`'s run summary, separate from
+  `failures`, so `emailsSent:0 / failures:0` can never read as healthy again. Verified by reading
+  only — proof will be `emailsSent` going non-zero (or `emailFailures` naming the problem) on the
+  first Escalate run after the worker2 deploy. (jcardinal)
 - 2026-08-04 — **Fixed: worker job failures were never captured at all** — worker2's front
   controller catches `Throwable` and returns 200, so six catch sites in
   `worker2/Controller/Index.php` now call `_Error::captureException()` after rollback and before the

package/knowledge/2.0/apps/worker2/features/notification-email.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-24
-owners: ["mhammontree"]
+updated: 2026-08-04
+owners: ["mhammontree", "jcardinal"]
 files:
   - worker2/Worker/Notification/Email.php
   - _underscore/Model/Client/EmailTemplate.php
@@ -39,7 +39,7 @@ migration backfilled first).
 - `worker2/Worker/Notification/Email.php` — `abstract _Worker_Notification_Email`. One method:
   `Send(string $clientIdentifier, string $subject, string $body, string|array $to=[],
   string|array $cc=[], string|array $bcc=[], string $fromEmail='donotreply@togatech.com',
-  string $fromName='TOGA Technology')`. The entry point. Self-registers the client DB (no
+  string $fromName='TOGA Technology', ?int $priority=null)`. The entry point. Self-registers the client DB (no
   `initialize()` — see below), wraps the body, and sends.
 - `_underscore/Model/Client/EmailTemplate.php` — supplies `WRAPPER_UUID` and
   `renderWrappedBody($subject, $body)`. Documented in
@@ -69,6 +69,20 @@ migration backfilled first).
 5. **Send** via a plain `_Email`: `setClientIdentifier`, `addTo/Cc/Bcc`, `setFrom`,
    `setSubject`, `setBody($wrapped ?? $raw)`, `send()`.
 
+### Optional per-send priority (added 2026-08-04)
+
+The trailing **`?int $priority = null`** maps to `_Email::setPriority()`, which emits the
+`X-Priority` / `Importance` / `X-MSMail-Priority` headers. Omit it and nothing changes — the
+dispatcher spreads **named** parameters, so a new trailing optional parameter is backward
+compatible for every existing caller and queued job.
+
+It was added so that moving the error pipeline's **business** escalation email off an inline
+`_Email` and onto this worker did not silently drop the urgency headers (see
+[error-escalation-cron](./error-escalation-cron.md)). Note the sibling
+[`Notification/EmailTemplate/Send`](./notification-email-template.md) path has **no** per-send
+priority — a stored template carries its own single priority column — so urgency there has to live
+in the subject and body.
+
 ### Enqueuing it
 
 `_Worker::runTask('Notification/Email/Send', ['clientIdentifier'=>…, 'subject'=>…, 'body'=>…, …])`
@@ -130,6 +144,11 @@ working recipe — verified in classic + new Outlook:
   are replaced simultaneously, so a `{body}` literal inside the subject can't be re-expanded.
 
 ## Change history
+- 2026-08-04 (**uncommitted/undeployed** at time of writing) — Added an optional trailing
+  `?int $priority = null` to `Send()`, mapping to `_Email::setPriority()`
+  (`X-Priority`/`Importance`/`X-MSMail-Priority`). Backward compatible because the dispatcher
+  spreads named parameters. Added so the error pipeline's business escalation email kept its urgency
+  headers when it moved off an inline `_Email` onto this worker. (jcardinal)
 - 2026-06-24 — Built the DB-driven notification-email mechanism (TRUE-79240): new
   `_Worker_Notification_Email::Send` entry point; branded shell moved out of code (deleted
   `_underscore/Email/Template.php`, which also carried the 1.0 double-render bug) into a reserved

package/package.json

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