Fix DSH provider auth status: env fallback and saved keys

The green, yellow, and unconfirmed hints on the DeepSeek Harness model page are about detection, not correctness. Green means the listed environment variable exists, yellow means none was found, and unconfirmed means the read failed. None of them validates the key or tests the connection. Treating a green hint as “connected” leads straight into MISSING_CREDENTIAL or 401 at request time.

DeepSeek Harness: What the three states mean

Triage by hint first, then choose between adding a variable, re-entering a key, or fixing a read failure. Compare:(source)

Green is not “passed”. The official docs say detection does not validate credentials or test connections. An empty, expired, or wrong-project key can still be green.

Yellow is not always “not configured”. If the provider uses a saved credential, the placeholder says “leave blank to use saved credential” and no status text appears. Only environment fallback shows a detection hint. Read the placeholder before the color.

DeepSeek Harness: Saved credentials and environment fallback

The same input box can mean two different paths when empty: a saved credential or an environment variable. Tell them apart:(source)

1. Read the placeholder — “leave blank to use saved credential” means a stored value exists; “leave blank to use environment auth” means fallback. Expected: know what an empty field does.
2. Read the hint below — environment fallback shows detection text when empty; saved credentials do not. Expected: do not confuse “no hint” with “not configured”.
3. Enter a value — both status texts disappear and the input is used. Expected: after saving, the page only receives a redacted descriptor, never the plaintext.

Keys are write-only. After saving, the page does not receive the plaintext again; the eye button only reveals the current input. The saved value stays write-only.

DeepSeek Harness: Three common misreads

Auth is confusing because “configured” and “usable” are separated by three layers. Three misreads:(source)

1. Green means usable — the variable may be empty, expired, or belong to another project. Expected: send a real request instead of trusting the color.
2. Yellow means unconfigured — a saved credential may be in use, or the variable name is not in the detection list. Expected: read the placeholder and apiKeyEnv.
3. No key field means broken — providers such as openai-codex have no native key auth and show no field unless the profile specifies a credential reference. Expected: inspect the profile.

A fourth case: AWS profiles and Google application default credentials are provider-managed files outside the check. They may work without a green hint, and a green hint does not prove they were checked.

DeepSeek Harness: A minimal config comparison

To check environment fallback, compare apiKeyEnv in the profile with the startup environment. Example:(source)

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: https://gateway.example/v1

If this says GATEWAY_API_KEY but the shell exports GATEWAY_KEY, detection is yellow and the request reports MISSING_CREDENTIAL. Variable names match exactly, not fuzzily.

DeepSeek Harness: Troubleshooting order

Check page → environment → file → request; do not start by rewriting configuration. Steps:(source)

1. Confirm the provider on the model page — check the provider ID and model name. Expected: the key was not entered for another provider.
2. Read the placeholder — decide whether the current path is saved credential or environment fallback. Expected: know whether to check a file or an environment variable.
3. Check the startup environment — env | grep -i <variable>. Expected: it exists and is non-empty in the process that started dsh.
4. Send a real request — one minimal message with the current model. Expected: success, MISSING_CREDENTIAL, 401, or another error.

If it is MISSING_CREDENTIAL, re-enter the key or fix the apiKeyEnv variable. If it is 401, the credential was read but rejected; check ownership and permissions instead of hunting for detection.

DeepSeek Harness: Three credential sources

Saved credential, environment variable, and profile credential reference suit different setups. Compare:(source)

1. Saved credential — convenient on a personal machine; the UI writes .credentials.yaml. Cost: plaintext sensitive file; do not commit it.
2. Environment variable — fits containers and CI. Cost: the name must match apiKeyEnv and be visible in the startup environment.
3. Profile credential reference — explicit control for providers that need it. Cost: more configuration to inspect.

A practical rule: use one source per provider. If you save a key and also export a variable, diagnosing which one won becomes guesswork.

Error-to-cause table

The same “auth failure” can mean different things; match the error and hint before acting. Reference:

If the same provider behaves differently on two machines, compare their startup environments and DSH_HOME before comparing screenshots. “Sometimes works” is often two different credential sources.

DeepSeek Harness FAQ

Green hint but 401—is this a DSH bug? No. 401 means the server rejected a credential that was read. Check key ownership, quota, and provider configuration.

Do I need to restart after editing .credentials.yaml? Do not edit it by hand. Save through the UI so settings and the credential reference stay consistent; model changes apply on the next request.

Why did auth break after switching profiles? Credentials are tied to profile configuration. The new profile may point at a different apiKeyEnv or credential reference; confirm on that profile’s model page.

The short version: the hint answers “what was detected”, not “what works”. Green → check the request, yellow → check the placeholder, unconfirmed → check the read path.