toga-ai 1.0.1004 → 1.0.1006

package/knowledge/1.0/apps/library/features/app-cloud-aws-credentials.md

@@ -6,19 +6,24 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-10-12
-owners: [jcardinal]
+updated: 2026-10-13
+owners: [jcardinal, mhammontree]
 files:
   - library/app/cloud.php
   - library/app/systemmonitor/rdsproductioncluster.php
   - worker/ebs/cron.worker.php
   - toga/ebs/register_instance_to_shared_application_load_balancer.php
   - tools/ebs/check_s3fs.php
+  - library/app/model.php
+  - togadesk/ebs/check_s3fs.php
+  - togadesk/ebs/register_instance_to_shared_application_load_balancer.php
+  - togadesk/.ebextensions/020_setup_git_libraries.config
 related:
   - ../../../../2.0/apps/worker2/features/cross-account-aws-access.md
   - ../../../../2.0/apps/_underscore/features/cloud-s3-helpers.md
   - ../../tools/workflows/deploy-to-elastic-beanstalk-al2023.md
   - ../architecture.md
+  - mvc-page-pattern-and-app-skeleton.md
 ---
 
 How every 1.0 AWS call (App_Cloud CLI + SDK, deploy scripts, `setup_git_libraries.php`) gets credentials by assuming `WorkloadsRuntime` from the EC2 instance role; open before touching 1.0 AWS access or EB deploy hooks.
@@ -56,8 +61,12 @@ CodePipeline `Worker` (502, us-west-2) sources `_production` of **both** `agilan
 - **Never put `$cmd` in an exception or log message.** It contains `$preCommands` = live temporary credentials.
 - **CLI temp creds are visible in argv (`ps`).** Open follow-up: CLI profile with `credential_source=Ec2InstanceMetadata`.
 - **`setup_git_libraries.php` failing is silent.** When the key died its pipeline lookup failed and **library was not updated on deploy** — the old library kept running. If a library change "didn't deploy", check this script first. It was public-read with the key inside — a likely leak path; never put a credential in it.
+- **Triage: `Aws\S3\Exception\S3Exception` 403 `InvalidAccessKeyId` (or any S3 403) in a 1.0 app → check App_Cloud credentials and whether the current library is on that app's instances — not the app code.** Library is not in the app repo: each app's EB deploy clones it (`.ebextensions/020_setup_git_libraries.config`) and pages load it from the include path (`require_once('_.php')`). A library-only fix reaches an app only on that app's next successful deploy. TRUE-82712: TOGa Desk MSP redbox (blob-field model load — see [BLOBSTORAGE](mvc-page-pattern-and-app-skeleton.md#gotchas)) stopped once library + togadesk were released 2026-10-13; no togadesk change.
+- **`copyFileToS3()` (and the other CLI-based calls) never report failure.** `shell_exec('aws s3 cp ...')` then `return true` — bad credentials = silent lost upload. Uploads made while the old key was dead (repair photos, KB files, `BLOBSTORAGE` saves via `App_Model::save()`, email-intake attachments) may be missing from S3. Open, not fixed.
+- **Open, not fixed: `togadesk` and `togaview` `ebs/check_s3fs.php` + `ebs/register_instance_to_shared_application_load_balancer.php` still hardcode the old dead key** (verified on `origin/_production` 2026-10-13; TRUE-82705 did not convert them). Not on the request path; follow up with Jeff/DevOps.
 - Verify assume-role in CloudTrail (`AssumeRole` on `WorkloadsRuntime`, by session name: `library-app-cloud`, `setup-git-libraries`, `register-instance`, `worker-deploy`).
 - Open, not fixed (developer owns): remove `AWS_ACCESS_KEY_ID`/`AWS_SECRET_KEY` from `agilant-worker` EB env properties.
 
 ## Change history
 - 2026-10-12 — Created: removed the static IAM key from all 1.0 code/config; App_Cloud, deploy scripts and `setup_git_libraries.php` assume `WorkloadsRuntime` (TRUE-82705) (jcardinal)
+- 2026-10-13 — S3 403 triage, silent `copyFileToS3` failure, unconverted togadesk/togaview ebs scripts (TRUE-82712) (mhammontree)

package/knowledge/1.0/apps/library/features/mvc-page-pattern-and-app-skeleton.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-10-01
+updated: 2026-10-13
 owners: [jcardinal, mhammontree]
 files:
   - library/app/framework.php
@@ -15,9 +15,11 @@ files:
   - library/app/database.php
   - library/app/model.php
   - library/app/config.php
+  - library/app/cloud.php
 related:
   - ../architecture.md
   - ../../togaview/architecture.md
+  - app-cloud-aws-credentials.md
 ---
 
 Recipe for a new 1.0 (`App_`) app and for adding pages: folder-based MVC routing, page lifecycle, models, multi-DB config; open when standing up a 1.0 app or adding a route.
@@ -63,6 +65,8 @@ class App_Model_Toga_Client extends App_Model {
 ```
 Usage: `new App_Model_X($id)` loads a row; `->save()` persists; `App_Model_X::lookupValueByField()`.
 
