# 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.