Fix bird live-sync profile avatars

[RajvardhanPatil07]

Fixes #71.

Summary

• request full bird tweet payloads for tweet-backed live reads, with a fallback for older bird versions
• propagate matching GraphQL avatar URLs into the existing profile image field
• preserve an avatar discovered on a later tweet from the same author

Root cause

Birdclaw normalized only the compact bird payload, which omitted the GraphQL avatar data before profile upsert.

Validation

• pnpm test -- src/lib/bird.test.ts src/lib/timeline-live.test.ts src/lib/timeline-collections-live.test.ts src/lib/mentions-live.test.ts
• pnpm run check

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 24, 2026, 5:30 AM ET / 09:30 UTC.

Summary
This PR changes bird tweet-backed reads to prefer --json-full with fallback, maps matching GraphQL avatar URLs into profile_image_url, and adds regression tests for live avatar persistence.

Reproducibility: yes. The linked issue provides live sync and SQL checks, and current main source shows bird tweet normalization omits profile_image_url before the profile writer that persists avatars.

Review metrics: 2 noteworthy metrics.

• Changed files: 1 implementation file, 4 test files. The patch is focused, but it changes a live external command integration rather than only pure normalization logic.
• Bird command surface: 7 tweet-backed command paths switch to --json-full first. The mocked fallback tests do not by themselves prove the upgraded external command output shape across those live paths.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #71
Summary: This PR is the open candidate fix for the canonical bird live-sync avatar persistence bug report.

Members:

• canonical: bird live sync does not persist profile avatar URLs from GraphQL user payloads #71 - The PR body links it with closing syntax, and the issue describes the same bird --json-full GraphQL avatar data being dropped before profiles.avatar_url persistence.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted terminal output, logs, screenshot, or recording from a real bird-backed sync showing profiles.avatar_url populated after the fix.
• Include the exact sync command and SQL or UI check used, redacting private details such as API keys, cookies, phone numbers, local paths, IP addresses, and non-public endpoints.
• After updating the PR body with proof, let ClawSweeper re-review automatically; if it does not, ask a maintainer to comment @clawsweeper re-review.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body lists tests/checks but no after-fix terminal output, logs, screenshot, recording, or live bird sync proof; the contributor should add redacted proof and update the PR body for re-review.

Risk before merge

• [P1] No after-fix terminal output, logs, screenshot, recording, or live bird sync proof was provided, so reviewer evidence has not observed profiles.avatar_url being populated in a real setup.
• [P2] The PR changes tweet-backed bird commands from --json to --json-full first for mentions, timeline, likes/bookmarks, search, read, and thread; mocked tests cover unsupported-option fallback but not a live supported --json-full output contract.

Maintainer options:

1. Require live bird proof (recommended)
   Before merging, ask for redacted terminal output, logs, screenshot, or recording showing a real bird-backed sync populates avatar URLs through the new --json-full path.
2. Accept the command-surface risk
   Maintainers may merge based on source review and tests if they explicitly accept that live bird --json-full behavior is not shown in the PR evidence.
3. Pause until validation is available
   If the contributor cannot provide live proof, keep this PR open or paused while the linked issue remains the canonical report for a maintainer-run validation pass.

Next step before merge

• [P1] Contributor-supplied real behavior proof cannot be generated by an automated repair worker, and maintainers need to review the external bird --json-full compatibility surface before merge.

Security
Cleared: The diff does not add dependencies, workflows, secrets handling, downloaded code, or broader permissions; it only changes bird command flags and avatar normalization code/tests.

Review details

Best possible solution:

Land the focused avatar normalization fix after redacted real bird sync proof confirms live --json-full reads persist profiles.avatar_url, while keeping the linked bug report open until the fix merges.

Do we have a high-confidence way to reproduce the issue?

Yes. The linked issue provides live sync and SQL checks, and current main source shows bird tweet normalization omits profile_image_url before the profile writer that persists avatars.

Is this the best way to solve the issue?

Yes, source review indicates the PR takes the narrow maintainable path by feeding GraphQL avatar data into the existing profile_image_url pipeline; the remaining blocker is proof and external command compatibility, not a different design.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against 10f98d3fb36a.

Label changes

Label changes:

• add P2: This is a normal-priority bug fix for silently missing avatar metadata in live bird sync while core syncing remains usable.
• add merge-risk: 🚨 compatibility: Merging changes the default bird CLI flag for existing tweet-backed live-read paths, and CI cannot prove the real external command's upgraded output contract.

Label justifications:

• P2: This is a normal-priority bug fix for silently missing avatar metadata in live bird sync while core syncing remains usable.
• merge-risk: 🚨 compatibility: Merging changes the default bird CLI flag for existing tweet-backed live-read paths, and CI cannot prove the real external command's upgraded output contract.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists tests/checks but no after-fix terminal output, logs, screenshot, recording, or live bird sync proof; the contributor should add redacted proof and update the PR body for re-review.

Evidence reviewed

What I checked:

• Target AGENTS check: No AGENTS.md exists under the target Birdclaw repository root, and no .agents/maintainer-notes files were present for the touched paths. (10f98d3fb36a)
• Current main still omits avatar mapping: normalizeBirdTweets on current main builds included users from id, username, and name only, so the bird payload never supplies profile_image_url to downstream persistence. (src/lib/bird.ts:447, 10f98d3fb36a)
• Existing persistence path expects profile_image_url: The shared profile writer derives profiles.avatar_url from user.profile_image_url and preserves existing avatars with coalesce, matching the PR's intended integration point. (src/lib/x-profile.ts:101, 10f98d3fb36a)
• PR implementation path: The patch adds a --json-full-first helper with unsupported-option fallback, traverses bird/GraphQL raw objects for matching rest_id avatar URLs, and feeds the result into profile_image_url. (src/lib/bird.ts:351, a0738270f076)
• PR scope: The proposed branch changes one implementation file and four focused test files, with 191 additions and 26 deletions. (a0738270f076)
• Proof remains missing: The PR body lists test/check commands, and the current PR comments contain only the prior ClawSweeper review; there is no terminal output, log, screenshot, recording, or live bird sync proof showing avatar persistence after the fix. (a0738270f076)

Likely related people:

• steipete: Current blame for bird tweet normalization, tweet ingest, and profile avatar persistence points to Peter Steinberger's v0.8.5 release snapshot, and all-ref history shows the bird transport plus live timeline/collection features in the same author trail. (role: introduced behavior and recent area contributor; confidence: high; commits: b456320a66aa, e413277f1297, aba65a1181e1; files: src/lib/bird.ts, src/lib/tweet-repository.ts, src/lib/x-profile.ts)
• cavit99: History shows adjacent mention, likes/bookmarks, pagination, and media-preservation work in the same live-sync surfaces, though not the current avatar normalization line itself. (role: adjacent sync contributor; confidence: medium; commits: 3fa6c3201475, f90cb71e258c, 3097c1b64b07; files: src/lib/mentions-live.ts, src/lib/timeline-collections-live.ts, src/lib/bird.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.