@kybernesis/create 0.15.6 → 0.15.8

package/dist/doctor.js

@@ -7,7 +7,9 @@ import { diagnoseManageRestart, findMatchingAgentServiceUnit } from "./systemd.j
 import { inspectEveAgent } from "./agent-limits.js";
 import { classifyModelReach } from "./model-reach.js";
 import { countAbandonedRuns } from "./run-store.js";
+import { describeStaleSidecar, newestPackageChange, staleSidecars } from "./stale-sidecar.js";
 import { checkSelfVersion } from "./self-version.js";
+import { envUrlProblems } from "./env-urls.js";
 const MARK = {
     pass: green("✓"),
     warn: yellow("!"),
@@ -117,6 +119,17 @@ async function head(url, headers) {
         return null;
     }
 }
+/** Running units that belong to a Kybernesis agent on this host. */
+function listAgentUnits() {
+    const out = capture("systemctl", ["list-units", "--type=service", "--state=running", "--no-legend", "--plain"]);
+    if (!out)
+        return [];
+    return out
+        .split("\n")
+        .map((line) => line.trim().split(/\s+/)[0] ?? "")
+        .filter((unit) => /-(agent|buzz-bridge)\.service$/.test(unit))
+        .map((unit) => unit.replace(/\.service$/, ""));
+}
 export async function doctor() {
     const cwd = process.cwd();
     const installedAgentService = findMatchingAgentServiceUnit(cwd);
@@ -132,6 +145,29 @@ export async function doctor() {
      * them. Reported rather than fixed: the remedy restarts the agent, which is
      * not something a diagnostic should do behind someone's back.
      */
+    /**
+     * Services still running the code they loaded at start.
+     *
+     * An agent host has more than one: deploy.sh restarts the agent, and the Buzz
+     * bridge is a separate unit it never touches. Both bridges on the reference
+     * fleet ran four days on a superseded package while the fix sat on disk, so
+     * two changes signed off as deployed were live nowhere. Nothing looked
+     * broken — the old code simply kept doing what it did.
+     */
+    const packageChange = newestPackageChange(cwd);
+    const started = new Map();
+    for (const unit of listAgentUnits()) {
+        const stamp = capture("systemctl", ["show", "-p", "ActiveEnterTimestamp", "--value", unit])?.trim();
+        const at = stamp ? new Date(stamp) : null;
+        if (at && !Number.isNaN(at.getTime()))
+            started.set(unit, at);
+    }
+    for (const stale of staleSidecars({ started, packageChange })) {
+        add("fail", `${stale.service} is running superseded code`, describeStaleSidecar(stale));
+    }
+    if (started.size > 0 && staleSidecars({ started, packageChange }).length === 0) {
+        add("pass", `every service is running the code currently installed (${started.size} checked)`);
+    }
     const runs = countAbandonedRuns(cwd);
     if (runs) {
         if (runs.abandoned === 0) {
@@ -180,6 +216,22 @@ export async function doctor() {
     };
     if (!existsSync(envPath))
         add("warn", ".env.local missing", "copy .env.example and fill it");
+    /**
+     * Config that is shaped wrong rather than missing.
+     *
+     * A URL-valued setting with no scheme does not fail at start; it fails inside
+     * whatever background drain uses it, once per turn, forever. The reference
+     * fleet logged 121 of these and lost every analytics event of a deployment
+     * while reporting healthy throughout. The value alone is enough to know, so
+     * this costs nothing and lands before a client's first turn.
+     */
+    const urlProblems = existsSync(envPath) ? envUrlProblems(readFileSync(envPath, "utf8")) : [];
+    for (const problem of urlProblems) {
+        add("fail", `${problem.name} cannot build a request (${problem.reason})`, problem.fix);
+    }
+    if (existsSync(envPath) && urlProblems.length === 0) {
+        add("pass", "every URL-valued setting is an absolute http(s) URL");
+    }
     const githubCheck = githubToolsDoctorCheck(existsSync(join(cwd, "agent/extensions/github.ts")), env);
     if (githubCheck)
         add(githubCheck.verdict, githubCheck.label, githubCheck.detail);

package/dist/env-urls.d.ts

@@ -0,0 +1,17 @@
+/** Does this name hold a whole URL? */
+export declare function expectsUrl(name: string): boolean;
+export type EnvUrlProblem = {
+    readonly name: string;
+    /** Why it cannot be used to build a request. Never includes the value. */
+    readonly reason: "no scheme" | "not a url" | "not http(s)";
+    readonly fix: string;
+};
+/**
+ * Check one value. Returns undefined when it is fine.
+ *
+ * The value never appears in the result: these files sit beside real secrets
+ * and a diagnostic that echoes them turns a config warning into a leak.
+ */
+export declare function checkEnvUrl(name: string, value: string): EnvUrlProblem | undefined;
+/** Every URL-shaped value in this env text that cannot build a request. */
+export declare function envUrlProblems(text: string): EnvUrlProblem[];

package/dist/env-urls.js

@@ -0,0 +1,79 @@
+import { parseEnv } from "./util.js";
+/**
+ * Environment values that are used to build a URL, and whether they can be.
+ *
+ * An SDK handed `POSTHOG_HOST=eu.i.posthog.com` does not complain at start. It
+ * fails once per turn, forever, inside a background drain: `Failed to parse URL
+ * from eu.i.posthog.com/batch/`. On the reference fleet that was 121 logged
+ * failures and every analytics event of the deployment silently discarded,
+ * while the agent itself looked perfectly healthy. Nothing surfaces it because
+ * nothing that matters to the turn depends on it.
+ *
+ * Hence checking the SHAPE of the value at rest, which costs nothing and finds
+ * it before a client's first turn.
+ */
+/**
+ * Names whose value is unambiguously a whole URL.
+ *
+ * `_HOST` is deliberately NOT here: plenty of them legitimately hold a bare
+ * hostname (`SMTP_HOST`, `PGHOST`, `REDIS_HOST`), and flagging those would make
+ * doctor cry wolf on a correct config.
+ */
+const URL_SUFFIXES = ["_URL", "_ENDPOINT", "_ISSUER"];
+/**
+ * `_HOST` names that specific SDKs use as a base URL, so they do need a scheme.
+ * An allowlist rather than a rule, because only the SDK knows which it is.
+ */
+const BASE_URL_HOSTS = new Set(["POSTHOG_HOST"]);
+/** Does this name hold a whole URL? */
+export function expectsUrl(name) {
+    if (BASE_URL_HOSTS.has(name))
+        return true;
+    return URL_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+/**
+ * Check one value. Returns undefined when it is fine.
+ *
+ * The value never appears in the result: these files sit beside real secrets
+ * and a diagnostic that echoes them turns a config warning into a leak.
+ */
+export function checkEnvUrl(name, value) {
+    const trimmed = value.trim().replace(/^["']|["']$/g, "");
+    if (trimmed === "")
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        // A bare host is by far the common case, and the remedy differs from junk.
+        const bare = /^[a-z0-9.-]+(:\d+)?(\/.*)?$/i.test(trimmed);
+        return {
+            name,
+            reason: bare ? "no scheme" : "not a url",
+            fix: bare
+                ? `${name} has no scheme, so anything built from it fails to parse. Prefix it with https://`
+                : `${name} is not a URL. Set it to an absolute https:// URL.`,
+        };
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        return {
+            name,
+            reason: "not http(s)",
+            fix: `${name} is a ${parsed.protocol.replace(":", "")} URL. Set it to an absolute https:// URL.`,
+        };
+    }
+    return undefined;
+}
+/** Every URL-shaped value in this env text that cannot build a request. */
+export function envUrlProblems(text) {
+    const problems = [];
+    for (const [name, value] of Object.entries(parseEnv(text))) {
+        if (!expectsUrl(name))
+            continue;
+        const problem = checkEnvUrl(name, value);
+        if (problem)
+            problems.push(problem);
+    }
+    return problems;
+}

package/dist/on-line-version.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Picking the right build of a per-eve-line package.
+ *
+ * `@kybernesis/*` packages ship one build per eve line, and the version numbers
+ * are NOT ordered by line: `@kybernesis/voice` 0.1.2 is the eve 0.49 build and
+ * was published AFTER 0.1.1, which is the 0.51 build. So `npm view <pkg>
+ * version` — npm's `latest` — is routinely the wrong package for a given host,
+ * and installing it puts an agent on a build compiled against an eve API it is
+ * not running.
+ *
+ * That failure is silent. The package installs, the agent builds, the service
+ * starts, and one code path breaks later at runtime. It is how
+ * `@kybernesis/notify` took an agent down and how two agents ran a 0.51 build of
+ * `@kybernesis/manage` on eve 0.49 for days without anyone noticing.
+ *
+ * So an upgrade must never ask for "latest". It must ask for the newest version
+ * whose declared eve peer range contains the eve this host actually runs.
+ */
+/** A published version and the eve range it declares. */
+export interface Candidate {
+    version: string;
+    /** `peerDependencies.eve`, or undefined when the package declares none. */
+    peer?: string;
+}
+/**
+ * Compare semver-ish versions numerically.
+ *
+ * Numerically, because these are picked by sorting and string order puts 0.8.9
+ * above 0.8.10 — which would hand a host the wrong build. A prerelease sorts
+ * BELOW its release (0.1.2-rc < 0.1.2), so a release candidate is never chosen
+ * over the release it precedes.
+ */
+export declare function versionCompare(a: string, b: string): number;
+/**
+ * Whether an eve version falls inside a declared peer range.
+ *
+ * Deliberately narrow: it understands the two forms these packages actually
+ * publish — `>=X <Y` and a caret — and returns false for anything it does not
+ * recognise. Guessing at a range it cannot parse is how a wrong build gets
+ * installed, and "I do not know" must not read as "yes".
+ */
+export declare function rangeContains(range: string | undefined, eve: string): boolean;
+/**
+ * The newest published build that supports this host's eve.
+ *
+ * Returns undefined when no published version declares support — which is a
+ * real answer and must be surfaced, not smoothed over by falling back to
+ * latest. `@kybernesis/voice` had NO eve 0.49 build for weeks while two agents
+ * on 0.49 ran its 0.51 one.
+ */
+export declare function newestOnLine(candidates: readonly Candidate[], eve: string): string | undefined;

package/dist/on-line-version.js

@@ -0,0 +1,87 @@
+/**
+ * Picking the right build of a per-eve-line package.
+ *
+ * `@kybernesis/*` packages ship one build per eve line, and the version numbers
+ * are NOT ordered by line: `@kybernesis/voice` 0.1.2 is the eve 0.49 build and
+ * was published AFTER 0.1.1, which is the 0.51 build. So `npm view <pkg>
+ * version` — npm's `latest` — is routinely the wrong package for a given host,
+ * and installing it puts an agent on a build compiled against an eve API it is
+ * not running.
+ *
+ * That failure is silent. The package installs, the agent builds, the service
+ * starts, and one code path breaks later at runtime. It is how
+ * `@kybernesis/notify` took an agent down and how two agents ran a 0.51 build of
+ * `@kybernesis/manage` on eve 0.49 for days without anyone noticing.
+ *
+ * So an upgrade must never ask for "latest". It must ask for the newest version
+ * whose declared eve peer range contains the eve this host actually runs.
+ */
+/**
+ * Compare semver-ish versions numerically.
+ *
+ * Numerically, because these are picked by sorting and string order puts 0.8.9
+ * above 0.8.10 — which would hand a host the wrong build. A prerelease sorts
+ * BELOW its release (0.1.2-rc < 0.1.2), so a release candidate is never chosen
+ * over the release it precedes.
+ */
+export function versionCompare(a, b) {
+    const split = (v) => {
+        const dash = v.indexOf("-");
+        const core = (dash === -1 ? v : v.slice(0, dash)).split(".").map((p) => Number(p) || 0);
+        return { core, pre: dash !== -1 };
+    };
+    const pa = split(a);
+    const pb = split(b);
+    for (let i = 0; i < Math.max(pa.core.length, pb.core.length); i += 1) {
+        const x = pa.core[i] ?? 0;
+        const y = pb.core[i] ?? 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    if (pa.pre === pb.pre)
+        return 0;
+    return pa.pre ? -1 : 1;
+}
+/**
+ * Whether an eve version falls inside a declared peer range.
+ *
+ * Deliberately narrow: it understands the two forms these packages actually
+ * publish — `>=X <Y` and a caret — and returns false for anything it does not
+ * recognise. Guessing at a range it cannot parse is how a wrong build gets
+ * installed, and "I do not know" must not read as "yes".
+ */
+export function rangeContains(range, eve) {
+    if (!range)
+        return false;
+    const bounded = /^>=\s*([0-9][^\s]*)\s*<\s*([0-9][^\s]*)$/.exec(range.trim());
+    if (bounded) {
+        return versionCompare(eve, bounded[1]) >= 0 && versionCompare(eve, bounded[2]) < 0;
+    }
+    const caret = /^\^([0-9][^\s]*)$/.exec(range.trim());
+    if (caret) {
+        const base = caret[1].split(".");
+        const major = Number(base[0] ?? 0);
+        const minor = Number(base[1] ?? 0);
+        // ^0.x is minor-locked, as npm treats it.
+        const upper = major === 0 ? `0.${minor + 1}.0` : `${major + 1}.0.0`;
+        return versionCompare(eve, caret[1]) >= 0 && versionCompare(eve, upper) < 0;
+    }
+    const atLeast = /^>=\s*([0-9][^\s]*)$/.exec(range.trim());
+    if (atLeast)
+        return versionCompare(eve, atLeast[1]) >= 0;
+    return false;
+}
+/**
+ * The newest published build that supports this host's eve.
+ *
+ * Returns undefined when no published version declares support — which is a
+ * real answer and must be surfaced, not smoothed over by falling back to
+ * latest. `@kybernesis/voice` had NO eve 0.49 build for weeks while two agents
+ * on 0.49 ran its 0.51 one.
+ */
+export function newestOnLine(candidates, eve) {
+    const supported = candidates.filter((c) => rangeContains(c.peer, eve));
+    if (supported.length === 0)
+        return undefined;
+    return supported.sort((a, b) => versionCompare(a.version, b.version)).at(-1)?.version;
+}

package/dist/stale-sidecar.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Services that are still running the code they loaded at start, after the
+ * package on disk has moved underneath them.
+ *
+ * Node reads a module once, at process start. Upgrading a package therefore
+ * changes nothing in a service that was already running — it keeps executing
+ * the old code from memory while the new version sits on disk, indefinitely.
+ *
+ * An agent host has more than one service. `deploy.sh` restarts the agent, and
+ * the Buzz bridge is a separate long-lived unit it does not touch. On the
+ * reference fleet both bridges ran for four days on `@kybernesis/buzz` 0.9.2
+ * while 0.9.9 was installed, so two fixes that had been signed off as deployed
+ * were live nowhere. Nothing was broken enough to notice; the bridges simply
+ * kept doing what the old code did.
+ *
+ * Checking the FILES is what hid it. The only honest question is whether the
+ * process started after the package changed.
+ */
+export interface StaleSidecar {
+    service: string;
+    /** When the unit last started. */
+    startedAt: Date;
+    /** The newest package change it has not picked up. */
+    packageChangedAt: Date;
+    /** The package whose change is newest, for the message. */
+    packageName: string;
+}
+/** The newest mtime across installed @kybernesis packages, and which one it was. */
+export declare function newestPackageChange(cwd: string): {
+    at: Date;
+    name: string;
+} | null;
+/**
+ * Compare each running unit's start time against the newest package change.
+ *
+ * `started` maps a unit name to when it started — supplied by the caller so
+ * this stays testable and does not shell out.
+ *
+ * A grace margin avoids flagging the restart that an install performs itself:
+ * a service restarted within a minute of the package landing has the new code.
+ */
+export declare function staleSidecars(input: {
+    started: ReadonlyMap<string, Date>;
+    packageChange: {
+        at: Date;
+        name: string;
+    } | null;
+    graceMs?: number;
+}): StaleSidecar[];
+/** One line per stale service, naming the fix. */
+export declare function describeStaleSidecar(stale: StaleSidecar): string;

package/dist/stale-sidecar.js

@@ -0,0 +1,56 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** The newest mtime across installed @kybernesis packages, and which one it was. */
+export function newestPackageChange(cwd) {
+    const scope = join(cwd, "node_modules", "@kybernesis");
+    let newest = null;
+    let entries;
+    try {
+        entries = readdirSync(scope);
+    }
+    catch {
+        return null;
+    }
+    for (const name of entries) {
+        try {
+            // The manifest is rewritten on every install of that package, so its
+            // mtime is when the package last changed on this host.
+            const at = statSync(join(scope, name, "package.json")).mtime;
+            if (!newest || at > newest.at)
+                newest = { at, name: `@kybernesis/${name}` };
+        }
+        catch {
+            // A half-removed package tells us nothing; skip it.
+        }
+    }
+    return newest;
+}
+/**
+ * Compare each running unit's start time against the newest package change.
+ *
+ * `started` maps a unit name to when it started — supplied by the caller so
+ * this stays testable and does not shell out.
+ *
+ * A grace margin avoids flagging the restart that an install performs itself:
+ * a service restarted within a minute of the package landing has the new code.
+ */
+export function staleSidecars(input) {
+    const change = input.packageChange;
+    if (!change)
+        return [];
+    const grace = input.graceMs ?? 60_000;
+    const out = [];
+    for (const [service, startedAt] of input.started) {
+        if (startedAt.getTime() >= change.at.getTime() - grace)
+            continue;
+        out.push({ service, startedAt, packageChangedAt: change.at, packageName: change.name });
+    }
+    return out;
+}
+/** One line per stale service, naming the fix. */
+export function describeStaleSidecar(stale) {
+    const started = stale.startedAt.toISOString().slice(0, 16).replace("T", " ");
+    const changed = stale.packageChangedAt.toISOString().slice(0, 16).replace("T", " ");
+    return (`${stale.service} started ${started} but ${stale.packageName} changed ${changed} — ` +
+        `it is still running the code it loaded at start. Restart it: sudo systemctl restart ${stale.service}`);
+}

package/dist/upgrade.js

@@ -7,6 +7,7 @@ import { upsertEnv } from "./envfile.js";
 import { reconcileHostArtifact } from "./host-artifacts.js";
 import { assessPeerTree, staleRangeWarning } from "./peer-tree.js";
 import { dockerPruneCronArtifact } from "./docker-prune-cron.js";
+import { newestOnLine } from "./on-line-version.js";
 import { findMatchingAgentServiceUnit, repairManageRestart } from "./systemd.js";
 import { repairTerminalSandboxCleanupHooks } from "./sandbox-cleanup.js";
 import { repairRemovedDefaultTools as repairRemovedDefaultTools_ } from "./removed-default-tools.js";
@@ -753,6 +754,44 @@ function installedPackageValue(cwd, name, expression) {
 function targetEvePeer(name, version) {
     return capture("npm", ["view", `${name}@${version}`, "peerDependencies.eve"])?.trim() || undefined;
 }
+/**
+ * The newest published build of a @kybernesis package that supports a given eve.
+ *
+ * NOT `npm view <name> version`. These packages ship one build per eve line and
+ * the versions are not ordered by line — voice 0.1.2 is the eve 0.49 build and
+ * was published after 0.1.1, the 0.51 build — so npm's `latest` is routinely the
+ * wrong package. Installing it puts the agent on a build compiled against an eve
+ * API it is not running, which fails at neither install nor build, only later
+ * and only on one path. That is how an 0.51 build of @kybernesis/manage ran on
+ * two eve 0.49 agents for days, and how @kybernesis/notify took one down.
+ *
+ * Returns undefined when nothing published supports this eve — a real answer,
+ * and one the caller must report rather than paper over.
+ */
+function newestBuildForEve(name, eve) {
+    const raw = capture("npm", ["view", name, "versions", "--json"]);
+    if (!raw)
+        return undefined;
+    let versions;
+    try {
+        const parsed = JSON.parse(raw);
+        versions = Array.isArray(parsed) ? parsed : [String(parsed)];
+    }
+    catch {
+        return undefined;
+    }
+    // Newest first, so the usual case stops after one lookup.
+    const ordered = [...versions].reverse();
+    const candidates = [];
+    for (const version of ordered) {
+        const peer = targetEvePeer(name, version);
+        candidates.push({ version, ...(peer ? { peer } : {}) });
+        const hit = newestOnLine(candidates, eve);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
 function dependencyEntries(pkg) {
     const entries = [];
     for (const section of ["dependencies", "devDependencies"]) {
@@ -879,9 +918,20 @@ export async function upgrade(options = {}) {
             continue;
         }
         installedVersions.set(name, installed);
-        const target = name === "eve" ? EVE_VERSION : capture("npm", ["view", name, "version"])?.trim();
+        // eve goes to the certified pin. Everything else goes to the newest build
+        // that supports the eve this host will be running — NOT npm's `latest`,
+        // which for a per-eve-line package is routinely a build for a different
+        // line and installs without complaint.
+        const target = name === "eve"
+            ? EVE_VERSION
+            : name.startsWith("@kybernesis/")
+                ? newestBuildForEve(name, EVE_VERSION)
+                : capture("npm", ["view", name, "version"])?.trim();
         if (!target) {
-            console.log(`  ${yellow("!")} ${name}: could not resolve target version`);
+            console.log(`  ${yellow("!")} ${name}: ` +
+                (name.startsWith("@kybernesis/")
+                    ? `no published build declares support for eve ${EVE_VERSION} — leaving it alone`
+                    : "could not resolve target version"));
             unresolved.add(name);
             continue;
         }
@@ -891,7 +941,7 @@ export async function upgrade(options = {}) {
             targetPeers.set(name, targetEvePeer(name, target));
         }
         if (installed === target) {
-            console.log(`  ${green("✓")} ${name}@${installed} ${dim(name === "eve" ? "(certified)" : "(latest)")}`);
+            console.log(`  ${green("✓")} ${name}@${installed} ${dim(name === "eve" ? "(certified)" : name.startsWith("@kybernesis/") ? `(newest for eve ${EVE_VERSION})` : "(latest)")}`);
         }
         else if (name === "eve" && versionLt(EVE_VERSION, installed)) {
             console.log(`  ${yellow("!")} eve@${installed} is AHEAD of the certified ${EVE_VERSION} ${dim("— unsupported territory")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.15.6",
+  "version": "0.15.8",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",
@@ -46,5 +46,6 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "peerDependencies": {}
 }