LinkedIn Insights: Always Fails with “Reached maximum turns per run”

Status: ✅ Fixed (2026-05-05)
Severity: Was High — LinkedIn channel insights permanently broken; retries exhausted in ~75s
File: packages/agents/src/workers/insights/insight-worker-base.ts

Symptom

After a LinkedIn channel is connected, the insights worker is queued automatically. Every attempt fails within 6–12 seconds:

ERROR [insight-worker] Insight generation failed
  error: "Reached maximum turns per run"
  at runInsightWorker (insight-worker-base.ts:268)
  at Worker.processJob (linkedin-insights.worker.ts:155)

BullMQ retried the job 5 consecutive times within 75 seconds. Each attempt got faster (12s → 10s → 8s → 6s), indicating a consistent failure path, not a timeout. No insight record was ever completed.

Root Cause (Confirmed)

insight-worker-base.ts runs with allowedTools: [] (correct — no tools should be used). However, maxTurnsPerRun: 1 caused immediate failure because:

1. Claude’s first response includes an attempt to use a tool (likely triggered by the system prompt’s mention of “PRIOR ACCEPTED INSIGHTS: human-verified observations from previous LinkedIn analyses” — Claude tries to find these files in the CWD even though none exist).
2. The Claude Code CLI blocks the tool call (empty allowedTools list) and needs to relay the “tool not permitted” error back to Claude.
3. Claude needs to respond to that error message — which would be turn 2.
4. With maxTurnsPerRun: 1, turn 2 is blocked → error_max_turns is immediately emitted.

The decreasing failure time across retries reflects the CWD directory being created on the first run (no mkdir overhead) + process warm-up, not state accumulation.

This does NOT affect the blog writer (also maxTurnsPerRun: 1, allowedTools: []) because the blog writer’s prompt doesn’t trigger any tool-seeking behavior.

Fix Applied

Changed maxTurnsPerRun: 1 → maxTurnsPerRun: 3 in insight-worker-base.ts:

// insight-worker-base.ts line 254
maxTurnsPerRun:  3,   // 3 turns: allows recovery if a blocked-tool error needs a follow-up response

3 turns is safe because allowedTools: [] still prevents any real tool use — Claude can only have a brief internal back-and-forth (attempt tool → tool blocked error → acknowledge + generate text), which resolves in at most 3 rounds.

Requires agents server restart to take effect.

Related: Deliverable Planner Same Issue

The deliverable planner (strategy.worker.ts) had a variant of this bug — it was missing allowedTools: [] entirely, giving Claude full tool access. With no tool restrictions + maxTurnsPerRun: 1, Claude used tools during generation (browsing CWD, writing output files), hit the limit, and failed. Fixed separately by adding allowedTools: [] to the deliverable planner config. See docs/issues/deliverable-planner-max-turns.md.