+`BLOBSTORAGE` fields are not in the row — the file lives outside the DB at `<env>/<DatabaseName>/<Table>/<field>/<id>` (`<env>` = `prod` when `worker`). `buildModel()` reads it on **every** model load: dev mode → local `[internal] storage_folder`; otherwise downloads it from S3 bucket `asifiles` via `App_Cloud::getFileFromS3()`. `save()` uploads/deletes it the same way.
+
 ### Databases (multiple are first-class)
 DB access is mysqli via `App_Database::query($sql, 'db_<name>')`. **Multiple databases are first-class:** each `[database_<name>]` section in `config.<env>.ini` is registered as registry key `db_<name>` by `App_Database::registerDatabaseConnect()`. SELECTs **auto-route to `<link>_read`** when the host is an RDS cluster (read-cluster support). Escape with `App_Database::sqlEscape()`; read results with `buildArrayOfRows()` / `fetchRow()`.
 
@@ -85,6 +89,7 @@ The app depends on the `library` core repo (bootstrapped via `_.php`).
 
 - **Route folders must stay distinct.** Matching is longest-to-shortest, so overlapping route folders can produce surprise matches.
 - **An unset `ENVIRONMENT` loads PRODUCTION config.** `getenv('ENVIRONMENT')` defaults to `'worker'`, so running a 1.0 cron locally without it loads `worker/config.worker.ini` — prod DB hosts, `test_mode=0`, `email_errors=1`. Set `ENVIRONMENT` to your dev config name (`config.dev-<name>.ini`) first. Symptom: errors mention `/var/www/cache`.
