5.7 KiB

Raw Blame History

Next Steps — Resume Pointer

Last updated: 2026-05-15, end of day. Where we are: Phase 0 + 0.5 done. Phase 1 doc updated for Path B. Where we go next: Freeze interface contracts, then T-1.0.

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)	⚠️ draft. Need orchestrator sign-off before T-1.5 / fan-out.
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

docs/NEXT-STEPS.md (this file)
docs/SYNC.md — current claims, gate, contracts
docs/PHASE-1-sidecar.md — what to build
docs/reference/PHASE-0-report.md and PHASE-0.5-report.md — why we're building it this way
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, or keep reserved? (Recommendation: drop.)
OQ-2. Resize message in IC-1? (Recommendation: defer.)
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.
OQ-4. Worker for T-1.0: same anthropic/claude-sonnet-4-5, or escalate to a higher-context model since the refactor touches multiple files? (Recommendation: sonnet-4-5 with context: fresh is fine for ~500 LoC refactor.)

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.

5.7 KiB Raw Blame History Unescape Escape