jay
/
pi-remote-control
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
pi-remote-control/docs/NEXT-STEPS.md

5.9 KiB
Raw Blame History

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.