Build an M-Agent + N-Human Cooperative IDE in Rust gpui

Activation boundary: use this when editor collaboration or recovery needs a decision across UI, CRDT, claims, and transport. A bounded pane, transition, or shader change can activate its owning sibling directly. This entry is the cross-layer architecture and authority contract, not a required wrapper for every visual edit.

This is the capstone: the whole-system skill for building the Harbor — an editor where M autonomous agents and N humans edit the same files at once, as co-equal replicas, on a native Rust gpui shell, governed by a daemon that already exists. It is an index/orchestration skill: it holds the architecture and dispatches each slice into the sibling rust skills. The thesis (from the battle plan) is the critical wall: make the CRDT governable — Loro merges bytes, claims govern intent, the harbor card decides who may write the region at all.

DEPENDS ON (pull these as you work)

Sibling skill	Pull it when you're working on…
gpui-rust-console	the shell itself — core/pd-console's mux/Workspace pane tree, the render-agnostic Pane/Surface contract, or the reqwest↔smol refresh pipeline the Harbor is built on top of.
rust-gpui-motion	any transition/animation — pane expand, board/hop, the spawn→fullscreen→diff flow, presence pulses. The no-transform constraint lives here.
gpui-shaders	bespoke GPU surfaces — the living-harbor water, dithered chrome, sonar sweep, biofield.
sound-design-and-audio	the fleet audio cues (board/steer/hop/approve/fail) and how to ship them in Rust.
beautiful-gui-design	the visual system — hierarchy, semantic tokens, light/dark, contrast, the 8pt grid, a11y.
vello-parley-rendering / metal-text-pipeline	vector viz + bare-metal text/glyph rendering when you go below the widget layer.

Plus the canon docs: docs/strategy/harbor-editor-battle-plan.md (the spine) and docs/design/harbor-interaction-model.md (the Quay/board/steer interaction). <!-- cite-exempt: forward design+build target of this capstone skill (harbor-editor track); not a file in this bundle -->

When to Use

• Building any part of the cooperative IDE / Harbor editor.
• Adding a new collaborative surface (editor, Quay, transcript, diff, commission).
• Wiring agents-as-peers, claims/conflict UX, salvage, or a harbor transport.

NOT for

• A single, non-collaborative gpui screen — compose the sibling skills directly.
• Web-based collaborative editors (different stack).
• Non-editor apps.

Decision Points

flowchart TD
  A[Working on the coop IDE] --> B{Which layer?}
  B -->|The FACE: panes, surfaces, interaction| L1[Layer 1 gpui shell → rust-gpui-motion, gpui-shaders, sound, beautiful-gui-design + ref 02]
  B -->|The TEXT: buffer, replicas, presence| L2[Layer 2 editor core on Loro → ref 03]
  B -->|GOVERNANCE: claims, guard, salvage| L3[Layer 3 coordination kernel = the daemon → ref 03]
  B -->|The WATER: LAN/shared/remote| L4[Layer 4 transport behind SyncTransport → ref 01/04]
  L1 --> P[Pick the phase in the roadmap → ref 04]
  L2 --> P
  L3 --> P
  L4 --> P

Core Rules

• Governable CRDT. Loro v1.13.x is the buffer; a claim is a presence range the guard can refuse to merge across. Bytes merge automatically; intent is governed above the CRDT.
• Actors and replicas are distinct. Bind a verified principal to a distinct device/session incarnation. Never derive a PeerID from a principal or display name alone: two devices must not reuse one operation counter. DocumentRef, not an absolute path, identifies a shared document. Names are labels, not verification.
• Claims govern intent, not bytes. "Merges cleanly" ≠ "merges correctly". Enforce direct claim violations. Semantic intersection allegations remain advisory unless an authorized policy explicitly creates a gate; similarity or an unconfirmed prediction cannot block human editing by itself.
• Authoritative recovery is the target wedge, not current functionality. P3.5 requires daemon-owned typed receipts from sequence zero, sealed abandonment, canonical Rust Loro validation, and one atomic P3 claim transfer/token/provenance transaction. Current P2 snapshots, /blob, notes, generic salvage, and apply_remote_ops cannot authorize it. Build the missing authorities; never simulate them.
• The daemon IS the collab server — no new sync backend. Loro Protocol rides the existing tube; the canonical editor-sync contract owns checkpoint/reconnect behavior, while P3.5 salvage uses separate daemon-owned typed operation receipts. Notes are provenance, never replay evidence.
• Topology behind a trait. SyncTransport abstracts Shared (daemon HTTP+SSE) / LAN (iroh) / Remote (relay+E2E); the editor never knows which.
• Reuse without overstating. Layers 1, 3, and 4 assemble many shipped PD assets, but authoritative P3.5 editor recovery is still unimplemented. Layer 2's editor core and the missing recovery authorities remain real product work.
• One motion owner per surface (see rust-gpui-motion). No UI merges without visual artifacts in the test plan (screenshot + motion clip) — full stop.

Current Implementation Truth

The authenticated POST /editor/recovery/{request,prepare,replay,finalize} routes are registered security scaffolding, not a usable Harbor recovery pipeline. The P1 Rust operation-receipt producer, P1B, canonical Rust Loro recovery adapter, and P3 same-database released-claim transfer adapter remain unimplemented external gates. Daemon scope minting also lacks the required verified worktree root device/inode witness, and production does not yet provide the content-hash/parser-generation symbol lease or daemon file-mutation generation authority. Keep the public routes 503-gated until all authorities exist. Finalization must retain the descriptors and both leases through P3 transfer, persist the exact root/file device+inode, content hash, and generations, seal that hash in provenance as scope.canonical_content_hash, and consume the mutation lease in the same transaction. That lease excludes daemon-authorized writers, not arbitrary OS processes; later governed edits must reject any stale persisted witness. Canonical editor-owned provenance and its append-only outbox do not authorize replay. Any post-commit projection read, attempt-log write, or local publication-receipt failure must preserve canonical 200 success and return the stable outbox ID with a truthful pending reason; restart retries the same sink-deduplicated key until one local receipt exists. Without an atomically idempotent derived-note sink, no drain is scheduled and the outbox remains durably pending without churn; with one, bounded startup/periodic passes retry the exact key. Never fall back to sessions.addNote, and do not add migration compatibility for unshipped intermediate schemas.

Failure Modes

Anti-Pattern: "Agents as tools, not peers"

Symptom: agents are a side-panel that edits for the human; no shared cursor/claim/provenance. Detection: agent edits don't appear as a replica in the buffer; no PeerID identity. Fix: make every human/agent embodiment a distinct replica with verified principal/device/session provenance (ref 03). Do not hash a principal into one shared PeerID.

Anti-Pattern: "Trusting CRDT auto-merge for correctness"

Symptom: two actors edit the same symbol; it merges cleanly and silently produces wrong code. Detection: no claim/conflict layer above Loro; no /conflicts/predict call. Fix: claim-before-edit; predict overlap; render Conflicted band + nudge before any write (ref 03).

Anti-Pattern: "Building the editor before the coordination"

Symptom: a beautiful buffer with no claims/salvage — demos well, fails the moment two actors touch one file. Detection: P1 buffer done, P3 claims/salvage indefinitely deferred. Fix: the wedge IS coordination; sequence per the roadmap (ref 04); refuse the Potemkin editor.

Anti-Pattern: "Transport-first"

Symptom: weeks sunk into iroh/NAT traversal before the buffer or claims exist. Detection: P4/P5 work happening before P1–P3. Fix: abstract topology behind SyncTransport from day one but prove the buffer+coordination over the daemon bus first (ref 04).

Worked Example: add a collaborative surface end-to-end

Adding the Editor surface (battle plan P0→P1), composing the siblings:

