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

Pi User Authentication and Startup Error Handling Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make Dockerized Pi consume the configured user auth store, expose four approved models, fail session startup cleanly, and remove three incomplete attempts.

Architecture: Compose mounts only the host Pi auth.json into the container while repository-owned Pi settings define the model policy. The backend validates the persisted model before creating a session and converts post-persistence runtime-construction errors into a failed session plus a sanitized 503.

Tech Stack: Docker Compose, Pi 0.80.3, Fastify/TypeScript, Vitest, shell deployment-contract tests.

Global Constraints

• Never copy or log provider keys.
• Mount the auth file read-only.
• Enabled model order is ZAI, DeepSeek Flash, DeepSeek Pro, local Qwen.
• UI error strings remain English.
• Preserve the question in the frontend retry composer.
• Delete only the three explicitly approved incomplete session IDs.

---

Task 1: Container Pi auth and model policy

Files:

• Modify: compose.yaml
• Modify: .env.example
• Modify: deploy/pi/settings.json
• Modify: docker/core.Dockerfile
• Test: scripts/test-default-compose.sh
• Test: scripts/test-container-deployment.sh

Interfaces:

• Consumes: PI_AUTH_FILE, an absolute readable host path.

• Produces: /home/thoth/.pi/agent/auth.json read-only and a four-entry enabledModels policy.

• Add failing deployment-contract assertions for the auth mount, four enabled models, and Pi 0.80.3.

• Run the focused shell tests and confirm the expected failures.

• Add the configurable auth mount, model policy, environment documentation, and Pi version alignment.

• Re-run the focused shell tests and confirm they pass.

Task 2: Pre-persistence model availability guard

Files:

• Modify: backend/src/app.ts
• Modify: backend/src/routes/sessions.ts
• Test: backend/test/routes-sessions.test.ts

Interfaces:

• Consumes: the existing ListModelsFn used by model/settings routes.

• Produces: a sanitized 503 before sessionNew when saved settings are unavailable.

• Add a failing route test proving an unavailable model returns 503 and never calls sessionNew.

• Run the single Vitest test and confirm the expected failure.

• Inject the model-list dependency into session routes and implement the minimal guard.

• Re-run the focused test and confirm it passes.

Task 3: Post-persistence runtime-construction failure

Files:

• Modify: backend/src/routes/sessions.ts
• Test: backend/test/routes-sessions.test.ts

Interfaces:

• Consumes: ThtRunner.failSession(id, workspace) and PiProcessManager.createFor.

• Produces: failed persisted state plus sanitized 503 when runtime construction throws.

• Add a failing route test for a throwing createFor after sessionNew.

• Run the single test and confirm it fails because the route currently returns 500 and leaves the session open.

• Catch runtime construction/binding failures, persist failed, and return the startup error.

• Re-run the focused test and confirm it passes.

Task 4: Cleanup and full verification

Files:

• Modify: external PSD session store only through tht session delete.

Interfaces:

• Consumes: the three approved session IDs.

• Produces: no corresponding directories or API rows.

• Run backend Vitest and TypeScript typecheck.

• Run deployment-contract tests and render Compose with the real auth path.

• Rebuild/recreate the core container and verify health.

• Verify /models returns all four enabled models in order.

• Start a uniquely named DeepSeek smoke and observe the first reviewer gate; clean up only the smoke.

• Delete the three approved incomplete sessions and verify they are absent.

• Run git diff --check and inspect the final diff for secret leakage.