toga-ai 1.0.309 → 1.0.311

package/knowledge/1.0/apps/togadesk/features/email-to-ticket-intake.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-07-09
-owners: ["jcardinal", "dfranks"]
+owners: ["jcardinal", "dfranks", "mhammontree"]
 files:
   - crons/tickets.php
   - crons/tickets_prod.php
@@ -40,6 +40,19 @@ TOGa Desk ingests support email into tickets through a cron-driven IMAP poller
 3. **Parse & route (`emailToTicket()`):** extract from/to/cc/subject/body (with encoding fixes);
    match an existing ticket via `In-Reply-To` + `Message-ID` headers and **plus-addressing**
    (`support+<ticketnum>@…`). Matched ⇒ `addReply()`; otherwise ⇒ `add()`.
+   - **Noise suppression (before any ticket/attachment is created):** both feeders drop known
+     automated no-noise mail via the shared helper
+     `Ticket::isSuppressedNoiseEmail(?string $from, ?string $subject): bool` (static, in
+     `class.ticket.php`). It returns true only when the sender matches `/^no-?reply@/` **AND**
+     the subject starts with `staples po ` — both required so a real person is never blocked, and
+     the sender check is **domain-agnostic** (matches `noreply@togatech.com` /
+     `noreply@goagilant.com` and survives future sender-domain flips; the Staples PO alert sender
+     flipped `goagilant.com → togatech.com` on 2026-06-02). Wired into BOTH intake feeders:
+     `crons/tickets.php` adds it as one more `&&`-clause in the existing IMAP intake guard
+     (alongside the delivery-status / `MAILER-DAEMON` / Compass auto-reply filters);
+     `crons/pipe.php` uses it as an early guard-and-`exit(0)` right after the `$from`/`$subject`
+     parse. Each feeder logs a "suppressed" line. (TRUE-79975 — ~815 such alerts since Jun 2024,
+     ~704 of them landing in the dept-1 "Support Desk" catch-all and being closed by hand.)
 4. **Side effects:** auto-create a user when the sender domain maps to an existing client; assign
    to a department via the department email lookup; save attachments locally then push to **S3**
    (`App_Cloud::copyFileToS3()`, bucket `asifiles`); optionally generate Talos/TogaIQ summaries.
@@ -49,7 +62,12 @@ TOGa Desk ingests support email into tickets through a cron-driven IMAP poller
 ## Data model
 Writes `tickets`, `tickets_replies`, attachment `files`; reads config from the `config` table
 (`tickets_defaultdepartment`, `tickets_defaultclient`, `auto_close_tickets`,
-`email_from_address`, `timezone`). Department routing keys on `tickets_departments.email`.
+`email_from_address`, `timezone`). Department routing keys on a `tickets_departments.email`
+`LIKE` match against the To/CC addresses; **anything unmatched falls through to config
+`tickets_defaultdepartment` (= dept 1 "Support Desk" catch-all) and `tickets_defaultclient`** —
+which is why unrouted/automated mail piles into "Support Desk". There is **no allowlist/blocklist
+config framework**: noise filtering is ad-hoc inline guards in the crons (the hardcoded Compass
+"Automatic reply:" filter and now `isSuppressedNoiseEmail`).
 
 ## Gotchas / known issues
 - **`$processName` guard:** `tickets.php` throws if executed directly instead of via an env
