pi-remote-control/docs/NEXT-STEPS.md

# Next Steps — Resume Pointer

> **Last updated:** 2026-05-15.
> **Where we are:** Phase 0 + 0.5 done. Phase 1 doc updated for Path B. Interface contracts IC-1..IC-4 frozen (commit 7c40c49).
> **Where we go next:** Dispatch T-1.0 — Server Refactor.

This document is the "where did I leave off" anchor. Read this first when
resuming work. The rest of `docs/` is reference.

---

## State at end of session

| Item | Status |
|---|---|
| Phase 0 — Stream Spike | ✅ done. Verdict GREEN with caveat (pipe-pane unreliable). Branch `feat/spike-stream` kept. |
| Phase 0.5 — Control-Mode Spike | ✅ done. Verdict: **Path B — tmux control mode**. Branch `feat/spike-tmux-cc` kept. |
| Phase 1 plan | ✅ updated to Path B. T-1.1 now specifies control mode + `%output` parser. Architecture diagram, risks (R4 + R5) added. |
| Interface Contracts (IC-1..IC-4) | ✅ **frozen** 2026-05-15. See SYNC.md. |
| Phase 1 implementation | ⛔ not started. T-1.0 is the next dispatch. |
| iOS work | blocked, untouched. |

Branches on remote `git.vpsj.de/jay/pi-remote-control`:
- `main` — has all docs, no implementation changes yet.
- `feat/spike-stream` — Phase 0 PoC, throwaway.
- `feat/spike-tmux-cc` — Phase 0.5 PoC, throwaway. Reference impl for T-1.1.

---

## Orchestrator todo list (in order)

These are things only the orchestrator does — not delegatable to a worker
subagent.

### 1. Freeze interface contracts

Open `PHASE-1-sidecar.md` §Interface Contracts and re-read IC-1..IC-4.
For each: does it still look right after the spikes? Anything to tweak?

Things to double-check:
- **IC-1 ClientToServer**: do we want to add `{ type:"resize"; cols:int; rows:int }` so iPad-Landscape can renegotiate tmux pane size? (Spec said fixed 120×40, but if we ever want elastic, this is the place.) Recommendation: defer, fix at 120×40 for v1, revisit only if it bites.
- **IC-1 ServerToClient**: `tree` event — gruppe T is out of iOS scope, so this can be dropped from the contract OR kept as "reserved, server may emit but client ignores". Recommendation: drop to keep contract tight.
- **IC-2 REST shape**: `/sessions/:id/thumbnail` is referenced by iOS-D-01c (Phase 3). Should the endpoint return raw text/plain capture, or a structured JSON `{cols,rows,lines:[…]}`? Recommendation: raw text/plain — simpler, smaller, client parses lines itself.
- **IC-3 pairing**: `deviceToken` and `environment` are now mandatory in Phase 2. Pre-Phase-2 they're optional. Mark accordingly.
- **IC-4 TOML config**: `[apns]` section can have an `environment_default` for testing convenience? Probably no — environment is per-device. Leave as-is.

After review:
- Edit `SYNC.md` "Frozen Interface Contracts" table: set Status `frozen` and fill `Frozen at` date.
- Commit on main.

### 2. Dispatch T-1.0 — Server Refactor

Single agent, blocking everyone else. Refactor existing
`extensions/remote-control/server.ts` (335 lines) and friends into the
modular layout from `PHASE-1-sidecar.md` §Architecture Sketch.

Prompt template (adapt with concrete contract numbers):

```
# Task: Phase 1 T-1.0 — Server Refactor

Working dir: /Users/jay/.pi/agent/git/git.vpsj.de/jay/pi-remote-control

Read first:
- docs/NEXT-STEPS.md (state of play)
- docs/PHASE-1-sidecar.md §Architecture Sketch and §Task Breakdown row T-1.0
- docs/SYNC.md (claim the task)
- existing code: extensions/remote-control/{index,server,html,messages,auth,config}.ts

Goal:
- Carve existing server.ts into the server/ + server/routes/ + server/upgrade.ts
  structure from the phase doc.
- Keep the LEGACY HTML client (html.ts) working end-to-end. Add comments
  tagging these legacy paths.
- No new features. No new endpoints. Just structural refactor + ensure
  existing tests / smoke usage still works.
- After your refactor lands, the directory layout matches the Phase-1
  Architecture Sketch.

Out of scope: anything touching tmux/, buffer/, pi/, auth/{pairing,tls}.ts,
apns/, cli/. Those are for later T-1.* tasks.

Branch: feat/p1-t1-0-server-refactor
```

After T-1.0 merges into main, the parallel fan-out becomes available.

### 3. Plan the parallel fan-out

Once T-1.0 is in main:
- 5 worker dispatches in parallel: T-1.1, T-1.2, T-1.3, T-1.4, T-1.10.
- Each gets a tight prompt referencing their row in `PHASE-1-sidecar.md`
  and the relevant frozen ICs.
- T-1.1 explicitly says: use control mode, reference `spike-cc.ts` on
  `feat/spike-tmux-cc`, follow R-CC-1..R-CC-5 expectations.

T-1.5, T-1.6, T-1.7 follow as their deps come in.

---

## Reading order for resumption

1. `docs/NEXT-STEPS.md` (this file)
2. `docs/SYNC.md` — current claims, gate, contracts
3. `docs/PHASE-1-sidecar.md` — what to build
4. `docs/reference/PHASE-0-report.md` and `PHASE-0.5-report.md` — why we're
   building it this way
5. Spec only if you forget the why: `docs/reference/SPEC-ios-app.md`

---

## Open questions for next session

- ~~**OQ-1.** Drop the `tree` event from IC-1 ServerToClient~~ — **resolved**: dropped. IC-1 frozen 2026-05-15.
- ~~**OQ-2.** Resize message in IC-1?~~ — **resolved**: deferred, fixed 120×40 for v1.
- **OQ-3.** Should `tmux/manager.ts` use a single long-lived control-mode connection per **server**, or per **session**? The spike used per-session for simplicity. Per-server scales better but is more code. Decide before T-1.1 starts. (Not an IC question — T-1.1 implementation detail.)
- ~~**OQ-4.** Worker model for T-1.0?~~ — **resolved**: `anthropic/claude-sonnet-4-6` with `context: fresh`. Haiku rejected: previous swarm attempt produced broken imports across `index.ts`/`html.ts`/`messages.ts` even on a stronger model (see deleted `feat/p1-t1-0-server-refactor` branch). T-1.0 is the blocker for all parallel fan-out — reliability over cost.

---

## Don't do tomorrow

- Don't merge the spike branches into main. They're reference, not code.
- Don't start T-1.1 before T-1.0 is in main.
- Don't start any iOS task until Phase 1 is at least feature-complete.
- Don't expand scope. Stick to v3 spec; new ideas go into a v4 review
  round, not into open PRs.