dsh-home-hosted 0.6.1 → 0.6.3

package/README.md

@@ -114,6 +114,13 @@ A tool that changes something asks for approval **only** when the session is not
 When the process cannot elevate, the page prints the exact commands instead — including the
 `launchd-daemon` that starts a Mac **before** login.
 
+A boot entry runs the panel as the person who installed it: the account comes from the login that
+elevated (`SUDO_UID`) or from the panel root's owner, not from `$USER`.
+<sub>An entry with no account to name runs the panel as root — that is the default, and the page
+says so rather than hiding it. A `User=` systemd cannot resolve is refused too, because it makes
+the unit fail to start. Moving an install from root to a user later needs
+`chown -R <user> <home>`.</sub>
+
 </details>
 
 <details>

package/docs/DESIGN.md

@@ -21,14 +21,18 @@ always wins — that is an instruction, not a preference.
 
 The range is stated twice and both must agree: `dependencies['home-hosted']` in
 `package.json` (what gets installed) and `EXPECTED_RANGE` in
-`src/home-hosted/resolve.ts` (what the page offers to install globally and warns
+`src/home-hosted/resolve.ts` (what the page offers to install globally, and warns
 about when a global copy is older). Bumping one alone makes the page recommend a
-range the plugin is not actually built against.
+range the plugin is not built against. A bump is therefore those two plus the
+version-coupled tests — *unless* the release moved something this plugin names: a
+path under `.hh`, `CONFIG_SCHEMA`, `serverSchema`, `/api/settings`, or a CLI
+subcommand. 0.7.2 (the panel's reverse proxy, all of it under `.hh/.proxy/`) moved
+none of them.
 
 That copy resolves to a pnpm path carrying a version and a peer hash
 (`…/.pnpm/home-hosted@0.6.1_zod@4.6.5/node_modules/home-hosted/…`), which moves
-on the next install and disappears when the profile is rebuilt. A boot entry
-that baked it in would fail exactly when it matters.
+on the next install and disappears when the profile is rebuilt. A boot entry that
+baked it in would fail exactly when it matters.
 
 So the boot entry runs a generated launcher in the plugin state directory
 (`bin/home-hosted.mjs`, rewritten on every plugin start). At boot the launcher
@@ -42,25 +46,23 @@ launcher the way the unit invokes it and shows the version it answers.
 The panel starts `dsh web` from a server row, so a boot entry never runs dsh
 itself. That row points at a second generated launcher (`bin/dsh.mjs`), and the
 launcher has to answer "which dsh" without the plugin running. A local build is
-the obvious case and the one that broke: a user ran a source checkout while
-sharing the global `~/.dsh`, and the panel started a *different* global dsh that
-shared the same data directory and crashed on the version mismatch. Choosing by
-highest version, with the recorded path only as a tie-breaker, is what allowed
-that: an unrelated install that reports a bigger number won.
+the case that broke: a user ran a source checkout while sharing the global
+`~/.dsh`, and the panel started a *different* global dsh on the same data
+directory, which crashed on the version mismatch. Choosing by highest version,
+with the recorded path only as a tie-breaker, is what allowed that.
 
 So the record (`bin/dsh-resolved.json`) carries `pinned` — the image this plugin
 was installed on — and the launcher checks it before any version sort. A pin is
-carried, never guessed: only a caller that *is* the running image adopts a new
-one (`repin`), so an upgrade that lands elsewhere is adopted but a copy found on
-PATH never displaces the pin. A build whose path is genuinely gone falls back to
-its recorded roots, then to real dsh installs, then to a bare build file, and
-only then to PATH.
+carried, never guessed: only a caller that *is* the running image adopts a new one
+(`repin`), so an upgrade that lands elsewhere is adopted but a copy found on PATH
+never displaces the pin. A build whose path is gone falls back to its recorded
+roots, then to real dsh installs, then to a bare build file, and only then PATH.
 
 Candidates are ordered by how they were found, not just by version: a dsh by
 construction (a manifest, `node_modules/dsh`, a pnpm store) beats a root that
-merely offers `lib/bin.js` (a clone), which beats a `dsh` on PATH. A clone has
-no manifest, so it is found by that build-file name — a guess that must never
-outrank a real install.
+merely offers `lib/bin.js` (a clone), which beats a `dsh` on PATH — a clone has no
+manifest, so it is found by that build-file name, a guess that must never outrank
+a real install.
 
 The row's stored command is repaired while the plugin runs (`launcherRepair`),
 including a row that names a bare `dsh`: PATH is exactly what pointed at the copy
@@ -70,85 +72,82 @@ adopted row that deliberately runs a different absolute dsh is left alone.
 ### A project that depends on dsh keeps it, by name
 
 The launcher is the fallback, not the common case. `home-hosted` resolves a bare
-command itself (`resolveCommand(command, cwd, projectDir)` in its process
-provider) by checking `node_modules/.bin/<command>` under the row's cwd and then
-its own project directory, and only then PATH. So a row whose project installed
-dsh as a dependency is written as a bare `dsh` with that project as its cwd: it
-runs the copy the project's own lockfile chose, through the shim its own package
-manager wrote, with nothing absolute to move when the project or the store does.
-
-That is also why this plugin never shells out to a package manager for it:
-`npx dsh` falls back to the registry and to a global when the local bin is
-missing, `pnpm dsh` needs pnpm on the boot PATH, and `nlx --local` would add a
-global tool to a boot path for a lookup the panel already performs. The launcher
-is still what a row gets when a bare name would *not* reach the pinned image —
-a clone run without its own `.bin`, or a global-only machine.
+command itself (`resolveCommand(command, cwd, projectDir)`) by checking
+`node_modules/.bin/<command>` under the row's cwd and then its own project
+directory, and only then PATH. So a row whose project installed dsh as a
+dependency is written as a bare `dsh` with that project as its cwd: it runs the
+copy the project's lockfile chose, through the shim its package manager wrote,
+with nothing absolute to move.
+
+That is also why this plugin never shells out to a package manager for it: `npx
+dsh` falls back to the registry and to a global when the local bin is missing,
+`pnpm dsh` needs pnpm on the boot PATH, and `nlx --local` would add a global tool
+to a boot path for a lookup the panel already performs. The launcher is what a row
+gets when a bare name would *not* reach the pinned image — a clone run without its
+own `.bin`, or a global-only machine.
 
 ## One panel root and one boot artifact per state root
 
 Two dsh installs share `~/.dsh` far more often than they should, and each one
 installing this plugin used to mean two plugins editing one panel's state and one
-autostart unit under one ownership marker — so the second install quietly
-replaced the first's boot entry. A panel root is now derived per instance: an
-explicit `$HHOSTED_HOME` still wins, and a panel already living at
-`~/.home-hosted` is adopted rather than abandoned (an upgrade must never make
-every server look like it vanished), but otherwise the root is the instance's own
-`<stateDir>/panel`. A root counts when it is a 0.7 one (`.hh/workspaces.json` or
-`.hh/settings.json`), when it is a pre-0.7 one with a `servers.config.json`, or
-when a `run.json` in either layout has a live pid — a killed panel leaves a
-runtime file behind, and adopting on that would point a fresh install at
-somebody's dead root. Adoption is
-also limited to an instance that already exists: the machine's own harness home,
-or a state dir that already holds settings. A scratch `DSH_HOME` or a test
-project must not reach over and drive the panel some other install owns.
-
-The boot artifact name follows the state root too, but keyed on the *machine*
-default: `home-hosted` only for `~/.dsh/dsh-home-hosted`, `home-hosted-<hash>`
-otherwise. Keying it on the running process's own `$DSH_HOME` would name every
-install's default state dir `home-hosted` and reintroduce the collision. An
-install that used to write the old name retires it once its own artifact is in
-place (an upgrade would otherwise autostart the panel twice), and only an
+autostart unit under one ownership marker — so the second install quietly replaced
+the first's boot entry.
+
+A panel root is derived per instance: an explicit `$HHOSTED_HOME` wins, and a
+panel already living at `~/.home-hosted` is adopted rather than abandoned (an
+upgrade must never make every server look like it vanished), but otherwise the
+root is the instance's own `<stateDir>/panel`. A root counts when it is a 0.7 one
+(`.hh/workspaces.json` or `.hh/settings.json`), a pre-0.7 one with a
+`servers.config.json`, or when a `run.json` in either layout has a live pid — a
+killed panel leaves a runtime file behind, and adopting on that would point a
+fresh install at somebody's dead root. Adoption is limited to an instance that
+already exists (the machine's harness home, or a state dir that already holds
+settings): a scratch `DSH_HOME` must not reach over and drive the panel some other
+install owns.
+
+The boot artifact name follows the state root too, keyed on the *machine* default:
+`home-hosted` only for `~/.dsh/dsh-home-hosted`, `home-hosted-<hash>` otherwise.
+Keying it on the running process's `$DSH_HOME` would name every install's default
+state dir `home-hosted` and reintroduce the collision. An install that used to
+write the old name retires it once its own artifact is in place, and only an
 artifact carrying this plugin's marker is ever removed.
 
 ## Agent tools are merged and on by default
 
-Seven tools, not ten: `servers_lifecycle` carries start/stop/restart, `servers_edit`
-carries create/update/delete, `autostart_manage` carries install/uninstall, and
-`ui_manage` drives the panel's own UI (`ui-update` / `ui-revert` / `ui-switch`).
-`workspaces_list` is the read-only way to see every workspace, and every server
-call names its `workspace` explicitly.
-They are registered on by default; what gates a mutating call is the session's
-own permission mode, not a plugin-level default.
+Seven tools, not ten: `servers_lifecycle` carries start/stop/restart,
+`servers_edit` carries create/update/delete, `autostart_manage` carries
+install/uninstall, `ui_manage` drives the panel's own UI (`ui-update` /
+`ui-revert` / `ui-switch`), and `workspaces_list` is the read-only way to see
+every workspace. They are registered on by default; what gates a mutating call is
+the session's own permission mode, not a plugin-level default.
 
-A description is read at the approval prompt, so each one is a line a person can
+A description is read at the approval prompt, so each is one line a person can
 glance at: what the tool does, and only the consequence they could not predict
 (restarting this session's own entry ends it; installing an entry stops the
 panel). Mechanics — which panel is reached how, which workspace a default means —
-belong in the argument schemas and the docs, not in the sentence somebody has to
-read before saying yes.
+belong in the argument schemas and the docs.
 
-Structured tool parameters are declared as objects, never as `type: 'json'`: an
+Structured parameters are declared as objects, never as `type: 'json'`: an
 author-only `json` node projects to a schema with no `type` at all, and a real
 session then delivers something the handler cannot read — `create`/`update` were
-unusable because of it, while every test passed, since tests call the handler
+unusable because of it while every test passed, since tests call the handler
 directly. A declared object is validated by the runtime before the handler, so a
-wrong shape is rejected with the parameter named and an absent one is reported as
-absent.
+wrong shape is rejected with the parameter named.
 
 ## The dsh entry is the only entry the page manages
 
-The page shows one toggle: manage `dsh` as a home-hosted entry, or not. Adding
-one sends a minimal intent (`{ id: 'dsh', autostart: true }`) and the host fills
-the rest from the platform default policy; removing one restores an entry this
-plugin merely adopted, and deletes one it created. Removing an entry the panel
-supervises stops that process — which may be the session asking for it.
+One toggle: manage `dsh` as a home-hosted entry, or not. Adding one sends a
+minimal intent (`{ id: 'dsh', autostart: true }`) and the host fills the rest from
+the platform default policy; removing one restores an entry this plugin merely
+adopted, and deletes one it created. Removing an entry the panel supervises stops
+that process — which may be the session asking for it.
 
-Deleting on toggle-off is the intended reading of that switch, not an oversight:
-"manage" means the plugin owns the entry, so switching it off gives the entry
-back — removed if this plugin created it, restored if it only adopted one.
-Pausing instead would leave an entry nobody manages. The state that must never
-happen is the third one: a toggle that is on with no entry behind it, which is
-why the entry is recreated from the intent while the switch is on.
+Deleting on toggle-off is the intended reading, not an oversight: "manage" means
+the plugin owns the entry, so switching it off gives the entry back — removed if
+created, restored if adopted. Pausing instead would leave an entry nobody manages.
+The state that must never happen is the third one: a toggle on with no entry
+behind it, which is why the entry is recreated from the intent while the switch is
+on.
 
 The generated entry always binds loopback (`bind: 'local'`, `--host 127.0.0.1`):
 `dsh` rejects `--host 0.0.0.0` as a usage error, so repeating a running harness's
@@ -169,7 +168,12 @@ is passed through untouched rather than fought over. `authNotice` turns it off;
 
 A managed entry asks for `persistent: true`: home-hosted then runs it under its
 nanny, which owns the child and outlives `stopAll()`/`dispose()` — so restarting
-or stopping the *panel* no longer ends a prompt mid-flight.
+or stopping the *panel* no longer ends a prompt mid-flight. Staying up across a
+panel stop is the point, not a side effect: the panel's stop copy says as much,
+and 0.7.2 gives the reverse-proxy engine the same treatment ("`down` leaves it
+serving"). A `systemctl stop` still takes both with it unless the unit carries
+`KillMode=process`, which is why that belongs on every unit this plugin writes —
+see below.
 
 ## Approvals follow the session's sandbox
 
@@ -186,7 +190,7 @@ channel).
 `onPortConflict: kill` arrived in home-hosted 0.6.0 and `persistent` in 0.6.3, and
 an older panel handed either key can refuse to *boot* from the config. The plugin
 used to consult the answering panel's version and refuse or drop them
-(`KILL_UNSUPPORTED`). That is gone on purpose: it pins `home-hosted@^0.7.1` and
+(`KILL_UNSUPPORTED`). That is gone on purpose: it pins `home-hosted@^0.7.2` and
 autostarts its own copy, so a panel older than those keys is only reachable by
 deliberately preferring an old global install — and this is pre-1.0. Supporting
 older panels again means bringing that check back from history, not re-deriving
@@ -224,73 +228,128 @@ its own.
 
 ## Several panels on one machine
 
-`home-hosted` is not one panel per machine: it can be installed per project, and
-one install can run several panels from different `--home` roots. This plugin
-drives exactly one of them — the state root it resolved — so a person with two
-panels used to be indistinguishable from a person with one.
+`home-hosted` can be installed per project, and one install can run several panels
+from different `--home` roots. This plugin drives exactly one of them — the state
+root it resolved — so a person with two panels used to be indistinguishable from a
+person with one.
 
 Discovery is bounded, never a scan of the disk: the managed root (always listed,
-even before its first start), `$HHOSTED_HOME`, the operator's `instanceRoots`,
-and the `~/.home-hosted*` siblings. Another root counts only when it holds a
-0.7 `.hh`, a pre-0.7 `servers.config.json`, or a `run.json` with a live pid. The
-inventory is cached
-(`INSTANCES_CACHE_MS`); the prompt path re-measures a stale cache in place
-(`instancesNow()`), because a provider that only read a snapshot would never
-notice a panel started while this dsh was already running.
+even before its first start), `$HHOSTED_HOME`, the operator's `instanceRoots`, and
+the `~/.home-hosted*` siblings. Another root counts only when it holds a 0.7
+`.hh`, a pre-0.7 `servers.config.json`, or a `run.json` with a live pid. The
+inventory is cached (`INSTANCES_CACHE_MS`); the prompt path re-measures a stale
+cache in place (`instancesNow()`), because a provider that only read a snapshot
+would never notice a panel started while this dsh was already running.
 
 The agent is told rather than left to guess: with more than one panel found, the
