dsh-home-hosted 0.6.1 → 0.6.2

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

@@ -292,6 +292,71 @@ 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 or a root unit 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: it is a shell variable rather than an
+exported one, so when it is present at all it was inherited, and it also feeds the
+launchd domain (`gui/$UID`). It is read only when the platform gives no 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 —
+  worse than running as root, and the same unexplained failure in a new costume.
+  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
 
 A `LaunchAgent` starts at login; starting before login means a `LaunchDaemon` in
@@ -299,8 +364,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
 
@@ -491,6 +557,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

package/lib/index.js

@@ -70,77 +70,6 @@ import path15 from "node:path";
 import process10 from "node:process";
 import { fileURLToPath } from "node:url";
 
-// src/boot/ladder.ts
-import os2 from "node:os";
-import process3 from "node:process";
-
-// src/util/exec.ts
-import { spawn } from "node:child_process";
-async function run(command, args = [], options = {}) {
-  const maxBytes = options.maxBytes ?? 256 * 1024;
-  const timeoutMs = options.timeoutMs ?? 2e4;
-  return await new Promise((resolve) => {
-    let settled = false;
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    const finish = (result) => {
-      if (settled)
-        return;
-      settled = true;
-      resolve({
-        command,
-        args,
-        code: result.code ?? null,
-        signal: result.signal ?? null,
-        stdout: result.stdout ?? stdout,
-        stderr: result.stderr ?? stderr,
-        timedOut,
-        error: result.error ?? null
-      });
-    };
-    let child;
-    try {
-      child = spawn(command, args, {
-        cwd: options.cwd,
-        env: { ...process.env, ...options.env },
-        shell: false,
-        windowsHide: true,
-        stdio: ["ignore", "pipe", "pipe"]
-      });
-    } catch (error) {
-      finish({ error: error instanceof Error ? error.message : String(error) });
-      return;
-    }
-    const timer = setTimeout(() => {
-      timedOut = true;
-      child.kill("SIGKILL");
-    }, timeoutMs);
-    child.stdout?.on("data", (chunk) => {
-      if (stdout.length < maxBytes)
-        stdout += chunk.toString("utf8").slice(0, maxBytes - stdout.length);
-    });
-    child.stderr?.on("data", (chunk) => {
-      if (stderr.length < maxBytes)
-        stderr += chunk.toString("utf8").slice(0, maxBytes - stderr.length);
-    });
-    child.on("error", (error) => {
-      clearTimeout(timer);
-      finish({ error: error.message });
-    });
-    child.on("close", (code, signal) => {
-      clearTimeout(timer);
-      finish({ code, signal });
-    });
-  });
-}
-async function sudoAvailable() {
-  if (process.getuid?.() === 0)
-    return true;
-  const result = await run("sudo", ["-n", "true"], { timeoutMs: 5e3 });
-  return result.code === 0;
-}
-
 // src/boot/common.ts
 import fs2 from "node:fs";
 import os from "node:os";
@@ -211,32 +140,129 @@ function tempDir(ctx) {
   const value = ctx.env.TMPDIR?.trim() || ctx.env.TEMP?.trim() || ctx.env.TMP?.trim();
   return value || os.tmpdir();
 }
