ThothII/docs/superpowers/specs/2026-07-21-pi-user-auth-and-startup-errors-design.md

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.