Edit the workspace's critical apps through previews, the careful flow, and a kept rollback point

[gnguralnick]

The template side of editing the workspace's critical apps (docs/system/blueprint/critical-app-editing/plan-critical-app-editing.md), all six phases on one branch. The paired mngr PR is imbue-ai/mngr-internal#877 (the observe read side and the follower's start-without-a-writer mode); system/vendor/mngr is refreshed from it, and that PR lands first.

Before: every edit to the shell went through the update-system-interface skill, and no other critical app (the chat, the terminal) had a safe path at all: the chat spawned its own mngr observe (a shed or restarted observer froze its agent view for good), a preview existed only for the shell, and an apply that turned out bad had nothing kept to go back to once it exited 0.

Now:

• agent-observer in system/supervisord.conf runs the workspace's one mngr observe --quiet, in the chat's memory band (SERVICE_BANDS 24, just below the chat: shedding it blinds every chat's agent view at once while freeing almost nothing). The chat follows its event file through mngr's ObserveEventFollower, reports the outage in /api/health's agent_events (status stays ok), and chat-app --secondary boots a second chat beside the live one for previews -- same observer and live accounts, but it reconciles nothing, writes no memory scores, opens no windows, registers nothing, and refuses an account switch with a 400 (it would write the chat's record only into a scratch copy the live chat never reads). CHAT_DATA_DIR names the chat's data directory so a secondary's writes stay out of it.
• Every app's app.toml can carry a [preview] table (PreviewSpec: command, named ports, copied directories, env and args with {port:}/{copy:}/{scratch}/{registry}/{host} placeholders, health and open paths; a default is scaffolded per name, and build-app writes it into every new app). update-app's preview_app.py up --app <name> --worktree <dir> [--with <sibling>] boots any app from it as the labeled <name>-preview tab, siblings first, over copies of its data, with refresh re-booting in place after a rebuild and down tearing the whole set down. One preview per app: another worktree's live preview is refused rather than hijacked, and a sibling re-upped or taken down on its own is written into every live preview's registry copy so the framing preview follows without a re-up.
• serve_isolated_instance.py gains named ports, copies, placeholders, and --inner-path, and carries the old live-editing branch's work forward: refresh --name re-boots the inner server on its existing port, down escalates SIGTERM to SIGKILL and keeps the state (exiting non-zero) for a survivor, a failed boot quotes the log since the last boot marker and the health response and copies the log aside, and both processes launch through oom_tag_service.py user. The health probe reads the route's own verdict, so a 200 whose JSON says is_frontend_built is false is not up. A preview now puts one app in the launcher, not two: the labeled frame registers as the app, the inner service registers --internal.
• system-interface --preview and terminal-app --no-register are the read-only boots. The preview shell runs the real desktop over a seeded state copy and a copied registry; everything that edits that copy or reaches its own windows stays live, and only an app's stop and start and the update notice's verbs are refused with a 403. terminal-app/terminal-pty --no-register serve without re-pointing the live rows, appending a discovery event, or running the window sweep.
• update-app routes by manifest: critical = true (or a workspace_ui change) follows the new references/critical-app.md, the careful flow that replaces update-system-interface (deleted with reveal_system_interface.py): one lease, an isolated worktree, the live loop through the preview (each round closes the preview's window before editing and re-opens it when the round is ready), a harden worker on the lead's branch, and the apply with both bundles and --keep-rollback-point.
• update_self.py apply --keep-rollback-point keeps its snapshots and writes data/.state/update-apply/last-good.json (what it landed, the copies, the critical apps and programs it touched); rollback-last forward-reverts, restores, restarts exactly those programs (or names the services-agent restart when the diff reached the workspace's own setup) and waits for a settled verdict now shared with the apply; confirm-last discards. A rollback holds a lock for its whole run, so a double press starts one script; a restore it cannot complete reports incomplete recovery, keeps the copies, and writes emergency state rather than letting later health checks read as success.
• The shell raises that record as a notice only a person closes: a band in every tab of a touched app and a banner for the shell, with "Roll back" (asks first) and "Everything seems good", progress and outcome pushed over the socket as update_notice_changed, the verbs on /api/updates/pending/{confirm,rollback} (refused in a preview shell). An unknown path under /api/ now answers a JSON 404 rather than the app shell.
• forward_port.py --display-name <label> gives a manifest-less row the label users read instead of the raw service name; like --internal and --program every call is authoritative, and a label the shell would reject on read is refused at registration. agent joins the reserved app names, since an app by that name would claim agent-observer as its sidecar.
• launch-task's create_worker.py launch/launch-sync take --branch <spec>, so a worker can extend a branch the lead already built up (what the careful flow's harden worker uses). launch-sync reads the worker's branch back from mngr ls --format json's initial_branch -- the mngr PR's widening -- rather than assuming mngr/<name>, and destroy's unmerged-work warning counts commits on that recorded branch.

Validation: the automated suites (update-self apply and rollback tests over a fixture tree, the chat's follower tests against a real mngr observe, the shell's route and watch tests, the frontend vitest, and one release e2e test that raises the band from a seeded record over stub apps and confirms it away). docs/system/blueprint/critical-app-editing/test-plan.md is the hand-run plan; its manual scenario in a real workspace has not been run, and that is recorded as owed in the spec.

Deviations from the spec, recorded there: the observer's band is 24 (bands must be distinct and ordered), preview_app.py runs under uv run python3 because it imports app_manifest, a rollback's outcome lives in the notice's own record rather than the apply's run record, CHAT_DATA_DIR moves only the message stamps (chat instances are in memory), and the wait_settled verdict is one function over every program rather than the shell alone. The shell's direct-subprocess ratchet admits one use: the rollback is launched detached in its own session, since supervisord stops the shell's program as a group and the rollback restarts it.

🤖 Generated with Claude Code

[joshalbrecht]

lgtm I guess -- it's a little weird how aware the apps are of being previews, but that doesn't seem TOO crazy...

it feels a little smelly, but I'm ok trying it out for now (can't think of a better way off the top of my head that doesn't involve considerably more complexity than we want right now)

long term it's probably about putting previews in containers or something like that