-function currentUser(ctx) {
-  const value = ctx.env.USER?.trim() || ctx.env.LOGNAME?.trim() || ctx.env.USERNAME?.trim();
-  if (value)
-    return value;
+function parsePasswd(text) {
+  return text.split("\n").map((line) => {
+    const fields = line.split(":");
+    const uid = Number.parseInt(fields[2] ?? "", 10);
+    return fields.length < 6 || !Number.isFinite(uid) || (fields[0] ?? "").length === 0 ? null : { name: fields[0] ?? "", uid, home: fields[5] ?? "" };
+  }).filter((entry) => entry !== null);
+}
+function readPasswd() {
   try {
-    return os.userInfo().username;
+    return parsePasswd(fs2.readFileSync("/etc/passwd", "utf8"));
   } catch {
+    return [];
+  }
+}
+function numberFrom(value) {
+  const text = value?.trim();
+  if (text === void 0 || text.length === 0)
+    return null;
+  return /^\d+$/.test(text) ? Number.parseInt(text, 10) : null;
+}
+function accountFrom(row, ambientHome) {
+  const home = row.home.length > 0 ? row.home : ambientHome?.trim() || null;
+  return { name: row.name, uid: row.uid, home, root: row.uid === 0, verified: true };
+}
+function declaredName(env) {
+  const value = env.SUDO_USER?.trim() || env.PKEXEC_USER?.trim();
+  return value !== void 0 && value.length > 0 ? value : null;
+}
+function sessionName(env) {
+  const value = env.LOGNAME?.trim() || env.USER?.trim() || env.USERNAME?.trim();
+  return value !== void 0 && value.length > 0 ? value : null;
+}
+function ownerAccount(paths, passwd) {
+  for (const path17 of paths ?? []) {
+    try {
+      const uid = fs2.statSync(path17).uid;
+      if (uid === 0)
+        continue;
+      const row = passwd.find((entry) => entry.uid === uid);
+      if (row !== void 0)
+        return accountFrom(row);
+    } catch {
+    }
+  }
+  return null;
+}
+function accountOf(input) {
+  const passwd = input.passwd ?? readPasswd();
+  const byUid = (uid) => uid === null ? null : passwd.find((entry) => entry.uid === uid) ?? null;
+  const byName = (name2) => name2 === null ? null : passwd.find((entry) => entry.name === name2) ?? null;
+  const elevatedUid = numberFrom(input.env.SUDO_UID) ?? numberFrom(input.env.PKEXEC_UID);
+  const elevatedName = declaredName(input.env);
+  if (elevatedUid !== null || elevatedName !== null) {
+    const row = byUid(elevatedUid) ?? byName(elevatedName);
+    if (row !== null)
+      return accountFrom(row);
+    if (elevatedUid !== null && elevatedUid !== 0 && elevatedName !== null)
+      return { name: elevatedName, uid: elevatedUid, home: null, root: false, verified: false };
+  }
+  const euid = input.uid === void 0 ? process.getuid?.() ?? null : input.uid;
+  const ownUid = euid ?? numberFrom(input.env.UID);
+  const session = sessionName(input.env);
+  if (session !== null && session.toLowerCase() !== "root") {
+    const sessionRow = byName(session);
+    if (sessionRow !== null)
+      return accountFrom(sessionRow, input.env.HOME);
+    const uidRow = byUid(ownUid === 0 ? null : ownUid);
+    if (uidRow !== null)
+      return accountFrom(uidRow, input.env.HOME);
+    return { name: session, uid: ownUid, home: input.env.HOME?.trim() || null, root: false, verified: false };
+  }
+  const ownRow = ownUid === 0 ? null : byUid(ownUid);
+  if (ownRow !== null)
+    return accountFrom(ownRow);
+  const owner = ownerAccount(input.ownerPaths, passwd);
+  if (owner !== null)
+    return owner;
+  if (ownUid === 0 || session?.toLowerCase() === "root")
+    return { name: "root", uid: 0, home: input.env.HOME?.trim() || "/root", root: true, verified: true };
+  return null;
+}
+function currentUser(ctx) {
+  const account = accountOf(ctx);
+  if (account !== null && !account.root)
+    return account.name;
+  const value = sessionName(ctx.env);
+  return value !== null && value.toLowerCase() !== "root" ? value : null;
+}
+function bootUserName(ctx) {
+  const account = accountOf(ctx);
+  if (account === null) {
+    warnAccount(ctx, "no account could be resolved for the entry, so a system unit would run the panel as root. Install it from the account that should own the panel, or set User= yourself.");
+    return null;
+  }
+  if (account.root) {
+    warnAccount(ctx, "the only account available is root; a system unit would run the panel as root. Install it from the account that should own the panel, or set User= yourself.");
+    return null;
+  }
+  if (!isUserName(account.name)) {
+    warnAccount(ctx, `the account name ${JSON.stringify(account.name)} is not a usable user name, so no User= line was written`);
     return null;
   }
+  if (!account.verified) {
+    warnAccount(ctx, `the account ${JSON.stringify(account.name)} could not be found in the user database, so no User= line was written: systemd would refuse to start the unit (status=217/USER). Set User= yourself if that account resolves through LDAP or NIS.`);
+    return null;
+  }
+  return account.name;
+}
+function isUserName(name2) {
+  return /^[A-Za-z_][A-Za-z0-9._-]*$/.test(name2);
 }
-function userNameOf(ctx) {
-  const configured = ctx.env.USER?.trim() ?? ctx.env.USERNAME?.trim();
-  if (configured !== void 0 && configured.length > 0)
-    return configured;
+function warnAccount(ctx, message) {
   try {
-    return os.userInfo().username;
+    (ctx.warn ?? ((line) => console.warn(`[dsh-home-hosted] ${line}`)))(message);
   } catch {
-    return null;
   }
 }
 function uidOf(ctx) {
-  const configured = ctx.env.UID?.trim();
-  if (configured)
-    return configured;
-  const uid = process.getuid?.();
-  return uid === void 0 ? null : String(uid);
+  const configured = numberFrom(ctx.env.UID);
+  if (configured !== null)
+    return String(configured);
+  const uid = ctx.uid === void 0 ? process.getuid?.() ?? null : ctx.uid;
+  return uid === null ? null : String(uid);
 }
 function inspectOwned(file, marker) {
   if (!fs2.existsSync(file))
@@ -284,6 +310,77 @@ function isInstalledState(state) {
   return state === "installed-disabled" || state === "enabled-running" || state === "enabled-failing";
 }
 
+// src/boot/ladder.ts
+import os2 from "node:os";
+import process3 from "node:process";
+
+// src/util/exec.ts
+import { spawn } from "node:child_process";
+async function run(command, args = [], options = {}) {
+  const maxBytes = options.maxBytes ?? 256 * 1024;
+  const timeoutMs = options.timeoutMs ?? 2e4;
+  return await new Promise((resolve) => {
+    let settled = false;
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const finish = (result) => {
+      if (settled)
+        return;
+      settled = true;
+      resolve({
+        command,
+        args,
+        code: result.code ?? null,
+        signal: result.signal ?? null,
+        stdout: result.stdout ?? stdout,
+        stderr: result.stderr ?? stderr,
+        timedOut,
+        error: result.error ?? null
+      });
+    };
+    let child;
+    try {
+      child = spawn(command, args, {
+        cwd: options.cwd,
+        env: { ...process.env, ...options.env },
+        shell: false,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (error) {
+      finish({ error: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => {
+      if (stdout.length < maxBytes)
+        stdout += chunk.toString("utf8").slice(0, maxBytes - stdout.length);
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderr.length < maxBytes)
+        stderr += chunk.toString("utf8").slice(0, maxBytes - stderr.length);
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      finish({ error: error.message });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      finish({ code, signal });
+    });
+  });
+}
+async function sudoAvailable() {
+  if (process.getuid?.() === 0)
+    return true;
+  const result = await run("sudo", ["-n", "true"], { timeoutMs: 5e3 });
+  return result.code === 0;
+}
+
 // src/boot/systemd.ts
 import fs3 from "node:fs";
 
@@ -306,6 +403,11 @@ function assertMarker(marker) {
     throw new Error("marker must not be empty");
   return assertNoControl(marker, "marker");
 }
+function assertUserName(name2) {
+  if (!/^[A-Za-z_][A-Za-z0-9._-]*$/.test(name2))
+    throw new Error(`user name ${JSON.stringify(name2)} must match ^[A-Za-z_][A-Za-z0-9._-]*$`);
+  return name2;
+}
 function assertEnvKey(key) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
     throw new Error(`environment key ${JSON.stringify(key)} is not a valid name`);
@@ -462,6 +564,15 @@ function envLines(spec) {
   return Object.entries(spec.env).map(([key, value]) => `Environment=${systemdEnvLine(key, value)}`);
 }
 var MANAGED = (spec) => `# Managed by ${spec.marker}`;
+function codeOf(result) {
+  return result.error ? null : result.code;
+}
+function accountNote(own, ctx) {
+  if (!own.owned || own.text === null)
+    return "";
+  const declared = /^User=(.*)$/m.exec(own.text)?.[1]?.trim() ?? "";
+  return declared === "" || declared === "root" ? "; the unit names no other user, so the panel runs as root \u2014 install again from the account that should own it" : "";
+}
 function systemdUserUnit(spec) {
   validate(spec);
   return `${[
@@ -474,6 +585,14 @@ function systemdUserUnit(spec) {
     "Type=exec",
     `ExecStart=${[spec.command, ...spec.args].map(systemdExecWord).join(" ")}`,
     `WorkingDirectory=${systemdPath(spec.cwd, "spec.cwd")}`,
+    // A persistent entry survives a panel restart only because its nanny is not
+    // the panel. The nanny is spawned `detached`, which gives it its own session —
+    // but *not* its own cgroup, so the default `KillMode=control-group` kills it
+    // with the panel and takes the entry down too, quietly falsifying what
+    // `persistent: true` promises. `process` signals the panel alone. (An ordinary
+    // entry is spawned detached as well, so this keeps every supervised server, not
+    // only the nannies — the panel re-adopts such a survivor by its port.)
+    "KillMode=process",
     "Restart=always",
     "RestartSec=5",
     ...envLines(spec),
@@ -494,10 +613,12 @@ function systemdSystemUnit(spec, user = null) {
     "StartLimitBurst=5",
     "",
     "[Service]",
-    ...user ? [`User=${user}`] : [],
+    ...user === null || user === "" || user === "root" ? [] : [`User=${assertUserName(user)}`],
     "Type=exec",
     `ExecStart=${[spec.command, ...spec.args].map(systemdExecWord).join(" ")}`,
     `WorkingDirectory=${systemdPath(spec.cwd, "spec.cwd")}`,
+    // See the user unit: `control-group` would kill the nannies too.
+    "KillMode=process",
     "Restart=always",
     "RestartSec=5",
     ...envLines(spec),
@@ -507,9 +628,6 @@ function systemdSystemUnit(spec, user = null) {
     ""
   ].join("\n")}`;
 }
-function codeOf(result) {
-  return result.error ? null : result.code;
-}
 function parseKeyValues(stdout) {
   const out = {};
   for (const line of stdout.split("\n")) {
@@ -734,10 +852,6 @@ function createSystemdUserProvider(ctx) {
     }
   };
 }
-function systemUserName(ctx) {
-  const user = currentUser(ctx);
-  return user && /^[A-Za-z_][A-Za-z0-9._-]*$/.test(user) ? user : null;
-}
 function stageUnit(ctx, unit, content) {
   const staged = posixJoin(tempDir(ctx), `home-hosted-${unit}`);
   fs3.writeFileSync(staged, content, { mode: 420 });
@@ -747,7 +861,7 @@ function createSystemdSystemProvider(ctx) {
   const mechanism = "systemd-system";
   const unitOf = (spec) => `${assertUnitName(spec.unitName)}.service`;
   const pathOf = (spec) => posixJoin("/etc", "systemd", "system", unitOf(spec));
-  const contentOf = (spec) => systemdSystemUnit(spec, ctx.isRoot ? systemUserName(ctx) : null);
+  const contentOf = (spec) => systemdSystemUnit(spec, bootUserName(ctx));
   const installCommands = (staged, file, unit) => [
     shellCommand("sudo", ["install", "-m", "0644", staged, file]),
     shellCommand("sudo", ["systemctl", "daemon-reload"]),
@@ -761,12 +875,14 @@ function createSystemdSystemProvider(ctx) {
       if (!existsOf(ctx, "/run/systemd/system"))
         return { mechanism, available: false, bootCapable: false, privileged: false, reason: "systemd is not the init system here (no /run/systemd/system)" };
       const privileged = ctx.isRoot || await ctx.sudo();
+      const who = accountOf(ctx);
+      const scope = who === null || who.root ? "no account was resolved for the entry, so it would run the panel as root" : `the entry runs the panel as ${who.name}`;
       return {
         mechanism,
         available: privileged,
         bootCapable: privileged,
         privileged,
-        reason: privileged ? "systemd is PID 1 and this process can use root, so a system unit starts at boot" : "systemd is PID 1, but installing a system unit needs root or passwordless sudo"
+        reason: privileged ? `systemd is PID 1 and this process can use root, so a system unit starts at boot; ${scope}` : "systemd is PID 1, but installing a system unit needs root or passwordless sudo"
       };
     },
     async status(spec) {
@@ -786,7 +902,7 @@ function createSystemdSystemProvider(ctx) {
         return {
           state,
           unitPath: file,
-          detail: `${probe.detail}${privileged ? "" : "; needs root to change"}`,
+          detail: `${probe.detail}${privileged ? "" : "; needs root to change"}${accountNote(own, ctx)}`,
           commands
         };
       } catch (error) {
@@ -983,7 +1099,8 @@ function launchdLabel(spec) {
 function launchdPlist(spec, options = {}) {
   validate2(spec);
   const label = launchdLabel(spec);
-  const userName = options.userName?.trim();
+  const named = options.userName?.trim();
+  const userName = named === void 0 || named.length === 0 ? void 0 : assertUserName(named);
   const out = path3.posix.join(spec.logDir, `${label}.out.log`);
   const err = path3.posix.join(spec.logDir, `${label}.err.log`);
   const envKeys = Object.keys(spec.env);
@@ -1127,7 +1244,7 @@ function createLaunchdProvider(ctx, mode) {
         validate2(spec);
         const file = pathOf(spec);
         const label = launchdLabel(spec);
-        const content = launchdPlist(spec, mode === "daemon" ? { userName: userNameOf(ctx) } : {});
+        const content = launchdPlist(spec, mode === "daemon" ? { userName: bootUserName(ctx) } : {});
         const own = inspectOwned(file, spec.marker);
         if (own.exists && !own.owned)
           return failed(own.reason ?? "foreign file");
@@ -2025,7 +2142,8 @@ function bootProviders(ctx, platform = ctx.platform) {
 }
 function createBootLadder(options = {}) {
   const platform = options.platform ?? process3.platform;
-  const isRoot = process3.getuid?.() === 0;
+  const uid = options.uid === void 0 ? process3.getuid?.() ?? null : options.uid;
+  const isRoot = uid === 0;
   const ctx = {
     platform,
     home: options.home ?? os2.homedir(),
@@ -2033,6 +2151,10 @@ function createBootLadder(options = {}) {
     run: options.run ?? run,
     sudo: options.sudo ?? (async () => isRoot ? true : await sudoAvailable()),
     isRoot,
+    uid: options.uid,
+    ownerPaths: options.ownerPaths,
+    passwd: options.passwd,
+    warn: options.warn,
     exists: options.exists
   };
   const providers = bootProviders(ctx, platform);
@@ -2525,6 +2647,13 @@ function homeHostedEnv(facts, launch, extra = {}) {
     HHOSTED_HOME: facts.home,
     ...extra
   };
+  const accountHome = facts.accountHome?.trim();
+  if (accountHome !== void 0 && accountHome.length > 0) {
+    if (accountHome !== env.HOME)
+      env.HOME = accountHome;
+  } else if (facts.accountHome === null) {
+    delete env.HOME;
+  }
   if (facts.projectDir)
     env.HHOSTED_PROJECT = facts.projectDir;
   return env;
@@ -2539,7 +2668,16 @@ function buildHomeHostedBootSpec(facts, launch, options) {
     command: launch.program,
     args,
     cwd: facts.projectDir ?? facts.home,
-    env: homeHostedEnv(facts, launch),
+    env: homeHostedEnv(
+      {
+        ...facts,
+        // `undefined` means the option was not given; `null` is a decision (an
+        // account whose home is unknowable), and `??` would erase it.
+        accountHome: options.accountHome === void 0 ? facts.accountHome : options.accountHome,
+        env: options.env ?? facts.env
+      },
+      launch
+    ),
     marker: options.marker ?? "managed by dsh-home-hosted",
     // One artifact per state root, so two plugin instances cannot overwrite or
     // delete each other's entry. The machine-default install keeps the old name.
@@ -5006,10 +5144,34 @@ var HomeHostedService = class extends Service {
   // -------------------------------------------------------------------------
   // Boot autostart
   // -------------------------------------------------------------------------
+  /**
+   * Everything account resolution reads.
+   *
+   * The state paths matter: they name the person the panel belongs to, so a root
+   * process launched at boot (a system unit that names no `User=`) can still be
+   * told whose panel it is running.
+   */
+  /** This process's environment, from the test seam when one is supplied. */
+  processEnv() {
+    return this.options.env ?? process10.env;
+  }
+  accountFacts() {
+    return {
+      env: this.processEnv(),
+      uid: this.options.uid,
+      ownerPaths: [this.options.home, this.options.stateDir],
+      passwd: this.options.passwd
+    };
+  }
+  /**
+   * The ladder resolves the account per provider, and the spec below resolves it
+   * for the entry's environment. Both are handed the *same* facts, so the `User=`
+   * line and the `HOME=` line can never describe two different people.
+   */
   ladder() {
     if (this.options.createLadder !== void 0)
       return this.options.createLadder();
-    return createBootLadder({ env: process10.env });
+    return createBootLadder(this.accountFacts());
   }
   async bootSpec() {
     const { resolution, launcher } = await this.cli();
@@ -5017,6 +5179,7 @@ var HomeHostedService = class extends Service {
     if (launch === null)
       return null;
     const runtime = this.runtime();
+    const account = accountOf(this.accountFacts());
     const spec = buildHomeHostedBootSpec(
       {
         home: this.options.home,
@@ -5024,7 +5187,16 @@ var HomeHostedService = class extends Service {
         version: runtime?.version ?? null
       },
       launch,
-      { stateDir: this.options.stateDir, unitName: bootUnitName(this.options.stateDir) }
+      {
+        stateDir: this.options.stateDir,
+        unitName: bootUnitName(this.options.stateDir),
+        // `undefined` when no account was resolved: the entry then runs as this
+        // process (or as root), and this process's own HOME is the right one. A
+        // spec that merely repeats this environment stays byte-identical, so
+        // reconcile does not rewrite the entry on every start.
+        accountHome: account === null ? void 0 : account.home,
+        env: this.processEnv()
+      }
     );
     if (launcher !== null) {
       const cliArgs2 = spec.args.slice(launch.args.length);