Audit: credential system UX and functionality

[unforced]

Context

The credential layer (Phases 1-3 from #291) is merged. It works — helpers register, manifests self-describe, validation catches injection, tokens mint. But it hasn't had a proper UX pass or comprehensive functional audit.

What needs auditing

Functional (AI-assisted)

• Hot-reload gap: POST /setup writes to config but the running broker doesn't pick up new providers until server restart. Delete has the same desync. This is the biggest functional issue found during manual testing.
• Manifest-to-UI fidelity: Does the Flutter UI correctly render all field types, method selectors, and capability badges for every helper type?
• Error states in Flutter: What happens when the server is unreachable, setup fails, or a helper returns unexpected manifest shape?
• credentials.yaml migration: Does it actually run on startup? Does it correctly skip env vars already covered by registered helpers?
• Token minting flow end-to-end: Set up a PAT via the UI, trigger a sandboxed agent, confirm GH_TOKEN appears in the sandbox environment.
• Wrangler wrapper script: Does it actually work when wrangler is installed? PATH interposition, fallthrough behavior.
• API endpoint naming: /helpers vs /status vs /manifests — is this coherent? The test guide initially used wrong endpoints.

UX (human review)

• Setup flow: Is it clear how to add a credential? The generic env-passthrough dialog vs the manifest-driven setup dialog are two different patterns.
• Credential visibility: Can the user tell at a glance what's configured, what's healthy, what's broken?
• Delete/reconfigure: Is it obvious how to remove or change a credential?
• Empty state: Does "No credentials configured" give enough guidance on why you'd want to set them up?
• Naming: "Helper" vs "Provider" vs "Credential" — the terminology isn't consistent across UI, API, and docs.
• Settings placement: Credentials section sits between API Keys and Trust Levels — is this the right location?

Security

• Broker secret handling: Is the auth model (localhost trusted, remote needs secret) well-communicated?
• Token storage: Tokens are in config.yaml in plaintext. Is this acceptable for v1? What's the upgrade path?
• Env var injection surface: The regex + newline validation covers the obvious cases. Are there other injection vectors?

Approach

This is a combined AI + human audit:

1. AI does a systematic walkthrough of all endpoints, UI states, and error paths
2. Human reviews the overall UX coherence and whether this is understandable to a new user
3. File issues for anything that needs fixing, tagged with priority

Known issues from initial testing

• Hot-reload: setup/delete don't update running broker (restart required)
• API naming inconsistency (/helpers, /status, /manifests as separate endpoints)
• Terminology inconsistency (helper/provider/credential)
• No per-provider env/scripts endpoints (data embedded in manifest — is that right?)

Related

• feat: Credential layer for sandboxed AI agents #291 — original credential layer issue
• feat: Brain bridge agent — ambient context enrichment #130 — bridge agent (Phase 4 runtime consent is deferred)