toga-ai 1.0.381 → 1.0.383

package/knowledge/2.0/apps/ai-bdr/features/web-funnel-app.md

@@ -6,7 +6,7 @@ project: AI-BDR
 client: shared
 type: feature
 status: active
-updated: 2026-07-16
+updated: 2026-07-20
 owners: [tcox]
 files:
   - bdr/PLAN.md
@@ -31,14 +31,19 @@ files:
   - bdr/src/components
   - bdr/src/flow
   - bdr/src/server
+  - bdr/src/server/toga.ts
   - bdr/src/app/api
   - bdr/test
+  - bdr/test/togaPrimaryPhone.test.ts
   - bdr/public
   - bdr/mockup/styles.css
 related:
   - web-funnel-content-model.md
   - bdr-web-funnel-plan.md
   - ../architecture.md
+  - ../workflows/safe-call-loop-testing.md
+  - ../../worker2/features/vapi-webhook-handler.md
+  - ../../api2/features/nested-relationship-writes.md
 ---
 
 ## What this is
@@ -88,7 +93,9 @@ to its ship state (trusted-IP position for X-Forwarded-For; O(1) LRU-capped limi
 - **ESLint flat config** carries a **no-em-dash rule** on shipped strings
   (`Literal` / `TemplateElement` / `JSXText` selectors) — enforces the mockup copy
   rule on in-repo strings (`eslint.config.mjs`).
-- **Vitest** test suite: **104 tests, all green** (13 added in the first 2026-07-16 session:
+- **Vitest** test suite: **114 tests, all green** (10 added 2026-07-20 for the primary-phone
+  self-heal — null-pointer re-link, changed-number re-link, create-as-last-resort, strict
+  `requestCall` vs. absorbing `upsertContactByEmail`; 13 added in the first 2026-07-16 session:
   phone format/prefill/mask, live-anchor consent links, `submitOk` race; the later 2026-07-16
   session added the rate-limiter + trusted-IP + LRU-eviction + `hsCampaignId` validation tests
   to reach 104). Every phase was verified with `tsc` + lint + build + a live SSR `curl` before
@@ -212,19 +219,33 @@ source of truth for "why isn't my contact being called." Full rules are document
   call windows and weekly cadence limits, but still requires an active campaign **with an
   assigned assistant**, `isActive=1`, `isOkayToCall=1`, a live **primary** phone, and
   `attemptCount < maxAttemptsPerContact`.
-- **BUG — a phone-less HubSpot contact can never receive a call (silent).** When the HubSpot
-  contact has no phone, BDR creates the Toga contact **without** a phone at page-prime; the
+- **BUG (funnel side FIXED — self-heal shipped; api2 platform fix still deferred).** When the
+  HubSpot contact has no phone, BDR creates the Toga contact **without** a phone at page-prime; the
   phone the visitor types arrives later via the Call Now `PUT`. api2 creates a
   `ContactPhoneNumber` row on that update but does **not** set
-  `Contacts.primaryContactPhoneNumberId`. The dialer's eligibility SQL `INNER JOIN`s on
-  `primaryContactPhoneNumberId`, so the contact stays invisible to the dialer. **Re-submitting
-  does not fix it** (verified in production: the phone row exists but the primary pointer
-  stays null). The funnel still shows success and returns `200` — a silent failure. The old
-  `info` site never hit this because CRM-sourced contacts already had a phone at CREATE time
-  (api2 links the primary on create, not on a later update). Fix candidates: api2-side (set
-  the primary when a phone row is created during an update) or a BDR workaround (a follow-up
-  `PUT` linking the existing phone-row uuid as primary). Affects **any** phone-less HubSpot
-  contact and blocks live call testing.
+  `Contacts.primaryContactPhoneNumberId` — the exact api2 root cause (the UPDATE path injects a
+  reverse back-reference into the nested child object, defeating the single-key-uuid forced-MATCH
+  fast-path) is now documented in
+  [api2 nested-relationship-writes.md](../../api2/features/nested-relationship-writes.md). The
+  dialer's eligibility SQL `INNER JOIN`s on `primaryContactPhoneNumberId`, so the contact stays
+  invisible to the dialer, the funnel still shows success and returns `200` — a silent failure. The
+  old `info` site never hit this because CRM-sourced contacts had a phone at CREATE time (api2 links
+  the primary on create, not on a later update).
+  - **Self-heal (SHIPPED, `src/server/toga.ts`, commit `4ac579e`):** after any contact write that
+    carried a phone, if the response echoes `primaryContactPhoneNumber` **null** OR a number whose
+    last-10 digits **don't match** what was sent (stale-pointer / changed-number case), the code
+    finds the orphaned `ContactPhoneNumber` row uuid (from the echoed contact's `contactPhoneNumbers`
+    → fresh `GET /contacts/{uuid}` → creates one via `POST /contact-phone-numbers` as a last resort)
+    and re-links it with an **identifier-only** `PUT {primaryContactPhoneNumber:{uuid}}` (a single-key
+    identifier object hits api2's forced-MATCH path). **`requestCall` is strict** (throws → the route
+    returns `500`, so the UI never reports success for an undial-able submit); **`upsertContactByEmail`
+    absorbs + warns** (lead priming must never break the funnel — call-now re-heals). Covered by 10
+    regression tests (written first, failed on old code; 114-test suite green; an independent review
+    found + fixed the changed-number case). Resolves the funnel-side bug **once `_dev-sandbox` deploys**
+    (deploy still pending — see the deploy note below).
+  - **api2 platform fix is still deferred** to its own PR/ticket (gate the reverse-back-reference
+    injection to true reverse/has-many relations). The self-heal covers the funnel meanwhile; the
+    same api2 bug likely affects `primaryContactEmailAddress` / `primaryContactAddress` on update.
 
 ## Local dev setup (BDR)
 
@@ -244,6 +265,30 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
 - **Restart the dev server after creating `.env.local`** — Next reads env files only at
   server startup. `.env.*` is gitignored in BDR.
 
+## Deploy status (AWS Amplify — NOT yet deployed)
+
+The BDR site is **not deployed anywhere yet** (as of 2026-07-20). Go-live is blocked on the
+Amplify setup, tracked by ClickUp **868kdf4tj "BDR - create amplify and sandbox route"** (urgent,
+Sprint 82) — still `to do`. (ClickUp shows Alex Peterson as assignee; the team says Jeff picked it
+up — ClickUp is stale, confirm the real owner before assuming.)
+
+- **Deploy branch is `_dev-sandbox`** (underscore-prefix convention), **not** `BDR-Development` /
+  `BDR-Phase-2`. The primary-phone self-heal (commit `4ac579e`, see the phone-less bug above) is
+  already merged into `_dev-sandbox`, so **Amplify's first build ships the fix**.
+- **Amplify must be configured for SSR hosting (NOT static export)** — the app is server-rendered
+  (server components, route handlers, and the `proxy.ts` edge proxy all require the SSR/compute
+  runtime). Point the app at branch `_dev-sandbox`.
+- **5 server-side env vars are required** (same set as local dev): `TOGA_API_BASE_URL`,
+  `TOGA_CLIENT_ID`, `TOGA_CLIENT_API_UUID`, `TOGA_CLIENT_API_SECRET`, `HUBSPOT_ACCESS_TOKEN`.
+  **Where the values live (never the values):** the `info` repo's `.env.local` (production
+  credential set). Add them in the Amplify console environment config — never commit them.
+- **Phase 8 WAF pairing.** `BDR/PLAN.md` Phase 8 specifies a **per-IP rate rule on the CloudFront
+  distribution / WAF** that pairs with the in-app token-bucket limiter (the app limiter is
+  defense-in-depth only; the edge WAF rule is the authoritative control — see the enumeration
+  gotcha). Configure it as part of the Amplify/CloudFront setup, along with the non-gating `cso`
+  follow-ups (lock the Amplify origin to CloudFront; verify `CloudFront-Viewer-Address` inject+strip
+  before trusting it).
+
 ## What is parked / not built
 
 - **Creator screen + `TweaksPanel` — deliberately NOT ported** (parked per plan
@@ -371,6 +416,19 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
   harness; pull it with `npx toga-ai`.
 
 ## Change history
+- 2026-07-20 — FIXED the phone-less-contact dialer bug on the funnel side: shipped a primary-phone
+  **self-heal** in `src/server/toga.ts` (commit `4ac579e`) — after any contact write carrying a
+  phone, if the echoed `primaryContactPhoneNumber` is null or its last-10 digits mismatch, find/create
+  the `ContactPhoneNumber` row uuid and re-link via an identifier-only `PUT {primaryContactPhoneNumber:
+  {uuid}}` (single-key forced-MATCH). `requestCall` is strict (throws → route 500, UI never falsely
+  reports success); `upsertContactByEmail` absorbs+warns (priming never breaks the funnel; call-now
+  re-heals). 10 regression tests (114 suite green; independent review found+fixed the changed-number
+  case). The **exact api2 root cause** was also located and documented (UPDATE-path reverse-back-ref
+  injection defeats the uuid forced-MATCH — see api2 `nested-relationship-writes.md`); the api2 platform
+  fix is deferred. Added the **Deploy status** section: BDR is not deployed yet (ClickUp 868kdf4tj still
+  to-do); deploy branch is `_dev-sandbox` (now carrying the self-heal); Amplify needs SSR (not static),
+  the 5 server env vars (values sourced from `info`'s `.env.local`), and the Phase 8 per-IP WAF rate
+  rule. (tcox)
 - 2026-07-16 — Rate-limit mitigation HARDENED to ship state after an independent `cso` security
   review returned **SHIP after two rounds** (supersedes the mid-state recorded in the entry
   below: test count is **104**, not 89, and the review is complete, not "still running"). Added

package/knowledge/2.0/apps/ai-bdr/workflows/safe-call-loop-testing.md

@@ -0,0 +1,112 @@
+---
+title: Safe AI-BDR Call-Loop Testing (isolated test-campaign runbook)
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: workflow
+status: active
+updated: 2026-07-20
+owners: [tcox]
+files:
+  - dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql
+  - worker2/Worker/Ai/Bdr/Vapi.php
+  - worker2/Config/beta.ini
+related:
+  - new-campaign-onboarding.md
+  - ../architecture.md
+  - ../../worker2/features/vapi-webhook-handler.md
+---
+
+## Summary
+
+How to prove the AI-BDR **dialer → Vapi → end-of-call webhook** loop end-to-end **without
+dialing real prospects**. The production dialer cron (`Core.CronJobs` "AI BDR",
+`ProcessAllActiveCampaigns`, schedule `* * * * *`) fires **every minute**, so any campaign that
+becomes eligible starts dialing live prospects **within 60 seconds** — a test must be built so
+that the *only* contact that can ever be dialed is a deliberate test contact. The safe technique
+is an **isolated one-contact test campaign with no call windows**. Eligibility mechanics that make
+this work are in [worker2 vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md).
+
+## Rule 1 — NEVER revive an ended campaign that has linked prospects
+
+An ended campaign (`dateEnd` in the past) is rejected every run by `validateCampaignReady`
+("Campaign has ended"). Flipping `dateEnd`/`isActive` to revive it makes **all** its
+contact-level-dialable contacts eligible at once, and the every-minute cron dials them within
+60s. (Observed live: campaign `26.05 - AI BDR - Ryan Nitti` was blocked **solely** by
+`dateEnd`; it had 132 linked contacts, ~86 contact-level dialable — reviving it would have
+dialed real prospects in one cron tick.) Likewise, do **not** blanket-flip `isOkayToCall=1` on a
+real list: it is two mass writes plus a restore burden, and it silently un-blocks any contact
+that was intentionally set `isOkayToCall=0`.
+
+## Rule 2 — Use an isolated one-contact test campaign with NO call windows
+
+The safe posture exploits the eligibility split (see vapi-webhook-handler.md): the normal
+(non-requested) dial path requires a `CampaignCallWindows` row for the current day/time, but the
+**requested** path (`dtNextContactRequested <= NOW()`) bypasses windows/cadence. So:
+
+1. **Deactivate any ended campaign** that shares the environment (also silences the every-minute
+   "Campaign has ended" cron error).
+2. **Create a dedicated test campaign** copied from a known-good campaign's config (same assistant
+   / Cal.com event / timezone, a short window e.g. 7 days, the normal attempt cap), with a
+   **hardcoded UUID** so the migration is idempotent and re-runnable.
+3. Create **NO `CampaignCallWindows` rows** for it. With no call windows, the campaign can **only
+   ever dial a contact that has a pending `dtNextContactRequested`** — never a normal-cadence
+   contact.
+4. **Link exactly ONE test contact** (by uuid, `INNER JOIN`-guarded so the migration no-ops on any
+   environment that lacks that contact). That single linked contact is the *only* thing the
+   campaign can dial, and only when you set its `dtNextContactRequested`.
+
+Reference implementation: `dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql`
+(idempotent `NOT EXISTS` guards keyed to the real UNIQUE constraints; passed `sql-reviewer`). This
+proves the loop with **zero prospect exposure** instead of mass-writing flags on real contacts.
+
+## Rule 3 — NEVER dry-run against production
+
+`dryRun` in the dialer is **not** write-free: `createContactAttempt` runs **before** the dryRun
+early-return, writing a real `ContactAttempts` row (`dtStarted` set, `dtEnded NULL`) that counts
+toward `maxAttemptsPerContact` **and** wedges the contact as in-progress (excluded from all future
+dialing). See the dryRun gotcha in vapi-webhook-handler.md. Unwedge SQL:
+`UPDATE ContactAttempts SET dtEnded=NOW() WHERE contactId=? AND dtEnded IS NULL`.
+
+## Rule 4 — Validate the assistant identifier before assigning it
+
+`validateCampaignReady` only checks `assistantIdentifier` is **non-empty**, not that it is a
+well-formed Vapi UUID. A corrupt value (e.g. a 37-char uuid-plus-trailing-char) passes the gate
+and then **400s at Vapi** at call time. Confirm the assistant's identifier shape before wiring it
+to any campaign, test or real.
+
+## Why a true beta end-to-end CALL is impossible as currently wired
+
+Do **not** expect to place a real beta call and see its webhook land in the beta DB:
+
+- Vapi is **one production account**. Its assistants' `serverUrl` targets the **production**
+  webhook (`webhook.togahub.com`). A beta-placed call's `end-of-call-report` therefore posts to
+  **production**, where the `contactAttemptUuid` (created in the **beta** DB) has no matching row
+  → the write-back can never find its attempt.
+- **Beta is good only for rehearsing the SQL / eligibility logic** via a **local worker2 run**
+  (not a real call). Note `worker2/Config/beta.ini`'s `aws_worker_queue_url` still points at
+  `WorkerProductionQueue` — another reason not to trust beta for anything that enqueues work.
+
+A real end-to-end call test must run against production, which is exactly why the isolated
+one-contact test campaign (Rule 2) is the safe vehicle.
+
+## dbchanges2 execution caveat — don't ship create + cleanup in the same window
+
+The dbchanges2 external executor runs a folder's files **alphabetically in one pass**. Never place
+a create-migration and its cleanup/teardown migration in the **same** run window (same day/folder
+batch) — they will apply together in one pass and the cleanup will immediately undo the create.
+Sequence the cleanup into a later, separately-executed window. (See dbchanges2 architecture for the
+`YYYY-MM-DD<letter>` ordering contract.)
+
+## Change history
+- 2026-07-20 — Initial runbook. Captured the safe AI-BDR call-loop test procedure: never revive an
+  ended campaign with linked prospects (every-minute cron dials within 60s); use an isolated
+  one-contact test campaign with NO `CampaignCallWindows` (only requested `dtNextContactRequested`
+  calls can fire) as built in `dbchanges2/Client_True/2026-07-20a`; never dry-run in prod (writes a
+  wedging ContactAttempts row); validate the assistant identifier shape (non-empty check lets a
+  corrupt uuid 400 at Vapi); a true beta end-to-end call is impossible (single prod Vapi account →
+  webhook posts to prod, beta contactAttemptUuid unmatchable); and the dbchanges2 same-window
+  create+cleanup execution caveat. (tcox)
+</content>
+</invoke>

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

@@ -6,13 +6,15 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
-owners: ["bala", "mhammontree"]
+updated: 2026-07-20
+owners: ["bala", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
 related:
   - ../architecture.md
   - ../../../clients/aig/features/entitlement-intake.md
+  - ../../ai-bdr/features/web-funnel-app.md
+  - ../../worker2/features/vapi-webhook-handler.md
 ---
 
 ## Summary
@@ -58,6 +60,39 @@ rows on every write.
 If you need to link by a business key (like an employee XID), **resolve that key to a uuid in your
 caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
 
+## UPDATE-path back-reference injection defeats the uuid forced-MATCH (primary-pointer bug)
+
+A **single-key identifier object** (`{uuid: <x>}` and nothing else) is supposed to hit the
+engine's **forced-MATCH fast-path** (`V2.php:6952`) — link the existing child, never create,
+and let the caller re-point a parent's forward FK to it. On the **CREATE** path this works: the
+set-loop (`V2.php:4601–4616`) applies the child object and the parent FK is assigned at
+`V2.php:4647` with no interference.
+
+On the **UPDATE** path it does **not**. When a child model carries a `contactId` FK *back* to
+the parent (as `ContactPhoneNumbers` → `Contacts` does), the update path **injects a reverse
+back-reference** (sets the child's `contactId = parent id`) into the nested child object at
+`V2.php:4985–4996` — added by commit `91d803f` "guard child FK set". That injection turns the
+single-key object into a **multi-key** object, so it no longer qualifies for the forced-MATCH
+fast-path, and it diverts what `getForeignKeyValue()` returns **before** the parent's forward FK
+is assigned at `V2.php:5047`. Net effect: a `PUT {primaryContactPhoneNumber: {uuid}}` does **not**
+set `Contacts.primaryContactPhoneNumberId`, and the `PUT` response **echoes
+`primaryContactPhoneNumber: null`** on the miss — which callers can detect.
+
+**Scope.** Any **forward singular FK** whose child model has a back-FK to the parent is exposed
+on update — `primaryContactEmailAddress` / `primaryContactAddress` on `Contacts` are likely
+affected the same way. This is the exact root cause of the **BDR web-funnel "phone-less contact
+is never dialed"** bug (a phone added by a later `PUT` links a `ContactPhoneNumber` row but never
+becomes the primary): see
+[web-funnel-app.md](../../ai-bdr/features/web-funnel-app.md) and
+[vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md).
+
+**Suggested platform fix (deferred to its own PR/ticket):** gate the `4985–4996` injection to
+**true reverse / has-many** relations only, so a forward singular-FK child keeps its single-key
+forced-MATCH; confirm `RecordFields.childPolicy` for `Contacts.primaryContactPhoneNumberId` when
+fixing. Until then the caller-side workaround is a follow-up identifier-only `PUT` re-link with a
+self-heal that detects the null/mismatched echo (shipped on the BDR funnel side — see
+web-funnel-app.md).
+
 ## Per-API overrides (`Apis_RecordFields`)
 
 The base identifier flags above (`Core.RecordFields.isIdentifier`) can be **overridden per API**
@@ -100,6 +135,15 @@ beta/QA threw EV-12 on the injected `entitlementFulfillmentType` — see
 
 ## Change history
 
+- 2026-07-20 — Root-caused the **UPDATE-path** failure of the single-key-uuid forced-MATCH: the
+  update path injects a reverse back-reference (`contactId = parent id`) into nested child objects
+  at `V2.php:4985–4996` (commit `91d803f`) when the child has a back-FK to the parent, turning the
+  single-key object multi-key and diverting `getForeignKeyValue()` before the forward FK assignment
+  at `:5047` — so `PUT {primaryContactPhoneNumber:{uuid}}` never sets the pointer and the response
+  echoes `null`. CREATE path (`:4601–4616` / `:4647`) is unaffected. Scope: any forward singular FK
+  whose child has a back-FK to the parent (likely `primaryContactEmailAddress`/`primaryContactAddress`
+  too). This is the root cause of the BDR web-funnel phone-less-contact dialer bug; platform fix
+  deferred to its own PR (gate the injection to true reverse/has-many relations). (tcox)
 - 2026-07-09 — Documented the per-API `Apis_RecordFields` override layer (`overrideIsIdentifier`,
   `overrideChildPolicy`) and the trap that a `NULL` `overrideIsIdentifier` is read as "not an
   identifier" (`!$row->overrideIsIdentifier`) — an override row set only for a child policy

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

@@ -10,6 +10,7 @@
 | [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
 | [ClickUp Rich-Text Custom Fields via Quill Delta (API)](features/clickup-richtext-api.md) | ClickUp custom text fields (type `text` and long-text) support rich formatting only through a **Quill Delta** written to the undocumented `value_richtext` key o | test/@dave/clickup_md2delta.js, .claude/skills/plan-ticket/scripts/clickup.js |
 | [ClickUp Subtask Activity → Parent Opportunity/Epic Comments](features/clickup-subtask-activity.md) | Surfaces **subtask** progress, completion, and discussion on the top-level **Opportunity** or **Epic** it rolls up to, so a deal/project owner sees activity whe | worker2/Worker/Clickup/Subtask.php, worker2/Worker/Clickup.php, dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql |
+| [ClickUp Task Description Fluffer (Talos KB Investigation)](features/clickup-task-fluffer-talos.md) | `_Worker_Clickup_Fluffer` "fluffs" a ClickUp task by sending its name + existing description to the **Talos `dev-core` KB-investigation agent** and writing the | worker2/Worker/Clickup/Fluffer.php, worker2/Worker/Clickup.php, worker2/Config/production.ini, worker2/Config/beta.ini, worker2/Config/dev-rohan-mac.ini |
 | [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.php |
 | [Compass VIP Support Importer (worker2)](features/compass-vip-support-importer.md) | A worker2 action that ingests Compass's quarterly VIP spreadsheet and assigns each VIP user's support technician by setting `Users.c_supportedByUserId` in `Clie | worker2/Worker/Client/Compass/VipSupport.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |

package/knowledge/2.0/apps/worker2/features/clickup-task-fluffer-talos.md

@@ -0,0 +1,156 @@
+---
+title: ClickUp Task Description Fluffer (Talos KB Investigation)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-07-20
+owners: [rgirish]
+files:
+  - worker2/Worker/Clickup/Fluffer.php
+  - worker2/Worker/Clickup.php
+  - worker2/Config/production.ini
+  - worker2/Config/beta.ini
+  - worker2/Config/dev-rohan-mac.ini
+related:
+  - ./clickup-project-routing.md
+  - ./clickup-richtext-api.md
+  - ./talos-transcript-ingestion.md
+  - ./creating-worker-actions.md
+  - ../architecture.md
+  - ../../talos/features/talos-agent.md
+---
+
+## Summary
+
+`_Worker_Clickup_Fluffer` "fluffs" a ClickUp task by sending its name + existing description
+to the **Talos `dev-core` KB-investigation agent** and writing the returned Markdown report
+back onto the task's `markdown_content`. It runs automatically on every ClickUp
+`taskCreated` webhook and on demand via the `Clickup/Fluffer/Process` action. It is
+**async by design** — the ~3-4 minute Talos call runs as its own worker-tier job and never
+blocks the webhook response.
+
+This is TOGA-internal team tooling (ClickUp + Talos), not client-specific.
+
+## Key files / entry points
+
+- `Worker/Clickup/Fluffer.php` — `abstract class _Worker_Clickup_Fluffer`; action method
+  `public static function Process(string $taskId, bool $force = false): string`. Invoked as
+  action path `Clickup/Fluffer/Process`.
+- `Worker/Clickup.php` — the `taskCreated` case (~line 787) enqueues the fluffer.
+- `Config/*.ini` `[talos]` section — the **new** `agent_endpoint` + `agent_api_key` keys
+  (see Configuration; `beta.ini`'s `[talos]` section was newly added this session).
+
+## How it works
+
+### Enqueue (async)
+`taskCreated` enqueues via
+`_Worker::runTask('Clickup/Fluffer/Process', ['taskId' => $payload->task_id])`. In
+production/beta, `_Worker::runTask` (`_underscore/Worker.php`) does **no MySQL** — it just
+sends the job to SQS and returns immediately, so the fluffer runs later as its own
+worker-tier job and the long Talos call never blocks the webhook response. Only local debug
+mode (`_Environment::isDebugMode()`) runs `runTask` synchronously via a direct HTTP POST to
+the worker.
+
+### The Talos agent call
+Uses `_ApiRequest` (not the ClickUp component) for the Talos call:
+`POST https://api.togaiq.com/api/ai/agent`, body:
+
+```json
+{
+  "assistant_slug": "dev-core",
+  "stream": false,
+  "format": "json",
+  "tool_categories": ["knowledge_base"],
+  "messages": [{"role": "user", "content": "<prompt: task name + existing description>"}]
+}
+```
+
+`_ApiRequest` settings: `setTimeout(280)`, `setConnectTimeout(20)`, `setLogging(false)`,
+`throwExceptionsOnFailure = false`; header **`X-API-Key`** (NOT `Authorization: Bearer`);
+`addHeader('Expect','')` to avoid 100-continue flakiness. The agent returns a Markdown
+`## Talos KB Investigation` report.
+
+- **`/api/ai/agent` is a DIFFERENT endpoint from the existing `/api/ai/generate`** used by
+  the Transcripts/Sprint features, and it uses a **different key** scoped to the `dev-core`
+  assistant slug. Both live in **new** `[talos]` INI keys `agent_endpoint` + `agent_api_key`,
+  separate from the existing `api_key`/`endpoint`. Read via
+  `_Config::talos('agent_endpoint')` / `_Config::talos('agent_api_key')` — never hardcode.
+- The agent endpoint requires the `feature/api-key-agent-bridge` branch deployed to prod
+  (verified live this session — prod returned HTTP 200).
+
+### Writing back to the task
+Uses `_Component_Api_Clickup::send('GET'|'PUT', '/task/'.$taskId, $payload)` for ClickUp
+reads/writes (the shared component owns the ClickUp token). The report is written to the
+task's `markdown_content`, which ClickUp renders as rich text server-side.
+
+### Idempotency & layout
+A styled header line
+`> **_🤖 Generated by Talos KB Investigation — do not edit above this line manually._**`
+(marker substring **"Generated by Talos"**) leads the generated block; the end sentinel
+**"— end of Talos KB Investigation —"** closes it. Layout order:
+
+1. header line
+2. Talos report
+3. end sentinel
+4. preserved human-authored text (everything AFTER the end sentinel)
+
+`stripTalosBlock()` keeps the portion after the end sentinel, so human edits below the
+sentinel survive regeneration. The auto path **skips** (returns `"skipped: already fluffed"`)
+if the marker substring is already present; `force=true` regenerates.
+
+### Rate limiting
+Reuses the shared constant `_Worker_Clickup_Project::RATE_LIMIT_DELAY_US` (120000 µs = 120ms
+→ 500 ClickUp calls/min) via `usleep()` after **each** ClickUp `send()` call — the same
+convention `Project.php` and `Subtask.php` use, so all Clickup workers cooperate on one
+ClickUp rate budget.
+
+## Configuration
+
+`worker2/Config/{production,beta,dev-rohan-mac}.ini` `[talos]` section adds:
+
+- `agent_endpoint` — the `/api/ai/agent` URL.
+- `agent_api_key` — the `dev-core`-scoped key.
+
+Both are separate from the existing `[talos]` `api_key`/`endpoint` (used by
+Transcripts/Sprint). Per existing repo convention the secret lives in the committed INI;
+read it via `_Config::talos(...)`, never hardcode. Documented here by key name/account only,
+never by value.
+
+## Gotchas / known issues
+
+- **Watchdog race.** The fluffer is an **ACTION** job; its watchdog is the Lambda env
+  `MAX_EXECUTION_TIME_WORKER_ACTION` (default 300s). The Talos timeout is set to **280** (just
+  under 300) so the job doesn't lose the race against its own watchdog out of the box.
+  Recommend raising `MAX_EXECUTION_TIME_WORKER_ACTION` to ~420s so slow investigations
+  complete.
+- **`_Component_Api_Clickup::send()` fails in a bare CLI harness with a misleading error.**
+  `send()` leaves `_ApiRequest` logging **ON** by default, so `execute()` tries to write an
+  api-log row to the Client Logs DB (alias resolves to database name `ClientLogs`) **before**
+  the curl call. In a bare CLI harness (or the legacy `action` dispatch path) where the logs
+  DB isn't registered, this throws `Unknown database 'ClientLogs'` and surfaces as an
+  empty-code `API Error … (HTTP ): no error detail` — even though the ClickUp call would have
+  succeeded. The production `workerJobId` dispatch path (`Controller/Index.php`) registers
+  `DB_LOGS` + `DB_CLIENT_LOGS` before running the action, so `send()`'s logging works there.
+  **Workaround for manual/CLI testing:** call the ClickUp API via `_ApiRequest` with
+  `setLogging(false)`, or register the logs DBs first. This is a test-harness gotcha, not a
+  code bug. (Same DB-registration class of issue as the worker-action gotchas in
+  [Creating Worker Actions](./creating-worker-actions.md).)
+- **Distinct Talos endpoint/key.** Do not reuse the Transcripts/Sprint `[talos]` `api_key` /
+  `endpoint` for the agent — `/api/ai/agent` needs the `dev-core`-scoped `agent_api_key`, and
+  the header is `X-API-Key`, not `Authorization: Bearer`.
+
+## Change history
+
+- 2026-07-20 — Built the ClickUp task description fluffer: new `_Worker_Clickup_Fluffer`
+  (action `Clickup/Fluffer/Process`, `taskCreated` webhook auto-trigger, `force` regenerate)
+  calling the Talos `dev-core` KB-investigation agent at `/api/ai/agent` via `_ApiRequest`
+  (`X-API-Key`, `Expect:` cleared, 280s timeout). Report written to ClickUp
+  `markdown_content` with a "Generated by Talos" marker + end sentinel for idempotency
+  (human text below the sentinel is preserved). New `[talos]` `agent_endpoint`/`agent_api_key`
+  keys (beta.ini `[talos]` section newly added). Requires `feature/api-key-agent-bridge` in
+  prod (verified HTTP 200). Documented the `_Component_Api_Clickup::send()` CLI logging-DB
+  gotcha (`Unknown database 'ClientLogs'`). (rgirish)
+</content>

package/knowledge/2.0/apps/worker2/features/vapi-webhook-handler.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-16
+updated: 2026-07-20
 owners: [snaredla, tcox]
 files:
   - worker2/Worker/Vapi.php
@@ -14,6 +14,8 @@ files:
 related:
   - ../../ai-bdr/features/call-orchestration.md
   - ../../ai-bdr/features/vapi-integration.md
+  - ../../ai-bdr/workflows/safe-call-loop-testing.md
+  - ../../api2/features/nested-relationship-writes.md
 ---
 
 ## Summary
@@ -152,6 +154,34 @@ truth for **"why isn't my contact being called."** Confirmed against source
 `initiateCallForContact(…, CALL_TYPE__IMMEDIATE)`. It errors **"not assigned to any active
 campaign"** if no ACTIVE/PENDING campaign-contact link exists.
 
+### Finer detail (source-verified 2026-07-20)
+
+Where each gate actually lives in `Worker/Ai/Bdr/Vapi.php`, and where the eligibility summary
+above is easy to over-read:
+
+- **The campaign gate is split across two methods.** `getActiveCampaignsForDialing` (L177–193)
+  filters **only** `Campaigns.isActive = 1` + `INNER JOIN CampaignAssistants` — there is **no
+  date check there**. The date-range gate lives in `validateCampaignReady` (L759–789), which
+  throws **"Campaign has ended / not started"** and separately requires the `campaignAssistantId`
+  to resolve to a **NON-EMPTY `assistantIdentifier`**. So an active campaign with a valid assistant
+  can still be rejected every run purely because `dateEnd`/`dateStart` is out of range.
+- **`Campaigns_Contacts.status IN ('PENDING','ACTIVE')` is required ONLY when
+  `dtNextContactRequested IS NULL`** (L237). On a requested (web-funnel call-now/scheduled) contact
+  the status is not checked. **`PENDING` is a NORMAL dialable state** — the webhook resets links to
+  `PENDING` for retries, so "stuck on PENDING" is **not** a blocker signal.
+- **The prior-DNC / terminal-outcome exclusion is BYPASSED when `dtNextContactRequested` is set.**
+  The exclusion (L314–331: `c_dncRequested`, `DO_NOT_CALL`, `MEETING_BOOKED` / `DNC_REQUESTED`
+  outcomes) applies only on the non-requested path; a customer who actively re-engages
+  (`dtNextContactRequested`) is dialed regardless of a prior terminal outcome.
+- **The normal (non-requested) path requires a `CampaignCallWindows` row to EXIST for the current
+  day/time.** A campaign with **no** call-window rows can therefore **only ever dial contacts with a
+  pending `dtNextContactRequested`** — this is the **safest launch posture for a web-funnel-only
+  campaign** (see the safe call-loop testing workflow in
+  `../../ai-bdr/workflows/safe-call-loop-testing.md`).
+- **Per-run cap + in-progress exclusion.** Results are `LIMIT MAX_CALLS_PER_MINUTE` per run, and the
+  in-progress check excludes any contact with an **open attempt** (`dtStarted` set, `dtEnded NULL`)
+  for that campaign — see the dryRun gotcha below for how a stray open attempt wedges a contact.
+
 ### Gotcha — a phone-less contact is silently never dialed (BDR web funnel)
 
 Criterion 4's `INNER JOIN` on `primaryContactPhoneNumberId` is why a contact whose phone was
@@ -160,10 +190,33 @@ added **after** creation can be invisible to the dialer: **api2 creates the
 (it only links the primary on CREATE). The BDR web funnel hits this for any phone-less HubSpot
 contact — the visitor's typed phone arrives via a later `PUT /contacts/{uuid}`, so the row
 exists but the primary pointer stays null and the eligibility join excludes it. Re-submitting
-does not fix it (verified in production). See
-`../../ai-bdr/features/web-funnel-app.md` for the funnel side. Fix candidates: api2 sets the
-primary on phone-row create-during-update, or a caller-side `PUT` linking the existing
-phone-row uuid as primary.
+does not fix it (verified in production). The **exact api2 root cause** is now documented — the
+UPDATE path injects a reverse back-reference into the nested child object, defeating the
+single-key-uuid forced-MATCH fast-path (see
+[api2 nested-relationship-writes.md](../../api2/features/nested-relationship-writes.md)). The
+platform fix is deferred; a **funnel-side self-heal has SHIPPED** (`bdr/src/server/toga.ts`):
+after any contact write that carried a phone, if the echoed `primaryContactPhoneNumber` is null or
+its last-10 digits don't match what was sent, BDR finds/creates the `ContactPhoneNumber` row uuid
+and re-links it with an identifier-only `PUT {primaryContactPhoneNumber:{uuid}}`. So on the funnel
+side this is resolved once the fix deploys — see `../../ai-bdr/features/web-funnel-app.md`.
+
+### Gotcha — `dryRun` is NOT write-free; it wedges contacts (never dry-run in prod)
+
+`createContactAttempt` (which sets `dtStarted = NOW()`, `dtEnded NULL`) executes **BEFORE** the
+`dryRun` early-return (L438–466 / L685–708). So a "dry run" writes a **real `ContactAttempts` row
+for every eligible contact** — it counts toward `maxAttemptsPerContact` **and** wedges the contact
+as "in progress" (the open-attempt check above then excludes it from **all** future dialing) until
+someone sets `dtEnded`. **Never dry-run against production.** Fix candidate: move
+`createContactAttempt` below the `dryRun` return (build the payload with a placeholder uuid).
+Unwedge SQL: `UPDATE ContactAttempts SET dtEnded=NOW() WHERE contactId=? AND dtEnded IS NULL`.
+
+### Gotcha — a corrupt `assistantIdentifier` passes validation but 400s at Vapi
+
+`validateCampaignReady` only checks that `assistantIdentifier` is **non-empty**, not that it is a
+well-formed Vapi assistant UUID. A corrupt identifier (e.g. a valid uuid with an extra trailing
+character — a 37-char value) **passes** the readiness gate and the campaign is dialed, then the
+Vapi `POST /call/phone` **400s** at call time. Validate the assistant identifier's shape before
+assigning an assistant to any campaign.
 
 ## Data model
 
@@ -192,6 +245,18 @@ status. See the `ai-bdr` skill / `_Model_True_ContactAttempt` for the full field
 - [VAPI Integration — assistants, tools, structured output](../../ai-bdr/features/vapi-integration.md)
 
 ## Change history
+- 2026-07-20 — Source-verified corrections/extensions to the dialer eligibility rules: the campaign
+  gate is split (`getActiveCampaignsForDialing` L177–193 = isActive+assistant, NO date; date range +
+  non-empty `assistantIdentifier` in `validateCampaignReady` L759–789); `Campaigns_Contacts.status
+  IN (PENDING,ACTIVE)` required ONLY when `dtNextContactRequested IS NULL` (PENDING is normal/dialable);
+  prior-DNC/terminal-outcome exclusion is bypassed on the requested path; a campaign with NO
+  `CampaignCallWindows` rows can only dial requested contacts (safest web-funnel launch posture);
+  per-run `LIMIT MAX_CALLS_PER_MINUTE` + open-attempt exclusion. Added gotchas: (1) `dryRun` is NOT
+  write-free — `createContactAttempt` runs before the dryRun return, writing a real ContactAttempts
+  row that counts toward the attempt cap AND wedges the contact as in-progress (never dry-run in
+  prod; unwedge SQL provided); (2) a corrupt `assistantIdentifier` passes the non-empty check but
+  400s at Vapi. Updated the phone-less-contact gotcha: exact api2 root cause now documented and a
+  funnel-side self-heal (`bdr/src/server/toga.ts`) has shipped. (tcox)
 - 2026-07-16 — Documented the outbound dialer eligibility rules from source
   `getEligibleContactsForVapi()` (the 6 ALL-of criteria, the `dtNextContactRequested <= NOW()`
   window/cadence bypass = the website call-now/scheduled path, cron entry chain, and the single

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 35 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 30 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 31 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 12 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/package.json

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