[lavaman131]

Make a Build visible and approvable where people work

What the maintainer saw

On a hosted deployment:

1. No way to approve. After chopin rewrote a document's tasks, it said in Chat that the new version "is a draft, so it still needs approval". Nothing anywhere offered an approval. Pressing Build went ahead.
2. Chat showed nothing of a Build. During a 60-minute build, Chat had only "asked chopin to break the plan into tasks" and chopin's task message. The run strip under Chat listed only the Planner's workflow runs, never the build, its task or its pull request.
3. "The scroll box gets clipped under the workflow widget." Scrolled up, Chat's transcript ended on a hard line against the runs card, so the card looked like it covered messages.

Causes

1. Approval. The code is clear that a person's press is the approval: queueBuild approves the exact draft it starts, and a built document's rebuild works from the document's own edits, not from the task graph. Only the Planner didn't know. Its tool said "Only people may approve, lock or start implementation" and nothing more, so it told people a draft waited for an approval that doesn't exist.
2. Chat. Nothing about a build reached Chat. The strip reads only Planner workflow runs, and no system line was ever posted for a build.
3. Scroll edge. Two things.
   • The card had no height limit. With several runs unfolded it grew to its full height: in a 600px window it measured 906px, squeezed the transcript to 12px above the window's top and pushed the composer below its bottom, on desktop and phone alike. Only a single run's "every stage" lane had a limit.
   • A hard cut. With few runs, the transcript does end at the card's top edge, with its newest line and scrollbar above it, in main Chat and on a phone. But a line scrolled past that edge was cut off flat against the card, while the top edge fades.

What changed

1. Build plan is the approval, and the Planner says so (agent/tools.ts, agent/planner.ts, build-view.tsx)

• edit_implementation_graph's description and the Planner's instructions say the Build plan press approves the saved draft and starts it, so it never tells people tasks still need approval.
• A saved draft's result carries a note for the Planner to read before it says what happens next:
  • A document not yet built: Build plan builds exactly this draft.
  • A built document: Build carries the document's edits onto its pull requests; this draft is not what it runs.
• Build's "Not built yet" card says "Build plan approves these tasks and builds them."

2. A running build heads Chat's run strip (build-model.ts buildRun, chat/run-card.tsx, chat.tsx, room-workspace.tsx)

• The row: one line, read from the same snapshot as Build: a pulsing dot, "Build" (or "Building changes" for a rebuild), "1 of 2 tasks", and its age.
• Unfolded by default: the task being built, the agent's latest activity, the pull requests opened so far as #12 links, and Open Build.
• Beside workflows: a running workflow folds itself, unless it waits on people.
• Always shown: it appears whether or not the Planner runs here, and leaves the strip when the build ends.

3. Chat says what the build did (tasks/build-notices.ts, tasks/notifications.ts, main.ts, chat/transcript.tsx)

• One line per pull request: "Build opened Add type scale tokens, replace arbitrary font sizes #12 for “Scaffold the crate”."
• One line when it ends:
  • "Build finished: 2 tasks, Add type scale tokens, replace arbitrary font sizes #12 and Add easing and duration tokens, set transition defaults #13."
  • "Build stopped: “Task” is blocked: …", or why it stopped or didn't start.
  • For a rebuild: "Build finished: updated Add type scale tokens, replace arbitrary font sizes #12."
• Links and icon: each # links to its pull request, and the line shows a wrench instead of the system icon. The system row only links a GitHub pull request URL whose label is its own number; any other Markdown stays as text.
• No flooding: nothing is posted per task or per activity change.
• When they're posted: after the change is persisted, through a new backend callback under the document lock, the way the research notices are posted.
• No duplicates: each line has a fixed ID made from the build and the pull request, so a repeat is one line. A document opened long after its builds records what it has already seen and posts nothing about them.

4. The transcript's lower edge fades (chat/overlay-scrollbar.css)

• The fade: its last 16px fade into the pane, as the top edge already does.
• At the bottom: resting on the newest line, the fade sits on the transcript's own bottom space, under no text. The spec checks there are at least 16px.
• Over, not in: it is drawn over the scroller. A first version used a scroll-state query inside the scroller, which restyled the whole transcript (1,773 elements) once it left the bottom; this version restyles 12, the same as main.

5. The runs card takes at most half of Chat (chat/run-card.css, chat.tsx, threads/thread-panel.tsx)

• However many runs are unfolded, the card takes at most half of Chat's height, in main Chat and in a thread, and scrolls in its own lane beyond that, with its scrolling contained. The transcript keeps its place and the composer stays in view.

apps/web/DESIGN.md records the strip row, Chat's build lines, the edge and the card's limit.

Evidence

Synthetic, from the browser spec's fake connector, paused on its first task (desktop 1280 wide, and at a phone's width).

	Before (main)	After
A build running, desktop
A build running, phone width
The build finished

Chopin's app view is light only, so there are no dark shots.

