flowviant 0.54.0 → 0.54.1

package/bin/cli.mjs

@@ -19,6 +19,8 @@
  * `npx flowviant` can reuse a stale cache). A running daemon also self-updates
  * on its own — at startup and when idle — so it stays current without restarts
  * (FLOWVIANT_NO_UPDATE=1 makes it nag-only; `flowviant update` updates now).
+ * `flowviant stop` stops every daemon on this box — the answer to "is one even
+ * running?", which otherwise ends in a pid hunt through `ps`.
  *
  * The daemon: install ONCE with a machine credential, then work entirely from
  * Flowviant. It polls GET /api/v2/fleet/agents, and the roster hands it the
@@ -146,6 +148,30 @@ if (process.argv[2] === 'shot') {
   process.exit(0);
 }
 
+// `flowviant stop` — stop every flowviant daemon on this machine.
+//
+// THE FRICTION IT REMOVES is not knowing whether one is running. So you run
+// `flowviant`, get a refusal naming a pid in a directory you do not recognise,
+// and go hunting through `ps`. This asks no question and takes no argument: it
+// sweeps every credential's lock file, not just the one this checkout keys to,
+// because a stop command with a scope is one you have to be sure about before
+// you can use it — and being unsure is the whole reason you typed it.
+//
+// It identifies each holder before signalling it and says so when it cannot
+// (see stopAllDaemons); it needs NO credential and NO network — it reads lock
+// files under ~/.flowviant and signals pids — so it runs BEFORE the auth gate,
+// like `shot`. "I don't know what is running" is not a state in which we should
+// also be asking someone to log in.
+//
+// EXIT 0 when it stopped something AND when it found nothing: "no flowviant
+// daemon is running on this machine." is the answer the asker came for, not an
+// error. Non-zero only when something was alive and could not be stopped.
+if (process.argv[2] === 'stop') {
+  const { stopAllDaemons } = await import('./lib/instance.mjs');
+  const { failed } = stopAllDaemons({ log: (m) => console.log(m) });
+  process.exit(failed > 0 ? 1 : 0);
+}
+
 // `flowviant env <import|set|show>` — the CLI half of team env sync. Values
 // are sealed to the project pubkey ON THIS MACHINE (same write-only crypto as
 // the browser); `show` decrypts locally — it only works on an ENROLLED machine.

package/bin/lib/fleet.mjs

@@ -270,6 +270,48 @@ async function maybeReportLocalSessions({ repoRoot, excludeDirs }) {
   }
 }
 
+/**
+ * A STOP COMMANDED BY FLOWVIANT, read off the roster poll.
+ *
+ * The daemon is a PULL client — the /fleet/stream socket is a one-way wake
+ * nudge with no server→daemon request path — so "stop this machine" can never
+ * be a request the server makes of us. It rides the roster RESPONSE instead, on
+ * the same `daemon` object the version signal already travels on, which is why
+ * it needs no new endpoint and no version floor: an older daemon reads an
+ * unknown key as nothing and keeps running, and fail-open is the safe direction
+ * for a switch whose failure mode is "your machine went dark".
+ *
+ * The server decides whether a stop is LIVE — it stamps the credential and only
+ * sends the key inside a short honor window — and the daemon does NOT re-derive
+ * that. The key's PRESENCE is the command. Evaluating the same TTL on both
+ * sides would make clock skew the arbiter of whether a machine may run, and get
+ * it wrong in the direction that bricks the box: a relaunch that re-reads an
+ * old timestamp and stops itself again, forever.
+ *
+ * Pure and exported so the decision can be proved without a credential or a
+ * live server. `null` means keep running.
+ */
+export function shouldStop(rosterDaemon) {
+  const stop = rosterDaemon?.stop;
+  // An OBJECT, and not an array: `typeof [] === 'object'`, so the plain typeof
+  // guard let `stop: []` — an empty list, which is how this codebase spells "no
+  // jobs" on every other roster key — read as a live stop with no reason. A
+  // switch that kills a machine gets the narrow test.
+  if (!stop || typeof stop !== 'object' || Array.isArray(stop)) return null;
+  // Re-sanitized HERE even though the server wrote it: this string is operator
+  // prose typed into a SQL UPDATE and then printed straight to a terminal, so
+  // control bytes would let a stop reason repaint the console it is being read
+  // on, and an unbounded one would bury the line that matters. The WORDING is
+  // untouched — the operator's own sentence is the whole point of the field,
+  // and paraphrasing it would leave the person at the keyboard guessing.
+  const reason = String(stop.reason ?? '')
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 300);
+  return { stop: true, reason };
+}
+
 // 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.
 
@@ -327,7 +369,15 @@ export async function runFleetDaemon() {
       // restart, so it takes a word.
       note('run with --takeover to stop it and serve this repo instead.');
     }
-    note('or run this one with FLOWVIANT_ALLOW_MULTI=1 if you know what you are doing.');
+    // WITHHELD when we could not identify the holder. ALLOW_MULTI runs this
+    // daemon unguarded beside one we just admitted we cannot see, and in the
+    // same repo that is two `git fetch`, two worktree sweeps, and one
+    // `retireWorkSessions` deleting directories the other is serving. Offering
+    // it as the way out of "I don't know what that process is" would be handing
+    // someone the worst option at the moment they have the least information.
+    if (!instance.unidentified) {
+      note('or run this one with FLOWVIANT_ALLOW_MULTI=1 if you know what you are doing.');
+    }
     console.log('');
     process.exit(1);
   }
@@ -1240,6 +1290,36 @@ export async function runFleetDaemon() {
     if (roster.mcpUrl) mcpUrl = roster.mcpUrl;
     if (roster.project?.id) wikiProjectId = roster.project.id; // keys the vault dir
     if (roster.leaseTtlSeconds) leaseTtlSeconds = roster.leaseTtlSeconds;
+    // A COMMANDED STOP OUTRANKS AN UPDATE, and that ordering is the whole reason
+    // this sits ABOVE the version signal rather than inside it. Both read the
+    // same `roster.daemon` object, but `handleVersionSignal` can re-exec this
+    // process into a newer build — so checked second, a machine somebody just
+    // told to stop would come back up wearing a different version instead of
+    // going away.
+    const stopSignal = shouldStop(roster.daemon);
+    if (stopSignal) {
+      warn(
+        stopSignal.reason
+          ? `stopped by Flowviant — ${stopSignal.reason}`
+          : 'stopped by Flowviant — no reason given.'
+      );
+      note('shutting down — stopping workers. Worktrees are kept: in-flight work resumes next run.');
+      // teardown() is NOT optional on this path. Detached preview tunnels
+      // survive this process BY DESIGN, so exiting without it strands a public
+      // hostname pointed into a worktree until somebody reboots the box — which
+      // is precisely the state a remote stop is usually being used to end. It
+      // also kills the session CLIs and the wiki Claude, which would otherwise
+      // keep editing worktrees and burning quota for a machine nobody is
+      // watching any more.
+      teardown();
+      // EXIT 0, and this is load-bearing: the stop was ASKED FOR, so it is not
+      // a failure. Under `Restart=on-failure` a nonzero code has systemd
+      // relaunch the daemon immediately, fighting the very command that stopped
+      // it; exit 0 reads as "the job is done" and leaves it down. The server's
+      // honor window is what makes the other half work — a deliberate relaunch
+      // minutes later comes up clean instead of stopping itself forever.
+      process.exit(0);
+    }
     // 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.

package/bin/lib/instance.mjs

@@ -140,6 +140,9 @@ const record = (repoRoot) =>
     // The script we were started from, and what we are. A takeover matches the
     // live command line against `entry` before signalling anything — a lock
     // records a PID, and a crashed daemon's PID can be reused by anything.
+    // Locks written before this field existed (0.51.2 through 0.53.0) are
+    // matched on the holder's process START TIME instead; stillTheHolder says
+    // why that is the weaker of the two claims and still strong enough.
     entry: process.argv[1] || '',
     version: VERSION,
   });
@@ -175,16 +178,26 @@ function neighbourLockPath(holder, fallback) {
   return NEIGHBOUR_PATHS.get(holder) ?? fallback;
 }
 
