@kybernesis/create 0.15.5 → 0.15.7

package/dist/doctor.js

@@ -6,6 +6,8 @@ import { bold, capture, dim, green, parseEnv, red, yellow } from "./util.js";
 import { diagnoseManageRestart, findMatchingAgentServiceUnit } from "./systemd.js";
 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";
 const MARK = {
     pass: green("✓"),
@@ -116,6 +118,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);
@@ -125,6 +138,44 @@ export async function doctor() {
     if (selfVersion.kind === "stale") {
         add("warn", selfVersion.message, selfVersion.fix);
     }
+    /**
+     * Durable runs nothing will ever finish. They are replayed at every boot and
+     * eve removes none of them, so this only ever grows until something retires
+     * 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) {
+            add("pass", `durable run store is clean (${runs.total} runs, ${runs.held} held by a hook)`);
+        }
+        else {
+            add("warn", `${runs.abandoned} abandoned durable run(s) of ${runs.total} — replayed at every boot, never removed`, "scripts/safe-restart.sh, or reclaimAbandonedRuns() from @kybernesis/exe. Runs a hook still holds (routine sessions) are never retired.");
+        }
+    }
     // ── project shape ──────────────────────────────────────────────────────
     if (!existsSync(join(cwd, "agent"))) {
         console.error(red("Not an eve agent project (no agent/ directory). Run inside the agent repo."));

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/run-store.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How many durable runs this host is carrying that nothing will ever finish
+ * (KYB-546).
+ *
+ * eve leaves a run in `running` when a session, turn or task is abandoned, and
+ * ships nothing that retires them. They accumulate — four figures per host after
+ * a month — and every one is replayed at boot. After a durable-runtime change
+ * those replays diverge, are declared CORRUPTED_EVENT_LOG, and the conversation
+ * is dead for good.
+ *
+ * Reimplemented here rather than imported from @kybernesis/exe: doctor runs in
+ * repos that do not depend on exe, and a diagnostic that cannot run where the
+ * problem is is not a diagnostic. It only counts — retiring is exe's job.
+ */
+export interface RunStoreCount {
+    abandoned: number;
+    /** Held by a hook token: routine sessions live here and must never be retired. */
+    held: number;
+    total: number;
+}
+/** Count abandoned runs under an agent's `.eve/.workflow-data`, or null when there is no store. */
+export declare function countAbandonedRuns(cwd: string, olderThanDays?: number, now?: Date): RunStoreCount | null;

package/dist/run-store.js

@@ -0,0 +1,63 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+/** Count abandoned runs under an agent's `.eve/.workflow-data`, or null when there is no store. */
+export function countAbandonedRuns(cwd, olderThanDays = 2, now = new Date()) {
+    const data = join(cwd, ".eve", ".workflow-data");
+    const runsDir = join(data, "runs");
+    let names;
+    try {
+        names = readdirSync(runsDir).filter((n) => n.endsWith(".json"));
+    }
+    catch {
+        return null;
+    }
+    const held = new Set();
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!e.name.endsWith(".json"))
+                continue;
+            try {
+                const d = JSON.parse(readFileSync(full, "utf8"));
+                if (typeof d.runId === "string" && d.runId !== "")
+                    held.add(d.runId);
+            }
+            catch {
+                // Unreadable hook: count nothing rather than guess a run is unheld.
+            }
+        }
+    };
+    walk(join(data, "hooks"));
+    const threshold = olderThanDays * 86_400_000;
+    const out = { abandoned: 0, held: 0, total: names.length };
+    for (const name of names) {
+        let run;
+        try {
+            run = JSON.parse(readFileSync(join(runsDir, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (run.status !== "running")
+            continue;
+        if (typeof run.runId === "string" && held.has(run.runId)) {
+            out.held += 1;
+            continue;
+        }
+        const updated = typeof run.updatedAt === "string" ? Date.parse(run.updatedAt) : NaN;
+        if (Number.isFinite(updated) && now.getTime() - updated >= threshold)
+            out.abandoned += 1;
+    }
+    return out;
+}

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.5",
+  "version": "0.15.7",
   "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",