# Channel Insights · Automatic recording refresh

## What it does

After the conversation automation coordinator finishes a linked Zoom, phone-call or
showroom recording, it refreshes that lead's affected channel reading, then Overall,
then Summary. It does not run Profile enrichment, transcribe audio again, or refresh
unaffected channels. The manual Analyse and Analyse All controls remain available.

## How it works

- `RefreshLeadConversationInsights` accepts a lead id and an integer
  `ConversationSourceType`. Each queue job performs one stage. Only a successful stage
  dispatches the next; an AI failure never advances using an old reading.
- Dispatch is delayed 30 seconds and unique until processing by lead, source type and
  stage. A burst coalesces; a source change during a running job can enqueue another
  pass. Automatic stages for the same lead cannot overlap.
- The five `Src\Lead\Services\Lead*Insights` services are shared with the manual
  controllers. They retain the same source queries, full transcript rendering,
  fingerprint, prompt/model selection, quote verification, speaker attribution,
  repository writes and action-proposal handling. There is no synthetic HTTP request
  and no controller invocation from a job.
- Each service serializes writers of one lead/channel with a cache lock and rechecks
  the source fingerprint after the provider finishes, before publishing. A changed
  fingerprint rejects the reply for retry. This is an optimistic check: source
  writers do not all share that lock, so a change at the final save boundary is
  reconciled by its subsequent queued refresh.
- Retries reuse already-saved fingerprints. A failed Overall or Summary stage retries
  itself; it does not pay again for an unchanged channel reading. Provider calls
  that fail before saving can still incur provider charges on retry.
- When removal or unlinking leaves no readable source, automatic refresh retires the
  old reading, supersedes that channel's pending action proposals, detaches historical
  proposal references and refreshes readiness. Approved tasks and decided proposal
  history are preserved. The next stage still runs, so Overall and Summary no longer
  retain a removed source. Manual generation keeps its existing 404/422 response.
- Summary reads only human Discussion entries (`conversation_source IS NULL` when
  the provenance column is installed). Generated notes are already represented by the
  source channel and cannot become a second source of purported staff facts.
- Controllers keep lead visibility and channel permission gates. Overall/Summary
  reads and downloads also check channels recorded on their stored reading, even if
  those underlying sources have since disappeared. Background generation does not
  grant anyone access to the resulting words.
- Avatar facts count as input from their actual recording channel, including when
  no reading exists for that channel yet. Lead Insights only use avatars whose
  original call or meeting still belongs to the lead. Deleted/ignored calls and
  deleted/webinar meetings are excluded; relinking never rewrites or re-mines a
  cached avatar. An old avatar is omitted until a valid source exists again.

### Worker envelope and failures

These jobs extend `AiJob` for its rate limiter, breaker and overlap handling, but use
their own `redis-insights` connection and `insights` queue. Horizon's
`supervisor-insights` has one process in both production and local configurations:
job timeout **3600 s**, worker **3630 s**, queue `retry_after` **3660 s**.

The service checks `ChannelInsightsAnalyzer::timeBudget()` before spending tokens.
A reading estimated above **3540 s** fails with an explicit budget message instead
of extending PHP time beyond the worker envelope. Operational failures appear in
the queue's normal failed-job/Horizon tooling; transient failures retry with the
AI backoff for up to six hours. No-source cleanup is a success, not a provider failure.

A plain `queue:work` deployment needs an explicitly configured isolated worker for
`redis-insights --queue=insights --timeout=3630`; adding the connection to source code
does not install a system service. See the [Horizon runbook](/docs/modules_handbook/production-setup/horizon.md).

## Reference usage

The recording automation coordinator dispatches after its note/task writes commit:

```php
use App\Jobs\Lead\RefreshLeadConversationInsights;
use Src\Conversation\ConversationSourceType;

RefreshLeadConversationInsights::dispatch($lead->id, ConversationSourceType::PHONE_CALL);
```

For the manual HTTP boundary, follow `LeadPhoneCallInsightsController::generate()`:
authorize the user and lead, call `LeadPhoneCallInsights::generate()`, then map the
result or `InsightGenerationFailed` to the existing JSON contract.

## Related files

- `app/Jobs/Lead/RefreshLeadConversationInsights.php`
- `src/Lead/Services/LeadInsightGenerator.php` and `Lead{PhoneCall,ZoomMeeting,Showroom,Overall,Summary}Insights.php`
- `src/Lead/Support/ReadsLeadInsights.php`
- `src/Lead/Exceptions/InsightGenerationFailed.php`, `InsightSourcesUnavailable.php`
- `src/Lead/Repositories/LeadChannelInsightRepository.php`
- `config/queue.php`, `config/horizon.php`
- `tests/Unit/Lead/RefreshLeadConversationInsightsTest.php` (SQLite memory only, mocked AI)
