[Improve] Always-on live previews with setup in the preview pane

[mrubens]

What

Live previews no longer have an enabled/disabled state. Preview availability is now simply: preview runtime config is ready AND the environment defines ports. The task page's preview pane is always accessible and hosts the whole setup experience, including launching an agent (admins) to get previews working.

Removed the enabled/disabled notion

• Controller publishes environment ports whenever the preview runtime config resolves as ready; the deployment metadata read and the previews_enabled !== false term are gone (apps/controller/src/utils.ts).
• Deleted the previews_enabled deployment-control helpers from @roomote/feature-flags and stopped seeding previews_enabled: false for new deployments.
• The per-environment previews_enabled field is deprecated, ignored, and removed from the public docs. It stays parseable so stored configs remain valid, and the setup agent removes it from configs when it encounters it.
• Chat thread footers now include preview links for environments that previously had the flag off.

Preview pane is always accessible

• The Live Preview sidebar button is always clickable for environment-backed runs. Without a preview URL it opens a setup state instead of being disabled; the command palette entry behaves the same. Repo-only tasks (including environment setup tasks) hide the button entirely, since there is no app to preview. Bare /task/[id]/previews is now routable.
• New PreviewSetupState covers: repo-only tasks reached via direct URL, an in-flight setup agent (links to it), runtime not configured (admins get the origin/DNS/validation setup inline; non-admins see "ask an administrator" with no infra details), environment without ports (agent CTA + manual link for admins, "ask an administrator" for members), and runs that predate ports (sleep/wake attaches a preview, which snapshot restore genuinely does).

Broken-preview help flow

• A "Preview not working?" help button in the pane header, plus a dismissible warning banner when the proxy-injected widget never reports a successful load within the existing retry window (the app may still be visible, some apps block the widget, so this is a soft warning rather than an error state).
• The banner is environment-setup-aware via the run's environmentSetupState (mirrored from the workspace .roomote/setup-status.json): while setup is still running it shows a calm "services are still starting" notice instead of a warning; when setup finishes without a load, the retry window resets and the iframe reloads; when setup failed or completed with warnings, the timeout warning says so.
• Both open a help dialog: admins can launch a repair agent targeting proxied-preview failure modes (host/allowed-hosts checks, loopback-only binding, hardcoded localhost origins, CORS, X-Frame-Options / frame-ancestors, websocket/HMR bypass); members see ask-an-administrator copy.
• The repair agent can actually fix and verify: unlike configure mode, it does not invoke the $environment-setup skill (which prohibits app source changes). Its standalone brief reproduces the failure through the sandbox's own public preview origin (ROOMOTE_<PORT>_HOST), fixes environment-definition problems via the manage_environments MCP action, fixes app-level blockers as code changes with a PR, restarts the affected service, and re-verifies through the preview origin before declaring success. Workflow and payload markers are unchanged, so dedup and agent classification still apply.

Agent kickoff (admin-only)

• New previewSettings.startSetupTask mutation (admin-gated server-side) derives the environment from the task and launches an $environment-setup task with a preview-focused change request; a mode: 'configure' | 'repair' input picks between the add-ports prompt and the diagnose-broken-preview prompt, and reuses the environment verification advisory lock so repeat clicks return the in-flight task instead of launching duplicates.
• Preview setup/repair tasks run inside the target environment (payload environmentId, like verification tasks) so the agent validates the actually-running services. That also makes them distinguishable from the initial repo-only environment-creation task: taskStatus classifies the active agent as 'preview' vs 'environment', and the pane/help dialog say "this environment is still being set up" during initial setup instead of wrongly claiming a preview agent is running.
• New non-admin-safe previewSettings.taskStatus query (no DNS probe, matches the controller gate exactly) drives the pane.

Settings page deleted

• Settings → Live Previews (nav item, page, component) is removed; the admin runtime-config blocks moved into the pane (apps/web/src/components/previews/PreviewRuntimeSetup.tsx). /settings/previews redirects to environment settings for old bookmarks.
• Docs updated: apps/docs, SELF_HOSTING.md, and the coolify/fly/railway/render deploy READMEs.

Notes

• Setup agent launch is admin-only for now, consistent with the rest of environment management; members see ask-an-administrator copy. Opening it up later is a one-line gate change plus button copy.
• Rollback (N-1) safety: no migrations, stored previews_enabled metadata/config keys are never rewritten, and the new release never writes the key. Rolling back restores the old gate against unchanged data.

Testing

• pnpm lint, pnpm check-types, pnpm knip all pass.
• Updated controller/feature-flags/types/slack tests for the new gate; added real-database tests for taskStatus, startSetupTask dedup, and the non-admin rejection; component tests cover the setup-state matrix for both admins and members.
• Verified against a running dev stack that the app compiles and serves with the new pane wired in.

[roomote-roomote]

1 issue outstanding; no new code issues found in the latest update. See task

• High: Keep preview setup/repair tasks from being discoverable by members (apps/web/src/trpc/commands/preview-settings/index.ts:620-642). Returning setupTask.taskId: null removes the links from the preview pane, but these tasks are still enqueued with the default visible visibility. Members can select “Any User” on the Tasks page, then open the task because task-by-ID has no initiator/admin restriction; that response includes the full prompt payload and embedded environment YAML. Enqueue these tasks as hidden while preserving the admin-only direct link, sanitize the task payload, or enforce authorization on task reads.
• Medium: Dispatch repair requests through a workflow that can actually change application code (packages/types/src/environment-definition-tasks.ts:103). The new prompt tells the agent to make minimal source changes for app-level CORS, framing, host, and origin failures, but startPreviewSetupTaskCommand explicitly launches $environment-setup; that workflow prohibits application/source changes (packages/cloud-agents/src/server/workflows/skills/standard/environment-setup/SKILL.md:78) and requires reporting them as blockers (SKILL.md:152). As a result, the “Fix previews with an agent” action cannot repair several advertised failure modes. Use a standard implementation workflow for repair mode, or narrow the CTA and prompt to environment-definition-only fixes.

_{Reviewed afc3f31}

[mrubens]

Addressed both review findings in ed1e354:

• High (agent task links exposed to members): taskStatus now returns setupTask.taskId: null for non-admin viewers, and both the setup state and the help dialog render the task link only when the id is present. Members still see accurate progress messaging (kind + status), just without a link into a task whose description embeds the environment YAML.
• Medium (repair prompt vs environment-setup scope): took the narrow-the-prompt option. The repair change request now instructs the agent to fix only what the environment definition can express and to report required application-code changes (files + changes) as the blocker outcome, matching the skill's constraints. The help dialog copy says the same. Making repair mode code-capable via a standard workflow is a possible follow-up, but it needs its own dedup/authorization design.

[mrubens]

Update on the Medium finding: rather than permanently narrowing repair scope, a1f8358 makes repair mode a standalone coding-task brief that skips the $environment-setup skill entirely (configure mode still uses it). The repair agent reproduces the failure through its sandbox's public preview origin, fixes environment-definition problems via manage_environments action: "update", fixes app-level blockers (framing headers, CORS, allowed hosts) as code changes with a PR, restarts the affected service, and re-verifies through the preview origin before declaring success. Workflow and payload markers are unchanged, so the active-agent dedup and preview/environment classification are unaffected.