nomoremeatproxy 0.0.0-stage → 0.1.0

package/src/adapters/opener.mjs

@@ -0,0 +1,29 @@
+// Runs a program that opens a chat in a desktop app, for the Claude and the Codex opener alike.
+import { spawn } from 'node:child_process';
+
+// Waits for the opener to exit. `opened: true` only when it exited with code 0; another exit
+// code or running out of time is reported, never thrown. A failure to start rejects, so that
+// each opener words it. The opener's own output is never read. At the time limit the opener is
+// sent a plain kill signal: on macOS that should end `script`, whose closing terminal hangs up
+// the Claude opener under it.
+export function runOpener([file, args], { cwd, start = spawn, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const child = start(file, args, { cwd, detached: true, stdio: 'ignore' });
+    // At the limit the answer is given at once, without waiting for an exit, and the child is
+    // released so that one that survives the kill cannot keep the bridge running.
+    const timer = setTimeout(() => {
+      const signalled = child.kill();
+      child.unref();
+      const limit = `the opener did not exit within ${timeoutMs / 1000} seconds`;
+      resolve({ opened: false, reason: signalled ? `${limit}; a stop signal was sent` : `${limit} and could not be stopped` });
+    }, timeoutMs);
+    child.once('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.once('exit', (code, signal) => {
+      clearTimeout(timer);
+      resolve(code === 0 ? { opened: true } : { opened: false, reason: `the opener exited with ${code === null ? `signal ${signal}` : `code ${code}`}` });
+    });
+  });
+}

package/src/call.mjs

