pi-remote-control/docs/SYNC.md

# SYNC — Multi-Agent Coordination

> **Purpose:** allow several agents (human or AI) to work concurrently on
> this codebase without stepping on each other.
>
> **Scope:** all phases. This document is the live coordination surface;
> the phase plans (`PHASE-0..PHASE-3`) are immutable plans, this file
> tracks who is doing what *right now*.

---

## How this works

1. Every concrete work item lives in a phase plan as `T-<phase>.<n>`.
2. Before starting work on a task, an agent:
   - Pulls latest `main`.
   - Edits the **Active Claims** table below to add a row claiming the
     task with its branch name, owner handle, and timestamp.
   - Commits that edit on `main` directly (small, low-conflict).
   - Then opens the feature branch and works.
3. When the task is done (PR merged) the agent removes its claim row and
   appends a one-line entry to **History**.
4. If a task needs to **change a frozen interface contract** (IC-1..IC-4
   from Phase 1, IC-2.1 from Phase 2), the agent must:
   - Open a section under **Contract Change Requests** below.
   - Wait for at least one other active agent (or the orchestrator) to
     acknowledge by editing the row to `acked: <handle>`.
   - Only then implement the change.

The point: no central scheduler is required. A short structured edit on
`main` is the lock.

---

## Phase Gate

| Phase | Status | Notes |
|---|---|---|
| Phase 0 — Spike Stream | done | ✅ GREEN LIGHT with caveat: pipe-pane unreliable. See `reference/PHASE-0-report.md`. |
| Phase 0.5 — Spike tmux Control Mode | done | ✅ VERDICT: Path B (control mode) recommended. See `reference/PHASE-0.5-report.md`. |
| Phase 1 — Sidecar | **done** | All T-1.0..T-1.10 implemented. Smoke 12/12 green. |
| Phase 2 — iOS MVP | **in progress** | T-2.0..T-2.5, T-2.9 done. App runs on device (iOS 26, wireless). Repo: `pi-remote-ios`. |
| Phase 3 — iOS Augmentation | blocked on Phase 2 | Continuous after MVP ships. |

Update the **Status** column when a phase transitions. Allowed states:
`not started`, `in progress`, `blocked on …`, `done`.

---

## Active Claims

| Task | Branch | Owner | Claimed at | ETA | Notes |
|---|---|---|---|---|---|
| _(none)_ | | | | | |

Example of a filled row:
```
| T-1.1 | feat/p1-t1-1-tmux-manager | @jay  | 2026-05-20 14:00 | +2d | starting with manager.ts |
```

Rules:
- **One row per task.** A task can have only one active owner.
- **Owner** = the agent's handle (`@jay`, `@worker-1`, `@scout`, etc.).
- **ETA** is a rough estimate; missing it is OK, but if a row is stale > 2× ETA, anybody may reclaim after pinging.
- **Branch** must exist on the remote within 24h of the claim, otherwise
  the row is considered abandoned and may be removed.

---

## File Ownership Map

For each high-traffic file, the table below lists the tasks that may
legitimately modify it. If you need to touch a file outside this list,
add a row or open a Contract Change Request.

| File | Authorised Tasks |
|---|---|
| `extensions/remote-control/index.ts` | T-1.0, T-1.4 (events wiring only) |
| `extensions/remote-control/server.ts` (legacy) | nobody after T-1.0; legacy frozen |
| `extensions/remote-control/server/**` | T-1.0 (refactor), T-1.5, T-1.6, T-1.7 |
| `extensions/remote-control/tmux/**` | T-1.1 (control mode, not pipe-pane — see Phase 0.5) |
| `extensions/remote-control/buffer/**` | T-1.2 |
| `extensions/remote-control/sequence.ts` | T-1.2 |
| `extensions/remote-control/auth/**` | T-1.3, T-1.10 (device tokens only) |
| `extensions/remote-control/pi/**` | T-1.4 |
| `extensions/remote-control/apns/**` | T-1.10, Phase-2 T-2.9 (when iOS supplies tokens) |
| `extensions/remote-control/cli/**` | T-1.3, T-1.7 |
| `extensions/remote-control/config.ts` | T-1.7 |
| `scripts/smoke/**` | T-1.0a (harness), any T-1.* task (add new test files) |
| `docs/SYNC.md` | all (this file) |
| `docs/PHASE-*.md` | nobody once a phase has started (frozen plan) — open a CCR to amend |
| `docs/reference/**` | nobody during implementation — archival |

For the iOS repo `pi-remote-ios`, an analogous map will be added when
Phase 2 kicks off.

---

## Frozen Interface Contracts

