agentbox-app 0.1.6

package/main/codex-bin.mjs

@@ -0,0 +1,261 @@
+// Where Codex actually is, and whether we are entitled to say it is not here.
+//
+// The sibling of main/claude-bin.mjs, and it keeps that file's rule rather than
+// re-arguing it.
+//
+// So `found` decides which binary would be spawned and `certain` decides
+// whether a screen may SAY there is nothing here, and they are never the same
+// value.
+//
+// ONE DIFFERENCE FROM CLAUDE CODE, AND IT CHANGES THE SCREEN. Claude Code is
+// required: the app will not open an inbox without it. Codex is optional, and
+// an absence is the ordinary case rather than a fault. So nothing here ever
+// produces a warning. All a missing Codex does is leave the second engine out
+// of the map that shared/engines.mjs reads, which is silence rather than a
+// sentence about software she never asked for.
+//
+// NOTHING HERE SPAWNS ANYTHING, AND main/config.mjs IS WHAT CALLS IT.
+//
+// It was inert when it was written -- "no config key, no snapshot field, no
+// Settings row" -- and that stopped being true the moment the supervisor
+// started spawning `config.codexBin`. Until this was wired in, that path
+// arrived on `config` through the unknown-key spread in main/config.mjs and
+// went to `spawn` with no finder and no existence check behind it, which is the
+// one path in the second engine that becomes a process and was the only one
+// with no guard on it. `resolveCodexBin` is now what answers "is there a Codex
+// on this Mac", and its answer is the fact `engineFor` refuses on.
+//
+// There is still no Settings row, which is a real gap and not a claim of one:
+// she can set `codexBin` in zero.config.json and nothing on screen says whether
+// it was found.
+//
+// ------------------------------------------------------------------------
+// MEASURED ON THIS MAC 2026-09-04, BECAUSE THE 2026-08-25 ORIGINAL WAS WRITTEN
+// AGAINST codex-cli 0.144.0 AND SIX OF ITS ASSUMPTIONS HAVE MOVED SINCE.
+//
+// Installed here: codex-cli 0.148.0 at /opt/homebrew/bin/codex. That is a
+// Homebrew CASK, not a formula as the original said, and the bin entry is a
+// SYMLINK into /opt/homebrew/Caskroom/codex/0.148.0/bin/codex. `brew info
+// --cask codex` the same minute reports 0.148.0 installed against 0.152.1
+// available, so the moment mid-upgrade where that link points at nothing is a
+// live state on this machine and not a hypothetical. It is the same shape the
+// dangling-symlink rule was written for in the sibling file.
+//
+// THE INSTALL METHOD THE DOCS NOW LEAD WITH DID NOT EXIST IN THE ORIGINAL.
+// `https://chatgpt.com/codex/install.sh`, read 2026-09-04:
+//
+//   BIN_DIR="${CODEX_INSTALL_DIR:-$HOME/.local/bin}"
+//   CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
+//   STANDALONE_ROOT="$CODEX_HOME_DIR/packages/standalone"
+//
+// It links ~/.local/bin/codex at a versioned file under that root and swaps the
+// file on every update. Three things follow, and all three are changes from the
+// original: that path goes FIRST (the tool's own answer settles a machine set
+// up the documented way in one stat call, exactly as ~/.local/bin/claude does
+// next door), the standalone store's own bin is worth listing for the case
+// where CODEX_INSTALL_DIR put the link somewhere no list covers, and CODEX_HOME
+// can move every trace below out from under us.
+//
+// AND THE STORE KEEPS THE BINARY IN TWO PLACES, WHICH THE FIRST VERSION OF THIS
+// FILE MISSED. Same script, read the same day:
+//
+//   line  951:  ln -sf "bin/codex" "$stage_release/codex"
+//   line 1021:  version_from_binary "$release_dir/bin/codex" \
+//                 || version_from_binary "$release_dir/codex"
+//
+// Every staged release carries the binary at `<release>/bin/codex` AND at
+// `<release>/codex`, and the installer accepts either when it goes looking for
+// a version. `current` is a symlink at the live release, so BOTH
+// `current/bin/codex` and `current/codex` resolve on a machine set up the
+// documented way. Each is one stat call, so listing both costs nothing, and
+// listing only one is how the app tells somebody their Codex is missing while
+// they are looking at it.
+//
+// WHAT ~/.codex REALLY HOLDS NOW: 38 entries. auth.json, config.toml, sessions/
+// and history.jsonl are all still there, so the original's evidence list is not
+// wrong. It is INCOMPLETE, and it is aging in a specific way. The directory
+// also holds state_5.sqlite, thread_history_1.sqlite, logs_2.sqlite,
+// memories_1.sqlite, queue_1.sqlite, goals_1.sqlite, models_cache.json,
+// installation_id and shell_snapshots/, and the split matters: sessions/ holds
+// 1691 rollout files with the newest written 2026-09-03, while history.jsonl
+// has not been touched since 2026-06-03. The live record moved into sqlite
+// files whose names carry a schema number that increments, which is a name no
+// list can hold. That is why the directory itself stays on the list, last and
+// broad, and why nothing below tries to enumerate what is inside it.
+//
+// AND THE LINK MOVED. The original's install URL, developers.openai.com/codex/
+// cli, answers 308 to learn.chatgpt.com/docs/codex/cli.
+//
+// The npm package is unchanged and still real (@openai/codex, 0.153.0 on
+// 2026-09-04), so the package-manager paths and the per-Node directories below
+// are carried over exactly as they were.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { askShell } from './claude-bin.mjs';
+
+// In order, and the first that exists wins. The shell installer's own path is
+// first for the same reason its sibling's is: it is the answer the tool itself
+// produces. Everything after it is a package manager's default bin directory,
+// because Codex ships as a Homebrew cask and as an npm package rather than with
+// an installer that owns a folder.
+export function candidatePaths(home = os.homedir()) {
+  return [
+    path.join(home, '.local/bin/codex'),      // the shell installer's link
+    path.join(home, '.codex/packages/standalone/current/bin/codex'),
+    path.join(home, '.codex/packages/standalone/current/codex'),
+    '/opt/homebrew/bin/codex',                // the Homebrew cask, Apple Silicon
+    '/usr/local/bin/codex',                   // Homebrew on Intel, and npm -g
+    path.join(home, '.bun/bin/codex'),
+    path.join(home, '.volta/bin/codex'),
+    path.join(home, '.asdf/shims/codex'),
+    path.join(home, '.npm-global/bin/codex'),   // the two npm prefixes people
+    path.join(home, '.npm-packages/bin/codex'), // actually write in a guide
+    path.join(home, '.yarn/bin/codex'),
+    path.join(home, 'Library/pnpm/codex'),    // pnpm's own bin on macOS
+    path.join(home, '.deno/bin/codex'),
+    path.join(home, 'bin/codex'),             // a hand-rolled ~/bin on PATH
+    '/opt/local/bin/codex',                   // MacPorts
+    '/usr/bin/codex',
+  ];
+}
+
+// One bin directory per installed Node, under a name no list can hold. A global
+// npm install under nvm, fnm, n or asdf lands there and nowhere else, and a
+// double-clicked Electron app inherits launchd's PATH, which has never heard of
+// any of them.
+export function versionedPaths(home = os.homedir(), readdir = defaultReaddir) {
+  const under = (dir, tail) => readdir(path.join(home, dir)).map((v) => path.join(home, dir, v, tail));
+  return [
+    ...under('.nvm/versions/node', 'bin/codex'),
+    ...under('.local/share/fnm/node-versions', 'installation/bin/codex'),
+    ...under('Library/Application Support/fnm/node-versions', 'installation/bin/codex'),
+    ...under('n/versions/node', 'bin/codex'),
+    ...under('.asdf/installs/nodejs', 'bin/codex'),
+  ];
+}
+
+function defaultReaddir(dir) {
+  try { return fs.readdirSync(dir); } catch { return []; }
+}
+
+// WHAT CODEX LEAVES BEHIND. None of these is a binary and none is ever spawned.
+// They exist only to stop the app claiming an absence it has not established.
+//
+// Both homes are looked in when CODEX_HOME is set, and that is on purpose: a
+// CODEX_HOME inherited from somewhere else is not proof the ordinary directory
+// is gone, and the whole job of this list is to make an absence hard to claim
+// rather than easy.
+export function evidencePaths(home = os.homedir(), env = process.env) {
+  const homes = [env?.CODEX_HOME, path.join(home, '.codex')].filter(Boolean);
+  const out = [];
+  for (const dir of new Set(homes)) {
+    out.push(
+      path.join(dir, 'auth.json'),                    // it has been logged in
+      path.join(dir, 'config.toml'),
+      path.join(dir, 'sessions'),                     // one folder tree of past runs
+      path.join(dir, 'history.jsonl'),
+      path.join(dir, 'packages/standalone/releases'), // the installer's version store
+      dir,                                            // and the directory itself, last
+    );
+  }
+  return out;
+}
+
+// A path that is a symlink to nothing. `existsSync` follows the link and says
+// false, which is indistinguishable from nothing being there at all, and the
+// two mean opposite things. Both of Codex's normal installs are a symlink into
+// a versioned directory that gets swapped on every update, so this is the
+// ordinary shape of a Codex that is being upgraded rather than an odd one.
+function defaultDangles(p) {
+  try { return !!fs.lstatSync(p) && !fs.existsSync(p); } catch { return false; }
+}
+
+export function installEvidence({
+  home = os.homedir(), env = process.env, exists = fs.existsSync, dangles = defaultDangles,
+} = {}) {
+  for (const p of evidencePaths(home, env)) if (exists(p)) return p;
+  for (const p of candidatePaths(home)) if (dangles(p)) return p;
+  return null;
+}
+
+export const INSTALL_URL = 'https://learn.chatgpt.com/docs/codex/cli';
+
+/**
+ * The whole search, a pure function of its inputs so a test can put Codex
+ * anywhere without touching the machine it runs on.
+ *
+ * Returns the same shape its sibling does: { path, found, certain, from,
+ * searched, evidence }, so a caller can hold the two side by side without
+ * learning two vocabularies.
+ */
+export function findCodexBin({
+  configured = null,
+  home = os.homedir(),
+  env = process.env,
+  exists = fs.existsSync,
+  shellLookup = () => askShell({ bin: 'codex' }),
+  readdir = defaultReaddir,
+  dangles = defaultDangles,
+} = {}) {
+  if (configured) {
+    return {
+      path: configured, found: exists(configured), certain: true, from: 'settings',
+      searched: [], evidence: null,
+    };
+  }
+
+  const searched = [...candidatePaths(home), ...versionedPaths(home, readdir)];
+  for (const candidate of searched) {
+    if (exists(candidate)) return { path: candidate, found: true, certain: true, from: 'disk', searched, evidence: null };
+  }
+
+  const fromShell = shellSaid(shellLookup());
+  if (fromShell.path) return { path: fromShell.path, found: true, certain: true, from: 'shell', searched, evidence: null };
+
+  // NOT FOUND, AND WHETHER THAT IS KNOWN. Every cheap path missed and every
+  // shell we could reach missed, so the last question is whether this Mac shows
+  // any sign of Codex anyway.
+  const evidence = installEvidence({ home, env, exists, dangles });
+  return {
+    path: null,
+    found: false,
+    certain: fromShell.answered && !evidence,
+    from: null,
+    searched,
+    evidence,
+  };
+}
+
+// askShell used to answer with a path or null. Anything handing back the old
+// shape is read as an answer, because that is what it always meant.
+function shellSaid(result) {
+  if (typeof result === 'string') return { path: result, answered: true };
+  if (!result || typeof result !== 'object') return { path: null, answered: true };
+  return { path: result.path ?? null, answered: result.answered !== false };
+}
+
+/* ------------------------------- the cache -------------------------------- */
+// Only the SHELL step is remembered, for the same thirty seconds and the same
+// reason: the path checks are stat calls, and caching those is how a settings
+// screen ends up still saying "not found" after somebody has installed it.
+
+const SHELL_TTL = 30_000;
+let shellAnswer = null;
+let shellAskedAt = 0;
+
+export function resolveCodexBin(configured = null, { now = Date.now(), shellLookup = () => askShell({ bin: 'codex' }), ...where } = {}) {
+  const remembered = () => {
+    if (shellAskedAt && now - shellAskedAt < SHELL_TTL) return shellAnswer;
+    shellAnswer = shellLookup();
+    shellAskedAt = now;
+    return shellAnswer;
+  };
+  return findCodexBin({ ...where, configured, shellLookup: remembered });
+}
+
+export function forgetCodexBin() {
+  shellAnswer = null;
+  shellAskedAt = 0;
+}

