Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(settings): explain update refusals, merge Server into Devices (#135)
Abdurrahman Fakhrul3c3195845069
diff --git a/.gitleaksignore b/.gitleaksignoreindex 59320227..a24c0d6f 100644--- a/.gitleaksignore+++ b/.gitleaksignore@@ -45,3 +45,7 @@ aff0713f4630404be63127c9ce733baa78d9003c:lib/a2a/client-security.test.ts:generic# Reviewed Agent Vault redaction fixture: deterministic synthetic text in a temporary repo.# No provider credential; keep only the original commit/file/rule/line fingerprint.4c9ea47d97efdd1053ccdf438c319e32e578cd7d:lib/agent-vault/service.test.ts:generic-api-key:57++# Reviewed Orca env fixture: synthetic placeholder string in a test, no live credential+# and no provider request. Present only in history reachable from another open branch.+2b153d9ec2fe55d17799805c9e8284bbef787669:scripts/orca/env.test.mjs:generic-api-key:15diff --git a/docs/OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md b/docs/OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.mdnew file mode 100644index 00000000..a94fd455--- /dev/null+++ b/docs/OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md@@ -0,0 +1,317 @@+# OS Settings: update automation, Devices merge, account icon — plan++Status: **open plan, 2026-10-21. Nothing here is shipped.** Each phase lands as its own+PR and its own gate run. This document is the decision record, not the implementation.++Scope is five owner-facing gaps reported from the live deployment:++1. Auto-update opt-in (checkbox).+2. "Stable only" update channel (no rolling `main`).+3. Devices out of Account, merged with Server into one top-level **Devices** section.+4. Account icon picker (emoji / Lucide / Phosphor) from+ `https://resource.manef.dev/slices/icon-picker`.+5. Uploaded art is converted server-side to WebP + ICO + favicon sizes, with a hard+ input cap, so a 4 MB phone photo never becomes a 4 MB icon.++Prerequisite already done: the missing Update button was **not** a UI bug. The checkout+was on `feat/linear-provider-composio-key-routing`, so+`updateBranchReason()` reported `supported:false` and `update-section.tsx` correctly+rendered zero buttons. Fixed by moving the checkout to `main` and running+`mso update --rebuild`. See "Phase 0" for the durable fix so it cannot recur silently.++---++## Phase 0 — make the "cannot update" state self-explanatory (small, ship first)++Right now a non-`main` checkout produces a page with no action and no explanation. The+reason string exists in `UpdateStatus.reason` but only reaches the section footnote.++Files:++- `frontend/slices/os-settings/components/update-section.tsx` — when+ `info.supported === false`, render `UpdateStatusUnavailable` with the actual+ `info.reason` plus the one-line remedy (`git checkout main`, then rebuild), instead of+ falling through to a footnote. No buttons, but not a dead end either.+- `frontend/slices/os-settings/components/update-status-card.test.ts` (new) — assert the+ unsupported card surfaces the reason text.++Acceptance: opening Settings → About → Updates on the feature branch shows+"software updates require the checkout to be on main (current: …)" and the remedy.++---++## Phase 1 — Devices section: merge Server into it, move it out of Account++Owner decision: **Account should hold identity only** (name, icon, password, sign-out).+Devices and Server belong together because both answer "what machine am I talking to and+who may talk to it".++### Navigation model++| Before | After |+| --- | --- |+| Account → Devices (nested) | **Devices** (top level, group `system`) |+| Server (top level) | folded into **Devices**, no separate section |+| Account → About (nested) | unchanged (nested, stays) |++`frontend/slices/os-settings/lib/sections.ts`:++- `SectionId`: drop `"server"`, keep `"devices"`.+- `CATALOG.devices`: `label: "Devices"`, `blurb: "This server, approved browsers, and auto-lock"`,+ icon `ShieldCheck` (keep) — or `Server` if the merged body leads with the host target.+- `CATALOG.server`: delete.+- `NAV_ORDER`: replace `"server"` with `"devices"` (same position, group `system`).+- `SEARCH_EXTRA`: `devices` gains `"server ssh live mock target host vps approved browser sessions auto-lock"`.+- `settingsNavActive`: keep `account` covering `about` only; drop the `devices` clause.+- `settingsBackTarget`: `about → account`; `devices` returns `null` (it is now top level).++### Body++`frontend/slices/os-settings/components/sections.tsx`, case `"devices"`:++1. Host target card — moved verbatim from `server-section.tsx` (`ServerSection`,+ `addSshTarget`, `selectServerTarget`, `updateServerTarget`, test/connect row).+2. Auto-Lock card — unchanged (`AutoLockRow`).+3. Approved devices card — unchanged (`DevicesPanel`).+4. Delete case `"server"`.++`server-section.tsx` shrinks to the exported pieces the merged body imports, or is+renamed to `devices-host-card.tsx`. Prefer the rename: one section, one file name that+matches the nav.++### Account++`account-section.tsx`: remove the "Also in Account → Devices" row and the footnote that+promises it. Keep About. Blurb becomes `"Name, icon, password, and about"`.++### Redirects++Old deep links must not 404: `?section=server` → `sectionFromSearch` maps to `"devices"`;+`?section=devices` keeps working. Add both to the mapping test.++Tests to update: `frontend/slices/os-settings/lib/sections.test.ts` (nav groups, last+section still `updates`, `settingsBackTarget("devices") === null`, `server` alias),+`about-pages.test.ts` untouched, plus any e2e selector that clicks `Server`.++Acceptance: Settings nav lists `Devices` once, no `Server`; the merged page reaches the+live host, approves/revokes a device, and toggles auto-lock without leaving the section.++---++## Phase 2 — Account icon picker + image pipeline++Two independent halves. Ship the picker first; conversion is a separate PR because it+touches server-side bytes.++### 2a. Icon picker++Owner asked for `https://resource.manef.dev/slices/icon-picker`. That catalog is+installable and self-describing:++```+npx rahman-resources add icon-picker # alias: npx rr add icon-picker+```++It copies `frontend/slices/icon-picker/` into the project and installs+`@phosphor-icons/react` (new dependency; `lucide-react` already present). Stored value+contract is a plain string:++```+emoji:<char> | lucide:<Name> | phosphor:<Name> with optional ?c=<hex>+```++Decision: **adopt the slice, do not hand-roll a picker.** It ships search, recents, tint,+keyboard grid nav and popover→dialog fallback, and an `IconPickerPopover` ++`DynamicIcon` pair. Hand-rolling the same surface is ~3× the code for less behaviour.++Model change in `lib/auth/account-profile-model.ts`:++```ts+export type AccountIcon =+ | { type: "preset"; id: AccountPreset } // existing, kept for old stores+ | { type: "library"; value: string } // NEW: emoji:/lucide:/phosphor:+ | { type: "image"; src: string }; // existing, now always WebP+```++`lib/auth/account-profile.ts` must validate the new `library` value the way it already+validates presets: allow only `^(emoji:[^\\s]{1,8}|lucide:[A-Za-z0-9]+|phosphor:[A-Za-z0-9]+)(\\?c=[0-9a-fA-F]{6})?$`,+cap length (say 96), and reject anything else. This is a trust boundary — the value is+rendered into an SVG-adjacent component.++UI: `account-profile-card.tsx` replaces the 8 fixed preset buttons with+`IconPickerPopover`, keeping the existing upload button beside it. `account-avatar.tsx`+gains a `library` branch that delegates to `DynamicIcon`, and keeps the preset map for+back-compat.++Bundle note: the slice lazy-loads its ~250 Lucide + ~190 Phosphor catalogs behind+`React.lazy`, so pages that never open the picker pay nothing. Verify with+`bun run bundle:check` — the eager shell budget (currently 884.9 KiB raw / 282.5 KiB+gzip) must not move.++### 2b. Upload → WebP + ICO + favicon, with a hard cap++Owner requirement: accept anything a phone produces, but never store or serve a fat+file. Targets below are the decision.++| Output | Size | Format | Consumer |+| --- | --- | --- | --- |+| `icon.webp` | 256×256 | WebP q82 | in-app avatar, About tile |+| `icon-192.png` / `icon-512.png` | 192, 512 | PNG | PWA manifest (WebP is not universally accepted there) |+| `apple-touch-icon.png` | 180×180 | PNG | `app/apple-icon` |+| `favicon.ico` | 16, 32, 48 multi-entry | ICO (PNG-embedded) | browser tab |++Input rules:++- Accept `image/png|jpeg|webp|gif|avif|heic` **and** SVG (rasterize first).+- Hard cap **8 MiB** on the request body; reject earlier at the multipart/JSON layer.+- Decode with `sharp` (already a transitive dependency via Next; it must become an+ explicit `dependencies` entry — relying on Next's optional dep is not a contract).+- `sharp` **cannot write ICO** (`sharp.format` exposes png/webp/jpeg/avif/tiff/gif only,+ verified on this host). Do **not** add a dependency for it: an ICO is a 6-byte header,+ N×16-byte directory entries, then the PNG payloads. ~30 lines, and PNG-embedded ICO is+ readable by every browser that matters.+- Strip metadata (`withMetadata` off, no EXIF), flatten alpha onto the current+ background colour instead of storing transparency where the target needs a square.+- Reject images whose decoded pixel area exceeds ~40 MP before resizing (decompression+ bomb).++Where it lives:++- `lib/auth/account-icon-image.ts` (new) — pure-ish: `decode → normalise → encode` with+ `sharp`, returns `{ webp, png192, png512, apple180, ico }` as Buffers. One runnable+ check behind it (assert-based or one vitest file) proving: EXIF stripped, output is+ WebP (`RIFF....WEBP` magic), ICO directory offsets are correct, oversize input is+ rejected rather than truncated.+- `app/api/auth/account/icon/route.ts` (new, `runtime = "nodejs"`) — owner-only, same+ session gate as `POST /api/auth/account`, body-size capped, returns the stored profile.+- Store the **WebP** in the existing `account.json` (`imageIcon` already caps at 32 KB —+ a 256×256 q82 WebP of a photo lands well under that; keep the cap as a backstop, raise+ it to 48 KB only if a real photo exceeds it).+- Static icon files become dynamic: `app/icon.svg` is a static file today, so a per-owner+ icon cannot reach the tab. Replace with `app/icon.tsx` + `app/apple-icon.tsx` reading+ the stored profile (with the current brand SVG as fallback), so favicon/apple-touch+ follow the owner's upload. `app/manifest.ts` icons point at the same dynamic routes.+ Cache: short `max-age` + revalidate, because these are read on every page load.++Acceptance: upload a 4 MB phone JPEG → tab favicon, in-app avatar, PWA 192/512 and Apple+touch all show the new art; stored `account.json` grows by < 48 KB; no `sharp` output+retains GPS.++---++## Phase 3 — Auto-update checkbox++Owner wants an opt-in "keep this host updated automatically". Design:++**Scheduler = systemd user timer, not cron.** The installer already enables linger and+gives `mso.service` `XDG_RUNTIME_DIR` so the service can reach the per-user manager; the+updater already launches as a transient `--user` unit. Reusing that path means no new+credential surface, no sudo, and the same log the panel already polls.++- `mso-self-update.timer` (user): `OnCalendar=*-*-* 04:30` + `RandomizedDelaySec=25m`,+ `Persistent=true`. Nightly, jittered, catches up after downtime.+- `mso-self-update.service` (user, already exists as transient) gains a persistent unit+ twin so the timer can trigger it without a build-time argument.++**Gate before firing** (reuse, do not reimplement):++- `getUpdateStatus(true)` → refuse when `!supported`, `dirty`, `running`, `ahead > 0`.+- Refuse when a build already failed twice in a row (read the log's `FAILED:` markers) —+ a broken commit must not be retried forever unattended.+- Never auto-apply when `behind > 0` **and** the incoming commits touch the updater itself+ (`lib/host/self-update.ts`, `scripts/mso-service-update`, `scripts/self-update.sh`) —+ that is the one case where an unattended restart can strand the host.++**State** (single source, `lib/prefs/store.ts` `tweaks.updates`, owner-only POST like the+rest of `/api/prefs`):++```ts+updates?: {+ auto: boolean; // default false+ channel: "stable" | "main"; // default "stable"+ lastAttemptAt?: number; // written by the updater, not the client+ lastResult?: "ok" | "failed" | "skipped";+}+```++**CLI parity** (`mso` must reach the same state without a browser):+`mso update --auto on|off`, `mso update --channel stable|main`, `mso update status` prints+the same block. `docs/CLI.md` is generated, so the contract test catches drift.++**UI**: a `SettingsToggleRow` in the Updates card ("Update automatically at night"),+disabled with an explanation when `supported === false` (e.g. feature branch, dirty+checkout). Show `lastAttemptAt` + `lastResult`. Never show "on" when the timer unit is+missing — read the unit's real state, not just the pref.++Acceptance: enabling writes the pref **and** installs+enables the timer; disabling really+removes it. `systemctl --user list-timers` reflects the toggle. A simulated failed build+stops the next run and surfaces "paused after 2 failed builds".++---++## Phase 4 — "Stable only" channel++Today `origin/main` is hard-coded (`lib/host/self-update.ts` comment: "the only knob is a+boolean, and `origin/main` is hard-coded"). Stable needs a second, equally bounded ref.++Decision: **stable = highest semver git tag reachable from `origin/main`**, not a branch.+Tags exist (`v0.2.0`, ancestor of `main`) and `package.json` is at `0.2.23`, so tags have+lagged — Phase 4 starts by deciding whether stable tags are cut per release or the+channel is simply "latest tag, else main". Recommend: keep it honest — if no tag is newer+than the running build, the stable channel reports "already up to date" rather than+silently falling back to rolling `main`.++Implementation sketch:++- `updateBranchReason()` currently hard-requires `main`. Generalise to+ `updateRefReason(branch, channel)`; a stable checkout is still on `main` but the target+ commit is the tag (`git rev-parse <tag>^{commit}`), so the checkout branch rule does not+ need to change.+- `getUpdateStatus` compares `HEAD` against the channel target instead of `origin/main`.+ `behind` = `git rev-list --count HEAD..<target>`; `commits` from `HEAD..<target>`.+- The transient unit needs the ref. Keep the current security property — **no client+ string is ever interpolated into a command** — by passing a fixed enum+ (`--channel=stable|main`) and resolving the tag server-side inside+ `scripts/self-update.sh` with the same allowlist.+- Fast-forward still required: if `HEAD` is not an ancestor of the target tag, refuse+ with "reconcile first" rather than force-checkout.++Acceptance: on `main` with a newer tag, stable channel reports that tag and updates to+it; with no newer tag it reports current even when `main` has moved. Existing+`updateBranchReason` tests keep passing for the `main` channel.++---++## Sequencing and cost++| Phase | PR | Rough size | Risk |+| --- | --- | --- | --- |+| 0 | 1 | ~40 lines + 1 test | none |+| 1 | 1 | nav model + 3 components + tests | medium: touches every Settings entry point |+| 2a | 1 | new dep + model + 2 components | low: lazy-loaded catalog |+| 2b | 1 | new lib + route + dynamic icon routes | medium: server-side bytes, favicon caching |+| 3 | 1 | timer units + pref + CLI + UI | medium: unattended restarts |+| 4 | 1 | updater ref resolution | **high**: this is the code that replaces the running process |++Phase 4 is last on purpose. Phases 0–2 are additive; Phase 3 can strand a host only+through a failed build; Phase 4 can strand it by pointing at the wrong commit.++## Explicit non-goals++- No separate "Server" section kept for muscle memory — the merge is the requirement.+- No client-side image conversion as the source of truth. Canvas can pre-shrink to save+ upload time, but the server re-encodes and is the only thing that decides what is+ stored, because the client is untrusted.+- No ICO npm package.+- No automatic update on the `main` channel by default, and no auto-update at all while+ the checkout is off `main`.+- No per-device icons. The icon is the owner account's identity.++## Known environment issue found while doing this++`umask` on this host is `0002`, so `git worktree add` creates `0775` directories and+`pinSecurityStorePath()` refuses them as group-writable. `bun run verify` therefore fails+3 tests locally while passing in CI (`umask 0022`). Workaround used for this PR: run the+gate under `umask 022`. Proper fix (separate PR): `fs.chmod(workspacePath, 0o755)` right+after `prepareProjectWorktree()` or a test-level `umask` set, so a local gate run is+trustworthy.diff --git a/docs/README.md b/docs/README.mdindex 355fa460..dd1bb5fb 100644--- a/docs/README.md+++ b/docs/README.md@@ -114,6 +114,7 @@ source comments. They are **not current implementation contracts**.| [`AUDIT-2026-06-11.md`](./AUDIT-2026-06-11.md) | Archived audit at its named date; later fixes changed many findings || [`SHELL-FIDELITY-PLAN.md`](./SHELL-FIDELITY-PLAN.md) | Historical design backlog/baseline; current shell design lives in code + architecture || [`DRAWER-MENU-BYOK-PLAN.md`](./DRAWER-MENU-BYOK-PLAN.md) | Historical implementation plan; phases A–C and OpenAI Codex D1 shipped; remaining ideas are not promises |+| [`OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md`](./OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md) | **Open plan, not implemented**: auto-update opt-in, stable channel, Devices/Server merge, account icon picker, upload→WebP/ICO pipeline |## Marketing/demo collateraldiff --git a/frontend/slices/os-settings/components/account-section.tsx b/frontend/slices/os-settings/components/account-section.tsxindex 87c7c389..d2229858 100644--- a/frontend/slices/os-settings/components/account-section.tsx+++ b/frontend/slices/os-settings/components/account-section.tsx@@ -15,8 +15,7 @@ export function AccountSection({ onOpen }: { onOpen: (id: SectionId) => void })<div className="space-y-4 sm:space-y-5"><AccountProfileCard status={status} role={role} /><AccountPasswordCard status={status} role={role} />- <SettingsSection icon={<ShieldCheck />} title="Also in Account" footnote="Devices and About live here. They are not separate Settings sections.">- <SettingsActionRow label="Devices" onClick={() => onOpen("devices")} trailing={<ChevronRight className="size-4" aria-hidden />} />+ <SettingsSection icon={<ShieldCheck />} title="Also in Account" footnote="About lives here. Devices and Server are their own section."><SettingsActionRow label="About" onClick={() => { setPage("overview"); onOpen("about"); }} trailing={<ChevronRight className="size-4" aria-hidden />} /></SettingsSection></div>diff --git a/frontend/slices/os-settings/components/server-section.tsx b/frontend/slices/os-settings/components/devices-host-card.tsxsimilarity index 86%rename from frontend/slices/os-settings/components/server-section.tsxrename to frontend/slices/os-settings/components/devices-host-card.tsxindex 62e8d0ea..3357a6e1 100644--- a/frontend/slices/os-settings/components/server-section.tsx+++ b/frontend/slices/os-settings/components/devices-host-card.tsx@@ -11,10 +11,10 @@ import {updateServerTarget,useAppearance,type ServerTarget,- type SshServerTarget,} from "@/lib/appearance";-import { useOsApi, ResponsiveDialog } from "@/features/appshell";-import { useSession, LoginCard } from "@/features/auth";+import { isSsh, kindLabel, targetSubtitle } from "../lib/host-target-label";+import { useOsApi } from "@/features/appshell";+import { useSession } from "@/features/auth";import { IS_DEMO } from "@/lib/demo";import {SettingsSection,@@ -22,30 +22,16 @@ import {SettingsValueRow,SettingsActionRow,} from "@/features/shell-settings";+import { DevicesSignInDialog } from "./devices-sign-in-dialog";import { StatusChip, type TestState } from "./status-chip";function targetIcon(target: ServerTarget) {return target.kind === "ssh" ? <Laptop className="size-4" /> : <Server className="size-4" />;}-function targetSubtitle(target: ServerTarget): string {- if (target.kind === "mock") return "Safe demo data; no host access.";- if (target.kind === "local") return "Same-origin MSO host API on this VPS.";- return target.host ? `SSH over Tailscale: ${target.user ? `${target.user}@` : ""}${target.host}` : "Configure a Tailscale SSH host.";-}--// Friendly kind label — never the raw enum ("ssh"/"mock").-function kindLabel(target: ServerTarget): string {- if (target.kind === "local") return "Live";- if (target.kind === "mock") return "Mock";- return "SSH — not connected";-}--function isSsh(target: ServerTarget): target is SshServerTarget {- return target.kind === "ssh";-}--export function ServerSection() {+/** Host target, session and connection test — the "which machine am I talking to"+ * half of the merged Devices section. Rendered inside Devices, never on its own. */+export function DevicesHostCard() {const { tweaks, setServer } = useAppearance();const { status, refresh, signOut } = useSession();const api = useOsApi();@@ -212,14 +198,11 @@ export function ServerSection() {</SettingsSection>)}- <ResponsiveDialog open={loginFor !== null} onOpenChange={(o) => { if (!o) setLoginFor(null); }} size="sm">- <ResponsiveDialog.Header>- <ResponsiveDialog.Title>Sign in</ResponsiveDialog.Title>- </ResponsiveDialog.Header>- <ResponsiveDialog.Body>- <LoginCard onAuthed={onLoginSuccess} />- </ResponsiveDialog.Body>- </ResponsiveDialog>+ <DevicesSignInDialog+ open={loginFor !== null}+ onOpenChange={(o) => { if (!o) setLoginFor(null); }}+ onAuthed={onLoginSuccess}+ /></div>);}diff --git a/frontend/slices/os-settings/components/devices-sign-in-dialog.tsx b/frontend/slices/os-settings/components/devices-sign-in-dialog.tsxnew file mode 100644index 00000000..b9cefde2--- /dev/null+++ b/frontend/slices/os-settings/components/devices-sign-in-dialog.tsx@@ -0,0 +1,27 @@+"use client";++import { ResponsiveDialog } from "@/features/appshell";+import { LoginCard } from "@/features/auth";++/** Sign-in prompt used by the Devices host card when a live/SSH target is selected+ * while signed out. Split out of devices-host-card.tsx for the 220-line cap. */+export function DevicesSignInDialog({+ open,+ onOpenChange,+ onAuthed,+}: {+ open: boolean;+ onOpenChange: (open: boolean) => void;+ onAuthed: () => void | Promise<void>;+}) {+ return (+ <ResponsiveDialog open={open} onOpenChange={onOpenChange} size="sm">+ <ResponsiveDialog.Header>+ <ResponsiveDialog.Title>Sign in</ResponsiveDialog.Title>+ </ResponsiveDialog.Header>+ <ResponsiveDialog.Body>+ <LoginCard onAuthed={onAuthed} />+ </ResponsiveDialog.Body>+ </ResponsiveDialog>+ );+}diff --git a/frontend/slices/os-settings/components/sections.tsx b/frontend/slices/os-settings/components/sections.tsxindex 3920bcd8..53f0678e 100644--- a/frontend/slices/os-settings/components/sections.tsx+++ b/frontend/slices/os-settings/components/sections.tsx@@ -26,7 +26,7 @@ const CleanupSection = dynamic(() => import("./cleanup-section").then((module) =const McpSection = dynamic(() => import("./mcp-section").then((module) => module.McpSection), { loading: loadingSection });const MemorySection = dynamic(() => import("./memory-section").then((module) => module.MemorySection), { loading: loadingSection });const QuicklinksSection = dynamic(() => import("./quicklinks-section").then((module) => module.QuicklinksSection), { loading: loadingSection });-const ServerSection = dynamic(() => import("./server-section").then((module) => module.ServerSection), { loading: loadingSection });+const DevicesHostCard = dynamic(() => import("./devices-host-card").then((module) => module.DevicesHostCard), { loading: loadingSection });const ThemeSection = dynamic(() => import("./theme-section").then((module) => module.ThemeSection), { loading: loadingSection });const UpdateSection = dynamic(() => import("./update-section").then((module) => module.UpdateSection), { loading: loadingSection });@@ -89,6 +89,10 @@ export function SettingsSectionBody({ id, onOpen }: { id: SectionId; onOpen?: (icase "devices":return (<div className="space-y-4 sm:space-y-5">+ {/* Which machine am I talking to, then who may talk to it. One section+ because both answer the same question — the Server section used to be+ separate and duplicated the sign-in/session vocabulary. */}+ <DevicesHostCard /><SettingsSection icon={<Lock />} title="Auto-Lock"><AutoLockRow /></SettingsSection>@@ -103,8 +107,6 @@ export function SettingsSectionBody({ id, onOpen }: { id: SectionId; onOpen?: (i</SettingsSection></div>);- case "server":- return <ServerSection />;case "cleanup":return <CleanupSection />;case "backup":diff --git a/frontend/slices/os-settings/components/update-notes-drawer.tsx b/frontend/slices/os-settings/components/update-notes-drawer.tsxnew file mode 100644index 00000000..cd91da97--- /dev/null+++ b/frontend/slices/os-settings/components/update-notes-drawer.tsx@@ -0,0 +1,40 @@+"use client";++import { Button } from "@/components/ui/button";+import { FormDrawer } from "@/features/appshell";+import type { UpdateCommit } from "@/lib/host/self-update";+import { UpdateNotes } from "./update-notes";++/** Release-notes drawer for the Updates section. Split out of update-section.tsx to+ * keep that file inside the 220-line architecture cap. */+export function UpdateNotesDrawer({+ open,+ onOpenChange,+ behind,+ commits,+}: {+ open: boolean;+ onOpenChange: (open: boolean) => void;+ behind: number;+ commits: UpdateCommit[];+}) {+ return (+ <FormDrawer open={open} onOpenChange={onOpenChange} size="lg">+ <FormDrawer.Header>+ <FormDrawer.Title>+ {behind > 0 ? `What's in this update (${behind})` : "Release notes"}+ </FormDrawer.Title>+ <FormDrawer.Description>+ Incoming commits first, then everything already shipped to this+ deployment.+ </FormDrawer.Description>+ </FormDrawer.Header>+ <UpdateNotes commits={commits} />+ <FormDrawer.Footer>+ <Button type="button" variant="ghost" onClick={() => onOpenChange(false)}>+ Close+ </Button>+ </FormDrawer.Footer>+ </FormDrawer>+ );+}diff --git a/frontend/slices/os-settings/components/update-refusal.test.ts b/frontend/slices/os-settings/components/update-refusal.test.tsnew file mode 100644index 00000000..9172cd88--- /dev/null+++ b/frontend/slices/os-settings/components/update-refusal.test.ts@@ -0,0 +1,60 @@+import { describe, expect, it } from "vitest";+import { readFileSync } from "node:fs";+import { join } from "node:path";+import { hasAvailableUpdate, REFUSAL_COMMANDS, updateRefusalRemedy } from "./update-status-client";++const dir = __dirname;+const section = readFileSync(join(dir, "update-section.tsx"), "utf8");+const card = readFileSync(join(dir, "update-status-unsupported.tsx"), "utf8");++describe("update refusal surface", () => {+ it("maps each actionable host refusal to its own remedy", () => {+ expect(updateRefusalRemedy("software updates require the checkout to be on main (current: feat/x)")).toBe("branch");+ expect(updateRefusalRemedy("the checkout has uncommitted changes — commit or stash them on the host first")).toBe("dirty");+ });++ it("does not invent a remedy it cannot deliver", () => {+ // No git checkout / no service unit: a shell command would be a lie.+ expect(updateRefusalRemedy("this deployment is not a git checkout, so there is nothing to pull")).toBeNull();+ expect(updateRefusalRemedy("mso.service has no automatic restart policy; refusing to stop the running process during self-update")).toBeNull();+ expect(updateRefusalRemedy(null)).toBeNull();+ expect(updateRefusalRemedy(undefined)).toBeNull();+ });++ it("keeps every remedy command read-only about the update itself", () => {+ for (const command of Object.values(REFUSAL_COMMANDS)) {+ // The update is the one fixed verb; the checkout is never rewritten in place.+ expect(command).toContain("mso update --rebuild");+ // No force, no hard reset, no untracked deletion.+ expect(command).not.toContain("--force");+ expect(command).not.toContain("reset --hard");+ expect(command).not.toContain("clean -");+ }+ // The branch remedy names the exact target branch; the dirty remedy must not+ // silently switch branches under uncommitted work.+ expect(REFUSAL_COMMANDS.branch).toContain("git checkout main");+ expect(REFUSAL_COMMANDS.dirty).not.toContain("git checkout");+ expect(REFUSAL_COMMANDS.dirty).toContain("git stash");+ });++ it("renders the reason instead of an empty panel when unsupported", () => {+ // The regression this guards: `supported:false` used to fall through to the+ // status card with zero action rows, which reads as a missing button.+ expect(section).toContain("info.supported === false");+ expect(section).toContain("UpdateStatusUnsupported");+ expect(card).toContain("Software updates are unavailable on this checkout");+ expect(card).toContain("REFUSAL_COMMANDS[remedy]");+ });++ it("still hides the update action while the host refuses", () => {+ expect(section).toContain('behind > 0 && ahead === 0 && (');+ expect(section).toContain('behind === 0 && (');+ });++ it("keeps the badge signal tied to real remote knowledge", () => {+ expect(hasAvailableUpdate({ behind: 0, pendingBuild: false, remoteChecked: false })).toBe(false);+ expect(hasAvailableUpdate({ behind: 3, pendingBuild: false, remoteChecked: false })).toBe(false);+ expect(hasAvailableUpdate({ behind: 3, pendingBuild: false, remoteChecked: true })).toBe(true);+ expect(hasAvailableUpdate({ behind: 0, pendingBuild: true, remoteChecked: false })).toBe(true);+ });+});diff --git a/frontend/slices/os-settings/components/update-section.tsx b/frontend/slices/os-settings/components/update-section.tsxindex f679fe7c..8cfb1f3f 100644--- a/frontend/slices/os-settings/components/update-section.tsx+++ b/frontend/slices/os-settings/components/update-section.tsx@@ -2,13 +2,12 @@import { useCallback, useEffect, useRef, useState } from "react";import { ArrowDownToLine, BookOpen, RefreshCw, Search } from "lucide-react";-import { Button } from "@/components/ui/button";-import { FormDrawer } from "@/features/appshell";import { SettingsActionRow, SettingsSection } from "@/features/shell-settings";import { IS_DEMO } from "@/lib/demo";import type { UpdateStatus } from "@/lib/host/self-update";-import { UpdateNotes } from "./update-notes";+import { UpdateNotesDrawer } from "./update-notes-drawer";import { UpdateStatusCard, UpdateStatusSkeleton, UpdateStatusUnavailable } from "./update-status-card";+import { UpdateStatusUnsupported } from "./update-status-unsupported";import { readStatus } from "./update-status-client";const POLL_MS = 3_000;@@ -92,29 +91,42 @@ export function UpdateSection() {};if (IS_DEMO) return null;- if (!info && !checking) {+ const retry = () => {+ setChecking(true);+ void refresh(true).finally(() => setChecking(false));+ };++ if (!info) {return (- <SettingsSection icon={<ArrowDownToLine />} title="Software update">- <UpdateStatusUnavailable error={error} onRetry={() => {- setChecking(true);- void refresh(true).finally(() => setChecking(false));- }} />+ <SettingsSection+ icon={<ArrowDownToLine />}+ title="Software update"+ footnote={checking ? "Checking the running build, checkout and update service." : undefined}+ >+ {checking ? <UpdateStatusSkeleton /> : <UpdateStatusUnavailable error={error} onRetry={retry} />}</SettingsSection>);}- if (!info && checking) {++ // A refusal is not an empty page. The host says exactly why this checkout+ // cannot update itself (wrong branch, dirty tree, no service unit); showing+ // the status card with zero actions made that look like a missing button.+ if (info.supported === false) {return (<SettingsSectionicon={<ArrowDownToLine />}title="Software update"- footnote="Checking the running build, checkout and update service."+ footnote="This host can still update from a terminal: mso update">- <UpdateStatusSkeleton />+ <UpdateStatusUnsupported+ reason={info.reason ?? "This deployment cannot update itself."}+ info={info}+ onRetry={retry}+ /></SettingsSection>);}- if (!info) return null;const ahead = info.ahead ?? 0;const behind = info.behind ?? 0;const running = info.running ?? false;@@ -130,11 +142,7 @@ export function UpdateSection() {<SettingsSectionicon={<ArrowDownToLine />}title="Software update"- footnote={- info.supported === false- ? (info.reason ?? undefined)- : "Pulls origin/main, verifies compile and mandatory browser journeys out-of-tree, then builds and restarts. The running build is not replaced until those checks pass."- }+ footnote="Pulls origin/main, verifies compile and mandatory browser journeys out-of-tree, then builds and restarts. The running build is not replaced until those checks pass."><UpdateStatusCardinfo={info}@@ -144,7 +152,7 @@ export function UpdateSection() {finished={finished}/>- {behind > 0 && ahead === 0 && info.supported !== false && (+ {behind > 0 && ahead === 0 && (<SettingsActionRowlabel={running@@ -176,13 +184,10 @@ export function UpdateSection() {label="Check again"icon={<Search />}busy={checking}- onClick={() => {- setChecking(true);- void refresh(true).finally(() => setChecking(false));- }}+ onClick={retry}/>)}- {info.supported !== false && behind === 0 && (+ {behind === 0 && (<SettingsActionRowlabel={pending@@ -196,23 +201,12 @@ export function UpdateSection() {/>)}- <FormDrawer open={notes} onOpenChange={setNotes} size="lg">- <FormDrawer.Header>- <FormDrawer.Title>- {behind > 0 ? `What's in this update (${behind})` : "Release notes"}- </FormDrawer.Title>- <FormDrawer.Description>- Incoming commits first, then everything already shipped to this- deployment.- </FormDrawer.Description>- </FormDrawer.Header>- <UpdateNotes commits={info.commits ?? []} />- <FormDrawer.Footer>- <Button type="button" variant="ghost" onClick={() => setNotes(false)}>- Close- </Button>- </FormDrawer.Footer>- </FormDrawer>+ <UpdateNotesDrawer+ open={notes}+ onOpenChange={setNotes}+ behind={behind}+ commits={info.commits ?? []}+ /></SettingsSection>);}diff --git a/frontend/slices/os-settings/components/update-status-client.ts b/frontend/slices/os-settings/components/update-status-client.tsindex df5cfc66..a47e134b 100644--- a/frontend/slices/os-settings/components/update-status-client.ts+++ b/frontend/slices/os-settings/components/update-status-client.ts@@ -16,3 +16,17 @@ export function hasAvailableUpdate(status: Pick<UpdateStatus, "behind" | "pendinreturn status.pendingBuild === true || (status.remoteChecked === true && status.behind > 0);}+/** Which host-side remedy the refusal text points at, or `null` when the operator+ * cannot fix it from a shell either (no git checkout, no service unit). */+export function updateRefusalRemedy(reason: string | null | undefined): "branch" | "dirty" | null {+ const text = reason ?? "";+ if (text.includes("on main")) return "branch";+ if (text.includes("uncommitted changes")) return "dirty";+ return null;+}++export const REFUSAL_COMMANDS: Record<"branch" | "dirty", string> = {+ branch: "cd /path/to/mso\ngit checkout main\ngit pull --ff-only origin main\nmso update --rebuild",+ dirty: "cd /path/to/mso\ngit status\ngit stash # or commit\ngit pull --ff-only origin main\nmso update --rebuild",+};+diff --git a/frontend/slices/os-settings/components/update-status-unsupported.tsx b/frontend/slices/os-settings/components/update-status-unsupported.tsxnew file mode 100644index 00000000..ac89a9a1--- /dev/null+++ b/frontend/slices/os-settings/components/update-status-unsupported.tsx@@ -0,0 +1,46 @@+"use client";++import { Button } from "@/components/ui/button";+import { SettingsBlock } from "@/features/shell-settings";+import type { UpdateStatus } from "@/lib/host/self-update";+import { REFUSAL_COMMANDS, updateRefusalRemedy } from "./update-status-client";++/**+ * The refusal panel. Shown instead of the normal status card when the host says+ * it cannot update itself — a wrong branch, a dirty checkout, no service unit.+ *+ * This used to render the ordinary card with zero action rows, which reads as a+ * missing button. The reason is now the headline and, when a shell can fix it,+ * the exact commands are printed.+ */+export function UpdateStatusUnsupported({+ reason,+ info,+ onRetry,+}: {+ reason: string;+ info: UpdateStatus;+ onRetry: () => void;+}) {+ // The remedy is decided by the reason, not by a generic "try again". Only two+ // refusals are actionable from a shell, so only those print commands.+ const remedy = updateRefusalRemedy(reason);+ return (+ <SettingsBlock className="space-y-3 p-4">+ <p role="alert" className="text-sm font-medium text-destructive-text">+ Software updates are unavailable on this checkout+ </p>+ <p className="text-[11px] leading-relaxed text-muted-foreground">{reason}</p>+ <p className="font-mono text-[11px] text-muted-foreground">+ Running {info.buildSha || "unknown"} · Checkout {info.current || "unknown"}+ </p>+ {remedy && (+ <div className="space-y-1.5 rounded-md border border-border/60 bg-secondary/40 p-2.5">+ <p className="text-[11px] font-medium text-foreground">Fix on the host, then reload this page:</p>+ <pre className="overflow-x-auto font-mono text-[11px] leading-relaxed text-muted-foreground">{REFUSAL_COMMANDS[remedy]}</pre>+ </div>+ )}+ <Button type="button" variant="outline" onClick={onRetry}>Check again</Button>+ </SettingsBlock>+ );+}diff --git a/frontend/slices/os-settings/lib/host-target-label.ts b/frontend/slices/os-settings/lib/host-target-label.tsnew file mode 100644index 00000000..1d424baf--- /dev/null+++ b/frontend/slices/os-settings/lib/host-target-label.ts@@ -0,0 +1,23 @@+import type { ServerTarget, SshServerTarget } from "@/lib/appearance";++/** Pure presentation helpers for the Devices host card. Kept out of the component+ * so that file stays inside the 220-line architecture cap. */++export function targetSubtitle(target: ServerTarget): string {+ if (target.kind === "mock") return "Safe demo data; no host access.";+ if (target.kind === "local") return "Same-origin MSO host API on this VPS.";+ return target.host+ ? `SSH over Tailscale: ${target.user ? `${target.user}@` : ""}${target.host}`+ : "Configure a Tailscale SSH host.";+}++/** Friendly kind label — never the raw enum ("ssh"/"mock"). */+export function kindLabel(target: ServerTarget): string {+ if (target.kind === "local") return "Live";+ if (target.kind === "mock") return "Mock";+ return "SSH — not connected";+}++export function isSsh(target: ServerTarget): target is SshServerTarget {+ return target.kind === "ssh";+}diff --git a/frontend/slices/os-settings/lib/sections.test.ts b/frontend/slices/os-settings/lib/sections.test.tsindex 44882311..f72614fa 100644--- a/frontend/slices/os-settings/lib/sections.test.ts+++ b/frontend/slices/os-settings/lib/sections.test.ts@@ -5,32 +5,43 @@ describe("settings section model", () => {it("filters metadata without depending on a renderer", () => {expect(filterSettingsSections("chatgpt").map((x) => x.id)).toEqual(["mcp"]);expect(filterSettingsSections("wallpaper").map((x) => x.id)).toEqual(["appearance"]);- expect(filterSettingsSections("devices").map((x) => x.id)).toEqual(["account"]);+ expect(filterSettingsSections("devices").map((x) => x.id)).toEqual(["devices"]);expect(filterSettingsSections("system info").map((x) => x.id)).toEqual(["account"]);expect(filterSettingsSections("version").map((x) => x.id)).toEqual(["updates"]);expect(filterSettingsSections("updates").map((x) => x.id)).toEqual(["updates"]);});- it("groups Account with personalization, keeps Devices/About nested, and places Update MSO last", () => {- expect(SECTIONS.map((section) => section.id)).not.toContain("devices");+ it("lists Devices as its own system section and keeps no Server section", () => {+ expect(SECTIONS.map((section) => section.id)).toContain("devices");+ expect(SECTIONS.map((section) => section.id)).not.toContain("server");expect(SECTIONS.map((section) => section.id)).not.toContain("about");expect(groupSettingsSections().map((group) => group.map((x) => x.id))).toEqual([["account", "appearance", "theme"],["ai", "quicklinks", "mcp", "a2a"],- ["server", "cleanup", "backup", "updates"],+ ["devices", "cleanup", "backup", "updates"],]);expect(SECTIONS.at(-1)?.id).toBe("updates");});- it("opens Devices and About from Account, including old deep links", () => {+ it("folds the old Server section into Devices", () => {+ expect(settingsSection("devices")).toMatchObject({ label: "Devices", blurb: "This server, approved browsers, and auto-lock" });+ // Old deep link and old search vocabulary must keep resolving.+ expect(sectionFromSearch("server")).toBe("devices");+ expect(sectionFromSearch("devices")).toBe("devices");+ expect(filterSettingsSections("ssh").map((x) => x.id)).toEqual(["devices"]);+ expect(filterSettingsSections("server").map((x) => x.id)).toEqual(["devices"]);+ });++ it("keeps About nested inside Account", () => {expect(settingsSection("account")).toMatchObject({ label: "Account" });expect(settingsSection("about")).toMatchObject({ label: "About", blurb: "System info and reset" });- expect(settingsSection("devices").label).toBe("Devices");- expect(sectionFromSearch("devices")).toBe("devices");expect(sectionFromSearch("about")).toBe("about");expect(settingsNavActive("account", "about")).toBe(true);- expect(settingsNavActive("server", "about")).toBe(false);- expect(settingsBackTarget("devices")).toBe("account");+ expect(settingsNavActive("account", "devices")).toBe(false);+ expect(settingsNavActive("devices", "devices")).toBe(true);+ expect(settingsBackTarget("about")).toBe("account");+ // Devices is top level now, so it has no back target.+ expect(settingsBackTarget("devices")).toBeNull();expect(settingsBackTarget("appearance")).toBeNull();});});diff --git a/frontend/slices/os-settings/lib/sections.ts b/frontend/slices/os-settings/lib/sections.tsindex 80388150..bade0e78 100644--- a/frontend/slices/os-settings/lib/sections.ts+++ b/frontend/slices/os-settings/lib/sections.ts@@ -7,7 +7,6 @@ import {Paintbrush,Palette,Plug,- Server,ShieldCheck,Sparkles,Trash2,@@ -24,7 +23,6 @@ export type SectionId =| "mcp"| "a2a"| "devices"- | "server"| "cleanup"| "backup"| "updates"@@ -45,7 +43,7 @@ type SectionFields = Omit<SettingsSectionMeta, "id">;const CATALOG: Record<SectionId, SectionFields> = {account: {label: "Account",- blurb: "Name, icon, password, devices, and about",+ blurb: "Name, icon, password, and about",icon: UserRound,color: "var(--primary)",group: "personalization",@@ -94,18 +92,11 @@ const CATALOG: Record<SectionId, SectionFields> = {},devices: {label: "Devices",- blurb: "Approved browsers and sessions",+ blurb: "This server, approved browsers, and auto-lock",icon: ShieldCheck,color: "var(--primary)",group: "system",},- server: {- label: "Server",- blurb: "Mock or live host data",- icon: Server,- color: "var(--primary)",- group: "system",- },cleanup: {label: "Cleanup",blurb: "Free disk space safely",@@ -144,22 +135,29 @@ const NAV_ORDER: readonly SectionId[] = ["quicklinks","mcp","a2a",- "server",+ "devices","cleanup","backup","updates",];const SEARCH_EXTRA: Partial<Record<SectionId, string>> = {- account: "devices approved browsers sessions about system info reset rename password icon",+ account: "name icon rename password about system info reset",+ devices: "server ssh live mock target host vps approved browsers sessions auto-lock sign in",updates: "version versions update updates software release new build latest",};+/** Old deep links that must keep working after sections merge or move. */+const SECTION_ALIASES: Readonly<Record<string, SectionId>> = {+ server: "devices",+ // `about` stays a nested Account page, but the bare link still resolves.+};+function meta(id: SectionId): SettingsSectionMeta {return { id, ...CATALOG[id] };}-/** Top-level Settings navigation. Devices and About are opened from Account. */+/** Top-level Settings navigation. About stays nested inside Account. */export const SECTIONS: ReadonlyArray<SettingsSectionMeta> = NAV_ORDER.map(meta);export function settingsSection(id: SectionId): SettingsSectionMeta {@@ -167,16 +165,17 @@ export function settingsSection(id: SectionId): SettingsSectionMeta {}export function sectionFromSearch(value: string | null): SectionId | undefined {- if (value === "devices" || value === "about") return value;- return SECTIONS.find((section) => section.id === value)?.id;+ if (value === "about") return value;+ const resolved = value ? (SECTION_ALIASES[value] ?? value) : null;+ return SECTIONS.find((section) => section.id === resolved)?.id;}export function settingsNavActive(id: SectionId, active: SectionId): boolean {- return id === active || (id === "account" && (active === "devices" || active === "about"));+ return id === active || (id === "account" && active === "about");}export function settingsBackTarget(active: SectionId): SectionId | null {- return active === "devices" || active === "about" ? "account" : null;+ return active === "about" ? "account" : null;}export function filterSettingsSections(query: string): ReadonlyArray<SettingsSectionMeta> {