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

8.1 KiB
Raw Blame History

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.