| ID | Defined in | Status | Frozen at | Owner of changes |
|---|---|---|---|---|
| IC-1 — WebSocket frame protocol | `PHASE-1-sidecar.md` §Interface Contracts | **frozen** | 2026-05-15 | T-1.5 lead, with sign-off from any active T-2.x owner |
| IC-2 — HTTP REST shape | `PHASE-1-sidecar.md` §Interface Contracts | **frozen** | 2026-05-15 | T-1.5..T-1.7 leads |
| IC-3 — Pairing payload | `PHASE-1-sidecar.md` §Interface Contracts | **frozen** | 2026-05-15 | T-1.3 lead |
| IC-4 — Config TOML schema | `PHASE-1-sidecar.md` §Interface Contracts | **frozen** | 2026-05-15 | T-1.7 lead |
| IC-2.1 — `SessionConnection` Swift surface | `PHASE-2-ios-mvp.md` §Interface Contracts | **draft** — freeze at Phase 2 kickoff | — | T-2.5 lead |

**Freeze protocol:** when the orchestrator is ready to fan out work that
depends on a contract, they (a) re-read the contract spec, (b) update the
Status column to `frozen` and fill in the `Frozen at` date, (c) commit
that change to main. After that, modifications require a CCR.

Once a contract is *frozen* (i.e. at least one consumer task has started
work that depends on it), changes require a CCR.

---

## Contract Change Requests (CCR)

Format:

```
### CCR-YYYY-MM-DD-<slug>
- **Contract**: IC-1 / IC-2 / …
- **Proposer**: @handle
- **Motivation**: 1-3 sentences.
- **Proposed change**: diff or prose.
- **Affected tasks**: list.
- **Status**: open | acked by @… | merged | rejected
```

_(none open)_

---

## Cross-Phase Notes

Threads that don't belong in a single phase plan.

- **Spec deviations.** If implementation reveals that a spec item is
  wrong or unbuildable, write a short note here under **History**, plus
  open a CCR if it changes a frozen contract. The spec itself stays
  immutable until a v4 review round.
- **Risks materialised.** When a `Risks` row from a phase plan actually
  hits, log it here with the workaround used.
- **Tools / shared scripts.** Anything added under `scripts/` that's
  reused across tasks gets a one-liner here.

---

## History

Append-only log of completed work and notable events. One line each.

```
yyyy-mm-dd  @handle  T-x.y  what was done
```

```
2026-05-15  @worker-phase0  T-0.*  Phase 0 spike complete. tmux+pipe-pane PoC validated. GREEN LIGHT for Phase 1. Report: reference/PHASE-0-report.md. Branch: feat/spike-stream (kept for reference, not merged).
2026-05-15  @worker-phase0.5  T-0.5  Phase 0.5 spike complete. tmux control mode validated. VERDICT: Path B recommended. Report: reference/PHASE-0.5-report.md. Branch: feat/spike-tmux-cc (kept for reference, not merged).
2026-05-15  @worker-t1.0  T-1.0  Server refactor scaffold complete. server.ts carved into server/{types,server,upgrade}.ts + server/routes/ stub. LEGACY html path preserved end-to-end. Reviewer APPROVE. Branch: feat/p1-t1-0-server-refactor (merged).
2026-05-15  @worker-t1.0a  T-1.0a  Smoke test harness MVP complete. scripts/smoke/ with helpers.mjs + smoke.mjs. 6 tests: manifest, icon, GET/ auth+unauth, WS upgrade, process-alive. All green in ~1.4s. Key finding: pi requires PTY; workaround via python3 pty.spawn(). Branch: feat/p1-t1-0a-smoke (merged).
2026-05-15  @jay  T-1.1..T-1.10  Phase 1 complete. All modules implemented sequentially on single branch: tmux control-mode client (fix: -C not -CC), disk ring-buffer, auth/pairing/TLS, pi adapter, stream+input+sessions+commands+side+health routes, APNs scaffold. T-1.8 stream integration smoke 12/12 green. T-1.9 operator guide written. Two production bugs fixed: base-index issue (send-keys target was :0.0, now session-only) and -CC→-C flag in control mode.
2026-05-15  @jay  T-2.0..T-2.5,T-2.9  Phase 2 started. Repo pi-remote-ios created. T-2.0 Xcode scaffold (de.vpsj.pi-remote, team KNXX8R3648, SwiftTerm+Starscream). T-2.1 WebSocketClient+FrameCodec+ResumeCursor (IC-1). T-2.2 Pairing+Keychain+QRScanner (IC-3). T-2.3 TerminalView+ThemeStore+FontStore. T-2.4 ModifierBar+ModifierState+PasteSheet. T-2.5 SessionConnection (IC-2.1)+ScrollbackCache. T-2.9 APNs NotificationDelegate+DeviceTokenRegistrar. 111 unit tests. App boots on device (iOS 26, wireless, Xcode 16.4 Intel). APNs key: ~/.local/share/pi-remote/apns/AuthKey_285C2X4689.p8.
```