-`instancesNotice` setting contributes one runtime-context line naming the managed
-panel and the others (`ctx.systemPrompt.context`, `instances-notice.ts`). Every
-tool also takes an optional `instance` (a state root or URL); a mutating call
-that names none asks the user which panel it means, through `ctx.userQuestions`,
-after the approval gate so a call the session may not make prompts for nothing.
-The question is asked only when a human channel can answer — no answerer, or a
-delegated child — and an unexpected ask failure is refused rather than treated as
-consent, because changing a panel the user never confirmed is the outcome this
-exists to prevent. Its wording is English like every other host-side message: the
-locale service is a browser-side seat, and first-party host plugins ask in English
-too.
-
-The page shows the same inventory under the panel details, including which panel
-hosts this dsh, and the Agent-tools section carries the `instancesNotice` toggle.
-
-A call that names another panel is no dead end. The plugin asks the user how to
-reach it, offering every way that endpoint has, least invasive first:
-
-- `file` edits that panel's workspace config file (`.hh/<workspace>/servers.config.json`,
-  its default workspace unless the call names another) — no credential, but no live
-  status either, and a running panel applies a changed definition at that
-  entry's next start;
-- `cli` runs the home-hosted CLI against its state root — the only runtime path
-  the panel itself offers (`start`/`stop`; a restart is a stop then a start,
-  because the CLI has no server restart);
+`instancesNotice` setting adds one runtime-context line naming the managed panel
+and the others (`ctx.systemPrompt.context`, `instances-notice.ts`). Every tool
+also takes an optional `instance` (a state root or URL); a mutating call that
+names none asks which panel it means, through `ctx.userQuestions`, after the
+approval gate so a call the session may not make prompts for nothing. The question
+is asked only when a human channel can answer — no answerer, or a delegated child
+— and an unexpected ask failure is refused rather than treated as consent, because
+changing a panel the user never confirmed is the outcome this exists to prevent.
+Its wording is English like every other host-side message: the locale service is a
+browser-side seat, and first-party host plugins ask in English too.
+
+A call that names another panel is no dead end. The plugin asks how to reach it,
+offering every way that endpoint has, least invasive first:
+
+- `file` edits that panel's workspace config file
+  (`.hh/<workspace>/servers.config.json`, its default workspace unless the call
+  names another) — no credential, but no live status either, and a running panel
+  applies a changed definition at that entry's next start;
+- `cli` runs the CLI against its state root — the only runtime path the panel
+  itself offers (`start`/`stop`; a restart is a stop then a start, because the CLI
+  has no server restart);
 - `api` mints a token for that panel, enrols it and uses its HTTP API — the only
   way to get live status, and it replaces any token that panel had, which the
   question says outright.
 
