ccdeck 3.30.0 → 3.32.0

package/dist/web/index.html

@@ -62,8 +62,8 @@
           stored === "light" || (stored !== "dark" && light) ? "light" : "dark");
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-BVTWHDta.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-3vS6A0vt.css">
+    <script type="module" crossorigin src="/assets/index-DiTUBs9l.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DKn7nc15.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccdeck",
-  "version": "3.30.0",
+  "version": "3.32.0",
   "description": "Live dashboard for Claude Code and Codex — which agent is waiting on you, tool calls, token spend and every Claude Code subagent on one calm canvas. Run it with npx ccdeck.",
   "type": "module",
   "bin": {

package/release-notes.json

@@ -59,6 +59,30 @@
     "3.29.7",
     "3.29.9"
   ],
+  "3.32.0": [
+    {
+      "title": "🗺️ A map of your network",
+      "body": "A new button on the Local network row, and in its view's header, opens a map of every deck around this one. This deck is at the centre and the paired decks that are on stand around it. Further out are the quiet ones, the machines nearby and any deck asking to pair. Wires are solid on your local network and dashed over Tailscale. Pointing at a deck says how it is reached, what it runs and which logins the two share, and pressing it opens that deck's own dialog."
+    }
+  ],
+  "3.31.0": [
+    {
+      "title": "📊 Account capacity",
+      "body": "A gauge button in the accounts panel's header opens Account capacity: how many of your Claude accounts are ready now, what the 5-hour and 7-day windows have left across all of them, and a row for each account with its use, its state (Ready, Limited, Exhausted or Stale) and when it was last read. Each window also says whose reset comes next."
+    },
+    {
+      "title": "🚦 Claude and Codex incidents",
+      "body": "When Anthropic's or OpenAI's status page reports an incident on something your sessions use, the deck says so in the topbar, the Usage panel and the tray, and every mark links to the status page. A provider with nothing wrong draws nothing."
+    },
+    {
+      "title": "↕️ Order your other accounts",
+      "body": "The Other accounts row can sort the list by slot, by how full a window is, or by most room, and open every account at once. Both stay as you left them after a reload."
+    },
+    {
+      "title": "🔐 A settings folder left by sudo can be given back",
+      "body": "On a Mac, running ccdeck once with sudo left its settings folder owned by another user, and every settings change was refused, sharing an account included. The message now offers \"give it back\": macOS asks for your password, the folder is yours again, and the deck reads its settings back without a restart."
+    }
+  ],
   "3.30.0": [
     {
       "title": "🧮 Token counts and costs are no longer doubled",

package/src/server/claude-dir.mjs

@@ -29,8 +29,12 @@ import { join, resolve, posix as posixPath, win32 as winPath } from "node:path";
  * The environment and the home directory are parameters purely so callers that
  * are already working from an injected environment can stay consistent with it;
  * every caller in the deck passes nothing and gets the real machine's answer.
+ * `platform` is the same kind of parameter: the answer for another platform's
+ * paths, joined with that platform's separator, which is what legacyDeckDir
+ * needs to be checked for a Mac on a Windows runner (#1711).
  */
-export function claudeConfigDir(env = process.env, home = homedir()) {
+export function claudeConfigDir(env = process.env, home = homedir(), platform = process.platform) {
+  const { join, resolve } = platform === "win32" ? winPath : posixPath;
   const override = env.CLAUDE_CONFIG_DIR?.trim();
   return override ? resolve(override) : join(home, ".claude");
 }

package/src/server/deck-home.mjs

@@ -61,7 +61,7 @@ const HOME_ENV = "CCDECK_HOME";
  *  live. Also the place a migration reads from. */
 export function legacyDeckDir(env = process.env, home = homedir(), platform = process.platform) {
   const { join } = platform === "win32" ? winPath : posixPath;
-  return join(claudeConfigDir(env, home), "agent-dag");
+  return join(claudeConfigDir(env, home, platform), "agent-dag");
 }
 
 /**

package/src/server/deck-prefs.mjs

@@ -472,6 +472,13 @@ export function withAlias(fp, name) {
   };
 }
 
+/** loadPrefs, behind every write already queued (#1711): a re-read that lands
+ *  between a write's read and its rename, or that answers with a copy older
+ *  than a write that finished first, is a copy the next write merges onto. */
+export function loadPrefsInTurn(home = deckDataDir(), deps = {}) {
+  return queued(() => loadPrefs(home, deps));
+}
+
 /** One read-modify-write, behind every other one. Both entry points go through
  *  here so there is a single queue and a single merge. */
 function queued(job) {

package/src/server/index.mjs

@@ -134,7 +134,7 @@ import { applyLanPrefs, resetLanLoaded } from "./lan-deck.mjs";
 // The Local network panel's four routes — see lan-routes.mjs.
 import { handleLanInvite, handleLanPeer, handleLanStatus, handleLanSync } from "./lan-routes.mjs";
 // GET and POST /api/prefs — see prefs-routes.mjs.
-import { handlePrefsRead, handlePrefsWrite } from "./prefs-routes.mjs";
+import { handlePrefsGiveBack, handlePrefsRead, handlePrefsWrite } from "./prefs-routes.mjs";
 import { MANIFEST_PATH, offerManifest } from "./app-manifest.mjs";
 import { historySnapshot, readProcesses, startSystemMetrics, systemSnapshot } from "./system-metrics.mjs";
 // How every route reads a body and answers, and the answer for one that threw
@@ -150,7 +150,7 @@ import { handleBrowserWatch, handleBrowserWatchDismiss, handleBrowserWatchSettin
 // The music routes, every one behind AGENTS_DECK_NO_MUSIC — see music-routes.mjs.
 import { handleBestOfNostalgia, handleCafeMusicBgm, handleClaudeFm, handleFmStation, handleGoodLifeRadio, handleLiveRadioMix, handleLofiGirl } from "./music-routes.mjs";
 // The usage panel's quota and history reads — see usage-routes.mjs.
-import { handleCcusage, handleCodexQuota, handleCodexUsage, handleQuota } from "./usage-routes.mjs";
+import { handleCcusage, handleCodexQuota, handleCodexUsage, handleProviderStatus, handleQuota } from "./usage-routes.mjs";
 // The port fallback, one listen attempt, and the words for a failed one — see
 // listen.mjs. The loop that uses them is startServer's.
 import { listenFailure, portRetryable, randomPort, tryListen } from "./listen.mjs";
@@ -293,6 +293,7 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "POST" && url.pathname === "/api/lan/invite")   return guard(handleLanInvite(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/lan/sync")     return guard(handleLanSync(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/prefs")        return guard(handlePrefsWrite(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/prefs/give-back") return guard(handlePrefsGiveBack(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/system")       return send(res, 200, systemSnapshot());
     // On demand only — the process list costs a subprocess on every platform,
     // so it is fetched while the detail panel is open and never on the timer.
@@ -327,6 +328,7 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     }
     if (req.method === "GET"  && url.pathname === "/api/codex-quota") return guard(handleCodexQuota(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/ccusage")     return guard(handleCcusage(req, res), res);
+    if (req.method === "GET"  && url.pathname === "/api/provider-status") return guard(handleProviderStatus(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/browser-watch") return guard(handleBrowserWatch(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/browser-watch") return guard(handleBrowserWatchSettings(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/browser-watch/dismiss") return guard(handleBrowserWatchDismiss(req, res), res);

package/src/server/pinned-build.mjs

@@ -82,6 +82,8 @@ const PINNED_MODULES = [
   "account-projects.mjs",
   "swap-log.mjs",
   "lan-sync.mjs",
+  // The providers' status pages (#1311), reached only from their route.
+  "provider-status.mjs",
 ];
 
 let _pinned = null;

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-refusal.mjs

@@ -62,16 +62,25 @@ const ERRNO = /^E?[A-Z][A-Z0-9]{1,15}$/;
  *
  * 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.
+ * 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) {
+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;
-  return {
+  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

@@ -10,7 +10,8 @@
 import { notificationsOn, notificationsVetoed, prefsRefusalDetail, prefsWriteRefusal, publicPrefs } from "./deck-prefs.mjs";
 import { PRODUCT } from "./brand.mjs";
 import { heldPrefs } from "./prefs-state.mjs";
-import { applyLanPrefs, forgetReach } from "./lan-deck.mjs";
+import { applyLanPrefs, forgetReach, resetLanLoaded } from "./lan-deck.mjs";
+import { giveBackDeckFolders } from "./prefs-give-back.mjs";
 import { readBody, send } from "./http-io.mjs";
 
 /**
@@ -74,3 +75,25 @@ export async function handlePrefsWrite(req, res) {
   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-state.mjs

@@ -15,7 +15,7 @@
 // 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, readPrefs, updatePrefs, writePrefs } from "./deck-prefs.mjs";
+import { DEFAULTS, loadPrefs, loadPrefsInTurn, updatePrefs, writePrefs } from "./deck-prefs.mjs";
 
 /**
  * The deck's own settings, in memory, refreshed whenever they are written.
@@ -29,6 +29,12 @@ import { DEFAULTS, readPrefs, updatePrefs, writePrefs } from "./deck-prefs.mjs";
  * 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
@@ -37,7 +43,7 @@ let _prefs = { ...DEFAULTS };
 // 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 = readPrefs().then(p => { _prefs = p; }).catch(() => {});
+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. */
@@ -48,4 +54,17 @@ export const heldPrefs = Object.freeze({
   /** `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;
+  },
 });