package/main/codex-compaction.mjs

@@ -0,0 +1,49 @@
+// One operation on an existing thread. No prompt, worker queue or automatic retry.
+import { resumeThreadParams } from './codex-session.mjs';
+
+export async function compactCodexThread({ server, threadId, threadParams = {}, onState = () => {}, timeoutMs = 120000 }) {
+  if (!threadId) return 'missing';
+  let watched = false, sent = false, turnId = null, timer, finish;
+  const completion = new Promise(resolve => { finish = resolve; });
+  const handlers = {
+    onNotification(method, params) {
+      if (!sent || params?.threadId !== threadId) return;
+      const id = params?.turn?.id ?? params?.turnId;
+      if (method === 'turn/started' && !turnId && typeof id === 'string') turnId = id;
+      if (method === 'turn/completed' && turnId && id === turnId) {
+        finish(params.turn?.status === 'completed' ? 'done' : 'failed');
+      }
+    },
+    onClosed() { finish('failed'); },
+  };
+  try {
+    const read = await server.request('thread/read', { threadId, includeTurns: true });
+    if (read?.thread?.status?.type === 'active' || read?.thread?.turns?.some(turn => turn.status === 'inProgress')) return 'busy';
+    // Resuming a dormant thread with an active goal can start autonomous work.
+    // Compaction must not wake a goal outside the tracked worker lifecycle.
+    try {
+      const { goal } = await server.request('thread/goal/get', { threadId });
+      if (goal?.status === 'active') return 'busy';
+    } catch (error) {
+      if (error?.code !== -32601 && !/method not found|unknown (method|variant)/i.test(error?.message ?? '')) throw error;
+    }
+    watched = true;
+    await server.resumeThread(resumeThreadParams(threadId, threadParams), handlers);
+    onState('running');
+    timer = setTimeout(() => {
+      if (turnId) Promise.resolve(server.interruptTurn(threadId, turnId)).catch(() => {});
+      finish('failed');
+    }, timeoutMs);
+    sent = true;
+    // An empty response acknowledges the request; only turn/completed settles it.
+    await server.request('thread/compact/start', { threadId });
+    const result = await completion;
+    onState(result);
+    return result;
+  } catch (error) {
+    return error?.code === -32601 || /method not found|unknown (method|variant)/i.test(error?.message ?? '') ? 'unavailable' : 'failed';
+  } finally {
+    clearTimeout(timer);
+    if (watched) server.unwatch(threadId);
+  }
+}

