# Phase 5 Implementation — Next-Session Prompt

**Use a fresh session.** **Model: Claude Sonnet (latest) / Cursor Auto** (⚡ — implementation against
an already-ratified contract). Escalate to a thinking model ONLY if a security-tier test reveals a
genuine ambiguity in the Phase 5 contract — stop and ask rather than guessing.

---

You are implementing **Phase 5 — the Companion App shell** on Muse branch `feat/companion-app`.

This is the ⚡ implementation phase against an **already-ratified design**. The bind gate
`docs/COMPANION-APP-PHASE-5-BIND-GATE.md` (D5.1–D5.8) was **owner-approved 2026-06-06**. Do **not**
re-litigate the design — implement it exactly. If you find a real gap in the contract, **stop and ask**;
do not silently deviate (Aaron's Rule #1/#2).

## Read first (in full)

- `docs/COMPANION-APP-PHASE-5-BIND-GATE.md` — the ratified contract you are implementing (D5.1–D5.8,
  threat model P-a…P-k, §11 test obligations, §0 scope boundary).
- The four pure cores you are wiring (do not modify their security invariants):
  - `lib/companion-loopback-guard.mjs` (Phase 2 — `verifyLoopbackRequest`)
  - `lib/companion-oauth-pkce.mjs` + `lib/companion-token-custody.mjs` (Phase 3)
  - `lib/companion-runtime-manager.mjs` (Phase 4 — lifecycle/admission/integrity/resources)
  - `lib/model-runtime-lane.mjs` (Phase 1 — `selectLane`, `companionAvailable` seam)
- `hub/gateway/native-oauth-provider.mjs` (the server you authenticate against — `/api/v1/auth/native`,
  emits `iss`, loopback variable-port, scope ceiling). ✅ already implemented.
- `lib/daemon-llm.mjs` + `lib/llm-complete.mjs` (the OpenAI-compatible call path the runtime speaks —
  reuse with `base_url = http://127.0.0.1:<port>` or the UDS).
- `test/helpers/companion-keychain-fake.mjs` (the in-memory keychain fake already on the branch — use
  it in tests; the real adapters are what you build).

## What to build (run-from-source; NOT packaging — that's Phase 7, §0)

Real I/O adapters + the orchestration/shell that wires the pure cores. Suggested module layout
(adjust names if a better fit, but keep one concern per file):

1. **Keychain adapter (D5.3)** — `lib/companion-keychain-adapter.mjs` (+ per-OS backends):
   `{ get, set, delete }` on the four `KEYCHAIN_ACCOUNTS` only; reject unknown accounts; macOS
   Keychain `…WhenUnlockedThisDeviceOnly` (no iCloud sync), Windows per-user DPAPI, Linux libsecret;
   **no plaintext fallback** (fail-closed when locked/unavailable). Pick the OS backend at runtime;
   shell out to `security`/`secret-tool` or use a vetted native binding — document the choice.
2. **Inference listener + Phase 2 guard front-door (D5.1)** — `lib/companion-inference-listener.mjs`:
   `listen(0,'127.0.0.1')` (or `[::1]`), build `allowedHosts` from the bound port, call
   `verifyLoopbackRequest` before any model work, never emit permissive CORS, no `SO_REUSEPORT`,
   hard-abort if loopback bind fails.
3. **OAuth redirect listener + flow driver (D5.2)** — `lib/companion-oauth-flow.mjs`:
   separate one-shot ephemeral loopback listener, open the **system browser** with
   `buildAuthorizationUrl`, validate the callback with `validateAuthorizationResponse({..., expectedIssuer})`,
   POST the token request over TLS (full cert verification), store via custody.
4. **Spawn adapter (D5.4)** — `lib/companion-spawn-adapter.mjs`: `spawn`/`kill`/`healthCheck`; absolute
   binary path, `shell:false`, argv array, **scrubbed child env** (no `SESSION_SECRET`/`*_API_KEY`/JWT/
   tokens/keychain refs), process-group, loopback/UDS-`0600` bind flag; detect-and-reclaim a stale
   runtime on start.
5. **Download adapter (D5.5)** — `lib/companion-download-adapter.mjs`: dumb HTTPS-only streaming byte
   pump (`download(url, onChunk)`), full TLS verification, no integrity decision in the adapter. The
   **orchestrator** owns `createIntegrityAccumulator` + `finalize()`, atomic temp→verified move, and
   the first-party out-of-band manifest fetch (trust anchor — NOT from the model host).
6. **Resource probe (D5.6)** — `lib/companion-resource-probe.mjs`: runtime-PID-scoped RAM/CPU; VRAM
   aggregate-only, never enumerate other GPU processes; no privilege escalation; ≤500ms cache.
7. **Orchestrator / shell (D5.7, D5.8)** — `lib/companion-shell.mjs`: wires everything; computes
   `companionAvailable` (true only when integrity-verified ∧ lifecycle `ready` ∧ recent health
   round-trip, recency-bounded; false on any doubt); enforces **object-capability segregation** —
   the runtime group (spawn/download/health/stat) is constructed with **no** reference to the
   authority group (keychain/JWT/canister).

## Hard constraints

- **Muse-canonical**, stay on `feat/companion-app`. No git/gh for this tree.
- **Fail-closed** at every bind/custody/spawn/download/probe point.
- **No secret** in any log, error, adapter interface, or redirect (loopback token, JWT, refresh token,
  code, `code_verifier`, `SESSION_SECRET`, digest, model path).
- Do **not** change the pure cores' security invariants or the server-side OAuth provider.
- Do **not** do packaging/signing/notarization/auto-update (Phase 7), new storage paths (Phase 6), or
  new server routes (none needed).

## Tests (Aaron's Rule #0 — all 7 tiers before any merge to `main`)

Per `PHASE-5-BIND-GATE.md` §11. Centerpiece security tier MUST include: loopback-only bind (reject
`0.0.0.0`/`::`/routable); DNS-rebinding + cross-origin still 403 at the front-door; runtime back-end
carries no authority + no CORS; keychain surface minimal + device-local; **child-env contains no
secret**; **architecture/import test: runtime group imports no authority module** (build-blocking);
manifest trust-anchor out-of-band from the model host; resource probe never enumerates other GPU
processes; `companionAvailable` fail-closed; no secret in any output.

## Suggested order

1. Keychain adapter (+ 7 tiers) — everything else depends on custody.
2. Inference listener + guard front-door (+ 7 tiers).
3. Spawn + download + resource adapters (+ 7 tiers each).
4. OAuth flow driver (+ 7 tiers; stub the browser-open in tests).
5. Orchestrator/shell (+ integration/e2e: sign in → manifest → download → verify → spawn → health →
   `companionAvailable=true` → enrich locally; plus the architecture/env-scrub security tests).
6. Run the full suite once, fix all failures, re-run only the failed files, then full suite as the
   final gate. Commit on `feat/companion-app` via Muse.