toga-ai 1.0.574 → 1.0.577

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

@@ -9,6 +9,7 @@
 | [ENVIRONMENT (not the EB environment name) decides the _underscore branch and Config file](features/environment-variable-drives-underscore-branch.md) | An api2 Elastic Beanstalk instance decides **which `_underscore` branch it clones** and **which `Config/<env>.ini` it loads** from the EB environment property * | api2/.ebextensions/git.php, api2/.ebextensions/php_include_underscore.config, api2/.ebextensions/git.sandbox-dev.json, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, api2/Component/Api/V2/V2.php |
 | [Health-check endpoint (/health liveness short-circuit)](features/health-check-endpoint.md) | `_Controller_Index::api()` short-circuits **liveness/health-probe** requests to an HTTP 200 **before** any routing, DB bootstrap, or V2 engine work runs. | api2/Controller/Index.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
+| [/auth/login resolves the client from the email domain, not the Bearer token (cross-client user path)](features/login-cross-client-user-resolution.md) | `POST /v2/auth/login` (email/password user login) can silently swap the target client mid-request. | api2/Component/Api/V2/V2.php, _underscore/String.php |
 | [Nested FK object embedding is gated by the CHILD record's own ACL](features/nested-fk-acl-embedding.md) | When the V2 JSON engine serializes a foreign-key field into a **nested object** (in `getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record | api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql |
 | [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ContactEmailAddress.php |
 | [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Query.php |

package/knowledge/2.0/apps/api2/features/login-cross-client-user-resolution.md

@@ -0,0 +1,76 @@
+---
+title: "/auth/login resolves the client from the email domain, not the Bearer token (cross-client user path)"
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-08-13
+owners: [apeterson]
+files:
+  - api2/Component/Api/V2/V2.php
+  - _underscore/String.php
+related:
+  - ./cross-client-data-retrieval.md
+  - ./surface-meta-option.md
+  - ../../_underscore/features/per-client-database-connections.md
+---
+
+## What it is
+
+`POST /v2/auth/login` (email/password user login) can silently swap the target client
+mid-request. When the credentialed user is a **cross-client (home) user**, the engine
+abandons the client it started on and re-registers the user's **home** client's databases
+before minting the token. Understanding this path is the difference between diagnosing a
+login `EO-1` in minutes vs. hours — especially in local dev, where the home client's DB
+usually does not exist.
+
+## How it works
+
+`_Component_Api_V2::execute()` (~L701-744):
+
+1. The user is loaded **by email** from the current client's DB (~L705) — the client is
+   resolved from `ClientEmailDomains`, **not** from any Bearer token.
+2. The submitted password is checked with `_String::passwordVerify()` → `password_verify()`
+   (bcrypt) against the local user row (`_underscore/String.php` L563-576).
+3. **If the password does NOT verify AND the loaded user row has a non-null `clientId` that
+   differs from the current client**, the engine treats it as a **cross-client user**: it
+   calls `registerClientDatabases($user->clientId)` and re-loads the *home* user via
+   `homeClientUserId` (~L716-731). Authentication then completes against the home client.
+
+This is the same `homeClientUserId` bridge that
+[cross-client data retrieval](./cross-client-data-retrieval.md) uses to fan a home user out
+across tenant DBs — here it governs which client a login actually authenticates against.
+
+## Gotchas
+
+- **A login `EO-1 "Unknown database 'client_<x>'"` is the cross-client branch failing to
+  open the home client's DB.** Observed: logging into **Elite** locally with
+  `devteam@togatech.com` throws `EO-1 Unknown database 'client_true'`. That account is an
+  internal TOGA (client `true` / `Client_True`) user shared into Elite via
+  `homeClientUserId`; because its Elite-local password does not verify, the cross-client
+  path tries to open `Client_True`, which does not exist in local dev. It works on the dev
+  sandbox only because `Client_True` exists there.
+- **Local-dev workaround (never commit):** set the **local** `Client_<Client>` user's own
+  bcrypt password hash to a known value so login succeeds on the **direct** path and never
+  enters the cross-client branch. Generate with `_String::passwordHash()` /
+  `password_hash($pw, PASSWORD_BCRYPT)`. This is a per-machine local fixup, not a code or
+  data change to commit.
+- **The api2 dev server talks to `localhost` as `root` — sandbox DB edits are invisible to
+  it.** Local stack traces show `mysqli_connect(["localhost","root",...])`. Any ACL/grant/
+  password change must be applied to the **localhost** client DB, not a sandbox connection
+  in a DB GUI, or the local API will never see it. (In DbGate specifically: "Run"
+  autocommits; a query-tab "unsaved" label refers to the unsaved `.sql` *script file*, not
+  pending uncommitted data.) This exact confusion — a grant present in sandbox while the API
+  read localhost — cost real debugging time.
+
+## Change history
+- 2026-08-13 — Initial capture from an Elite local-dev login debug session (no code
+  changes). Documented that `/auth/login` resolves the client from the email domain and, on
+  a local-password miss for a user whose `clientId` differs, follows the `homeClientUserId`
+  cross-client branch (`V2.php` ~L701-744), which throws `EO-1 Unknown database` when the
+  home client's DB is absent locally; plus the local-dev workarounds (set the local bcrypt
+  hash; apply changes to the localhost DB, not sandbox). (apeterson)
+</content>
+</invoke>

package/knowledge/2.0/apps/api2/features/surface-meta-option.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-15
+updated: 2026-08-13
 owners: [jcardinal, apeterson]
 files:
   - api2/Component/Api/V2/V2.php
@@ -94,6 +94,14 @@ FE, the type `RecordSurfaceState` (`src/surface/types.ts`) is
   silently lack it.
 
 ## Change history
+- 2026-08-13 — Confirmed the per-client seed gap in the wild: **Elite** was missing the
+  `surfaces/meta` dispatch grant in its client DB, so `GET /v2/surfaces/meta` 403'd EZ-1
+  with `identifiers.script = "meta"` while other clients worked. Concrete reference data:
+  Core `Records` route `surfaces` id **333** (`aclDatabase = CORE`), Core `RecordScripts`
+  `meta` id **28** (GET); the grant lives in `Client_<slug>.AclRecordScripts`
+  (`recordScriptId = 28`, `roleId = 1` for CORE Public). This is a per-client seed-gap class
+  — the grant must be captured in a `dbchanges2` `Client_<Name>` migration, not just
+  inserted locally. (apeterson)
 - 2026-07-20 — Documented the `meta.surface`/`recordSurfaceState` payload flow: computed only when the
   `surface` option is present AND action is READ (V2.php ~5688-5717); single-GET shape
   `{slug, state:{<elementUuid>:{isVisible,isEnabled}}}`, LIST shape

package/knowledge/INDEX.md

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

package/knowledge/clients/elite/profile.md

@@ -15,7 +15,7 @@ project: Worker
 client: elite
 type: profile
 status: active
-updated: 2026-08-12
+updated: 2026-08-13
 owners: [snaredla, apeterson, tcox, bala]
 files:
   - worker2/Worker/Elite.php

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.574",
+  "version": "1.0.577",
   "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/scripts/hooks/kickoff-gate.js

@@ -68,12 +68,15 @@ function readPayload() {
     try { data.tool_input = JSON.parse(process.env.CLAUDE_TOOL_INPUT); } catch (e) {}
   }
   if (!data.prompt && process.env.CLAUDE_USER_PROMPT) data.prompt = process.env.CLAUDE_USER_PROMPT;
-  if (!data.session_id && process.env.CLAUDE_SESSION_ID) data.session_id = process.env.CLAUDE_SESSION_ID;
+  if (!data.session_id) data.session_id = process.env.CLAUDE_SESSION_ID || process.env.CLAUDE_CODE_SESSION_ID;
   return data;
 }
 
 function lockPath() {
-  return path.join(process.cwd(), '.claude', '.kickoff-gate.json');
+  // Anchor to the project dir (reliably provided by the harness) rather than the shell's
+  // cwd, so the hook and a manually-run `kickoff-primed` always agree on the lock location.
+  const base = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return path.join(base, '.claude', '.kickoff-gate.json');
 }
 
 function readLock() {
@@ -250,10 +253,10 @@ function main() {
       // preflight ADVANCES to stage 2 (does NOT release) — the team KB is still unprimed.
       if (isPreflightBash(command)) { writeLock(lock.session, 'primer'); process.exit(0); }
       if (isPrimingBash(command)) process.exit(0); // other read-only priming step
-      console.log(armedMessage());
+      console.error(armedMessage());
       process.exit(2);
     }
-    if (BLOCKED_TOOLS.has(tool)) { console.log(armedMessage()); process.exit(2); }
+    if (BLOCKED_TOOLS.has(tool)) { console.error(armedMessage()); process.exit(2); }
     process.exit(0); // AskUserQuestion, Skill, TodoWrite, … — part of the interview
   }
 
@@ -263,7 +266,7 @@ function main() {
     // Priming must run in the MAIN session; delegating it (or fanning out other agents
     // alongside it) is exactly what this stage forbids.
     if (tool === 'Agent' || tool === 'Task') {
-      console.log(primerMessage());
+      console.error(primerMessage());
       process.exit(2);
     }
     if (tool === 'Bash') {
@@ -271,22 +274,22 @@ function main() {
       // has read every resolved doc itself, in the main session.
       if (isPrimedSentinelBash(command)) { clearLock(); process.exit(0); }
       if (isPrimingBash(command)) process.exit(0); // knowledge.js search/get, version check, …
-      console.log(primerMessage());
+      console.error(primerMessage());
       process.exit(2);
     }
     if (tool === 'Read') {
       const p = toolInput.file_path || toolInput.path;
       if (isMemoryReadPath(p)) process.exit(0); // repo-path lookup
       if (isTeamKbPath(p)) process.exit(0);      // reading a team-KB doc IS the priming
-      console.log(primerMessage());              // repo code — blocked until primed
+      console.error(primerMessage());              // repo code — blocked until primed
       process.exit(2);
     }
     if (tool === 'Grep' || tool === 'Glob') {
       if (isTeamKbSearch(toolInput)) process.exit(0); // locating a doc inside knowledge/
-      console.log(primerMessage());                    // searching repo code — blocked
+      console.error(primerMessage());                    // searching repo code — blocked
       process.exit(2);
     }
-    if (BLOCKED_TOOLS.has(tool)) { console.log(primerMessage()); process.exit(2); } // Edit/Write/…
+    if (BLOCKED_TOOLS.has(tool)) { console.error(primerMessage()); process.exit(2); } // Edit/Write/…
     process.exit(0); // AskUserQuestion (ask for a repo path), Skill, … — allowed
   }