Finish the living document flow's rough edges

[MaggieAppleton]

Findings (from the e2e9 critique)

1. Spike result callouts dominated the document: headline, recommendation, up to six findings and full-size screenshots made a ~600px green block at 1440 and several screens at 390.
2. The passage a spike answered still read "We are not sure whether…" directly above its own answer.
3. A spike missed while the clicker's connector was offline was never rescouted; it took another edit.
4. At 390px, long Build view task titles were cut off with an ellipsis.

Changes

• Compact result callouts. Callout gains an optional fold attribute (1–3), the number of leading blocks that stay visible. A spike result renders fold="1", so readers see the headline (title) and the recommendation, and the findings and screenshots sit behind the existing quiet "Show more" / "Show less" disclosure. Folding is a per-reader view preference, like the tab strip and code collapse. It is never written to the document, and a caret in a hidden block opens the fold. The fold is node state in its own module (callout-fold.ts). containers.ts is untouched, so its reviewed design-contract hashes stay valid. The spike prompt now asks for a headline of at most 8 words, at most three one-sentence findings and a one- or two-sentence recommendation that states the decision. Over-escaped quotes from an agent's tool arguments (\"No notes yet\") are cleaned up.
• The answered passage settles itself. I chose the "agent just does it" route over a button. When a result first lands in its callout, the server starts a Planner turn (the relinkDecisions pattern, now a shared serverInstruction). That turn rewrites only that passage as the decision the recommendation supports and keeps the callout as the evidence. It appears in Chat as "Updating the passage the prototype answered", and the edit carries a normal change mark. It runs under the existing Planner owner. If there is none, it claims one for the person whose edit started the spike, but only while they have the document open. It never runs while a build holds the lock. Why not a button: the editor has no notion of which callouts are spike results. A button would need a new protocol message plus per-callout chrome, and the person would still have to notice it.
• Reconnect rescouting. SpikeScout remembers documents whose last scan found no local agent. connected(repositoryId, owner) rescans them, wired next to liveSync.connected on pairing approval.
• Wrapping task titles. Titles clamp at two lines. The status dot and the pull-request capsule stay on the first line, and single-line rows are still 40px.

Tests: fold logic, fold round trip and validation, the result callout's fold, landed-once, the instruction text, quote cleanup, and reconnect rescans (only the matching repository and owner, and only once). bun run types, bun test (the only failures come from untracked design-jig files and pass once they are moved out), bun run ci and bun run build are green. Initial JS is 79,824 B gzip, under the 81,500 B budget.

Real-run verification

The server ran from this branch on chopin_living with LIVE_BUILD=on LIVE_SPIKES=on CONVERSATION_PLAN=on, against a real copilot --acp --allow-all connector on MaggieAppleton/margin. The document was "Margin — polish check".

• Compact callout: the empty-state spike landed at 23:53:29 as headline, recommendation and "Show more" at 1440 and 390. Show more reveals the three findings and the screenshot.

• Passage settled: the Planner turn ran right after it landed. "We are not sure whether the empty list should show…" became "At 1280px, the empty list uses a centred card saying “No notes yet” with a one-line hint…". A second spike, on an acceptance criterion, settled the same way.

• Reconnect rescout: I stopped the connector and restarted the server, then added "We are not sure whether each note's time should be relative…" at 23:55:58. No spike started over the next ~80s. I restarted the connector and approved pairing at 23:57:24. "Prototyping…" appeared the same second without another edit. The result landed at 23:59:10, with plain quotes, and the passage was rewritten to "Each note shows a relative time, such as “5 min ago,”…".

• Build view at 390: I clicked Build plan at 00:00:15 and the build reached In sync at 00:05:27 (Margin PRs Let the planner draft and revise implementation graphs #45–Expose MCP task lifecycle reporting with durable progress state #48, with no prototype task). "Display relative note times with exact-time tooltips" wraps to two lines. I also re-rendered the e2e9 "Margin — fix check" build. "Delete notes with the prototyped control" now wraps to two lines, with Persist versioned implementation graphs alongside plan revisions #44 aligned to the first line.

• Hard kill (51de746): in "Margin — hard kill check" I SIGKILLed the connector at 01:13:34 and added an uncertain sentence. The spike queued on the dead connection, then expired at 01:15:08. The callout read "Prototype paused — Waiting for @MaggieAppleton’s coding agent to reconnect" instead of "Propose a new attempt". After I re-paired, the same spike ran (retries: 1) and landed at 01:16:31 with no further edit.

• Testing: bun run types, server bun test (2774 pass), connector and experiment bun test, bun run build and bun run ci all pass. New unit tests cover an interrupted spike retrying on reconnect, the retry cap, dismissal staying permanent, the waiting copy, and skipping connections silent for two heartbeats.

Screenshots

	Before	After
Result callout, 1440
Result callout, 390
Expanded, 1440
Build view, 390
Build view, 390 (this run)

Stack

Stacked on #457 (living-design-review), at the top of #451 → #452 → #453 → #454 → #457. Merges are rebase-only. Rebase and force-with-lease after a lower PR lands.

🤖 Generated with Claude Code

[coolify-githubnext-app]

The preview deployment for chopin is ready. 🟢

Open app | Open Build Logs | Open Application Logs

Last updated at: 2026-10-11 05:42:39 CET