-The endpoint's first mechanism is the default when a caller names none, so a
-host that cannot reach a person still does the least invasive thing. A read is
-the one silent upgrade: with a token this plugin already holds for that panel it
-uses the API, because that carries live status and mints nothing. Every such
-result ends by naming the panel and the mechanism it used.
+The endpoint's first mechanism is the default when a caller names none, so a host
+that cannot reach a person still does the least invasive thing. A read is the one
+silent upgrade: with a token this plugin already holds for that panel it uses the
+API, because that carries live status and mints nothing. Every such result ends by
+naming the panel and the mechanism it used.
 
 A config edit reaches a running panel through its file watcher, so a newly added
 `autostart` entry is written disabled and then flipped — the same two-phase add
-the managed path uses.
-
-The credential for another panel lives beside the managed one, under its own slot
-(`panel-tokens/<slot>.token`, 0600), minted on first use of that mechanism and
-never shared with the managed panel's token.
+the managed path uses. The credential for another panel lives beside the managed
+one, under its own slot (`panel-tokens/<slot>.token`, 0600), minted on first use
+of that mechanism and never shared with the managed panel's token.
 
 Machine-wide and self-referential endpoints are the exception: `home_hosted_status`
-describes the panel this plugin manages (its payload already lists the others),
-and the OS boot entry is one entry for that same panel. Those refuse a `home`
-rather than ignoring it, so a caller is never left believing it aimed a boot
-entry at a panel it did not.
-
-The settings stamp moved to 3 for `instancesNotice`, while the tool-name
-migration stays bound to the release that merged the tools: a stamp bump must
-never re-read a current file's explicit two-tool allowlist as "nobody chose".
+describes the panel this plugin manages (its payload already lists the others), and
+the OS boot entry is one entry for that same panel. Those refuse a `home` rather
+than ignoring it, so a caller is never left believing it aimed a boot entry at a
+panel it did not.
+
+The settings stamp moved to 3 for `instancesNotice`, while the tool-name migration
+stays bound to the release that merged the tools: a stamp bump must never re-read
+a current file's explicit two-tool allowlist as "nobody chose".
+
+## Boot entries run the panel as a person
+
+Two mechanisms drop privilege by name — a systemd `User=` and a launchd
+`UserName` — and both used to take that name from `$USER`. That is right in the
+common case and wrong in the one case it exists for: `sudo` and `pkexec` rewrite
+`USER`, `LOGNAME` and `HOME` to the *target* account, so a panel started from a
+root shell read `USER=root`, and a mechanism that already runs as root got an
+entry that either repeated root or, with the name dropped, silently kept it.
+`os.userInfo()` is no help: it reports the euid.
+
+So the account comes from whoever this process is. An elevating tool's
+`SUDO_UID`/`PKEXEC_UID` is an instruction and is used while it resolves, so a stale
+value inherited from an ancestor cannot collapse the entry to root; otherwise this
+session's own login — its database row, else the row for this uid; otherwise the
+owner of the state root or the panel root, which names the person a root-launched
+panel belongs to; and only then, honestly, root. The uid is the fact and `$UID` is
+a claim: a shell variable rather than an exported one, so when it is present at all
+it was inherited. It is read only when the platform gives no uid, and it also feeds
+the launchd domain (`gui/$UID`).
+
+Two answers are refused rather than written, and both fail loudly:
+
+- **`User=root`**, because an entry with no `User=` already runs as root — naming
+  it only dresses up the silent default this change exists to surface;
+- **a name the user database cannot place.** systemd matches names
+  case-sensitively and cannot resolve what it does not know, so `User=<such a
+  name>` makes the unit refuse to start (`status=217/USER`) and `Restart=always`
+  turns that into a crash-loop that never mentions the account. An LDAP or NIS
+  login has no `/etc/passwd` row, so those operators set `User=` themselves; the
+  warning says so.
+
+`HOME` is written into every spec, because `Environment=HOME=` **overrides
+`User=`** — verified on real systemd. So it has to be the account's home: left at
+the installer's it is root's under `sudo`, and the panel would run as the person
+with `~` pointing at `/root`, dying with a permission error that never mentions its
+own user. It is written only when it differs, so an unchanged install stays
+byte-identical and startup `reconcile()` does not rewrite the entry. When an
+account resolves but its home is not knowable, the line is **omitted** instead:
+systemd then supplies the right one from NSS, which leaving root's in place would
+have prevented.
+
+An installed entry that already runs as the wrong account is reported by `status()`,
+and the `enabled-failing` repair heals it by installing again. A *working* entry is
+deliberately left alone: re-installing stops the panel and hands it to the entry,
+which is a person's decision and not a startup side effect.
+
+## KillMode=process: a restart must not take the entries with it
+
+`persistent: true` puts an entry under a nanny the panel spawns, and the nanny is
+what makes it outlive the panel: it owns the child's pipes, so a panel stop,
+restart or kill cannot break them. The nanny is spawned `detached`, which gives it
+its own session — but *not* its own cgroup, and systemd's default
+`KillMode=control-group` signals every process in the unit's cgroup. So a
+`systemctl stop`/`restart` — which is what this plugin's own activation, and any
+`Restart=always`, runs — takes the nanny down with the panel, quietly falsifying
+the guarantee the design depends on. `KillMode=process` signals the panel alone.
+
+An ordinary entry is spawned `detached` too, so the same applies to every
+supervised server and not only the nannies: the panel re-adopts a survivor by its
+port, which is what makes keeping them the right answer rather than a leak.
+It belongs on both units.
 
 ## macOS: agent or daemon
 
@@ -299,8 +358,9 @@ A `LaunchAgent` starts at login; starting before login means a `LaunchDaemon` in
 install. The daemon is therefore offered even when this process cannot elevate:
 install stages the plist and returns the three commands to run. The daemon plist
 names the invoking user in `UserName`, Apple's sanctioned way to avoid running
-the panel as root, and the recommendation still prefers a mechanism this process
-can install on its own so "Automatic" stays a single click.
+the panel as root — resolved by the rule above, never from `$USER`. The
+recommendation still prefers a mechanism this process can install on its own so
+"Automatic" stays a single click.
 
 ## macOS: reachable launchd is not a requirement
 
@@ -342,11 +402,11 @@ So:
 
 ## What the plugin owns
 
-Only `autostart`, `onPortConflict` and `stop.killPortHolders`. Everything else —
-command, args, env, health, restart, labels — is the person's, and a patch never
-touches it.
+Exactly `autostart`, `onPortConflict`, `persistent` and `stop.killPortHolders`
+(`OWNED_ENTRY_KEYS`). Everything else — command, args, env, health, restart,
+labels — is the person's, and a patch never touches it.
 
-Adopting an entry snapshots those three keys first (absence included). Disabling
+Adopting an entry snapshots those keys first (absence included). Disabling
 restores the snapshot; a key the snapshot does not carry is restored to the
 panel's schema default, because a PATCH cannot delete a key. `kill` is the only
 policy that reclaims a port held by a process the panel cannot identify as the
