flowviant 0.102.2 → 0.104.0

package/bin/lib/turnLock.mjs

@@ -0,0 +1,68 @@
+/**
+ * THE CROSS-PROCESS TURN LOCK — the one reading of "is a CLI of ours already
+ * working in this directory".
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). It is read by the session
+ * lane before a spawn and by the ship executor before a merge, and it is pure
+ * over the disk and the kernel: no manager state, so it needs no factory and
+ * is tested directly (turnLock.test.mjs). The lock FILE's path is the
+ * caller's (`sessionMetaPath(wt, 'flowviant-turn.lock')`); what a pid in it
+ * means is this module's.
+ */
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { processStartTime } from './procRegistry.mjs';
+
+/**
+ * The spawn lock: the pid of the CLI currently live in this worktree. A
+ * restarted daemon must not put a second Claude into a directory the orphan
+ * of its previous life is still editing — two CLIs appending to one held
+ * conversation is exactly the incoherence workChains prevents in-process,
+ * and the lock extends that guarantee across a restart. A dead pid is a
+ * stale lock (removed here); a live one means "come back next poll".
+ *
+ * …AND A PID IS ONLY THE HOLDER WHILE IT IS STILL THE SAME PROCESS.
+ *
+ * The lock outlives a reboot or a daemon killed mid-turn, and pids are
+ * recycled. Two readings treated a stranger as the holder and wedged every
+ * turn and ship in the place until somebody deleted the file by hand: EPERM
+ * was read as "alive, just not ours" — but the lock only ever holds a CLI this
+ * daemon spawned under its own uid, so a pid we may not signal is by
+ * definition not ours, i.e. stale — and a recycled pid of our OWN uid
+ * answered signal 0 like the CLI it replaced. The lock now records the
+ * process's start time beside the pid (`pid:start`); a live pid whose start
+ * time differs is a different process. A lock with no start time (written by
+ * an older daemon) keeps the old signal-0 reading, minus EPERM.
+ */
+export const turnLockedByLivePid = (lockPath) => {
+  if (!lockPath || !existsSync(lockPath)) return false;
+  let pid = 0;
+  let start = null;
+  try {
+    const raw = readFileSync(lockPath, 'utf8').trim();
+    const cut = raw.indexOf(':');
+    pid = Number(cut < 0 ? raw : raw.slice(0, cut));
+    start = cut < 0 ? null : raw.slice(cut + 1) || null;
+  } catch {
+    /* unreadable — treat as stale */
+  }
+  if (Number.isInteger(pid) && pid > 0) {
+    let alive = false;
+    try {
+      process.kill(pid, 0);
+      alive = true; // signal 0 delivered — a process of OUR uid holds the pid
+    } catch {
+      /* ESRCH: gone. EPERM: another uid's process — never our CLI. Stale. */
+    }
+    if (alive) {
+      const now = start ? processStartTime(pid) : null;
+      // Unmeasurable start time is "cannot tell", which keeps the lock.
+      if (!start || !now || now === start) return true;
+    }
+  }
+  try {
+    rmSync(lockPath, { force: true }); // dead holder — clear the stale lock
+  } catch {
+    /* best-effort */
+  }
+  return false;
+};

package/bin/lib/turnProfile.mjs

@@ -0,0 +1,77 @@
+/**
+ * A TURN'S PROFILE — the one name a caller gives `runTurn` for the posture a
+ * CLI turn runs under, and what that name means before any adapter sees it.
+ *
+ * Split out (SOLID F047) because `runTurn` took five independent posture
+ * switches — `wikiPerm`, `readOnly`, `planPerm`, `planMode`, `posture` — and
+ * resolved them through two separate precedence chains (one for the adapter's
+ * profile name, one for Claude's permission list). A caller could say two
+ * things at once (a plan turn that is also read-only) and the answer was
+ * whichever branch came first. Now a caller names ONE profile; a name this
+ * table does not know, or any of the retired switches, fails the turn in
+ * words instead of falling through to the build posture.
+ *
+ * The profiles:
+ *  - build     — the default: the operator's own build posture;
+ *  - wiki      — the cartographer: writes only the vault;
+ *  - consult   — read-only (the scratch planner, the AI pre-review);
+ *  - plan      — the capture chat: read-only plus its control plane;
+ *  - plan-mode — a Workbench plan turn: Claude Code's own
+ *                `--permission-mode plan`, REPLACING the build posture, no MCP.
+ *                Claude only. The adapter sees `build` (argv is `perm`);
+ *  - design / research — a non-code card's posture (agentTaskKinds.mjs),
+ *                refused on any runtime that does not DECLARE it, because every
+ *                other adapter's fallback is its build branch.
+ *
+ * Claude's permission list for each name lives beside the lists themselves
+ * (`claudePermFor`, claudePosture.mjs); this module owns the vocabulary and the
+ * refusals, and imports only the card-kind table.
+ */
+import { KIND_POSTURES } from './agentTaskKinds.mjs';
+
+const plain = (adapterProfile) => Object.freeze({ adapterProfile, onlyOn: null, strictMcp: false });
+
+export const TURN_PROFILES = Object.freeze({
+  build: plain('build'),
+  wiki: plain('wiki'),
+  consult: plain('consult'),
+  plan: plain('plan'),
+  'plan-mode': Object.freeze({
+    adapterProfile: 'build',
+    // Plan mode is Claude's own flag. The other adapters build argv from the
+    // profile name and never read `perm`, so on them it would be a BUILD turn
+    // wearing the word "plan".
+    onlyOn: (rt) => (rt.id === 'claude' ? null : `plan mode runs on Claude Code only — not '${rt.label}'`),
+    strictMcp: true,
+  }),
+  // The kind postures: fenced to "write only the artifacts directory", and a
+  // runtime that does not declare one would run its build branch instead.
+  ...Object.fromEntries(
+    KIND_POSTURES.map((name) => [
+      name,
+      Object.freeze({
+        adapterProfile: name,
+        onlyOn: (rt) => ((rt.profiles ?? []).includes(name) ? null : `a ${name} card runs on Claude Code only — not '${rt.label}'`),
+        strictMcp: false,
+      }),
+    ])
+  ),
+});
+
+/** The switches `profile` replaced. Passing one is a caller nobody updated —
+ *  and silently ignoring it would run that caller's turn as a BUILD turn. */
+export const RETIRED_POSTURE_KEYS = Object.freeze(['wikiPerm', 'readOnly', 'planPerm', 'planMode', 'posture']);
+
+/**
+ * `{ name, adapterProfile, onlyOn, strictMcp }` for a turn's options, or
+ * `{ error }` in words. Absent `profile` is build.
+ */
+export function resolveTurnProfile(opts = {}) {
+  const retired = RETIRED_POSTURE_KEYS.filter((k) => opts[k] !== undefined);
+  if (retired.length) return { error: `the turn named a retired posture switch (${retired.join(', ')}) — name one profile instead` };
+  const name = opts.profile ?? 'build';
+  if (typeof name !== 'string' || !Object.hasOwn(TURN_PROFILES, name)) {
+    return { error: `unknown turn profile '${String(name).slice(0, 40)}'` };
+  }
+  return { name, ...TURN_PROFILES[name] };
+}

package/bin/lib/uninstall.mjs

@@ -1,13 +1,15 @@
 import * as nodeFs from 'node:fs';
 import { execFile as nodeExecFile } from 'node:child_process';
 import { homedir } from 'node:os';
-import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { runningCompiledBinary } from './update.mjs';
 import { VERSION } from './config.mjs';
+import { parseVersion } from './versionOrder.mjs';
+import { copyKind, exactBlock, inside } from './uninstallCopies.mjs';
+import { disconnectShortfall, removeOnMachinesPage } from './machineDisconnect.mjs';
 
 const execFileAsync = promisify(nodeExecFile);
-const inside = (path, dir) => path === dir || path.startsWith(`${dir}${sep}`);
 const errorWords = (error) => String(error?.stderr || error?.message || error).trim();
 
 function defaults(options = {}) {
@@ -55,11 +57,6 @@ function compiledExecutable(fs, path) {
     return magic === 0x7f454c46 || [0xfeedfacf, 0xcffaedfe, 0xfeedface, 0xcefaedfe, 0xcafebabe].includes(magic);
   } catch { return false; }
 }
-function exactBlock(dir, rc) {
-  const line = basename(rc) === 'flowviant.fish'
-    ? `fish_add_path "${dir}"` : `export PATH="${dir}:$PATH"`;
-  return `\n# flowviant\n${line}\n`;
-}
 
 function liveDaemons(o) {
   const found = [];
@@ -170,7 +167,8 @@ export async function buildUninstallPlan(options = {}) {
     try {
       const output = await o.execFile(copy.path, ['--version'], { timeout: 5000 });
       const version = String(output.stdout).trim();
-      if (/^\d+\.\d+\.\d+/.test(version)) copy.version = version;
+      // The same rule that orders versions decides what IS one (versionOrder.mjs).
+      if (parseVersion(version)) copy.version = version;
     } catch { /* A foreign or older binary may not answer. */ }
   }
   for (let i = copies.length - 1; i >= 0; i--) {
@@ -179,31 +177,19 @@ export async function buildUninstallPlan(options = {}) {
   }
   const daemons = liveDaemons(o);
   for (const copy of copies) {
+    // Every discovered record carries a kind the strategy table knows —
+    // `copyKind` throws on one it does not, so a new kind cannot be planned
+    // without saying what protects it and how it goes.
+    const kind = copyKind(copy.kind);
     const source = real(o.fs, copy.path);
-    copy.current = copy.kind === 'path-line' ? false :
-      (copy.kind === 'binary' ? source === own : inside(own, source));
-    const daemon = daemons.find((d) => !o.procAvailable || !d.paths.length || d.paths.some((p) =>
-      copy.kind === 'binary' ? p === source : inside(p, source)));
-    if (daemon && copy.kind !== 'path-line') copy.runningPid = daemon.pid;
+    copy.current = kind.current(source, own);
+    if (!kind.runsFrom) continue;
+    const daemon = daemons.find((d) => !o.procAvailable || !d.paths.length || d.paths.some((p) => kind.runsFrom(p, source)));
+    if (daemon) copy.runningPid = daemon.pid;
   }
   return { copies, daemons, home: o.home };
 }
 
-function removePathBlock(o, path, block) {
-  const before = o.fs.readFileSync(path);
-  const at = before.indexOf(Buffer.from(block));
-  if (at < 0) return false;
-  const after = Buffer.concat([before.subarray(0, at), before.subarray(at + Buffer.byteLength(block))]);
-  const mode = o.fs.statSync(path).mode & 0o7777;
-  const temp = `${path}.${process.pid}.flowviant-tmp`;
-  try {
-    o.fs.writeFileSync(temp, after, { mode });
-    o.fs.chmodSync(temp, mode);
-    o.fs.renameSync(temp, path);
-  } finally { try { o.fs.rmSync(temp, { force: true }); } catch { /* Renamed. */ } }
-  return true;
-}
-
 export async function runUninstall(options = {}) {
   const o = defaults(options);
   const { others = false, purge = false, yes = false, json = false } = options;
@@ -231,32 +217,54 @@ export async function runUninstall(options = {}) {
       if (tally.failed) result.errors.push(`${tally.failed} daemon(s) could not be stopped`);
     } catch (e) { result.errors.push(`stopping daemons: ${errorWords(e)}`); }
   }
+  /**
+   * THE PURGE READS THE DISCONNECT'S OUTCOME, NEVER ITS SENTENCES.
+   *
+   * This used to match four phrases in the log lines to decide whether the
+   * app had been told, and then deleted `~/.flowviant` anyway — so a leave the
+   * app never heard destroyed the only credential that could tell it. Now a
+   * RETRYABLE shortfall (a daemon that would not stop, a leave the network or
+   * the app refused, a credential that could not be forgotten, or a disconnect
+   * that threw) keeps the local state, and the disconnect is asked to keep
+   * that project's credential after a failed leave, so running the purge again
+   * can finish it. An older server with no leave route is reported and does
+   * not hold the purge: asking it again changes nothing.
+   */
+  const unfinished = [];
   if (purge && !others) {
     try {
       const projects = o.projects || (await import('./credentials.mjs')).listStoredProjects;
       const disconnect = o.disconnect || (async (entry, log) => {
-        const { disconnectHere, realDisconnectDeps, leaveUrlFrom } = await import('./machines.mjs');
+        const { disconnectHere, realDisconnectDeps } = await import('./machineDisconnect.mjs');
+        const { leaveUrlFrom } = await import('./machines.mjs');
         const { FLEET_URL } = await import('./config.mjs');
-        return disconnectHere(entry, await realDisconnectDeps({ url: leaveUrlFrom(FLEET_URL), log }), { log });
+        return disconnectHere(entry, await realDisconnectDeps({ url: leaveUrlFrom(FLEET_URL), log }), { log, forgetAfterFailedLeave: false });
       });
       for (const entry of await projects()) {
         try {
-          const messages = [];
-          const res = await disconnect(entry, (m) => { messages.push(m); line(m); });
-          const failure = messages.find((m) => /could not tell the app|does not take a leave|not disconnected|could not forget/.test(m));
-          if (!res.ok || failure) result.errors.push(`registry removal for ${entry.projectId}: ${failure || messages.at(-1) || 'failed'}`);
-        } catch (e) { result.errors.push(`registry removal for ${entry.projectId}: ${errorWords(e)}`); }
+          const short = disconnectShortfall(await disconnect(entry, line));
+          if (short) {
+            result.errors.push(`registry removal for ${entry.projectId}: ${short.reason}`);
+            if (short.retryable) unfinished.push(entry.projectId);
+          }
+        } catch (e) {
+          result.errors.push(`registry removal for ${entry.projectId}: ${errorWords(e)}`);
+          unfinished.push(entry.projectId);
+        }
       }
-    } catch (e) { result.errors.push(`reading projects: ${errorWords(e)}`); }
+    } catch (e) {
+      result.errors.push(`reading projects: ${errorWords(e)}`);
+      unfinished.push(null);
+    }
   }
 
   for (const c of plan.copies) {
     const item = { kind: c.kind, path: c.path };
+    const kind = copyKind(c.kind);
     let reason = c.skipReason;
     if (others && c.current) reason = 'running copy';
     if (others && c.runningPid) reason = `a daemon is running from it (pid ${c.runningPid})`;
-    if (others && c.kind === 'path-line' && plan.daemons.length && !o.procAvailable) reason = 'a daemon may be using this copy';
-    if (others && c.kind === 'path-line' && plan.copies.some((copy) => copy.kind === 'binary' && copy.current && c.block === exactBlock(dirname(copy.path), c.path))) reason = 'needed by the running binary';
+    if (others) reason = kind.othersSkip(c, plan, o) ?? reason;
     if (reason) {
       result.skipped.push({ ...item, reason });
       // The copy doing the work is not news; every other skip is.
@@ -264,16 +272,18 @@ export async function runUninstall(options = {}) {
       continue;
     }
     try {
-      if (c.kind === 'npm-global') await o.execFile('npm',
-        c.npmPrefix ? ['uninstall', '-g', '--prefix', c.npmPrefix, 'flowviant'] : ['uninstall', '-g', 'flowviant'],
-        { timeout: 120000 });
-      else if (c.kind === 'path-line') removePathBlock(o, c.path, c.block);
-      else o.fs.rmSync(c.removal, { recursive: c.kind === 'npx-cache', force: true });
+      await kind.remove(c, o);
       result.removed.push(item);
-      if (!json) line(c.kind === 'path-line' ? `removed the flowviant PATH line from ${c.path}` : `removed ${c.path}`);
+      if (!json) line(kind.removedLine(c));
     } catch (e) { result.errors.push(`${c.path}: ${errorWords(e)}`); }
   }
-  if (purge && !others) {
+  if (purge && !others && unfinished.length) {
+    result.kept.push(join(o.home, '.flowviant'));
+    // Every retryable shortfall lands here (a daemon that would not stop, a
+    // leave or a forget that failed, projects that could not be read); the
+    // `error:` lines below name which, so this line claims none of them.
+    if (!json) line(`Kept ~/.flowviant: the purge did not finish for every project (see the errors below). Reinstall and run \`flowviant uninstall --purge\` again to finish, or ${removeOnMachinesPage('this box')}.`);
+  } else if (purge && !others) {
     try { o.fs.rmSync(join(o.home, '.flowviant'), { recursive: true, force: true }); }
     catch (e) { result.errors.push(`local purge: ${errorWords(e)}`); }
   } else {

package/bin/lib/uninstallCopies.mjs

@@ -0,0 +1,112 @@
+/**
+ * WHAT EACH KIND OF INSTALLED COPY MEANS TO UNINSTALL — one entry per kind,
+ * holding the three questions uninstall asks of a copy: is it the copy this
+ * process runs from, does a live daemon run from it, and how is it removed
+ * (plus the words a person reads about it).
+ *
+ * Split out of uninstall.mjs (SOLID F058): discovery, protection and removal
+ * each branched on the kind string separately, so a new kind of install was
+ * three coordinated edits and a missed one removed a copy a daemon was
+ * running from. `buildUninstallPlan` still owns DISCOVERY (where copies are);
+ * this table owns what a copy of each kind IS. A record whose kind has no
+ * entry here is refused at planning, never guessed at.
+ */
+import { basename, dirname, sep } from 'node:path';
+
+export const inside = (path, dir) => path === dir || path.startsWith(`${dir}${sep}`);
+
+/** The installer's PATH block for `dir` in rc file `rc`, byte for byte. */
+export function exactBlock(dir, rc) {
+  const line = basename(rc) === 'flowviant.fish' ? `fish_add_path "${dir}"` : `export PATH="${dir}:$PATH"`;
+  return `\n# flowviant\n${line}\n`;
+}
+
+function removePathBlock(o, path, block) {
+  const before = o.fs.readFileSync(path);
+  const at = before.indexOf(Buffer.from(block));
+  if (at < 0) return false;
+  const after = Buffer.concat([before.subarray(0, at), before.subarray(at + Buffer.byteLength(block))]);
+  const mode = o.fs.statSync(path).mode & 0o7777;
+  const temp = `${path}.${process.pid}.flowviant-tmp`;
+  try {
+    o.fs.writeFileSync(temp, after, { mode });
+    o.fs.chmodSync(temp, mode);
+    o.fs.renameSync(temp, path);
+  } finally {
+    try {
+      o.fs.rmSync(temp, { force: true });
+    } catch {
+      /* Renamed. */
+    }
+  }
+  return true;
+}
+
+/**
+ * The strategies. For each kind:
+ *  - `label`: how `doctor` names it;
+ *  - `current(source, own)`: is this the copy this process runs from;
+ *  - `runsFrom(daemonPath, source)`: does a daemon whose command names
+ *    `daemonPath` run from this copy — null for a kind no daemon can run from;
+ *  - `othersSkip(copy, plan, o)`: an extra reason `--others` must leave it
+ *    (beyond "current" and "a daemon runs from it", which every kind obeys);
+ *  - `remove(copy, o)`: the removal itself (may be async);
+ *  - `removedLine(copy)`: what a person reads after it;
+ *  - `removeHint`: what `doctor` adds after "uninstall --others" when that
+ *    removal can need more than the command ('' when it cannot).
+ */
+export const COPY_KINDS = Object.freeze({
+  binary: {
+    removeHint: '',
+    label: 'binary',
+    current: (source, own) => source === own,
+    runsFrom: (p, source) => p === source,
+    othersSkip: () => null,
+    remove: (c, o) => o.fs.rmSync(c.removal, { recursive: false, force: true }),
+    removedLine: (c) => `removed ${c.path}`,
+  },
+  'npm-global': {
+    removeHint: ' (if npm refuses, `sudo npm uninstall -g flowviant`)',
+    label: 'npm global',
+    current: (source, own) => inside(own, source),
+    runsFrom: (p, source) => inside(p, source),
+    othersSkip: () => null,
+    remove: (c, o) =>
+      o.execFile('npm', c.npmPrefix ? ['uninstall', '-g', '--prefix', c.npmPrefix, 'flowviant'] : ['uninstall', '-g', 'flowviant'], {
+        timeout: 120000,
+      }),
+    removedLine: (c) => `removed ${c.path}`,
+  },
+  'npx-cache': {
+    removeHint: '',
+    label: 'npx cache',
+    current: (source, own) => inside(own, source),
+    runsFrom: (p, source) => inside(p, source),
+    othersSkip: () => null,
+    remove: (c, o) => o.fs.rmSync(c.removal, { recursive: true, force: true }),
+    removedLine: (c) => `removed ${c.path}`,
+  },
+  'path-line': {
+    removeHint: '',
+    label: 'PATH line',
+    // An rc file line is never "the copy this process runs from", and no
+    // daemon runs from it — but the binary it puts on PATH may be running.
+    current: () => false,
+    runsFrom: null,
+    othersSkip: (c, plan, o) => {
+      if (plan.copies.some((copy) => copy.kind === 'binary' && copy.current && c.block === exactBlock(dirname(copy.path), c.path)))
+        return 'needed by the running binary';
+      if (plan.daemons.length && !o.procAvailable) return 'a daemon may be using this copy';
+      return null;
+    },
+    remove: (c, o) => removePathBlock(o, c.path, c.block),
+    removedLine: (c) => `removed the flowviant PATH line from ${c.path}`,
+  },
+});
+
+/** The strategy for a copy's kind. Throws on a kind with no entry. */
+export function copyKind(kind) {
+  const k = Object.hasOwn(COPY_KINDS, kind) ? COPY_KINDS[kind] : null;
+  if (!k) throw new Error(`unknown installed-copy kind '${kind}'`);
+  return k;
+}

package/bin/lib/update.mjs

@@ -39,18 +39,14 @@ import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
 import { runningViaNpx, terminalCommand } from './launchCommand.mjs';
 import { VERSION } from './config.mjs';
+import { compareVersions, versionBelow } from './versionOrder.mjs';
 import { note, ok, warn } from './ui.mjs';
 
-/** Compare x.y.z version strings → -1 | 0 | 1 (missing parts read as 0). */
-export function cmpVersion(a, b) {
-  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
-  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
-  for (let i = 0; i < 3; i++) {
-    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
-    if (d !== 0) return d > 0 ? 1 : -1;
-  }
-  return 0;
-}
+/*
+ * Version order lives in versionOrder.mjs. Every decision here treats an
+ * UNKNOWN comparison (a version that does not parse) as "nothing to do": it
+ * never installs, never restarts and never nags on a version it cannot read.
+ */
 
 /** Bun marks compiled entrypoints with a virtual /$bunfs/ script path. */
 export function runningCompiledBinary() {
@@ -79,7 +75,7 @@ export async function installBinaryUpdate({
       !Number.isSafeInteger(file?.bytes) || file.bytes <= 0) {
     throw new Error('invalid release manifest');
   }
-  if (minimumVersion && cmpVersion(version, minimumVersion) < 0) {
+  if (minimumVersion && versionBelow(version, minimumVersion)) {
     throw new Error(`release manifest still serves ${version}; waiting for ${minimumVersion}`);
   }
   const binaryResponse = await fetchImpl(`${origin}/dl/${version}/${file.name}`);
@@ -180,7 +176,10 @@ function reexec(teardown, { viaNpx = false, viaBinary = false, target = null } =
 export function updateRestartFailed(target) {
   const attempted = process.env.FLOWVIANT_UPDATE_TARGET;
   if (!attempted) return false;
-  return cmpVersion(VERSION, attempted) < 0 && cmpVersion(target ?? attempted, attempted) <= 0;
+  // Unknown on either comparison is "cannot tell", which is not a failure.
+  const nowVsAttempted = compareVersions(VERSION, attempted);
+  const targetVsAttempted = compareVersions(target ?? attempted, attempted);
+  return nowVsAttempted === -1 && targetVsAttempted !== null && targetVsAttempted <= 0;
 }
 
 /** Install @latest globally. Throws on failure (EACCES without sudo, offline…). */
@@ -227,16 +226,28 @@ let naggedFor = null;
 let lastInstallFailAt = 0;
 const INSTALL_RETRY_MS = 15 * 60_000;
 
+/**
+ * WHICH VERSION A {latest, min} SIGNAL ASKS FOR. Only a signal the running
+ * version is measurably below counts (an unreadable one is unknown, never
+ * below); latest wins when it counts, else min. An unreadable latest never
+ * becomes the target — it would feed an install a minimum nothing can meet.
+ * `{ target: null }` = nothing to do.
+ */
+export function versionSignalTarget(cur, { latest, min }) {
+  const belowMin = Boolean(min) && versionBelow(cur, min);
+  const belowLatest = Boolean(latest) && versionBelow(cur, latest);
+  if (!belowMin && !belowLatest) return { target: null, belowMin: false };
+  return { target: belowLatest ? latest : min, belowMin };
+}
+
 /**
  * React to the server's {latest, min} signal from a roster poll.
  * @returns true if it kicked off a self-update + re-exec (caller must stop).
  */
 export async function handleVersionSignal({ latest, min, autoUpdate, safeToUpdate, teardown }) {
   const cur = VERSION;
-  const belowMin = min && cmpVersion(cur, min) < 0;
-  const belowLatest = latest && cmpVersion(cur, latest) < 0;
-  if (!belowMin && !belowLatest) return false; // current — nothing to do
-  const target = latest || min;
+  const { target, belowMin } = versionSignalTarget(cur, { latest, min });
+  if (!target) return false; // current, or nothing readable — nothing to do
   const npx = runningViaNpx();
   const binary = runningCompiledBinary();
   const wantInstall = belowMin || autoUpdate;
@@ -340,7 +351,9 @@ export async function handleVersionSignal({ latest, min, autoUpdate, safeToUpdat
     } catch {
       /* offline / npm hiccup — treat as "can't confirm", skip this poll */
     }
-    if (!published || cmpVersion(published, cur) <= 0) {
+    // An unreadable answer from npm is "can't confirm", like no answer at all.
+    const publishedOrder = published ? compareVersions(published, cur) : null;
+    if (publishedOrder === null || publishedOrder <= 0) {
       if (naggedFor !== target) {
         naggedFor = target;
         note(`update ${target} announced but npm still serves ${published ?? '?'} — waiting for the publish.`);