package/main/codex-models.mjs

@@ -0,0 +1,194 @@
+// WHICH MODELS CODEX CAN BE ASKED FOR, READ OFF THIS MAC RATHER THAN LISTED.
+//
+// She is right and the card was wrong. `renderer/src/models.ts` holds four
+// names -- Opus, Sonnet, Haiku, Fable -- and drew them whatever the engine was,
+// so a task set to run on Codex read "On Opus. With Codex.", which is two
+// sentences that cannot both be true.
+//
+// AND THE LIST IS NOT OURS TO KEEP. Claude Code's four are safe to generate
+// once into a committed file because `--model` there takes an ALIAS (`opus` is
+// whatever Opus is on the day the task runs, resolved by the CLI at spawn), so
+// `shared/claude-models.generated.mjs` cannot silently point at an old model.
+// Codex has no aliases: `-m` and `thread/start`'s `model` want the exact slug
+// of one specific model, and OpenAI ships new ones on their own schedule. A
+// hardcoded Codex list is a list that is wrong the week after it is written,
+// and a generated one is a list that is wrong the week after the build.
+//
+// SO IT IS READ AT THE MOMENT IT IS ASKED FOR, AND THE CLI HAS ALREADY FETCHED
+// IT. codex-cli keeps `<home>/models_cache.json`, refreshed against the server
+// with an etag, holding every model the logged-in account may use. Measured on
+// this Mac 2026-09-04 against codex-cli 0.148.0: 198,977 bytes, 8 models,
+// `fetched_at` 2026-09-04T10:21:25.048219Z, `client_version` "0.148.0". Six
+// carry `visibility: "list"` and two carry `"hide"`. Reading that file IS the
+// fetch: one readFileSync of a file the CLI maintains, no network, and it
+// cannot disagree with what Codex will actually accept.
+//
+// NOTHING HERE SPAWNS ANYTHING. `codex` has no subcommand that prints its
+// models (checked against 0.148.0), and even if it did, a picker must never be
+// the reason a login shell is spawned while she is typing.
+//
+// AND NOTHING HERE IS CACHED IN MEMORY, for the reason main/codex-bin.mjs
+// gives about its own stat calls: caching a cheap read is how a screen ends up
+// still saying the old answer after the thing changed underneath it. The CLI
+// rewrites this file whenever its etag moves, and a spawn is not a hot path.
+//
+// ---------------------------------------------------------------------------
+// TWO QUESTIONS, NOT ONE, AND THE 2026-08-26 ORIGINAL ONLY ASKED THE FIRST.
+//
+//   WHAT MAY SHE BE OFFERED -> `codexModels`, the six with `visibility: "list"`.
+//     `gpt-reserve` and `codex-auto-review` are Codex's own internal models and
+//     a person who chose one would get a session that behaves nothing like a
+//     coding agent.
+//
+//   WHAT WOULD CODEX ACCEPT -> `codexKnownSlugs`, all eight. This one is new,
+//     and it exists because main/supervisor.mjs now REFUSES to start a run
+//     whose model this Mac's Codex does not know. Answering that question with
+//     the offer list would refuse `gpt-reserve` -- a slug Codex takes -- and a
+//     false refusal is a row that cannot run for a reason that is not true.
+//
+// `priority` is ascending and is the order the CLI's own picker uses, so the
+// newest frontier model is first and the small old ones are last. Sorted by it
+// rather than by name, so the list never reorders itself when a model ships.
+//
+// REASONING LEVELS ARE PER MODEL AND THEY REALLY DIFFER. Measured in the same
+// file the same day: `gpt-5.6-sol` supports low/medium/high/xhigh/max/ultra and
+// `gpt-5.5` stops at xhigh; the defaults differ too (`low` against `medium`).
+// One shared list beside a picker would offer her a level half these models
+// cannot run.-- but they are carried here so the slice that does draw them does
+// not have to come back and re-read a 199KB file.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * WHICH CODEX HOME. Her own setting first, then the environment, then the
+ * default -- the same precedence the install script itself uses, read
+ * 2026-09-04: `CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"`. An empty
+ * `CODEX_HOME` falls through exactly as `${VAR:-default}` does, so an
+ * exported-but-blank one cannot turn this into a read at the root of the disk.
+ *
+ * main/codex-bin.mjs looks under BOTH `CODEX_HOME` and `~/.codex` for signs of
+ * an install, and that is not this rule rather than a contradiction of it: its
+ * job is to make an ABSENCE hard to claim, so two homes is the right answer
+ * there. This one has to name the single home a specific Codex reads, because
+ * offering models out of the wrong one would offer models a different login
+ * cannot run.
+ */
+export function codexHome({ configured = null, env = process.env, home = os.homedir() } = {}) {
+  return configured || env?.CODEX_HOME || path.join(home, '.codex');
+}
+
+/**
+ * The models this Mac's Codex may be OFFERED, in the order it ranks them.
+ *
+ * `{ id, label, description, defaultLevel, levels }`, where `levels` is the
+ * model's own `[{ id, description }]`. Every word in it is Codex's; nothing is
+ * typed here, for the reason `shared/claude-models.generated.mjs` gives about
+ * its own labels -- a name typed into a file of ours looks authoritative while
+ * being a guess.
+ *
+ * An unreadable, absent or half-written cache answers `[]` rather than a guess.
+ * `[]` is not "there are no models"; it is "this Mac cannot say", and the
+ * supervisor's refusal is built to need a list before it refuses anything.
+ */
+export function codexModels({ home = codexHome(), read = readJson } = {}) {
+  return modelRows(read(path.join(home, 'models_cache.json')))
+    .filter((m) => m.visibility === 'list')
+    .sort((a, b) => priorityOf(a) - priorityOf(b))
+    .map((m) => ({
+      id: String(m.slug),
+      label: String(m.display_name || m.slug),
+      description: typeof m.description === 'string' ? m.description : '',
+      defaultLevel: typeof m.default_reasoning_level === 'string' ? m.default_reasoning_level : null,
+      levels: (Array.isArray(m.supported_reasoning_levels) ? m.supported_reasoning_levels : [])
+        .filter((l) => l && typeof l.effort === 'string' && l.effort)
+        .map((l) => ({ id: l.effort, description: typeof l.description === 'string' ? l.description : '' })),
+    }));
+}
+
+/**
+ * Every slug in the cache, hidden ones included: what Codex would accept if it
+ * were handed the word, which is a different question from what she may pick.
+ */
+export function codexKnownSlugs({ home = codexHome(), read = readJson } = {}) {
+  return new Set(modelRows(read(path.join(home, 'models_cache.json'))).map((m) => String(m.slug)));
+}
+
+/**
+ * The reasoning levels ONE model advertises, hidden models included, as the
+ * bare words `turn/start`'s `effort` takes.
+ *
+ * Null when this Mac cannot say -- no readable cache, or a slug it does not
+ * list -- which the caller has to tell apart from a model that lists none:
+ * the first is "carry the word and let Codex answer", the second is a level
+ * nothing can run. Same two questions as `codexKnownSlugs` against
+ * `codexModels`, asked about the other field.
+ */
+export function codexModelLevels(slug, { home = codexHome(), read = readJson } = {}) {
+  const cache = read(path.join(home, 'models_cache.json'));
+  if (!cache) return null;
+  const row = modelRows(cache).find((m) => m.slug === slug);
+  if (!row) return null;
+  return (Array.isArray(row.supported_reasoning_levels) ? row.supported_reasoning_levels : [])
+    .filter((l) => l && typeof l.effort === 'string' && l.effort)
+    .map((l) => l.effort);
+}
+
+/**
+ * WHAT CODEX RUNS ON WHEN NOBODY HAS CHOSEN, WHICH IS HER OWN SETTING.
+ *
+ * Read out of the bare `model = "..."` line at the top of the home's
+ * config.toml, because that is the model her `codex` in a terminal already
+ * uses, and a fleet quietly running a different one would be a fleet she cannot
+ * reason about. Hers on 2026-09-04 is `gpt-5.6-sol`.
+ *
+ * A DELIBERATELY SMALL PARSER, and the smallness is the safety. The only thing
+ * it is ever allowed to take out of that file is one top-level string, so it
+ * scans line by line and STOPS AT THE FIRST TABLE HEADER. That is not a
+ * shortcut, it is TOML: once a `[table]` opens, every key below it belongs to
+ * that table, so a bare top-level key can only appear above the first one. Her
+ * real config is 234 lines with 71 `[projects."..."]` tables in it, and a regex
+ * over the whole file reports whichever project it hit first as her default.
+ *
+ * `model_reasoning_effort` sits on the line directly below `model` in that same
+ * file and shares its first eight characters, which is why the key is anchored
+ * on both sides rather than merely at the start.
+ *
+ * NULL IS A REAL ANSWER: pass no model at all and let Codex decide, which is
+ * what happens today. The 2026-08-26 version fell back to the top-priority
+ * model in the list instead, and that is our sort order's first row rather than
+ * Codex's default. The two are equal on this Mac by luck, and a screen printing
+ * one as the other would be wrong with nothing here able to notice.
+ */
+export function codexDefaultModel({ home = codexHome(), read = readText } = {}) {
+  const text = read(path.join(home, 'config.toml'));
+  if (!text) return null;
+  for (const raw of String(text).split('\n')) {
+    const line = raw.trim();
+    if (line.startsWith('[')) return null; // a table opens; the top level is over
+    const hit = /^model\s*=\s*["']([^"']+)["']/.exec(line);
+    if (hit) return hit[1];
+  }
+  return null;
+}
+
+/** The `models` array, or nothing, however badly the file is malformed. */
+function modelRows(cache) {
+  const rows = Array.isArray(cache?.models) ? cache.models : [];
+  return rows.filter((m) => m && typeof m === 'object' && typeof m.slug === 'string' && m.slug);
+}
+
+// A model with no priority sorts last rather than first. A new field arriving
+// with a null in it must not silently jump to the top of her picker.
+function priorityOf(m) {
+  return Number.isFinite(m.priority) ? m.priority : Number.MAX_SAFE_INTEGER;
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function readText(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch { return null; }
+}