Prototype uncertain passages inline before the first build (LIVE_SPIKES)

[MaggieAppleton]

Summary

While a document is being written, Jev notices passages that a quick prototype would de-risk. The editing person's connected coding agent builds it on a throwaway chopin/spike-<id> branch with no permission prompt. A Callout under the passage shows "Prototyping…", then findings, a recommendation and screenshots. Deleting the callout dismisses the spike.

Behind LIVE_SPIKES=on.

What changed

• SpikeScout watches a document after edits settle (20s) and asks Jev which passages are worth prototyping, bounded per document and per pass.
• Spike records (spikeSchema in @chopin/experiment) own placement and dismissal state; the Callout is only a projection.
• Spike placement (spike-placement.ts) inserts and rewrites the Callout in place under the passage.
• Spike host (spike-host.ts) runs each spike as an investigation on the editing person's connector.
• Connector (apps/connector) checks out chopin/spike-<id> for spike runs and uses a spike-specific prompt; it never pushes.
• MCP gains spike-only upload_investigation_image (at most 3 per run) and submit_spike_result.
• LIVE_SPIKES config flag, startup description, and the e2e Jev fixture.

Flow

sequenceDiagram
    participant E as Editor
    participant S as SpikeScout
    participant J as Jev
    participant H as Server (investigation)
    participant C as Connector coding agent
    E->>S: Edit settles (20s)
    S->>J: Per passage (bounded)
    J-->>S: Passage worth prototyping
    S->>H: Investigation on editor's connection
    H->>C: Spike run on chopin/spike-id
    C->>H: upload_investigation_image (up to 3)
    C->>H: submit_spike_result
    H->>H: Persist spike record and document
    H-->>E: Callout rewritten in place

Loading

Persistence precedes publication: the spike record and document commit before the callout is broadcast.

Safety notes

• The image tool exists only for spike runs, with a per-run cap.
• Coding agent text is escaped into MDAST, never parsed as MDX.
• Callouts never overwrite human edits; a changed callout gets a sibling callout instead.
• Anchors are rebased against the current document before any server-authored edit.
• Jev errors do not launch coding agents.
• Spikes run only on the editing person's own connector, on a throwaway branch, and are never pushed.

Screenshots

Testing

• Unit tests for the scout, placement, host, spike records and routes.

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:

• d9af340: full-size spike screenshots via connector-local upload_image_file, follow-up scans beyond 5 passages, Queued state in creation order, no re-spike of a passage that already has a callout, and immediate cancel on callout deletion.
• 64fd0fa: Copilot CLI 1.0.96 rejects stdio MCP servers over ACP, so spike runs now get a token-guarded loopback HTTP bridge serving the run's tools plus upload_image_file, and a scan stopped at the 3-spike cap resumes when a spike finishes, fails or is dismissed. Connector test covers the HTTP bridge, its token check and the worktree path guard.
• b12cb4a: parallel upload_investigation_image calls in one run no longer overwrite each other's upload record (3-image cap holds under concurrency), and a spike result deferred by a first build's lock now lands when the lock releases or the room reopens. Unit tests in routes.test.ts and spike-host.test.ts. A connector workspace lock whose process has exited is now replaced instead of blocking startup (workspace.test.ts).

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

• Spikes ran Queued in creation order and produced 1280x800 screenshots.
• Rewriting a passage did not re-spike it, and deleting a callout cancelled its spike in about 2s.
• After 64fd0fa, spikes run over the loopback HTTP MCP bridge with real Copilot, and passages beyond the 3-spike cap are judged when a spike finishes.
• 236c29d: a spike that finishes while Build plan is queued behind it now lands its result before the build claims. The build and its approved tasks move to the callout-only revision in the same commit, and the claim waits up to 30s for spike results. Unit tests in spike-host.test.ts (queued build: result lands, then claimImplementation starts) and tasks/routes.test.ts (claim waits for results first). Server and web bun test, bun run types, bun run build and bun run ci pass.

Stack note

Stacked on #453, which is stacked on #452, #451 and #450. Base is living-build-ui. Merge rebase-only, after the lower PRs land.

🤖 Generated with Claude Code