Contrast (computed colours read from the rendered page, WCAG ratios):

Element	Ratio
Build row: "Build" and the task	9.58:1
Build row: status, activity, Open Build	6.50:1
Build row: age and chevron	4.97:1
Build row: pulse dot (non-text)	5.79:1
Chat build line: text on the ground	5.89:1
Chat build line: #12 link	6.86:1
Chat build line: wrench (non-text)	4.51:1

Tests

New

• implementation-launcher.e2e.ts: "a running build heads Chat's run strip with its task, and Chat says when it opens each pull request and when it finishes". It pairs the fake connector and pauses it on the first task, then checks:

  • the row, unfolded, with the task, at desktop and phone widths;
  • Open Build;
  • after resuming, both "Build opened" lines, "Build finished: 2 tasks, Add human-readable document URLs #101 and Repair legacy callout Enter behavior #102." with its links, and that the strip lets the build go;
  • three lines after a reload.

  It fails on main, which shows no row.

• chat-run-strip.e2e.ts (harness project):

  • Five runs of six stages, all unfolded, in a 1280 × 600 window and a 390 × 664 phone. It checks that the card is at most half of Chat and scrolls; that the transcript keeps its top and some height; that the card ends above the composer, and the composer inside Chat and the window; that the last run's stages are reached by scrolling the card; and that the newest message is clear of it. It fails without the new rule (906px against a limit of 289px).
  • A long Chat and four runs, on desktop and phone. At the transcript's end, the scroll area, newest message and scrollbar end above the card, with 16px clear for the fade, as runs unfold, all show and fold again. This passes on main for the geometry; the 16px check is new.

• Unit tests:

  • build-notices.test.ts: opened once per pull request, finished, stopped, didn't start, rebuild.
  • build-model.test.ts: buildRun.
  • run-card.test.tsx: the row's markup and folding.
  • transcript.test.tsx: pull request links in system lines.

Checks run

• bun run types and bun run ci pass.

• Rebased onto 8cb7e623f, which includes the full-height row shade and the image viewer; the only conflicts were in DESIGN.md's Chat row paragraph, where both changes are kept. The build row is a .run-row > .run-head, so it gets the row-shade change's hairline and shade with no change of its own. Earlier, on 8634eefaf, which includes build-pr-lifecycle: The only conflict was two new describe blocks appended to build-model.test.ts; both are kept. The Chat lines read open pull requests from live.pullRequests, which now lists only open ones, and a rebuild's updates from its commits, so a closed pull request is never named as updated.

• bun test apps/web/src: 1,666 pass. bun test apps/server/src/tasks apps/server/src/agent apps/server/src/plan apps/server/src/chat: 1,873 pass.

• bun run build:

  	Size	Budget
  Initial JavaScript, raw	259,958 B	260,500 B
  Initial JavaScript, gzip	82,481 B	83,450 B
  Initial stylesheet, raw	184,420 B	185,000 B
  Initial stylesheet, gzip	32,675 B	33,000 B

  Initial JavaScript is the same as main. The card's 74 B limit lands in the initial stylesheet with run-card.css.

• Browser specs, --workers=2, after rebasing onto 8634eefaf: implementation-launcher, chat-run-strip, run-card and stopped-build-editing passed 33, with 1 skipped (the opt-in live ACP case). Before that rebase, chat-hover-contrast and chat-phone also passed.

• Before the rebase: build-restart, chat-row-edges, chat-long-transcript, message-toolbar-layout and pane-work also passed, except one test, chat-row-edges "scrolling a long Chat moves only its thumb". It fails on main the same way on this machine: 160 forced layouts from Playwright's own injected script. With that line logged rather than asserted, its other limits hold: 15 dirty objects and 12 restyles, as on main.

• bun run design:behavior: 104 passed and 2 failed under load: connecting-indicator and chat-media (narrow), where the design-audit page didn't load in time. Run alone, connecting-indicator passed, and chat-media passed 14 of 14.

Judgement calls

• Build plan stays the approval; there's no Approve button. The code already treats the press as the approval, and AGENTS.md says "A person's press is the approval". Adding a separate approval would change the product. So the fix is the Planner's words, plus one line on Build's card.
• On a built document, a Planner draft is explained, not refused. Refusing edit_implementation_graph there would be cleaner, but could break a flow I can't see. The Planner is told the draft isn't what Build runs.
• The strip shows only a running build. Once a build ends, its Chat line carries the result; keeping an ended row as well would say it twice.
• The thread panel's strip shows no build. A build belongs to the document, not to a thread.
• No progress bar in the row. Build already shows one. A new one would add CSS to the nearly full initial stylesheet.
• A notice that would be posted twice keeps its first text. If a build's end were recorded before its run's outcome, the ID keeps the first line and the conflict is only logged. In the flows tested, the outcome is recorded first.
• A notice lost in a crash isn't recovered. A crash between persisting a change and posting its line loses that one line. The next process sees the state as already known.