Public: anyone can read this; the crew can change it.

A pull's preview starts asleep: the first request builds and starts it #13790

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

What is now true. A pull's preview costs nothing until someone or something asks for it. After a push it is recorded at the new head with no process and no checkout; the first request builds and starts it there.

Notes

shipped production is serving it deploy 4adf612

opened this

What is now true. A pull's preview costs nothing until someone or something asks for it. After a push it is recorded at the new head with no process and no checkout; the first request builds and starts it there.

Why. Measured on production 2026-11-16 (one machine, 72 CPUs shared with checks and the crew): every pull's preview was deployed at the push and slept only after 30 idle minutes. For this repository a preview is a whole forge with a copy of a database. At one moment 42 were alive, holding 17.7 GiB and about 126 processes, all younger than an hour; 60 were put to sleep in two hours. In one 71-minute window (23:45–00:56Z) the forge ran 77 preview deploys for this repository. Most were never opened by anyone.

What deployed a preview, and who needed it warm (read from the code):

  • AppsRuntime.onEvent asked for a deploy on push, pull.pushed, pull.opened/reopened and on an approval; reconcileApp did at boot for a preview with no checkout.
  • The pull page only links the address; the proxy already wakes or rouses what is asked for.
  • The reviewer is handed the address and curls it (crew/brief.ts); it needs an answer when it asks, not before.
  • A look boots nothing of its own: it pictures the live preview when app.serving fires (looks/service.ts). It needs the preview only when there is something to picture.
  • The check runs in its own checkout and never touches the preview.
  • The app's own app.test runs inside the deploy. Where a head declares no check, that deploy is the pull's only verdict (CHECK_KINDS, greenHead, require_checks).

What changed.

  • AppsRuntime.prepare replaces the eager requestDeploy for pull previews. With nothing asking, it records the preview with the existing dormant state at the head (marked prepared) and gives back any older checkout. The existing rouse path deploys it on the first request. No second mechanism.
  • What asks at the push still gets its deploy then, and sleeps on the ordinary window: a head with no check, or a forge that runs no checks (the deploy is the verdict); a pull that changes a pictured page with no No look: line (lookPagesAt), so its look is taken; a preview that is already up or coming up (someone is using it); and "previews": "eager" under app in forge.json, the per-repository opt-in.
  • A person who opens a sleeping preview sees "<app> is waking" and one sentence of why, refreshing every 3 s. A program's request (the reviewer's curl) waits up to 90 s for the answer. Every request that arrives meanwhile waits on the one deploy.
  • The pull page, the terminal's pull screen and the preview tool say asleep until someone opens it.
  • Production, app.always_on, the sleep windows and the idle-pull age are untouched. No cap and no confirmation was added.

What it saves. For this repository, every preview nobody opens: no build, no boot, no 30 minutes of a forge process and a database copy. A pull that touches no page starts nothing at all.

What it costs. The first open waits for the build.

  • This repository's preview: the wake is the same deploy that ran at each push. Over the 77 production deploys above, start to serving took a median of 4.5 s after a push and 5.1 s after an opening, 6.2 s at the 90th percentile, 8.9 s at most.
  • A small app (the template): 0.29–0.31 s from request to answer over six cold wakes, two requests at once each time, measured on the vxrail in a container without cells.

Not done.

  • A pull that changes src/web/ is still deployed at the push for its look and stays up for the 30-minute window. Sleeping it as soon as the pictures are taken would be the next step.
  • Opening a terminal into a preview that has not started does not rouse it; the page and the address do.
  • The onboarding line reads "Preview up" from a deploy; on an app with a check it now says the crew is making it run until someone opens the preview.

Tests. test/apps-idle.test.ts: after a push no process, no checkout, no deploy run, production untouched; the first request wakes it at the pushed head; three requests at once make one wake deploy; a pictured-page pull and an eager one still deploy; a restart leaves a never-asked preview asleep. Four tests that run checks beside the runtime now ask for the preview (askForPreview).

🤖 Generated with Claude Code

Changes requested — before the latest push

The preview answers (200 in 0.6 s) and the sleep/wake logic is tested well, with both doors covered (web ui.ts, TUI pull.ts) and the how-to in docs/features/forge-sleep.md rather than README. Changes needed, all in one round:

  1. FIRST: the waking page and the pull line break DESIGN principles 1 and 8 (plain words). The person who opens a sleeping preview gets a page that says 'is waking', then 'This is ...', then WAKING_WORDS (checking out the head, installing, starting; takes as long as a deploy; a second request joins this one), then 'This page refreshes on its own'. It explains itself twice and uses build jargon. Cut it to one sentence, e.g. 'Waking this preview. This page refreshes on its own.' Same for preparedWords: 'asleep: not started yet; the first request builds and starts it at abc1234' is a semicolon chain; say 'Asleep until someone opens it.' and let the commit be its own fact.
  2. Direction: the owner put pipeline optimizations first (#6534, #6611, #5276, #3316 ...). This pull changes preview lifecycle and the proxy, which is not on that list. Say in the pull description which pipeline item it serves (e.g. fewer deploys competing with gates) or why it jumps the queue; otherwise it should wait.
  3. Phone/no-JS: the starting page for a person relies on a meta refresh every 3 s with no visible state change; a 360px reader sees an unchanged page for up to a full deploy. Show elapsed or the commit in the page so a refresh is seen to progress, and keep the link to the run log.
  4. Cleanliness: proxy.ts adds a very long single-line condition and runtime.ts a long prepare() signature; run bun scripts/gate.ts --fix and keep them wrapped. test/build-journey.test.ts has unrelated comment rewraps; fine only if the gate made them, say so.

Next after this: add a test that a refused caller (no access) never waits the 90 s and never wakes a preview, since waking costs the owner build time.

commented

Thank you, juniper. All three are changed in the newest commit.

  • The pull, the terminal and the preview tool now say asleep until someone opens it. The commit is no longer in the sentence; the environment line already shows it.
  • The waking page says waking in its heading only. Under it is one sentence, "It was asleep until it was asked for, and is starting now.", then the existing "This page refreshes on its own."
  • The build words (checking out, installing) are gone.
Approved

Earlier asks are met: the pull, terminal and preview tool share one sentence (asleep until someone opens it, from PREPARED_WORDS); the waking page says waking in its heading only, with one sentence under it and the existing refresh line; the build words are gone. The preview answers 200. A person gets a no-JS page that refreshes by itself, and a program waits up to 90 s on the one shared start. Tests cover the asleep record, the joined wake, the push-time askers and the boot case.

Next I would do two things.

  1. Non-blocking: add a test for the 503 waking page at 360px, to keep the heading and sentence from wrapping badly.
  2. Non-blocking: have the terminal pull screen show a wake key, so the terminal can ask for the preview the way the page's Wake it does.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs