feat(review): non-environment config source for the reviewer relay extension allowlist

[salgozino]

Before submitting

• I searched open and closed issues and did not find a request for this feature.
• I reviewed this request and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem or opportunity

GENTLE_PI_REVIEW_RELAY_EXTENSIONS (shipped for #1158) is the supported way to re-admit provider/auth extensions (e.g. pi-claude-bridge) into the reviewer child via explicit -e flags. But its only transport is an environment variable, and environment variables are process-global by nature:

• Exported from shell startup (~/.zshenv), it leaks into every other tool's environment even though it only has meaning for gentle-pi's reviewer relay. Env vars are process-global by nature, so there is no way to scope the allowlist to Pi without user-built machinery.
• Scoped alternatives are all user-built: a shell alias (misses non-interactive launchers) or a custom global Pi extension that mutates process.env at load. The extension approach works — we validated the full lifecycle end-to-end with it — but every bridge user must write it themselves, and Pi's /reload does not pick up newly created extensions, so it fails silently until a full Pi restart.

Anyone routing review lenses to claude-bridge/* (or any extension-provided provider) needs this today, and there is no in-product way to configure it.

Proposed outcome

resolveReviewHostRelayExtensionPaths() (lib/review-host-relay.ts) additionally reads a gentle-pi-owned config source — for example ${gentlePiConfigHome}/review-relay.json with {"reviewerExtensionPaths": ["..."]} — with the environment variable, when set and non-empty, replacing the file entirely as a per-invocation override (same semantics as GENTLE_PI_AUTONOMOUS_MODE in runtime-guardrails). Validation stays exactly as today: absolute, existing paths, typed REVIEWER_CONFIG_INVALID refusal before anything launches.

A config file is user-owned and Pi-scoped by construction, so the allowlist can no longer leak into other runtimes' environments.

Happy to send the PR if this direction is approved.

Alternatives considered

• ~/.zshenv export: works, but leaks a Pi-only setting into every other process's environment.
• Shell alias/wrapper around pi: covers interactive shells only; launchers and non-interactive invocations miss it.
• Custom global extension setting process.env at extension load (~30 lines): our current working workaround, but per-user boilerplate, and invisible to /reload when newly created.

Additional context

Full native RDD lifecycle validated end-to-end through pi_host_relay with the bridge re-admitted via -e from the env allowlist: lens executed on a claude-bridge/* model, result admitted, review approved, authority burned.

Related: #1158 (origin of the env allowlist), #757 (silent model substitution when the provider extension is missing from the reviewer child — a first-class config source also narrows the window in which users run without any allowlist configured).

[Alan-TheGentleman]

Hey @salgozino! Approved, go ahead with the PR. The direction is right: a global file under gentlePiConfigHome matches how runtime-guardrails.json, background-subagents.json and models.json already work, and the resolver is small enough that this stays a contained change.

One correction to the motivation first. I checked gentle-ai and it never reads GENTLE_PI_REVIEW_RELAY_EXTENSIONS. The only Pi env gate is GENTLE_PI_REVIEW_RELAY_CONTRACT, and it is only evaluated under case model.AgentPi; the runtime identity comes exclusively from the --agent flag. So exporting the allowlist globally cannot produce a #2242-class refusal in OpenCode. If you saw that refusal on the same machine, it had another cause. The rest of the argument stands on its own (env vars are process-global, there is no in-product config, and the extension workaround is invisible to /reload), so please drop the OpenCode claim from the PR description.

Conditions for the PR

1. Global file only. No <cwd>/.pi/gentle-ai/review-relay.json variant. A cloned repository controlling extension paths would be arbitrary code execution inside the reviewer child.
2. Separate file, not models.json. Go reads models.json with strict validation and fails on unknown fields, so adding extensions to a lens entry would break review-refuter and review-validator on the Go side.
3. Pick one precedence semantics. The issue says both "merged" and "env keeps precedence as override". Go with override: when the env var is set and non-empty, it replaces the file entirely. That matches the GENTLE_PI_AUTONOMOUS_MODE pattern in runtime-guardrails and keeps the per-invocation story simple.
4. Tests for the resolver. resolveReviewHostRelayExtensionPaths has no direct coverage in tests/review-host-relay.test.ts today. Cover file-only, env-only, both (override), missing file, malformed JSON (typed REVIEWER_CONFIG_INVALID, not silent fallback), and non-array / non-string entries.
5. Docs. Update the extension allowlist bullet in docs/review-integration.md with the file path, schema and precedence.

Keep the validation exactly where it is (absolute, existing, typed refusal before launch); the new source only feeds paths into it.

Note that #757 stays open. The frozen --no-extensions is still the root cause; this is a better mitigation, not the fix.