@@ -370,14 +430,13 @@ nothing), and keeps it 0600 in its own state directory. It is never rendered,
 logged, or embedded in a unit file.
 
 Three facts about that CLI are load-bearing, and were read out of its source
-rather than guessed from `--help`: `set-token` replaces whatever hash is there
-(so `--clear` is not needed to overwrite, and is not used — see below),
-`HHOSTED_TOKEN` is the non-interactive input, and every command peels
-`--home <dir>` off before any state module is imported and turns it into
-`HHOSTED_HOME` — which is what makes the secrets file, `run.json` and every
-workspace's config live under the directory this plugin passes, so the plugin and
-the CLI always agree on where state is. A workspace-scoped command (`start`,
-`stop`) also takes `--workspace <id>`.
+rather than guessed from `--help`: `set-token` replaces whatever hash is there (so
+`--clear` is not needed, and is not used), `HHOSTED_TOKEN` is the non-interactive
+input, and every command peels `--home <dir>` off before any state module is
+imported and turns it into `HHOSTED_HOME` — which is what makes the secrets file,
+`run.json` and every workspace's config live under the directory this plugin
+passes, so the plugin and the CLI always agree on where state is. A
+workspace-scoped command (`start`, `stop`) also takes `--workspace <id>`.
 
 The token state the page shows is measured, not assumed. When the panel answers,
 the plugin proves its token with a non-mutating `listServers()`: a refusal is
