Keep a built document in sync with its pull requests (LIVE_BUILD)

[MaggieAppleton]

Summary

Once a document's first build completes, the document stays the source of truth. After every editor has been quiet for 45 seconds, the delta since the last built revision passes a Jev gate. If Jev judges it worth building, the delta goes to the builder's local agent, which commits onto the existing pull requests. Editing never locks during a rebuild.

Everything is behind LIVE_BUILD.

What changed

• Live snapshot. A completed live build records the built source and revision, so later deltas are always measured from the last built revision.
• LiveSyncCoordinator. Debounces edits per document (45s), runs a check, and defers behind any build in flight. Edits made during a rebuild join the next delta, so one follow-up check runs when the build stops.
• Jev gate. live-gate.ts asks Jev whether the delta is worth rebuilding. An unchanged source is never rebuilt.
• Rebuild builds. A new rebuild build kind, queued with queueRebuild against the existing pull requests. Rebuilds do not lock editing. The read_rebuild and report_rebuild tools let the agent read its delta and report its commits; the report advances the live snapshot.
• Connector rebuild prompt. The connector targets the builder's repository connection and tells the local agent to gh pr checkout, commit, and push onto each existing pull request.
• Live first-build prompt. The first build under LIVE_BUILD ends cleanly after its reports land and starts the living state.

Flow

sequenceDiagram
    participant E as Editors
    participant L as LiveSyncCoordinator
    participant J as Jev gate
    participant S as Server builds
    participant C as Connector / local agent
    E->>L: edit
    L->>L: settle 45s (reset on each edit)
    L->>J: delta since built revision
    J-->>L: worth rebuilding
    L->>S: queueRebuild
    S->>C: rebuild build
    C->>C: gh pr checkout, commit, push
    C->>S: report_rebuild
    S->>S: live snapshot advanced
    opt edits arrived mid-rebuild
        S->>L: build stopped
        L->>J: follow-up check
    end

Loading

Build kinds and states

stateDiagram-v2
    [*] --> FirstBuild
    FirstBuild: First build (locks editing)
    FirstBuild --> Live: completes, snapshot taken
    Live --> Rebuild: settled delta passes Jev gate
    Rebuild: Rebuild (queued, running; no lock)
    Rebuild --> Live: report_rebuild, snapshot advanced
    Rebuild --> Live: failed or cancelled, snapshot unchanged

Loading

Deliberate prototype tradeoffs

• Rebuild graph versions are auto-approved. This bypasses the human-only approval step, so it is acceptable only behind the flag.
• Everything is gated by LIVE_BUILD.
• After a server restart, the reconnect re-check only covers documents seen since startup.

Testing

Unit and integration tests added for the coordinator, Jev gate, rebuild lifecycle and routes, graph handling, connector run, and config.
On 10 Oct I ran this end to end on github.com/MaggieAppleton/margin with a Copilot coding agent (copilot --acp --allow-all):

• Spikes posted findings inline under 3 passages.
• Build plan drafted, approved and started in one click, and opened margin PRs Comment on the plan, and accept the thread as a decision #1 to Test the frontend with a browser, and run it on every push #6.
• After going live, the edits "Snooze 15 -> 10 min" and "unread badge on the bell" each went Out of sync (+3s), Building... (+47s), In sync (+79s). They landed as commits 4e38f460 and b9fc9286 on the existing margin PR Test the frontend with a browser, and run it on every push #6, with no new PR.
• Typing during Building... was accepted.

Follow-up fixes from that run, now in this branch:

• 85e99be: a blocked or stopped first build still goes live, and rebuilds carry outstanding tasks.

Verified end to end (second run, 10 Oct) with copilot --acp --allow-all on github.com/MaggieAppleton/margin:

• The first build of 8 tasks opened margin PRs Let the planner reach for a diagram or a formula #7 to #14 with no blocks.
• A live edit, "Snooze 15 -> 5", went Out of sync, then Syncing... (+44s), then In sync (+92s). It landed as commit a1f2f553 on the existing PR Add type scale tokens, replace arbitrary font sizes #12, with no new PR, and is listed under "Since first build".
• Not exercised: a blocked first build resuming (85e99be). That is unit-tested only.

Planner fixes (f49cbe3, 31fcf10): edit_implementation_graph now advertises the exact task schema (id, title, context, goal, acceptance[2-8], dependsOn) and refusals name the expected fields, so the Planner stops guessing description. Decision cards no longer stay on "Linking…" after a first build: once a living document's first build releases editing, the Planner is asked to re-link pending decisions (anchor_plan already works during rebuilds). Flag-off behaviour is unchanged.

Stack

Merge after #450 and #451, rebase-only.

Review fixes (restack, 2026-10-12)

• Consent at pairing (decision 2, S1). The pairing page now asks once, unticked by default: "Let Chopin build and prototype automatically on this laptop". The answer is sent with approve and kept in memory on the connection.
  • Automatic rebuilds go only to the builder's own opted-in connection for the live repository.
  • A pressed Build still works without consent.
  • Rebuild checks are scheduled only by persisted edits from writers. Every document-changing socket frame requires write access, and MCP writes require push.
  • The rebuild prompt and the Jev gate frame document text as untrusted data.
  • The trust model is now in AGENTS.md (Authority and security) and in docs/implementation-lifecycle.md under "Living documents".
• Interrupted first builds never resume on their own (decision 4, S2). A first build goes live only when its agent reports stopped. A sweep, expiry, disconnect or failure needs Retry; there is a test.
• S3. reportRebuild clones the lifecycle before changing it. A test shows that a failed commit leaves the graph, lifecycle, live record and builds unchanged.
• S4. Once the history reaches 100 builds, ended rebuilds give way, oldest first. The first build and active builds stay; there is a test.
• N1. The live snapshot shows the builder's checkout, their connection, and whether their agent is online only to the builder. Others get LiveRebuild without connectionId, checkout or session.
• N2. A repeated report_rebuild after the rebuild landed returns the same success, even after a newer rebuild has queued. A different report is still refused.
• N5. A rebuild's graph version records its sealed target.revision. Pull request URLs compare case-insensitively, and commit SHAs accept uppercase and are stored lowercase.
• New tests.
  • A rebuild token cannot call start_task, read_implementation or complete_task, and a build token cannot call report_rebuild.
  • Another person's laptop, or the builder's laptop for another repository, never takes the rebuild.
  • A laptop paired without consent takes no automatic rebuild.
  • Pairing records consent.
  • Persistence failures and pruning are covered.

🤖 Generated with Claude Code