-export function daemonInSameRepo(repoRoot, ownPath) {
-  const dir = join(homedir(), '.flowviant');
-  let files;
+/** Every daemon lock file on this machine, absolute, sorted for a stable read.
+ *  ONE scan, because two callers walk this directory for opposite reasons —
+ *  daemonInSameRepo looking for a neighbour to refuse or replace, stopAllDaemons
+ *  sweeping the lot — and the FILENAME PATTERN is the thing that must not drift
+ *  between them: it is what separates our locks from anything else living in
+ *  ~/.flowviant. An unreadable (or absent) directory is not an error here, it is
+ *  an empty machine. */
+function lockFiles() {
   try {
-    files = readdirSync(dir).filter((f) => /^daemon-[0-9a-f]{12}\.lock$/.test(f));
+    return readdirSync(join(homedir(), '.flowviant'))
+      .filter((f) => /^daemon-[0-9a-f]{12}\.lock$/.test(f))
+      .sort()
+      .map((f) => join(homedir(), '.flowviant', f));
   } catch {
-    return null;
+    return [];
   }
-  for (const f of files) {
-    const path = join(dir, f);
+}
+
+export function daemonInSameRepo(repoRoot, ownPath) {
+  for (const path of lockFiles()) {
     if (path === ownPath) continue; // our own credential — the lock above owns that question
     const holder = readHolder(path);
     if (!holder || !alive(holder.pid)) continue;
@@ -197,6 +210,175 @@ export function daemonInSameRepo(repoRoot, ownPath) {
   return null;
 }
 
+/** How far a holder's actual start may sit BEFORE the `startedAt` line it wrote
+ *  and still be the same process. Measured on this exact path: node boot to the
+ *  first line of JS is 20ms, and the whole way through importing this module,
+ *  `git rev-parse --show-toplevel` and base-ref detection to record() is 29-32ms.
+ *  The worst realistic run is a start that had to take over a NEIGHBOUR's lock
+ *  first (a 20s grace, then 600ms) and then its own (another 20s), which lands
+ *  around 41s. 120s is ~3x that worst path and ~4000x the typical one, and it is
+ *  still short enough that pid reuse cannot reach into it: reuse means cycling
+ *  the entire pid space (4194304 by default), which no machine does inside two
+ *  minutes. */
+const TAKEOVER_START_WINDOW_MS = 120_000;
+
+/** ...and how far the OTHER way, which is a unit problem rather than a real
+ *  possibility. `starttime` is quantised to clock ticks and `ps -o etime=` to
+ *  whole seconds, so a process that genuinely started a moment before its own
+ *  lock line can compute a hair after it. 5s covers that granularity and
+ *  nothing else. The window is deliberately asymmetric and BACKWARD-looking: it
+ *  brackets the daemon's own startup, not "recently", so a freshly forked
+ *  impostor that inherited a recycled pid lands on this side and is refused. */
+const TAKEOVER_START_SLACK_MS = 5_000;
+
+/** USER_HZ — the unit `/proc` publishes `starttime` in. NOT the kernel's internal
+ *  CONFIG_HZ (250/300/1000): the kernel converts before writing, and USER_HZ is a
+ *  fixed ABI constant, 100 on every architecture that matters. So the fallback
+ *  below is the ABI and not a guess, and `getconf` is only belt and braces.
+ *
+ *  A wrong value here fails SAFE in BOTH directions, which is why it is allowed
+ *  to be a guess at all: too low and the process computes as far older than its
+ *  lock (refused by the 120s window), too high and it computes as newer than a
+ *  lock it supposedly wrote (refused by the 5s slack). */
+function userHz() {
+  try {
+    const n = Number.parseInt(
+      execFileSync('getconf', ['CLK_TCK'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 3000,
+      }).trim(),
+      10,
+    );
+    if (Number.isInteger(n) && n > 0 && n <= 1_000_000) return n;
+  } catch {
+    /* no getconf — the constant below IS the ABI */
+  }
+  return 100;
+}
+
+/**
+ * Wall-clock milliseconds at which `pid` started, or null.
+ *
+ * NULL IS NOT "UNKNOWN, PROBABLY FINE". Every caller must read it as refuse —
+ * this feeds a check that gates a SIGTERM and then a SIGKILL, and there is no
+ * such thing as a harmless guess about which process to kill.
+ */
+function processStartedAt(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    if (platform() === 'linux') {
+      // FIELD 22 OF /proc/<pid>/stat, and the parse is the whole trap. Field 2
+      // is `comm`, which the kernel wraps in parens and which may contain BOTH
+      // spaces and parens — it is the first 15 bytes of the executable's name,
+      // and a name is not a token. A naive split on whitespace taking $22 then
+      // lands on `nice` for any such process, and `nice` is a small integer, so
+      // the answer is not a parse error but a plausible-looking "started at
+      // boot" that sails past any isFinite guard. Measured: a binary named
+      // `ev (i l) x` read 28308s too old that way.
+      //
+      // Every field after `comm` is a number or a single-character state, so no
+      // ')' can appear later: the LAST ')' in the line is always the kernel's
+      // own closing paren, even when comm itself ends in one.
+      const raw = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const close = raw.lastIndexOf(')');
+      if (close < 0) return null;
+      const fields = raw.slice(close + 1).trim().split(/\s+/); // fields[0] IS field 3
+      const ticks = Number.parseInt(fields[19], 10); // field 22 => 22 - 3
+      if (!Number.isFinite(ticks) || ticks < 0) return null;
+      // `/proc/uptime` rather than `/proc/stat`'s btime, and not for precision
+      // alone (measured 6ms out against 162ms). Date.now() and uptime are read
+      // at the same instant, so a realtime clock stepped since boot cancels
+      // out of the subtraction; btime bakes in a boot-realtime estimate that a
+      // later NTP step silently invalidates. `starttime` is in ticks either
+      // way — uptime gives seconds-since-boot, so the division by USER_HZ is
+      // not optional.
+      const up = Number.parseFloat(readFileSync('/proc/uptime', 'utf8').split(/\s+/)[0]);
+      if (!Number.isFinite(up) || up < 0) return null;
+      const ageMs = (up - ticks / userHz()) * 1000;
+      if (!Number.isFinite(ageMs) || ageMs < 0) return null;
+      return Date.now() - ageMs;
+    }
+    if (platform() === 'darwin') {
+      // `etime`, not `lstart`. A DURATION has no locale, no timezone, and no
+      // ambiguous repeated hour at the DST fall-back — where `lstart` is an
+      // hour out and would refuse a genuine holder twice a year. It also dodges
+      // Date.parse being LENIENT rather than strict: a localized `lstart` can
+      // parse to a wrong-but-finite instant instead of failing honestly.
+      // (`etimes`, the seconds-only form, is procps-only and not a BSD keyword.)
+      // Both derive from the same kinfo_proc.p_starttime, so 1s resolution
+      // against a 120s window costs nothing. LC_ALL is pinned anyway, since a
+      // localized number format would be a wrong answer rather than no answer.
+      const out = execFileSync('ps', ['-o', 'etime=', '-p', String(pid)], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 3000,
+        env: { ...process.env, LC_ALL: 'C', LC_TIME: 'C' },
+      });
+      const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(out.trim()); // [[dd-]hh:]mm:ss
+      if (!m) return null;
+      const age =
+        Number(m[1] || 0) * 86400 + Number(m[2] || 0) * 3600 + Number(m[3]) * 60 + Number(m[4]);
+      if (!Number.isFinite(age) || age < 0) return null;
+      return Date.now() - age * 1000;
+    }
+    return null; // win32, and anything else — never signalled rather than guessed at
+  } catch {
+    return null; // no /proc (hidepid=2, a pid namespace, a stripped container), no ps
+  }
+}
+
+/**
+ * THE FALLBACK, for a lock that carries no `entry`.
+ *
+ * `entry` arrived after the lock did. Every daemon from 0.51.2 through 0.53.0
+ * wrote `{pid, repoRoot, startedAt}` and nothing else, and stillTheHolder used
+ * to refuse those outright. Refusing was right in spirit and useless in fact:
+ * it made takeover impossible on precisely the locks takeover exists for, since
+ * the daemon you are replacing is by definition the OLD one. `--takeover` did
+ * nothing, and re-running `flowviant` in the repo you were working in printed a
+ * refusal and sent you hunting for a pid — the exact ceremony the same-repo rule
+ * was written to abolish. (Those locks carry no `version` either, so a legacy
+ * takeover also skips takeOverFrom's downgrade guard, which short-circuits on
+ * `holder.version &&`. Separate hole, not this function's to close.)
+ *
+ * WHY START TIME PROVES IDENTITY, which is the only question worth asking here,
+ * because what this gates is a SIGTERM and then a SIGKILL. A pid alone proves
+ * nothing: pids are recycled, and a crashed daemon's number goes to whatever
+ * forks next. The PAIR (pid, start time) is the standard POSIX process
+ * identity — pidfd, systemd and procps all key on it — because the kernel
+ * stamps a start time at fork and it is immutable for the life of the process,
+ * unforgeable by anything that started later. And `startedAt` was written BY
+ * the process being identified, measured 29-32ms after its own fork, so the
+ * lock is that process's own witness to when it began.
+ *
+ * It is a WEAKER statement than `entry`, which says what the process IS rather
+ * than when it started, and that is why `entry` stays the primary path. What
+ * makes this one acceptable anyway is that a false positive needs two things at
+ * once that are close to mutually exclusive: the pid space must have wrapped
+ * back to this exact number, AND the new occupant must have started inside a
+ * 2-minute window that ENDS at the lock write. Wrapping takes millions of
+ * forks; the window ends before the impostor could have been born.
+ *
+ * EVERY ERROR MODE HERE PUSHES TOWARD REFUSAL, never toward signalling — an
+ * unreadable /proc, a pid namespace, a kernel before 5.5 whose starttime drifts
+ * across suspend, a realtime clock stepped in either direction, a locale that
+ * mangles `ps`, Windows. All of them return false, and false costs a person a
+ * manual kill. The other direction costs somebody else's process.
+ */
+function startedAroundLockWrite(holder) {
+  try {
+    const written = Date.parse(holder?.startedAt ?? '');
+    if (!Number.isFinite(written)) return null; // no witness — nothing was measured
+    const started = processStartedAt(holder.pid);
+    if (started === null) return null; // could not measure — see the tri-state note
+    const delta = written - started; // >0: the process predates its own lock line, as it must
+    return delta >= -TAKEOVER_START_SLACK_MS && delta <= TAKEOVER_START_WINDOW_MS;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * IS THIS PID STILL THE DAEMON THAT TOOK THE LOCK?
  *
@@ -207,11 +389,30 @@ export function daemonInSameRepo(repoRoot, ownPath) {
  * runner living under a `…-flowviant/` directory. That last one is not
  * hypothetical — a looser version of this check SIGTERMed one.
  *
- * A lock with no `entry` predates this and is never signalled.
+ * A lock with no `entry` is no longer refused outright. Those locks are real
+ * and current — every daemon 0.51.2 through 0.53.0 wrote one — so refusing
+ * them meant takeover never worked on the upgrade it was built for. They fall
+ * back to the holder's PROCESS START TIME, which is the same claim made a
+ * weaker way; startedAroundLockWrite above argues why that is a proof rather
+ * than a guess, and why every way it can go wrong ends in a refusal.
+ *
+ * TRI-STATE, and the third value is the point: `true` identified, `false`
+ * measured-and-it-is-someone-else, `null` COULD NOT MEASURE. Both `false` and
+ * `null` refuse — that never changes — but they are not the same sentence, and
+ * collapsing them made the refusal assert a fact nobody had established: on a
+ * `hidepid=2` host (ordinary Debian/Ubuntu hardening) the daemon told the user
+ * their live holder "is no longer the daemon that took this lock", i.e. that
+ * the lock was stale. Acting on that — deleting the lock, or taking the
+ * ALLOW_MULTI escape printed underneath it — lands them in two daemons in one
+ * working tree, which this module's header says no server lease can arbitrate.
+ * Ignorance is not a state this product renders as fact.
  */
 function stillTheHolder(holder) {
   const want = typeof holder?.entry === 'string' ? holder.entry : null;
-  if (!want) return false;
+  // An `entry` of '' is a field with nothing in it — record() writes
+  // `process.argv[1] || ''` — and matching on '' would match every process
+  // alive, so it takes the same road as a missing one.
+  if (!want) return startedAroundLockWrite(holder);
   try {
     if (platform() === 'linux') {
       return readFileSync(`/proc/${holder.pid}/cmdline`, 'utf8').replace(/\0/g, ' ').includes(want);
@@ -222,7 +423,11 @@ function stillTheHolder(holder) {
       timeout: 3000,
     }).includes(want);
   } catch {
-    return false; // gone, or unreadable — not something we signal
+    // NOT `false`. takeOverFrom already returned early if the pid were gone, so
+    // reaching here means the process is alive and we could not READ it —
+    // hidepid=2, a pid namespace, a stripped image with no `ps`. Saying `false`
+    // here is what made the refusal claim the pid belonged to somebody else.
+    return null;
   }
 }
 
@@ -242,7 +447,16 @@ const sleep = (ms) => {
 const TAKEOVER_GRACE_MS = 20_000;
 
 /**
- * Ask the holder to stand down, then take its place.
+ * THE STAND-DOWN, and it is deliberately ONE copy of this.
+ *
+ * Two callers perform this identical ritual for different reasons — a takeover
+ * (a second run in the same repo replacing the daemon serving it) and
+ * `flowviant stop` (a person who does not know what is running clearing the
+ * box). What they share is a SIGTERM followed by a SIGKILL, and two hand-copies
+ * of a SIGKILL are two places to get the grace period, the zombie trap or the
+ * mid-update handover subtly wrong. The IDENTITY gate is NOT in here: this
+ * function signals whatever it is handed, so every caller must have proved what
+ * the pid is before it calls (see stillTheHolder, and read its tri-state note).
  *
  * SIGTERM FIRST, and not out of politeness: the daemon's handler runs its
  * teardown — it kills the CLI children it spawned and stops its preview
@@ -259,18 +473,24 @@ const TAKEOVER_GRACE_MS = 20_000;
  * because the holder SELF-UPDATED: update.mjs re-execs and the successor adopts
  * this same lock through the ppid branch. Treating that as free steals a live
  * daemon's lock and leaves it running unguarded — measured doing exactly that.
+ *
+ * Returns null when the holder is stopped and its lock file is cleared, or
+ * `{ failed }` with a sentence the caller can print as-is.
  */
-function takeOverFrom(holder, path, log, { allowDowngrade = false } = {}) {
-  if (!holder?.pid || !alive(holder.pid)) return null; // already gone
-  if (!stillTheHolder(holder)) {
-    return { failed: `pid ${holder.pid} is no longer the daemon that took this lock — refusing to signal it` };
-  }
-  if (!allowDowngrade && holder.version && cmpVersion(VERSION, holder.version) < 0) {
-    return {
-      failed: `the running daemon is ${holder.version} and this one is ${VERSION} — refusing to replace a newer daemon with an older one (--takeover-downgrade if you mean it)`,
-    };
-  }
-
+function standDown(holder, path, log) {
+  // NEVER SIGNAL OURSELVES, and this is not a theoretical guard — it was
+  // reproduced end to end. A 0.54.0+ lock records `entry` = the daemon's
+  // argv[1], i.e. `…/bin/cli.mjs`. Run `flowviant stop` and OUR cmdline is
+  // `node …/bin/cli.mjs stop`, which CONTAINS that string. So if a stale lock's
+  // pid has been recycled to us — ordinary on a host with pid_max 32768, and
+  // stale locks are deliberately left on disk — stillTheHolder answers `true`
+  // ABOUT THE SWEEPER and this function SIGTERMs the process running it. The
+  // command then dies mid-line, every later lock goes unexamined, and the real
+  // daemons it was asked to stop keep running. It is the signal-the-wrong-
+  // process bug arriving through a POSITIVE identification, which is why the
+  // identity check cannot catch it and the guard belongs here, at the one place
+  // that signals, rather than in each caller.
+  if (holder.pid === process.pid) return { failed: 'refusing to signal this very process' };
   log?.(`asking daemon pid ${holder.pid} to stand down…`);
   try {
     process.kill(holder.pid, 'SIGTERM');
@@ -316,6 +536,44 @@ function takeOverFrom(holder, path, log, { allowDowngrade = false } = {}) {
   } catch {
     return { failed: 'could not clear the lock file' };
   }
+  return null;
+}
+
+/**
+ * Ask the holder to stand down, then take its place.
+ *
+ * WHAT THIS FUNCTION IS, now that the choreography lives in standDown above: the
+ * IDENTITY GATE. Nothing below signals anything until the pid has been proved to
+ * be the process that wrote this lock — a lock records a PID, pids are recycled,
+ * and a crashed daemon's number goes to whatever forks next. `stillTheHolder` is
+ * tri-state and both of its refusing values are reported, separately, because
+ * "it is someone else" and "we could not look" are different sentences and
+ * collapsing them once had the daemon telling people a live holder was stale.
+ */
+function takeOverFrom(holder, path, log, { allowDowngrade = false } = {}) {
+  if (!holder?.pid || !alive(holder.pid)) return null; // already gone
+  const identified = stillTheHolder(holder);
+  if (identified === null) {
+    // We know nothing about this pid, and said so. The remedy is a human
+    // stopping it, NOT running a second daemon alongside it.
+    return {
+      failed:
+        `cannot confirm what pid ${holder.pid} is on this host — no readable /proc or ps — ` +
+        `so it will not be signalled. Stop that process yourself and start this one again.`,
+      unidentified: true,
+    };
+  }
+  if (identified === false) {
+    return { failed: `pid ${holder.pid} is no longer the daemon that took this lock — refusing to signal it` };
+  }
+  if (!allowDowngrade && holder.version && cmpVersion(VERSION, holder.version) < 0) {
+    return {
+      failed: `the running daemon is ${holder.version} and this one is ${VERSION} — refusing to replace a newer daemon with an older one (--takeover-downgrade if you mean it)`,
+    };
+  }
+
+  const bad = standDown(holder, path, log);
+  if (bad) return bad;
   log?.(`daemon pid ${holder.pid} stopped — taking over.`);
   return null;
 }
@@ -351,7 +609,8 @@ export function acquireInstanceLock(fleetToken, repoRoot, opts = {}) {
     if (noTakeover) return { ok: false, holder: neighbour, sameRepo: true };
     log?.(`another project's daemon is serving this repo (pid ${neighbour.pid}).`);
     const bad = takeOverFrom(neighbour, neighbourLockPath(neighbour, path), log);
-    if (bad) return { ok: false, holder: neighbour, sameRepo: true, takeoverFailed: bad.failed };
+    if (bad)
+      return { ok: false, holder: neighbour, sameRepo: true, takeoverFailed: bad.failed, unidentified: bad.unidentified };
   }
 
   // Two passes at most: one to clear a stale holder, one to take the lock. A
@@ -394,7 +653,8 @@ export function acquireInstanceLock(fleetToken, repoRoot, opts = {}) {
       const wanted = force || (here && !noTakeover);
       if (wanted) {
         const bad = takeOverFrom(holder, path, log, { allowDowngrade });
-        if (bad) return { ok: false, holder, takeoverFailed: bad.failed, sameRepo: here };
+        if (bad)
+          return { ok: false, holder, takeoverFailed: bad.failed, sameRepo: here, unidentified: bad.unidentified };
         continue; // the file is gone — the next pass takes it
       }
       return { ok: false, holder, sameRepo: here };
@@ -429,3 +689,138 @@ function makeRelease(path) {
   process.on('exit', release);
   return release;
 }
+
+/**
+ * STOP EVERY FLOWVIANT DAEMON ON THIS MACHINE — `flowviant stop`.
+ *
+ * WHY IT IS "EVERY" AND NOT "THIS REPO'S". The friction this exists to remove is
+ * not knowing what is running. Somebody who could NAME the daemon they meant
+ * would not need this command — they would already have the pid. What actually
+ * happens is that they run `flowviant`, hit a refusal naming a pid and a
+ * directory they do not recognise, and go hunting through `ps`. So this takes no
+ * argument, asks no question, and sweeps every credential's lock file rather
+ * than the one this checkout happens to key to: a stop command with a scope is a
+ * stop command you have to be sure about before you can use it.
+ *
+ * IT IDENTIFIES BEFORE IT SIGNALS, exactly as takeover does and for the same
+ * reason — a lock records a PID, pids are recycled, and there is no such thing
+ * as a harmless guess about which process to kill. The tri-state from
+ * stillTheHolder is reported as three DIFFERENT sentences and never collapsed:
+ *
+ *   true   -> stopped, through the same standDown the takeover path uses.
+ *   false  -> measured, and that pid is somebody else now. Nothing is signalled
+ *             and it is NOT a failure: the daemon that wrote the lock is gone,
+ *             which is the answer the asker wanted.
+ *   null   -> COULD NOT CONFIRM — either the lock carries no witness to match
+ *             against, or the host hides the process (hidepid=2, a pid
+ *             namespace, an image with no `ps`); the line below names BOTH,
+ *             since we did not measure which. Said out loud WITH THE PID,
+ *             because we have just declined to touch a live process and the
+ *             remedy is a human running `kill`.
+ *             That one counts as a failure — something is alive and we did not
+ *             stop it — which is the ONLY thing that makes this command exit
+ *             non-zero.
+ *
+ * A STALE LOCK IS LEFT ON DISK. Unlinking one looks tidy and races a daemon that
+ * is starting RIGHT NOW: acquire clears a dead holder's file and then re-creates
+ * it with `wx`, so a sweep landing between those two steps deletes a LIVE
+ * daemon's lock and leaves it running unguarded — the one condition this whole
+ * module exists to prevent. Clearing stale files is acquire's job, it already
+ * does it, and it does it without the race.
+ *
+ * FINDING NOTHING IS THE FEATURE, not an error: "no flowviant daemon is running
+ * on this machine." is the sentence the person who did not know came for, and it
+ * exits 0. Reported through `log` line by line as the sweep goes — a person
+ * watching a SIGTERM wants to see which pid it went to while it is happening,
+ * not in a summary afterwards.
+ *
+ * Returns `{ stopped, unconfirmed, failed }`; the caller turns `failed` into the
+ * exit code.
+ */
+export function stopAllDaemons({ log = (m) => console.log(m) } = {}) {
+  let stopped = 0;
+  let unconfirmed = 0;
+  let failed = 0;
+  let running = 0; // locks naming a process we believe is, or might be, a daemon
+
+  for (const path of lockFiles()) {
+    const holder = readHolder(path);
+    if (!holder) continue; // absent, truncated, half-written — no claim to answer
+    const where = holder.repoRoot ? ` in ${holder.repoRoot}` : '';
+    const what = holder.version ? ` ${holder.version}` : '';
+
+    if (!alive(holder.pid)) {
+      log(`pid ${holder.pid}${where} is already gone — nothing to stop.`);
+      continue;
+    }
+    // Us. standDown refuses this too, but reaching it would print a stand-down
+    // line and then a failure for the one pid we are certain is not a daemon.
+    if (holder.pid === process.pid) continue;
+
+    const identified = stillTheHolder(holder);
+    if (identified === false) {
+      // A live pid, but measured NOT to be the process that wrote this lock. The
+      // daemon is gone; the number was handed to something else. Not counted as
+      // running, and deliberately not counted as a failure either.
+      log(`pid ${holder.pid} is no longer the daemon that took this lock — nothing signalled.`);
+      continue;
+    }
+    running++;
+    if (identified === null) {
+      unconfirmed++;
+      failed++;
+      // NAMES BOTH CAUSES, because null has two and we did not measure which:
+      // the lock may carry no witness to match against (neither `entry` nor
+      // `startedAt` — a hand-edited or half-written file), or this host may hide
+      // the process from us (hidepid=2, a pid namespace, an image with no `ps`).
+      // "no readable /proc" alone is what takeover says, and said HERE it would
+      // assert a diagnosis nobody established — over a live process we are about
+      // to tell someone to kill.
+      // `kill` is not a command on Windows, where platform() is 'win32' and
+      // processStartedAt has no implementation at all — so EVERY lock lands in
+      // this branch and the whole command is a no-op that exits 1. Say that
+      // once, in the platform's own vocabulary, rather than handing someone a
+      // remedy their shell does not have.
+      const byHand =
+        platform() === 'win32'
+          ? `taskkill /PID ${holder.pid} /F`
+          : `kill ${holder.pid}`;
+      log(
+        `could not confirm that pid ${holder.pid} is still a flowviant daemon — its lock carries ` +
+          `nothing to match it against, or this host hides the process from us` +
+          `${platform() === 'win32' ? ' (identifying a process is not implemented on Windows)' : ''}` +
+          ` — so it was NOT signalled. Stop it by hand: ${byHand}`
+      );
+      continue;
+    }
+
+    const bad = standDown(holder, path, log);
+    if (bad) {
+      failed++;
+      log(`could not stop daemon pid ${holder.pid}${where}: ${bad.failed}`);
+      continue;
+    }
+    stopped++;
+    log(`stopped daemon${what} pid ${holder.pid}${where}.`);
+  }
+
+  // WHAT WE ACTUALLY MEASURED IS LOCKS, so that is what this says. The old
+  // sentence — "no flowviant daemon is running on this machine" — was asserted
+  // from lock files alone, and there are several ways to run a daemon that
+  // holds no readable lock: FLOWVIANT_ALLOW_MULTI=1 returns before the
+  // filesystem is touched (and fleet.mjs PRINTS that flag as the way out of an
+  // "already running" refusal, so a stuck user is steered straight onto it), an
+  // unwritable ~/.flowviant runs `unguarded`, and every daemon before 0.51.2
+  // predates the lock entirely. Telling somebody "nothing is running" while
+  // something is, is this product's cardinal sin: it turns ignorance into a
+  // state. So the claim is scoped to what was looked at, and the ways past it
+  // are named rather than left for them to discover.
+  if (!running) {
+    log('no flowviant daemon holds a lock on this machine.');
+    log(
+      '(a daemon started with FLOWVIANT_ALLOW_MULTI=1, or one older than 0.51.2, holds no lock — ' +
+        'this cannot see those. `pgrep -af flowviant` will.)'
+    );
+  }
+  return { stopped, unconfirmed, failed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.54.0",
+  "version": "0.54.1",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {