flowviant 0.82.0 → 0.84.0

package/bin/lib/fleet.mjs

@@ -24,6 +24,7 @@ import {
   MCP_URL,
   SAFE,
   DAEMON_INSTANCE,
+  MACHINE_HOST,
   POLL_SECONDS,
   MAX_CONCURRENT,
   IDLE_SECONDS,
@@ -87,10 +88,18 @@ import { scanLocalSessions, ourConversationIds } from './localSessions.mjs';
 import { repoState } from './repoState.mjs';
 import { claudeAuthContext } from './claudeAuth.mjs';
 
+/** Said once per process — see the catch around `envQueryParams` below. */
+let warnedEnvIdentity = false;
+
 async function fetchRoster(
   haveIds,
   livePreviewSessionIds = [],
-  heldSessionIds = []
+  heldSessionIds = [],
+  /** The churn ADMISSION verdict, taken by the caller from the same `admit`
+   *  every unattended lane asks — see the `pr` param below for why it is the
+   *  admission and not the pressure reading alone. Undefined where the caller
+   *  has no admission to offer, which reads exactly like an older daemon. */
+  churnHold = undefined
 ) {
   const url = new URL(FLEET_URL);
   if (haveIds.length) url.searchParams.set('have', haveIds.join(','));
@@ -115,6 +124,15 @@ async function fetchRoster(
   // WHICH PROCESS, so the server can lease preview work to exactly one of two
   // daemons on one credential. Older servers ignore unknown params.
   url.searchParams.set('di', DAEMON_INSTANCE);
+  // WHICH BOX, by name, so the app can say "your machine is mac-mini" instead
+  // of naming a public key. Display only: arbitration is keyed on `envpub`,
+  // which is durable per box, while a hostname is neither unique nor stable.
+  // Absent when the host has no readable name — an older daemon looks the same,
+  // and both mean "nobody said", which is what the nameless fallback renders.
+  if (MACHINE_HOST) url.searchParams.set('mh', MACHINE_HOST);
+  // NOTHING HERE ASKS FOR THE MACHINE. A poll reports what this box IS; moving
+  // the project's machine onto it is a gesture a person makes in the app, and
+  // the daemon learns the outcome on its next poll like every other holder fact.
   // Which shares this machine is still serving. It rides the poll rather than
   // taking an endpoint of its own: one beat, no floor, and the stale window is
   // the reconcile interval instead of minutes — which matters, because a share
@@ -174,8 +192,75 @@ async function fetchRoster(
     for (const [k, v] of Object.entries(await envQueryParams())) {
       if (v != null) url.searchParams.set(k, v);
     }
-  } catch {
+  } catch (e) {
     /* env identity is best-effort — the poll must never fail on it */
+    /**
+     * …BUT IT IS NOT SILENT, because since 2026-09-14 losing it costs
+     * something visible. `envpub` is how the server tells two computers apart,
+     * so a poll without one is EXEMPT from arbitration — it is served in full,
+     * which is right — and nothing stamps `holder_heard_at`, which is the
+     * column presence is now read from. The app therefore says the machine is
+     * offline while this daemon is sitting here answering turns, and before
+     * this line the only evidence anywhere was a keypair file nobody looks at.
+     *
+     * Once per process: it is the same failure on every poll, and a reason
+     * repeated every few seconds is a reason nobody reads.
+     */
+    if (!warnedEnvIdentity) {
+      warnedEnvIdentity = true;
+      console.warn(
+        `[flowviant] could not read ${'~/.flowviant/env-keypair.json'} (${e?.message ?? e}).\n` +
+          '  This machine cannot identify itself, so the app may show it as offline while it works.\n' +
+          '  It has NOT been replaced — that file is what the project secrets are sealed to.'
+      );
+    }
+  }
+  /**
+   * WHY THIS MACHINE IS NOT TAKING NEW WORK, in its own measured words.
+   *
+   * Three states, and the third is why this is a param and not a header:
+   *   · a reason  — the churn ADMISSION refused; new unattended work is being
+   *                 deferred, and the board can say so AT the agent that is
+   *                 waiting instead of leaving it looking like a slow model.
+   *   · `-`       — asked, and nothing is holding anything back. A POSITIVE
+   *                 fact, which is what lets the server clear a stale reason
+   *                 rather than letting one sit there being true-looking
+   *                 forever.
+   *   · absent    — an older daemon, or a poll with no admission to ask. The
+   *                 reserved meaning, and the reason nothing is sent in that
+   *                 case: silence must not be readable as "fine".
+   *
+   * `FLOWVIANT_NO_PRESSURE_GUARD` no longer silences the param, and should not:
+   * it turns off the MEMORY AND LOAD half, and the concurrency half it does not
+   * touch is still a true account of why nothing is starting. What the operator
+   * asked for is a box that is not second-guessed about its own memory, not an
+   * agent that sits still with no explanation.
+   *
+   * IT IS THE WHOLE ADMISSION, AND IT USED TO BE THE PRESSURE HALF ONLY. The
+   * argument for narrowing it was that "four turns are running" is a capacity
+   * statement — but the effect was worse than the thing it avoided: a machine
+   * refusing every agent turn at its ceiling sent `pr=-`, which says MEASURED
+   * AND FINE, so the server cleared any stored reason and the board fell
+   * through to "nothing has polled this turn for 12m" over a daemon that was
+   * polling every ten seconds and declining on purpose. The machine positively
+   * asserted health at the one moment it was refusing.
+   *
+   * And CLAUDE.md already carves this exact shape out: queueing is said "AT THE
+   * THING THAT IS WAITING, in the moment, never budgeted for in advance on a
+   * global chip". The relayed sentence is `admission.mjs`'s, and it names
+   * ACTIVITY — "the machine is already running 3 CLI turns" — never the
+   * ceiling, never headroom, and never anywhere but on the row that is stalled.
+   * That is the same shape as a CLI relaying that it hit its own limit.
+   *
+   * `URLSearchParams` does its own encoding; the slice is the belt against a
+   * pathological reason.
+   */
+  try {
+    if (churnHold !== undefined) {
+      url.searchParams.set('pr', churnHold ? String(churnHold.reason).slice(0, 160) : '-');
+    }
+  } catch {
+    /* a readout — the poll must never fail on one */
   }
   // An explicit User-Agent is required: Node's default ("node"/empty) trips
   // Cloudflare Bot Fight Mode (403). A descriptive product UA passes.
@@ -420,6 +505,193 @@ export function shouldStop(rosterDaemon) {
   return { stop: true, reason };
 }
 
+/**
+ * HOW LONG AGO, in the words the standby sentence needs. Milliseconds in, one
+ * short label out; anything that is not a finite, non-negative number renders
+ * NOTHING and the caller drops the clause rather than printing "heard NaN ago".
+ * The three-state rule applied to a duration: measured, or say nothing.
+ */
+export function agoLabel(ms) {
+  // `typeof`, not `Number()`: `Number(null)` is 0, so a coercing guard turns
+  // "the server said nothing" into "heard 0s ago" — a measurement nobody took,
+  // printed at the one moment the person is deciding whether to wait.
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) return null;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.round(h / 24)}d`;
+}
+
+/**
+ * WHOSE MACHINE THIS IS — read off the roster, said once, and never a refusal.
+ *
+ * A project has ONE machine credential and `device/approve` hands every device
+ * the same raw token, so two boxes running `npx flowviant` are two daemons that
+ * both believe they are the machine. The old behaviour was a silent race: the
+ * loser could not see the winner at all, and the moment the winner went quiet
+ * long enough for a lease to lapse it cut a FRESH branch for an agent whose work
+ * exists only on the other box's disk, then ran a CLI with no conversation
+ * behind it. A confident, context-free redo of work somebody was mid-way
+ * through.
+ *
+ * The server arbitrates (it is the only party that can see both boxes) and the
+ * answer rides the poll RESPONSE as `holder`. This turns that answer into what
+ * the person at the keyboard needs to know, and nothing more:
+ *
+ *   · ABSENT        -> this server does not arbitrate machines. Behave exactly
+ *                      as every daemon before 0.84.0 did — zero new paths.
+ *   · mine: true    -> we are the machine. Announce it only if we have been
+ *                      standing by, so an ordinary daemon prints nothing new.
+ *   · mine: false   -> STAND BY. Keep polling quietly; the restricted roster
+ *                      serves us nothing, the auto-handover makes this box the
+ *                      machine when the holder dies, and the app is where a
+ *                      person moves it sooner. Never exit: a standby that quits
+ *                      is a box somebody has to go and restart by hand.
+ *
+ * Printed ONCE PER DISTINCT HOLDER rather than per poll — a true sentence
+ * restated every ten seconds is a scrolling console nobody reads, and the fact
+ * only CHANGES when the holder does.
+ *
+ * Pure except for the injected `say`, so the whole decision can be proved
+ * without a credential, a server or a second box.
+ */
+export function createHolderWatch({ say = () => {} } = {}) {
+  let standbyKey = null; // the holder we last announced, or null while we serve
+  return {
+    /** Returns 'absent' | 'mine' | 'standby' — the state, for the caller's
+     *  own gating and for tests that must not read the console. */
+    observe(holder) {
+      if (!holder || typeof holder !== 'object' || Array.isArray(holder)) {
+        // An older server, or a poll it did not arbitrate. Silence, and not one
+        // new path: this is the 0.83.0 daemon.
+        return 'absent';
+      }
+      if (holder.mine === true) {
+        if (standbyKey !== null) {
+          standbyKey = null;
+          say('this machine now serves the project.');
+        }
+        return 'mine';
+      }
+      // The NAME is all the response carries about the other box, so it is also
+      // the only thing "a distinct holder" can be keyed on. An unnamed holder
+      // keys on the empty string, which is stable — one announcement, not one
+      // per poll.
+      const name = typeof holder.name === 'string' && holder.name.trim()
+        ? holder.name.trim().slice(0, 64)
+        : null;
+      const key = name ?? '';
+      if (key !== standbyKey) {
+        standbyKey = key;
+        const ago = agoLabel(holder.heardAgo);
+        // THE SENTENCE POINTS AT THE APP, NEVER AT A COMMAND. The owner's
+        // ruling, verbatim: "i dont intend to run or do anything in the
+        // terminal besides npx flowviant or npx flowviant login." So the
+        // terminal surface is those two commands, full stop — this box waits
+        // or a person moves the machine from project settings, and there is no
+        // third thing to type here. An earlier cut of this sentence ended by
+        // telling the person to re-run this daemon with a claim flag; that flag
+        // is deleted, and the gesture is the app's — where the server can see
+        // both boxes and every daemon learns the outcome on its next poll.
+        //
+        // The ago clause DROPS whole when unmeasured — agoLabel returns null
+        // rather than a zero — because "heard 0s ago" is a measurement nobody
+        // took, printed at the one moment the person is deciding whether to
+        // wait.
+        say(
+          `This project's machine is ${name ?? 'another machine'}${ago ? ` (heard ${ago} ago)` : ''}. ` +
+            'It moves here automatically once that machine has been quiet 10 minutes ' +
+            "— or move it now from the app's project settings."
+        );
+      }
+      return 'standby';
+    },
+  };
+}
+
+/** The sentence an in-flight agent turn is settled with when the machine moves
+ *  out from under it. MEASURED, not inferred: the server named the box that
+ *  took over, and an unnamed one says so rather than guessing. */
+export function displacedTurnSentence(by) {
+  const name = typeof by === 'string' && by.trim() ? by.trim().slice(0, 64) : 'another machine';
+  return `The project's machine moved to ${name} while this turn was running.`;
+}
+
+/**
+ * THE MACHINE MOVED. STAND DOWN.
+ *
+ * The server sends `displaced` only when it is aimed at THIS box (it matches the
+ * poll's own `envpub`) and only inside a short window, so there is nothing to
+ * re-derive here and nothing to honour from last week — the same shape, and the
+ * same reasoning, as the commanded stop above.
+ *
+ * Unlike the signal handlers this path is poll-response-driven, so it CAN await:
+ * every in-flight agent turn is settled first, because a turn this daemon
+ * abandons silently sits pending until the server's six-hour expiry while the
+ * board shows an agent working on a machine that has gone. `nothing` is the
+ * honest outcome and the sentence says what happened.
+ *
+ * EXIT 0, for the reason the two existing terminal paths (the commanded stop,
+ * and the revoked credential above it) both document: under `Restart=on-failure`
+ * a nonzero code has systemd relaunch this daemon immediately, where it would
+ * poll, be told again that it is not the machine, and stand down again — a
+ * restart loop fighting a decision somebody made on purpose.
+ *
+ * Every dependency is injected so the whole stand-down can be proved without a
+ * server, a repo or a process to kill.
+ */
+export async function standDownDisplaced({
+  by,
+  settleAgentTurns,
+  flushReports,
+  teardown,
+  exit,
+  log = { warn: () => {}, note: () => {} },
+}) {
+  /** A bound on a wedged uplink, and never a reason to hang: the timer is
+   *  unref'd, so the only thing that keeps this process alive is the work. */
+  const bounded = (p, seconds) =>
+    Promise.race([
+      p,
+      new Promise((resolve) => {
+        const t = setTimeout(resolve, seconds * 1000);
+        t.unref?.();
+      }),
+    ]);
+  const name = typeof by === 'string' && by.trim() ? by.trim().slice(0, 64) : null;
+  log.warn(
+    name
+      ? `this project's machine moved to ${name} — standing down.`
+      : "this project's machine moved to another box — standing down."
+  );
+  // FIRST, and awaited: an unsettled turn is the one thing here that no later
+  // poll from anybody can fix — this process holds the only copy of the fact
+  // that it was running.
+  try {
+    await bounded(settleAgentTurns(displacedTurnSentence(by)), 10);
+  } catch {
+    /* an unsettled turn expires server-side with words of its own */
+  }
+  // THEN the queued settles, bounded exactly as the commanded stop bounds them:
+  // a queued report is a COMPLETED turn whose side effects already happened, and
+  // dropping it re-runs the whole turn somewhere else.
+  try {
+    await bounded(flushReports(), 5);
+  } catch {
+    /* undelivered reports re-run; delivering them was best-effort */
+  }
+  // NOT optional, for the reason the commanded stop states: detached preview
+  // tunnels survive this process by design, and a public hostname pointed into a
+  // worktree on a box that no longer serves the project is the worst thing this
+  // path can leave behind.
+  teardown();
+  log.note('worktrees are kept — the branches here are the only copy of this box\'s work.');
+  exit(0);
+}
+
 // One roster agent's loop: persistent worktree, one intent per turn, reset to
 // base between tasks (fresh conversation), resume in place while on a blocker.
 
