[Asaf-prog]

This PR fixes lifetime token-budget accounting for unfinished runs and adds the opt-in WhatsApp channel through pilot packaging. Its effective diff against main includes the implementations from #149 and #150: 120 files, 13,676 additions and 178 deletions, verified at head 05b31af49d556f55af134e3d5907252a26e90f62.

Scope and rationale

This is a combined manager integration PR. The WhatsApp channel uses the generic conversation-turn preparation and existing conversation/run lifecycle, while the usage ledger preserves consumed work independently of whether an execution produces an assistant message. Approval of this PR covers both accounting and the complete channel stack below.

• Run and conversation accounting ([Bug][P2] Cancelled runs consume tokens without counting toward the conversation budget #140): retain cumulative usage for failed/cancelled runs, pending approvals, resumed runs and inactive conversation branches. Reconcile missed retention writes from authoritative run records and retain charges after run-record expiry. Atomic (run_id, leg_id) claims prevent duplicate charges after ambiguous commits while charging distinct overlapping legs. Manager pending_approval and final SSE frames expose token totals.
• Generic channel prerequisites (WA-01–WA-02): idempotent turn preparation, SQL channel storage, durable sender/conversation binding and a client-owned identity resolver boundary.
• WhatsApp intake and execution (WA-03–WA-04): signed, bounded webhook normalization; durable intake before acknowledgement; an opt-in worker with exclusive ownership, fresh identity checks, conservative restart recovery, bounded concurrency, health projection and cancellation-safe shutdown.
• Delivery and controls (WA-05): immutable ordered text parts, recipient/window/suppression checks, callback projection and deterministic stop/start/reset/help controls. Controls remain active whenever the worker runs, including sender-disabled startup without outbound credentials; missing durable control storage rejects startup.
• Pilot operation (WA-06): sanitized status/rejection logs, a loopback-bound example deployment, runbook and fake-provider round-trip/restart rehearsal.

Intake, worker and outbound sender are separately disabled by default. Provider-specific code stays in agent_manager; the engine receives its existing typed requests and context.

Acceptance criteria

• Consumed run usage survives failure, cancellation, approval suspension/resume, branch edits and run-record expiry without charging a leg twice.
• Ambiguous-commit retries and overlapping legs are covered for built-in repositories; external run adapters cannot silently inherit unsafe unkeyed accounting.
• Both manager stream endpoints expose cumulative usage in pending-approval events.
• Authenticated webhook intake is durable and idempotent, with bounded validation and sanitized rejections.
• Worker ownership, fresh identity checks, restart recovery and shutdown behavior have deterministic regression coverage.
• Delivery preserves ordering, authorization and suppression; uncertain sends are held for reconciliation.
• Worker-on/sender-off stop suppresses later engine execution; start affects only new input, reset starts a fresh conversation, and help never invents a contact. Restart into sending mode does not deliver old suppressed replies.
• Status logs, runbook and pilot configuration match implemented behavior; fake-provider rehearsal covers intake, answer, delivery callback and restart without resending.
• Full quality gate, offline example validation and GitHub CI pass.

Contracts and migration

• Apply Alembic revisions 0006–0010: lifetime usage/backfill and leg keys, turn-preparation receipts, channel storage, webhook receipts and delivery/control storage.
• External RunRepository adapters must implement the required abstract add_leg_token_usage operation with an atomic keyed claim plus usage update. Delegation to unkeyed add_token_usage does not satisfy the contract.
• The manager SSE token fields are additive. The channel adds its opt-in webhook and configuration; agent YAML and the engine request ports retain their existing contracts.
• Design and compatibility details: ADR 0002, ADRs 0006–0010, implementation plan, runbook, and tasks 0013–0021 plus the two PR-148 follow-up tasks.

Validation

Fresh verification on 2026-10-23, at head 05b31af:

• make check: 1,456 tests passed, 27 dependency warnings; formatting (361 files), lint, mypy (357 files) and generated-stub checks passed.
• make validate: starter and enterprise examples passed.
• agentctl validate examples/whatsapp-pilot/agents.yml: passed.
• git diff --check: passed; the verified checkout remained clean and at the same commit.
• GitHub CI run 39812408471: both check and ui passed, including widget type checks, bundle freshness, unit tests and Playwright end-to-end tests.
• All five inline review threads are resolved, including the atomic accounting contract and sender-disabled opt-out finding. The accounting and paused-control follow-ups record regression evidence; the WhatsApp review documents cover the channel implementation and lifecycle corrections.

Tests use fake engine/model/provider boundaries and temporary local SQLite. No live model, Meta delivery, production credentials or live PostgreSQL server was exercised by this verification.

Remaining pilot work and operating limits

Organization Google/JWT account linking, automatic channel-data retention and the authorized real-number smoke test remain pending. The pilot allowlist is an example identity plugin. Deployment requires a trusted identity implementation and current account/protocol verification. Failed, blocked and unknown delivery work needs operator reconciliation; durable conversations do not make process-local approvals/tool replay durable. This PR does not activate a real account or deploy a service.

Fixes #140

[AmitAvital1]

I found two blocking correctness issues in the token accounting path. Details and reproductions are attached to the exact lines.

[AmitAvital1]

The two original findings are fixed and their threads are resolved. The second full review found one new blocking accounting race; details and a reproduction are attached inline.

[AmitAvital1]

The overlapping-leg race is fixed and I resolved that thread. One blocking contract issue remains: RunRepository.add_leg_token_usage documents at-most-once behavior but its default implementation is non-idempotent, so existing external adapters can silently double-charge after an ambiguous commit. Please require adapters to implement the atomic keyed operation instead of falling back to add_token_usage.

[AmitAvital1]

The atomic run-leg contract is fixed, and I resolved that thread. The PR now also contains the full #149/#150 WhatsApp stack: 118 files and 13,456 added lines, although this PR and its follow-up task are scoped to token accounting. That imported code still has a confirmed opt-out bypass when the worker runs with sending disabled; I left the exact inline finding. Please remove the unrelated stack from this PR, or fix and explicitly review it here before merging.

[AmitAvital1]

The opt-out bug is fixed and I resolved its thread. One general blocker remains: the title and description still present this as the #140 token-accounting fix with 1,126 tests, while the effective PR now includes the full WhatsApp stack (120 files, 13,676 additions) and 1,456 tests. Please either remove the unrelated stack or update the PR scope, rationale, acceptance criteria, and validation so reviewers can see exactly what this merge is approving.

[AmitAvital1]

Reviewed the final combined scope at 05b31af. All five inline findings are fixed and resolved; the updated title and description now accurately define the accounting and WhatsApp integration being merged, including contracts, acceptance criteria, migrations, limits, and validation. Focused regressions, the full local suite except the confirmed environment-only Click baseline failure, example validation, diff checks, and GitHub check/ui jobs all pass. Approved.