flowviant 0.102.2 → 0.104.0

package/bin/lib/instance.mjs

@@ -24,7 +24,7 @@
  * AFTER the work token is minted and the attachments are fetched — a window
  * containing a network round trip — so both daemons clear the check and both
  * spawn a CLI into one held conversation. It was built for a RESTARTED daemon
- * (its own comment says so, work.mjs), where the holder is already live when
+ * (its own comment says so, turnLock.mjs), where the holder is already live when
  * the successor looks; it was never a concurrency primitive.
  *
  * What a duplicate run cost before the session lease, all of it invisible in
@@ -89,7 +89,7 @@ import {
   openSync,
   readdirSync,
   readFileSync,
-  realpathSync,
+  renameSync,
   rmSync,
   writeFileSync,
   writeSync,
@@ -98,6 +98,8 @@ import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { VERSION, PROCESS_STARTED_AT } from './config.mjs';
+import { compareVersions } from './versionOrder.mjs';
+import { samePath } from './repoPath.mjs';
 
 /** Deliberately a HASH: a credential must never become a filename. */
 export function instanceLockPath(fleetToken) {
@@ -105,20 +107,6 @@ export function instanceLockPath(fleetToken) {
   return join(homedir(), '.flowviant', `daemon-${key}.lock`);
 }
 
-/** Numeric dotted compare, -1/0/1. Unparsable compares EQUAL, so a version we
- *  cannot read never silently authorises a downgrade. */
-function cmpVersion(a, b) {
-  const x = String(a).split('.').map((n) => Number.parseInt(n, 10));
-  const y = String(b).split('.').map((n) => Number.parseInt(n, 10));
-  for (let i = 0; i < Math.max(x.length, y.length); i++) {
-    const p = x[i] ?? 0;
-    const q = y[i] ?? 0;
-    if (Number.isNaN(p) || Number.isNaN(q)) return 0;
-    if (p !== q) return p > q ? 1 : -1;
-  }
-  return 0;
-}
-
 /** Signal 0 — a liveness probe, not a kill. EPERM means alive and not ours. */
 function alive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -139,6 +127,19 @@ function readHolder(path) {
   }
 }
 
+/**
+ * WHAT THE DAEMON HOLDING THIS CREDENTIAL'S LOCK IS FINISHING — the `target →
+ * env` words its draining mark carries (`markLockDraining`), or null. Read-only,
+ * for `status --json` (desktopContract.mjs), so the tray can say the box is
+ * finishing a deploy rather than idle. Null covers no lock, no mark, and an
+ * older daemon that never writes one; the caller asks only of a daemon it has
+ * already measured running.
+ */
+export function drainingFor(fleetToken) {
+  const what = readHolder(instanceLockPath(fleetToken))?.draining?.what;
+  return typeof what === 'string' && what ? what : null;
+}
+
 /** Read-only desktop measurement. No lock is unknown because an unguarded or
  * older daemon may still run; a stale lock with a dead pid measures empty. */
 export function daemonRunningFor(fleetToken) {
@@ -258,20 +259,6 @@ function isOurReexecParent(pid) {
   return false;
 }
 
-/** Same directory, whatever it is spelled as — symlinks and trailing slashes
- *  included. A repo compared by string would let `/repo` and `/repo/` past. */
-function samePath(a, b) {
-  if (!a || !b) return false;
-  const norm = (v) => {
-    try {
-      return realpathSync(v);
-    } catch {
-      return String(v).replace(/\/+$/, '');
-    }
-  };
-  return norm(a) === norm(b);
-}
-
 /**
  * A LIVE daemon in this same checkout, under a DIFFERENT credential.
  *
@@ -636,10 +623,21 @@ const TAKEOVER_GRACE_MS = 20_000;
  * 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.
  *
+ * A DRAINING HOLDER IS NEVER SIGNALLED (ruling 2026-09-26, "a stand-down lets
+ * a deploy finish and report"). It is already standing down and leaves by
+ * itself once its deploy's outcome is posted, and a signal can only cost that
+ * outcome. So the mark is read BEFORE the SIGTERM, and again on every look
+ * after it (the holder writes it the moment our SIGTERM finds a deploy in
+ * flight). What happens then is the caller's: `flowviant stop` is told so and
+ * returns (`draining`), a takeover waits for the lock to clear
+ * (`waitOutDrain`) — one line said once, no deadline, and Ctrl+C on the
+ * waiting process abandons only the wait (no handler is installed yet, so the
+ * default action ends the process; the draining daemon is untouched).
+ *
  * 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 standDown(holder, path, log) {
+function standDown(holder, path, log, { waitOutDrain = false } = {}) {
   // 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
@@ -653,19 +651,23 @@ function standDown(holder, path, log) {
   // 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');
-  } catch {
-    return { failed: `could not signal pid ${holder.pid}` };
-  }
-
   const standing = () => {
     const now = readHolder(path);
     if (!now || !alive(now.pid)) return null;
     return now;
   };
+  const before = standing();
+  if (!(before?.pid === holder.pid && before.draining)) {
+    log?.(`asking daemon pid ${holder.pid} to stand down…`);
+    try {
+      process.kill(holder.pid, 'SIGTERM');
+    } catch {
+      return { failed: `could not signal pid ${holder.pid}` };
+    }
+  }
+
   const deadline = Date.now() + TAKEOVER_GRACE_MS;
+  let saidWaiting = false;
   for (;;) {
     const now = standing();
     if (!now) break;
@@ -674,6 +676,28 @@ function standDown(holder, path, log) {
         failed: `the daemon handed over to pid ${now.pid}${now.version ? ` (${now.version})` : ''} while we waited — it is mid-update, so try again in a moment`,
       };
     }
+    /**
+     * IT IS FINISHING A DEPLOY — never forced (see above). The lock's mark
+     * (`markLockDraining`) says it has stopped taking work and leaves by
+     * itself once the outcome is posted; a SIGKILL here would lose exactly
+     * that outcome, so the server would hand the same irreversible job out
+     * again.
+     */
+    if (now.draining) {
+      const what = typeof now.draining.what === 'string' && now.draining.what ? ` (${now.draining.what})` : '';
+      if (!waitOutDrain) {
+        return {
+          draining: true,
+          failed: `pid ${holder.pid} is finishing a deploy${what} and stops by itself once its outcome is reported — it was not forced`,
+        };
+      }
+      if (!saidWaiting) {
+        saidWaiting = true;
+        log?.(`pid ${holder.pid} is finishing a deploy${what} — waiting…`);
+      }
+      sleep(1000);
+      continue;
+    }
     if (Date.now() >= deadline) {
       log?.(`pid ${holder.pid} did not stand down within ${TAKEOVER_GRACE_MS / 1000}s — forcing it.`);
       try {
@@ -734,13 +758,23 @@ function takeOverFrom(holder, path, log, { allowDowngrade = false } = {}) {
     // clears the corpse the same way it clears a dead pid's.
     return { stale: true };
   }
-  if (!allowDowngrade && holder.version && cmpVersion(VERSION, holder.version) < 0) {
+  /**
+   * THE DOWNGRADE GUARD refuses only a MEASURED downgrade. A holder version
+   * this daemon cannot read (versionOrder.mjs answers unknown) gates nothing,
+   * the same as before the one comparator existed: ignorance never refuses
+   * (CLAUDE.md, "What Flowviant is"). The old comment here claimed the
+   * opposite while its code let the takeover through; the code was the rule.
+   * A lock with NO version (an older daemon wrote it) is not compared either.
+   */
+  if (!allowDowngrade && holder.version && compareVersions(VERSION, holder.version) === -1) {
     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);
+  // A takeover WAITS OUT a drain (ruling 2026-09-26): the new start is what
+  // was asked for, and it arrives once the deploy has reported.
+  const bad = standDown(holder, path, log, { waitOutDrain: true });
   if (bad) return bad;
   log?.(`daemon pid ${holder.pid} stopped — taking over.`);
   return null;
@@ -875,6 +909,37 @@ export function acquireInstanceLock(fleetToken, repoRoot, opts = {}) {
   return { ok: false, holder: readHolder(path) };
 }
 
+/**
+ * MARK THIS PROCESS'S LOCK AS DRAINING — it is standing down and waits only
+ * for its in-flight deploys to report (ruling 2026-09-26; standDownExit.mjs).
+ * The lock stays held, so `status --json` still shows the daemon running and
+ * busy until the outcome lands; the mark is what tells a takeover (which then
+ * waits) or a `flowviant stop` (which then says so) never to signal it
+ * (see standDown).
+ *
+ * Written only while the lock still names this pid, and by rename, so a
+ * reader never sees half a record. Returns whether it was written; an
+ * unguarded daemon (no lock) has nothing to mark.
+ */
+export function markLockDraining(fleetToken, what) {
+  const path = instanceLockPath(fleetToken);
+  const holder = readHolder(path);
+  if (!holder || holder.pid !== process.pid) return false;
+  const tmp = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify({ ...holder, draining: { what: String(what ?? ''), since: new Date().toISOString() } }));
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      /* best-effort */
+    }
+    return false;
+  }
+}
+
 /** Release ONLY what we still own: a successor that adopted the lock (see the
  *  ppid branch) must not have it deleted out from under it when we exit. */
 function makeRelease(path) {
@@ -890,7 +955,8 @@ function makeRelease(path) {
       /* best-effort; a stale file is cleared by the next acquire */
     }
   };
-  // 'exit' covers the SIGINT/SIGTERM handlers too — both call process.exit().
+  // 'exit' covers the SIGINT/SIGTERM handlers too — both leave through
+  // standDownExit.mjs's `leave`, which ends in process.exit().
   process.on('exit', release);
   return release;
 }
@@ -906,7 +972,9 @@ function makeRelease(path) {
  * for the reason `standDown` gives about SIGKILLs.
  *
  * `tally` is mutated in place: `running` counts locks naming a process we
- * believe is, or might be, a daemon; the rest are what the caller reports.
+ * believe is, or might be, a daemon; `draining` counts the ones that were
+ * obeyed but are still alive, finishing a deploy (also counted `stopped`); the
+ * rest are what the caller reports.
  */
 function stopLock(path, log, tally) {
   const holder = readHolder(path);
@@ -960,6 +1028,16 @@ function stopLock(path, log, tally) {
   }
 
   const bad = standDown(holder, path, log);
+  if (bad?.draining) {
+    // Asked, heard, and leaving once its deploy reports: the stop was obeyed,
+    // so this is not a failure — and nothing is forced (see standDown). It is
+    // counted apart too, because it is still ALIVE: a disconnect must not go
+    // on to leave and forget under it (machineDisconnect.mjs).
+    tally.stopped++;
+    tally.draining++;
+    log(`daemon pid ${holder.pid}${where}: ${bad.failed}.`);
+    return;
+  }
   if (bad) {
     tally.failed++;
     log(`could not stop daemon pid ${holder.pid}${where}: ${bad.failed}`);
@@ -985,7 +1063,7 @@ function stopLock(path, log, tally) {
  * running" rather than failing. Returns the same tally `stopAllDaemons` does.
  */
 export function stopDaemonFor(fleetToken, { log = (m) => console.log(m) } = {}) {
-  const tally = { stopped: 0, unconfirmed: 0, failed: 0, running: 0 };
+  const tally = { stopped: 0, unconfirmed: 0, failed: 0, running: 0, draining: 0 };
   stopLock(instanceLockPath(fleetToken), log, tally);
   return tally;
 }
@@ -1038,7 +1116,7 @@ export function stopDaemonFor(fleetToken, { log = (m) => console.log(m) } = {})
  * exit code.
  */
 export function stopAllDaemons({ log = (m) => console.log(m) } = {}) {
-  const tally = { stopped: 0, unconfirmed: 0, failed: 0, running: 0 };
+  const tally = { stopped: 0, unconfirmed: 0, failed: 0, running: 0, draining: 0 };
   for (const path of lockFiles()) stopLock(path, log, tally);
   const { stopped, unconfirmed, failed, running } = tally;
 
@@ -1046,8 +1124,8 @@ export function stopAllDaemons({ log = (m) => console.log(m) } = {}) {
   // 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
+  // filesystem is touched (and fleetStartup.mjs PRINTS that flag as the way out
+  // of an "already running" refusal, so a stuck user is steered 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