@kybernesis/create 0.14.9 → 0.14.11

package/dist/docker-prune-cron.d.ts

@@ -0,0 +1,8 @@
+export declare function registeredDockerPruneAppDirs(installedContent: string | null): string[];
+export interface DockerPruneCronArtifact {
+    content: Buffer;
+    appDirs: string[];
+    manualCommand: string;
+}
+/** Render the package script with a managed, mergeable app-directory header. */
+export declare function dockerPruneCronArtifact(packageSource: string, currentAppDir: string, installedContent: string | null, targetPath: string): DockerPruneCronArtifact;

package/dist/docker-prune-cron.js

@@ -0,0 +1,38 @@
+const MANAGED_PREFIX = "# kyb-managed-eve-app-dirs: ";
+function shellSingleQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+export function registeredDockerPruneAppDirs(installedContent) {
+    if (!installedContent)
+        return [];
+    const line = installedContent.split("\n").find((candidate) => candidate.startsWith(MANAGED_PREFIX));
+    if (!line)
+        return [];
+    try {
+        const parsed = JSON.parse(line.slice(MANAGED_PREFIX.length));
+        return Array.isArray(parsed) && parsed.every((value) => typeof value === "string") ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Render the package script with a managed, mergeable app-directory header. */
+export function dockerPruneCronArtifact(packageSource, currentAppDir, installedContent, targetPath) {
+    const appDirs = [...new Set([...registeredDockerPruneAppDirs(installedContent), currentAppDir])];
+    const newline = packageSource.indexOf("\n");
+    const shebang = newline === -1 ? packageSource : packageSource.slice(0, newline);
+    const body = newline === -1 ? "" : packageSource.slice(newline + 1);
+    const joined = appDirs.join(":");
+    const content = Buffer.from(`${shebang}\n` +
+        `${MANAGED_PREFIX}${JSON.stringify(appDirs)}\n` +
+        `if [ -z "\${EVE_APP_DIRS:-}" ]; then EVE_APP_DIRS=${shellSingleQuote(joined)}; fi\n` +
+        `export EVE_APP_DIRS\n` +
+        body);
+    const encoded = content.toString("base64");
+    return {
+        content,
+        appDirs,
+        manualCommand: `printf %s ${shellSingleQuote(encoded)} | base64 -d | ` +
+            `sudo install -m 0755 /dev/stdin ${shellSingleQuote(targetPath)}`,
+    };
+}

package/dist/doctor.d.ts

@@ -22,6 +22,7 @@ export interface DockerTemplateInspection {
 export declare function dockerTemplateDoctorChecks(result: DockerTemplateInspection): Check[];
 export declare function modelReachDoctorCheck(authoredSource: string | null, compiledRouting: CompiledModelRouting): Check;
 export declare function agentInputLimitDoctorCheck(limit: AgentInputLimit): Check;
+export declare function diskUsageDoctorCheck(percent: number, dockerSummary: string | null): Check;
 /**
  * The inspector lives in @kybernesis/exe, next to the runtime that owns the
  * templates; create already resolves that package's scripts out of

package/dist/doctor.js

@@ -84,6 +84,15 @@ export function agentInputLimitDoctorCheck(limit) {
             };
     }
 }
+export function diskUsageDoctorCheck(percent, dockerSummary) {
+    if (percent < 85)
+        return { verdict: "pass", label: `disk ${percent}% used` };
+    const detail = `Docker: ${dockerSummary?.trim() || "docker system df unavailable"}. ` +
+        `Run: sudo /etc/cron.daily/kyb-docker-prune`;
+    if (percent < 95)
+        return { verdict: "warn", label: `disk ${percent}% used`, detail };
+    return { verdict: "fail", label: `disk ${percent}% used`, detail };
+}
 /**
  * The inspector lives in @kybernesis/exe, next to the runtime that owns the
  * templates; create already resolves that package's scripts out of
@@ -406,14 +415,17 @@ export async function doctor() {
             const job = capture("sh", ["-c", "test -x /etc/cron.daily/kyb-docker-prune && echo yes"])?.trim();
             const percent = Number(capture("sh", ["-c", "df / | awk 'NR==2{print $5}' | tr -d '%'"])?.trim() ?? 0);
             if (job !== "yes") {
-                add("warn", "no daily docker reclaim on this host", "sandbox templates, build cache, and generic stopped containers accumulate; durable sessions stay protected and terminal hooks remove closed sessions; `kyb upgrade` installs /etc/cron.daily/kyb-docker-prune");
-            }
-            else if (percent >= 80) {
-                add("fail", `disk ${percent}% full despite the reclaim job`, "run it now: sudo /etc/cron.daily/kyb-docker-prune, and check what else is on this host");
+                add("warn", "no daily docker reclaim on this host", "sandbox templates, build cache, and generic stopped containers accumulate; `kyb upgrade` installs /etc/cron.daily/kyb-docker-prune");
             }
             else {
-                add("pass", `daily docker reclaim installed (disk ${percent}% used)`);
+                add("pass", "daily docker reclaim installed");
             }
+            const dockerSummary = capture("sh", [
+                "-c",
+                "docker system df 2>/dev/null | head -3 | paste -sd ';' -",
+            ]);
+            const diskCheck = diskUsageDoctorCheck(percent, dockerSummary);
+            add(diskCheck.verdict, diskCheck.label, diskCheck.detail);
         }
         /**
          * Instructions that name a tool the agent does not have.

package/dist/peer-tree.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Who, exactly, is unhappy about the installed eve.
+ *
+ * @remarks
+ * `kyb upgrade` refuses to touch a project whose peer tree is broken (KYB-538),
+ * because changing a project on a bad tree is how a half-upgraded host happens.
+ * That gate read `npm ls eve`'s exit code and nothing else, so any package
+ * anywhere in the tree could veto the whole upgrade.
+ *
+ * On 2026-09-08 one did. `@github-tools/eve-extension` still declares
+ * `>=0.44.0 <0.48.0` while every Kybernesis package declares the 0.49 line the
+ * host actually runs. The upgrade aborted before `repairHostArtifacts`, so
+ * kyber did not receive the KYB-542 reclaim job it was being upgraded for, and
+ * the job had to be installed by hand.
+ *
+ * A third-party range that trails the framework is not a broken install. A
+ * Kybernesis package disagreeing with the framework it is pinned against is.
+ * So the verdict distinguishes them, and anything it cannot attribute is
+ * treated as fatal rather than waved through.
+ */
+export interface PeerTreeVerdict {
+    /** Nothing in the tree objects to the installed version. */
+    readonly ok: boolean;
+    /** Packages whose declared range excludes the installed version, deduplicated and sorted. */
+    readonly offenders: readonly string[];
+    /** An objection from a Kybernesis package, or one that could not be attributed. */
+    readonly fatal: boolean;
+}
+/**
+ * Read `npm ls <pkg> --json` and say whether the upgrade may proceed.
+ *
+ * Unparseable output is fatal: not knowing the shape of the tree is exactly the
+ * case the gate exists for.
+ */
+export declare function assessPeerTree(stdout: string): PeerTreeVerdict;
+/** What to print when a third-party range trails the framework but nothing else does. */
+export declare function staleRangeWarning(offenders: readonly string[], dependency: string): string;

package/dist/peer-tree.js

@@ -0,0 +1,62 @@
+const OWNED_SCOPE = "@kybernesis/";
+/** Every `from node_modules/<pkg>` in one npm `invalid` string. */
+function requiredBy(invalid) {
+    const found = [];
+    const pattern = /from node_modules\/((?:@[^/\s,]+\/)?[^/\s,]+)/g;
+    let match = pattern.exec(invalid);
+    while (match !== null) {
+        if (match[1])
+            found.push(match[1]);
+        match = pattern.exec(invalid);
+    }
+    return found;
+}
+function collect(node, offenders, unattributed) {
+    if (!node || typeof node !== "object")
+        return;
+    const record = node;
+    if (typeof record.invalid === "string" && record.invalid.length > 0) {
+        const owners = requiredBy(record.invalid);
+        // An objection nobody signed is not evidence that the tree is fine.
+        if (owners.length === 0)
+            unattributed.seen = true;
+        for (const owner of owners)
+            offenders.add(owner);
+    }
+    const dependencies = record.dependencies;
+    if (dependencies && typeof dependencies === "object") {
+        for (const child of Object.values(dependencies)) {
+            collect(child, offenders, unattributed);
+        }
+    }
+}
+/**
+ * Read `npm ls <pkg> --json` and say whether the upgrade may proceed.
+ *
+ * Unparseable output is fatal: not knowing the shape of the tree is exactly the
+ * case the gate exists for.
+ */
+export function assessPeerTree(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return { ok: false, offenders: [], fatal: true };
+    }
+    const offenders = new Set();
+    const unattributed = { seen: false };
+    collect(parsed, offenders, unattributed);
+    if (offenders.size === 0 && !unattributed.seen)
+        return { ok: true, offenders: [], fatal: false };
+    const sorted = [...offenders].sort();
+    const ours = sorted.some((name) => name.startsWith(OWNED_SCOPE));
+    return { ok: false, offenders: sorted, fatal: ours || unattributed.seen };
+}
+/** What to print when a third-party range trails the framework but nothing else does. */
+export function staleRangeWarning(offenders, dependency) {
+    const names = offenders.join(", ");
+    return (`${names} declare${offenders.length === 1 ? "s" : ""} a ${dependency} range that excludes the installed version. ` +
+        `Every Kybernesis package agrees with it, and the runtime already runs on it, so the upgrade continues. ` +
+        `Upgrade or replace ${offenders.length === 1 ? "that package" : "those packages"} when a compatible release exists.`);
+}

package/dist/upgrade.js

@@ -1,9 +1,12 @@
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 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 { findMatchingAgentServiceUnit, repairManageRestart } from "./systemd.js";
 import { repairTerminalSandboxCleanupHooks } from "./sandbox-cleanup.js";
 import { repairRemovedDefaultTools as repairRemovedDefaultTools_ } from "./removed-default-tools.js";
@@ -246,7 +249,7 @@ function repairHostArtifacts(cwd, deps) {
         return;
     const scripts = join(cwd, "node_modules/@kybernesis/exe/scripts");
     const pruneSource = join(scripts, "docker-prune.sh");
-    const pruneTarget = "/etc/cron.daily/kyb-docker-prune";
+    const pruneTarget = process.env.KYB_DOCKER_PRUNE_TARGET ?? "/etc/cron.daily/kyb-docker-prune";
     const hasDocker = capture("sh", ["-c", "command -v docker >/dev/null && echo yes"])?.trim() === "yes";
     // The host start script is package-owned too. It carried a 45-second
     // verdict clock that called a cold sandbox template build a failure, and no
@@ -276,18 +279,37 @@ function repairHostArtifacts(cwd, deps) {
         });
     }
     if (existsSync(pruneSource)) {
+        let installedPrune = null;
+        try {
+            if (existsSync(pruneTarget))
+                installedPrune = readFileSync(pruneTarget, "utf8");
+        }
+        catch {
+            // reconcileHostArtifact reports the unreadable target and refuses to replace it.
+        }
+        const pruneArtifact = dockerPruneCronArtifact(readFileSync(pruneSource, "utf8"), cwd, installedPrune, pruneTarget);
         const pruneResult = reconcileHostArtifact({
             targetPath: pruneTarget,
-            desiredContent: readFileSync(pruneSource),
+            desiredContent: pruneArtifact.content,
             expectedMode: 0o755,
             installIfMissing: hasDocker,
-            owner: "@kybernesis/exe/scripts/docker-prune.sh",
-            update: () => run("sudo", ["-n", "install", "-m", "0755", pruneSource, pruneTarget], {
-                cwd,
-                allowFail: true,
-                quiet: true,
-            }),
-            manualCommand: `sudo install -m 0755 ${shellQuote(pruneSource)} ${pruneTarget}`,
+            owner: "@kybernesis/exe/scripts/docker-prune.sh with registered app directories",
+            update: () => {
+                const stageDir = mkdtempSync(join(tmpdir(), "kyb-docker-prune-"));
+                const staged = join(stageDir, "docker-prune.sh");
+                try {
+                    writeFileSync(staged, pruneArtifact.content, { mode: 0o755 });
+                    return run("sudo", ["-n", "install", "-m", "0755", staged, pruneTarget], {
+                        cwd,
+                        allowFail: true,
+                        quiet: true,
+                    });
+                }
+                finally {
+                    rmSync(stageDir, { recursive: true, force: true });
+                }
+            },
+            manualCommand: pruneArtifact.manualCommand,
         });
         if ((pruneResult === "current" || pruneResult === "updated") && existsSync("/etc/cron.weekly/docker-prune")) {
             const removed = run("sudo", ["-n", "rm", "-f", "/etc/cron.weekly/docker-prune"], {
@@ -800,9 +822,22 @@ export async function upgrade(options = {}) {
     }
     const validation = commandResult("npm", ["ls", "eve"], cwd);
     if (validation.status !== 0) {
-        fail("npm ls eve failed. The installed peer tree is not valid.");
-        recoveryGuidance(targets, stoppedBridge ?? undefined);
-        return;
+        /**
+         * Judge WHO objects, not merely that something did.
+         *
+         * A third-party extension whose declared range trails the framework is not
+         * a broken install, and letting it veto the upgrade left kyber without the
+         * host artifacts it was being upgraded for (KYB-548). A Kybernesis package
+         * disagreeing with the framework it is pinned against still stops
+         * everything, and so does an objection we cannot attribute.
+         */
+        const verdict = assessPeerTree(commandResult("npm", ["ls", "eve", "--json"], cwd, false).stdout);
+        if (verdict.fatal || verdict.ok) {
+            fail("npm ls eve failed. The installed peer tree is not valid.");
+            recoveryGuidance(targets, stoppedBridge ?? undefined);
+            return;
+        }
+        console.log(yellow(`  ! ${staleRangeWarning(verdict.offenders, "eve")}`));
     }
     if (stoppedBridge && !startStoppedBridge(cwd, stoppedBridge))
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.14.9",
+  "version": "0.14.11",
   "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",