feat(visibility): three-tier agent visibility with tier gate

[bokelley]

Summary

• Replaces agent is_public boolean with visibility: 'private' | 'members_only' | 'public'. Public listing requires Professional+ (API access) tier; Explorer and non-paying users can set private or members_only.
• members_only is the paid-member discovery pool: non-paying orgs can register agents and be found by Professional+ members via MCP list_agents / get_member, without landing in the public directory or brand.json. Solves the Scope3-style use case.
• Stripe webhook auto-demotes public → members_only on any tier change where the new tier lacks API access (including full cancellation), and strips those agents from the community brand.json manifest.
• MCP list_agents, get_agent, list_members, get_member are tier-aware: API-access callers receive members_only agents; non-API callers never do. Tool descriptions spell out the semantics. The visibility field is omitted for non-API callers to cut context bloat.
• PUT /api/me/member-profile coerces smuggled visibility=public down to members_only for non-API callers and surfaces the coercion via a warnings[] array in the response — closes the whole-profile bypass path.
• applyAgentVisibility runs in a transaction with SELECT ... FOR UPDATE, eliminating the publish/downgrade race.
• /check endpoint is report-only now — returns a drift value instead of silently mutating visibility.
• UI: server/public/member-card.js renders a three-radio selector with an Upgrade-to-Professional upsell on the disabled public option; new agents default to members_only.
• Drive-by fix: brand_revisions.domain was renamed to brand_domain in migration 389 but the code still queried the old name — caused 500s on the second updateManifestAgents call for the same community brand.
• Migration 419 rewrites existing agents JSONB (is_public: true → visibility: 'public', false → 'private') and drops any pre-existing visibility key to prevent pre-migration smuggling.

Test plan

• Unit: agent-visibility.test.ts (tier helper + type guard, 10 tests)
• Unit: agent-service-visibility.test.ts (filter by viewer tier, 6 tests)
• Unit: agent-visibility-enforcement.test.ts (demote helper, 8 tests)
• Unit: mcp-tools-viewer-context.test.ts (MCP callerHasApiAccess filtering, 6 tests)
• Integration (docker postgres): agent-visibility-e2e.test.ts — Explorer 403, Professional 200, PUT-bypass coercion, private-profile members_only, tier downgrade, full cancellation, legacy is_public normalization, 11 tests
• Full 39/39 tests pass against a real migrated Postgres via docker-compose
• tsc --noEmit clean across server/
• Manual smoke via dev server: add agent in member dashboard, toggle radio, verify PATCH network call + brand.json snippet dialog
• Verify upsell copy / link in member-profile page for Explorer tier

Deferred (not blockers)

• Rate limits on PATCH /visibility (low abuse surface)
• Reconciler for non-Stripe tier changes (admin direct UPDATE, trial expiry) — current hook covers Stripe webhook path
• Error code standardization across /publish//check (PATCH uses error: tier_required; others still human strings)
• Upsell telemetry ("47 Professional members viewed this agent")

🤖 Generated with Claude Code

[EmmaLouise2018]

Review — Three-Tier Agent Visibility

Blockers

2. Tier bypass via POST /api/me/member-profile (profile creation). The PUT handler coerces public→members_only for non-API tiers, but the POST creation path persists the request body's agents verbatim via createProfile. An Explorer user who hasn't created a profile yet can land visibility:'public' on first write, and subsequent readers filter strictly on visibility === 'public' with no tier re-check. Apply the same isValidAgentVisibility + tier-gate coercion on create.

3. addAgent MCP path defaults visibility:'public' with no tier gate. server/src/addie/mcp/member-tools.ts:4870 — an unpaid org calling this tool writes a public agent straight into its profile. Either default to members_only (matches the UI) or resolve caller tier and gate. Option A is safer.

High

4. TOCTOU on the tier gate. applyAgentVisibility uses SELECT … FOR UPDATE on member_profiles, but requireApiAccessTier reads the org tier before the transaction. A concurrent Stripe downgrade webhook can land between the tier read and the UPDATE, committing a public write on a now-downgraded org. Re-read tier inside the transaction.

5. demotePublicAgentsOnTierDowngrade is not transactional. services/agent-visibility-enforcement.ts:38-73 calls getProfileByOrgId then updateProfileByOrgId as two statements — no row lock. A concurrent PUT/PATCH can reinsert public entries. Wrap in a transaction with FOR UPDATE.

Medium

• brand.json + agents JSONB updates are not atomic. brandDb.updateManifestAgents opens its own pool connection outside applyAgentVisibility's transaction — if the JSONB UPDATE/commit fails after the manifest is written, drift results (the exact thing /check detects). Pass client through so both ride the same transaction.
• profile_visibility field in MCP responses (mcp-tools.ts:817,868) conflates profile-level is_public with agent-level visibility on the wire under the same naming. Rename to directory_listed: boolean.
• Error shapes are inconsistent across /publish, /check, /visibility, PUT profile ({error} vs {error,message} vs {error, valid}). UI copes via data.message || data.error. PR defers standardization; acceptable with a follow-up.
• New helpers typed req: any, res: any (resolveUserOrgId, requireApiAccessTier in member-profiles.ts). Use Request/Response + an AuthenticatedRequest to drop the six req.user!.* non-null assertions.
• No exhaustiveness guards on AgentVisibility. agent-service.ts:isVisibleToViewer and the applyAgentVisibility body builder use ternary chains with implicit fallthrough. Switch to switch + assertNever so adding a tier becomes a compile error.
• warnings: Array<Record<string, unknown>> (member-profiles.ts:498). Now that this is part of the PUT response contract, model a ProfileWarning discriminated union with code: 'visibility_downgraded'.

Nits

• listAgents(typeOrOptions?: AgentType | AgentListOptions) dual-signature — the as AgentType | undefined cast launders arbitrary strings. Consider splitting or adding a runtime guard.
• normalizeAgentConfig is duplicated inline in applyAgentVisibility's raw-SQL path. Extract to one module.
• is_public dropped from AgentConfig without a deprecated-optional step — consider keeping it deprecated-optional for one release.
• mcp-tools.ts:callerHasApiAccess comment claims memoization but no cache map is passed.
• .changeset/agent-visibility-tiers.md has a doubled --- frontmatter delimiter.

Positives

• Report-only /check with a three-state drift enum — material correctness improvement.
• Structured warnings[] with visibility_downgraded on PUT is a great pattern.
• safeId derived only from URL prevents user-controlled name from poisoning brand.json.
• applyAgentVisibility correctly centralizes /publish, DELETE /publish, and PATCH /visibility; /check stays out of it.
• Good test coverage (39 tests, real Postgres e2e), dependency-injectable enforcement service.

Recommendation

Request changes. Blockers: migration idempotency, POST creation tier bypass, MCP addAgent default. The two TOCTOU fixes likely share the same transactional-tier-read change.