@@ -59,7 +77,13 @@ Writes `tickets`, `tickets_replies`, attachment `files`; reads config from the `
 - **Loop prevention** only excludes FROM==department-TO addresses; CC/reply-all across multiple
   department addresses can still loop.
 - **Auto-reply filters** are partly hardcoded (e.g. ignore `TechHub@compass-usa.com`
-  "Automatic reply:" messages).
+  "Automatic reply:" messages), and now the `isSuppressedNoiseEmail` Staples-PO filter — there
+  is no config-driven allow/block list, so each new noise source is another inline guard.
+- **`Ticket::extractEmail()` returned an undefined offset on a no-match** (bare `$matches[0]`).
+  With a sender-less/malformed email this codebase promotes the warning to a thrown error
+  (`E_ALL` + `App_Error::handleError`), so an intake cron could **halt**. Hardened to
+  `return $matches[0] ?? '';` (TRUE-79975) — important because `isSuppressedNoiseEmail` routes
+  nullable/malformed sender input through `extractEmail`, putting this latent bug on the hot path.
 - Attachments are deleted locally immediately after the S3 upload with **no retry** if S3 fails.
 - **`adminid` clobber on reply routing:** after `emailToTicket()` sets `$data['adminid']` from
   the FROM address (~line 1407), an asset lookup (~line 1437-1442) overwrites it with the
@@ -69,6 +93,10 @@ Writes `tickets`, `tickets_replies`, attachment `files`; reads config from the `
   classification. See the ticket-lifecycle doc.
 
 ## Change history
+- 2026-07-09 — added `Ticket::isSuppressedNoiseEmail()` noise suppression (no-reply sender + "Staples PO"
+  subject) wired into both feeders before ticket creation; hardened `extractEmail()` no-match to
+  `''`; documented the `tickets_defaultdepartment` → "Support Desk" catch-all fall-through
+  (TRUE-79975) (mhammontree)
 - 2026-07-09 — documented the `emailToTicket()` adminid-overwrite reply misclassification
   (TRUE-80114 planning investigation) (dfranks)
 - 2026-06-15 — documented from a source read of `crons/tickets*.php` and `emailToTicket()` (jcardinal)

package/knowledge/clients/prudential/INDEX.md

