bug(providers): an invalid stored provider profile wedges sandbox creation and profile repair with no in-product recovery

[Tojaj]

User Story

As an OpenShell operator upgrading an existing local gateway, I want to list,
export, repair, or delete a stored provider profile that a newer release now
rejects, so that one stale record does not block sandbox creation and force me
to erase all gateway state.

Problem Statement

A custom provider profile that a gateway accepted and persisted can become
invalid after an upgrade, because profile validation gained rules that did not
exist when the profile was imported. In the reported case, a credentialed
endpoint with no protocol now requires an explicit
allow_uninspected_credentials: true.

The gateway builds and validates the entire effective provider-profile catalog,
and fails the whole request if any profile in a user-managed source is invalid.
Every provider-profile RPC does this before touching the addressed record, so
the invalid profile blocks the very operations needed to inspect, repair, or
remove it: list, get/export, lint, import, update, and delete.

The same catalog snapshot is also taken unconditionally on the sandbox create
path, so the failure is not contained to provider workflows.

Impact / Why This Matters

One bad record takes out the gateway's primary function. Sandbox creation fails
even for sandboxes that reference no provider at all, because the create path
snapshots the provider-profile catalog before doing anything else. Provider
creation, provider attach, provider-profile listing, export, lint, import,
update, and delete all fail with the same error.

Nothing in the product can fix it. The documented export → edit → update repair
loop is unavailable, because export is one of the blocked calls; the persisted
profile is precisely the data needed to diagnose and repair the failure, and it
cannot be read out. Import of a corrected replacement is blocked too.

The reporter's workaround was to remove the gateway registration and delete all
local OpenShell state (~/.local/state/openshell/,
~/.config/openshell/gateways/) before reinstalling. That is insufficient
because it discards every unrelated provider, profile, credential reference, and
sandbox record on the gateway. Reinstalling the package alone (dnf remove openshell plus a fresh install.sh) did not help, which confirms the bad data
lives in gateway state, not in the installed artifacts. The only narrower
recovery is hand-editing the gateway's object store, which is unsupported.

This is worst during upgrades, which is exactly when it fires: the operator has
no warning that a stored profile has become invalid until the next request
fails, and by then every recovery command is already blocked.

Acceptance Criteria

• Creating a sandbox that references no provider succeeds while an invalid
  stored provider profile exists.
• Listing provider profiles succeeds and reports the invalid profile as
  invalid, rather than failing the whole call.
• Exporting the invalid profile by ID succeeds and returns its stored
  fields plus a resource_version usable for a follow-up update.
• Updating the invalid profile by ID with a valid replacement succeeds,
  and still enforces the existing target-ID and resource-version checks.
• Deleting the invalid profile by ID succeeds when no provider references
  it, and still fails when one does.
• Recovery operations continue to enforce workspace authorization,
  configured-source boundaries, and static/interceptor profile immutability.
• Operations that would put the invalid profile into effect — creating a
  provider on it, or attaching it to a sandbox — remain rejected until it is
  repaired or removed.
• The error surfaced to the operator names the offending profile and states
  how to recover from it.

Reproduction Steps

1. On an OpenShell release published before 2026-08-19 (before the credentialed
   endpoint rule landed), import a custom provider profile named
   opencode-openrouter containing a credential and an endpoint with no
   protocol and no allow_uninspected_credentials:

   id: opencode-openrouter
   display_name: Opencode OpenRouter
   credentials:
     - name: token
       env_vars: [OPENROUTER_API_KEY]
   endpoints:
     - host: openrouter.ai
       port: 443
       protocol: rest
       tls: terminate
     - host: opencode.ai
       port: 443

   openshell provider profile import ./opencode-openrouter.yaml

2. Upgrade to a current release and start the local gateway.

3. Create a sandbox that references no provider:

   openshell sandbox create repro -- bash

   Observe the catalog validation error instead of a sandbox.

4. Attempt the documented repair loop:

   openshell provider profile list
   openshell provider profile export opencode-openrouter -o yaml
   openshell provider profile delete opencode-openrouter

   Observe that all three fail with the same error, leaving no in-product way
   to read, repair, or remove the profile.

Environment

• OpenShell: 0.0.116
• OS: Fedora 44
• Install method: install.sh from main, upgraded in place over an older
  install
• Gateway: local, https://127.0.0.1:17670, mTLS
• Gateway state: ~/.local/state/openshell/
• Profile source: user (default user-managed source), workspace default

Logs

$ openshell provider profile delete opencode-openrouter
Error:   × code: 'The system is not in a state required for the operation's execution', message: "provider profile source 'user' is invalid: provider profile 'opencode-
│ openrouter' endpoints[1].allow_uninspected_credentials: credentialed endpoint 'opencode.ai:443' uses L4-only; configure L7 inspection or explicitly set
│ allow_uninspected_credentials: true"

The identical error is returned by openshell provider create,
openshell provider profile export, and openshell provider profile list.

Technical Investigation

Where the error comes from:

• validate_source_profiles turns the first error diagnostic from any
  user-managed source into FailedPrecondition
  (crates/openshell-server/src/provider_profile_sources.rs:725). It is called
  from build_effective_profiles, separately for the platform-scoped and
  workspace-scoped groups of each user-managed source
  (provider_profile_sources.rs:589-617), so an invalid platform-scoped profile
  fails catalog construction in every workspace.
• snapshot_catalog (provider_profile_sources.rs:362) therefore returns an
  error for the whole catalog, not for the individual bad profile.

Which callers are affected — every one of these calls snapshot_catalog and
propagates with ? before it looks at the addressed record:

Operation	Location
create sandbox (unconditional, even with no providers)	crates/openshell-server/src/grpc/sandbox.rs:407
attach sandbox provider	crates/openshell-server/src/grpc/sandbox.rs:1144
create provider	crates/openshell-server/src/grpc/provider.rs:2502
list provider profiles	provider.rs:2623
get provider profile (backs profile export)	provider.rs:2654
import provider profiles	provider.rs:2684
update provider profiles	provider.rs:2774
lint provider profiles	provider.rs:2900
delete provider profile	provider.rs:2933
policy chunk reconciliation	crates/openshell-server/src/grpc/policy.rs:990, policy.rs:1277

Note that handle_create_sandbox_inner has no early exit for an empty
spec.providers; the guard at sandbox.rs:392 only skips the sandbox sync
lock, and the catalog snapshot at sandbox.rs:407 runs regardless.

Which rule fires: crates/openshell-providers/src/profiles.rs:2640-2659 flags a
credentialed profile whose endpoint has an empty protocol or tls: skip
without allow_uninspected_credentials: true. It was added on 2026-08-19 in
0d708d6d, "fix(policy): gate uninspected credentialed endpoints" (#2493). Any
profile of this shape imported before that commit is accepted at import time and
rejected on every read afterwards.

This report does not ask for that rule to be relaxed. Fail-closed is right for
putting a profile into effect. The problem is that it is applied to the whole
catalog ahead of operations that only address one record, and ahead of paths
that do not consult provider profiles at all.

For context, the reporter previously filed
#1714 ("provider v2 profile
lint does not validate L7 endpoint constraints"), which is the same validation
area; #2493 is the change that introduced the specific rule seen here.

ProviderTypeProfile already serializes resource_version when non-zero
(profiles.rs:599), so an export-based repair loop has the field it needs once
export is reachable.

No new configuration, protocol schema, Helm, or LSM behavior appears to be
required.