Best possible solution:

Land only after maintainers accept the trusted ZALO_API_URL contract and the docs describe the production default, trusted sources, and workspace dotenv block.

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

Not applicable: this is a feature/config-surface PR rather than a reported bug. Source inspection confirms current main has a fixed Zalo API root and the PR adds the alternate-root path with focused tests.

Is this the best way to solve the issue?

Mostly yes: resolving the root inside callZaloApi is the narrow owner-boundary fix because Zalo API helpers funnel through that function. The merge-ready version still needs maintainer acceptance and docs for the trusted env contract.

Full review comments:

• [P3] Document the Zalo API root override — extensions/zalo/src/api.ts:11
  This introduces ZALO_API_URL as a runtime endpoint override, but docs/channels/zalo.md still documents only ZALO_BOT_TOKEN and docs/gateway/security/index.md lists endpoint dotenv blocking without Zalo. Please document trusted process/global sources, the production default, and workspace .env blocking so operators know the contract.
  Confidence: 0.86

Overall correctness: patch is correct
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 381b44a9fc26.

Label justifications:

• P2: This is a bounded Zalo channel feature with limited blast radius but real operator-facing compatibility impact.
• merge-risk: 🚨 compatibility: A pre-existing ZALO_API_URL process/global environment value would redirect Zalo API requests and bot tokens after upgrade.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this maintainer-labeled MEMBER PR; the PR body's targeted test list is supplemental validation.

PR surface:

Source +32, Tests +80. Total +112 across 6 files.

What I checked:

• Repository policy applied: Root AGENTS.md was read fully and treats provider routing, config/default additions, setup/startup checks, and fallback behavior as compatibility-sensitive; extensions/AGENTS.md keeps bundled plugin behavior inside the plugin boundary. (AGENTS.md:31, 381b44a9fc26)
• Current main lacks alternate Zalo API roots: Current main defines a fixed ZALO_API_BASE and constructs every callZaloApi request from that production root, so the requested behavior is not already implemented on main. (extensions/zalo/src/api.ts:10, 381b44a9fc26)
• PR head centralizes the endpoint override: At the PR head, resolveZaloApiUrl reads an explicit option first, otherwise process.env.ZALO_API_URL, validates HTTP(S), strips trailing slashes, and feeds the shared callZaloApi URL construction. (extensions/zalo/src/api.ts:108, 84d84f7f9a37)
• Shared Zalo caller path checked: Polling, send, probe, webhook setup, webhook cleanup, typing, and pairing replies all route through helpers in api.ts, so the endpoint change is not a one-sided path patch. (extensions/zalo/src/monitor.ts:259, 381b44a9fc26)
• Workspace dotenv mitigation exists on PR head: The PR adds ZALO_API_URL to the workspace dotenv blocklist and extends tests to prove workspace .env cannot set it while trusted global .env still can. (src/infra/dotenv.ts:171, 84d84f7f9a37)
• Docs gap remains: The Zalo docs still document ZALO_BOT_TOKEN but not ZALO_API_URL, and the security guide's workspace dotenv endpoint list mentions Matrix, Mattermost, IRC, and Synology Chat but not Zalo. Public docs: docs/channels/zalo.md. (docs/channels/zalo.md:95, 381b44a9fc26)

Likely related people:

• steipete: Commit 5abe3c2 introduced the Zalo plugin/API client, and shortlog/history show the largest share of Zalo API, monitor, and docs changes in this area. (role: introduced behavior and heavy Zalo area contributor; confidence: high; commits: 5abe3c21456e, 58baf22230e0, 453664f09d09; files: extensions/zalo/src/api.ts, extensions/zalo/src/monitor.ts, docs/channels/zalo.md)
• RomneyDa: Beyond authoring this PR, RomneyDa authored the merged Slack alternate API-root PR and the merged Zalo identity-contract base that this PR was restacked on. (role: adjacent endpoint-surface owner; confidence: high; commits: 39e1be080ca0, 381b44a9fc26, 84d84f7f9a37; files: extensions/slack/src/client-options.ts, src/infra/dotenv.ts, extensions/zalo/src/api.ts)
• Devin Robison: Commit 6a79324 introduced the untrusted CWD .env filtering boundary that this PR extends for Zalo endpoint routing. (role: dotenv trust-boundary contributor; confidence: medium; commits: 6a793248024d; files: src/infra/dotenv.ts, src/infra/dotenv.test.ts)
• Vincent Koc: Recent history shows Zalo runtime/API and dotenv-adjacent maintenance by Vincent Koc, including Zalo runtime seam work and shared dotenv edits. (role: recent Zalo and dotenv area contributor; confidence: medium; commits: 76c22217174c, 58409cd5c570, 11590eb6ce38; files: extensions/zalo/src/api.ts, extensions/zalo/src/monitor.ts, src/infra/dotenv.ts)

• 🦀 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.

• 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.