@kybernesis/create 0.14.8 → 0.14.10

package/README.md

@@ -85,7 +85,7 @@ Run inside an agent project. Checks, with pass/warn/fail per line:
 
 Exit code 1 on any failure — usable as a CI preflight.
 
-## `kyb upgrade [--skip-eval] [--yes]`
+## `kyb upgrade [--host[=<ssh-target>]] [--skip-eval] [--yes]`
 
 Compares installed `@kybernesis/*` versions against npm, installs what's
 behind, typechecks, then **runs the eval suite as the gate** — prints
@@ -100,6 +100,23 @@ runs fail closed unless `--yes` (or `-y`) is supplied. The warning is still prin
 are migrated to `kyb-eval`; custom scripts are left untouched with a manual fix.
 The wrapper counts corruption diagnostics beside the eval result and turns a
 nominally green eve exit into a failure when condemned durable state was seen.
+It also identifies failures from `judge.autoevals.*` assertions as judge
+reachability or HTTP failures rather than implying that the agent model failed.
+
+Immediately before a local gate, upgrade classifies the authored and compiled
+model route the same way as `kyb doctor`, then checks host-only dependencies. A
+Claude subscription agent must have its loopback proxy answering, and an
+exe-backed agent or judge must be able to reach `EXE_LLM_URL` (or the internal
+exe model catalog). If those routes are unavailable, the eval command is not
+run and upgrade exits with status 2, prints that the gate can only run on the
+host, and gives the exact ssh command. It does not print "Do NOT deploy" because
+no eval exercised the code.
+
+Use `kyb upgrade --host` to run the gate over ssh after the upgrade. The target
+uses the same defaults as `kyb deploy`: `EVE_SSH_HOST`, then
+`$EXE_VM_NAME.exe.xyz`; `--host=<ssh-target>` overrides them. The remote project
+path is `~/<package-name>`, and the remote eval output streams directly to the
+terminal. `--skip-eval` remains an explicit bypass and performs no preflight.
 
 On self-hosted agents, upgrade also reconciles package-owned host artifacts. It
 refreshes a stale `/etc/cron.daily/kyb-docker-prune` and an existing generated

package/dist/cli.js

@@ -11,6 +11,8 @@
  *   kyb deploy            put this repo on its host and restart it, with proof
  *   kyb upgrade           bump @kybernesis/* to latest, gated on the eval suite
  *     --skip-eval           skip the eval gate (not for production changes)
+ *     --host[=<target>]     run the eval gate over ssh on the agent host
+ *     --allow-stale         proceed even when this kyb is behind npm
  *     --yes, -y             confirm an eve upgrade noninteractively
  */
 import { existsSync, readFileSync } from "node:fs";
@@ -52,6 +54,12 @@ function flag(rest, key) {
     const hit = rest.find((a) => a.startsWith(`--${key}=`));
     return hit ? hit.slice(key.length + 3) : undefined;
 }
