toga-ai 1.0.879 → 1.0.880

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/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/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/package.json

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