@kybernesis/create 0.14.3 → 0.14.6

package/README.md

@@ -47,13 +47,22 @@ 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]`
+## `kyb upgrade [--skip-eval] [--yes]`
 
 Compares installed `@kybernesis/*` versions against npm, installs what's
 behind, typechecks, then **runs the eval suite as the gate** — prints
 "deploy" only on green. This is the maintenance-retainer loop as a command:
 package improvement → `kyb upgrade` per client → green → `npx eve deploy`.
 
+Before an eve version change, upgrade reads `.eve/.workflow-data/runs`, prints
+`This will reset N open conversations`, lists matching persisted Buzz channel
+sessions when available, and requires explicit confirmation. Noninteractive
+runs fail closed unless `--yes` (or `-y`) is supplied. The warning is still printed with
+`--yes` and is not bypassed by `--skip-eval`. Existing direct `eve eval` scripts
+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.
+
 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
 systemd unit, warning before replacement and printing an exact manual repair

package/dist/cli.js

@@ -11,6 +11,7 @@
  *   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)
+ *     --yes, -y             confirm an eve upgrade noninteractively
  */
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
@@ -73,7 +74,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 the certified versions (--skip-eval).",
+    upgrade: "Bring @kybernesis packages and eve to certified versions (--skip-eval, --yes).",
     tui: "Talk to your agents in the terminal.",
     version: "Print the version of this tool.",
 };
