@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/timeouts.ts

@@ -0,0 +1,76 @@
+// timeouts.ts — the per-command time budgets, split out of server-core.ts (same reason as
+// staleness.ts): figma-pull.ts's exported, test-driven parseArgs (and read-plan.ts) pick their budgets from this table,
+// and it need not load the whole bridge core just to read two constants. No load-time effects. Every caller imports
+// them from here.
+import { ALLOWED_PORTS } from "./ports.ts";
+
+// Per-COMMAND time budgets, in ONE table. The budget is a property of the work, not of the caller, so
+// both front-ends (figma-pull CLI, figma-mcp) read it from here instead of restating the tiers — a
+// fourth caller would otherwise inherit `command` again, which is the 120s default tuned for
+// ping/getSelection and far too small for anything that walks a page.
+//   selection  — one hand-picked selection (small by construction)
+//   list       — cheap RELATIVE to an export, not fast: depth 2 loads EVERY page, which Figma's own
+//                docs call "slow for large documents". The tool you're told to call FIRST must not be
+//                the first to fail on exactly the large files where looking before you pull matters.
+//   export     — one page / one node: found the hard way on a ~1000-node file.
+//   exportAll  — whole file / --all-pages: measured >15 min on a real 25-page file.
+export const TIMEOUTS = { command: 120000, selection: 120000, list: 300000, export: 300000, exportAll: 900000 };
+
+// The scope -> tier RULE is read-plan.ts's (with the rest of what a read sends): hoisting only the numbers
+// still left both front-ends restating which tier an export picks, and they had already drifted once (the
+// MCP copy omitted the selection tier).
+
+// How often the bridge pings each connected plugin socket, and so how long a silently dead one (a
+// laptop lid closed mid-session, a pulled cable, a renderer that vanished without a FIN) can sit in the
+// client registry looking live: a client that has not answered the PREVIOUS ping when the next tick
+// fires is terminated, so detection takes between one and two intervals. 30 s is the interval of the
+// ws README's own "How to detect and close broken connections?" example. Browsers answer pings in the
+// network stack without involving page script, so a plugin busy with a long export still answers.
+// createBridge's `heartbeatMs` option overrides it (the test suite uses a short one).
+export const HEARTBEAT_MS = 30000;
+
+// How long a NAMED --client target (file name / fileKey, not a c<N> connId) is waited for after the
+// first plugin connects. Every open plugin window redials every PLUGIN_REDIAL_MS, one port at a time, so
+// a file that is open lands within one walk of the three ports (3 s); 15 s is five such walks — room for
+// a window Figma throttles in the background — and a name that never matches fails with the connected
+// list instead of holding the terminal for the whole connect window.
+export const NAMED_CLIENT_WAIT_MS = 15000;
+
+// The longest delay one setTimeout holds: "When delay is larger than 2147483647 or less than 1, the delay
+// will be set to 1" (nodejs.org/api/timers.html#settimeoutcallback-delay-args), so a longer wait would
+// fire at once — or, re-armed, spin. Every wait or guard built from a caller's number stays within it.
+export const MAX_TIMER_MS = 2147483647;
+
+// How often an open plugin window redials a bridge it has lost or not found yet: figma-plugin ui.template.html
+// REDIAL_MS (scheduleReconnect's `ms || REDIAL_MS`; test/ui.test.ts pins the two together), one port of
+// the three per attempt (connect() walks BRIDGE_PORTS on every failed dial), so a window that keeps
+// missing comes back to the same port every 3 s.
+export const PLUGIN_REDIAL_MS = 1000;
+
+// How long a bridge whose plugins have only just started connecting holds a request that does not name
+// one file by connId or fileKey (no target, or a file name — names repeat and match as substrings) before
+// routing it. Two open files redial on their own clocks, so right after a bridge starts, whichever lands
+// first is all there is for a moment — and an unaddressed (or half-addressed) command would silently go to
+// that file instead of being refused as ambiguous. A second window can be anywhere in its walk of the
+// three ports, so it reaches this bridge's port up to one full walk (3 × PLUGIN_REDIAL_MS) after the
+// first; that plus a margin for its `hello` covers every window that is redialling normally, for 3.5 s
+// on an unaddressed one-shot command. The walk assumes a refused dial fails at once, as it does on macOS
+// and Linux; on Windows a refused localhost connect can take about 2 s, so a walk there is longer and the
+// settle covers less of it. A window Figma throttles in the background can still land later.
+// Counted from the moment the bridge went from no plugin to one, and restarted when a plugin leaves while
+// others stay (it is probably redialling), so a bridge whose plugins have been connected for longer (a
+// daemon, a long MCP session) pays nothing until one of them leaves; a connId or fileKey is routed at
+// once. A request's own connect window cannot cut the settle short.
+export const SETTLE_MS = ALLOWED_PORTS.length * PLUGIN_REDIAL_MS + 500;
+
+// The client-side guard on a request sent through a daemon: every phase the daemon's bridge may spend on it — the
+// connect window, then at most NAMED_CLIENT_WAIT_MS for a named target (server-core awaitClient); a wait in the plugin's
+// queue behind an earlier run in that file (figma-plugin state.ts scheduleRun), bounded by the command timeout armed
+// at send; then the run itself, given the whole command timeout again when it starts (server-core re-arms it on the
+// request's `start` frame) — and a margin (it also absorbs the settle, SETTLE_MS), so the daemon's own, clearer error
+// normally lands before the guard does. Two command timeouts, because a request that takes no progress never relays
+// that `start` to the guard (one that does re-arms the guard on every frame instead, as above). Not always first: the
+// MAX_TIMER_MS cap below can cut the sum short.
+// Capped at MAX_TIMER_MS: the guard is one setTimeout, which runs a longer delay after 1 ms.
+export const daemonGuardMs = (timeoutMs: number, connectWaitMs: number = 0): number =>
+  Math.min(2 * timeoutMs + connectWaitMs + Math.min(connectWaitMs, NAMED_CLIENT_WAIT_MS) + 30000, MAX_TIMER_MS);

package/src/timings.ts

@@ -0,0 +1,118 @@
+// timings.ts — the opt-in stage record of one dtwin command, for profiling rather than for a user: set
+// DTWIN_TIMINGS=1 (one JSON line on stderr) or DTWIN_TIMINGS=<file> (appended to that file as JSON Lines).
+//
+// The closing `done in …` line already splits a command into connect / export / write, but "export" is one number for
+// everything between the request leaving and the reply landing: a run queued behind another export in that file, the
+// plugin's page walk, its catalogue build, its render pass and the transfer all fall in it. The plugin's progress
+// ticks (server-core.ts ProgressTick) already arrive per phase, so their arrival times split that span without a
+// protocol change: `phases[]` says when each phase was first and last heard, measured on this side (transport latency
+// included). `queueMs` is the time to the first tick of any phase other than `queued`, when the run was queued.
+//
+// What is recorded is counts, sizes and times only — phase names, page index/of, node and asset counters, payload
+// bytes, peak RSS. Never a page or layer name, a file name or key, a token, or document content.
+//
+// Measured with performance.now() (monotonic); peak RSS from process.resourceUsage().maxRSS (kilobytes on every
+// platform Bun supports, per Node's documentation of the field — converted to bytes here).
+import fs from "node:fs";
+import { errMsg } from "./errmsg.ts";
+
+export const TIMINGS_ENV = "DTWIN_TIMINGS";
+export const TIMINGS_SCHEMA = "designtwin/timings@1";
+
+/** Where a record goes: stderr ("1"/"true"), a file path (anything else non-empty), or nowhere (unset, "", "0"). */
+export function timingsTarget(env: Record<string, string | undefined> = process.env): "stderr" | { file: string } | null {
+  const v = (env[TIMINGS_ENV] ?? "").trim();
+  if (!v || v === "0" || v.toLowerCase() === "false") return null;
+  return v === "1" || v.toLowerCase() === "true" ? "stderr" : { file: v };
+}
+
+export interface PhaseSpan { phase: string; firstMs: number; lastMs: number; ticks: number }
+/** The asset payload of a reply: how many assets and their decoded bytes (base64 counted as the bytes it decodes to). */
+export interface PayloadStats { assets: number; assetBytes: number; nodes: number | null }
+export interface StageRecord {
+  schema: typeof TIMINGS_SCHEMA;
+  command: string;
+  viaDaemon: boolean;
+  totalMs: number; connectMs: number; exportMs: number; writeMs: number;
+  /** request sent → first tick of a phase other than `queued`; null when the run was never queued */
+  queueMs: number | null;
+  phases: PhaseSpan[];
+  requests: number;
+  payload: PayloadStats | null;
+  peakRssBytes: number | null;
+}
+
+const round1 = (ms: number): number => Math.round(ms * 10) / 10;
+
+/** Decoded byte length of a base64 string without decoding it. */
+export function base64Bytes(b64: string): number {
+  const n = b64.length;
+  if (!n) return 0;
+  const pad = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+  return Math.floor((n * 3) / 4) - pad;
+}
+
+/** PayloadStats of one reply (read defensively: it is the plugin's JSON). null when it carries no `assets` array. */
+export function payloadStats(result: unknown): PayloadStats | null {
+  if (!result || typeof result !== "object") return null;
+  const r = result as { assets?: unknown; manifest?: { nodes?: unknown }; screen?: { manifest?: { nodes?: unknown } } };
+  if (!Array.isArray(r.assets)) return null;
+  let assetBytes = 0;
+  for (const a of r.assets as Array<{ base64?: unknown; text?: unknown } | null>) {
+    if (!a) continue;
+    if (typeof a.text === "string") assetBytes += Buffer.byteLength(a.text, "utf8");
+    else if (typeof a.base64 === "string") assetBytes += base64Bytes(a.base64);
+  }
+  const nodes = r.screen?.manifest?.nodes ?? r.manifest?.nodes;
+  return { assets: r.assets.length, assetBytes, nodes: typeof nodes === "number" ? nodes : null };
+}
+
+/** The clock of one command: started at creation; fed every request, reply and progress tick. */
+export interface StageClock {
+  sent(): void;
+  replied(result: unknown): void;
+  tick(phase: string | null): void;
+  record(o: { command: string; viaDaemon: boolean; connectMs: number; exportMs: number; writeMs: number }): StageRecord;
+}
+
+export function stageClock(now: () => number = () => performance.now(), rss: () => number | null = peakRss): StageClock {
+  const t0 = now();
+  const phases = new Map<string, PhaseSpan>();
+  let firstSent: number | null = null, queued = false, queueMs: number | null = null, requests = 0;
+  let payload: PayloadStats | null = null;
+  return {
+    sent() { requests++; if (firstSent === null) firstSent = now() - t0; },
+    replied(result) {
+      const p = payloadStats(result);
+      if (!p) return;
+      payload = payload ? { assets: payload.assets + p.assets, assetBytes: payload.assetBytes + p.assetBytes, nodes: p.nodes ?? payload.nodes } : p;
+    },
+    tick(phase) {
+      const at = now() - t0;
+      const name = phase || "unnamed";
+      if (name === "queued") queued = true;
+      else if (queued && queueMs === null && firstSent !== null) queueMs = round1(at - firstSent);
+      const s = phases.get(name);
+      if (s) { s.lastMs = round1(at); s.ticks++; } else phases.set(name, { phase: name, firstMs: round1(at), lastMs: round1(at), ticks: 1 });
+    },
+    record(o) {
+      return {
+        schema: TIMINGS_SCHEMA, command: o.command, viaDaemon: o.viaDaemon,
+        totalMs: round1(now() - t0), connectMs: round1(o.connectMs), exportMs: round1(o.exportMs), writeMs: round1(o.writeMs),
+        queueMs, phases: [...phases.values()], requests, payload, peakRssBytes: rss(),
+      };
+    },
+  };
+}
+
+function peakRss(): number | null {
+  try { return process.resourceUsage().maxRSS * 1024; } catch { return null; }
+}
+
+/** Write one record to its target. A file that cannot be appended to is said on stderr, never thrown: a profiling
+ *  aid must not fail the command it measures. */
+export function emitTimings(rec: StageRecord, target: "stderr" | { file: string }, err: (s: string) => void = (s) => console.error(s)): void {
+  const line = JSON.stringify(rec);
+  if (target === "stderr") { err("[dtwin] timings " + line); return; }
+  try { fs.appendFileSync(target.file, line + "\n"); } catch (e) { err(`[dtwin] ${TIMINGS_ENV}: could not append to ${target.file} (${errMsg(e)})`); }
+}