@@ -0,0 +1,193 @@
+// One call from an assistant to a peer: pick the thread, bound the exchange, refuse
+// duplicates, and record every state before and after the vendor is contacted.
+import { createHash, randomUUID } from 'node:crypto';
+
+export const DEFAULT_MAX_HOPS = 4;
+const TITLE_TEXT_LENGTH = 60;
+
+const NOTES = Object.freeze({
+  sent: 'sent without waiting; the reply will not come back to this call',
+  duplicate: 'this request was already sent or answered; read the thread instead of sending again',
+  uncertain: 'an earlier attempt may have been delivered; inspect the thread, then resend with --force only if the message is absent',
+  attendedStanding: 'that chat answers from its own app, and the standing thread is continued without the app; nothing was sent. Send with --thread alone, or name another thread',
+});
+
+// Deliveries where the peer's own app runs the turn with the chat's own model and level.
+const RUNS_AS_IS = new Set(['queued', 'attended']);
+
+// `named` lists the settings the caller gave itself, not the peer's defaults.
+const dropped = (delivery, named) => (RUNS_AS_IS.has(delivery) && named?.length ? { notApplied: named } : {});
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+
+// Unique text inside the header, used to find this request's turn in a thread later.
+export const requestMarker = (requestId) => `request ${requestId};`;
+
+// Seen on macOS: the Codex app did not list a chat the bridge made until it re-read its list, and
+// a question card raised there never reached the owner although the card tool answered accepted.
+const UNLISTED_CHAT = 'The owner may not see this chat: put any question for the owner in your answer, marked for the owner, not in a question card.';
+
+// The recipient must be able to tell a peer's message from the owner's own words. Kept to
+// one short line: it is sent with every message. The opening words are what the calling
+// rules tell an assistant to look for, and the request marker is what recovery searches for.
+// `unlisted` adds one line for a chat the owner may not see.
+export function stampMessage({ message, from, requestId, hop, maxHops, unlisted = false }) {
+  const header = `[nomeat call from ${from}; ${requestMarker(requestId)} hop ${hop}/${maxHops}; AI, not user]`;
+  return `${header}${unlisted ? `\n${UNLISTED_CHAT}` : ''}\n\n${message}`;
+}
+
+// Shown in the peer's app so the owner can tell bridge threads, and their projects, apart.
+export function threadTitle({ from, peer, project, message }) {
+  const text = message.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+  const shown = text.length > TITLE_TEXT_LENGTH ? `${text.slice(0, TITLE_TEXT_LENGTH)}...` : text;
+  // Both separators, so a Windows path is read correctly on any platform.
+  const folder = project.split(/[\\/]/).filter(Boolean).at(-1);
+  return `${from} to ${peer} [${folder}]: ${shown}`;
+}
+
+function priorOutcome(history) {
+  const threadId = history.findLast((entry) => entry.threadId)?.threadId ?? null;
+  if (history.some((entry) => entry.state === 'answered' || entry.state === 'sent')) return { state: 'duplicate', threadId };
+  const lastAttempt = history.findLast((entry) => entry.state === 'submitting' || entry.state === 'failed');
+  if (!lastAttempt) return null;
+  // A failure known to have happened before anything was sent is safe to retry.
+  if (lastAttempt.state === 'failed' && lastAttempt.sent === false) return null;
+  return { state: 'uncertain', threadId };
+}
+
+// How the caller steered this call away from the route's default thread, if it did.
+const steering = (request) => (request.threadId ? 'thread' : request.newThread ? 'new' : null);
+
+// An explicit thread wins, and a new thread starts fresh. Otherwise the standing conversation
+// between this caller and peer in this project continues; where none has been named yet, the
+// last answered thread that no caller steered does.
+function chooseThread(request, ledger, route) {
+  if (request.threadId) return request.threadId;
+  if (request.newThread) return null;
+  return ledger.standingThread(route) ?? ledger.lastThread(route);
+}
+
+// A thread becomes the standing one when the caller says so, or when the route has none and
+// the caller did not steer this call: a side thread or an exact thread must not take over by
+// being first or recent. A chat that answers from its app is never named: the standing
+// thread is continued without the app.
+function nameStanding({ request, ledger, route, result, attendedChat }) {
+  if (!result.threadId || result.delivery === 'attended' || attendedChat(result.threadId)) return;
+  const first = !steering(request) && !ledger.standingThread(route);
+  // Recorded for the route, not under the request id: it is not a step of that request.
+  if (request.makeStanding || first) ledger.append({ ...route, state: 'standing', threadId: result.threadId });
+}
+
+// Before reporting an uncertain delivery, look in the thread: the answer may already be there.
+async function recoverAnswer({ prior, recover, requestId }) {
+  if (prior.state !== 'uncertain' || !recover) return null;
+  return recover({ threadId: prior.threadId, marker: requestMarker(requestId), requestId });
+}
+
+// `attendedChat` says why a chat cannot be a standing thread, or null when it can.
+export async function callPeer(request, { ledger, adapters, recoverers = {}, attendedChat = () => null, newId = randomUUID }) {
+  const { peer, message, from, project, effort, write = false, force = false } = request;
+  const hop = request.hop ?? 1;
+  const maxHops = request.maxHops ?? DEFAULT_MAX_HOPS;
+  const requestId = request.requestId ?? newId();
+  // A peer without a model uses the vendor's default, and the result then has no model field.
+  const header = (model) => ({ requestId, peer: peer.name, vendor: peer.vendor, ...(model == null ? {} : { model }) });
+  let base = header(peer.model);
+  const route = { project, from, peer: peer.name };
+
+  if (hop > maxHops) {
+    const note = `hop ${hop} exceeds the limit of ${maxHops}; put the open question to the owner instead of calling again`;
+    return { ...base, state: 'refused', threadId: request.threadId ?? null, note };
+  }
+  // A fresh request sends nothing before the adapter is called: a failure up to there, such as
+  // a state folder that cannot be read or written, is marked not sent. Once an earlier attempt
+  // is found, it may have been delivered, so a failure while recovering it is not marked.
+  let adapter, threadId, threadAccess, prior, model = peer.model, level = effort;
+  try {
+    if (request.makeStanding && request.threadId && attendedChat(request.threadId)) {
+      return { ...base, state: 'refused', threadId: request.threadId, note: NOTES.attendedStanding };
+    }
+    const history = ledger.history(requestId);
+    prior = force ? null : priorOutcome(history);
+    if (prior) {
+      // Report the model the earlier attempt sent, which a call into an existing thread may not have.
+      base = header(history.findLast((entry) => entry.state === 'submitting')?.model);
+      const found = await recoverAnswer({ prior, recover: recoverers[peer.vendor], requestId });
+      if (!found) return { ...base, ...prior, note: NOTES[prior.state] };
+      ledger.append({ requestId, ...route, state: 'answered', threadId: prior.threadId, recovered: true });
+      // A recoverer states the delivery only when it knows it; Codex's cannot tell direct from queued.
+      return { ...base, state: 'answered', threadId: prior.threadId, continued: true, recovered: true, ...dropped(found.delivery, request.named), reply: found.reply };
+    }
+
+    adapter = adapters[peer.vendor];
+    if (!adapter) throw new Error(`no adapter for vendor "${peer.vendor}"`);
+    threadId = chooseThread(request, ledger, route);
+    // An existing Codex thread keeps its own model and level unless the caller named one; the
+    // peer's defaults are for a new thread. A Claude session is still given the peer's model.
+    if (peer.vendor === 'codex' && threadId) {
+      const named = request.named ?? [];
+      if (!named.includes('model')) model = undefined;
+      if (!named.includes('effort')) level = undefined;
+      base = header(model);
+    }
+    const steered = steering(request);
+    threadAccess = ledger.threadAccess(threadId);
+    // Written last before contacting the vendor, so that a crash mid-send reads as "maybe
+    // delivered" and a failure before it leaves no entry that would block a retry.
+    ledger.append({ ...base, ...route, state: 'submitting', hop, threadId, ...(steered ? { steered } : {}), messageSha256: sha256(message), messageChars: message.length });
+  } catch (error) {
+    if (!prior) Object.assign(error, { notSent: true, message: `${error.message}; nothing was sent` });
+    throw error;
+  }
+
+  try {
+    // A Codex chat the bridge makes: in this call, or in an earlier one, whose access only the
+    // creating call records. Limit: a creating call whose answer was never recorded is missed.
+    const unlisted = peer.vendor === 'codex' && (!threadId || Boolean(threadAccess));
+    const result = await adapter({
+      threadId: threadId ?? undefined,
+      message: stampMessage({ message, from, requestId, hop, maxHops, unlisted }),
+      marker: requestMarker(requestId),
+      title: threadTitle({ from, peer: peer.name, project, message }),
+      model,
+      effort: level,
+      write,
+      threadAccess,
+      cwd: project,
+      onThread: (id) => ledger.append({ requestId, state: 'thread', threadId: id }),
+      // For an adapter that can choose between destinations.
+      requestId,
+      from,
+      peer: peer.name,
+      hop,
+      maxHops,
+      pinned: Boolean(request.threadId || request.newThread),
+      noWait: Boolean(request.noWait),
+    });
+    const delivery = result.delivery ? { delivery: result.delivery } : {};
+    // A delivery that went through but with something the caller should know.
+    const warning = result.warning ? { warning: result.warning } : {};
+    // A Codex turn that sets no access runs with the thread's own, so the ledger says what that is.
+    const access = result.access ?? (peer.vendor === 'codex' ? ledger.threadAccess(result.threadId) : null);
+    const applies = result.effort ? { effort: result.effort } : {};
+    const notApplied = dropped(result.delivery, request.named);
+    const applied = { ...(access ? { access } : {}), ...applies };
+    // Only the call that made a thread records its access: a later resume with write may not stick.
+    const recorded = threadId ? applies : applied;
+    nameStanding({ request, ledger, route, result, attendedChat });
+    if (request.noWait) {
+      ledger.append({ requestId, ...route, state: 'sent', threadId: result.threadId, ...delivery, ...recorded });
+      return { ...base, state: 'sent', threadId: result.threadId, continued: Boolean(threadId), ...delivery, ...applied, ...notApplied, ...warning, note: NOTES.sent };
+    }
+    // Sizes and the vendor's token figures, for measuring what calls cost. Never the text.
+    const cost = { replyChars: result.reply.length, ...(result.usage ? { usage: result.usage } : {}) };
+    ledger.append({ requestId, ...route, state: 'answered', threadId: result.threadId, ...delivery, ...recorded, ...cost });
+    return { ...base, state: 'answered', threadId: result.threadId, continued: result.continued ?? Boolean(threadId), ...delivery, ...applied, ...notApplied, ...warning, reply: result.reply };
+  } catch (error) {
+    ledger.append({ requestId, state: 'failed', sent: !error.notSent, error: error.message });
+    // An adapter that refuses an attempt says why. Recorded as possibly sent, since an earlier
+    // attempt was, so a later retry looks for the answer first.
+    if (error.refused) return { ...base, state: 'refused', threadId: request.threadId ?? null, note: error.message };
+    throw error;
+  }
+}