@@ -144,7 +145,10 @@ switch (command) {
         tui(rest);
         break;
     case "upgrade":
-        await upgrade(rest.includes("--skip-eval"));
+        await upgrade({
+            skipEval: rest.includes("--skip-eval"),
+            yes: rest.includes("--yes") || rest.includes("-y"),
+        });
         break;
     case "--version":
     case "-v":
@@ -209,6 +213,7 @@ ${dim("  npm i -g @kybernesis/create@latest")}
       --no-env          ${dim("do not send .env.local (host manages its own secrets)")}
   ${bold("kyb upgrade")}         bump @kybernesis/* packages, gated on evals
       --skip-eval       ${dim("skip the eval gate")}
+      --yes, -y          ${dim("confirm an eve version change noninteractively")}
 
 Registry: https://registry.kybernesis.ai · Docs: the FDE playbook
 `);

package/dist/init.js

@@ -74,7 +74,19 @@ export async function init(rawName, options = {}) {
     // refuses an id it cannot find in the AI Gateway catalog and then creates
     // nothing at all, and an exe-hosted agent takes its model from EXE_MODEL,
     // not from the gateway.
-    run("npx", [`eve@${EVE_VERSION}`, "init", name], { allowFail: true });
+    // Two guards, both learned on a real Factory build (KYB-521):
+    //  - AI_AGENT: eve's init hands off to `eve dev --onboard` when it sees no
+    //    interactive terminal, and that is a server that waits for a person, so a
+    //    headless `kyb init` never returned. eve skips the handoff and prints its
+    //    summary when it believes a coding agent launched it; the marker is
+    //    stripped from eve's own child spawns, so nothing else sees it.
+    //  - a timeout, because `--yes` cannot reach a choice eve makes internally,
+    //    and a scaffold that cannot finish must fail, not wait forever.
+    run("npx", [`eve@${EVE_VERSION}`, "init", name], {
+        allowFail: true,
+        env: { AI_AGENT: process.env.AI_AGENT?.trim() || "kybernesis-create" },
+        timeoutMs: 20 * 60_000,
+    });
     // The real test of that step, since its exit code cannot be trusted.
     if (!existsSync(join(dir, "package.json"))) {
         console.error(red(`\n  eve did not create a project in ${dir}. Nothing else can run.`));

package/dist/templates.js

@@ -207,7 +207,7 @@ export function evalScript(name, depts) {
         `ARCANA_DM_WORKSPACE=${name}-eval`,
         ...depts.map((d) => `ARCANA_${d.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_WORKSPACE=${name}-eval`),
     ];
-    return `${overrides.join(" ")} eve eval`;
+    return `${overrides.join(" ")} kyb-eval`;
 }
 export const CHANNEL_KINDS = [
     "none",

package/dist/upgrade-sessions.d.ts

@@ -0,0 +1,43 @@
+import type { Readable, Writable } from "node:stream";
+export interface DurableRunInspection {
+    runningRunIds: string[];
+    inspectedRecords: number;
+    issues: string[];
+}
+export interface BuzzSessionMatch {
+    runId: string;
+    community: string;
+    channel: string;
+}
+export interface BuzzSessionInspection {
+    path?: string;
+    matches: BuzzSessionMatch[];
+    issue?: string;
+}
+export type EvalScriptReconciliation = {
+    kind: "updated";
+    script: string;
+} | {
+    kind: "current";
+    script: string;
+} | {
+    kind: "custom";
+    script: string;
+} | {
+    kind: "missing";
+};
+/** Read the local durable records without loading eve or mutating its store. */
+export declare function inspectDurableRuns(cwd: string): DurableRunInspection;
+/** Follow the same precedence as buzzBridge when enough environment is available. */
+export declare function buzzSessionsPath(cwd: string, env: Record<string, string | undefined>): string | undefined;
+/** Best-effort join from durable run ids to Buzz's persisted community|channel map. */
+export declare function inspectBuzzSessions(cwd: string, env: Record<string, string | undefined>, runningRunIds: readonly string[]): BuzzSessionInspection;
+/** Replace only a simple direct eve eval invocation, preserving assignments and arguments. */
+export declare function reconcileEvalScript(script: unknown): EvalScriptReconciliation;
+export declare function confirmEveUpgrade(options: {
+    yes: boolean;
+    input?: Readable & {
+        isTTY?: boolean;
+    };
+    output?: Writable;
+}): Promise<boolean>;

package/dist/upgrade-sessions.js

@@ -0,0 +1,123 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+/** Read the local durable records without loading eve or mutating its store. */
+export function inspectDurableRuns(cwd) {
+    const runsDir = join(cwd, ".eve", ".workflow-data", "runs");
+    if (!existsSync(runsDir))
+        return { runningRunIds: [], inspectedRecords: 0, issues: [] };
+    let entries;
+    try {
+        entries = readdirSync(runsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        return {
+            runningRunIds: [],
+            inspectedRecords: 0,
+            issues: [`could not read ${runsDir}: ${error.message}`],
+        };
+    }
+    const runningRunIds = [];
+    const issues = [];
+    let inspectedRecords = 0;
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const path = join(runsDir, entry.name);
+        try {
+            const record = JSON.parse(readFileSync(path, "utf8"));
+            inspectedRecords += 1;
+            if (record.status !== "running")
+                continue;
+            if (typeof record.runId !== "string" || record.runId.length === 0) {
+                issues.push(`${path}: running record has no string runId`);
+                continue;
+            }
+            runningRunIds.push(record.runId);
+        }
+        catch (error) {
+            issues.push(`${path}: ${error.message}`);
+        }
+    }
+    return { runningRunIds, inspectedRecords, issues };
+}
+function resolveEnvPath(cwd, value) {
+    return isAbsolute(value) ? value : resolve(cwd, value);
+}
+/** Follow the same precedence as buzzBridge when enough environment is available. */
+export function buzzSessionsPath(cwd, env) {
+    if (env.BUZZ_SESSIONS_FILE)
+        return resolveEnvPath(cwd, env.BUZZ_SESSIONS_FILE);
+    const legacy = join(cwd, ".buzz-sessions.json");
+    if (existsSync(legacy))
+        return legacy;
+    if (env.BUZZ_KEYFILE)
+        return join(dirname(resolveEnvPath(cwd, env.BUZZ_KEYFILE)), "buzz-sessions.json");
+    return undefined;
+}
+/** Best-effort join from durable run ids to Buzz's persisted community|channel map. */
+export function inspectBuzzSessions(cwd, env, runningRunIds) {
+    const path = buzzSessionsPath(cwd, env);
+    if (!path) {
+        return { matches: [], issue: "no BUZZ_SESSIONS_FILE, legacy .buzz-sessions.json, or BUZZ_KEYFILE was found" };
+    }
+    if (!existsSync(path))
+        return { path, matches: [], issue: `${path} does not exist` };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            throw new Error("expected an object map");
+        const running = new Set(runningRunIds);
+        const matches = [];
+        for (const [key, value] of Object.entries(raw)) {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                continue;
+            const runId = value.id;
+            if (typeof runId !== "string" || !running.has(runId))
+                continue;
+            const separator = key.lastIndexOf("|");
+            matches.push({
+                runId,
+                community: separator < 0 ? "unknown community" : key.slice(0, separator),
+                channel: separator < 0 ? key : key.slice(separator + 1),
+            });
+        }
+        return { path, matches };
+    }
+    catch (error) {
+        return { path, matches: [], issue: `could not read Buzz session metadata at ${path}: ${error.message}` };
+    }
+}
+/** Replace only a simple direct eve eval invocation, preserving assignments and arguments. */
+export function reconcileEvalScript(script) {
+    if (typeof script !== "string" || script.trim().length === 0)
+        return { kind: "missing" };
+    if (/^\s*(?:(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s]+))\s+)*kyb-eval(?:\s|$)/.test(script)) {
+        return { kind: "current", script };
+    }
+    if (/[;&|<>`]/.test(script))
+        return { kind: "custom", script };
+    const direct = /^(\s*(?:(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s]+))\s+)*)eve\s+eval(?=\s|$)(.*)$/.exec(script);
+    if (!direct)
+        return { kind: "custom", script };
+    return { kind: "updated", script: `${direct[1]}kyb-eval${direct[2]}` };
+}
+export async function confirmEveUpgrade(options) {
+    if (options.yes)
+        return true;
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    if (input.isTTY !== true)
+        return false;
+    const rl = createInterface({ input, output });
+    try {
+        const answer = (await rl.question("Continue with the eve upgrade? Type yes to continue: ")).trim().toLowerCase();
+        return answer === "yes" || answer === "y";
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/upgrade.d.ts

@@ -1,3 +1,7 @@
 import { type AgentInputLimit } from "./agent-limits.js";
 export declare function agentInputLimitUpgradeMessage(limit: AgentInputLimit): string;
-export declare function upgrade(skipEval: boolean): Promise<void>;
+export interface UpgradeOptions {
+    skipEval?: boolean;
+    yes?: boolean;
+}
+export declare function upgrade(options?: UpgradeOptions): Promise<void>;

package/dist/upgrade.js

@@ -1,31 +1,14 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { upsertEnv } from "./envfile.js";
 import { reconcileHostArtifact } from "./host-artifacts.js";
-import { repairManageRestart } from "./systemd.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";
-/**
- * Which packages to upgrade: every `@kybernesis/*` this agent depends on.
- *
- * @remarks
- * This was a fixed list of six, written when there were six. Four more shipped
- * afterwards — connectors, local, manage and exe — and an agent using them was
- * told "everything is at latest certified versions" while holding versions from
- * months earlier. A hardcoded list does not fail loudly when it falls behind;
- * it just quietly stops covering things, and the command that reports it is the
- * same one that is wrong.
- *
- * Reading the manifest cannot fall behind. A package added tomorrow is covered
- * by an upgrade run today.
- */
-function kybernesisPackages(deps) {
-    return Object.keys(deps)
-        .filter((name) => name.startsWith("@kybernesis/"))
-        .sort();
-}
+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);
@@ -330,113 +313,329 @@ function repairHostArtifacts(cwd, deps) {
         manualCommand: `bash ${shellQuote(serviceScript)} --refresh-unit`,
     });
 }
