Skip to content

armgit / mso

Public Imported from GitHub
0

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.

feat(settings): explain update refusals, merge Server into Devices (#135)

Abdurrahman Fakhrul3c3195845069
diff --git a/.gitleaksignore b/.gitleaksignore
index 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:15
diff --git a/docs/OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md b/docs/OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md
new file mode 100644
index 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.md
index 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 collateral
diff --git a/frontend/slices/os-settings/components/account-section.tsx b/frontend/slices/os-settings/components/account-section.tsx
index 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.tsx
similarity index 86%
rename from frontend/slices/os-settings/components/server-section.tsx
rename to frontend/slices/os-settings/components/devices-host-card.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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?: (i
case "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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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 (
<SettingsSection
icon={<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() {
<SettingsSection
icon={<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."
>
<UpdateStatusCard
info={info}
@@ -144,7 +152,7 @@ export function UpdateSection() {
finished={finished}
/>
- {behind > 0 && ahead === 0 && info.supported !== false && (
+ {behind > 0 && ahead === 0 && (
<SettingsActionRow
label={
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 && (
<SettingsActionRow
label={
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.ts
index 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" | "pendin
return 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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> {