toga-ai 1.0.879 → 1.0.881

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

@@ -20,4 +20,5 @@
 | [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | Tools (1.0) admin UI to browse/fix Talos KB documents, provision new Bedrock VECTOR KBs (S3 Vectors), and manage transcript-cleanup vocabulary — the human front |
 | [Talos Pricing UI (Contracts, Pricing Dashboard, Usage, Settings + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools) face of the Talos Pricing Platform — Contracts / Pricing Dashboard / Usage / Pricing Settings pages + the estimate engine, reading the Team DB v |
 | [App-Wide Colour Theme (light / dark / auto)](features/theme-light-dark.md) | App-wide light/dark/auto colour theme for the Tools app via a single semantic-token layer (`theme.css`), localStorage-persisted, applied before first paint; ope |
+| [Tools → worker2 Job Bridge (App_Worker::enqueue + reading WorkerJobs.output)](features/worker2-job-bridge.md) | How a 1.0 `tools` page runs 2.0 worker2 work and reads the result back; open before adding any Tools page that triggers a worker action. |
 | [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the Tools 1.0 app deploys/boots on Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023) — AL2023 package migration, INI/fpm session gotchas, git-clone of library |

package/knowledge/1.0/apps/tools/architecture.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: architecture
 status: active
-updated: 2026-09-16
-owners: [jcardinal, kyalamarthi, ajean]
+updated: 2026-09-23
+owners: [jcardinal, kyalamarthi, ajean, mhammontree]
 files:
   - tools/index.php
   - tools/.ebextensions/020_setup_git_libraries.config
@@ -79,6 +79,7 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
 
 ## Gotchas
 
+- **⚠ `tools` runs PHP 8, not 7.2 — check the vhost, not the framework label.** Despite being a 1.0 `App_` app, its vhost lives in the PHP 8 Apache (`DocumentRoot "C:/WWW/tools"`), and `App_Compass::tenantKey(mixed $key)` uses the `mixed` type hint (PHP 8.0+). The trap: `mixed` **passes** `php -l` on 7.2 (parsed as a class name) and only fatals at runtime — "Argument 1 passed to f() must be an instance of mixed, string given". So linting `tools` on 7.2 fails in the dangerous direction: it accepts code that would die.
 - **Plaintext secrets were publicly web-readable (fixed 2026-07-24; rotation still owed).** `config.*.ini` (incl. `config.prod.ini`) holds plaintext production secrets (RDS master password, SMTP, Payeezy, NetSuite). The front controller routed through `index.php` on a `RewriteCond !-f` rule **only**, which is not access control — a direct `GET /config.production.ini` served the file **verbatim**. Fixed 2026-07-24 by adding `<FilesMatch>` `Require all denied` blocks (sensitive extensions incl. `.ini`, and any `config.*`) — see the [1.0 back-end security standard](../../standards/backend-php.md). **Action still owed:** rotate every secret in `config.production.ini` — the file was reachable, so treat all of it as compromised. (Location only — no values recorded here.)
 - **Hardcoded GitHub Personal Access Token committed in plaintext (rotation owed).** `.ebextensions/020_setup_git_libraries.config` contains a GitHub PAT in plaintext, committed to the repo and therefore exposed in git history. **Action owed:** rotate the token and move it to an EB environment property (read via `getenv()`/`$_SERVER`/`$_ENV` per the deploy workflow's clear_env gotcha); a rotation does not un-expose git history. (Location only — no value recorded here.)
 - **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.

package/knowledge/1.0/apps/tools/features/worker2-job-bridge.md

@@ -0,0 +1,68 @@
+---
+title: Tools → worker2 Job Bridge (App_Worker::enqueue + reading WorkerJobs.output)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-09-23
+owners: [mhammontree]
+files:
+  - tools/_/app/worker.php
+related:
+  - ../../../clients/compass-usa/features/people-file-import-admin-page.md
+  - ./mvc-data-access-patterns.md
+  - ../../../2.0/apps/worker2/architecture.md
+  - ../../../2.0/apps/worker2/features/stranded-worker-jobs.md
+---
+
+How a 1.0 `tools` page runs 2.0 worker2 work and reads the result back; open before adding any Tools page that triggers a worker action.
+
+## Summary
+
+`tools` never talks to a third-party system that worker2 already owns. It **enqueues a worker2
+action** and reads the answer out of `Core.WorkerJobs.output`. `App_Worker::enqueue()`
+(`tools/_/app/worker.php`) inserts the `Core.WorkerJobs` row and sends the SQS message.
+
+## How it works
+
+1. Page calls `App_Worker::enqueue($action, $parameters)`.
+2. worker2 picks the job up, runs it, writes the result into `Core.WorkerJobs.output`.
+3. Page polls the row by `workerJobId` and decodes `output`.
+
+**`output` is a LOG LINE wrapping the JSON**, written by `worker2/Controller/Index.php`:
+
+```
+[requestId] Successfully Executed (Ns): {"...json..."}
+```
+
+So find the first `{` and decode from there. If no `{` is present, show a clear error — never an
+empty result — because the wrapper format is worker2's, not a contract.
+
+## Gotchas
+
+- **`enqueue()` has THREE outcomes, not two.**
+  (a) insert fails → `ok=false`, `workerJobId=null`.
+  (b) insert succeeded but the **SQS send failed** → `ok=false` with a **real** `workerJobId` and
+  error "Job row created but SQS dispatch failed".
+  (c) both succeeded → `ok=true`.
+  A caller that tests only `workerJobId === null` reads (b) as success and then shows "still
+  running" forever, because no worker will ever pick that row up. **Test `ok`, not the id.**
+- **`isSuccess IS NULL` means two different things** — running, or abandoned. Same trap as
+  [stranded worker jobs](../../../2.0/apps/worker2/features/stranded-worker-jobs.md).
+- **Tools must not speak SFTP (or any integration worker2 owns).** Decided on CTO review
+  (TRUE-82250). Giving `tools` its own SFTP client would copy a production credential into a
+  second repo (rotation becomes a two-repo change forever), and **`library/phpseclib` is
+  phpseclib 1.x**: it offers only `diffie-hellman-group1-sha1`, `group14-sha1`,
+  `group-exchange-sha1`, `group-exchange-sha256` — no curve25519, no ecdh-sha2. Modern SFTP
+  servers commonly refuse sha1 key exchange, so 1.0 may not negotiate at all where worker2's
+  phpseclib3 can.
+- **Timeouts do not match.** Tools' PHP `max_execution_time` is **120s**. A job enqueued outside
+  the CronScheduler has `cronJobId NULL` and therefore the **300s** action cap, not the cron's
+  `maxExecutionTime`. Never make a page wait for long work — poll, don't block.
+- **Deploy worker2 first.** A Tools page that calls a new action is broken until the action
+  exists.
+
+## Change history
+- 2026-09-23 — Created from TRUE-82250: documented the three `enqueue()` outcomes, the log-line-wrapped `output`, and the CTO decision that tools never speaks SFTP (phpseclib 1.x sha1-only KEX + credential duplication). (mhammontree)

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -6,9 +6,10 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: ["bala", "mhammontree", "tcox", "apeterson", "rgirish"]
+updated: 2026-09-23
+owners: ["bala", "mhammontree", "tcox", "apeterson", "rgirish", "jcardinal"]
 files:
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/ContactEmailAddress.php
   - _underscore/Model/Client/TransferOrderStage.php
@@ -156,6 +157,13 @@ WHERE recordId = 351 AND field = 'c_netsuiteInternalTransferOrderStatus';
 
 `recordId 351` is `transfer-order-stages`; the equivalent row exists per tenant with a **different `id`** but often the **same `uuid`** (both Elite and NYCHH carry `b273f4d1-dac0-4093-ad1d-7c3a526ab894`), the tell that the row came from one shared seed and only one tenant's copy has the wrong flag.
 
+### Nested inherent-child create — parent FK is auto-set, any depth
+
+- V2 auto-sets the child's FK to the parent: first field whose `FIELDOPT_FOREIGNKEY_MODEL` equals the parent class (exact normalized `_Model_Client_` string), then break (`V2.php` ~5211-5221). Payload supplies the OTHER FK only (e.g. bridge row `{ purchaseOrder: { uuid } }` under a transfer order).
+- `processRoutePairs` recurses with `parentModel` (~5284-5300); `lookupInherentChildByFieldName` is rebuilt per record (~3407), so grandchildren work (`transferOrderItems[].purchaseOrderItemsTransferOrderItems[]`).
+- Each level's key must be an `InherentRecordChildren` child of THAT level's record, else it lands in `unknownFields` (~5047).
+- Adding an inherent-child row also inlines that child in the parent's default GET for every client — check deep readers (1.0 NetSuite sync reads depth 5) first.
+
 ## Gotchas
 
 - **Nested write with only a non-identifier field silently creates duplicates.** A duplicate-generating footgun: each write inserts a new empty child and the parent links to a fresh shell (or is left with a NULL FK). It compounds on any cron/integration that writes the same entity repeatedly. Root-caused in production on the Prudential device-sync cron, which sent `contact: {c_employeeXid}` and generated ~893k empty Contact rows (~5,600/day). See [Prudential device import + contact linking](../../../clients/prudential/features/device-information-import-and-contact-linking.md).

package/knowledge/2.0/apps/toga25-supply/features/transfer-orders-page.md

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: [apeterson, bala]
+updated: 2026-09-23
+owners: [apeterson, bala, "jcardinal"]
 files:
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/PanelSelect.tsx
@@ -199,7 +199,7 @@ One `SurfaceOverrides` row, `IS_VISIBLE = '1'`, **client-wide** (`personaId`/`ro
 
 **Two record requests, not one.** The modal reads the lines from the nested route `GET /v2/transfer-orders/{uuid}/transfer-order-items`, with the child route read from the items surface's `config.childRoute` so the FE never hardcodes it.
 
-> ⚠ **The reason for the second request is GONE — the read path was not revisited.** This build declined to add the `InherentRecordChildren` row (it changes the default response shape for *every* existing `/transfer-orders` caller, including the 1.0 NetSuite importer). **That decision was reversed later:** `Core.InherentRecordChildren` row **152** now declares `transfer-orders` (312) → `transfer-order-items` (313), so `/transfer-orders` **does** inline `transferOrderItems` today. The modal still makes two calls; collapsing it to one is available but unclaimed work. See [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).
+> ⚠ **The reason for the second request is GONE — the read path was not revisited.** This build declined to add the `InherentRecordChildren` row (it changes the default response shape for *every* existing `/transfer-orders` caller, including the 1.0 NetSuite importer). **That decision was reversed later:** `Core.InherentRecordChildren` row **150** now declares `transfer-orders` (312) → `transfer-order-items` (313), so `/transfer-orders` **does** inline `transferOrderItems` today. The modal still makes two calls; collapsing it to one is available but unclaimed work. See [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).
 
 **The record fetch raises `calcDepth` to 2.** `_Model_Client_Location` exposes `_addressLine1/_addressLine2/_addressCity/_addressState/_addressZip` as `FIELD_SQL` calculated fields. One FK hop out from the order they need `calcDepth 2`; at the default of 1 they come back **NULL silently** rather than erroring.
 
@@ -321,7 +321,7 @@ Related data-shape facts found the same day:
 
 #### The whole transfer is ONE POST — lines nested under `transferOrderItems`
 
-`hooks/useCreateTransferOrder.ts`. Header **and** every line go out in a **single `POST /transfer-orders`**, with the lines nested under the key **`transferOrderItems`**. This is possible because `Core.InherentRecordChildren` row **152** now makes `transfer-order-items` (313) an inherent child of `transfer-orders` (312).
+`hooks/useCreateTransferOrder.ts`. Header **and** every line go out in a **single `POST /transfer-orders`**, with the lines nested under the key **`transferOrderItems`**. This is possible because `Core.InherentRecordChildren` row **150** now makes `transfer-order-items` (313) an inherent child of `transfer-orders` (312).
 
 **Why one request, not three.** An earlier draft posted the header and then each line separately and could leave a **half-written transfer** behind on a mid-sequence failure. One API request is one API transaction — the front controller commits the umbrella connection on `isSuccess` and rolls the data back on failure — so the nested POST is all-or-nothing **without** a scripted endpoint.
 
@@ -331,6 +331,13 @@ Related data-shape facts found the same day:
 
 This closes both **required POST changes** recorded on 2026-09-02: `number` is no longer sent (so `FIELD_AUTOINCREMENT` mints the `TA100000` sequence) and the lines ride nested in the same request (so `_Model_Client_TransferOrder::postPost` sees them when it reads the order back for the NetSuite push) — see [Toga TransferOrder → NetSuite Push](../../worker2/features/netsuite-transferorder-outbound-push.md).
 
+**PO links ride the same POST (2026-09-23).** `CreateTransferOrderModal/hooks/useCreateTransferOrder.ts`:
+- header: `purchaseOrdersTransferOrders: [{ purchaseOrder: { uuid } }]` → bridge `PurchaseOrders_TransferOrders` (record **325**; inherent child of 312 via row 151).
+- each `transferOrderItems[]` line: `purchaseOrderItemsTransferOrderItems: [{ purchaseOrderItem: { uuid } }]` → bridge `PurchaseOrderItems_TransferOrderItems` (record **329**; inherent child of 313 via `dbchanges2/Core/2026-09-23d`). Source: `TransferOrderDraftLine.purchaseOrderItemUuid` ← `PurchaseOrderItemRow.purchaseOrderItemUuid`.
+- V2 auto-sets each bridge's parent-side FK; payload supplies only the other side. Engine: [nested-relationship-writes](../../api2/features/nested-relationship-writes.md).
+- Direct `purchaseOrder: { uuid }` (`TransferOrders.purchaseOrderId`) is **kept** — the record modal's PO deep link reads `transferOrder.purchaseOrder.uuid`.
+- Use 325/329, never the reverse-named twins 326 `TransferOrders_PurchaseOrders` / 330 `TransferOrderItems_PurchaseOrderItems` (0 rows in prod; dead).
+
 **FKs go out as nested `{ uuid }` objects under the field name WITHOUT the `Id` suffix** — `contact: { uuid }`, `createdByUser: { uuid }`. Each is omitted entirely when absent rather than sent as `null`: a location can have no contact, and an SSO session can lack a user uuid.
 
 #### The picker fetch — 13.3 s → 0.39 s by filtering SERVER-side (2026-09-14)
@@ -516,7 +523,7 @@ Money (Unit Value / Total / Total Value) and Target Contact are **dropped for v1
 
 ~~⚠ `TransferOrders` carries **no contact FK at all** today, so the Target Contact element's `valueKey` is a **placeholder**~~ — **closed 2026-09-01.** `TransferOrders.contactId` (FK `Contacts`) exists and RecordField **2561** is granted to roles 1 and 3, so the element has a real binding and enabling it is now genuinely a one-row client override.
 
-The items table's **PO column is order-level**: `TransferOrderItems` has no line-level PO, so the column binds the parent order's `purchaseOrder.number` and repeats on every row. For NYCHH it resolves NULL because their PO links are **upstream** — see [NYCHH PO direction](../../../../clients/nychh/features/po-number-upstream-direction.md). It is left visible in Core (neutral default; other tenants populate `TransferOrders.purchaseOrderId` normally). **The header's PO value is now a link into Inventory** (above); for NYCHH it is the same null, so nothing renders there for this tenant yet.
+The items table's **PO column is order-level**: `TransferOrderItems` has no line-level PO column (line PO link lives in bridge 329 since 2026-09-23, not bound to the column), so the column binds the parent order's `purchaseOrder.number` and repeats on every row. For NYCHH it resolves NULL because their PO links are **upstream** — see [NYCHH PO direction](../../../../clients/nychh/features/po-number-upstream-direction.md). It is left visible in Core (neutral default; other tenants populate `TransferOrders.purchaseOrderId` normally). **The header's PO value is now a link into Inventory** (above); for NYCHH it is the same null, so nothing renders there for this tenant yet.
 
 ### Entry point #2 — the Inventory page's "Create Transfer Order" button (2026-09-03)
 

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

@@ -53,6 +53,7 @@
 | [Service Request → Sales Order → Purchase Order generation (Sync/ServiceRequest)](features/service-request-sales-order-generation.md) | Worker `_Worker_Sync_ServiceRequest` that turns a Service Request → Sales Order → one PO per vendor for any tenant; open for the SR→SO→PO chain, its interceptor |
 | [SSO Stability Monitor (Monitor/Operations/SsoStability)](features/sso-stability-monitor.md) | Reporter cron that GETs the saml `/healthcheck` and pushes an SSO heartbeat to a OneUptime monitor; open when working on the SSO uptime probe, its tokens, or it |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Inbound Startech (Easeedesk) webhook handler that creates/updates the matching TOGA 2.0 ticket; open for the webhook flow, its payload, or ticket-type/stage res |
+| [Stranded WorkerJobs (deploy-window job loss) and how to repair them](features/stranded-worker-jobs.md) | Jobs queued while worker2 restarts are dropped silently with no retry and no alert; open when a cron "never ran" or a webhook vanished. |
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | Consumer side of Talos (TOGa IQ): the endpoints, DevCore assistant, and JWT auto-refresh a worker2 dev tool needs to query the meeting-notes corpus; open when a |
 | [Talos Pricing Automation (worker2 Cron — Usage Import, AWS Actuals, Margins, Profiles)](features/talos-pricing-automation.md) | Monthly worker2 crons that turn raw usage + AWS cost into a measured platform unit price, per-client cost, and margins; open for the pricing pipeline, its AWS c |
 | [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | `_Worker_Team_Transcripts` cron pipeline ingesting Teams VTT transcripts into Talos/TOGa IQ Bedrock KBs + emailing organizer recaps; open for Export/Process/Ret |

package/knowledge/2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: ["bala"]
+updated: 2026-09-23
+owners: ["bala", "jcardinal"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
   - _underscore/Model/Client/TransferOrder.php
@@ -84,7 +84,7 @@ Nothing beyond this list. A transfer order has no shipping cost, ship method, te
 | line `rate` | **0** — the zero-value part |
 | line `location` | the **origin** warehouse. **`location` is NOT a ship-to** — NetSuite never uses a line's location for delivery. |
 
-**Missing data ABORTS the order — never sends a partial one.** Each throws with a named message: **no origin location, no destination location, no lines, no PO number**. Mirrors the sales-order push's missing-mapping rule. **PO # is mandatory on the NetSuite order form**, which is why a missing PO number is fatal rather than omitted. `resolvePurchaseOrderNumber()` reads the PO number from the **`purchaseOrdersTransferOrders` header bridge first** (what the Create Transfer Order modal writes), falling back to the direct `purchaseOrderId` column. See [SO↔PO bridge direction](../../_underscore/features/sales-order-purchase-order-bridge-direction.md).
+**Missing data ABORTS the order — never sends a partial one.** Each throws with a named message: **no origin location, no destination location, no lines, no PO number**. Mirrors the sales-order push's missing-mapping rule. **PO # is mandatory on the NetSuite order form**, which is why a missing PO number is fatal rather than omitted. `resolvePurchaseOrderNumber()` reads the PO number from the **`purchaseOrdersTransferOrders` header bridge first** (written by the Create Transfer Order modal since 2026-09-23), falling back to the direct `purchaseOrderId` column. See [SO↔PO bridge direction](../../_underscore/features/sales-order-purchase-order-bridge-direction.md).
 
 **`description` → `memo` cannot leak into a plain sales order.** `memo` is sent only from the transfer-order shape. There is **no `memo` RecordField and no `memo` column anywhere** in the sales-order path.
 

package/knowledge/2.0/apps/worker2/features/stranded-worker-jobs.md

@@ -0,0 +1,56 @@
+---
+title: Stranded WorkerJobs (deploy-window job loss) and how to repair them
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-09-23
+owners: [mhammontree]
+files:
+  - worker2/Controller/Index.php
+  - worker2/LambdaFunctions/JobScheduler/lambda_function.py
+  - worker2/Worker/Infrastructure/Worker.php
+related:
+  - ../architecture.md
+  - ./creating-worker-actions.md
+  - ../../../1.0/apps/tools/features/worker2-job-bridge.md
+---
+
+Jobs queued while worker2 restarts are dropped silently with no retry and no alert; open when a cron "never ran" or a webhook vanished.
+
+## Summary
+
+A **worker2 deploy silently drops every job queued during the restart window.** The row stays
+`dtQueued` set, `dtStarted NULL`, `isSuccess NULL` — forever. Nothing recovers it:
+
+- JobScheduler Part A only re-queues rows where `dtQueued IS NULL`.
+- The watchdog (Part B) only fails rows that already have `dtStarted`.
+
+So there is **no failure, no alert, no `Logs.Issue`** — the job just never happened.
+
+Measured in prod 2026-09-23: **95 rows** stranded between 09:15:45 and 11:05:22. Not only crons —
+Clickup/Webhook 9, Netsuite/Webhook 6, Github/Webhook 5, Infrastructure/Email/Send/Run 4,
+Infrastructure/Errors/Escalate 4, plus 2 each for eight `Monitor/Compass/*` actions.
+
+## How it works — repairing them (crons and webhooks need OPPOSITE treatment)
+
+**CRON row** — mark it `isSuccess = 0` with an explanatory `output`.
+- Do **not** delete it: that destroys the audit record.
+- Do **not** re-queue by nulling `dtQueued`: that re-runs stale time-based work.
+- If the run is genuinely still needed, fire it deliberately as a fresh job.
+
+**WEBHOOK row** — the payload is still in `parameters`, so
+`_Worker_Infrastructure_Worker::Retry($workerJobId)` genuinely recovers it. Retry it.
+
+## Gotchas
+
+- **`isSuccess IS NULL` is ambiguous** — running, or abandoned. Check `dtStarted`: NULL plus a
+  `dtQueued` older than a few minutes = stranded.
+- **After any worker2 deploy, sweep for stranded rows.** Nothing else will tell you.
+- Same ambiguity on the enqueue side in `tools` — see
+  [Tools → worker2 job bridge](../../../1.0/apps/tools/features/worker2-job-bridge.md).
+
+## Change history
+- 2026-09-23 — Created: 95 prod jobs lost in a deploy window (2026-09-23), with the cron-vs-webhook repair rule. (mhammontree)

package/knowledge/2.0/apps/worker2/workflows/running-worker2-locally.md

@@ -131,6 +131,7 @@ NetSuite or to `Forecast`.
 
 - **⚠ Locally, worker2's `Core` resolves to the 1.0 `Core` database, not the 2.0 one.** `worker2/_.php:20` has `const DB_CORE = 'Core';` and `Core` is never explicitly registered, so the schema name is used literally. On a dev machine the 2.0 tables live in **`Core_2`** (48 tables) while `Core` is the 1.0 schema (10 tables) — symptom: `Table 'core.workerjobs' doesn't exist`. Workaround: flip `DB_CORE` to `'Core_2'` locally and **revert before committing**.
 - **That workaround is incomplete — `_underscore/Email.php:435` hardcodes the literal prefix `FROM Core.Clients`.** So the summary-email step still throws `Table 'core.clients' doesn't exist` no matter what `DB_CORE` says. In the Compass PEOPLE cron that step runs **last**, after both tenants commit, so the data work is unaffected — but do not read the trailing exception as a failed run.
+- **Locally, YOU are the queue — non-prod worker2 has no SQS consumer.** Nothing picks a `WorkerJobs` row up on its own; kick each job by POSTing `{"workerJobId": N}` to the worker2 host (Postman).
 - **⚠ A stale local client database silently invalidates the test.** A local tenant that predates a migration can make broken code **pass** locally — e.g. local `Client_Compass` still had `contactId` NULLABLE, so a missing FK value was accepted where prod's `NOT NULL` turns it into `0` and a constraint error. Before testing anything schema-sensitive, drop and reload the tenant from production and **re-verify the constraint/index actually survived the copy**.
 
 - **The ad-hoc SuiteQL runner `test/@dave/Junk Drawer/NetSuite/nsq.php` cannot start — stale bootstrap.**
@@ -181,4 +182,5 @@ NetSuite or to `Forecast`.
   — the api2 sibling of steps 2–3.
 
 ## Change history
+- 2026-09-23 — Noted that non-prod worker2 has no SQS consumer: kick jobs locally by POSTing `{"workerJobId": N}`. (mhammontree)
 - 2026-09-23 — Added three local-run traps found on TRUE-82230: worker2's literal `DB_CORE = 'Core'` hits the 1.0 schema locally (2.0 lives in `Core_2`); `_underscore/Email.php:435` hardcodes `FROM Core.Clients` so the summary-email step throws regardless; and a stale local client DB can make broken code pass (reload from prod and re-verify constraints). (mhammontree)

package/knowledge/INDEX.md

@@ -15,12 +15,12 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **test** (Test) — 16 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 3 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **store** (Store) — 3 doc(s) → [1.0/apps/store/INDEX.md](1.0/apps/store/INDEX.md)
-- **tools** (Tools) — 19 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 21 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 90 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 74 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 75 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 19 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/clients/compass-usa/INDEX.md

@@ -21,6 +21,7 @@
 | [Compass: ODP / Strategic Systems ASN CSV email import (and the scientific-notation tracking-number loss)](features/odp-strategic-systems-asn-csv-import.md) | 1.0 | The 1.0 worker cron that reads Office Depot / Strategic Systems ASN CSVs from email, why it routes by column count, and why a tracking number can arrive as `8.7 |
 | [Compass: MA refresh-order monitor (Monitor/Compass/MaRefreshOrderExceptions)](features/oneuptime-ma-refresh-order-monitor.md) | 2.0 | worker2 OneUptime push monitor counting Compass MA employee-refresh orders whose ODP SO has no NetSuite order yet; open when working on Compass MA monitoring or |
 | [Compass USA — Fulfilled vs Partially Fulfilled (order total kept; per-line rule built then rejected)](features/order-fulfillment-status-per-line.md) | 2.0 | Why Compass USA shows Fulfilled on partly-shipped orders and why the per-line fix was built, measured, then reverted; open before touching Compass USA `_status` |
+| [People File Import admin page (tools /compass/people-file-import → worker2)](features/people-file-import-admin-page.md) | 1.0 | Browser page that lists the Compass PEOPLE files on SFTP and runs the importer on demand; open before changing the page or the importer's listing/guard code. |
 | [Compass PEOPLE-File User Lifecycle (duplicate accounts, reactivation grace window, raw-SQL deactivation)](features/people-file-user-lifecycle.md) | 2.0 | The nightly Compass PEOPLE-file cron's Users-row lifecycle (insert/reactivate/deactivate), why it creates duplicate accounts, and its raw-SQL/index traps; open |
 | [Persona Model & Levy-Sector Gating (worker2 PEOPLE cron)](features/persona-model-and-levy-gating.md) | 2.0 | Compass USA catalogue visibility is driven by **personas** in `Client_Compass`. |
 | [Compass Sales-Order Line-Number Renumbering (and why it hangs off the SO hooks)](features/sales-order-line-renumbering.md) | 2.0 | How Compass keeps SO lines numbered 1..N with no gaps, why the renumber rides the parent SO hooks, and the two-phase SQL that avoids a duplicate-key fatal; open |

package/knowledge/clients/compass-usa/features/people-file-import-admin-page.md

@@ -0,0 +1,62 @@
+---
+title: People File Import admin page (tools /compass/people-file-import → worker2)
+framework: "1.0"
+repo: tools
+project: Tools
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-09-23
+owners: [mhammontree]
+files:
+  - tools/_/app/compass/peoplefile.php
+  - tools/mvc/compass/people-file-import/get.php
+  - tools/mvc/compass/people-file-import/post.php
+  - worker2/Worker/Client/Compass/PeopleFile.php
+related:
+  - ./people-file-user-lifecycle.md
+  - ../../../1.0/apps/tools/features/worker2-job-bridge.md
+  - ../../../1.0/apps/tools/features/compass-user-persona-admin.md
+  - ../../../2.0/apps/worker2/features/stranded-worker-jobs.md
+---
+
+Browser page that lists the Compass PEOPLE files on SFTP and runs the importer on demand; open before changing the page or the importer's listing/guard code.
+
+## Summary
+
+`tools` page **/compass/people-file-import** (`App_Compass_PeopleFile`, Development Team persona
+only) lists the PEOPLE files waiting on the SFTP server, with a **Refresh** button and an
+**Import** button shown only when files exist. It exists so a stranded or failed nightly cron can
+be re-run without a developer.
+
+`tools` does **not** touch SFTP — it enqueues worker2 actions and reads `Core.WorkerJobs.output`.
+See [Tools → worker2 job bridge](../../../1.0/apps/tools/features/worker2-job-bridge.md) for the
+enqueue/decode rules and why SFTP stays in worker2.
+
+## How it works
+
+worker2 side (`Worker/Client/Compass/PeopleFile.php`):
+
+- `gatherPeopleFiles(SFTP): array` — oldest first, **shared by both** the listing and the import,
+  so the page can never show a different "next file" than the importer takes.
+- `Client/Compass/PeopleFile/ListFiles` — new read-only action returning JSON, used by the page.
+- `isAnotherRunInFlight()` guard on `ProcessPeopleFiles`.
+- `ProcessPeopleFiles` now **returns a JSON summary on every path**. It previously returned
+  nothing, so every run recorded "<no return message>".
+
+**Deploy order: worker2 FIRST, then tools.** The page calls `ListFiles`, which does not exist
+until worker2 ships.
+
+Reference: prod `Core.CronJobs` id **8** = "Compass - People File Import", schedule `15 9 * * *`,
+`maxExecutionTime` 3600, action `Client/Compass/PeopleFile/ProcessPeopleFiles`. A job enqueued
+from this page is **not** scheduler-fired, so it gets the 300s action cap, not 3600.
+
+## Gotchas
+
+- **A failed run does not mean nothing happened.** The importer is not all-or-nothing — see
+  [PEOPLE-file user lifecycle](./people-file-user-lifecycle.md). Check the data before importing
+  the same file again.
+- **Persona-gated to Development Team.** It runs a production import; do not widen it casually.
+
+## Change history
+- 2026-09-23 — Created with the page (TRUE-82250, tools 0cc6f99 / worker2 a81ad6c, branch TRUE-82250): shared `gatherPeopleFiles`, new `ListFiles` action, in-flight guard, and a JSON summary return on every path. (mhammontree)

package/knowledge/clients/compass-usa/features/people-file-user-lifecycle.md

@@ -91,6 +91,7 @@ The insert-time hook designed 2026-08-12 was built and grew into a reusable engi
 **Open product question, still open:** when a manager has genuinely left and HR supplied no replacement, what should the order do — block, escalate to the supervisor's supervisor, or route to an admin queue? The engine deliberately **skips** these as ambiguous rather than guessing.
 
 ## Gotchas
+- **⚠ The import is NOT all-or-nothing — a failed job can still have written everything.** Each tenant's import is transactional, but everything **after** the tenant transactions commit runs outside it: `sendProcessingSummaryEmail()` (~line 264) and the SFTP delete. A run that fails at the email step records `isSuccess = 0` while all the data stays written, **and the file stays on SFTP**, so the same file can be imported a second time. Proven locally 2026-09-23: job 1076884 failed in `sendProcessingSummaryEmail` after 25.4s with 460 US + 26 CA users (and the same number of Contacts) committed and kept. **Check the data before re-running.**
 - **⚠ Deactivation is raw bulk SQL — model hooks never fire.** User inactivation runs as `UPDATE Users SET isActive = 0 WHERE id IN (...)` through `_Query`, **not** the model layer. A `postPut` / `postPost` interceptor on the User model will **never** run on deactivation. Any deactivation-time side effect must be written **inside the importer itself** — adding a model hook and expecting it to fire is a silent no-op.
 - **The same raw SQL is invisible to the change-audit log.** It produces no `RecordField` rows in `Logs_Compass`, so anything the importer should be accountable for must write its own `Record` **note** explicitly. See [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md).
 - **A duplicate account strands approvals, but not email.** The approval gate matches on user id, so a decision assigned to the old row is invisible to the same human's new account — while the notification email still arrives, because both rows carry the same address. Visible symptom: a person chased to approve an order they cannot see. Detail: [Approval-Decision Flow](./approval-decision-flow.md).
@@ -118,8 +119,11 @@ The insert-time hook designed 2026-08-12 was built and grew into a reusable engi
 - [Compass Approval-Decision Flow](./approval-decision-flow.md) — what a duplicate account breaks downstream.
 - [Stranded Approval Reassignment](./stranded-approval-reassignment.md) — the engine that repairs the approvals a duplicate account stranded.
 - [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md) — why the importer's raw writes leave no audit trail.
+- [People File Import admin page](./people-file-import-admin-page.md) — the on-demand re-run page in `tools`.
+- [Stranded WorkerJobs](../../../2.0/apps/worker2/features/stranded-worker-jobs.md) — why the nightly cron row can never run at all.
 - [Compass USA profile](../profile.md)
 - [Users.email as login identity](../../../2.0/apps/_underscore/features/user-email-as-identity-and-password-reset.md)
 
 ## Change history
+- 2026-09-23 — Recorded that the import is **not** all-or-nothing (post-commit email + SFTP delete run outside the tenant transaction; job 1076884 failed yet kept 460 US / 26 CA users). TRUE-82230 confirmed in prod: 543 `Client_Compass` users created, **zero** null-or-0 `contactId`, two manual ACTION runs ~18s each — needed because the 09:15 cron row (job 1784367) was stranded. (mhammontree)
 - 2026-09-23 — **Fixed the `Users.contactId` FK write order (TRUE-82230).** Jeff's `NOT NULL` + `Users_ibfk_1` on both tenants broke the importer from 2026-09-22 09:15 (last good run 2026-09-21); the whole run rolled back and Canada never executed. New `insertContactsForNewUsers()` creates the Contact before the `Users` batch and puts `contactId` in the INSERT column list; existing users missing a contact keep the create-then-UPDATE path. Also recorded: `LAST_INSERT_ID()` must be read on the write connection (not `_Query`); `TEST_MODE` vs `DRY_RUN` neither being safe alone; the FIFO/one-file/empty-is-silent-success facts; and that a stale local DB hides this class of bug. Verified against prod-reloaded local schemas: 80 new US / 17 new CA users, 0 with null-or-0 `contactId`. (mhammontree)

package/knowledge/clients/nychh/features/transfer-order-netsuite-push.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-17
-owners: ["bala"]
+updated: 2026-09-23
+owners: ["bala", "jcardinal"]
 files:
   - _underscore/Model/Client/TransferOrder.php
   - worker2/Worker/Netsuite/SalesOrder.php
@@ -203,11 +203,18 @@ email, which must fire *after* this push writes `number` back. The `POST` row ab
 
 ## Data + metadata state (2026-09-02)
 
-- **`Client_Nychh.PurchaseOrders_TransferOrders` has 0 rows in production**, and
-  `TransferOrders.purchaseOrderId` is set on **0** of the 1,930 rows — **no transfer order has a PO
-  link yet.** New orders from the Create Transfer Order modal are what will populate the bridge.
-  Until then `resolvePurchaseOrderNumber()` returns null and **the push aborts by design** (PO # is
-  mandatory on the NetSuite order form).
+- **Prod 2026-09-23:** `PurchaseOrders_TransferOrders` (325) = **1,592 rows**; `TransferOrders.purchaseOrderId`
+  set on 10 rows. The Create Transfer Order modal now writes 325 (header) + 329 (lines) in its single POST
+  ([transfer-orders-page](../../../2.0/apps/toga25-supply/features/transfer-orders-page.md)). An order
+  with no PO link still makes `resolvePurchaseOrderNumber()` return null → push aborts by design.
+- Reverse-named twins 326 / 330 have 0 rows — dead; never read or write them.
+- Prod `InherentRecordChildren` ids: 150 = 312→313, 151 = 312→325, 152 = 312→357; added 2026-09-23
+  (`Core/2026-09-23d`): 17→325, 18→329, 313→329.
+- RecordFields: 325 = 2209 id / 2210 uuid / 2211 purchaseOrderId / 2212 transferOrderId; 329 = 2225 / 2226 /
+  2227 purchaseOrderItemId / 2228 transferOrderItemId.
+- Base (role 1) + API (role 3) ACL for 325/329 already complete (record CRUD, expressions 302/303, field
+  write on uuid + both FKs). Duplicate Base `AclRecordPermissions` (325/331, 328/334) — harmless.
+- `TransferOrderStages` prod: 1 Pending, 2 In Transit, 3 Received, 4 Canceled, 5 Closed.
 - **`Core.InherentRecordChildren` for record 312** — the depth-4 read needs both the lines and the
   header PO bridge:
   - **prod** — was 312→313 and 312→**329** (the *item-level* bridge); repointed by the developer, now

package/knowledge/clients/nychh/profile.md

@@ -18,7 +18,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-09-17
+updated: 2026-09-23
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
@@ -102,6 +102,7 @@ TOGA 2.0 client on `_underscore`, prod schema `Client_Nychh`. Supply-chain / ful
 - 🚨 **`Client_Nychh.TransferOrders` HAS production data — 1,927 rows (verified 2026-08-31 on `reader1.client.database.togahub.com`).** The transfer-order *tables and data* have been live in prod for a while (the 1.0 NetSuite importer writes them); only the **2026-08-28 UI vertical** (TableView, Core surfaces, nav override) is new. An earlier version said transfer orders were "local only … not yet run on sandbox-client or production", and that stale line produced a wrong recommendation — that a prod-to-local restore would *wipe* the transfer-orders feature. **Never infer prod state from this repo or from a migration's run status; read prod.** Restoring or overwriting `Client_Nychh` destroys real transfer-order rows.
 - **The Transfer Orders SCREEN is NYCHH-only and new (2026-08-28).** NYCHH is the first — and today the only — tenant with a `transfer-orders` TableView (`Client_Nychh/2026-08-28a`, which also seeds the ACL chain for record 351 that the Status column silently depends on) and the one `SurfaceOverrides` row that reveals the nav item (`2026-08-28b`, client-wide, matching how this tenant grants Sales Orders and Inventory — NYCHH does not scope navigation by role). The Core surfaces and stage colour tokens are **shared/neutral**, hidden for every other client until they opt in. The seven migration files were **committed 2026-08-31** (`dbchanges2` commit `1c3fe2e`, branch `TRUE-80852`, pushed); run order is **`Core/` → `Client/` fan-out → `Client_Nychh/`**, because the client files reference Core record ids and the NYCHH TableView/ACL need the columns the fan-out files add. Run state per environment must be **verified against that environment**, never assumed from the repo. **beta is blocked** because it lacks the `TransferOrderStages` table. The **Create Transfer Order** modal was reworked 2026-09-01 and its data layer is wired, but 🚨 **the item picker shows zero selectable lines for NYCHH** — see the availability blocker below. See [Transfer Orders page](../../2.0/apps/toga25-supply/features/transfer-orders-page.md).
 - 🚨 **The transfer-order ACL + schema on prod/sandbox are UNTRACKED (2026-08-28).** Record and field ACL for records 312/313, their logic-group/expression chain, and the `TransferOrderItems.dtCreated`/`dtUpdated` columns were all hand-applied when the NetSuite TransferOrder POST was enabled — **no `dbchanges2` file creates any of it**, so a fresh environment can reproduce neither the UI nor the importer. Reconstructed in `Client_Nychh/2026-08-28c` (ACL, faithful — role 2 deliberately excluded) and `Client/2026-08-28b` (columns; root cause is the blank client template, which affects **every** tenant). See [transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
+- **Create Transfer Order links POs (2026-09-23)** — one POST writes header bridge 325 + line bridge 329 (Core `2026-09-23d` inherent children). Prod 325 has 1,592 rows; 326/330 twins are dead. See [transfer-order push](./features/transfer-order-netsuite-push.md).
 - **Two-branch inventory quantities + TransferOrder V2 enablement** — NYCHH-only on-hand/available/fulfilled/backordered model on `_Model_Nychh_Item`, plus the client-override models + ACL rows that let a NetSuite TransferOrder POST succeed. See [transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
 - 🚨 **OPEN BLOCKER — every NYCHH PO line reports availability 0, in sandbox AND production (verified 2026-09-01).** The deployed `_Model_Nychh_PurchaseOrderItem` sources stock-in from inventory adjustments and `INNER JOIN`s `InventoryAdjustmentItems.itemFulfillmentItemId`, which is **NULL on 100% of rows** (292/292 sandbox, 317/317 prod). So `_qtyReceived` / `_qtyOnHand` / `_qtyAvailable` are all `0.00` for every purchase-order line, and the **Create Transfer Order item picker has nothing to show**. Needs an **integration / data-owner decision** — backfill the FK, or change the override's stock-in source (base PO item receipts return real numbers today). Not a frontend or ACL defect, and **not** fixed by `Client/2026-09-01a`. See [transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
 - 🚨 **`_Model_Nychh_PurchaseOrderItem` is NOT on every `_underscore` branch (verified 2026-09-01).** `Model/Nychh/PurchaseOrderItem.php` exists on **`_production`** and **`_sandbox-client`** but is **absent from `_beta`** and **`_sandbox-dev`**. Because `_underscore` is pulled at deploy by branch, NYCHH PO-line `_qty*` values are **different numbers per tier**: prod/sandbox-client run the inventory-adjustment formula (0.00 until the NetSuite link is backfilled), beta/sandbox-dev fall back to the base item-receipt formula and report real quantities. **Never eliminate a tenant override by `ls`-ing your working tree** — use `git ls-tree -r --name-only origin/<branch>`. That mistake cost a full session chasing a non-existent "API returns 0" bug. See [transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).

package/package.json

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