toga-ai 1.0.586 → 1.0.588

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

@@ -2,7 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
-| [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md, tools/assets/css/theme.css, tools/assets/js/theme.js |
+| [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/.ebextensions/020_setup_git_libraries.config, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md, tools/assets/css/theme.css, tools/assets/js/theme.js |
 | [ClickUp Sprint Dashboard (tools /clickup/react)](features/clickup-sprint-dashboard.md) | A native **ClickUp sprint dashboard** in the 1.0 `tools` app at route `/clickup/react`, built for a wall-mounted **TV display** ("TOGa IQ" internal sprint metri | tools/_/app/clickup/sprint.php, tools/v2/sprints/tile/index.php, tools/v2/sprints/current/index.php, tools/v2/sprints/status-breakdown/index.php, tools/v2/sprints/worktype-breakdown/index.php, tools/v2/sprints/points-by-dev/index.php, tools/v2/sprints/burndown/index.php, tools/assets/clickup/sprint-dashboard.html, tools/mvc/clickup/react/get.php, tools/mvc/login/get.php, tools/_/app/nav.php |
 | [CloudFront Client Setup](features/cloudfront-client-setup.md) | An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that onboards a client onto **CloudFront + Route 53 across multiple AWS account | tools/_/app/devops/cloudfront.php, tools/mvc/devops/cloudfront-clients/get.php, tools/mvc/devops/cloudfront-clients/post.php, tools/assets/js/cloudfront-clients.js, tools/assets/css/cloudfront-clients.css, tools/_/app/nav.php, tools/_/app/frameworkindex.php, tools/config.production.ini |
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
@@ -16,4 +16,4 @@
 | [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | > **PER-AI-MODEL, DATA-DRIVEN SCOPING (2026-07-29).** The KB-documents and Vocabulary admin > UIs were refactored from a single hard-coded **"development-team"* | tools/mvc/talos/kb-documents/get.php, tools/mvc/talos/kb-documents/post.php, tools/mvc/talos/knowledge-bases/get.php, tools/mvc/talos/knowledge-bases/post.php, tools/mvc/talos/vocabulary/get.php, tools/mvc/talos/vocabulary/post.php, tools/_/app/talos/s3.php, tools/_/app/talos/bedrock.php, tools/_/app/pg.php, tools/_/app/model/true/aimodels.php, tools/_/app/model/true/vectorindexes.php, tools/_/app/model/true/aimodels_vectorindexes.php, tools/_/app/worker.php, tools/_/app/nav.php, tools/config.production.ini, tools/config.alpha.ini, tools/.platform/httpd/conf.d/timeouts.conf, tools/.platform/hooks/prebuild/01-install-php-pgsql.sh, tools/.platform/hooks/postdeploy/01-restart-php.sh |
 | [Talos Pricing UI (Contracts, Pricing Dashboard, Usage, Settings + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus the estimate engine. | tools/_/app/nav.php, tools/_/app/talos/estimator.php, tools/_/app/talos/usage.php, tools/mvc/talos/contracts/get.php, tools/mvc/talos/contracts/post.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/usage/get.php, tools/mvc/talos/settings/get.php, tools/mvc/talos/settings/post.php, tools/assets/css/style.css |
 | [App-Wide Colour Theme (light / dark / auto)](features/theme-light-dark.md) | A **light / dark / auto** colour theme for the *entire* Tools app, built as a single semantic-token layer (`assets/css/theme.css`) rather than per-page edits. | tools/assets/css/theme.css, tools/assets/js/theme.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/common/header.php, tools/mvc/login/get.php, tools/assets/css/style.css, tools/assets/css/design.css, tools/assets/css/login.css, tools/assets/css/cloudfront-clients.css, tools/assets/css/gchart.css, tools/mvc/talos/usage/get.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/contracts/get.php, tools/mvc/clickup/dashboard/get.php, tools/mvc/email-migration/notify/post.php |
-| [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json, tools/ebs/setup_export_cache_folders.php, tools/_/app/frameworkindex.php |
+| [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/003_pgsql_hook_optional.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/.platform/hooks/prebuild/01-install-php-pgsql.sh, tools/.platform/hooks/prebuild/02-install-php-redis.sh, tools/ebs/git.json, tools/ebs/setup_export_cache_folders.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php |

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

@@ -10,6 +10,7 @@ updated: 2026-08-14
 owners: [jcardinal, kyalamarthi]
 files:
   - tools/index.php
+  - tools/.ebextensions/020_setup_git_libraries.config
   - tools/_/app/framework.php
   - tools/_/app/frameworkindex.php
   - tools/assets/img/favicon/favicon.ico
@@ -66,8 +67,24 @@ App_Framework_Tools::renderIndex();`. App-specific framework subclasses
 `App_Framework_Tools` / `App_FrameworkIndex_Tools` live in `_/app/`. The 1.0 folder-based MVC
 page pattern is unchanged from the library skeleton (see the library feature doc).
 
-`App_Framework_Tools::initialize()` sets the session cookie HttpOnly + SameSite=Lax before
-calling the parent initialize.
+`App_Framework_Tools::initialize()` sets the session cookie HttpOnly + SameSite=Lax, then
+`App_Framework_Tools::startSession()` starts the session on the **shared ElastiCache Redis
+cluster** (phpredis `rediscluster` handler, cluster-mode config endpoint
+`asi-session-cache…clustercfg.usw2.cache.amazonaws.com:6379`, shared with the `vision` app),
+configured at runtime via `ini_set()` (`session.save_handler=rediscluster`,
+`session.save_path=seed[]=<endpoint>:6379`, `session.gc_maxlifetime=345600`), guarded by
+`extension_loaded('redis')`. It calls `session_start()` itself and sets
+`App_Framework::$useSessions=false` so the parent's `initialize()` does not double-start the
+session (verified that flag's only consumer is the parent's `session_start` guard).
+
+**Ordering is load-bearing:** `startSession()` runs **before** `parent::initialize()` installs
+App_Error's fatal handler, so a Redis failure degrades to file sessions via a graceful
+`@session_start()` fallback instead of a site-wide 500. **Why this exists:** sessions used to
+run on the default **file** handler on **per-instance local disk**; because prod is
+multi-instance behind an ALB, every deploy / instance replacement wiped the local session
+files and logged all users out. Prod-verified 2026-08-14: a redeploy no longer logs users out.
+How the handler is wired at the platform level (INI-file parser drops `seed[]`, fpm overrides
+`/etc/php.d`, phpredis install) is in `workflows/deploy-to-elastic-beanstalk-al2023.md`.
 
 ## Layout (single-style app)
 
@@ -133,6 +150,12 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
   `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`.
 - **Unproxied third-party polling from the browser (`/clickup/react`).** The monitor column pulls
   ~250 KB from OneUptime every 5s — ~3 MB/min **per open tab** — to render about six numbers, and
@@ -147,6 +170,12 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
   composer package must `require_once` the autoloader itself.
 
 ## Change history
+- 2026-08-14 — Corrected the session model: sessions were on the file handler on per-instance
+  local disk (not Redis as previously assumed), so every deploy logged everyone out; moved to the
+  shared ElastiCache Redis `rediscluster` handler via `App_Framework_Tools::startSession()`
+  (runtime `ini_set()`, `$useSessions=false`, started before App_Error installs so a Redis failure
+  degrades gracefully). Flagged the plaintext GitHub PAT in `020_setup_git_libraries.config` for
+  rotation + move to an EB env property. (jcardinal)
 - 2026-08-14 — Recorded that `/clickup/react` is now an unattended wall display holding a
   full-screen colour state indefinitely, carrying the app's only cross-origin browser dependency
   (OneUptime public status-page API) plus per-iframe permission policy

package/knowledge/1.0/apps/tools/features/oneuptime-monitor-status-panel.md

@@ -123,7 +123,8 @@ poll's:
 - The **first successful poll is the baseline**, so opening the page mid-outage is **silent**
   (the standing tint, being level-triggered, still shows immediately).
 - A state that simply persists never re-alarms.
-- A full recovery to operational is **silent** (the monitor drops out of the row set entirely).
+- A full recovery to operational is **visually silent** (no popup, no tint) but now plays a
+  distinct **recovery chime** — see the recovery event below.
 - It fires on **any change of non-operational state** — `r.role !== previous.get(r.key)`, where
   the row set only ever holds non-operational monitors, so good→degraded, good→offline,
   degraded→offline **and offline→degraded** all alert. An earlier version compared severity
@@ -134,11 +135,30 @@ poll's:
 The event presentation, held for `ALERT_HOLD_MS` (5s):
 
 - **Sound** — Web Audio beeps, synthesised at runtime, so there is **no audio asset to ship**.
-  **1 beep @ 720 Hz** degraded, **2 beeps @ 990 Hz** offline. The beep count describes the state
-  the monitor is in **now**, so an offline → degraded change beeps **once**. Pitch differs too,
-  so severity is recognisable across a room without counting.
-- **Popup** — a centre overlay naming each affected monitor.
+  Each role's sound is defined in a single `ALERT_SOUND` table keyed by role, read by a
+  generalised `playBeeps(role)` (signature unchanged: role → bool). Each entry carries a beep
+  **count**, base **freq** (Hz), a per-beep **step** (Hz added to each successive beep — `0` =
+  flat, positive = a rising chime), duration/gap/volume, and a **wave** shape. Current tuned
+  values: **warning (degraded) = 3× square @ 720 Hz** (flat), **critical (offline) = 4× square
+  @ 410 Hz** (flat), **recovered = 3× square rising chime 620 → 800 → 980 Hz** (freq 620,
+  step 180). Distinct count, pitch and the rising vs. flat contour make each event
+  recognisable across a room without looking. The three sounds were tuned by ear in a
+  throwaway standalone "Monitor Sound Lab" browser page and the final numbers ported in — the
+  lab is not part of the repo.
+- **Popup** — a centre overlay naming each affected monitor. **Bad-state events only** —
+  recovery fires no popup.
 - **Blink** — the tint element gains `.is-blinking` for the 5s pulse, then the colour **holds**.
+  **Bad-state events only** — recovery fires no blink and no tint.
+
+**Recovery event — audio-only, by design.** `useMonitorAlerts` also computes `recovered` = keys
+that were non-operational in the previous poll and have **dropped out of `model.rows`** this poll,
+and calls `playBeeps('recovered')` (the rising chime) for them. It deliberately fires **no popup
+and no screen tint**: the level-triggered standing tint already clears itself when a row leaves
+the set, and a green "all clear" popup/flash would fight the "the board only shouts when something
+is wrong" design. So recovery is silent **visually** but audible. Two edge rules: the **first
+poll is still the baseline** (opening the page mid-outage does not chime), and if a bad-state
+change and a recovery land in the **same 5s poll the bad-state alert wins** that tick, avoiding
+overlapping sounds (simultaneous transitions are rare).
 
 **State — `standingRole(model)`** returns `critical` if any row is offline, else `warning` if any
 is degraded, else `null` (no tint). The tint element only renders while `standingRole` is
@@ -148,8 +168,10 @@ Note the two can legitimately show different colours at once: the tint always re
 **worst-current** state while the popup reflects **the event**, so a degraded-event popup can sit
 on a red screen because something else is still offline. That is correct, not a bug.
 
-Verified across full cycles: beep sequence 720 / 990 990 / 720, silent on unchanged and on
-recovery, popup held 4982 ms and 4955 ms against the 5s spec; amber standing → red when offline
+Verified across full cycles (against the original 1-beep-720 / 2-beep-990 tuning; the current
+values are 3×720 / 4×410 / recovered 620→800→980): distinct sounds per event, silent on
+unchanged, recovery now chimes but stays visually silent, popup held 4982 ms and 4955 ms against
+the 5s spec; amber standing → red when offline
 joined (priority) → amber when offline cleared → no tint on full recovery, with the blink
 stopping after 5s and the colour held. Circle verified against the DOM: `#0ca30c` all-clear,
 `#fab219` degraded only, `#d03b3b` with 1 degraded + 1 offline, and `textNodesInSvg = 0`.
@@ -209,8 +231,9 @@ reduced-motion viewer never lands on a fully-invisible (opacity 0) glow.
   OneUptime call returns HTTP 200 with a malformed or empty body, `buildMonitorModel` yields
   total 0, empty buckets and empty rows. The status pill correctly degrades to "Unknown", but
   the affected-list card still reads **"All 0 monitors are operational"**, and any
-  previously-degraded monitor silently disappears **with no alert** (recovery is silent by
-  design, and an empty row set is indistinguishable from a full recovery). Since the standing
+  previously-degraded monitor silently disappears — and, worse now that recovery is audible,
+  the mass drop-out is **indistinguishable from a full recovery**, so the panel plays the happy
+  **recovery chime** for every vanished monitor on a parse failure. Since the standing
   tint and the status circle are both driven by that same empty row set, a parse failure also
   **clears a standing red screen back to green** — the most reassuring possible display of a
   total loss of visibility. Recommended fix: treat "zero resources parsed" as an **error
@@ -231,6 +254,18 @@ summary, and caches ~5s. Rationale:
   alerting really wants (today the baseline resets every time a tab reloads).
 
 ## Change history
+- 2026-08-14 — Generalised alert-sound synthesis and added a **recovery chime**. The old
+  `BEEP_COUNT`/`BEEP_HZ`/`BEEP_MS`/`BEEP_GAP_MS`/`BEEP_VOLUME` constants and the square-wave-only
+  `playBeeps` were replaced by a single per-role `ALERT_SOUND` table (count / freq / per-beep
+  `step` / duration / gap / volume / `wave`) read by a generalised `playBeeps(role)` (signature
+  unchanged). Retuned to degraded 3×square@720, offline 4×square@410 (was degraded 1×@720,
+  offline 2×@990). Recovery — a monitor dropping out of the non-operational row set — now plays
+  a distinct rising chime (620→800→980, freq 620/step 180) and is **audio-only by design**: no
+  popup, no tint (the standing tint already self-clears; a green "all clear" flash would fight
+  the "only shouts when wrong" design). First poll stays the silent baseline; a bad-state change
+  and a recovery in the same tick let the bad-state alert win. Sounds were tuned by ear in a
+  throwaway standalone browser "Sound Lab" (not a repo file) and ported in. Corrects the prior
+  "recovery is silent" and old beep-count/pitch documentation. (jcardinal)
 - 2026-08-14 — The standing (level-triggered) edge tint now **slowly breathes** its opacity
   0→1→0 on a 7s ease-in-out loop (`@keyframes alert-breathe`) instead of holding a static tint,
   so a still-broken screen draws a distant eye. The fast 0.7s `.is-blinking` event pulse still

package/knowledge/1.0/apps/tools/workflows/deploy-to-elastic-beanstalk-al2023.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: workflow
 status: active
-updated: 2026-08-03
+updated: 2026-08-14
 owners: [jcardinal, bala]
 files:
   - tools/.ebextensions/004_http_to_https.config
@@ -14,10 +14,14 @@ files:
   - tools/.ebextensions/007_setup_export_cache_folders.config
   - tools/.ebextensions/008_setup_ldap.config
   - tools/.ebextensions/009_setup_phpini.config
+  - tools/.ebextensions/003_pgsql_hook_optional.config
   - tools/.ebextensions/020_setup_git_libraries.config
   - tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config
+  - tools/.platform/hooks/prebuild/01-install-php-pgsql.sh
+  - tools/.platform/hooks/prebuild/02-install-php-redis.sh
   - tools/ebs/git.json
   - tools/ebs/setup_export_cache_folders.php
+  - tools/_/app/framework.php
   - tools/_/app/frameworkindex.php
 related:
   - ../architecture.md
@@ -60,9 +64,23 @@ failed silently (it was wrapped in `ignoreErrors: true`), so `include_path` neve
 The `application.ini` sets `include_path = ".:/var/www/library"`, upload/post limits
 (`upload_max_filesize=25M` / `post_max_size=30M`, raised from 16M so multi-MB design-demo HTML
 exports up to ~25MB post through — see `features/design-demo-admin.md`),
-`memory_limit = 2G`, `display_errors`, the `redis.so` extension, and the rediscluster session
-handler (`session.save_path` points at the ElastiCache cluster cfg endpoint). Session GC
-maxlifetime is 4 days.
+`memory_limit = 2G`, `display_errors`, and loads the `redis.so` extension.
+
+> **Do NOT configure the rediscluster session handler in `application.ini` (or any INI file) on
+> this platform — it silently fails.** See the "Redis sessions" section below. Session
+> `save_handler`/`save_path` are now set at **runtime via `ini_set()` in
+> `tools/_/app/framework.php`**, not in `009_setup_phpini.config`. Two INI-file facts drove this
+> (both verified 2026-08-14 on EB PHP 8.5 / AL2023):
+> - **The INI-file parser silently drops a `session.save_path` value of the form
+>   `"seed[]=host:port"`** — in *both* `/etc/php.d/*.ini` and the php-fpm pool
+>   (`www.conf` `php_value[...]`). `session.save_handler=rediscluster` applies but `save_path`
+>   stays `/tmp`, so `session_start()` fatals ("Failed to initialize storage module:
+>   rediscluster (path: /tmp)") on **every** request → full outage. CLI `php -d` with the same
+>   value works, confirming it is the INI-file parser, not the value itself.
+> - **The php-fpm pool overrides `/etc/php.d/*.ini` at runtime.** `memory_limit=2G` /
+>   `display_errors=On` set in `application.ini` were observed running as 256M/Off because the
+>   fpm pool `www.conf` wins. Values that must hold have to be set where fpm cannot override
+>   them — for session handling, that means `ini_set()` in code.
 
 ### Cloning the libraries — bash, not the CodePipeline PHP script
 
@@ -82,6 +100,52 @@ The replacement is pure bash via a cfn-init `files:` block that writes
 `ebs/git.json` was corrected to match: branch `_production` for both repos and the resources
 path set to `/var/app/ondeck/resources`.
 
+### Native PHP extensions — prebuild hooks (phpredis, pgsql)
+
+Native PECL extensions are installed by `.platform/hooks/prebuild/*.sh` scripts, not
+`.ebextensions`. `02-install-php-redis.sh` installs phpredis (needed for the Redis sessions
+below); `01-install-php-pgsql.sh` installs pgsql (needed only by the Talos "Knowledge Bases"
+create flow). Both target the platform php `php-common-8.5.6`. The durable AL2023 gotchas:
+
+- **The package is `php8.5-pecl-redis6`** (phpredis major-version suffix `6`), **not**
+  `php8.5-redis`.
+- **A plain `dnf install php8.5-pecl-redis6` drags in the php8.1 serializers.** It pulls the
+  igbinary/msgpack deps built for **php8.1** → `php8.1-common`, which **conflicts with the
+  platform's `php-common-8.5.6`** over `/etc/php.ini` and `/usr/lib64/php/modules/*.so` (the dnf
+  transaction test aborts, failing the deploy). Install with
+  `--setopt=install_weak_deps=False --exclude=php8.1-*`.
+- **The versioned package installs the `.so` into a non-platform module dir.** Even once
+  installed, `redis.so` (and `pgsql.so`) lands in a dir the platform php does **not** scan. The
+  platform php loads from its own `extension_dir` — discover it with
+  `php -r 'echo ini_get("extension_dir");'`. The hook copies the `.so` there, writes a scan-dir
+  ini enabling it, then **verifies with `php -m`** and fails the deploy on error.
+- **Escape hatch env property.** `02-install-php-redis.sh` honours `REDIS_HOOK_OPTIONAL=1` (EB
+  env property) to skip on failure rather than block the whole deploy.
+
+**Known-broken sibling — `01-install-php-pgsql.sh` (pgsql).** It has the *same* versioned-package
+/ wrong-module-dir bug and currently **fails on fresh AL2023 instances**. It is presently
+**bypassed** via the EB env property `PGSQL_HOOK_OPTIONAL=1`
+(`.ebextensions/003_pgsql_hook_optional.config`). This is a **temporary** measure: it leaves the
+Talos "Knowledge Bases" create flow (the only pgsql consumer) broken. The fix is the same
+install-and-copy-into-`extension_dir` treatment `02-install-php-redis.sh` already received; once
+applied, **delete the `PGSQL_HOOK_OPTIONAL` bypass config.**
+
+### Redis sessions (survive deploys & load balancing)
+
+Prod Tools runs multiple EB instances behind an ALB, so PHP sessions must live in a shared store,
+not per-instance local disk. Sessions use the **shared ElastiCache Redis cluster**
+(`asi-session-cache…clustercfg.usw2.cache.amazonaws.com:6379`, cluster-mode config endpoint —
+also used by the `vision` app) via the phpredis `rediscluster` handler.
+
+Because the INI-file parser silently drops the `seed[]=host:port` save_path (see the PHP ini
+section above), the handler is configured at **runtime in `tools/_/app/framework.php`**
+(`App_Framework_Tools::startSession()`): `ini_set()` sets
+`session.save_handler=rediscluster`, `session.save_path=seed[]=<cluster cfg endpoint>:6379`, and
+`session.gc_maxlifetime=345600` (4 days), guarded by `extension_loaded('redis')`, then calls
+`session_start()` itself. The full outage story (sessions were previously on the file handler on
+local disk, so every deploy logged everyone out) and the graceful-degrade ordering vs. App_Error
+are in the [architecture doc](../architecture.md).
+
 ### Duplicate config neutralization
 
 EB merges every `.config` alphabetically; two configs with **identical** `container_commands`
@@ -185,6 +249,19 @@ cross-instance storage has a local-disk fallback path for dev, where the AWS SDK
   e.g. `GIT=$(which git || echo /usr/bin/git)`.
 - **cfn-init `files:` runs before `container_commands`** — the correct pattern for writing a
   script and then executing it in the same config.
+- **The php-fpm pool overrides `/etc/php.d/*.ini` — never trust an INI value that fpm can
+  override.** `memory_limit` / `display_errors` set in `application.ini` ran as 256M/Off because
+  the fpm pool `www.conf` wins at runtime. Values that must hold (e.g. session handler config)
+  belong in code via `ini_set()`, or in the fpm pool itself.
+- **The INI-file parser silently drops a `session.save_path` of the form `"seed[]=host:port"`**
+  (in both `/etc/php.d/*.ini` and the fpm pool). `rediscluster` handler applies but save_path
+  stays `/tmp` → `session_start()` fatals on every request. Set it via `ini_set()` in code (CLI
+  `php -d` with the same value works, so it is the INI-file parser, not the value).
+- **Native PECL extensions: use `php8.5-pecl-redis6`, exclude the php8.1 serializer deps, and
+  copy the `.so` into the platform `extension_dir`.** A plain `dnf install` pulls `php8.1-common`
+  which conflicts with `php-common-8.5.6`; install with
+  `--setopt=install_weak_deps=False --exclude=php8.1-*`, then copy the built `.so` into
+  `ini_get('extension_dir')` and verify with `php -m`. Same fix owed to the pgsql sibling hook.
 - **A SAML SSO return-leg "connection timeout" is a missing HTTPS listener, not code. (CONFIRMED + RESOLVED.)**
   When the gateway's return redirect to `https://<host>/sso` times out in the browser, verify the
   **EB/ALB HTTPS (443) listener + ACM cert cover the EXACT return hostname before debugging
@@ -196,6 +273,15 @@ cross-instance storage has a local-disk fallback path for dev, where the AWS SDK
   returns `200` fast. Reusable for any TOGA app behind Elastic Beanstalk.
 
 ## Change history
+- 2026-08-14 — Added the phpredis/pgsql prebuild-hook install pattern
+  (`.platform/hooks/prebuild/02-install-php-redis.sh`): package `php8.5-pecl-redis6`,
+  `--setopt=install_weak_deps=False --exclude=php8.1-*` to avoid the php8.1-common conflict, and
+  copy the built `.so` into the platform `extension_dir`; recorded the pgsql sibling as
+  known-broken and bypassed via `PGSQL_HOOK_OPTIONAL=1`
+  (`003_pgsql_hook_optional.config`, temporary — breaks the Talos KB create flow). Corrected the
+  PHP ini section: `rediscluster` session `save_path` (`seed[]=host:port`) is silently dropped by
+  the INI-file parser and the fpm pool overrides `/etc/php.d/*.ini`, so session handling moved to
+  runtime `ini_set()` in `framework.php`; added a Redis-sessions section. (jcardinal)
 - 2026-08-03 — Recorded that prod Tools is multi-instance behind an ALB, so `/var/www/cache` is
   per-instance local disk (not shared) and cross-request state must go to S3 — the root cause of a
   Preview→Send "job expired"; noted the no-composer-install deploy, `ENVIRONMENT`-based config

package/knowledge/1.0/standards/backend-php.md

@@ -5,7 +5,7 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-08-06
+updated: 2026-08-14
 owners: [jcardinal, rgirish, mhammontree, ajean]
 files: []
 related:
@@ -306,6 +306,26 @@ Two sanctioned patterns, in order of preference:
 
 Never leave either one in effect beyond the block that needs it.
 
+### Start the session before App_Error's fatal handler — and set the handler in code, not INI
+
+On EB PHP 8.5 / AL2023, the `.so` extension and cookie flags aside, two rules make Redis
+sessions reliable:
+
+1. **Set `session.save_handler` / `session.save_path` at runtime with `ini_set()`, not in an
+   INI file.** The INI-file parser silently drops a `session.save_path` of the form
+   `"seed[]=host:port"` (in both `/etc/php.d/*.ini` and the php-fpm pool), and the fpm pool
+   overrides `/etc/php.d/*.ini` anyway. `session_start()` then fatals on every request. `ini_set()`
+   in the app framework takes the value verbatim.
+2. **Call `session_start()` before App_Error's fatal handler is installed.** Because any 1.0
+   warning routes through `App_Error::handleError` → `exit` (see above), a session store that is
+   unreachable would take the whole site down. Starting the session first lets an unreachable
+   store degrade to file sessions via a guarded `@session_start()` fallback (acceptable for a
+   graceful boot; file sessions are single-instance only). Set the framework's own
+   `useSessions=false` flag so the parent boot does not double-start.
+
+Reference implementation: `App_Framework_Tools::startSession()` — see the Tools architecture and
+its EB deploy workflow.
+
 ### Documentation
 
 * **DocBlocks:** framework (`library`) classes/methods are well documented with a description and `@param`/`@return`/`@throws`. Application code is less consistent — document new and modified methods to the framework standard.

package/package.json

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