ccdeck 3.29.11 → 3.31.0

package/src/server/prefs-give-back.mjs

@@ -0,0 +1,206 @@
+// Giving the deck's own folders back to the person running it, from the panel
+// (#1711).
+//
+// #1335 taught the deck to say, precisely, that its settings folder belongs to
+// another user — which is what a `sudo ccdeck` leaves on a Mac, where sudo keeps
+// HOME. It could not do more: the folder is root's, and only root can give it
+// back. So the way out was a `sudo chown -R` line in a log the person reporting
+// it did not know how to find, and until they ran it every settings write was
+// refused, the share tick included.
+//
+// On macOS the deck can ask for that root itself, through the operating
+// system's own password dialog. That makes this the one place ccdeck acts with
+// administrator rights, and everything below is about keeping it that narrow:
+//
+//   THE PATHS ARE THE DECK'S OWN. Computed here, from the same functions that
+//   decide where the deck keeps its things. Nothing the request carries reaches
+//   the command; the route takes no body at all.
+//
+//   EVERY TARGET IS CHECKED BEFORE THE DIALOG. A real directory, not a symlink,
+//   named like one of the deck's, strictly inside the user's home both as
+//   written and after realpath, and owned by somebody else. A folder that is
+//   already the user's is left out, so the dialog never appears for nothing.
+//
+//   THE PATHS ARE DATA, NOT SOURCE. They reach AppleScript as argv, after `--`
+//   (see notify in browser-react.mjs for what a leading dash did without it),
+//   and reach the shell through `quoted form of`. The script text is a
+//   constant, and osascript is named by its full path.
+//
+//   THE FOLDER ROOT CHANGES IS THE FOLDER THAT WAS CHECKED. The checks run
+//   before the dialog and root acts after it, minutes later if the person is
+//   slow, and the parent folder is the user's: anything running as the user
+//   could put a folder of its own in place of the checked one, holding a hard
+//   link to a file root owns, and `chown -R` would hand that file over. So the
+//   root step does not trust the path. It enters the folder, compares the
+//   device and inode of where it landed with the ones surveyed here, refuses
+//   a tree holding any file with a second hard link, and only then changes
+//   `.`, which a rename of the path can no longer move.
+//
+//   `chown -n -x -R -P`: numeric ids with no name lookup, no mount point
+//   crossed, and no symlink inside the tree followed.
+import { lstat, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+// POSIX, not the host's: every path here is a Mac's, and the suite checks
+// them on Windows too, where the host's `normalize` would turn every slash
+// into a backslash and find nothing inside any home (see deckDataDir).
+import { posix } from "node:path";
+import { PRODUCT } from "./brand.mjs";
+import { deckDataDir, deckLogDir, legacyDeckDir } from "./deck-home.mjs";
+import { run } from "./exec.mjs";
+import { prefsDir } from "./prefs-path.mjs";
+
+/** The folder names the deck files itself under. A CCDECK_HOME named anything
+ *  else is somebody's own choice of place, and the log's command is still there
+ *  for it; the deck does not take root to change the owner of it. */
+const DECK_FOLDER_NAMES = new Set(["ccdeck", "agent-dag"]);
+
+/** How long the password dialog may stay open. It waits on a person, so the
+ *  exec default of twenty seconds would close it under them. */
+export const GIVE_BACK_TIMEOUT_MS = 180_000;
+
+/** What the dialog says it is for, above macOS's own "wants to make changes". */
+export const GIVE_BACK_PROMPT =
+  `${PRODUCT} needs your password to make its settings folder yours again. It was left owned by another user, most likely by a run with sudo.`;
+
+/** osascript, by its full path: this is the one call that asks for the
+ *  administrator's password, and a PATH lookup is a way to put a different
+ *  dialog in front of it. */
+export const OSASCRIPT = "/usr/bin/osascript";
+
+/** The whole of what runs as root. Item 1 is `uid:gid`, item 2 the prompt, and
+ *  after them a folder and its `device:inode` for each folder; every one is
+ *  quoted by AppleScript, never by hand. A folder that is not the one surveyed,
+ *  or that holds a file with a second hard link, stops the whole command with
+ *  status 3 before anything in it changes owner. */
+export const GIVE_BACK_SCRIPT = [
+  "on run argv",
+  "set owner to quoted form of (item 1 of argv)",
+  'set cmd to "true"',
+  "repeat with i from 3 to (count of argv) by 2",
+  "set target to quoted form of (item i of argv)",
+  "set wanted to quoted form of (item (i + 1) of argv)",
+  'set cmd to cmd & " && { cd -P -- " & target & " && [ \\"$(/usr/bin/stat -f %d:%i .)\\" = " & wanted & " ] && [ -z \\"$(/usr/bin/find -x -P . ! -type d -links +1 -print)\\" ] || exit 3; } && /usr/sbin/chown -n -x -R -P -- " & owner & " ."',
+  "end repeat",
+  "do shell script cmd with prompt (item 2 of argv) with administrator privileges",
+  "end run",
+].join("\n");
+
+/** osascript's "User canceled." — the person closed the dialog. */
+const CANCELLED = /\(-128\)/;
+/** The root step's own refusal: the folder was not the one surveyed, or held a
+ *  hard link. osascript reports the shell's status in brackets. */
+const GUARD_TRIPPED = /\(3\)\s*$/m;
+
+/**
+ * Which of the deck's folders belong to somebody else, and whether each one is
+ * safe to hand back.
+ *
+ * The settings folder is the one the refusal was about, so it comes first and
+ * its verdict decides the answer. The log folder and the legacy folder are
+ * where the same sudo run wrote too — the event log, the hook, the port
+ * registry — and are given back in the same dialog when they need it, or
+ * skipped when they do not exist or already belong to the user.
+ */
+export function deckFolders(platform = process.platform, env = process.env, home = homedir()) {
+  return [prefsDir(deckDataDir(platform, env, home)), deckLogDir(platform, env, home), legacyDeckDir(env, home, platform)]
+    .filter((path, i, all) => all.indexOf(path) === i);
+}
+
+async function survey(path, { uid, home, fs }) {
+  let st;
+  try {
+    // BigInt, because the inode is handed to the root step to compare with
+    // stat(1)'s, and a number past 2^53 would compare unequal to itself.
+    st = await fs.lstat(path, { bigint: true });
+  } catch (err) {
+    return { path, state: err?.code === "ENOENT" ? "missing" : "unsafe" };
+  }
+  if (Number(st.uid) === uid) return { path, state: "yours" };
+  if (!st.isDirectory() || st.isSymbolicLink()) return { path, state: "unsafe" };
+  if (!DECK_FOLDER_NAMES.has(basename(path))) return { path, state: "unsafe" };
+  if (!strictlyInside(path, home)) return { path, state: "unsafe" };
+  const real = await fs.realpath(path).catch(() => "");
+  const realHome = await fs.realpath(home).catch(() => "");
+  if (!real || !realHome || !strictlyInside(real, realHome)) return { path, state: "unsafe" };
+  return { path, state: "foreign", id: `${st.dev}:${st.ino}` };
+}
+
+const { basename, isAbsolute, normalize, sep } = posix;
+
+function strictlyInside(path, home) {
+  if (!isAbsolute(path) || !isAbsolute(home) || normalize(path) !== path) return false;
+  const root = home.endsWith(sep) ? home : home + sep;
+  return path.startsWith(root) && path.length > root.length;
+}
+
+let _inFlight = false;
+
+/**
+ * Ask macOS for the password, and give the deck's folders back to this user.
+ *
+ * Answers `{ ok: true, changed }` — `changed: false` when nothing needed it,
+ * which is also what a folder somebody already fixed by hand looks like — or
+ * `{ ok: false, reason }` from a closed set, because the route hands it to a
+ * page and a path names the user:
+ *
+ *   unsupported    not macOS, or no uid to compare, or running as root already
+ *   busy           a dialog from an earlier press is still open
+ *   not_eligible   the settings folder failed one of the checks above
+ *   cancelled      the person closed the dialog
+ *   timed_out      nobody answered it
+ *   refused        macOS or chown said no; the log has what it said
+ *   still_foreign  chown answered and the folder is still not theirs
+ */
+export async function giveBackDeckFolders(deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  if (platform !== "darwin") return { ok: false, reason: "unsupported" };
+  const uid = deps.getuid ? deps.getuid() : process.getuid?.();
+  const gid = deps.getgid ? deps.getgid() : process.getgid?.();
+  if (uid === undefined || gid === undefined || uid === 0) return { ok: false, reason: "unsupported" };
+  if (_inFlight) return { ok: false, reason: "busy" };
+  _inFlight = true;
+  try {
+    return await giveBack({ ...deps, platform, uid, gid });
+  } finally {
+    _inFlight = false;
+  }
+}
+
+async function giveBack({ platform, uid, gid, env = process.env, home = homedir(), fs = { lstat, realpath }, exec = run, warn = console.error }) {
+  const folders = await Promise.all(deckFolders(platform, env, home).map(path => survey(path, { uid, home, fs })));
+  const [settings] = folders;
+  if (settings.state === "unsafe") {
+    warn(`${PRODUCT}: ${settings.path} is not a folder this deck will change the owner of from the panel — it has to be a real folder named like the deck's, inside your home. Give it back by hand: sudo chown -R "$(id -un)" "${settings.path}"`);
+    return { ok: false, reason: "not_eligible" };
+  }
+  const foreign = folders.filter(f => f.state === "foreign");
+  if (!foreign.length) return { ok: true, changed: false };
+
+  const r = await exec(OSASCRIPT, [
+    "-e", GIVE_BACK_SCRIPT, "--", `${uid}:${gid}`, GIVE_BACK_PROMPT, ...foreign.flatMap(f => [f.path, f.id]),
+  ], { timeout: GIVE_BACK_TIMEOUT_MS });
+  const said = (r?.stderr || r?.code || "osascript failed").toString().trim();
+  if (!r?.ok && !r?.timedOut && CANCELLED.test(r?.stderr ?? "")) return { ok: false, reason: "cancelled" };
+
+  // WHO OWNS THEM NOW, WHATEVER osascript ANSWERED. One command gives every
+  // folder back, so a failure on the log folder fails the exit after the
+  // settings folder was already changed, and a password typed just before the
+  // deadline can land after it. Answering that as a refusal would leave the
+  // deck on defaults with its writes now succeeding.
+  const owners = await Promise.all(foreign.map(f => fs.lstat(f.path).then(st => Number(st.uid), () => undefined)));
+  const left = foreign.filter((_, i) => owners[i] !== uid).map(f => f.path);
+  const settingsGiven = settings.state === "foreign" && !left.includes(settings.path);
+  if (!left.length || settingsGiven) {
+    if (left.length) warn(`${PRODUCT}: the settings folder is yours again, but ${left.join(", ")} still belongs to another user: ${said}`);
+    return { ok: true, changed: true };
+  }
+  if (r?.timedOut) return { ok: false, reason: "timed_out" };
+  if (!r?.ok) {
+    warn(GUARD_TRIPPED.test(r?.stderr ?? "")
+      ? `${PRODUCT}: did not give ${left.join(", ")} back: the folder changed between the check and the password, or holds a file with a second hard link. Nothing in it changed owner.`
+      : `${PRODUCT}: could not give ${left.join(", ")} back: ${said}`);
+    return { ok: false, reason: "refused" };
+  }
+  warn(`${PRODUCT}: chown answered, but ${left.join(", ")} still belongs to another user.`);
+  return { ok: false, reason: "still_foreign" };
+}

package/src/server/prefs-path.mjs

@@ -0,0 +1,14 @@
+// Where prefs.json lives. Its own module because two do the arithmetic:
+// deck-prefs.mjs, which reads and writes the file, and the half that moves a
+// file nobody can use out of its way.
+import { join } from "node:path";
+import { deckDataDir } from "./deck-home.mjs";
+
+/* WHERE THIS FILE LIVES, AND WHY IT MOVED. It sat in ~/.claude/agent-dag — the
+   directory Claude Code owns — which meant a person clearing Claude Code's
+   configuration cleared this deck's private key, and every machine that had
+   pinned it had to be told to trust this one again. deck-home.mjs owns the new
+   answer and the reasons; what matters here is that the parameter is still a
+   DIRECTORY, so every caller that passes one is unchanged. */
+export const prefsDir = (home = deckDataDir()) => home;
+export const prefsPath = (home = deckDataDir()) => join(prefsDir(home), "prefs.json");

package/src/server/prefs-refusal.mjs

@@ -0,0 +1,86 @@
+// How the deck says it will not write prefs.json, and why.
+//
+// Moved out of deck-prefs.mjs whole: the error writePrefs throws rather than
+// merge onto a base it knows is not the user's, and the two readings of it the
+// route hands the panel (#1335) — a reason from a closed set, and the detail,
+// every field of which is picked from a closed set too, because a route's body
+// is readable by a DNS-rebound page and a path names the user.
+import { PRODUCT } from "./brand.mjs";
+
+/** The refusal `writePrefs` throws rather than merge onto a base it knows is
+ *  not the user's. Shaped like installer.mjs's SETTINGS_UNREADABLE, which is
+ *  the same policy on the other file this deck rewrites: a file we cannot
+ *  reproduce is never treated as an empty one. */
+export function unreadablePrefs(path, why, blocked) {
+  const err = new Error(
+    `${path} could not be read (${why}). Refusing to overwrite it — this deck's ` +
+    `LAN key and its pairings are in there and cannot be re-derived. Fix the ` +
+    `file or move it aside, then restart ${PRODUCT}.`,
+  );
+  err.code = "PREFS_UNREADABLE";
+  err.prefsPath = path;
+  err.why = why;
+  err.blocked = blocked;
+  return err;
+}
+
+/** The errors a filesystem raises for a place this user may not write — most
+ *  often a settings folder a `sudo` run left owned by root (#1335). */
+const NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS"]);
+
+/**
+ * Why a settings write failed, as a reason the panel can name — or null when
+ * the failure is not one of the two a person can fix from outside the deck.
+ *
+ * A code, never the message: the message carries the absolute path, and a
+ * route's body is readable by a DNS-rebound page (see sendInternalError). The
+ * deck's log keeps the path for the person who has to go and look.
+ */
+export function prefsWriteRefusal(err) {
+  if (err?.code === "PREFS_UNREADABLE") return "prefs_unreadable";
+  if (NOT_WRITABLE.has(err?.code)) return "prefs_not_writable";
+  return null;
+}
+
+/** What blocked a prefs.json that is not JSON and could not be moved aside —
+ *  no errno for it, so a name of the deck's own in the same shape. */
+export const NOT_JSON = Object.freeze({ code: "BADJSON", owner: "unknown", on: "file" });
+
+const OWNERS = new Set(["you", "other", "unknown"]);
+/** An errno as Node spells one, or the deck's BADJSON. Anything else — which
+ *  nothing here produces — is dropped rather than echoed to the page. */
+const ERRNO = /^E?[A-Z][A-Z0-9]{1,15}$/;
+
+/**
+ * The same refusal, told precisely enough to act on from a screenshot (#1335).
+ *
+ * 3.29.3's panel could only guess — "the file may belong to another user" — and
+ * the one Mac it was written for turned out not to be the case 3.29.4 repairs,
+ * with nothing on the screen to say which case it was. So the page now gets the
+ * errno, who owns what blocked the read (`you`, `other`, `unknown`), and whether
+ * that is the `file` or its `folder`.
+ *
+ * Every field is picked from a closed set. Still no path and no uid: the route's
+ * body is readable by a DNS-rebound page (see prefsWriteRefusal), and a path
+ * names the user. Null when there is nothing precise to add. `fix` is present
+ * only when the panel can offer the repair itself — see givesBack.
+ */
+export function prefsRefusalDetail(err, platform = process.platform) {
+  const blocked = err?.code === "PREFS_UNREADABLE" ? err.blocked
+    : NOT_WRITABLE.has(err?.code) ? { code: err.code, owner: "unknown", on: "folder" }
+    : null;
+  if (!blocked || typeof blocked !== "object") return null;
+  const detail = {
+    code: ERRNO.test(blocked.code ?? "") ? blocked.code : "",
+    owner: OWNERS.has(blocked.owner) ? blocked.owner : "unknown",
+    on: blocked.on === "folder" ? "folder" : "file",
+  };
+  return givesBack(detail, platform) ? { ...detail, fix: "give_back" } : detail;
+}
+
+/** The one refusal the panel can repair with a press (#1711): a settings folder
+ *  another user owns, on the platform whose password dialog can give it back.
+ *  Everywhere else the log's command is still the way out. */
+function givesBack({ owner, on }, platform) {
+  return platform === "darwin" && owner === "other" && on === "folder";
+}

package/src/server/prefs-routes.mjs

@@ -0,0 +1,99 @@
+// The deck's settings routes: GET /api/prefs, which answers what a page may see
+// of them and what the machine allows, and POST /api/prefs, which writes a
+// patch and hands the result to the LAN engine.
+//
+// These lived in src/server/index.mjs, beside the desktop notifier that reads
+// the same settings, and moved once the settings had (prefs-state.mjs) and the
+// engine had (lan-deck.mjs): what is left of them is a body read, a write
+// through the one, a push to the other, and an answer. The notifier stays in
+// index.mjs, beside the desktop-app connections it notifies through.
+import { notificationsOn, notificationsVetoed, prefsRefusalDetail, prefsWriteRefusal, publicPrefs } from "./deck-prefs.mjs";
+import { PRODUCT } from "./brand.mjs";
+import { heldPrefs } from "./prefs-state.mjs";
+import { applyLanPrefs, forgetReach, resetLanLoaded } from "./lan-deck.mjs";
+import { giveBackDeckFolders } from "./prefs-give-back.mjs";
+import { readBody, send } from "./http-io.mjs";
+
+/**
+ * GET the deck's settings, and what the machine is allowing.
+ *
+ * THREE fields, not two, and the third is the one a first attempt got wrong.
+ * `notificationsAllowed` is the effective answer, after the environment
+ * variable has had its say — but "false" there means either "the user switched
+ * it off" or "the machine forbids it", and the menu has to say a different
+ * sentence for each. Deriving the second from the first made the switch read
+ * "off — set at launch" the moment anybody turned it off on a deck launched
+ * with no variable at all, which is the deck telling the user their own press
+ * was somebody else's doing. `notificationsVetoed` answers only the machine's
+ * half.
+ */
+function prefsPayload() {
+  const prefs = heldPrefs.current();
+  return {
+    ok: true,
+    // `publicPrefs`, never the held prefs whole. This route answers anything
+    // that can reach the loopback port, and the LAN group passphrase is in the
+    // stored object — one field, and sending it here would put it in front of
+    // every page on the machine. What goes out is whether one is set.
+    prefs: publicPrefs(prefs),
+    notificationsAllowed: notificationsOn(prefs),
+    notificationsVetoed: notificationsVetoed(),
+  };
+}
+
+export function handlePrefsRead(req, res) {
+  return send(res, 200, prefsPayload());
+}
+
+/** POST a patch. Fields nobody sent keep their value — see writePrefs. */
+export async function handlePrefsWrite(req, res) {
+  const raw = await readBody(req, res).catch(() => null);
+  let body = null;
+  try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
+  if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+  try {
+    await heldPrefs.write(body);
+  } catch (err) {
+    // A settings file or folder this user cannot reach is the machine's to fix,
+    // not the deck's, and `guard`'s bare 500 left the panel with nothing to say
+    // about it (#1335). Anything else is still a bug and still goes to `guard`.
+    const reason = prefsWriteRefusal(err);
+    if (!reason) throw err;
+    console.error(`${PRODUCT}: settings were not saved:`, err?.message ?? err);
+    // What blocked it, from closed sets and without the path, so a screenshot
+    // of the panel is enough to tell the cases apart (#1335).
+    const detail = prefsRefusalDetail(err);
+    return send(res, 500, detail ? { ok: false, reason, detail } : { ok: false, reason });
+  }
+  // The engine reads its settings from here rather than holding its own copy,
+  // so turning the switch off in the panel really does stop the sockets rather
+  // than only changing what the panel says.
+  await applyLanPrefs();
+  // Somebody has just switched this on and is watching the panel for the answer
+  // to one question: is anything going to turn up. Whatever the probe said
+  // before is about a deck whose sockets were down — see forgetReach.
+  if (body.lan?.enabled === true) forgetReach();
+  return send(res, 200, prefsPayload());
+}
+
+/**
+ * POST: give the deck's settings folder back to this user, through macOS's own
+ * password dialog (#1711). No body — every path is the deck's own; see
+ * prefs-give-back.mjs.
+ *
+ * AND THEN READ THE FILE AGAIN, AS A BOOT WOULD. A deck that started on a folder
+ * it could not open is running on the defaults, and its LAN engine on a key it
+ * made up and could not keep. Once the file is readable that is the wrong deck:
+ * the settings are re-read, and the engine is handed the fields it authors off
+ * the file again — the stored key and pairings — which is what a restart would
+ * have done, without the restart.
+ */
+export async function handlePrefsGiveBack(req, res) {
+  const out = await giveBackDeckFolders();
+  if (!out.ok) return send(res, 409, { ok: false, reason: out.reason });
+  if ((await heldPrefs.reload()) === "file") {
+    resetLanLoaded();
+    await applyLanPrefs();
+  }
+  return send(res, 200, { ...prefsPayload(), changed: out.changed });
+}

package/src/server/prefs-set-aside.mjs

@@ -0,0 +1,86 @@
+// Moving a prefs.json nobody can use out of the way, before anything can write
+// over it: the bytes of a file that is not JSON (#1002), and a file another
+// user owns (#1335). Moved out of deck-prefs.mjs unchanged; loadPrefs decides
+// when, and this is how.
+import { stat } from "node:fs/promises";
+import { renameWithRetry } from "./atomic-write.mjs";
+import { deckDataDir } from "./deck-home.mjs";
+import { prefsDir, prefsPath } from "./prefs-path.mjs";
+
+/** Where the bytes of a prefs.json nothing could parse are put.
+ *
+ *  `Date.now()` rather than an ISO timestamp because a colon is not a legal
+ *  filename character on Windows, and a quarantine that cannot be created on
+ *  the platform it is protecting is not a quarantine. */
+export const quarantinePath = (home = deckDataDir(), at = Date.now()) =>
+  `${prefsPath(home)}.corrupt-${at}`;
+
+/** The read errors that can mean "not yours" rather than "broken". Only these
+ *  send a read to setAsideForeign; EISDIR, EIO and EMFILE never do. */
+export const DENIED = new Set(["EACCES", "EPERM"]);
+
+/** Where a prefs.json another user owns is put. Beside the file, like
+ *  quarantinePath, and stamped in milliseconds for the same Windows reason —
+ *  but a name of its own, because nothing is wrong with these bytes. */
+export const foreignPath = (home = deckDataDir(), at = Date.now()) =>
+  `${prefsPath(home)}.foreign-${at}`;
+
+/**
+ * Move a prefs.json that ANOTHER USER OWNS out of the way, or say why not.
+ *
+ * #1335. A `sudo ccdeck` that kept the user's HOME writes a root-owned 0600
+ * prefs.json into the user's own folder. From then on every
+ * deck that user starts is refused the read, refuses every settings write on
+ * top of it — rightly — and so can never keep anything: a new LAN identity on
+ * every start, a share tick that says "Could not share that account", and no
+ * way out from inside the deck.
+ *
+ * WHY MOVING IT IS SAFE HERE WHEN IT IS NOT FOR "unreadable". The refusal
+ * exists so the deck never loses a key it could still have read. A file owned
+ * by somebody else is not one this user's deck will ever read — waiting does
+ * not help, and the deck is already running on defaults. A rename reads and
+ * changes nothing: owner and mode travel with the file, so the key in it stays
+ * private and whole, and `sudo chown` plus a move puts it back.
+ *
+ * Only when the owner is KNOWN to be somebody else. A file this user owns and
+ * still cannot read (a mode bit, a lock, a sandbox) is left exactly where it
+ * is, and so is anything on Windows, where there is no uid to compare and
+ * EPERM is usually another program holding the file.
+ *
+ * Answers `{ moved, uid }`, `{ gone }` when the file vanished under it, or,
+ * when it stayed, `{ why, owner, on }`: a sentence for the log, possibly empty,
+ * and who owns what blocked the read — "you", "other" or "unknown" — and
+ * whether that is the "file" or its "folder". The last two are what the panel
+ * is told (see prefsRefusalDetail); the sentence, which has the path, is not.
+ */
+export async function setAsideForeign(path, home, deps) {
+  const uid = deps.getuid ? deps.getuid() : process.getuid?.();
+  if (uid === undefined) return { why: "", owner: "unknown", on: "file" };
+  const look = deps.stat ?? stat;
+  let st;
+  try {
+    st = await look(path);
+  } catch (err) {
+    if (err?.code === "ENOENT") return { gone: true };
+    // The folder itself is out of reach, so nothing in it can be looked at, let
+    // alone moved. Name the folder and its owner, which is what a person needs.
+    const folder = prefsDir(home);
+    const owner = await look(folder).then(s => s.uid, () => undefined);
+    if (owner === undefined) return { why: "", owner: "unknown", on: "folder" };
+    if (owner === uid) return { why: "", owner: "you", on: "folder" };
+    return {
+      why: ` The folder ${folder} belongs to another user (uid ${owner}), most likely from a run with sudo; sudo chown -R "$(id -un)" "${folder}" gives it back.`,
+      owner: "other",
+      on: "folder",
+    };
+  }
+  if (st.uid === uid) return { why: "", owner: "you", on: "file" };
+  const to = foreignPath(home);
+  try {
+    await (deps.rename ?? renameWithRetry)(path, to);
+  } catch (err) {
+    if (err?.code === "ENOENT") return { gone: true };
+    return { why: ` It belongs to another user (uid ${st.uid}) and could not be moved aside either: ${err?.message ?? err}.`, owner: "other", on: "file" };
+  }
+  return { moved: to, uid: st.uid };
+}

package/src/server/prefs-state.mjs

@@ -0,0 +1,70 @@
+// The deck's settings as this process holds them: the one in-memory copy every
+// reader asks, and the one place a write's answer is kept.
+//
+// This was `let _prefs` in src/server/index.mjs, and it is the reason the LAN
+// section could not leave that file. The notifier and the away-update read it;
+// the settings route, the LAN peer route and six of the LAN engine's callbacks
+// each assigned it back with `_prefs = await writePrefs(...)`; and a
+// module-level `let` is one no other module can assign. So the variable moved
+// first, behind the three things its callers actually do with it: read it,
+// write a patch, and compute a patch from the file. Every write now goes
+// through here, which is also what keeps the promise the comment below has
+// always made — that the copy and the file cannot drift within one process —
+// true by construction rather than by every caller remembering the assignment.
+//
+// The disk half is deck-prefs.mjs, unchanged: the queue, the merge and the
+// refusal to write over a file it could not read all live there. This holds
+// what they return and nothing else.
+import { DEFAULTS, loadPrefs, loadPrefsInTurn, updatePrefs, writePrefs } from "./deck-prefs.mjs";
+
+/**
+ * The deck's own settings, in memory, refreshed whenever they are written.
+ *
+ * Read once at boot and then kept here rather than read per event: `consider`
+ * is on the ingest path every hook event goes through, and a file read there
+ * would be a syscall per event to answer a question that changes when somebody
+ * presses a switch. The write path below updates this, so the in-memory copy
+ * and the file cannot drift within one process — and a second deck writing the
+ * file is picked up on ITS next write or this one's next boot, which is the
+ * same freshness every other cross-deck setting has.
+ */
+let _prefs = { ...DEFAULTS };
+/** Whether the boot read failed on a file that is still there (#1711): the
+ *  copy here is the defaults, and the file holds settings — the LAN key, the
+ *  pairings — this process never saw. Only a re-read that finds the file clears
+ *  it. A write that lands first merges onto the file, but leaves the engine on
+ *  what it made up, so it does not count. */
+let _unread = false;
+
+// Read at import, so `consider` has its answer from the first event. LAN sync
+// used to start from this same read, and it must not: bin/deck.js imports the
+// server module to ASK whether a deck is already up, and a launcher that then
+// attaches and exits had already bound the beacon and the sync port on the way
+// in — which is the `lan sync (listen): EADDRINUSE` line a second `ccdeck`
+// printed above `deck already running`. The engine starts from the listen that
+// succeeds, in startServer, which is the only process that may hold a port.
+export const prefsRead = loadPrefs().then(r => { _prefs = r.prefs; _unread = r.source === "unreadable"; }).catch(() => {});
+
+export const heldPrefs = Object.freeze({
+  /** What the last read or write left here. Never a disk read — see above. */
+  current: () => _prefs,
+  /** `writePrefs(patch)`, and keep what it wrote. A write that throws keeps
+   *  nothing, so the copy is never ahead of the file. */
+  write: async patch => (_prefs = await writePrefs(patch)),
+  /** `updatePrefs(mutate)`, and keep what it wrote: for a patch that has to be
+   *  computed from the file rather than from `current()` — see updatePrefs. */
+  update: async mutate => (_prefs = await updatePrefs(mutate)),
+  /** Read the file again, as a boot would, once something outside the deck has
+   *  made it readable (#1711) — and only for a deck whose boot read could not.
+   *  Any other deck is left alone and answers "held": re-reading it would race
+   *  the engine's own writes for nothing. Otherwise the read waits its turn
+   *  behind the writes, and is kept only when it really is the user's file; a
+   *  read that still fails leaves the copy this process was running on.
+   *  Answers "held", or the read's `source`. */
+  reload: async () => {
+    if (!_unread) return "held";
+    const { prefs, source } = await loadPrefsInTurn();
+    if (source === "file") { _prefs = prefs; _unread = false; }
+    return source;
+  },
+});