-export async function upgrade(skipEval) {
+function repairEvalCommand(cwd) {
+    const packagePath = join(cwd, "package.json");
+    const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+    const result = reconcileEvalScript(pkg.scripts?.eval);
+    if (result.kind === "updated") {
+        pkg.scripts = { ...pkg.scripts, eval: result.script };
+        writeFileSync(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
+        console.log(`  ${green("+")} updated scripts.eval to run through kyb-eval`);
+        return;
+    }
+    if (result.kind === "current")
+        return;
+    const current = result.kind === "custom" ? result.script : "(missing)";
+    console.log(`  ${yellow("!")} scripts.eval is not a recognized direct eve eval command, so it was left unchanged.\n` +
+        `    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))}`);
+}
+function upgradeEnvironment(cwd) {
+    const envPath = join(cwd, ".env.local");
+    const env = {
+        ...(existsSync(envPath) ? parseEnv(readFileSync(envPath, "utf8")) : {}),
+        ...process.env,
+    };
+    if (!env.BUZZ_SESSIONS_FILE && !env.BUZZ_KEYFILE) {
+        const unit = capture("sh", [
+            "-c",
+            "grep -ohE 'BUZZ_(SESSIONS_FILE|KEYFILE)=[^ \" ]+' /etc/systemd/system/*buzz-bridge.service 2>/dev/null | head -1",
+        ]);
+        const [name, ...value] = (unit ?? "").trim().split("=");
+        if (name && value.length > 0)
+            env[name] = value.join("=").replace(/^\"|\"$/g, "");
+    }
+    return env;
+}
+async function approveEveChange(cwd, yes, hasBuzz) {
+    const durable = inspectDurableRuns(cwd);
+    console.log(bold(`\nThis will reset ${durable.runningRunIds.length} open conversations`));
+    if (durable.issues.length > 0) {
+        console.log(`  ${yellow("!")} Durable-store inspection was incomplete; the count includes only readable records ` +
+            `whose status is exactly "running".`);
+        for (const issue of durable.issues)
+            console.log(`    ${dim(issue)}`);
+    }
+    if (hasBuzz) {
+        const buzz = inspectBuzzSessions(cwd, upgradeEnvironment(cwd), durable.runningRunIds);
+        if (buzz.matches.length > 0) {
+            console.log("  Buzz-bound open conversations:");
+            for (const match of buzz.matches) {
+                console.log(`    ${match.runId} ${dim(`(${match.community} | ${match.channel})`)}`);
+            }
+        }
+        else if (buzz.issue) {
+            console.log(`  ${yellow("!")} Buzz session metadata unavailable: ${buzz.issue}`);
+        }
+        else {
+            console.log(`  ${dim("No open durable conversations were matched to Buzz session metadata.")}`);
+        }
+    }
+    const approved = await confirmEveUpgrade({ yes });
+    if (!approved) {
+        console.log(`\n${red("Eve upgrade cancelled before installation.")} ` +
+            `${dim("Pass --yes for deliberate noninteractive use.")}\n`);
+    }
+    return approved;
+}
+function commandResult(command, args, cwd, print = true) {
+    console.log(dim(`  $ ${command} ${args.join(" ")}`));
+    const result = spawnSync(command, args, { cwd, encoding: "utf8", env: process.env });
+    const stdout = result.stdout ?? "";
+    const stderr = result.stderr ?? "";
+    if (print) {
+        if (stdout)
+            process.stdout.write(stdout);
+        if (stderr)
+            process.stderr.write(stderr);
+    }
+    return { status: result.status ?? 1, stdout, stderr };
+}
+function fail(message) {
+    console.error(red(message));
+    process.exitCode = 1;
+}
+function majorMinor(version) {
+    const match = /^(\d+)\.(\d+)(?:\.|$)/.exec(version);
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    return Number.isSafeInteger(major) && Number.isSafeInteger(minor) ? [major, minor] : null;
+}
+function installedPackageValue(cwd, name, expression) {
+    const packageName = JSON.stringify(`${name}/package.json`);
+    return capture("node", ["-p", `require(${packageName})${expression}`], cwd)?.trim() || null;
+}
+function targetEvePeer(name, version) {
+    return capture("npm", ["view", `${name}@${version}`, "peerDependencies.eve"])?.trim() || undefined;
+}
+function dependencyEntries(pkg) {
+    const entries = [];
+    for (const section of ["dependencies", "devDependencies"]) {
+        const values = pkg[section];
+        for (const [name, range] of Object.entries(values ?? {})) {
+            if (name === "eve" || name.startsWith("@kybernesis/"))
+                entries.push({ name, section, range });
+        }
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name) || a.section.localeCompare(b.section));
+}
+function rewriteManifest(cwd, pkg, targets) {
+    for (const target of targets) {
+        const section = pkg[target.section];
+        // eve is pinned exactly: the pin IS the certification. A caret let a
+        // clean install resolve eve@0.49.1 against a certified 0.49.0 (blind
+        // latest, the one thing kyb upgrade exists to prevent).
+        section[target.name] = target.name === "eve" ? target.targetVersion : `^${target.targetVersion}`;
+    }
+    writeFileSync(join(cwd, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+}
+function recoveryGuidance(targets, bridgeUnit) {
+    console.log(`\n${yellow("The dependency tree was not verified. Complete the clean install before using it:")}\n` +
+        `  1. Ensure every root @kybernesis/* range in package.json is the resolved ^version, and eve is pinned exactly to ${EVE_VERSION}.\n` +
+        `  2. ${dim("rm -rf node_modules")}\n` +
+        `  3. ${dim("rm -f package-lock.json")}\n` +
+        `  4. ${dim("npm install")}\n` +
+        `  5. ${dim("npm ls eve")}`);
+    const peerChanges = targets.filter((target) => target.name.startsWith("@kybernesis/") &&
+        target.installedEvePeer !== target.targetEvePeer &&
+        (target.installedEvePeer !== undefined || target.targetEvePeer !== undefined));
+    if (peerChanges.length > 0) {
+        console.log("\n  Published Eve peer metadata changed for these root packages:");
+        for (const target of peerChanges) {
+            console.log(`    ${target.name}: ${target.installedVersion} peers on ${target.installedEvePeer ?? "(none)"}; ` +
+                `${target.targetVersion} peers on ${target.targetEvePeer ?? "(none)"}`);
+        }
+        console.log(dim("  These are metadata facts, not an attribution of npm's reported conflict."));
+    }
+    if (bridgeUnit) {
+        console.log(`\n  The Buzz bridge remains stopped until the tree is verified. Then run:\n    ${dim(`sudo -n systemctl start ${bridgeUnit}`)}`);
+    }
+}
+function buzzBridgeUnit(cwd) {
+    const systemdDir = process.env.KYB_SYSTEMD_DIR;
+    const match = findMatchingAgentServiceUnit(cwd, systemdDir || undefined);
+    return match ? `${match.values.name}-buzz-bridge.service` : null;
+}
+function stopActiveBridge(cwd, unit) {
+    if (!unit)
+        return null;
+    const active = commandResult("systemctl", ["is-active", "--quiet", unit], cwd, false);
+    if (active.status !== 0)
+        return null;
+    const stopped = commandResult("sudo", ["-n", "systemctl", "stop", unit], cwd);
+    if (stopped.status === 0)
+        return unit;
+    fail(`Could not stop the active Buzz bridge. Run exactly:\n  sudo -n systemctl stop ${unit}`);
+    return false;
+}
+function startStoppedBridge(cwd, unit) {
+    const started = commandResult("sudo", ["-n", "systemctl", "start", unit], cwd);
+    if (started.status === 0)
+        return true;
+    fail(`Could not restart the Buzz bridge. Run exactly:\n` +
+        `  sudo -n systemctl start ${unit}\n` +
+        `  systemctl status ${unit}`);
+    return false;
+}
+export async function upgrade(options = {}) {
     const cwd = process.cwd();
-    const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
-    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const packagePath = join(cwd, "package.json");
+    const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+    const deps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
     console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
     warnIfStale();
-    // Read-only: report the compiled effective policy, never rewrite agent/agent.ts.
     reportAgentInputLimit(cwd);
-    // Env-only, so it is safe before anything is installed.
-    repairLocalQueueTimeouts(cwd, deps);
-    const toUpgrade = [];
-    const unresolved = [];
-    for (const name of kybernesisPackages(deps)) {
-        if (!deps[name])
+    const entries = dependencyEntries(pkg);
+    const installedVersions = new Map();
+    const targetVersions = new Map();
+    const installedPeers = new Map();
+    const targetPeers = new Map();
+    const unresolved = new Set();
+    for (const name of [...new Set(entries.map((entry) => entry.name))]) {
+        const installed = installedPackageValue(cwd, name, ".version");
+        if (!installed) {
+            console.log(`  ${yellow("!")} ${name}: could not resolve installed version`);
+            unresolved.add(name);
             continue;
-        const installed = capture("node", ["-p", `require('${name}/package.json').version`], cwd)?.trim();
-        const latest = capture("npm", ["view", name, "version"])?.trim();
-        if (!installed || !latest) {
-            console.log(`  ${yellow("!")} ${name}: could not resolve versions`);
-            unresolved.push(name);
+        }
+        installedVersions.set(name, installed);
+        const target = name === "eve" ? EVE_VERSION : capture("npm", ["view", name, "version"])?.trim();
+        if (!target) {
+            console.log(`  ${yellow("!")} ${name}: could not resolve target version`);
+            unresolved.add(name);
             continue;
         }
-        if (installed === latest)
-            console.log(`  ${green("✓")} ${name}@${installed} ${dim("(latest)")}`);
-        else {
-            console.log(`  ${yellow("↑")} ${name}: ${installed} → ${latest}`);
-            toUpgrade.push(`${name}@${latest}`);
+        targetVersions.set(name, target);
+        if (name.startsWith("@kybernesis/")) {
+            installedPeers.set(name, installedPackageValue(cwd, name, ".peerDependencies?.eve || ''") ?? undefined);
+            targetPeers.set(name, targetEvePeer(name, target));
         }
-    }
-    // eve itself: upgrade to the KYBERNESIS-CERTIFIED version, never blindly to
-    // npm latest. Certification happens in the platform repo — packages are
-    // tested against a new eve, then the pin in @kybernesis/create advances,
-    // then this command carries client agents there behind their eval gate.
-    let eveChanged = false;
-    const eveInstalled = capture("node", ["-p", "require('eve/package.json').version"], cwd)?.trim();
-    const eveLatest = capture("npm", ["view", "eve", "version"])?.trim();
-    if (eveInstalled) {
-        if (versionLt(eveInstalled, EVE_VERSION)) {
-            console.log(`  ${yellow("↑")} eve: ${eveInstalled} → ${EVE_VERSION} ${dim("(Kybernesis-certified)")}`);
-            toUpgrade.push(`eve@${EVE_VERSION}`);
-            eveChanged = true;
+        if (installed === target) {
+            console.log(`  ${green("✓")} ${name}@${installed} ${dim(name === "eve" ? "(certified)" : "(latest)")}`);
         }
-        else if (versionLt(EVE_VERSION, eveInstalled)) {
-            console.log(`  ${yellow("!")} eve@${eveInstalled} is AHEAD of the certified ${EVE_VERSION} ${dim("— unsupported territory")}`);
+        else if (name === "eve" && versionLt(EVE_VERSION, installed)) {
+            console.log(`  ${yellow("!")} eve@${installed} is AHEAD of the certified ${EVE_VERSION} ${dim("— unsupported territory")}`);
         }
         else {
-            console.log(`  ${green("✓")} eve@${eveInstalled} ${dim("(certified)")}`);
-        }
-        if (eveLatest && versionLt(EVE_VERSION, eveLatest)) {
-            console.log(dim(`    note: eve@${eveLatest} exists upstream; ${EVE_VERSION} is the newest Kybernesis-certified version.`));
+            console.log(`  ${yellow("↑")} ${name}: ${installed} → ${target}` +
+                (name === "eve" ? ` ${dim("(Kybernesis-certified)")}` : ""));
         }
     }
-    if (toUpgrade.length === 0 && unresolved.length > 0) {
-        // Saying everything is current, having just failed to check several
-        // packages, is the worst available answer: it is the sentence someone
-        // repeats to a client. Usually the dependencies are simply not installed
-        // here, which is worth naming rather than hiding behind a green tick.
-        console.log(`\n${yellow(`Checked what could be read. ${unresolved.length} package(s) could not be ` +
-            `resolved, so this is not a clean bill of health.`)}\n` +
-            `  ${dim("Usually: dependencies are not installed here. Run npm install, then kyb upgrade.")}\n`);
-        repairManageRestart(cwd, deps);
+    const eveInstalled = installedVersions.get("eve");
+    const eveLatest = capture("npm", ["view", "eve", "version"])?.trim();
+    if (eveLatest && versionLt(EVE_VERSION, eveLatest)) {
+        console.log(dim(`    note: eve@${eveLatest} exists upstream; ${EVE_VERSION} is the newest Kybernesis-certified version.`));
+    }
+    if (unresolved.size > 0) {
+        fail(`\nUpgrade planning failed for ${[...unresolved].sort().join(", ")}. ` +
+            `No manifest, dependency tree, or service state was changed.`);
         return;
     }
-    if (toUpgrade.length === 0) {
+    const targets = entries.map((entry) => ({
+        name: entry.name,
+        section: entry.section,
+        currentRange: entry.range,
+        installedVersion: installedVersions.get(entry.name),
+        targetVersion: targetVersions.get(entry.name),
+        installedEvePeer: installedPeers.get(entry.name),
+        targetEvePeer: targetPeers.get(entry.name),
+    }));
+    const eveTarget = targetVersions.get("eve");
+    const installedMajorMinor = eveInstalled ? majorMinor(eveInstalled) : null;
+    const targetMajorMinor = eveTarget ? majorMinor(eveTarget) : null;
+    if ((eveInstalled && !installedMajorMinor) || (eveTarget && !targetMajorMinor)) {
+        fail(`Cannot safely compare Eve versions ${JSON.stringify(eveInstalled)} and ${JSON.stringify(eveTarget)}.`);
+        return;
+    }
+    const eveChanged = Boolean(eveInstalled && eveTarget && versionLt(eveInstalled, eveTarget));
+    const cleanInstall = Boolean(eveChanged &&
+        installedMajorMinor &&
+        targetMajorMinor &&
+        (installedMajorMinor[0] !== targetMajorMinor[0] || installedMajorMinor[1] !== targetMajorMinor[1]));
+    const changed = [...new Set(targets
+            .filter((target) => target.installedVersion !== target.targetVersion && !(target.name === "eve" && versionLt(target.targetVersion, target.installedVersion)))
+            .map((target) => `${target.name}@${target.targetVersion}`))];
+    if (eveChanged && !(await approveEveChange(cwd, options.yes === true, Boolean(deps["@kybernesis/buzz"])))) {
+        process.exitCode = 1;
+        return;
+    }
+    repairLocalQueueTimeouts(cwd, deps);
+    if (changed.length === 0) {
         console.log(`\n${green("Everything is at latest certified versions.")}\n`);
-        // Still repair: being on the right versions is not the same as being set
-        // up. An agent can sit at latest for weeks with a capability switched off.
         repairBuzzSetup(cwd, deps);
         repairRemovedDefaultTools(cwd);
         repairSandboxCleanupHooks(cwd, deps);
         repairHostArtifacts(cwd, deps);
+        repairEvalCommand(cwd);
         repairManageRestart(cwd, deps);
         return;
     }
-    console.log(bold(`\nInstalling: ${toUpgrade.join(", ")}\n`));
-    /**
-     * One install, with peers relaxed. Every @kybernesis package peers on a
-     * narrow eve range, and eve moves with them: the installed set demands the
-     * old eve, the new set demands the new one, and npm's resolver refuses
-     * either order — eve first, packages first, or all at once — under strict
-     * peers (seen on Kyber moving 0.38 → 0.49: ERESOLVE all three ways). The
-     * set being installed is exactly the certified combination, so relaxing
-     * peer resolution for this one command changes nothing about what ends up
-     * on disk; the version check above is what guards correctness.
-     */
-    run("npm", ["install", ...toUpgrade, "--legacy-peer-deps"], { cwd });
-    /**
-     * Repairs run AFTER the install, not before.
-     *
-     * Both of these copy files out of packages that the install has just put
-     * there — a proxy script, a cron job, a CLI. Running them first meant looking
-     * for a file the older installed version did not ship: the repair found
-     * nothing, said nothing, and only worked on the NEXT upgrade. Which is a
-     * bug that hides itself, because by then it looks like it always worked.
-     */
+    console.log(bold(`\nInstalling: ${changed.join(", ")}\n`));
+    let stoppedBridge = null;
+    if (cleanInstall && deps["@kybernesis/buzz"]) {
+        const stopped = stopActiveBridge(cwd, buzzBridgeUnit(cwd));
+        if (stopped === false)
+            return;
+        stoppedBridge = stopped;
+    }
+    if (cleanInstall) {
+        rewriteManifest(cwd, pkg, targets);
+        try {
+            rmSync(join(cwd, "node_modules"), { recursive: true, force: true });
+            rmSync(join(cwd, "package-lock.json"), { force: true });
+        }
+        catch (error) {
+            fail(`Could not remove npm resolver state: ${error.message}`);
+            recoveryGuidance(targets, stoppedBridge ?? undefined);
+            return;
+        }
+    }
+    // Outside a clean install, eve goes in with --save-exact for the same
+    // reason rewriteManifest pins it: npm would save a caret by default.
+    const eveChange = changed.find((spec) => spec.startsWith("eve@"));
+    const others = changed.filter((spec) => spec !== eveChange);
+    const installArgs = cleanInstall ? ["install"] : ["install", ...others];
+    let installed = cleanInstall || others.length > 0 ? commandResult("npm", installArgs, cwd) : { status: 0, stdout: "", stderr: "" };
+    if (installed.status === 0 && !cleanInstall && eveChange) {
+        installed = commandResult("npm", ["install", "--save-exact", eveChange], cwd);
+    }
+    if (installed.status !== 0) {
+        const output = `${installed.stdout}\n${installed.stderr}`;
+        if (/ERESOLVE/i.test(output)) {
+            console.log(red("\nnpm reported ERESOLVE while installing the planned dependency set."));
+        }
+        else {
+            console.log(red("\nnpm install failed before the dependency tree could be verified."));
+        }
+        recoveryGuidance(targets, stoppedBridge ?? undefined);
+        process.exitCode = 1;
+        return;
+    }
+    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;
+    }
+    if (stoppedBridge && !startStoppedBridge(cwd, stoppedBridge))
+        return;
     repairBuzzSetup(cwd, deps);
     repairRemovedDefaultTools(cwd);
     repairSandboxCleanupHooks(cwd, deps);
     repairHostArtifacts(cwd, deps);
+    repairEvalCommand(cwd);
     repairManageRestart(cwd, deps);
     run("npm", ["run", "typecheck"], { cwd });
     if (eveChanged) {
-        // A framework bump must also pass discovery/compile, not just types.
         const infoOk = run("npx", ["eve", "info"], { cwd, allowFail: true, quiet: true });
         console.log(infoOk ? green("  ✓ eve discovery clean after framework upgrade") : red("  ✗ eve info failed after framework upgrade — inspect before going further"));
     }
-    if (skipEval) {
+    if (options.skipEval) {
         console.log(yellow("\nEval gate SKIPPED (--skip-eval). Run `npm run eval` before deploying.\n"));
         return;
     }

package/dist/util.d.ts

@@ -10,6 +10,10 @@ export declare function run(command: string, args: string[], options?: {
     cwd?: string;
     allowFail?: boolean;
     quiet?: boolean;
+    /** Extra environment for this one child; the parent's is inherited underneath. */
+    env?: Record<string, string>;
+    /** Kill the child after this many milliseconds. A command that cannot finish is a failure, not a wait. */
+    timeoutMs?: number;
 }): boolean;
 export declare function capture(command: string, args: string[], cwd?: string, extraEnv?: Record<string, string>): string | null;
 export declare function ask(question: string, fallback: string): Promise<string>;

package/dist/util.js

@@ -15,8 +15,12 @@ export function run(command, args, options) {
     const result = spawnSync(command, args, {
         cwd: options?.cwd,
         stdio: options?.quiet ? "pipe" : "inherit",
-        env: process.env,
+        env: { ...process.env, ...options?.env },
+        timeout: options?.timeoutMs,
     });
+    if (result.error && result.error.code === "ETIMEDOUT") {
+        console.error(red(`Command did not finish within ${Math.round((options?.timeoutMs ?? 0) / 60_000)} min and was stopped: ${command} ${args.join(" ")}`));
+    }
     const ok = result.status === 0;
     if (!ok && !options?.allowFail) {
         console.error(red(`Command failed: ${command} ${args.join(" ")}`));

package/package.json

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

package/skills/fde-engagement/references/playbook.md

@@ -1229,7 +1229,7 @@ to `acme-eval` and evals never write into a real brain:
 
 ```jsonc
 "scripts": {
-  "eval": "ARCANA_COMPANY_WORKSPACE=acme-eval ARCANA_DM_WORKSPACE=acme-eval ARCANA_FINANCE_WORKSPACE=acme-eval ARCANA_ENGINEERING_WORKSPACE=acme-eval eve eval",
+  "eval": "ARCANA_COMPANY_WORKSPACE=acme-eval ARCANA_DM_WORKSPACE=acme-eval ARCANA_FINANCE_WORKSPACE=acme-eval ARCANA_ENGINEERING_WORKSPACE=acme-eval kyb-eval",
   "typecheck": "tsc"
 }
 ```