# Pi User Authentication and Startup Error Handling

## Goal

Make the Dockerized ThothII runtime use the same provider authentication that Pi stores for
the host user, expose only the explicitly enabled model set (including DeepSeek V4 Pro), and
avoid leaving apparently healthy `open` sessions when model startup cannot begin.

## Runtime configuration

- Keep the container user `thoth` and `HOME=/home/thoth`; those are valid container-local
  identities and must not be changed to a macOS path.
- Bind-mount a configurable host Pi auth file, `PI_AUTH_FILE`, to
  `/home/thoth/.pi/agent/auth.json` read-only. The default local value is
  `${HOME}/.pi/agent/auth.json`; deployments may override it with another absolute path.
- Keep `deploy/pi/settings.json` as the non-secret runtime policy. It must enable, in order:
  `zai/glm-5.2`, `deepseek/deepseek-v4-flash`, `deepseek/deepseek-v4-pro`, and
  `aritmolab/qwen3.6-35b-a3b`.
- Keep `deploy/pi/models.json` for custom provider definitions only. Provider credentials stay
  exclusively in Pi's user auth file and are never copied into the repository.
- Run Pi 0.80.3 in the core image, matching the audited backend provider contract.

## Session-start behavior

The settings write endpoint remains the main model-validation boundary. Session creation adds a
defense-in-depth availability check before persistence: if the saved provider/model is absent
from Pi's current enabled and authenticated model list, return a sanitized 503 and do not call
`tht session new`.

If runtime construction fails after persistence despite that check (for example a race or local
process limit), catch the error, mark the just-created session failed, and return the same
sanitized startup error. Never expose provider credentials or raw Pi errors to the browser.
Asynchronous bootstrap failures continue to emit `session_failed` and persist failed state.

## Cleanup and verification

Delete only these incomplete sessions:

- `a390c8b8-0a91-4a37-967b-ce7ff9be9797`
- `a2f974b2-4c48-4967-b4b6-afdbc2b2d541`
- `f66e1959-3c71-4b10-8aa1-606992046b7e`

Verify configuration contracts, backend tests and typecheck, rendered Compose mounts, `/models`
containing all four configured models, and a live DeepSeek startup reaching its first reviewer
gate. The auth file must remain read-only and no secret value may appear in rendered Compose,
logs, tests, or source control.