+function optionalValueFlag(rest, key) {
+    if (rest.includes(`--${key}`))
+        return true;
+    const value = flag(rest, key);
+    return value === undefined ? undefined : value;
+}
 function initOptions(rest) {
     const subs = flag(rest, 'subagents');
     return {
@@ -75,7 +83,7 @@ const COMMANDS = {
     credential: "Write the agent credential onto a host (--local to stay here).",
     register: "Register this agent with the control plane (--name, --url).",
     deploy: "Deploy this agent to its host (--no-env to leave the env file alone).",
-    upgrade: "Bring @kybernesis packages and eve to certified versions (--skip-eval, --yes).",
+    upgrade: "Bring @kybernesis packages and eve to certified versions (--host, --skip-eval, --allow-stale, --yes).",
     tui: "Talk to your agents in the terminal.",
     version: "Print the version of this tool.",
 };
@@ -101,6 +109,14 @@ function usage(command) {
 
   ${dim("Factory env: KYB_MODEL_REACH=claude-sub (the CLI flag takes precedence).")}
   ${dim("Claude subscription reach uses the loopback OAuth proxy; it does not read EXE_MODEL.")}\n`);
+        }
+        else if (command === "upgrade") {
+            console.log(`  ${bold("kyb upgrade")} [options]
+      --host[=<target>]     ${dim("run the eval gate over ssh; defaults like kyb deploy")}
+      --skip-eval           ${dim("skip the eval gate")}
+      --allow-stale         ${dim("continue even when this kyb is behind the published version")}
+      --yes, -y             ${dim("confirm an eve version change noninteractively")}
+`);
         }
         return;
     }
@@ -161,6 +177,8 @@ switch (command) {
         break;
     case "upgrade":
         await upgrade({
+            allowStale: rest.includes("--allow-stale"),
+            host: optionalValueFlag(rest, "host"),
             skipEval: rest.includes("--skip-eval"),
             yes: rest.includes("--yes") || rest.includes("-y"),
         });
@@ -228,7 +246,9 @@ ${dim("  npm i -g @kybernesis/create@latest")}
       --host=<target>   ${dim("ssh target; defaults to $EXE_VM_NAME.exe.xyz")}
       --no-env          ${dim("do not send .env.local (host manages its own secrets)")}
   ${bold("kyb upgrade")}         bump @kybernesis/* packages, gated on evals
+      --host[=<target>] ${dim("run the eval gate over ssh; defaults to EVE_SSH_HOST or EXE_VM_NAME")}
       --skip-eval       ${dim("skip the eval gate")}
+      --allow-stale     ${dim("continue even when this kyb is behind the published version")}
       --yes, -y          ${dim("confirm an eve version change noninteractively")}
 
 Registry: https://registry.kybernesis.ai · Docs: the FDE playbook

package/dist/deploy.d.ts

@@ -1,3 +1,6 @@
+/** The ssh target: an explicit flag, then EVE_SSH_HOST, then the exe VM name. */
+export declare function sshTarget(dir: string, explicit?: string): string | null;
+export declare function remoteProjectPath(dir: string): string;
 export declare function deploy(options: {
     host?: string;
     dir?: string;

package/dist/deploy.js

@@ -34,7 +34,7 @@ function hostOf(dir) {
     return deps["@kybernesis/exe"] ? "exe" : "vercel";
 }
 /** The ssh target: an explicit flag, then EVE_SSH_HOST, then the exe VM name. */
-function sshTarget(dir, explicit) {
+export function sshTarget(dir, explicit) {
     const e = env(dir);
     if (explicit)
         return explicit;
@@ -97,6 +97,10 @@ async function ensureModel(dir, target) {
     upsertEnv(dir, { EXE_MODEL: chosen });
     console.log(green(`  ✓ EXE_MODEL="${chosen}" written to .env.local\n`));
 }
+export function remoteProjectPath(dir) {
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return `~/${pkg.name ?? "agent"}`;
+}
 export async function deploy(options) {
     const dir = options.dir ?? process.cwd();
     if (!existsSync(join(dir, "agent"))) {
@@ -118,8 +122,7 @@ export async function deploy(options) {
         process.exitCode = 1;
         return;
     }
-    const name = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name ?? "agent";
-    const remote = `~/${name}`;
+    const remote = remoteProjectPath(dir);
     console.log(dim(`  host: ${target}   path: ${remote}\n`));
     await ensureModel(dir, target);
     const run = (cmd, args) => {

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

@@ -6,6 +6,8 @@ export interface Check {
     label: string;
     detail?: string;
 }
+/** Report the opt-in GitHub capability only when its mount is present. */
+export declare function githubToolsDoctorCheck(mountExists: boolean, env: Record<string, string | undefined>): Check | null;
 /** The shape @kybernesis/exe's inspector returns; declared here so create keeps zero runtime deps. */
 export interface DockerTemplateInspection {
     status: "skipped" | "present" | "failed";
@@ -20,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

@@ -6,11 +6,22 @@ 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 { checkSelfVersion } from "./self-version.js";
 const MARK = {
     pass: green("✓"),
     warn: yellow("!"),
     fail: red("✗"),
 };
+/** Report the opt-in GitHub capability only when its mount is present. */
+export function githubToolsDoctorCheck(mountExists, env) {
+    if (!mountExists || env.GITHUB_TOKEN)
+        return null;
+    return {
+        verdict: "warn",
+        label: "GitHub tools off (no GITHUB_TOKEN)",
+        detail: "set GITHUB_TOKEN in .env.local or the deployment environment, then rebuild and restart",
+    };
+}
 export function dockerTemplateDoctorChecks(result) {
     if (result.status === "skipped")
         return [];
@@ -40,6 +51,8 @@ export function modelReachDoctorCheck(authoredSource, compiledRouting) {
             return { verdict: "pass", label: "Model reach: claude-sub (Claude subscription)" };
         case "exe":
             return { verdict: "pass", label: "Model reach: exe (host LLM integration)" };
+        case "grok-sub":
+            return { verdict: "pass", label: "Model reach: grok-sub (direct xAI subscription credential)" };
         case "gateway":
             return { verdict: "pass", label: "Model reach: gateway" };
         case "direct-provider":
@@ -71,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
@@ -99,6 +121,10 @@ export async function doctor() {
     const installedAgentService = findMatchingAgentServiceUnit(cwd);
     const checks = [];
     const add = (verdict, label, detail) => checks.push({ verdict, label, detail });
+    const selfVersion = checkSelfVersion();
+    if (selfVersion.kind === "stale") {
+        add("warn", selfVersion.message, selfVersion.fix);
+    }
     // ── project shape ──────────────────────────────────────────────────────
     if (!existsSync(join(cwd, "agent"))) {
         console.error(red("Not an eve agent project (no agent/ directory). Run inside the agent repo."));
@@ -138,6 +164,9 @@ export async function doctor() {
     };
     if (!existsSync(envPath))
         add("warn", ".env.local missing", "copy .env.example and fill it");
+    const githubCheck = githubToolsDoctorCheck(existsSync(join(cwd, "agent/extensions/github.ts")), env);
+    if (githubCheck)
+        add(githubCheck.verdict, githubCheck.label, githubCheck.detail);
     // ── arcana keys: validate every key↔workspace pair read-only ───────────
     const arcanaPairs = [];
     if (env.ARCANA_API_KEY && env.ARCANA_COMPANY_WORKSPACE)
@@ -386,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/init.d.ts

@@ -1,4 +1,9 @@
 import { type ChannelKind, type HostKind } from "./templates.js";
+/**
+ * Replace Eve's freshly installed registry mount with the Kybernesis-managed
+ * token-aware form. A failed registry add must not create a capability file.
+ */
+export declare function finalizeGithubToolsRegistryMount(cwd: string, registryAddSucceeded: boolean): boolean;
 export interface InitOptions {
     engineer?: boolean;
     /**

package/dist/init.js

@@ -1,7 +1,7 @@
 import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { DEFAULT_ISSUER, EVE_VERSION, REGISTRY_URL, ask, bold, closePrompts, dim, green, run, slug, red, yellow, } from "./util.js";
-import { CHANNEL_KINDS, channelPlan, engineerPlan, envExample, evalFileTs, exeEvalConfigTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
+import { CHANNEL_KINDS, channelPlan, engineerPlan, envExample, evalFileTs, exeEvalConfigTs, evalScript, hostAgentTs, hostSteps, githubToolsMountTs, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
 import { suiteDir } from "./skills.js";
 import { configureArcana } from "./arcana.js";
 import { upsertEnv } from "./envfile.js";
@@ -19,6 +19,19 @@ const CORE_ITEMS = ["enterprise", "arcana", "evals"];
 // self-hosted agent it cannot get an OIDC token and the agent fails to boot.
 const ENGINEER_ITEMS_ALL = ["extension/agent-browser", "extension/github-tools"];
 const ENGINEER_ITEMS_VERCEL = ["connection/vercel"];
+/**
+ * Replace Eve's freshly installed registry mount with the Kybernesis-managed
+ * token-aware form. A failed registry add must not create a capability file.
+ */
+export function finalizeGithubToolsRegistryMount(cwd, registryAddSucceeded) {
+    if (!registryAddSucceeded)
+        return false;
+    const path = join(cwd, "agent/extensions/github.ts");
+    if (!existsSync(path))
+        return false;
+    writeFileSync(path, githubToolsMountTs());
+    return true;
+}
 export async function init(rawName, options = {}) {
     const engineer = options.engineer === true;
     const studio = options.studio === true;
@@ -165,6 +178,8 @@ export async function init(rawName, options = {}) {
         const engItems = [...ENGINEER_ITEMS_ALL, ...(host === "vercel" ? ENGINEER_ITEMS_VERCEL : [])];
         for (const item of engItems) {
             const ok = run("npx", ["eve", "add", item, "--overwrite"], { cwd: dir, allowFail: true });
+            if (item === "extension/github-tools")
+                finalizeGithubToolsRegistryMount(dir, ok);
             if (!ok)
                 console.log(yellow(`  ! ${item} did not install cleanly — re-run: npx eve add ${item}`));
         }

package/dist/model-reach.d.ts

@@ -19,6 +19,8 @@ export type DoctorModelReach = {
     kind: "claude-sub";
 } | {
     kind: "exe";
+} | {
+    kind: "grok-sub";
 } | {
     kind: "gateway";
 } | {

package/dist/model-reach.js

@@ -35,12 +35,16 @@ export function classifyModelReach(authoredSource, compiledRouting) {
     if (authoredSource !== null) {
         const claudeSubscription = /\bclaudeSubscription\s*\(/.test(authoredSource);
         const exeModel = /\bexeModel\s*\(/.test(authoredSource);
-        if (claudeSubscription && !exeModel)
+        const grokSubscription = /\bgrokSubscription\s*\(/.test(authoredSource);
+        const authored = [claudeSubscription, exeModel, grokSubscription].filter(Boolean).length;
+        if (authored === 1 && claudeSubscription)
             return { kind: "claude-sub" };
-        if (exeModel && !claudeSubscription)
+        if (authored === 1 && exeModel)
             return { kind: "exe" };
-        if (claudeSubscription && exeModel) {
-            return { kind: "unresolved", reason: "root agent authors both claudeSubscription() and exeModel()" };
+        if (authored === 1 && grokSubscription)
+            return { kind: "grok-sub" };
+        if (authored > 1) {
+            return { kind: "unresolved", reason: "root agent authors more than one model reach helper" };
         }
     }
     if (compiledRouting.kind === "gateway")

package/dist/self-version.d.ts

@@ -0,0 +1,24 @@
+export declare const STALE_KYB_FIX = "npm install -g @kybernesis/create@latest";
+export type SelfVersionResult = {
+    kind: "stale";
+    installed: string;
+    latest: string;
+    message: string;
+    fix: typeof STALE_KYB_FIX;
+} | {
+    kind: "current";
+    installed: string;
+    latest: string;
+} | {
+    kind: "ahead";
+    installed: string;
+    latest: string;
+} | {
+    kind: "unknown";
+    installed?: string;
+    latest?: string;
+};
+/** Compare the three numeric version components exactly as upgrade historically has. */
+export declare function versionLt(a: string, b: string): boolean;
+/** Look up this CLI's published version. Unknown lookup state is deliberately non-blocking. */
+export declare function checkSelfVersion(): SelfVersionResult;

package/dist/self-version.js

@@ -0,0 +1,56 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+export const STALE_KYB_FIX = "npm install -g @kybernesis/create@latest";
+function usableVersion(value) {
+    return Boolean(value && /^\d+\.\d+\.\d+$/.test(value));
+}
+/** Compare the three numeric version components exactly as upgrade historically has. */
+export function versionLt(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) < (pb[i] ?? 0))
+            return true;
+        if ((pa[i] ?? 0) > (pb[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/** Look up this CLI's published version. Unknown lookup state is deliberately non-blocking. */
+export function checkSelfVersion() {
+    let installed;
+    try {
+        installed = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    }
+    catch {
+        return { kind: "unknown" };
+    }
+    let latest;
+    try {
+        const result = spawnSync("npm", ["view", "@kybernesis/create", "version"], {
+            encoding: "utf8",
+            env: process.env,
+        });
+        if (result.status === 0)
+            latest = result.stdout.trim();
+    }
+    catch {
+        return { kind: "unknown", installed };
+    }
+    if (!usableVersion(installed) || !usableVersion(latest)) {
+        return { kind: "unknown", ...(installed ? { installed } : {}), ...(latest ? { latest } : {}) };
+    }
+    if (installed === latest)
+        return { kind: "current", installed, latest };
+    if (versionLt(installed, latest)) {
+        return {
+            kind: "stale",
+            installed,
+            latest,
+            message: `kyb ${installed} is behind ${latest}. The certified eve version is ` +
+                "compiled into this tool, so an old kyb reports an old pin as current.",
+            fix: STALE_KYB_FIX,
+        };
+    }
+    return { kind: "ahead", installed, latest };
+}

package/dist/templates.d.ts

@@ -1,5 +1,17 @@
 /** File templates written by `kyb init`. Kept in sync with the proven Kyber patterns. */
 import type { ModelScaffoldConfig } from "./model-reach.js";
+/** Exact output of Eve's legacy extension/github-tools registry item. */
+export declare const LEGACY_GITHUB_TOOLS_MOUNT = "import githubTools from \"@github-tools/eve-extension\";\n\nexport default githubTools({});\n";
+/**
+ * The managed GitHub extension mount written by init and recognized by upgrade.
+ *
+ * Eve discovers configured extensions from the direct imported-factory default
+ * call, so keep that syntax. An empty include list prevents the dynamic resolver
+ * from building any descriptors without a credential, while the lazy provider
+ * avoids eager missing-token validation. After GITHUB_TOKEN is added, a restart
+ * evaluates the module again and preserves the registry's original `{}` behavior.
+ */
+export declare function githubToolsMountTs(): string;
 export declare const DEPT_DESCRIPTIONS: Record<string, string>;
 export declare function deptDescription(dept: string): string;
 export declare function identityMd(displayName: string, depts: string[]): string;

package/dist/templates.js

@@ -1,4 +1,35 @@
 /** File templates written by `kyb init`. Kept in sync with the proven Kyber patterns. */
+/** Exact output of Eve's legacy extension/github-tools registry item. */
+export const LEGACY_GITHUB_TOOLS_MOUNT = `import githubTools from "@github-tools/eve-extension";
+
+export default githubTools({});
+`;
+/**
+ * The managed GitHub extension mount written by init and recognized by upgrade.
+ *
+ * Eve discovers configured extensions from the direct imported-factory default
+ * call, so keep that syntax. An empty include list prevents the dynamic resolver
+ * from building any descriptors without a credential, while the lazy provider
+ * avoids eager missing-token validation. After GITHUB_TOKEN is added, a restart
+ * evaluates the module again and preserves the registry's original `{}` behavior.
+ */
+export function githubToolsMountTs() {
+    return `import githubTools from "@github-tools/eve-extension";
+
+function githubToolsOptions(hasToken = Boolean(process.env.GITHUB_TOKEN)) {
+  return hasToken
+    ? {}
+    : {
+        include: [],
+        token: async () => {
+          throw new Error("GITHUB_TOKEN is not set.");
+        },
+      };
+}
+
+export default githubTools(githubToolsOptions());
+`;
+}
 export const DEPT_DESCRIPTIONS = {
     finance: "Finance specialist: financials, budgets, spend, revenue, invoices, runway, and financial reporting. Keeps the finance team's own memory workspace. Delegate any finance-shaped task, question, or reporting request here.",
     marketing: "Marketing specialist: campaigns, content, positioning, brand, launches, social, and ads. Keeps the marketing team's own memory workspace. Delegate any marketing-shaped task or question here.",

package/dist/upgrade.d.ts

@@ -1,7 +1,25 @@
 import { type AgentInputLimit } from "./agent-limits.js";
 export declare function agentInputLimitUpgradeMessage(limit: AgentInputLimit): string;
+export type GithubToolsMountRepair = {
+    kind: "missing" | "current" | "updated" | "customized";
+} | {
+    kind: "error";
+    message: string;
+};
+/** Upgrade only the exact registry scaffold; authored GitHub policy is not ours. */
+export declare function repairGithubToolsMount(cwd: string): GithubToolsMountRepair;
 export interface UpgradeOptions {
+    allowStale?: boolean;
+    host?: true | string;
     skipEval?: boolean;
     yes?: boolean;
 }
+type EvalGatePreflight = {
+    kind: "ready";
+} | {
+    kind: "unavailable";
+    reasons: string[];
+};
+export declare function preflightEvalGate(cwd: string): Promise<EvalGatePreflight>;
 export declare function upgrade(options?: UpgradeOptions): Promise<void>;
+export {};

package/dist/upgrade.js

@@ -1,50 +1,21 @@
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, 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 { 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";
 import { EVE_VERSION, bold, capture, dim, green, parseEnv, red, run, yellow } from "./util.js";
 import { inspectEveAgent } from "./agent-limits.js";
+import { remoteProjectPath, sshTarget } from "./deploy.js";
+import { classifyModelReach } from "./model-reach.js";
+import { checkSelfVersion, versionLt } from "./self-version.js";
+import { LEGACY_GITHUB_TOOLS_MOUNT, githubToolsMountTs } from "./templates.js";
 import { confirmEveUpgrade, inspectBuzzSessions, inspectDurableRuns, reconcileEvalScript, } from "./upgrade-sessions.js";
-function versionLt(a, b) {
-    const pa = a.split(".").map(Number);
-    const pb = b.split(".").map(Number);
-    for (let i = 0; i < 3; i++) {
-        if ((pa[i] ?? 0) < (pb[i] ?? 0))
-            return true;
-        if ((pa[i] ?? 0) > (pb[i] ?? 0))
-            return false;
-    }
-    return false;
-}
-/**
- * Warn when this CLI is itself out of date.
- *
- * @remarks
- * The certified eve version is a constant compiled INTO this tool, so an old
- * kyb reports an old pin as though it were current — and does it with total
- * confidence, in the one command whose entire job is telling you what current
- * means. That failure runs the wrong way round: it tells a healthy agent it is
- * ahead of certified and in "unsupported territory", which invites someone to
- * downgrade a fleet that was fine.
- *
- * Checked here rather than at install because this is the command where being
- * stale changes the answer.
- */
-function warnIfStale() {
-    const installed = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-    const latest = capture("npm", ["view", "@kybernesis/create", "version"])?.trim();
-    if (!latest || latest === installed)
-        return;
-    if (!versionLt(installed, latest))
-        return;
-    console.log(`  ${yellow("!")} kyb ${installed} is behind ${latest}. The certified eve version is ` +
-        `compiled into this tool, so an old kyb reports an old pin as current.`);
-    console.log(`    ${dim("npm install -g @kybernesis/create@latest")}\n`);
-}
 export function agentInputLimitUpgradeMessage(limit) {
     switch (limit.kind) {
         case "explicit-numeric":
@@ -223,6 +194,48 @@ function repairSandboxCleanupHooks(cwd, deps) {
     console.log(`  ${green("+")} installed terminal sandbox cleanup for ${added.length} agent scope(s) ` +
         `${dim("(completed and failed sessions only)")}\n`);
 }
+/** Upgrade only the exact registry scaffold; authored GitHub policy is not ours. */
+export function repairGithubToolsMount(cwd) {
+    const path = join(cwd, "agent/extensions/github.ts");
+    if (!existsSync(path))
+        return { kind: "missing" };
+    let current;
+    try {
+        current = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        return { kind: "error", message: `could not read agent/extensions/github.ts: ${error.message}` };
+    }
+    const desired = githubToolsMountTs();
+    if (current === desired)
+        return { kind: "current" };
+    if (current !== LEGACY_GITHUB_TOOLS_MOUNT)
+        return { kind: "customized" };
+    const temp = `${path}.kyb-${process.pid}`;
+    try {
+        writeFileSync(temp, desired);
+        renameSync(temp, path);
+        return { kind: "updated" };
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        return { kind: "error", message: `could not update agent/extensions/github.ts: ${error.message}` };
+    }
+}
+function reportGithubToolsMountRepair(cwd) {
+    const result = repairGithubToolsMount(cwd);
+    if (result.kind === "updated") {
+        console.log(`  ${green("+")} updated agent/extensions/github.ts ` +
+            `${dim("(GitHub tools stay off until GITHUB_TOKEN is set)")}`);
+    }
+    else if (result.kind === "customized") {
+        console.log(`  ${yellow("!")} agent/extensions/github.ts is customized, so it was left unchanged.\n` +
+            `    To adopt the quiet no-token behavior, compare it with a new \`kyb init --engineer\` scaffold.`);
+    }
+    else if (result.kind === "error") {
+        console.log(`  ${yellow("!")} ${result.message}; leaving the file unchanged.`);
+    }
+}
 /**
  * Keep package-owned host files synchronized with the package that installed them.
  *
@@ -235,7 +248,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
@@ -265,18 +278,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"], {
@@ -357,6 +389,141 @@ function repairEvalCommand(cwd) {
         `    Manual remediation: make this command invoke kyb-eval instead of eve eval, preserving its setup and arguments.\n` +
         `    Current scripts.eval: ${dim(JSON.stringify(current))}`);
 }
+const EVAL_GATE_UNAVAILABLE_EXIT = 2;
+const DEFAULT_EXE_MODELS_URL = "https://llm.int.exe.xyz/models.json";
+function evalGateEnvironment(cwd) {
+    const envPath = join(cwd, ".env.local");
+    return {
+        ...(existsSync(envPath) ? parseEnv(readFileSync(envPath, "utf8")) : {}),
+        ...process.env,
+    };
+}
+async function routeAnswers(url) {
+    try {
+        await fetch(url, { signal: AbortSignal.timeout(6000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function claudeSubscriptionProxyReady(cwd) {
+    const module = join(cwd, "node_modules/@kybernesis/exe/dist/claude.js");
+    if (!existsSync(module))
+        return false;
+    try {
+        const loaded = (await import(pathToFileURL(module).href));
+        if (typeof loaded.claudeProxyReady !== "function")
+            return false;
+        return (await loaded.claudeProxyReady()).ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve an exe-backed judge from the provider the authored config actually calls. */
+function exeJudgeUrl(cwd, env) {
+    const paths = [join(cwd, "evals/evals.config.ts"), join(cwd, "evals.config.ts")];
+    const path = paths.find((candidate) => existsSync(candidate));
+    if (!path)
+        return null;
+    const source = readFileSync(path, "utf8");
+    const judgeProvider = /judge\s*:\s*\{[\s\S]*?model\s*:\s*([A-Za-z_$][\w$]*)\s*\(/.exec(source)?.[1];
+    if (!judgeProvider)
+        return null;
+    const escaped = judgeProvider.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const providerBody = new RegExp(`(?:const|let)\\s+${escaped}\\s*=\\s*create[A-Za-z]+\\s*\\(\\s*\\{([\\s\\S]*?)\\}\\s*\\)`).exec(source)?.[1];
+    if (!providerBody)
+        return /EXE_LLM_URL|llm\.int\.exe\.xyz/.test(source) ? undefined : null;
+    if (/EXE_LLM_URL/.test(providerBody))
+        return env.EXE_LLM_URL || DEFAULT_EXE_MODELS_URL;
+    const baseUrl = /baseURL\s*:\s*["']([^"']+)["']/.exec(providerBody)?.[1];
+    if (baseUrl?.includes("llm.int.exe.xyz"))
+        return baseUrl;
+    return null;
+}
+export async function preflightEvalGate(cwd) {
+    const env = evalGateEnvironment(cwd);
+    const agentPath = join(cwd, "agent/agent.ts");
+    const authoredSource = existsSync(agentPath) ? readFileSync(agentPath, "utf8") : null;
+    const inspection = inspectEveAgent(cwd, env);
+    const reach = classifyModelReach(authoredSource, inspection?.modelRouting ?? {
+        kind: "unresolved",
+        reason: "eve info failed before compiled model routing could be inspected",
+    });
+    const reasons = [];
+    switch (reach.kind) {
+        case "claude-sub":
+            if (!(await claudeSubscriptionProxyReady(cwd)))
+                reasons.push("the agent model proxy is unreachable");
+            break;
+        case "exe":
+            if (!(await routeAnswers(env.EXE_LLM_URL || DEFAULT_EXE_MODELS_URL)))
+                reasons.push("the agent model route is unreachable");
+            break;
+        case "unresolved":
+            reasons.push(`the agent model route could not be resolved (${reach.reason})`);
+            break;
+        case "grok-sub":
+        case "gateway":
+        case "direct-provider":
+            break;
+    }
+    const judgeUrl = exeJudgeUrl(cwd, env);
+    if (judgeUrl === undefined)
+        reasons.push("the eve judge route could not be resolved");
+    else if (judgeUrl && !(await routeAnswers(judgeUrl)))
+        reasons.push("the eve judge is unreachable");
+    return reasons.length === 0 ? { kind: "ready" } : { kind: "unavailable", reasons };
+}
+function hostEvalCommand(cwd, target) {
+    const host = target ?? "<host>";
+    return `ssh ${host} ${shellQuote(`cd ${remoteProjectPath(cwd)} && npm run eval`)}`;
+}
+function reportEvalGateUnavailable(cwd, target, reasons) {
+    console.log(`\n${yellow("The eval gate for this agent can only run on its host (the model proxy and the eve judge are only reachable there).")}`);
+    for (const reason of reasons)
+        console.log(`  ${dim(reason)}`);
+    console.log(`Run it there: ${bold(hostEvalCommand(cwd, target ?? undefined))}\n`);
+    process.exitCode = EVAL_GATE_UNAVAILABLE_EXIT;
+}
+async function runUpgradeEvalGate(cwd, host) {
+    if (host !== undefined) {
+        const target = sshTarget(cwd, typeof host === "string" && host.length > 0 ? host : undefined);
+        if (!target) {
+            reportEvalGateUnavailable(cwd, null, ["no ssh target is configured"]);
+            return;
+        }
+        console.log(bold(`\nRunning the eval gate on ${target} (${remoteProjectPath(cwd)}) — deploy only on green …\n`));
+        const result = spawnSync("ssh", [target, `cd ${remoteProjectPath(cwd)} && npm run eval`], {
+            cwd,
+            env: process.env,
+            stdio: "inherit",
+        });
+        if (result.status === 0) {
+            console.log(`\n${green("✓ Upgrade green.")} Deploy with: ${bold("npx eve deploy")}\n`);
+        }
+        else {
+            console.log(`\n${red("✗ Evals failed after upgrade.")} Do NOT deploy — inspect .eve/evals/ artifacts on the host.\n`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    const preflight = await preflightEvalGate(cwd);
+    if (preflight.kind === "unavailable") {
+        reportEvalGateUnavailable(cwd, sshTarget(cwd), preflight.reasons);
+        return;
+    }
+    console.log(bold("\nRunning the eval gate (npm run eval) — deploy only on green …\n"));
+    const ok = run("npm", ["run", "eval"], { cwd, allowFail: true });
+    if (ok) {
+        console.log(`\n${green("✓ Upgrade green.")} Deploy with: ${bold("npx eve deploy")}\n`);
+    }
+    else {
+        console.log(`\n${red("✗ Evals failed after upgrade.")} Do NOT deploy — inspect .eve/evals/ artifacts.\n`);
+        process.exitCode = 1;
+    }
+}
 function upgradeEnvironment(cwd) {
     const envPath = join(cwd, ".env.local");
     const env = {
@@ -507,6 +674,16 @@ function startStoppedBridge(cwd, unit) {
     return false;
 }
 export async function upgrade(options = {}) {
+    console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
+    const selfVersion = checkSelfVersion();
+    if (selfVersion.kind === "stale") {
+        console.log(`  ${yellow("!")} ${selfVersion.message}`);
+        console.log(`    ${dim(selfVersion.fix)}\n`);
+        if (!options.allowStale) {
+            process.exitCode = 1;
+            return;
+        }
+    }
     const cwd = process.cwd();
     const packagePath = join(cwd, "package.json");
     const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
@@ -514,8 +691,6 @@ export async function upgrade(options = {}) {
         ...(pkg.dependencies ?? {}),
         ...(pkg.devDependencies ?? {}),
     };
-    console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
-    warnIfStale();
     reportAgentInputLimit(cwd);
     const entries = dependencyEntries(pkg);
     const installedVersions = new Map();
@@ -597,6 +772,7 @@ export async function upgrade(options = {}) {
         repairBuzzSetup(cwd, deps);
         repairRemovedDefaultTools(cwd);
         repairSandboxCleanupHooks(cwd, deps);
+        reportGithubToolsMountRepair(cwd);
         repairHostArtifacts(cwd, deps);
         repairEvalCommand(cwd);
         repairManageRestart(cwd, deps);
@@ -654,6 +830,7 @@ export async function upgrade(options = {}) {
     repairBuzzSetup(cwd, deps);
     repairRemovedDefaultTools(cwd);
     repairSandboxCleanupHooks(cwd, deps);
+    reportGithubToolsMountRepair(cwd);
     repairHostArtifacts(cwd, deps);
     repairEvalCommand(cwd);
     repairManageRestart(cwd, deps);
@@ -666,13 +843,5 @@ export async function upgrade(options = {}) {
         console.log(yellow("\nEval gate SKIPPED (--skip-eval). Run `npm run eval` before deploying.\n"));
         return;
     }
-    console.log(bold("\nRunning the eval gate (npm run eval) — deploy only on green …\n"));
-    const ok = run("npm", ["run", "eval"], { cwd, allowFail: true });
-    if (ok) {
-        console.log(`\n${green("✓ Upgrade green.")} Deploy with: ${bold("npx eve deploy")}\n`);
-    }
-    else {
-        console.log(`\n${red("✗ Evals failed after upgrade.")} Do NOT deploy — inspect .eve/evals/ artifacts.\n`);
-        process.exit(1);
-    }
+    await runUpgradeEvalGate(cwd, options.host);
 }

package/package.json

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