@@ -6,6 +6,6 @@
 | [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, worker/crons/toga2/prudential/transmissions_to_dell.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_india.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_usa.php |
 | [Prudential: Device information import + unit→contact linking (import_device_information.php)](features/device-information-import-and-contact-linking.md) | 1.0 | Prudential's **device-sync** cron (`worker/crons/toga2/prudential/import_device_information.php`) pulls device/asset records (from ServiceNow / the Dell CMDB fe | worker/crons/toga2/prudential/import_device_information.php, worker/crons/toga2/prudential/backfill_unit_contacts.php, dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql |
 | [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php |
-| [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php |
+| [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/notifications/reports/prudential_exception_report.php |
 | [Prudential Financial](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |
 | [Prudential: Dell ASN failed POST backfill replay](workflows/dell-asn-backfill-replay.md) | 2.0 | When Dell ASN POSTs fail in bulk (e.g. |  |

package/knowledge/clients/prudential/features/transmit-ordershipped-email.md

@@ -6,13 +6,15 @@ project: Worker
 client: prudential
 type: client-feature
 status: active
-updated: 2026-07-06
+updated: 2026-07-10
 owners: ["rgirish"]
 files:
   - worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php
   - worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php
+  - worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php
   - worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php
   - worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php
+  - worker/crons/notifications/reports/prudential_exception_report.php
 related:
   - ../profile.md
 ---
@@ -47,11 +49,37 @@ Iterates the same POs collected in Phase 1. For each:
 - `Client_Prudential.PurchaseOrders.c_dtEmailSentOrderShipped` — stamped after email send
 - Both fields are checked by `prudential_exception_report.php` to detect discrepancies
 
+**⚠ `c_dtTransmittedOrderClosedUpdateToPrudential` is an OVERLOADED column (discovered 2026-07-10).**
+It is written by TWO different crons for THREE distinct terminal outcomes:
+- **Delivered / Closed-Complete** — stamped by `transmit_closecomplete_updates_prudential.php`,
+  gated on an ASN with a `DELIVERED` tracking number, and **pairs with a customer email**
+  (`c_dtEmailSentOrderClosed`). *Only this path owes an email.*
+- **Rejected / Cancelled** — stamped by `transmit_rejected_cancelled_updates_prudential.php`,
+  with **no ASN join**; it only pushes a ServiceNow "rejected"/"cancelled" RITM update and
+  **sends no customer email**.
+
+So a no-ASN Rejected/Cancelled PO shows a "delivered" transmit stamp with `c_dtEmailSentOrderClosed`
+NULL forever — that is correct, not a failure. Any query keyed on this column alone will
+conflate the two. Example: REQ4448998 (PO 26544) was a Rejected order with no ASN/tracking and
+was a false positive in the "Order Delivered Email Not Sent" report.
+
 ## Exception report link
 `worker/crons/notifications/reports/prudential_exception_report.php` flags any PO where
 `c_dtTransmittedOrderShippedUpdateToPrudential IS NOT NULL` AND `c_dtEmailSentOrderShipped IS NULL`
 as "Order Shipped Email Not Sent". This appears daily in the Prudential REQ Processing Report email.
 
+**Order-Delivered discrepancy query — DELIVERED gate required (fixed 2026-07-10, ~line 463-474).**
+The Order-Delivered discrepancy query originally filtered only on
+`c_dtTransmittedOrderClosedUpdateToPrudential IS NOT NULL AND c_dtEmailSentOrderClosed IS NULL`
+with no shipment/stage filter. Because that column is overloaded (see Data model), every
+Rejected/Cancelled Dell PO was flagged as an "Order Delivered Email Not Sent" failure even though
+it never owed a delivery email. Fix: add
+`AND EXISTS (AdvanceShippingNotices → ASNItems → ASNItemUnits → ASNItemUnits_TrackingNumbers →
+TrackingNumbers WHERE purchaseOrderId = PurchaseOrders.id AND TrackingNumbers.status = 'DELIVERED')`
+— this mirrors the closecomplete cron's own Phase-1 email precondition, so the report only flags
+orders that genuinely qualified for a delivery email. Over 2026-07-01..07-09 this dropped 6 false
+positives (25 → 19 flagged) while retaining all 19 genuine discrepancies.
+
 ## Sibling scripts sharing this pattern
 The same two-phase (transmit-then-email) shape and the same PDF-fetch fragility exist in three
 sibling crons, all fixed the same way this session (2026-07-06):
@@ -65,6 +93,21 @@ sibling crons, all fixed the same way this session (2026-07-06):
 
 ## Gotchas / known issues
 
+**ROOT CAUSE (third regression) — `App_Database::escapeString()` does not exist → fatal on the 404 auto-create path (fixed 2026-07-10):**
+`createAssetAndRetryPut()` in **both** `transmit_ordershipped` and `transmit_closecomplete`
+(~line 158) called `App_Database::escapeString($serialNumber)`. **That method does not exist** on
+`App_Database` — only `sqlEscape`, `sqlProtect`, and `mysqlRealEscapeString` do. Under the 1.0
+framework's `error_reporting(E_ALL)`, calling a non-existent static method is a **fatal `Error`
+that kills the cron mid-run**. It fires whenever an asset PUT to ServiceNow returns 404
+(`isAssetNotFoundError`) — routine for Breakfix/Reclaim/Refresh returned/replacement assets not yet
+in the Prudential CMDB. The fatal occurs in Phase 1 **after** the transmit flag is stamped but
+**before** the email phase, so the email is permanently stranded (email flag left NULL). This was
+the specific unaddressed trigger of the month-long email-stranding — distinct from, but riding on
+top of, the two-phase design flaw below. **Fix: `escapeString` → `sqlEscape` in both files**
+(`sqlEscape` is already used correctly elsewhere in the same files, e.g. ordershipped line 1386).
+This was flagged as a "latent error" in the 2026-07-06 pre-existing-issues note; it turned out to
+be the live trigger.
+
 **ROOT CAUSE — `file_get_contents` in a 1.0 cron THROWS, it does not return false (discovered 2026-07-06):**
 The 1.0 framework bootstrap sets `error_reporting(E_ALL)` and `App_Error::handleError`
 (`library/app/error.php` ~line 348) converts **every** PHP warning into an `ErrorException`.
@@ -110,8 +153,8 @@ URL was still live in 3 of the sibling files and was corrected this session.
 **Pre-existing issues surfaced this session (NOT fixed — awareness only):**
 - SQL-injection risk: unescaped `$reqNumber` concatenated into a `LIKE '%...%'` query in the
   Phase-2 body of both `transmit_ordershipped` and `transmit_closecomplete`.
-- `transmit_closecomplete` calls `App_Database::escapeString()` (~line 158) which does not exist
-  on `App_Database` (only `sqlEscape` does) — latent error in the `createAssetAndRetryPut` path.
+- (RESOLVED 2026-07-10) `App_Database::escapeString()` at ~line 158 in **both** crons — see the
+  ROOT CAUSE gotcha above; this "latent" error was the actual fatal trigger, now fixed to `sqlEscape`.
 - Separate inbound issue: Dell SR re-POST hitting `ServiceRequests.number` UNIQUE constraint →
   API 400 "Duplicate entry SR129013" (REQ4444748). Not part of the email fix.
 
@@ -132,5 +175,20 @@ stamp (crash hits the next iteration). With multiple New-type POs, a crash on PO
 all subsequent POs in the same run.
 
 ## Change history
+- 2026-07-10 — Third regression of the "Order Shipped / Order Delivered Email Not Sent" symptom.
+  True trigger: `createAssetAndRetryPut()` called the nonexistent `App_Database::escapeString()`
+  (~line 158 in `transmit_ordershipped` + `transmit_closecomplete`) — a fatal `Error` under E_ALL
+  that fired on the ServiceNow 404 asset auto-create path (routine for Breakfix/Reclaim/Refresh),
+  killing Phase 1 after the transmit stamp but before the email. Fixed `escapeString` -> `sqlEscape`
+  in both files (verified by 3 adversarial subagents; php -l clean). Recovered by nulling the
+  transmit flags for 9 stranded shipped POs + 1 closed PO (re-processing is idempotent) — the 9
+  owed shipped emails were confirmed sent 2026-07-10 09:34-09:35.
+  Also: discovered `c_dtTransmittedOrderClosedUpdateToPrudential` is overloaded across
+  Delivered vs Rejected/Cancelled (only Delivered owes an email), and fixed the
+  `prudential_exception_report.php` Order-Delivered discrepancy query to require an EXISTS on a
+  DELIVERED tracking number (drops Rejected/Cancelled false positives; REQ4448998/PO 26544 was one).
+  The structural two-phase stamp-before-email flaw remains **open** — candidate durable fix: stamp
+  the email flag only after a successful send and/or wrap each PO's email phase in try/catch. Not
+  done this session (scoped to the specific trigger) (rgirish)
 - 2026-07-06 — Found the real root cause: `file_get_contents` throws (E_ALL→ErrorException) so the `!== false` guards (incl. the 2026-06-18 one) were never effective. Added `safeFetchPdf()` (try/catch ErrorException → false) + independent per-PDF guards; email now always sends even if a PDF fails. Extended the same fix to `transmit_closecomplete` and both `generate_sales_and_purchase_orders_from_service_requests` scripts, and finished the stale Mac PDF URL fix in the 3 files the 2026-06-18 change missed. Documented the permanent two-phase stranding flaw and the date-bounded-recovery requirement; scope kept to fix-forward (no auto self-heal) by developer decision (rgirish)
 - 2026-06-18 — Fixed 403 crash: corrected Mac PDF URL (`_15.6_v4` → `PrudentialMacSetupGuide.pdf`) and added a `!== false` guard on all S3 fetches in New branch. NOTE (2026-07-06): this guard was ineffective — the exception is thrown inside `file_get_contents`, not returned (rgirish)

package/package.json

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