Add Build plan and live sync status to the document toolbar

[MaggieAppleton]

Summary

Adds a build control to the document toolbar. Once Jev judges the document ready, a one-click Build plan button appears. It drafts the graph, approves it, and starts the build on the viewer's local agent, with no review step. After the first build, the same slot shows In sync, Building…, or Out of sync with a reason. The Build view lists tasks with the commits made to each pull request.

Stacked on the living sync loop PR. Everything is behind LIVE_BUILD.

What changed

• Readiness. readiness.ts asks Jev whether the document is complete enough to build, falling back to a word and heading heuristic when Jev is unavailable. Documents already living, built, or implemented are skipped. Readiness is pushed to the client when it changes.
• Build plan button. build-plan-button.tsx runs draft, approve, start in one press, and points to the Build view if no local agent can take the build.
• Sync status. build-model.ts derives the slot's state and hint from the live snapshot and rebuild builds.
• Build view. Lists each task with its pull request commits.
• Protocol and server. Readiness and sync fields added to the implementation protocol and routes.

Toolbar slot

stateDiagram-v2
    [*] --> Hidden
    Hidden --> BuildPlan: Jev judges ready
    BuildPlan: Build plan
    BuildPlan --> Building: click
    Building: Building…
    Building --> InSync: build delivered
    InSync: In sync
    InSync --> OutOfSync: edits not yet built
    OutOfSync: Out of sync
    OutOfSync --> Building: rebuild starts
    Building --> OutOfSync: rebuild fails

Loading

Screenshots

States were captured with patched snapshots on a fake-GitHub server.

Hidden on a thin document, visible on a ready one, and the toolbar while building:

Sync states (in sync, out of sync, building), and the Build view with commits per pull request:

Testing

Unit tests cover the readiness judgement, build model, and live sync. The screenshots above come from a fake-GitHub run.

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:

• 1cca44f: Build plan queues behind a running prototype instead of being refused, and readiness ignores callouts.

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) as commit a1f2f553 on the existing PR Add type scale tokens, replace arbitrary font sizes #12, with no new PR. It is listed under "Since first build".
• Build plan clicked during a running spike queued, then auto-started about 35s after the spike finished (1cca44f).

With LIVE_BUILD off, nothing changes: no readiness judgement runs, the toolbar slot stays hidden, and the Build view behaves as before.

Stack

Base is the living sync loop PR; merge after it, rebase-only.

Queueing a build behind a running prototype or another document's build on the same connection is LIVE_BUILD-only. With the flag off, a busy workspace is refused with the previous 409 ("workspace is offline or busy").

Review fixes (restack, 2026-10-12)

• Rebase. Rebased onto main and the updated Keep a built document in sync with its pull requests (LIVE_BUILD) #452. Build plan sits in main's split header and status row.
• Draft during edit. Make Build plan explicit and show build status in one capsule #508 replaces this branch's Build plan and view, so the fix lives there. Edits made while the Planner drafts tasks now get one more draft, then the copy says "The document changed while Chopin was breaking it into tasks.", with Retry.
• Formatting. One whitespace-only commit reformats code that the whitespace-insensitive rebase left at its old indentation.

🤖 Generated with Claude Code