@@ -465,6 +524,9 @@ Nothing is stopped then — leaving a working panel up beats killing it for an
 entry that would not bring it back. A handover that could not be spawned is
 reported with the exact commands, and the panel is still up.
 
+Enabling and switching differ only in the retirement: a switch already has an
+entry keeping the panel alive, so its plan carries the old mechanism's removal.
+
 ## The panel's UI is changed by the panel's own CLI
 
 `ui.manage` shells out to `ui-switch` / `ui-update` / `ui-revert` rather than
@@ -475,9 +537,6 @@ matches the asset name and verifies the archive — the version logic stays in o
 place instead of being reimplemented against the GitHub API here. `--file` stays
 for a local build, which is the case the CLI cannot cover.
 
-Enabling and switching differ only in the retirement: a switch already has an
-entry keeping the panel alive, so its plan carries the old mechanism's removal.
-
 ## Privilege
 
 Boot scope needs privilege somewhere on every platform: a system unit, or
@@ -491,6 +550,13 @@ as the status moves: a person runs the commands and presses Re-check, and the no
 must not outlive the state it described. The persisted last attempt follows the
 same rule, so a failed install is not re-shown once an entry exists.
 
+Switching those entries to a `User=` later is not just a unit edit. The moment a
+panel runs as root, everything it writes — `<home>/.hh`, its workspaces, logs and
+`snapshots.json` — is root-owned, so the unprivileged account the unit now names
+cannot write its own state and the panel fails to boot with a permission error
+that never mentions ownership. Moving an install from root to a user therefore
+needs `chown -R <user> <home>` (and the plugin state dir) first.
+
 ## Tests
 
 No fixed ports: every stub listener binds `127.0.0.1` with port 0 and reads the