@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/scripts/daemon/sdk-version.mjs

@@ -1,22 +1,56 @@
 /**
  * scripts/daemon/sdk-version.mjs — which SDK version is the code THIS daemon
- * process is running?
+ * process is running, which one is INSTALLED beside it, and do they agree?
  *
- * The daemon runs from the agent dir's COPIED scripts/daemon, not from
- * node_modules. autoupdate installs the next version into node_modules first
- * and merges the files a minute or two later; a daemon that (re)starts inside
- * that window would report the node_modules version while executing the old
- * copies, and `maestro upgrade --verify` would go green on a lie. So the
- * order of trust is the version of the COPIED tree first:
+ * The daemon runs from the agent dir's COPIED scripts/daemon (and ../../lib),
+ * not from node_modules. `autoupdate.sh` installs the next version into
+ * node_modules FIRST and merges the files a minute or two later; a daemon that
+ * (re)starts inside that window executes the old copies while node_modules
+ * already holds the new package. So the RUNNING version is the version of the
+ * COPIED tree, and the order of trust for it is:
  *
  *   1. .maestro/shipped-manifest.json `sdkVersion` — written by the upgrade
  *      that copied the files (2.12+), i.e. the version of scripts/daemon/*;
  *   2. node_modules/@cohortapp/agent-sdk/package.json — a pre-2.12 manifest
- *      has no sdkVersion; the window above is then the only inaccuracy left;
+ *      has no sdkVersion, so this is a fallback and NOT an observation of the
+ *      copied tree (see `runningIsInferred` below);
  *   3. the package this file itself ships in (a framework checkout).
  *
+ * ── WHY IT NO LONGER RETURNS ONE STRING ──────────────────────────────────────
+ * It used to answer with `{version, source}` and nothing else, and every caller
+ * took `.version`. That is a true answer to "what am I executing" and a silent
+ * one about everything around it: this seat reported 2.18.0 to the org — read
+ * off a manifest written by the last `maestro upgrade` — while node_modules had
+ * already been moved to 2.18.1. Neither number was wrong. What was missing was
+ * that they DISAGREED, which is the only fact an operator watching a rollout
+ * actually wants, and the one the shape could not express.
+ *
+ * It matters twice over now: `autoupdate.sh`'s health gate compares the version
+ * a beat REPORTED against the version it INSTALLED, and refuses to call the hop
+ * healthy when they differ. A resolver that collapses the two teaches that gate
+ * to compare a number with itself.
+ *
+ * So the answer carries both, plus the verdict:
+ *
+ *   running           what the copied tree is, i.e. what is executing
+ *   runningSource     "manifest" | "node_modules" | "package" | "none"
+ *   runningIsInferred true when `running` did NOT come from the manifest — the
+ *                     copied tree's version was not observed, only assumed
+ *   installed         node_modules/@cohortapp/agent-sdk, independently read
+ *   agrees            true | false | null  (null = one of them is unknown, or
+ *                     `running` was inferred FROM `installed`, in which case
+ *                     equality is an artefact of the fallback and proves
+ *                     nothing — it must never read as agreement)
+ *   drift             a one-line human reason when `agrees === false`, else ""
+ *
+ * `version` and `source` stay on the object, unchanged, so existing callers
+ * keep working; `version` is `running`.
+ *
  * Read once at daemon start, never again (the dashboard must say what the
- * process IS, not what node_modules became meanwhile).
+ * process IS, not what node_modules became meanwhile). `installed` is read in
+ * the same breath for the same reason: a later read would compare this
+ * process's code against a node_modules that has moved on since, which is a
+ * different question and not this module's.
  *
  * @module scripts/daemon/sdk-version
  */
@@ -31,21 +65,69 @@ export const SDK_PACKAGE = "@cohortapp/agent-sdk";
 /**
  * Pure over an injected reader. `readJson(path)` returns the parsed file or
  * throws / returns null; every source is fail-open.
+ *
  * @param {{agentDir:string, ownPackagePath?:string, readJson?:(p:string)=>any}} o
- * @returns {{version:string, source:"manifest"|"node_modules"|"package"|"none"}}
+ * @returns {{version:string, source:"manifest"|"node_modules"|"package"|"none",
+ *            running:string, runningSource:"manifest"|"node_modules"|"package"|"none",
+ *            runningIsInferred:boolean, installed:string,
+ *            agrees:boolean|null, drift:string}}
  */
 export function resolveRunningSdkVersion(o = {}) {
   const readJson = o.readJson || ((p) => JSON.parse(readFileSync(p, "utf8")));
   const tryRead = (p) => { try { return readJson(p); } catch { return null; /* absent/corrupt → next source */ } };
-  const manifest = tryRead(join(o.agentDir, ".maestro", "shipped-manifest.json"));
-  if (manifest && typeof manifest.sdkVersion === "string" && manifest.sdkVersion) return { version: manifest.sdkVersion, source: "manifest" };
+
+  // INSTALLED — node_modules, read on its own terms and never skipped, because
+  // it is half of the comparison even when the manifest answers first.
   const dep = tryRead(join(o.agentDir, "node_modules", ...SDK_PACKAGE.split("/"), "package.json"));
-  if (dep && dep.name === SDK_PACKAGE && typeof dep.version === "string") return { version: dep.version, source: "node_modules" };
-  if (o.ownPackagePath) {
+  const installed = dep && dep.name === SDK_PACKAGE && typeof dep.version === "string" ? dep.version : "";
+
+  // RUNNING — the copied tree, in the documented order of trust.
+  let running = "";
+  let runningSource = "none";
+  const manifest = tryRead(join(o.agentDir, ".maestro", "shipped-manifest.json"));
+  if (manifest && typeof manifest.sdkVersion === "string" && manifest.sdkVersion) {
+    running = manifest.sdkVersion;
+    runningSource = "manifest";
+  } else if (installed) {
+    running = installed;
+    runningSource = "node_modules";
+  } else if (o.ownPackagePath) {
     const own = tryRead(o.ownPackagePath);
-    if (own && own.name === SDK_PACKAGE && typeof own.version === "string") return { version: own.version, source: "package" };
+    if (own && own.name === SDK_PACKAGE && typeof own.version === "string") {
+      running = own.version;
+      runningSource = "package";
+    }
   }
-  return { version: "", source: "none" };
+
+  return {
+    version: running,
+    source: runningSource,
+    running,
+    runningSource,
+    runningIsInferred: runningSource !== "manifest",
+    installed,
+    ...verdict(running, runningSource, installed),
+  };
+}
+
+/**
+ * The comparison, separated so it is testable on its own and so the three
+ * answers are exhaustive in one place.
+ *
+ * `null` is not a weaker `true`. A run whose `running` was INFERRED from
+ * `installed` has not compared anything — the two strings are equal because one
+ * was copied from the other — and reporting that as agreement is precisely the
+ * substitution ("it is running because it is installed") that let a seat stay
+ * six days behind an hourly "up to date".
+ */
+function verdict(running, runningSource, installed) {
+  if (!running || !installed) return { agrees: null, drift: "" };
+  if (runningSource !== "manifest") return { agrees: null, drift: "" };
+  if (running === installed) return { agrees: true, drift: "" };
+  return {
+    agrees: false,
+    drift: `running ${running} (copied tree) but ${installed} is installed — an upgrade installed the package and has not merged the files yet, or a merge failed`,
+  };
 }
 
 export default { resolveRunningSdkVersion, SDK_PACKAGE };