package/src/check.mjs

@@ -0,0 +1,46 @@
+// Following up on a message that was sent without waiting: has the peer started on it, is it
+// still working, or did it finish, and with what words. The sender asks; nothing is resent.
+import { requestMarker } from './call.mjs';
+
+const NOTES = Object.freeze({
+  returned: 'the reply came back to the call that sent it',
+  uncheckable: 'this kind of delivery cannot be checked from outside; read the thread instead',
+  // Only what is seen: the cause of a message not starting is not known.
+  waiting: 'the peer has not started on it; cause unknown',
+  idle: 'the chat is idle and has not picked the message up; open the chat in the Codex app, or send it again as a new call that waits (the queued copy may then run as well)',
+  running: 'the peer is working on it now',
+});
+
+// Under a minute after sending, a message not started yet is no sign of a problem.
+const RECENT_S = 60;
+
+function noteFor(found, secondsAgo) {
+  if (found.state !== 'waiting') return NOTES[found.state];
+  if (secondsAgo < RECENT_S) return `sent ${secondsAgo} seconds ago; the peer has not started on it yet`;
+  return found.idle ? NOTES.idle : NOTES.waiting;
+}
+
+export async function checkRequest(requestId, { ledger, checkers = {}, now = Date.now }) {
+  const history = ledger.history(requestId);
+  const sent = history.find((entry) => entry.state === 'submitting');
+  if (!sent) return { requestId, state: 'unknown', ...ledger.notFound('no such request') };
+  const threadId = history.findLast((entry) => entry.threadId)?.threadId ?? null;
+  // The latest handover, so that a failed attempt or a slow queue before it is not counted as
+  // time the message has waited; without one, the latest attempt.
+  const handedOver = history.findLast((entry) => entry.state === 'sent') ?? history.findLast((entry) => entry.state === 'submitting');
+  const base = { requestId, peer: sent.peer, threadId, sentAt: handedOver.at };
+  if (history.some((entry) => entry.state === 'answered')) return { ...base, state: 'answered', note: NOTES.returned };
+  const check = checkers[sent.vendor];
+  if (!check || !threadId) return { ...base, state: 'sent', note: NOTES.uncheckable };
+  const found = await check({ threadId, marker: requestMarker(requestId) });
+  const note = noteFor(found, Math.max(0, Math.floor((now() - Date.parse(handedOver.at)) / 1000)));
+  return { ...base, ...found, ...(note ? { note } : {}) };
+}
+
+// The requests of one project that were sent without waiting, newest last.
+export function sentWithoutWaiting(entries, { project, since }) {
+  const starts = new Map(entries.filter((entry) => entry.state === 'submitting').map((entry) => [entry.requestId, entry]));
+  return entries
+    .filter((entry) => entry.state === 'sent' && starts.get(entry.requestId)?.project === project && (!since || entry.at >= since))
+    .map((entry) => entry.requestId);
+}

package/src/doctor-live.mjs

@@ -0,0 +1,123 @@
+// `doctor --live`: one real, read-only, one-word call per side through the bridge's own call
+// path, each in a new thread, from a caller name that marks it as a check. Shows that the
+// command line is found, that sign-in and the model work, and what opening in the app said.
+// Tests inject `run`; only the command line makes real calls.
+import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const BIN = fileURLToPath(new URL('../bin/nomeat.mjs', import.meta.url));
+export const LIVE_CHECK_CALLER = 'doctor-check';
+const MESSAGE = 'This is a check of the bridge, not a task. Reply with the single word: ok';
+// One peer per side, with its default model and thinking level, since those are what calls use.
+// fable is the peer whose model needs a recent Claude CLI.
+export const LIVE_PEERS = Object.freeze([
+  { side: 'codex', peer: 'astra', cli: 'codex-cli', auth: 'codex-auth' },
+  { side: 'claude', peer: 'fable', cli: 'claude-cli', auth: 'claude-auth' },
+]);
+// One deadline per side, longer than the adapters' own ten-minute limit so they report first.
+const DEADLINE_MS = 11 * 60 * 1000;
+
+// Fixed wording only: vendor output and notes can carry an account identity.
+const DETAIL = Object.freeze({
+  notRun: 'not run: the command line or the subscription sign-in was not found',
+  notOpened: 'answered, but the chat opener did not start',
+  deadline: 'no answer before the deadline; the process tree was ended; delivery uncertain, not retried',
+  cleanupFailed: 'no answer before the deadline; ending its processes did not succeed, some may still run; delivery uncertain, not retried',
+  uncertain: 'uncertain: the request may have been delivered; not retried',
+});
+
+// Ends a process and every process it started, except those that left its tree or group on
+// purpose, such as the detached chat opener. Windows: taskkill walks the tree by parent id, so
+// it runs while the wrapper is still alive. Elsewhere: the wrapper leads its own process group.
+// Bounded, and returns whether it succeeded; a group already gone counts as ended.
+const CLEANUP_TIMEOUT_MS = 10000;
+function endTree(pid) {
+  if (process.platform === 'win32') {
+    return spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore', timeout: CLEANUP_TIMEOUT_MS }).status === 0;
+  }
+  try {
+    process.kill(-pid, 'SIGKILL');
+    return true;
+  } catch (error) {
+    return error.code === 'ESRCH';
+  }
+}
+
+// Runs Node with `args` and resolves with its exit status and stdout. At the deadline the whole
+// tree is ended and the promise settles at once, whether or not the process ever closes, with
+// `timedOut` and `treeEnded`. Stderr is drained and dropped.
+export function runWithDeadline(args, { deadlineMs = DEADLINE_MS, endTree: end = endTree } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: process.platform !== 'win32' });
+    let stdout = '';
+    child.stdout.on('data', (chunk) => (stdout += chunk));
+    child.stderr.resume();
+    const timer = setTimeout(() => {
+      const treeEnded = end(child.pid);
+      // A process that outlived its cleanup must not keep this one alive.
+      child.stdout.destroy();
+      child.stderr.destroy();
+      child.unref();
+      resolve({ status: null, stdout, timedOut: true, treeEnded });
+    }, deadlineMs);
+    const done = (status) => {
+      clearTimeout(timer);
+      resolve({ status, stdout, timedOut: false });
+    };
+    child.once('error', () => done(null));
+    child.once('close', done);
+  });
+}
+
+// `--new` keeps the check away from standing threads and listening chats; no Remote Control
+// work is queued for a check chat. The request id is given, so the ledger never sends it twice.
+export function callThroughBridge(peer, requestId) {
+  return runWithDeadline([BIN, 'call', '--to', peer, '--from', LIVE_CHECK_CALLER, '--new', '--no-remote-control', '--request-id', requestId, '--message', MESSAGE]);
+}
+
+function parseOutcome(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+function describe(r, outcome, answered, ok) {
+  if (r.timedOut) return r.treeEnded ? DETAIL.deadline : DETAIL.cleanupFailed;
+  if (outcome?.state === 'uncertain') return DETAIL.uncertain;
+  if (answered) return ok ? '' : DETAIL.notOpened;
+  // Only a known state name is repeated, never free text from the result.
+  const state = ['sent', 'duplicate', 'refused'].includes(outcome?.state) ? `state ${outcome.state}, ` : '';
+  return `not answered: ${state}exit code ${r.status}`;
+}
+
+// Called once, never retried. The reply itself is not reported: the check says whether there was one.
+async function checkSide({ side, peer }, { cliFound, ready }, run) {
+  if (!ready) return { side, peer, cliFound, answered: false, appOpened: null, ok: false, detail: DETAIL.notRun };
+  const r = await run(peer, randomUUID());
+  const outcome = r.timedOut ? null : parseOutcome(r.stdout);
+  const answered = outcome?.state === 'answered' && Boolean(outcome.reply?.trim());
+  // Only the Claude opener counts. A new Codex chat is opened by its link too, but that result is
+  // not checked here: its `opened` shows only that the system took the link.
+  // null where the result had nothing to say: a Codex side, or a call that did not answer.
+  const appOpened = side === 'claude' && typeof outcome?.app?.opened === 'boolean' ? outcome.app.opened : null;
+  const ok = answered && (side !== 'claude' || appOpened === true);
+  return { side, peer, cliFound, answered, appOpened, ok, detail: describe(r, outcome, answered, ok) };
+}
+
+// `checks` are those of inspectPrerequisites. A side is called only when its command line and
+// its sign-in are both 'found': a warning, such as paid API credentials, is not enough.
+export async function runLiveChecks({ checks, run = callThroughBridge }) {
+  const status = (id) => checks.find((c) => c.id === id)?.status;
+  const sides = [];
+  for (const target of LIVE_PEERS) {
+    const cliFound = ['found', 'warning'].includes(status(target.cli));
+    const ready = status(target.cli) === 'found' && status(target.auth) === 'found';
+    sides.push(await checkSide(target, { cliFound, ready }, run));
+  }
+  return { ok: sides.every((s) => s.ok), sides };
+}
+
+export const liveExitCode = (live) => (live.ok ? 0 : 1);

package/src/doctor.mjs

@@ -0,0 +1,213 @@
+// Read-only check of what the bridge depends on. Runs nothing on import. Reports versions,
+// counts and signed in or not only: no paths, user names, account details, message content or
+// raw command output, so the result is safe to commit.
+// Sections: command runner / probes / inspectPrerequisites / host.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { defaultStateDir } from './ledger.mjs';
+import { canWrite } from './writable.mjs';
+
+const isWin = process.platform === 'win32';
+
+// A limit of one model, not of the bridge. On the first macOS run, Claude CLI 2.1.283 had calls
+// to this model refused with "API Error 400"; the vendor's message named 2.1.290 as the minimum,
+// and 2.1.322 was seen working (docs/evidence/2026-11-11-macos-baseline.md).
+export const CLAUDE_CLI_MINIMUM_FOR_MODEL = Object.freeze({ model: 'claude-fable-5-2', version: '2.1.290' });
+
+// --- command runner ---
+
+// The default `capture`: runs a command and returns whether it succeeded and its output.
+export function runCommand(file, args = [], { shell = false, encoding = 'utf8' } = {}) {
+  const options = { encoding, timeout: 20000, windowsHide: true };
+  const r = shell ? spawnSync(file, { ...options, shell: true }) : spawnSync(file, args, options);
+  if (r.error || r.status === null) return { ok: false, out: '' };
+  return { ok: r.status === 0, out: `${r.stdout ?? ''}\n${r.stderr ?? ''}`.trim() };
+}
+
+const firstVersion = (text) => text.match(/\d+\.\d+(?:\.\d+)*/)?.[0] ?? null;
+const found = (version = null, note = '') => ({ status: 'found', version, note });
+const missing = (note = '') => ({ status: 'missing', version: null, note });
+const unknown = (note) => ({ status: 'unknown', version: null, note });
+const NOT_CHECKED_HERE = unknown('not checked on this platform');
+
+export function compareVersions(a, b) {
+  const x = a.split('.').map(Number);
+  const y = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(x.length, y.length); i += 1) {
+    const diff = (x[i] ?? 0) - (y[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+// --- probes ---
+// `shell` runs a constant command string: npm-installed CLIs are .cmd shims on Windows and need one.
+
+function cliVersion(shell, command) {
+  const r = shell(command);
+  const version = r.ok ? firstVersion(r.out) : null;
+  return version ? found(version) : missing();
+}
+
+function cliSupports(shell, command, pattern, capability) {
+  const r = shell(command);
+  if (!r.ok) return missing(`${capability}: command failed`);
+  return pattern.test(r.out) ? found(null, capability) : missing(`${capability}: not offered by this version`);
+}
+
+// The Node version against `engines.node` in package.json. Limit: only a lower bound written as
+// ">=x.y[.z]" is understood; any other range reads as no minimum known.
+const NODE_RANGE = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).engines?.node ?? '';
+export function nodeVersionCheck(version = process.versions.node) {
+  const minimum = NODE_RANGE.match(/^\s*>=\s*(\d+(?:\.\d+)*)\s*$/)?.[1];
+  if (!minimum) return unknown(`found ${version}; the minimum in package.json could not be read`);
+  if (compareVersions(version, minimum) >= 0) return found(version);
+  return { status: 'missing', version, note: `older than ${minimum}, the minimum this package declares` };
+}
+
+function claudeCliVersion(shell) {
+  const result = cliVersion(shell, 'claude --version');
+  const { model, version } = CLAUDE_CLI_MINIMUM_FOR_MODEL;
+  if (result.status !== 'found' || compareVersions(result.version, version) >= 0) return result;
+  return { ...result, status: 'warning', note: `older than ${version}, the minimum the vendor named for the model ${model}; calls to that model fail until the CLI is updated` };
+}
+
+// The vendors' own sign-in status commands, reduced to a fixed note. Nothing of their output
+// leaves these functions. 'found' means signed in with the subscription; an API key or a third
+// party is a warning, since calls would then use paid API credentials.
+const SUBSCRIPTION = found(null, 'signed in with the subscription');
+const PAID_API = { status: 'warning', version: null, note: 'signed in with an API key or a third party: paid API credentials would be used' };
+const SIGNED_OUT = missing('not signed in');
+const UNREAD = unknown('sign-in status could not be read');
+
+// Seen: "Logged in using ChatGPT", "Logged in using an API key - <masked key>", "Not logged in".
+function codexSignIn(shell) {
+  const r = shell('codex login status');
+  if (/not logged in/i.test(r.out)) return SIGNED_OUT;
+  if (!r.ok) return UNREAD;
+  if (/logged in using chatgpt/i.test(r.out)) return SUBSCRIPTION;
+  return /logged in using an api key/i.test(r.out) ? PAID_API : UNREAD;
+}
+
+// Seen in `--json`: authMethod 'claude.ai' with apiProvider 'firstParty' for a subscription,
+// authMethod 'api_key' for an API key; another apiProvider is a third party.
+function claudeSignIn(shell) {
+  let status;
+  try {
+    status = JSON.parse(shell('claude auth status --json').out.match(/\{[\s\S]*\}/)?.[0] ?? '');
+  } catch {
+    return UNREAD;
+  }
+  if (status?.loggedIn === false) return SIGNED_OUT;
+  if (status?.loggedIn !== true) return UNREAD;
+  if (status.authMethod === 'claude.ai' && status.apiProvider === 'firstParty') return SUBSCRIPTION;
+  return status.authMethod === 'api_key' || (status.apiProvider && status.apiProvider !== 'firstParty') ? PAID_API : UNREAD;
+}
+
+// Chromium browsers keep one folder per installed version next to the executable.
+function installedVersion(...relative) {
+  if (!isWin) return NOT_CHECKED_HERE;
+  const roots = [process.env.ProgramFiles, process.env['ProgramFiles(x86)'], process.env.LOCALAPPDATA].filter(Boolean);
+  for (const root of roots) {
+    const dir = path.join(root, ...relative);
+    if (!existsSync(dir)) continue;
+    const versions = readdirSync(dir).filter((name) => /^\d+(\.\d+){2,3}$/.test(name)).sort(compareVersions);
+    if (versions.length > 0) return found(versions.at(-1));
+  }
+  return missing();
+}
+
+function queryStoreApps(capture) {
+  const script = "Get-AppxPackage | Where-Object { $_.Name -match 'Claude|OpenAI|ChatGPT' } | ForEach-Object { $_.Name + ' ' + $_.Version }";
+  const r = capture('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script]);
+  if (!r.ok) return null;
+  return r.out.split(/\r?\n/).map((line) => line.trim().split(' ')).filter((parts) => parts.length === 2);
+}
+
+function storeApp(apps, pattern) {
+  if (!isWin) return NOT_CHECKED_HERE;
+  if (!apps) return unknown('could not query installed Store packages');
+  const hit = apps.find(([name]) => pattern.test(name));
+  return hit ? found(hit[1], `Store package ${hit[0]}`) : missing('no Store package; other install types are not detected');
+}
+
+function wslDistros(capture) {
+  if (!isWin) return NOT_CHECKED_HERE;
+  const r = capture('wsl.exe', ['-l', '-q'], { encoding: 'utf16le' });
+  const names = r.out.split(/\r?\n/).map((line) => line.replace(/\0/g, '').trim()).filter(Boolean);
+  return r.ok && names.length > 0 ? found(null, `${names.length} distro(s)`) : missing();
+}
+
+function sessionStore(dir, isSessionFile) {
+  if (!existsSync(dir)) return missing();
+  const entries = readdirSync(dir, { withFileTypes: true, recursive: true });
+  const count = entries.filter((entry) => entry.isFile() && isSessionFile(entry.name)).length;
+  return found(null, `${count} session files`);
+}
+
+// The folder is named by its variable, never by its path, which can hold a user name.
+function stateFolder() {
+  if (canWrite(defaultStateDir())) return found();
+  return missing('cannot be created or written; set NOMEAT_STATE_DIR to a folder this process can write');
+}
+
+function githubCli(shell) {
+  const version = cliVersion(shell, 'gh --version');
+  if (version.status !== 'found') return version;
+  return { ...version, note: shell('gh auth status').ok ? 'signed in' : 'not signed in' };
+}
+
+// --- inspectPrerequisites ---
+
+// Synchronous. `ok` is false when a required check is missing. `capture(file, args, options)`
+// returns `{ ok, out }`; tests inject one.
+export function inspectPrerequisites({ capture = runCommand } = {}) {
+  const shell = (command) => capture(command, [], { shell: true });
+  const apps = isWin ? queryStoreApps(capture) : null;
+  const codexHome = process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+  const claudeHome = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), '.claude');
+  const check = (id, required, result) => ({ id, required, ...result });
+  const checks = [
+    check('codex-cli', true, cliVersion(shell, 'codex --version')),
+    check('codex-auth', true, codexSignIn(shell)),
+    check('codex-queue-thread', false, cliSupports(shell, 'codex queue --help', /--thread/, '`codex queue --thread`')),
+    check('codex-exec-resume', false, cliSupports(shell, 'codex exec resume --help', /SESSION_ID/, '`codex exec resume`')),
+    check('codex-sessions', false, sessionStore(path.join(codexHome, 'sessions'), (name) => /\.jsonl(\.zst)?$/.test(name))),
+    check('claude-cli', true, claudeCliVersion(shell)),
+    check('claude-auth', true, claudeSignIn(shell)),
+    check('claude-resume', false, cliSupports(shell, 'claude --help', /--resume/, '`claude -p --resume`')),
+    check('claude-sessions', false, sessionStore(path.join(claudeHome, 'projects'), (name) => name.endsWith('.jsonl'))),
+    check('codex-app', false, storeApp(apps, /codex/i)),
+    check('claude-app', false, storeApp(apps, /^claude$/i)),
+    check('chatgpt-app', false, storeApp(apps, /chatgpt/i)),
+    check('chrome', false, installedVersion('Google', 'Chrome', 'Application')),
+    check('edge', false, installedVersion('Microsoft', 'Edge', 'Application')),
+    check('node', true, nodeVersionCheck()),
+    check('state-folder', true, stateFolder()),
+    check('git', false, cliVersion(shell, 'git --version')),
+    check('github-cli', false, githubCli(shell)),
+    check('tailscale', false, cliVersion(shell, 'tailscale version')),
+    check('wsl', false, wslDistros(capture)),
+  ];
+  return { ok: !checks.some((c) => c.required && c.status === 'missing'), checks };
+}
+
+// --- host ---
+
+function readOsRelease() {
+  try {
+    return readFileSync('/etc/os-release', 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// The host line of the report. Where /etc/os-release exists, as on Linux, the distribution and
+// its version; elsewhere the system's own description, which on Linux is only the kernel build.
+export function describeHost(osRelease = readOsRelease()) {
+  const field = (key) => osRelease?.match(new RegExp(`^${key}=["']?(.*?)["']?\s*$`, 'm'))?.[1];
+  const distribution = field('PRETTY_NAME') || [field('NAME'), field('VERSION_ID')].filter(Boolean).join(' ');
+  return `${distribution || os.version()} (${os.release()}), ${os.arch()}`;
+}