+- **An S3 error makes a plain model load fatal.** Any model with a `BLOBSTORAGE` field calls S3 in its constructor; `getFileFromS3()` swallows only 404 and rethrows the rest, so an AWS credential/permission failure turns `new App_Model_X($id)` into a redbox on every page that loads it (TRUE-82712: TOGa Desk MSP select via `ClientMsp.logo`, and NYCDOE `Repair::addNotes` via `App_Model_Common_NYCDOETicket.rawData`). Triage: [App_Cloud credentials](app-cloud-aws-credentials.md#gotchas).
 - **Secrets are currently stored in plaintext ini files** — a known practice, not a recommended one. Document where a credential lives, never its value.
 
 ## Related
@@ -93,3 +98,4 @@ The app depends on the `library` core repo (bootstrapped via `_.php`).
 
 ## Change history
 - 2026-10-01 — Unset-`ENVIRONMENT` gotcha: it loads production config locally; added symptom and fix (TRUE-82180). (mhammontree)
+- 2026-10-13 — `BLOBSTORAGE` load/save path + S3-error-is-fatal gotcha (TRUE-82712). (mhammontree)

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

@@ -6,7 +6,7 @@ project: TOGa Desk
 client: shared
 type: architecture
 status: active
-updated: 2026-10-02
+updated: 2026-10-13
 owners: ["mhammontree", "jcardinal"]
 files:
   - index.php
@@ -25,6 +25,9 @@ files:
   - desk/includes/functions.php
   - desk/template/header.php
   - ebs/setup_phpini.php
+  - .ebextensions/020_setup_git_libraries.config
+  - ebs/check_s3fs.php
+  - ebs/register_instance_to_shared_application_load_balancer.php
 related:
   - 1.0/apps/togadesk/features/per-client-host-restriction.md
   - 1.0/apps/togaview/architecture.md
@@ -36,6 +39,7 @@ related:
   - 1.0/apps/togadesk/features/notifications.md
   - 1.0/apps/togadesk/workflows/standalone-test-scripts.md
   - 1.0/apps/togadesk/features/staff-sso-login.md
+  - 1.0/apps/library/features/app-cloud-aws-credentials.md
 ---
 
 1.0 (App_) support desk + field-service platform — staff at `/desk/`, public/client portal at `/`; open for the request pipeline, domain-class layer, MSP data model, crons/integrations, or system topology.
@@ -147,6 +151,7 @@ Invariants:
 - The prod O365 OAuth secret used by `crons/tickets_prod.php` has a **hard expiry (~2026-12-20)**.
 - **Cross-tenant login hole in the per-client host restriction (pre-existing, NOT fixed).** The password-login access condition in `desk/includes/functions.php` (~L627-631) is a chain of ORs; two clauses grant access regardless of which client's subdomain is in use, letting an IM Houston or Fordham user sign in on another client's branded host. Post-login filtering keys off the session `clientid` so it is not an immediate record leak, but it defeats the restriction and contradicts the comment directly above it. Deserves its own ticket.
 - **Sessions are host-scoped, so a domain change logs everyone out.** `ebs/setup_phpini.php` sets `session.save_handler=rediscluster` but no `session.cookie_domain`, and there is no `session_set_cookie_params()` anywhere. Combined with `people.sessionid` being a **single column**, logging in on a second domain invalidates the session on the first.
+- **Library is not in this repo — a library fix is live in Desk only after a Desk deploy.** `.ebextensions/020_setup_git_libraries.config` clones `library` on every EB deploy; both loaders `require_once('_.php')` from the include path. An S3 403 / `InvalidAccessKeyId` redbox (e.g. selecting an MSP, which loads the `ClientMsp.logo` blob field) is a library credentials problem, not Desk code — see [App_Cloud credentials](../library/features/app-cloud-aws-credentials.md#gotchas). `ebs/check_s3fs.php` and `ebs/register_instance_to_shared_application_load_balancer.php` still hardcode the old dead IAM key (open).
 
 ## Related
 - [Staff SSO login](features/staff-sso-login.md)

package/knowledge.js

@@ -32,6 +32,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 const ROOT = path.join(__dirname, 'knowledge');
 const REGISTRY = path.join(ROOT, 'registry.json');
@@ -1048,10 +1049,31 @@ function cmdSkills(args) {
  * every resolved knowledge doc in the main session; the gate detects it and releases.
  *
  * This command intentionally does nothing but confirm — the gate keys off the command
- * itself, so no shared state is needed here.
+ * itself, so no shared state is needed here. The gate only allows the exact 3-word form, so
+ * the session id comes from the env (as the hooks read it), never a flag. After the confirm
+ * line it repeats the /rename line when /start saved a session title; else nothing extra.
  */
+const MAX_SESSION_TITLE_LENGTH = 60;
+
+// Saved "<TICKET>: <short>" title from /start (start-helper.js set-title), or ''.
+function currentSessionTitle() {
+    const sid = String(process.env.CLAUDE_SESSION_ID || process.env.CLAUDE_CODE_SESSION_ID || '').replace(/[^A-Za-z0-9_-]/g, '');
+    if (!sid) return '';
+    const dir = process.env.TOGA_SESSIONS_DIR || path.join(os.homedir(), '.claude', 'toga-sessions');
+    try {
+        const t = JSON.parse(fs.readFileSync(path.join(dir, sid + '.json'), 'utf8')).sessionTitle;
+        return typeof t === 'string' ? t.replace(/[\u0000-\u001f\u007f`]+/g, ' ').trim().slice(0, MAX_SESSION_TITLE_LENGTH) : '';
+    } catch (e) {
+        if (e.code !== 'ENOENT') console.error('currentSessionTitle: ' + e.message);
+        return '';
+    }
+}
+
 function cmdKickoffPrimed() {
     console.log('Team knowledge base primed in the main session — start gate released. Priming was synchronous; no subagents ran during it.');
+    const title = currentSessionTitle();
+    // Same text as skills/start/scripts/start-helper.js cmdSetTitle tellDeveloper — keep in sync.
+    if (title) console.log('Reminder — tell the developer: Paste this to name the session: `/rename ' + title + '`');
 }
 
 function main() {

package/package.json

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

package/skills/start/SKILL.md

@@ -102,7 +102,9 @@ prefix words only if needed to stay short; never "TOGa". Max 60 characters. Save
 node ".../start-helper.js" set-title --session <sid> --title "<T>: <short>"
 ```
 
-Then tell the developer in one line: "Paste this to name the session: `/rename <title>`".
+**Send the `tellDeveloper` line now — never skip, never defer.** Team rule for every developer.
+Put it in its own message, as its own plain line (not in a code block), BEFORE you start Step 4.
+Do not wait for the Step 8 brief. Example: Paste this to name the session: `/rename TRUE-82605: ClickUp workflow`
 The SessionStart hook also offers it as the session title on resume/compact, only when the
 developer has not named the session.
 
@@ -239,11 +241,14 @@ Status flow: to do -> in progress (/start) -> development finished (/finish).
 ## Step 8 — Brief
 
 Show a short brief, then propose the plan (multi-agent for non-trivial work, as in the old
-kickoff Step 6: planner -> implement -> reviewers; auto-review rules apply):
+kickoff Step 6: planner -> implement -> reviewers; auto-review rules apply).
+Start the brief with the rename line, as its own plain line ABOVE the code block:
+
+**Name this session:** `/rename <session title>`
 
 ```
 Ticket:     <T> — <title>  (<status>, <list>)
-Session:    <session title>  (paste: /rename <session title>)
+Session:    <session title>
 Apps:       <repos>  (core: <core>)
 Clients:    <clients>
 Task type:  <type>

package/skills/start/scripts/start-helper.js

@@ -357,7 +357,14 @@ function cmdSetTitle(args) {
   if (title.length > MAX_TITLE_LENGTH) return fail('title is longer than ' + MAX_TITLE_LENGTH + ' characters');
   r.s.sessionTitle = prefix + title.slice(prefix.length);
   writeSession(r.sid, r.s);
-  print({ ok: true, sessionId: r.sid, ticket: r.s.ticket, sessionTitle: r.s.sessionTitle });
+  print({
+    ok: true,
+    sessionId: r.sid,
+    ticket: r.s.ticket,
+    sessionTitle: r.s.sessionTitle,
+    // Same text as knowledge.js cmdKickoffPrimed reminder — keep in sync.
+    tellDeveloper: 'Paste this to name the session: `/rename ' + r.s.sessionTitle + '`',
+  });
 }
 
 /* Secret scan for text Claude is about to post (PR body, PM comment). Prints hit TYPES only. */