Variants: a branch is a living variant of an app with its own settings, compared side by side #10669

This adds a first slice of variants: a branch can run as its own environment with values of its own, and a board compares them. Two things in the issue are not done: the morning-paper first use, and "Make this main" as a one-click merge. The new tests, the gate, tsc, the design lint, the hollow-code check and the nearby suites passed locally. I did not run the full suite; the forge's check does that on this push.

What changed

• Variants. A writer who is a person registers a branch on an app, with a 1–16 character label that defaults from the branch name. It runs at <slug>--v-<label> with a copy of production's data. An app keeps at most 6. A new app_variant table records which branches are variants, and the migration is pinned.
• Per-branch values. A variant's values live in variant.json on its branch, for example {"values":{"PRINT":"true"}}. They go over the app's environment variables of the same name. Names must look like environment variables and may not start with FORGE_ or be a name the forge sets. A file that is present but wrong starts the variant with no values. Saving from the app page commits the file to the branch, and the variant restarts with it. Secrets stay in the app's environment settings and never go in the file.
• Variant board. /<owner>/<name>/variants, linked from the app page, shows each variant's state, values, preview link and last output. The page shows the live-preview count and the account's limit. It lists which variants are running, but not what each one counts as in that total. Writers get the register, save-values, retire and make-main controls.
• Last output. An app tells the board what it last made by writing last-output.json ({"title","path"}) into its own FORGE_APP_DATA. The forge reads it as bounded data only.
• Lifetime. Reconciles keep variants and a push to the branch redeploys them. They sleep on production's schedule instead of a preview's 30 minutes. They count as live previews against the account's previews limit.
• Reserved names. Slugs of the form v-<label> can no longer be created, as b<sha7> already is.
• Code and docs. The new code is src/actions/app_variants.ts, src/core/variants.ts, src/apps/variant_file.ts and src/web/pages/app_variants.ts, plus hooks in src/apps/runtime.ts. The how-to is in docs/features/variants.md.
• Tests. test/app-variants.test.ts runs two real variants. Only the one with PRINT=true reports PRINT=true. It also covers a reader, an agent and a missing branch changing nothing, values saved to the branch, a variant surviving a reconcile, and retiring.

What I chose not to do

• "Make this main" opens, or returns, the ordinary pull from the branch to the default branch, and a person merges it there with its checks. I did not add a direct merge, because agents and unchecked branches must not skip the pull gate.
• Morning-paper first use is not done. That app lives in its own repository and needs a variant.json per branch and a last-output.json write. The contract is in the docs.
• No terminal into a variant. parseAppLogin does not accept variant logins.
• Other limits. Retire does not ask for confirmation. A secret kept forge-side is overridden by a same-named value in the file. The variant limit is per app, not per account.
• Plan item. I did not keep the plan on the issue, because the keep_plan tool is not available in this run.

Try it: on this pull's preview, open /<owner>/<name>/variants for an app and run a branch as a variant. Save PRINT=true as its values, then open its preview.

🤖 Generated with Claude Code

Closes #10550

This adds a first slice of variants: a branch can run as its own environment with values of its own, and a board compares them. Two things in the issue are not done: the morning-paper first use, and "Make this main" as a one-click merge. The new tests, the gate, tsc, the design lint, the hollow-code check and the nearby suites passed locally. I did not run the full suite; the forge's check does that on this push.

What changed

• Variants. A writer who is a person registers a branch on an app, with a 1–16 character label that defaults from the branch name. It runs at <slug>--v-<label> with a copy of production's data. An app keeps at most 6. A new app_variant table records which branches are variants, and the migration is pinned.
• Per-branch values. A variant's values live in variant.json on its branch, for example {"values":{"PRINT":"true"}}. They go over the app's environment variables of the same name. Names must look like environment variables and may not start with FORGE_ or be a name the forge sets. A file that is present but wrong starts the variant with no values. Saving from the app page commits the file to the branch, and the variant restarts with it. Secrets stay in the app's environment settings and never go in the file.
• Variant board. /<owner>/<name>/variants, linked from the app page, shows each variant's state, values, preview link and last output. The page shows the live-preview count and the account's limit. It lists which variants are running, but not what each one counts as in that total. Writers get the register, save-values, retire and make-main controls.
• Last output. An app tells the board what it last made by writing last-output.json ({"title","path"}) into its own FORGE_APP_DATA. The forge reads it as bounded data only.
• Lifetime. Reconciles keep variants and a push to the branch redeploys them. They sleep on production's schedule instead of a preview's 30 minutes. They count as live previews against the account's previews limit.
• Reserved names. Slugs of the form v-<label> can no longer be created, as b<sha7> already is.
• Code and docs. The new code is src/actions/app_variants.ts, src/core/variants.ts, src/apps/variant_file.ts and src/web/pages/app_variants.ts, plus hooks in src/apps/runtime.ts. The how-to is in docs/features/variants.md.
• Tests. test/app-variants.test.ts runs two real variants. Only the one with PRINT=true reports PRINT=true. It also covers a reader, an agent and a missing branch changing nothing, values saved to the branch, a variant surviving a reconcile, and retiring.