@@ -464,6 +736,11 @@ export async function runFleetDaemon() {
   // across them. See instance.mjs for why that lock is not enough on its own.
   // Same repo -> this run replaces whatever was serving it. Different repo ->
   // refused, and nothing is signalled. See instance.mjs's header for the rule.
+  //
+  // `--takeover` ARBITRATES PROCESSES ON THIS BOX and nothing more — which
+  // daemon serves this repo. It says nothing about which BOX serves the
+  // project: that is holdership, the server decides it because only the server
+  // can see both boxes, and a person moves it from the app.
   const instance = acquireInstanceLock(FLEET_TOKEN, repoRoot, {
     takeover:
       process.argv.includes('--takeover') || process.argv.includes('--takeover-downgrade'),
@@ -831,13 +1108,35 @@ export async function runFleetDaemon() {
     retireWorkSessions,
     reportWorktrees,
     shutdownWork,
+    settleAgentTurns,
     workBusy,
+    admit,
+    liveTurns,
   } = createWorkManager({
     repoRoot,
     baseDir,
     getBaseRef,
     getMcpUrl: () => mcpUrl,
     getLeaseTtl: () => leaseTtlSeconds,
+    /**
+     * The cartographer is a CLI turn too, and it is the one this manager cannot
+     * see — it lives in this closure, not in `workChildren`. Without it the
+     * machine's ceiling would be a ceiling with a hole in it: a wiki sweep over
+     * a large repo is one of the heaviest turns the daemon runs.
+     *
+     * Read lazily (it is only ever called from the reconcile loop, long after
+     * `wikiChild` is declared below), for the same reason `onRepoChanged` is a
+     * callback: work.mjs is imported BY this file and cannot import back.
+     *
+     * `wikiBusy` COUNTS, not just the live child, and that is the wiki lane's
+     * version of the reservation `admission.mjs` describes: the drain sets the
+     * flag the moment it is admitted and the CLI does not exist until several
+     * awaits later, so counting the child alone left a hole exactly wide enough
+     * for the other lanes to spend the slot this one had already taken. The
+     * drain runs at most one CLI at a time, so the flag and the child are the
+     * same one turn and this can never double-count.
+     */
+    extraLiveTurns: () => (wikiBusy || wikiChild ? 1 : 0),
     /**
      * "THE REPO JUST CHANGED — look again."
      *
@@ -1039,6 +1338,7 @@ export async function runFleetDaemon() {
   const wikiQueue = [];
   let wikiBusy = false;
   let wikiChild = null; // the wiki turn's Claude process — tracked so teardown can kill it
+  let wikiHoldSaidAt = 0; // last time the drain said it was waiting on the box
   let lastSweepAt = null; // dedup: run each Regenerate request once
   // …UNLESS IT FAILED. A sweep that ends without WIKI_DONE never finalizes, so
   // the server's `regen_requested_at` stays set and the roster keeps offering
@@ -1218,6 +1518,28 @@ export async function runFleetDaemon() {
 
   async function drainWiki() {
     if (wikiBusy || wikiQueue.length === 0) return;
+    /**
+     * NOT WHILE THE BOX IS UNDER PRESSURE. A sweep is a CLI reading a whole
+     * repository, which is the heaviest turn the daemon runs and the one
+     * nobody is waiting on — so it is the first thing to yield.
+     *
+     * The queue is left INTACT: nothing is claimed, nothing is consumed, and
+     * the reconcile loop calls this again on its next poll. The one thing that
+     * must not happen is setting `wikiBusy` and returning, which would strand
+     * the drain until a restart.
+     */
+    const hold = admit('churn');
+    if (hold) {
+      // Said at most every five minutes: this runs on every poll, and a queued
+      // sweep can sit through a long stretch of pressure — a line every twenty
+      // seconds would be the console restating one unchanged fact all evening.
+      if (Date.now() - wikiHoldSaidAt > 5 * 60_000) {
+        wikiHoldSaidAt = Date.now();
+        note(`${c.cyan('wiki')} ${c.dim(`— holding off: ${hold.reason}`)}`);
+      }
+      return;
+    }
+    wikiHoldSaidAt = 0;
     wikiBusy = true;
     // Held for the WHOLE drain: this loop resets the worktree between tasks, and
     // a consult reading it mid-reset sees files vanish under it.
@@ -1507,6 +1829,11 @@ export async function runFleetDaemon() {
   let rosterSig = null; // last roster membership, to log changes only
   let idleBeatAt = 0; // throttle the "still alive" idle heartbeat
   let cappedWarned = false; // say once, not every reconcile, why extra lanes idle
+  // WHOSE MACHINE THIS IS, as of the last poll the server arbitrated. 'absent'
+  // is the reserved meaning — an older server, or a poll with no envpub — and
+  // everything downstream of it must read exactly as it did before 0.84.0.
+  const holderWatch = createHolderWatch({ say: (m) => note(m) });
+  let holderState = 'absent';
 
   // ── Push channel: a server wake short-circuits the reconcile sleep so a job is
   // picked up in ~a round trip instead of on the next poll. The socket only
@@ -1556,7 +1883,15 @@ export async function runFleetDaemon() {
   for (;;) {
     let roster;
     try {
-      roster = await fetchRoster(buildHave(), livePreviewIds(), heldSessionIds());
+      // The churn admission, asked ONCE here and relayed as `pr`: the same
+      // question every unattended lane asks a few lines later, so what the
+      // board is told and what the machine then does cannot disagree.
+      roster = await fetchRoster(
+        buildHave(),
+        livePreviewIds(),
+        heldSessionIds(),
+        admit('churn')
+      );
     } catch (e) {
       if (e.auth) {
         fail(`${e.message} — credential revoked or invalid. Shutting down.`);
@@ -1634,6 +1969,38 @@ export async function runFleetDaemon() {
       // minutes later comes up clean instead of stopping itself forever.
       process.exit(0);
     }
+    /**
+     * THE MACHINE MOVED OUT FROM UNDER US — checked BEFORE the version signal
+     * for the reason the stop above is: `handleVersionSignal` can re-exec this
+     * process, and a box that has just been displaced coming back up wearing a
+     * newer version is the one outcome nobody asked for.
+     *
+     * The key's PRESENCE is the command, exactly as it is for a stop: the server
+     * sends it only when it names THIS box's `envpub` and only inside its own
+     * window, so there is no TTL to re-evaluate here and no way for a relaunch
+     * to obey a displacement aimed at somebody else.
+     */
+    if (roster.displaced && typeof roster.displaced === 'object' && !Array.isArray(roster.displaced)) {
+      await standDownDisplaced({
+        by: roster.displaced.by,
+        settleAgentTurns,
+        flushReports: flushWorkReports,
+        teardown,
+        exit: (code) => process.exit(code),
+        log: { warn, note },
+      });
+      return;
+    }
+    /**
+     * WHOSE MACHINE THIS IS. Absent = a server that does not arbitrate, and then
+     * this is a no-op and the daemon behaves exactly as 0.83.0 did.
+     *
+     * A standby keeps polling and keeps everything the restricted roster still
+     * drives — its `activeWorkSessions` is credential-scoped and correct, so the
+     * sweep below is unchanged behaviour and must not be skipped, or a standby
+     * would start deleting worktrees it cannot see the tabs for.
+     */
+    holderState = holderWatch.observe(roster.holder);
     // Keep the daemon current. Safe = no worker mid-task (true at startup, since
     // no workers are spawned yet). If it self-updates it re-execs into the new
     // version and this process becomes a proxy — stop the loop.
@@ -1776,7 +2143,11 @@ export async function runFleetDaemon() {
       // first poll. It used to point at the Cockpit, a surface deleted
       // 2026-08-04 that now redirects to the Board. Say what is actually true
       // instead: the machine is up, and work starts in a tab.
-      info('Machine online. Open a tab in Flowviant → Workbench to start working.');
+      // …unless another box holds the machine. A standby IS connected and IS
+      // polling, and saying "machine online" over a daemon the server hands
+      // nothing would contradict the standby line printed a moment earlier.
+      if (holderState !== 'standby')
+        info('Machine online. Open a tab in Flowviant → Workbench to start working.');
     }
     // Heartbeat so a quiet daemon visibly stays alive. Gated on REAL work —
     // `rosterIds` is built from `roster.agents`, which the server sends
@@ -1785,7 +2156,11 @@ export async function runFleetDaemon() {
     // there session turns, ships or unsettled reports in flight?
     if (!workBusy() && Date.now() - idleBeatAt > 60_000) {
       idleBeatAt = Date.now();
-      info('machine online — nothing running right now.');
+      info(
+        holderState === 'standby'
+          ? 'standing by — another machine holds this project.'
+          : 'machine online — nothing running right now.'
+      );
     }
 
     // Living-wiki work (runs under its own minted wiki token — no agent
@@ -1831,14 +2206,23 @@ export async function runFleetDaemon() {
     // laptops; that is only true if the machine is visible. Per-task RSS is the
     // load-bearing part — "the box is full" is not actionable, "this task is
     // holding 9GB" is.
+    //
+    // …AND IT HAD NEVER BEEN POPULATED ONCE (fixed 2026-09-14). This read the
+    // dispatch-era `workers` map, which nothing has `.set()` since the lane was
+    // deleted on 2026-08-19 — so the list was permanently empty, the server
+    // stored an empty array every poll, and the column its own handler calls
+    // the load-bearing half of this report was blank on every machine that has
+    // ever run. The same shape as the env rotation two blocks up, which
+    // iterated the same dead map and reached no worktree at all.
+    //
+    // `liveTurns()` is the live registry: every CLI child this daemon is
+    // holding, with the session or agent id it serves. Bounded inside the
+    // snapshot, because each row costs a /proc tree walk.
     void reportMergeOutcome(
       MACHINE_URL,
       machineSnapshot({
         worktreeDir: baseDir,
-        tasks: [...workers].map(([, w]) => ({
-          intentId: w.state.intentId ?? null,
-          pid: w.state.child?.pid,
-        })),
+        tasks: liveTurns().map((t) => ({ intentId: t.id, pid: t.pid })),
       })
     );
 

package/bin/lib/instance.mjs

@@ -71,6 +71,13 @@
  * `--no-takeover` (or FLOWVIANT_NO_TAKEOVER=1) makes even the same-repo case
  * refuse, for anyone who wants the old ceremony.
  *
+ * EVERYTHING IN THIS FILE IS ABOUT PROCESSES ON ONE BOX, decided locally against
+ * a lock file. It says nothing about WHICH BOX serves the project — a project
+ * has one machine and the SERVER arbitrates that, because it is the only party
+ * that can see both boxes. A standby daemon here is a perfectly healthy holder
+ * of this repo's lock; the two questions never meet, and no flag in this file
+ * moves the project's machine.
+ *
  * IT FAILS OPEN. A home directory we cannot write to is not a reason to refuse
  * to start; it is a reason to say so and carry on unguarded.
  */