Keep credential references current after external rotation

User Story

As an operator running long-lived clients in OpenShell sandboxes, I want to rotate an externally managed provider credential without restarting the client or replacing the reference it already holds, so that routine credential rotation does not interrupt an active session.

Problem Statement

For externally supplied static provider credentials, the reference issued to a workload is revision-scoped. A running process can retain that reference after the provider value changes. Even after the supervisor installs the updated provider environment, the retained reference can still resolve to the previous credential value while its generation remains retained.

Long-running clients need an optional way for the issued reference to select the current value across value-only updates. The existing revision-scoped behavior is an established contract and must remain the default for existing users. The extension should reuse the existing credential path while preserving authorization boundaries and revocation.

For example, with the sandbox, provider instance, credential key, and authorized endpoint unchanged:

1. A client starts with an issued reference that resolves to credential A.
2. An external updater changes that provider credential to B.
3. The supervisor installs the updated provider environment containing B.
4. The same client sends its next request using the reference it received at startup.
5. With the existing revision-scoped behavior, that reference can still resolve to A. The requested behavior is for it to resolve to B.

Impact / Why This Matters

• A client that reads its credential reference only at startup cannot rely on a value-only provider update to switch its next request to the new credential.
• If the upstream service revokes A after rotation, the client can receive authentication failures even though OpenShell has already installed B.
• Restarting or recreating the client obtains a fresh reference, but can interrupt active sessions and require recovery of in-memory state or ongoing work.
• Keeping both upstream credentials valid during an overlap period can postpone failures, but does not establish when the running client has stopped using the old credential. It also delays retiring that credential.

The desired workflow lets the operator complete a routine value rotation while the client keeps its existing process and issued reference.

Proposed Design

Extend the existing provider credential path with credentials[].stable_placeholder: true for externally supplied static credentials that need continuity across value-only updates. Keep the default false and preserve existing revision-scoped behavior, API signatures, and ordinary mixed-version operation. Reuse the existing identity-bound handle and current-value resolver; do not add a second credential mechanism.

The user-facing workflow should be:

1. The operator enables the opt-in in a provider profile using supporting components, then creates and attaches a provider through the existing workflow with an effective endpoint binding.
2. The workload receives an opaque reference through its environment and uses that issued value in requests.
3. An external updater replaces only the value of the same provider credential through the existing provider update workflow.
4. After the supervisor installs the update, the workload's next authorized request using its original reference resolves the current value. The client does not restart or receive the real credential.

Acceptance Criteria

• With the opt-in enabled, one persistent synthetic client retains its original issued reference across exactly one value-only credential update. After supervisor activation, its first subsequent request reaches a controlled HTTPS backend using the new credential.
• With the setting omitted or false, existing revision references retain their established behavior. Ordinary profile operations and provider delivery continue to work with legacy components; existing public function signatures remain available.
• Repeated value-only rotations preserve that behavior without requiring the client to acquire a new reference. Reconstructing supervisor credential state preserves the reference for the same current identity and binding.
• Changing the sandbox identity, provider instance, credential key, or effective endpoint binding prevents the old reference from resolving the replacement credential.
• An expired current credential or activated detach revokes resolution without falling back to an older value. A separate unauthenticated reachability control distinguishes credential revocation from a network outage.
• Credential-bearing requests to the wrong host, port, or path are rejected. Requests denied by existing binary policy remain denied, and TLS verification remains active.
• Hand-written canonical aliases cannot grant authority to resolve a provider credential.
• Unsupported opt-in writes are rejected before profile mutation. Unsupported stable delivery and malformed or missing credential bindings fail closed. Gateway-managed refresh and token-grant credentials retain their existing lifecycle ownership and revocation behavior.
• The workload never receives the resolved upstream credential in its environment or configuration. Tests and diagnostics do not print credential values or issued references.
• API/SDK surfaces and documentation consistently describe the opt-in, supervisor activation, component compatibility, and revocation. Existing providers require no configuration changes.

Alternatives Considered

Make every existing reference follow the current value automatically. This changes established revision-scoped behavior for all users. The opt-in preserves that contract while enabling continuity where needed. The setting selects behavior in the existing credential implementation; it is not required by the resolver itself.

Restart the workload after each rotation. A new process can receive a fresh reference, but this does not meet the requirement to preserve a long-running client and its session state.

Retain old credential values or keep both upstream keys valid longer. An overlap period can reduce immediate failures, but it does not make the original reference select the newly installed value or provide a reliable point at which the old upstream key can be retired.

Use gateway-managed refresh for every credential. Managed refresh already provides stable-handle behavior where OpenShell owns token minting and refresh authorization. Externally issued API keys and other externally rotated values need continuity without moving their lifecycle ownership into that mechanism.

Give the workload the real credential or a separately mounted credential file. This changes the credential-custody model and requires application-specific reload behavior. The requested workflow preserves OpenShell's issued-reference interface and keeps the real value in the privileged credential path.

Agent Investigation

No response

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

No files, tests, or entry points are named. Start by locating the existing provider credential path, identity-bound handle, current-value resolver, supervisor activation, and profile validation, then review the architecture documentation referenced by the checklist. Done means the opt-in preserves default revision behavior while satisfying the listed rotation, authorization, revocation, compatibility, and non-disclosure criteria.