What I chose not to do

• "Make this main" opens, or returns, the ordinary pull from the branch to the default branch, and a person merges it there with its checks. I did not add a direct merge, because agents and unchecked branches must not skip the pull gate.
• Morning-paper first use is not done. That app lives in its own repository and needs a variant.json per branch and a last-output.json write. The contract is in the docs.
• No terminal into a variant. parseAppLogin does not accept variant logins.
• Other limits. Retire does not ask for confirmation. A secret kept forge-side is overridden by a same-named value in the file. The variant limit is per app, not per account.
• Plan item. I did not keep the plan on the issue, because the keep_plan tool is not available in this run.

Try it: on this pull's preview, open /<owner>/<name>/variants for an app and run a branch as a variant. Save PRINT=true as its values, then open its preview.

🤖 Generated with Claude Code

I fixed the two failing checks and pushed. Locally the four test files I reran pass (server-timing-sweep, attention, app-variants, fresh-app), tsc is clean, and gate.ts printed nothing. I didn't rerun the full suite; the forge's check does that on this push.

• Server-Timing sweep: the variants board answered "not found" without naming render in Server-Timing. Both not-found paths in variantBoardPage (src/web/pages/app_variants.ts) now run inside the render phase. The session phase was already named.
• First-view budget: the new Variants link on the app page added 2 words, taking repository and app from 116 to 118 against a budget of 116. I dropped the (n) count and the · separator, so the link adds 1 word. I raised the repository and app word budgets to 117 in docs/design/attention-budget.json, at both widths. That one word is the cost of the new entry point.
• Side effect: the "Environment settings" link still shows only to admins, but the Variants link now shows to everyone who sees the page.

I left the budget file raised rather than hiding the link behind "only when variants exist", because then a repo with none would have no way to reach the board.

Findings 1–5 are fixed and pushed on the same branch. The new and touched tests, tsc, gate.ts and design-lint.ts pass locally. I ran about 240 related tests, not the whole suite, because fast.ts named 2046 files. The forge runs the full check on this push.

1. Agent push (HIGH). A push to a variant's branch now redeploys only when the pusher is a person who can write (pusherMayRunVariant in src/apps/runtime.ts). Agents, readers and pushes with no actor wait; the log line is "variant waits for a person who can write". Contribution forks were already refused by mayRun, and "Save values" deploys directly for the writer who clicked it. A test pushes as an agent, a reader and nobody (nothing deploys), then as a writer (it deploys).
2. Symlink. readVariantValues now uses lstat and reads only a regular file. A test points variant.json at a host file and gets no values.
3. Legacy slug. resolveAppHostname now lets an app already slugged v-<label> keep its host, in its parent's world, ahead of the variant reading. A test covers both that host and a real variant host.
4. Terminal. src/tui/screens/variants.ts is a palette command ("Variants") on a repository that is an app, registered in workspace.ts next to the variables screen.

- Who sees what: anyone who can read sees the list. A person who can write gets the controls; an agent does not. - Keys: r registers a branch, s sets a value, u drops one, x retires after a confirm, and m makes it main. They use the same actions and refusal words as the page. - Tests: test/tui-variants.test.ts covers a reader, an agent, a missing branch, set and drop, retire declined and confirmed, and make main.

1. Design.

- Layout: variants are a listCard of row()s, with facts as rows and one action row (Open preview, Make this main, Retire). The values form sits in a disclosure under it. - Accent: "Run as variant" is the only primary button. - Copy: there is one intro sentence, and the repeated hints and the flash text are shortened. - Retire confirm: Retire on the page goes through /-/confirm; I added a retire entry to the DESTRUCTIVE list in search.ts. That covers part of finding 6.

Not done, from finding 6:

• Secret override: a variant.json value can still override a same-named sealed app secret. I left it for a follow-up that decides between rejecting and warning.
• /app/<env>/open: I did not check that it accepts variant envs or that to= stays on the app's origin.

docs/features/variants.md now describes the terminal door and the push rule. To try it, register a branch on the variants page, push to it as an agent, and see that it does not redeploy.

I fixed the failing check and pushed. The cause was a race in the test, not a bug in the screen.

test/tui-variants.test.ts read the terminal screen right after the keys went in. Setting a variant value commits to the branch, which takes longer than the screen's settle step waits. So the test read the screen before the "PRINT is set for print." note had appeared. The values did get saved.

The test's drive helper now takes an optional note to wait for, polling for up to about 3 seconds. The set step waits for "PRINT is set for print." and the drop step waits for "PRINT is dropped from print.". No source file changed.

test/tui-variants.test.ts passed 6 of 6 on three runs in a row, and bun x tsc --noEmit is clean. I didn't run the full suite or bun scripts/gate.ts (the forge's check runs the full suite on the push).

I didn't add a wait to the failed-value step (PORT=1). That step shows its refusal inside the open prompt without committing, so it doesn't race.