1. Shell (Layer 1) — add SurfaceKind::Editor { path, region } to mux.rs; implement the object-safe Pane (one pane, two faces). Pull beautiful-gui-design for hierarchy/tokens, rust-gpui-motion for the open transition (no transform — layout-fraction zoom).
2. Text (Layer 2) — reuse the existing EditorPane and HarborBuffer; allocate a distinct replica incarnation, bind shared admission to verified principal/device/session authority, and route by DocumentRef. Never shell out to pd whoami or treat its label as verification.
3. Governance (Layer 3) — claim the edited region; /conflicts/predict; paint overlap Tone::Conflicted; guard the commit; record each validated operation in the typed salvage ledger.
4. Polish — pull gpui-shaders for the living-harbor water behind it; sound-design-and-audio for the board/approve cues.
5. Land — visual artifacts (screenshot + a board→steer→diff clip) in the PR test plan, per the standing rule.

Quality Gates (phased)

• Every actor is a Loro replica with a PD identity + provenance (agents = peers).
• Claims//conflicts/predict gate edits; logical conflict is surfaced, never silently merged.
• Salvage implemented (dead-replica op-log replays; claim inherits) — not deferred away.
• Daemon is the collab server (no new sync backend); topology behind SyncTransport.
• Build order respected (buffer+coordination before transport polish).
• Each surface composes the right siblings (motion/shaders/audio/visual-system).
• No UI merge without visual artifacts in the test plan.

Fork Guidance

Fork by layer: shell (ref 02 + the three visual siblings) · editor core (ref 03 / Loro) · coordination (ref 03 / daemon) · transport (ref 01/04). Keep the architecture (the four layers + the dependency map) in the parent so one actor owns coherence.

Reference Map

• references/01-architecture-and-the-stack.md — the whole-system view: the four layers (gpui shell → Loro editor core → coordination kernel → transport), the dependency map onto the sibling skills, what's pivotal vs polish.
• references/02-the-gpui-app-skeleton.md — structuring a large gpui app: the mux/Workspace pane tree, the Pane/Surface contract, SurfaceKind variants, the refresh→channel→view pipeline; how to add a surface end-to-end.
• references/03-collaboration-coordination-salvage.md — the heart: agents+humans as co-equal Loro replicas, presence-as-claims, the daemon as collab server, conflict UX, agents-as-peers via MCP, salvage; the M×N model + three harbor topologies.
• references/04-build-order-and-composing-the-skills.md — the phased roadmap (P0 skeleton → P1 buffer → P2 LAN → P3 agents+claims → P3.5 salvage → P4 shared → P5 remote+viz), each phase naming which sibling skill it pulls; the "you are here / read next" map.

Sibling skills (dependencies): gpui-rust-console, rust-gpui-motion, gpui-shaders, sound-design-and-audio, beautiful-gui-design, vello-parley-rendering, metal-text-pipeline.

<!-- BEGIN BUNDLE INDEX (auto: index_references.py) -->

Skill Bundle Index

Every file in this skill, and when to open it. Auto-generated; run scripts/index_references.py --fix.

root

• CHANGELOG.md — UbuildUcoopUideUgpui — Changelog — - Brought to the agentic-family standard: added io-contract/provenance/pairs-with frontmatter - Added a deterministic audit helper (ma

examples/

• examples/sample-input.json — sample input (data/schema)

references/

• references/01-architecture-and-the-stack.md — Architecture & The Stack — The Whole-System View — This is the central wall of the capstone.
• references/02-the-gpui-app-skeleton.md — The gpui App Skeleton — > Capstone reference 02 of the "Build an M-Agent + N-Human Cooperative IDE in Rust gpui" skill. > This is the structural chapter: how
• references/03-collaboration-coordination-salvage.md — Collaboration, Coordination & Salvage — the heart of the M×N IDE — This is the capstone's decisive chapter.
• references/04-build-order-and-composing-the-skills.md — Build Order & Composing the Skills — This is the index card for the whole capstone.

schemas/

• schemas/coop-ide-plan.schema.json — coop ide plan.schema (data/schema)

scripts/

• scripts/coop_ide_audit.mjs

<!-- END BUNDLE INDEX -->