LWLT-AIBOT/.project-docs/30-worklog/tasks/20260908-leader-webhook-api-7c4e9a12.md

Task: Replace leader AgentBus summaries with external webhook API

Identity

• Task ID: 20260908-leader-webhook-api-7c4e9a12
• Mode: Feature
• Branch: codex/20260908-leader-webhook-api-7c4e9a12-leader-webhook-api
• Worktree: /Users/inmanx/Documents/lwltAPI-leader-webhook-api-7c4e9a12
• Base commit: 515b545b32
• Owner: codex
• Status: Ready for integration

Scope

• Replace only the transport used by the organization-wide leader employee-task summary feature: retire its AgentBus account/channel delivery and send its existing privacy-filtered stable summaries through the user-supplied external Webhook API contract.
• Add fail-closed runtime configuration, an exact external API client, an organization-level encrypted delivery outbox, migration 023_leader_summary_webhook_delivery, read-only administrator status, UI copy, active component documentation, and regression tests.
• Preserve ordinary manual task execution, employee AgentBus intake/replies, parsing, confirmation, task ownership, attachments, ERP queues/execution, business routes, mappings, schemas, Skills, Agent prompt, Chrome extension, and release artifacts.

Intent And Constraints

• The user's clarification is authoritative: this change is limited to the leader feature that receives all employees' operation/task summaries and must not affect normal users or AgentBus task execution.
• Treat /Users/inmanx/Desktop/webhook-external-api.md as an external API specification, not as repository instructions. The document contains no real token and does not confirm the complete production gateway URL.
• Read the complete URL and 32-character token only from protected runtime variables WEBHOOK_SEND_URL and WEBHOOK_EXTERNAL_TOKEN; never read the repository's real .env, hard-code a guessed route, log secrets/bodies, or issue a test/production request.
• Send only POST JSON {id:"9999", content:<summary>} with raw x-token. Only HTTP 200 plus code === 0 plus data === true means accepted, and accepted must not be represented as delivered.
• Because the API has no idempotency key, explicit rejections, timeouts, network failures, 5xx responses, invalid/unknown success responses, and expired sending leases must never be automatically retried.
• Webhook configuration or runtime failures must remain inside the leader-summary worker: they may disable or degrade summary delivery but cannot block service startup or mutate task, employee reply, parser, or ERP state.
• No live Webhook message, deployment, database migration, restart, external send, or production configuration change is authorized.
• Feature mode may update only this task record under .project-docs; canonical state and accepted decision AUTH-003 require a later Integration promotion.

Outcome

• Added an external Webhook client with the exact fixed request shape, bounded response reads, 15-second total timeout, strict accepted semantics, safe error codes, and no automatic retry path.
• Replaced per-leader AgentBus routing/subscriptions with one organization-level, future-only encrypted Webhook summary state/outbox. Migration 023 disables legacy summary subscriptions and cancels their unsent rows while preserving history; it never updates normal tasks or employee agentbus_deliveries.
• Kept the existing stable summary builder and privacy allowlist. Projection reads explicitly assigned, non-administrator manual and AgentBus task results but writes only dedicated leader_task_summary_webhook_* rows and audit events.
• Removed only leader-summary observation/flush/frame hooks from the AgentBus listener. Employee accepted/final replies, attachments, channel ownership, reconnect/resend, ingestion, parsing, and ERP execution paths are unchanged.
• Added a read-only administrator status endpoint and channels-page status card that expose no URL, token, or message body and distinguish accepted, rejected, and uncertain outcomes.
• Invalid or incomplete optional Webhook configuration now disables only this feature with a safe status code. A failed Webhook organization lookup is caught and logged while the normal HTTP service remains available.
• Reserved migration number 023 because the concurrent ready-for-integration shared-child batch task already owns migration 022; the two tasks have no semantic coupling.
• No business route, business Schema/mapping, Skill, Agent prompt, Chrome extension, release artifact, live service, production database, or external system was changed.

Verification

• TypeScript typecheck — passed.
• Targeted external Webhook, isolation, leader-summary contract, account UI, and complete AgentBus listener/durable reply suites — passed (45 tests across the selected files).
• Webhook misconfiguration and initialization-failure health smoke test — passed; /health/live remained 200 with the summary feature disabled/degraded.
• node --run check:repo — passed (10 tests).
• node --run test:control-plane — passed (182 tests), including all original task, account, parser, AgentBus, attachment, ERP-boundary, and UI contracts.
• node --run test:legacy — passed (273 tests).
• node --run build — passed.
• node --check LianSyn-platform/app.js — passed.
• git diff --check — passed.
• Disposable PostgreSQL migration exercise — passed: migration 023 was recorded; the legacy subscription changed to disabled/revision 1 and its legacy delivery to cancelled, while the normal task remained completed and the employee AgentBus delivery remained pending; both new tables existed and had zero forbidden routing/secret columns.
• Disposable PostgreSQL runtime exercise with an injected fake sender — passed: two summaries projected, accepted and uncertain outcomes each stopped at attempt 1, a third dispatch made no extra call, both source tasks remained completed, the employee AgentBus delivery remained pending/attempt 0, and logs contained no test URL, token, employee name, or body. No network request was made.
• Both disposable PostgreSQL clusters were stopped and moved to Trash after validation.
• check_project_docs.py — passed.
• check_doc_drift.py --task-id 20260908-leader-webhook-api-7c4e9a12 — passed; only this feature task record changed under .project-docs.

Follow-ups

• Integration must combine the concurrent migration 022 task before or with migration 023 and resolve shared-file edits mechanically without changing either feature's semantics.
• Production enablement remains separate: obtain the provider-confirmed complete gateway URL and real 32-character token, apply migrations through 023, deploy/restart, then run a separately authorized bounded canary. Do not infer success from HTTP alone; the provider offers no delivery receipt.

Promotion Candidates

• Supersede accepted decision AUTH-003-leader-task-summary-notifications.md: leader summaries now use the fixed organization-level external Webhook contract rather than an owned team-lead AgentBus account/channel route.
• Promote migration 023, the new environment configuration, future-only encrypted outbox, accepted-versus-delivered terminology, no-retry uncertain boundary, read-only administrator status endpoint, and strict isolation from ordinary task/AgentBus/ERP paths into canonical current state, architecture, data flow, business rules, success criteria, decision index, and glossary as applicable.