toga-ai 1.0.278 → 1.0.280

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [TOGa Desk Architecture](architecture.md) | TOGa Desk is the staff-facing support desk **and field-service platform** (analysts work at `/desk/`). | desk/index.php, desk/includes/loader.php, desk/config.php, desk/includes/controllers/actions.php, desk/includes/controllers/data.php, desk/includes/controllers/modals.php, desk/includes/classes/class.app.php, desk/includes/classes/class.ticket.php, desk/api/index.php, desk/api/resources/tickets.php, crons/tickets.php |
 | [Email-to-Ticket Intake (crons/tickets.php)](features/email-to-ticket-intake.md) | TOGa Desk ingests support email into tickets through a cron-driven IMAP poller (`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). | crons/tickets.php, crons/tickets_prod.php, crons/pipe.php, desk/includes/classes/class.ticket.php |
-| [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
+| [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairorder.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
 | [Ticket Email Notifications (notifications table)](features/notifications.md) | Which TOGa Desk emails fire for a given client is driven **entirely by data**, not code: the `TOGaDeskSupport.notifications` table holds one row per `(clientid, | desk/includes/classes/class.notification.php, crons/tickets.php, crons/tickets_prod.php |
 | [REST API (RPC-over-POST) & API-Key Auth](features/rest-api.md) | TOGa Desk exposes a programmatic API at `desk/api/`. | desk/api/index.php, desk/api/resources/tickets.php, desk/api/resources/assets.php, desk/api/resources/authenticate.php, desk/includes/classes/class.apikey.php, desk/includes/functions.php |
 | [SMB Contract Editing & the clientMspId Corruption Trap](features/smb-contract-editing.md) | The SMB contracts page (`/desk/?route=toga/smbcontracts&togaClientId=<id>`) edits `TOGA_*.SMBContracts` rows via a modal. | desk/template/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/edit.php |

package/knowledge/1.0/apps/togadesk/features/field-service-dispatch.md

@@ -6,7 +6,7 @@ project: TOGa Desk
 client: shared
 type: feature
 status: active
-updated: 2026-06-15
+updated: 2026-07-07
 owners: ["jcardinal", "mhammontree"]
 files:
   - desk/includes/controllers/actions/central/
@@ -16,6 +16,7 @@ files:
   - desk/template/pages/central.php
   - desk/template/pages/central/view.php
   - desk/template/modals/central/addTracking.php
+  - library/app/model/togadesk/repairorder.php
   - library/app/model/togadesk/repairordertracking.php
   - library/app/api/carrier/ups.php
 related:
@@ -90,6 +91,26 @@ always confirm the client arm before changing shared central logic.
   `controllers/actions/central/*.php` (the default fallback). Check both when tracing an action.
 - Status recomputation is centralized in `updateStatus()` — write paths that bypass it can leave
   an order in an inconsistent state.
+- **`updateStatus()` / `qqStatus()` silently overwrite status via a raw `UPDATE`** (no
+  `repair_order_history` / `repair_order_notes` row). `qqStatus()`
+  (`library/app/model/togadesk/repairorder.php` ~L356) is a computed SQL `CASE` that
+  recomputes `repair_orders.status` from technician / dispatch / ETA / parts data on every
+  `updateStatus()` call (fired by `scheduleDispatch`, `technicianOnsite`, `technicianEnRoute`,
+  `awaitingDispatch`, `reworkAwaitingScheduling`, and part flows). If a status is not
+  explicitly gated inside `qqStatus()`, it will be recomputed away with no audit trail — this
+  is **shared, client-agnostic** logic (no tenant conditional), so a change hits every
+  repair-order client.
+- **Hold states must be gated in `qqStatus()` or they are dropped.** There are six `HOLD_*`
+  constants; `qqStatus()` has hold gates that collapse recognized holds to base `STATUS_HOLD`.
+  TRUE-80060 fixed both `ONSITE_REPAIR`/`ONSITE_SERVICE`-branch gates (~L389, ~L429) recognizing
+  only 2 of the 6. **KNOWN REMAINING GAP:** the `DEPOT_REPAIR` branch (~L799) has **no hold gate
+  at all**, so a depot order set to any hold is still silently recomputed out of hold — a
+  follow-up ticket is needed. (DOE surfacing + full detail:
+  [NYCDOE Hold-Status Sync](../../../../clients/nycdoe/features/hold-status-sync.md).)
+- **The hold sub-reason is lost from `repair_orders.status` after a recompute.** `qqStatus()`
+  collapses all six hold variants to base `HOLD`; the specific sub-reason persists only in
+  `repair_order_notes.newstatus`. Badges/reports/filters reading `repair_orders.status`
+  directly cannot distinguish the variants.
 - Cross-database context: some central data controllers switch the DB link to a client database
   (`App_Model_Client::changeDbLinkToClientDatabase()`).
 - **UPS carrier-account dropdown is NOT honored by the shipment API call.** In
@@ -105,6 +126,11 @@ always confirm the client arm before changing shared central logic.
   account-location map noted under *UPS shipment / carrier-account billing*.
 
 ## Change history
+- 2026-07-07 — TRUE-80060: documented the shared `qqStatus()`/`updateStatus()` status-recompute
+  hold gates (in `library/app/model/togadesk/repairorder.php`) — silent raw-`UPDATE` overwrite,
+  hold states must be gated or dropped, the six-hold-variant collapse to base `STATUS_HOLD`, and
+  the untouched `DEPOT_REPAIR`-branch gap (follow-up needed). Added `repairorder.php` to files.
+  (mhammontree)
 - 2026-06-15 — documented UPS Prepare Shipment flow: CARRIER_ACCOUNTS dropdown vs hardcoded
   SHIPPER_NUMBER, and the gotcha that the dropdown selection is never forwarded to the UPS API
   (always bills Agilant). Agilant account migrated 135FV5 → 8696XA. (mhammontree)

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-06-18
-owners: ["dfranks"]
+owners: ["dfranks", "jcardinal"]
 files:
   - _underscore/Database.php
   - _underscore/ApiRequest.php
@@ -62,6 +62,17 @@ Engine InnoDB, `utf8mb4_unicode_ci`.
 
 None — uniform across clients; only the `<Id>` suffix differs.
 
+## Related shared clusters (not per-client)
+
+Alongside the three per-client aliases and the shared **Core** cluster, a dedicated shared
+**Cache** cluster was added (2026-07-07): `Core.Databases` id **145**, `_underscore` alias
+`DB_CACHE`, `CACHE_DATABASE_ID = 145`. It is modeled like Core (a single shared cluster, **not**
+per-client), region-aware (1=us-east-1, 2=us-west-2, 3=eu-west-1) with per-region `DatabaseHosts`
+(`hostCluster` DevOps-TBD). It exists to keep cache churn off Core and backs the api2
+[multi-client data retrieval](../../api2/features/cross-client-data-retrieval.md) engine. Boot
+registration is region-aware in `api2/Controller/Index.php`; the alias const is in `api2/_.php`.
+`Records.ttlCache` (TINYINT UNSIGNED, default 15) governs cache TTL.
+
 ## Gotchas / known issues
 
 - **The "logs DB write trap" (local dev).** A laptop usually imports only `Client_<Id>`, not
@@ -82,6 +93,8 @@ None — uniform across clients; only the `<Id>` suffix differs.
 
 ## Change history
 
+- 2026-07-07 — Noted the new shared **Cache** cluster (`Databases` id 145, alias `DB_CACHE`,
+  region-aware) added for the api2 cross-client retrieval engine. (jcardinal)
 - 2026-06-18 — Documented after the `Logs_Growrk`/`Logs_Aig` local 500s while testing the
   NetSuite TOGa Supply wrappers; created the missing local log schemas structure-only. (dfranks)
 

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

@@ -3,6 +3,8 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
+| [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, api2/_.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql |
+| [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple languages without forking the schema or breaking English consume | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |

package/knowledge/2.0/apps/api2/features/cross-client-data-retrieval.md

@@ -0,0 +1,120 @@
+---
+title: Multi-Client (Cross-Client) Data Retrieval
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: draft
+updated: 2026-07-07
+owners: [jcardinal]
+files:
+  - api2/Component/Api/CrossClient/CrossClient.php
+  - api2/Component/Api/V2/V2.php
+  - api2/Controller/Index.php
+  - api2/_.php
+  - _underscore/Model/Cache/Table.php
+  - _underscore/Model/Cache/Tables/Client.php
+  - dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql
+  - dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql
+related:
+  - ./encrypted-user-uuid-auth-handoff.md
+  - ../../_underscore/features/per-client-database-connections.md
+  - ../../_underscore/features/acl-permission-chain.md
+---
+
+## What it is
+
+A single authenticated V2 GET listing can return records across **many** clients (designed for
+1000+) that the caller is entitled to, honoring **each target client's own ACL**. It is triggered
+by a non-empty `client` query-string option on a GET listing; without that option the ordinary
+single-client path is byte-for-byte unchanged.
+
+Because client DBs live on **different clusters**, a cross-DB JOIN/UNION is impossible. The feature
+is a **scatter-gather** engine: it fans out to each entitled client's own V2 API, merges the
+streams, and caches the result per-user on a dedicated Cache cluster.
+
+> **Status: code-complete + reviewer-hardened, NOT yet runtime-tested.** Result rows are stored as
+> a JSON `rowData` column (deliberate v1 deviation from real typed columns). Phases 4 (single-record
+> cross-client), 5 (worker2 page-ahead prefetch), and 7 (live load test / verify `_Query`/`_Database`
+> method names against a running instance) are open. Per-client token hardening (§0) is an
+> owner-accepted deferred risk.
+
+## How it works
+
+Entry point is `_Component_Api_CrossClient` (`api2/Component/Api/CrossClient/CrossClient.php`),
+delegated to from a guard at the **top** of the `ACTION__LIST` case in
+`_Component_Api_V2::processRoutePairs()`: when `isCrossClientRequest($httpOptions)` is true (a
+non-empty `client` option), it calls `handleListing()`, merges result rows into `$outData` and meta
+into `$this->response->meta`, sets status 200, and breaks. The guard is **inert** on ordinary
+single-client GETs.
+
+1. **resolveScope** — the caller's entitled clients resolve via the `Users_Clients` bridge
+   (`Users.homeClientUserId` maps one home user to per-client user records across tenant DBs); each
+   target yields a minted per-client identity.
+2. **queryHash** — SHA-256 of the normalized query; the cache key.
+3. **Build lock** — a named `GET_LOCK` (`tablecache:<clientId>:<userId>:<hash>`) prevents duplicate
+   concurrent builds.
+4. **Fan out** — a two-phase concurrent HTTP handshake per client (see
+   [encrypted-user-uuid-auth-handoff](./encrypted-user-uuid-auth-handoff.md)): Phase A mints an
+   access token, Phase B issues the authenticated GET.
+5. **Watermark k-way merge** — client streams are merged into a globally-correct sort order using a
+   watermark (`safeRowCount`/`keyBeyond`); a `deepen` loop pulls more from lagging streams, capped
+   by a 50-iteration backstop.
+6. **Cache build/serve** — rows are cached on the Cache cluster; `servePage` emits a keyset page.
+
+### Total order + keyset pagination (V2 query builder, Phase 0a/0b)
+
+Cross-client global sort correctness requires each client's stream to be a **total order**:
+- **0a** — the LIST query builder always appends a **primary-key ASC tiebreaker** to `ORDER BY`
+  (also improves single-client determinism).
+- **0b** — a new keyset/seek pagination mode runs alongside offset mode; it engages **only** when
+  the caller passes `seekValue` + `seekId` options. It injects a seek `WHERE` predicate (V2.php
+  ~line 3782) and switches `LIMIT` from offset to `recordsPerPage` (~line 3861). The composite
+  unique sort key is `(sortfield, clientId, primaryKeyId)`.
+
+### Query-string forwarding (load-bearing gotcha)
+
+V2 parses list options (`fields`/`where`/`sort`/`join`/`group`…) from the **raw** query-string
+values into structured `$httpOptions` — re-serializing the parsed array does **not** round-trip.
+The fan-out therefore forwards the caller's **original** `$_SERVER['QUERY_STRING']` through an
+explicit **allowlist** of forwardable keys (`fields, where, sort, group, distinct, join, ojoin,
+depth, calcDepth, _`), re-stamping `recordsPerPage`, `seekValue`/`seekId`, and a fresh
+`transactionId` per client. The allowlist (not a denylist) prevents internal flags like
+`surface`/`debug` from leaking into sub-requests.
+
+### Cache cluster
+
+A new dedicated **Cache** cluster (Core-style shared cluster, `Databases` id **145**, alias
+`DB_CACHE`, `CACHE_DATABASE_ID = 145`) keeps cache churn off Core. It is region-aware
+(1=us-east-1, 2=us-west-2, 3=eu-west-1) with per-region `DatabaseHosts`; `hostCluster` values are
+DevOps TBD. Boot registration lives in `api2/Controller/Index.php`; the alias const in `api2/_.php`.
+See [per-client-database-connections](../../_underscore/features/per-client-database-connections.md)
+for how it sits among the shared/per-client clusters.
+
+## Key rules
+
+- **Triggered only by a non-empty `client` option** — single-client GETs are unaffected.
+- **Each target client's ACL is honored** via a minted per-client identity, not a global aggregate
+  view. This preserves ACL fidelity across tenants.
+- **Every outbound sub-request needs its own globally-unique `transactionId`** — the API enforces
+  uniqueness; it is the load-bearing idempotency/audit key across Core + Client logs.
+- **Forward the original query string, not the parsed options** — parsed `$httpOptions` do not
+  round-trip through re-serialization.
+- `MAX_CONCURRENT_CLIENT_FETCHES = 25` bounds fan-out concurrency (PHP-FPM has no in-process
+  concurrency, so transport is an HTTP pool via `curl_multi`).
+
+## Gotchas
+
+- **Cross-client output row shape must match single-client.** Served rows are cast to `(object)` in
+  `servePage` so payload interceptors reading `$row->prop` don't throw — the single-client path
+  emits `(object)$outRow`.
+- **The X-Cross-Client / X-Cross-User custom-header transport was a dead stub** — the V2 engine
+  never reads such headers. The real transport is the two-phase encrypted-UUID auth handshake.
+- **`curl_multi` busy-spin guard** — both multi loops `usleep(100)` when
+  `curl_multi_select() === -1`.
+
+## Change history
+- 2026-07-07 — Initial capture: scatter-gather cross-client retrieval engine (orchestrator, watermark
+  k-way merge, keyset pagination Phase 0a/0b, `client`-option delegation, Cache cluster id 145).
+  Code-complete + reviewer-hardened, not yet runtime-tested. (jcardinal)

package/knowledge/2.0/apps/api2/features/encrypted-user-uuid-auth-handoff.md

@@ -0,0 +1,54 @@
+---
+title: Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-07
+owners: [jcardinal]
+files:
+  - api2/Component/Api/CrossClient/CrossClient.php
+related:
+  - ./cross-client-data-retrieval.md
+---
+
+## What it is
+
+`POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**:
+given an encrypted `{client, user}` UUID pair, it mints a fresh access token for that client+user
+without the caller holding the target client's credentials. It is what the scatter-gather
+[cross-client data retrieval](./cross-client-data-retrieval.md) engine uses to authenticate each
+per-client sub-request.
+
+## How it works
+
+- The encrypted `{client, user}` pairs are produced during **normal** auth: `/auth/api` and
+  `/auth/login` emit them as `data.clients[].encrypted.{client, user}`, encrypted with
+  `KEY_API_SECRET_REFRESH_TOKEN`.
+- The route reads `$httpPayload->client` and `$httpPayload->user` (the encrypted UUIDs) from the
+  **JSON body**, decrypts them against the API secret rotation keys, and mints an access token.
+- The token is returned at `response data.tokens.access`.
+
+### Two-phase fan-out handshake (as used by cross-client retrieval)
+
+- **Phase A** — concurrent `POST /auth/encrypted-user-uuid` with the minted `{client, user}`
+  encrypted-UUID pair in the JSON body → read `data.tokens.access`.
+- **Phase B** — concurrent authenticated `GET` with `Authorization: Bearer <token>`.
+- Every request (both phases) carries its own globally-unique `transactionId` (query string); the
+  API enforces uniqueness.
+
+## Key rules
+
+- **Identity source of truth is the `Users_Clients` bridge** — `Users.homeClientUserId` maps one
+  home user to its per-client user records across tenant DBs; that is where the per-client UUIDs
+  come from.
+- **Never store or log the encrypted UUID values** — they are credentials; document where they live
+  (`data.clients[].encrypted`), never the value.
+- The encrypted pairs are encrypted with `KEY_API_SECRET_REFRESH_TOKEN` (rotation keys); decryption
+  tolerates the rotation set.
+
+## Change history
+- 2026-07-07 — Documented `/auth/encrypted-user-uuid` as the cross-client/SSO identity-handoff route
+  and its two-phase use by the cross-client fan-out engine. (jcardinal)

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 22 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 9 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/knowledge/clients/nycdoe/features/hold-status-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-06-29
+updated: 2026-07-07
 owners: [mhammontree]
 files:
   - worker/crons/sync/nycdoe/send_ticket_updates.php
@@ -25,9 +25,24 @@ related:
 DOE ticket **hold** status must round-trip between ServiceNow (SNOW) and TOGaDesk and
 **stay held** — holds are SLA-bearing in both systems. This doc covers the bidirectional
 hold-status sync for DOE Incidents (INC) and Request Items (RITM), the authoritative
-business rule that governs it, and the TRUE-79922 fix that made hold persist. It is the
-status-sync companion to the broader [ServiceNow / ASN integration](servicenow-integration.md)
-doc; the underlying crons and `App_Api_NYCDOEV2` plumbing are documented there.
+business rule that governs it, and the two independent defects that let holds silently
+revert. It is the status-sync companion to the broader
+[ServiceNow / ASN integration](servicenow-integration.md) doc; the underlying crons and
+`App_Api_NYCDOEV2` plumbing are documented there.
+
+> **Two distinct hold-revert paths — different repos, mechanisms, and revert targets.**
+> A held DOE order could be knocked out of hold by *either* of two unrelated code paths;
+> both had to be closed:
+> - **TRUE-79922 (worker crons):** the SNOW-side `state` 3⇄2 oscillation — an outbound
+>   self-clobber pushing `state:2` over a held `state:3`, plus an inbound wrong-field read
+>   — reverted the order to **"In Progress"**. Fixed; see *Change history* + the sections
+>   below. (Still pending deploy at time of writing.)
+> - **TRUE-80060 (`library` shared model):** the local `qqStatus()` recompute silently
+>   demoting the order to a scheduling status (**"Orders Assigned / Awaiting Scheduling"**,
+>   `ORDER_ASSIGNED_AWAITING_SCHEDULING`) whenever `updateStatus()` ran. Fixed; see
+>   *Local status recompute* below. This defect is in a **shared, client-agnostic** model
+>   method — surfaced by DOE but affecting every TogaDesk repair-order client; the durable
+>   mechanism lives in [Field-Service Dispatch](../../../1.0/apps/togadesk/features/field-service-dispatch.md).
 
 > DOE "tickets" are **`repair_orders`** rows (`App_Model_TogaDesk_RepairOrder`,
 > `db_togadesk` / legacy `TOGaDeskSupport`, **clientid = 16**) — NOT the generic `tickets`
@@ -82,6 +97,26 @@ doc; the underlying crons and `App_Api_NYCDOEV2` plumbing are documented there.
   technician. This mirrors the INC cron, which already sends `u_eta` while holding — keeping
   scheduling metadata flowing while the hold STATE stays asserted.
 
+### Local status recompute (`qqStatus` / `updateStatus`) — TRUE-80060
+- `App_Model_TogaDesk_RepairOrder::qqStatus()` is a computed SQL `CASE` expression that
+  `App_Model_TogaDesk_RepairOrder::updateStatus()` writes to `repair_orders.status`. It
+  recomputes status from technician / dispatch / ETA / parts data. Both live in the shared
+  model `library/app/model/togadesk/repairorder.php` (`qqStatus` ~L356, `updateStatus` ~L181)
+  — **no tenant conditional**, so this path is not DOE-specific.
+- `updateStatus()` is called from the togadesk central actions `scheduleDispatch`,
+  `technicianOnsite`, `technicianEnRoute`, `awaitingDispatch`, `reworkAwaitingScheduling`
+  (and the part flows). Any of these recomputes `repair_orders.status` via `qqStatus()`.
+- `qqStatus()` has two "hold gates" that short-circuit the recompute when an order is held.
+  Before TRUE-80060 they recognized only **2 of the 6** `HOLD_*` constants
+  (`HOLD_AWAITING_APPROVAL`, `HOLD_OTHER`); the base `STATUS_HOLD` and the other three
+  (`HOLD_AWAITING_CUSTOMER_APPROVAL`, `HOLD_ADDITIONAL_INFO_NEEDED`,
+  `HOLD_AWAITING_CUSTOMER_CONTACT`) fell through and were silently recomputed into a
+  scheduling / WIP status. The fix (`repairorder.php` ~L389 and ~L429) expanded **both**
+  gates to all six `HOLD_*` constants, still collapsing to base `STATUS_HOLD` (matching the
+  pre-existing behavior of the two that already worked).
+- The revert is **silent** — `updateStatus()` writes via a raw `UPDATE` with **no**
+  `repair_order_history` / `repair_order_notes` entry.
+
 ## Reference facts (DOE sync debugging)
 
 - **SNOW request/response logs:** logged to the legacy `Logs` schema, **`API` table**
@@ -108,8 +143,33 @@ doc; the underlying crons and `App_Api_NYCDOEV2` plumbing are documented there.
   on native `state` only.
 - Holds are **never auto-released** — if a SNOW user manually changes status, the outbound
   cron correctly re-asserts On Hold; that is intended, not a bug. Clear the hold in TOGaDesk.
+- **Diagnosing which writer dropped a hold:** `repair_order_history`
+  (`repairid, userid, dtStamp, note`) records *user-driven* status changes. A hold reverting
+  with **no** history row between the hold and the revert = a raw-`UPDATE` writer
+  (`updateStatus`/`qqStatus`), **not** the note/reply path (`class.repair.php::addNotes` syncs
+  replies to SNOW but never writes `repair_orders.status`) and **not** the worker inbound cron
+  (`process_tickets.php` contains no reference to `ORDER_ASSIGNED_AWAITING_SCHEDULING`). This
+  is how TRUE-80060 was pinned to `qqStatus()` rather than the SNOW round-trip.
+- **KNOWN REMAINING GAP (needs a follow-up ticket):** both `qqStatus()` hold gates live inside
+  the `type IN (ONSITE_REPAIR, ONSITE_SERVICE)` branch. The `DEPOT_REPAIR` branch
+  (`repairorder.php` from ~L799) has **no hold gate at all**, so a `DEPOT_REPAIR` order set to
+  any hold status is still silently recomputed out of hold by `updateStatus()` — the same
+  class of bug, untouched by TRUE-80060.
+- `qqStatus()` collapses all recognized hold sub-statuses to base `HOLD` in
+  `repair_orders.status`; the specific hold **sub-reason persists only in
+  `repair_order_notes.newstatus`**. Any status badge / report / filter reading
+  `repair_orders.status` directly cannot distinguish the six hold variants after a recompute.
 
 ## Change history
+- 2026-07-07 — TRUE-80060: closed the **second** DOE hold-revert path — the local
+  `qqStatus()` recompute (in the shared model `library/app/model/togadesk/repairorder.php`)
+  silently demoting held orders to `ORDER_ASSIGNED_AWAITING_SCHEDULING` whenever
+  `updateStatus()` ran. Root cause: both `qqStatus()` hold gates recognized only 2 of the 6
+  `HOLD_*` constants; expanded both (~L389, ~L429) to all six, collapsing to base
+  `STATUS_HOLD`. Separate from TRUE-79922 (different repo/mechanism/revert target). Documented
+  the raw-`UPDATE` silent-revert, the `repair_order_history`-gap debugging technique, and the
+  untouched `DEPOT_REPAIR`-branch gap (follow-up ticket needed). php -l clean; php-reviewer 0
+  critical / 0 blocking. (mhammontree)
 - 2026-06-29 — TRUE-79922: fixed DOE holds never persisting (reverted to In Progress, broke
   SLA reporting both sides). Two coupled defects: outbound self-clobber (`send_ticket_updates.php`
   unguarded Assigned→In-Progress pushing `state:2` over a held `state:3`) and inbound

package/package.json

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