feat(server-s3): one Linux user per account (S3) — experimental

Server mode can now run each account as its own Linux user (ah-<name>)
when `agenthub server install-system` has set S3 up. The dashboard
reaches a member only through sudo -u / write-as / pane-launch, reads a
member's files only through owner- and type-checked opens, and hooks
are authenticated by peer uid. Local mode and server mode without S3
are unchanged.

EXPERIMENTAL: tested with fake sudo and fake accounts only. It has not
yet been verified on a real install with real member accounts, sudo or
a real Codex login. Do not offer it to real users yet.

- S3 core: provisioning, per-member tmux servers, the proxy key
  gateway, shared tools in /opt, dropped capabilities for children
  (P0–P5)
- P4: plan and quota per member home
- P6: ~/.claude.json seed; opt-in plugin baseline installed as the
  member; managed-settings spike script (not run)
- P7: Codex account pool (`agenthub accounts add --tool codex`)
- Roles merged with main's admin / analyst / developer: analysts write
  only their own rows, under S3 as well
- Per-account prefs: one implementation (Chat UI + onboarding)
- Security reviews F1–F49 (five rounds), each fix with a regression
  test: symlink/TOCTOU-safe member reads, no host writes in a member
  home, credentials and the data dir never served, owner and folder
  account must agree, pane tokens bound to the pane's uid, bounded
  sudo/tmux/git calls and member reads (no hang or crash from a member),
  async route rejections answer 500 instead of exiting
- Docs: docs/SERVER-MODE.md (S3 model, accepted ceilings, operator
  runbook), docs/plans/server-mode/S3-PLAN.md, CLAUDE.md S3 rules

Tests: server 2838/2841 (3 need 127.0.0.1:3000, held on this box);
client 1162/1162; tsc clean; headers check passes.

Co-Authored-By: Claude <noreply@anthropic.com>

server/routes/me.js

@@ -1,14 +1,16 @@
 /**
  * @file me.js
- * @description `/api/me` — the signed-in account's own UI preferences
- * (`user_prefs`), so they follow it to any browser and differ between the
- * accounts of one dashboard. Local mode is one account, `local`; server mode
- * keys a row `u<id>` by the login cookie — the request never names an account.
- * Only the keys in `PREF_KEYS` are kept, each a string of at most 8 KB, and a
- * PUT merges into the row (`null` removes a key). Writes are same-origin.
- * Today the one key is `agenthub.chatUi` ("1" = Claude/Codex sessions open as
- * a chat, `PaneChat`). Same table, routes and semantics as the server-s3 work,
- * which adds its own keys to this list.
+ * @description `/api/me` — the signed-in account's own UI preferences and its
+ * first-run setup (docs/plans/onboarding). The browser keeps these in
+ * localStorage; this stores the same keys per ACCOUNT (`user_prefs`), so they
+ * follow it to any browser and the setup wizard shows once per account.
+ * Local mode is one account, `local`. Only the keys in `PREF_KEYS` are kept,
+ * each a string of at most 8 KB — this is a preferences store, not a blob
+ * store. Writes are same-origin and touch only the caller's own row.
+ * `agenthub.chatUi` ("1") opens Claude/Codex sessions as a chat (`PaneChat`).
+ *
+ * S3 (one Linux user per account): an account's dark/light choice also becomes
+ * the theme in their own Claude Code settings, written as them.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
@@ -19,8 +21,23 @@ const { sameOriginGuard } = require("../lib/same-origin");
 
 const router = Router();
 
-/** The keys an account's preferences are made of. */
-const PREF_KEYS = ["agenthub.chatUi"];
+/** The localStorage keys an account's preferences are made of. */
+const PREF_KEYS = [
+  "theme",
+  "agenthub.theme.dark",
+  "agenthub.theme.light",
+  "i18nextLng",
+  "agenthub.terminal.font",
+  "agenthub.pet",
+  "agenthub.pet.size",
+  "agent-dashboard-sagi-enabled",
+  "agent-dashboard-sagi-muted",
+  "agent-monitor-notifications",
+  "agenthub.defaultTool",
+  "agenthub.permissionMode",
+  "agenthub.tour",
+  "agenthub.chatUi",
+];
 const MAX_VALUE = 8 * 1024;
 
 /** `u<id>` for a server-mode account, `local` in local mode, null when nobody is signed in. */
@@ -36,6 +53,10 @@ const upsert = db.prepare(
    ON CONFLICT(user_key) DO UPDATE SET prefs = excluded.prefs,
      updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`
 );
+const markOnboarded = db.prepare(
+  `INSERT INTO user_prefs (user_key, onboarded_at) VALUES (?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+   ON CONFLICT(user_key) DO UPDATE SET onboarded_at = COALESCE(onboarded_at, excluded.onboarded_at)`
+);
 
 function read(key) {
   const row = getRow.get(key);
@@ -71,14 +92,31 @@ router.put("/prefs", sameOriginGuard, (req, res) => {
     }
     if (v === null) delete prefs[k];
     else if (typeof v === "string" && v.length <= MAX_VALUE) prefs[k] = v;
-    else
-      return res
-        .status(400)
-        .json({ error: { code: "EBADPREFS", message: `${k}: a short string` } });
+    else return res.status(400).json({ error: { code: "EBADPREFS", message: `${k}: a short string` } });
   }
   upsert.run(key, JSON.stringify(prefs));
+  if ("theme" in patch) followClaudeTheme(req, patch.theme);
   res.json(read(key));
 });
 
+router.post("/onboarded", sameOriginGuard, (req, res) => {
+  const key = userKey(req);
+  if (!key) return unauth(res);
+  markOnboarded.run(key);
+  res.json(read(key));
+});
+
+/** S3: an account's dark/light mode becomes their Claude Code theme (best effort). */
+function followClaudeTheme(req, mode) {
+  if (mode !== "dark" && mode !== "light") return;
+  try {
+    const runAs = require("../lib/run-as");
+    const acct = runAs.accountForUser(req.user?.username);
+    if (acct) require("../lib/member-claude").setTheme(acct, mode);
+  } catch (err) {
+    console.warn("[me] Claude theme not written:", err.message);
+  }
+}
+
 module.exports = router;
 module.exports.PREF_KEYS = PREF_KEYS;