package/src/token-store.ts

@@ -0,0 +1,261 @@
+// Where the bridge token LIVES between runs — the one place that knows the path, the precedence,
+// and the file's permissions.
+//
+// The token is not env-var-or-nothing: `server-core.ts` reads FIGMA_BRIDGE_TOKEN, and minting a fresh
+// random one PER RUN and printing it would leave the plugin's saved token wrong on the very next `dtwin`,
+// so the user would re-paste forever. The fix is not a better banner, it's persistence: generate once,
+// store it, reuse it.
+//
+// Deliberately dependency-free. `env-paths` is the usual answer for per-OS config dirs, but the logic is
+// ~15 lines, so it lives here rather than costing a dependency.
+//
+// Not a `.env` file either: a project-local `.env` would be the wrong CONVENTION — `.env` is for the
+// secrets of the app you are building, not for a tool's own credential, and putting it in the repo makes "did we gitignore it" a permanent live footgun.
+// Real CLIs (gh, wrangler, vercel) keep their own auth in a user config dir. So do we.
+//
+// Not the OS keychain either: keytar is archived, and its live replacements (@napi-rs/keyring,
+// keyring-node) are native binaries with per-platform install friction. That is disproportionate for
+// a loopback-only token that grants no authority beyond "drive a Figma plugin the same user already
+// has open". The honest limit of the 0600 file, stated so it isn't a surprise: it stops OTHER users
+// on the machine, not another process running as YOU.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { writeFileAtomic } from "./atomic-write.ts";
+import { sha256Hex } from "./hash.ts";
+import { errMsg } from "./errmsg.ts";
+
+/** Where the token in play came from. "ephemeral" = minted for this run only, never stored. */
+export type TokenSource = "token-file" | "env" | "file" | "ephemeral";
+
+/** What resolve() returns. `path` is the file the token lives in (null for env/ephemeral). */
+export interface ResolvedToken {
+  token: string;
+  source: TokenSource;
+  path: string | null;
+  /** true only on the run that minted AND stored a new token */
+  created: boolean;
+  /** why a minted token could not be stored (the result is then "ephemeral") */
+  persistError?: unknown;
+}
+
+export interface ResolveOptions {
+  tokenFile?: string | null;
+  persist?: boolean;
+}
+
+/** What --token-status prints: everything about the token except the token. */
+export interface TokenStatus {
+  path: string;
+  stored: boolean;
+  envSet: boolean;
+  activeSource: TokenSource;
+  fingerprint: string | null;
+  loosePerms: boolean;
+  shadowed: boolean;
+}
+
+const APP = "design-twin";
+const FILE = "bridge-token";
+
+// 24 bytes = 192 bits from the OS CSPRNG, hex-encoded. Matches what server-core minted before.
+export const generate = (): string => crypto.randomBytes(24).toString("hex");
+
+// Per-OS config directory.
+//
+// macOS gets ~/.config, NOT ~/Library/Application Support: `gh` does the same, and the Apple location
+// is really for plist-shaped data managed by `defaults`, not a hand-editable secret a user may well
+// want to `cat`. Honouring XDG_CONFIG_HOME when it is set also gives the Linux-conventions-on-macOS
+// crowd what they expect.
+//
+// DESIGNTWIN_CONFIG_DIR overrides everything — the tests need a config dir that is not the real
+// user's, and a container/CI run may want one explicitly.
+export function configDir(): string {
+  const override = process.env.DESIGNTWIN_CONFIG_DIR;
+  if (override && path.isAbsolute(override)) return override;
+
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (appData && path.isAbsolute(appData)) return path.join(appData, APP);
+    return path.join(os.homedir(), "AppData", "Roaming", APP);
+  }
+  // The XDG spec is explicit that a RELATIVE value here is invalid and must be ignored rather than
+  // resolved against cwd — otherwise the token file's location would depend on where you ran dtwin.
+  const xdg = process.env.XDG_CONFIG_HOME;
+  if (xdg && path.isAbsolute(xdg)) return path.join(xdg, APP);
+  return path.join(os.homedir(), ".config", APP);
+}
+
+export const tokenPath = (): string => path.join(configDir(), FILE);
+
+// A stable, non-secret way to say "the same token?" in logs, `--token-status`, and a 401 hint.
+// Truncated SHA-256, never the token itself — the whole point of persisting is to stop printing it.
+export const fingerprint = (tok: unknown): string | null => (tok ? sha256Hex(String(tok)).slice(0, 8) : null);
+
+// Read one token from a path. Trims: a token written with `echo tok > file` carries a trailing
+// newline, which would otherwise fail the handshake with a "bad token" that looks nothing like the
+// whitespace bug it is. Returns null for missing/empty/unreadable rather than throwing — every
+// caller's next move is "fall through to the next source".
+export function readFrom(file: string): string | null {
+  try {
+    const raw = fs.readFileSync(file, "utf8").trim();
+    return raw || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+// Is the file readable by anyone but the owner? POSIX only: on Windows the mode bits are not
+// meaningful (%APPDATA% is already per-user by ACL), so reporting on them would be a warning the
+// user cannot act on.
+export function loosePerms(file: string): boolean {
+  if (process.platform === "win32") return false;
+  try {
+    return (fs.statSync(file).mode & 0o077) !== 0;
+  } catch (e) {
+    return false;
+  }
+}
+
+// Write atomically, owner-only.
+//
+// tmp + rename (atomic-write.ts) because a token half-written by an interrupted run is worse than no token
+// at all: it would fail every handshake with a 401 until someone thought to look at the file. The 0600 mode
+// is set on the tmp file before the rename, so the token is never visible with wider permissions.
+export function write(token: string, file: string = tokenPath()): string {
+  const dir = path.dirname(file);
+  // 0700: the XDG spec asks for exactly this when creating a config dir that does not exist.
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileAtomic(file, token + "\n", { mode: 0o600 });
+  return file;
+}
+
+export function remove(file: string = tokenPath()): boolean {
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch (e) {
+    return false; // already gone — `--forget-token` twice is not an error
+  }
+}
+
+// THE precedence chain, in one place: explicit flag > environment > stored file > mint a new one.
+//
+// Order follows the usual CLI layering (flag beats env beats persisted config beats default). Env
+// stays ABOVE the file so CI and one-off overrides keep working unchanged, and so anyone who already
+// exported FIGMA_BRIDGE_TOKEN is unaffected by this file existing.
+//
+// Note there is deliberately no `--token <value>` flag anywhere in the CLI, only `--token-file`:
+// process arguments are world-readable via `ps` / /proc/<pid>/cmdline, so a value flag would leak the
+// secret to every other user on the machine.
+//
+// `persist: false` lets a caller ask "what WOULD be used" without creating a file as a side effect —
+// which is what --token-status needs.
+export function resolve({ tokenFile = null, persist = true }: ResolveOptions = {}): ResolvedToken {
+  if (tokenFile) {
+    const tok = readFrom(tokenFile);
+    if (!tok) {
+      const err: Error & { code?: string } = new Error(`--token-file ${tokenFile}: not readable, or empty.`);
+      err.code = "TOKEN_FILE_UNREADABLE";
+      throw err;
+    }
+    return { token: tok, source: "token-file", path: tokenFile, created: false };
+  }
+
+  const fromEnv = (process.env.FIGMA_BRIDGE_TOKEN || "").trim();
+  if (fromEnv) return { token: fromEnv, source: "env", path: null, created: false };
+
+  const file = tokenPath();
+  const stored = readFrom(file);
+  if (stored) return { token: stored, source: "file", path: file, created: false };
+
+  const token = generate();
+  if (!persist) return { token, source: "ephemeral", path: null, created: false };
+  try {
+    write(token, file);
+    return { token, source: "file", path: file, created: true };
+  } catch (e) {
+    // Read-only filesystem, no HOME, a locked-down container. Falling back to a per-run token keeps
+    // the bridge USABLE instead of failing to start over a convenience feature —
+    // the caller reports why so it isn't a silent downgrade.
+    return { token, source: "ephemeral", path: null, created: false, persistError: e };
+  }
+}
+
+/** What committing a token on its first use did (commit). */
+export interface CommittedToken {
+  /** the token as every later use should see it: a minted one now the saved file's, or kept ephemeral with why */
+  resolved: ResolvedToken;
+  /** this commit minted it (saved or not) — the one time the token itself is printed */
+  minted: boolean;
+  /** the mint could not be saved: it changes every run */
+  saveFailed: boolean;
+  /** what to tell the user, one line each */
+  notice: string[];
+}
+
+// THE first use of a resolved token: save it when nothing has (resolve() with persist:false leaves a minted token
+// "ephemeral"), and say which token is in play.
+//
+// The token itself is printed ONCE — on the commit that mints it — and never again. It is stable from here on, the
+// plugin has it saved in clientStorage, and reprinting a live secret into terminal scrollback on every single run is
+// exactly the habit this store exists to end. `--show-token` reveals it on demand; `--token-status` answers "which one
+// is in play" without disclosing it. Committing again what a commit returned saves and prints nothing new.
+// It expects an UNSAVED resolution (resolve() with persist:false, as settings.ts does) or its own output: a token resolve()
+// minted with persist:true and failed to save carries persistError already, and is taken as reported — its paste line
+// is resolve()'s caller's to print.
+export function commit(t: ResolvedToken, file: string = tokenPath()): CommittedToken {
+  const fp = fingerprint(t.token);
+  if (t.source === "ephemeral" && t.persistError === undefined) {
+    const paste = "auth token (paste into the plugin's \"Bridge token\" field): " + t.token;
+    try {
+      write(t.token, file);
+      return {
+        resolved: { ...t, source: "file", path: file, created: true }, minted: true, saveFailed: false,
+        notice: [paste, `saved to ${file} — you won't be asked to paste it again.`, "see it later with `dtwin --show-token`; replace it with `dtwin --rotate-token`."],
+      };
+    } catch (e) {
+      // Couldn't persist (read-only FS, no HOME, locked-down container). Still works — but say so, because the user
+      // WILL have to paste again next run and deserves to know why.
+      return {
+        resolved: { ...t, persistError: e }, minted: true, saveFailed: true,
+        notice: [paste, `could not save it (${errMsg(e)}) — it changes every run. Set FIGMA_BRIDGE_TOKEN to a stable value instead.`],
+      };
+    }
+  }
+  const done = (...notice: string[]): CommittedToken => ({ resolved: t, minted: false, saveFailed: false, notice });
+  if (t.source === "token-file") return done(`auth: token read from ${t.path} (${fp}).`);
+  if (t.source === "env") return done(`auth: using FIGMA_BRIDGE_TOKEN from the environment (${fp}).`);
+  if (t.source === "ephemeral") return done(`auth: using this run's unsaved token (${fp}).`);
+  const notice = [`auth: using the saved token from ${t.path} (${fp}).`];
+  if (t.path !== null && loosePerms(t.path)) notice.push(`warning: ${t.path} is readable by other users — chmod 600 it.`);
+  return done(...notice);
+}
+
+// What --token-status prints: everything about the token except the token.
+export function status(): TokenStatus {
+  const file = tokenPath();
+  const stored = readFrom(file);
+  const envTok = (process.env.FIGMA_BRIDGE_TOKEN || "").trim();
+  const active = resolve({ persist: false });
+  return {
+    path: file,
+    stored: !!stored,
+    envSet: !!envTok,
+    // Which source actually wins right now — the point of the whole command is that "there is a file"
+    // and "the file is what the bridge uses" are different questions when the env var is also set.
+    activeSource: active.source,
+    // No fingerprint for an ephemeral token. `status()` resolves with persist:false, so the
+    // "ephemeral" branch mints a THROWAWAY that nothing will ever use and that differs on every
+    // call — printing its fingerprint invites the user to compare it against the plugin's, which is
+    // exactly the wrong thing to do. A fingerprint is only meaningful for a token that persists.
+    fingerprint: active.source === "ephemeral" ? null : fingerprint(active.token),
+    loosePerms: stored ? loosePerms(file) : false,
+    // A stored token that is being SHADOWED by a DIFFERENT env var value is the confusing case worth
+    // naming — a project that always exports FIGMA_BRIDGE_TOKEN set to the SAME value as the saved
+    // file has nothing to fix, and warning on every run just trains the user to ignore the note.
+    shadowed: !!stored && !!envTok && stored !== envTok,
+  };
+}