@kybernesis/create 0.14.2 → 0.14.5

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/agent-limits.d.ts

@@ -0,0 +1,30 @@
+/** Eve 0.49's root default when the compiled config omits the policy. */
+export declare const CERTIFIED_INHERITED_MAX_INPUT_TOKENS_PER_SESSION = 40000000;
+export type AgentInputLimit = {
+    kind: "explicit-numeric";
+    value: number;
+} | {
+    kind: "explicit-uncapped";
+} | {
+    kind: "inherited";
+    value: typeof CERTIFIED_INHERITED_MAX_INPUT_TOKENS_PER_SESSION;
+} | {
+    kind: "unresolved";
+    reason: string;
+};
+export interface EveInfoInspection {
+    diagnostics: {
+        errors: number;
+        warnings: number;
+    } | null;
+    status: string | null;
+    limit: AgentInputLimit;
+}
+/**
+ * Read the effective root policy from Eve's compiled artifact, never from
+ * authored TypeScript. The 40M fallback is certified only when that artifact
+ * truly omits maxInputTokensPerSession.
+ */
+export declare function parseEveInfoInspection(output: string, readText?: (path: string) => string): EveInfoInspection;
+/** Compile once through Eve's structured info contract and inspect its artifact. */
+export declare function inspectEveAgent(cwd: string, env?: Record<string, string>): EveInfoInspection | null;

package/dist/agent-limits.js

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import { capture } from "./util.js";
+/** Eve 0.49's root default when the compiled config omits the policy. */
+export const CERTIFIED_INHERITED_MAX_INPUT_TOKENS_PER_SESSION = 40_000_000;
+/**
+ * Read the effective root policy from Eve's compiled artifact, never from
+ * authored TypeScript. The 40M fallback is certified only when that artifact
+ * truly omits maxInputTokensPerSession.
+ */
+export function parseEveInfoInspection(output, readText = (path) => readFileSync(path, "utf8")) {
+    let info;
+    try {
+        info = JSON.parse(output);
+    }
+    catch (error) {
+        return unresolved(`eve info --json was not valid JSON: ${error.message}`);
+    }
+    const diagnostics = parseDiagnostics(info.diagnostics);
+    const status = typeof info.status === "string" ? info.status : null;
+    const manifestPath = info.artifacts && typeof info.artifacts.compiledManifest === "string"
+        ? info.artifacts.compiledManifest
+        : null;
+    if (!manifestPath) {
+        return { diagnostics, status, limit: { kind: "unresolved", reason: "compiled manifest path was unavailable" } };
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(readText(manifestPath));
+    }
+    catch (error) {
+        return {
+            diagnostics,
+            status,
+            limit: { kind: "unresolved", reason: `compiled manifest could not be read: ${error.message}` },
+        };
+    }
+    if (!isRecord(manifest) || !isRecord(manifest.config)) {
+        return { diagnostics, status, limit: { kind: "unresolved", reason: "compiled root config was unavailable" } };
+    }
+    const limits = manifest.config.limits;
+    if (limits === undefined) {
+        return inherited(diagnostics, status);
+    }
+    if (!isRecord(limits)) {
+        return { diagnostics, status, limit: { kind: "unresolved", reason: "compiled root limits were malformed" } };
+    }
+    if (!Object.hasOwn(limits, "maxInputTokensPerSession")) {
+        return inherited(diagnostics, status);
+    }
+    const value = limits.maxInputTokensPerSession;
+    if (value === false)
+        return { diagnostics, status, limit: { kind: "explicit-uncapped" } };
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+        return { diagnostics, status, limit: { kind: "explicit-numeric", value } };
+    }
+    return {
+        diagnostics,
+        status,
+        limit: { kind: "unresolved", reason: "compiled maxInputTokensPerSession was neither a positive number nor false" },
+    };
+}
+/** Compile once through Eve's structured info contract and inspect its artifact. */
+export function inspectEveAgent(cwd, env) {
+    const output = capture("npx", ["eve", "info", "--json"], cwd, env);
+    return output === null ? null : parseEveInfoInspection(output);
+}
+function parseDiagnostics(value) {
+    if (!isRecord(value))
+        return null;
+    return typeof value.errors === "number" && typeof value.warnings === "number"
+        ? { errors: value.errors, warnings: value.warnings }
+        : null;
+}
+function inherited(diagnostics, status) {
+    return {
+        diagnostics,
+        status,
+        limit: { kind: "inherited", value: CERTIFIED_INHERITED_MAX_INPUT_TOKENS_PER_SESSION },
+    };
+}
+function unresolved(reason) {
+    return { diagnostics: null, status: null, limit: { kind: "unresolved", reason } };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -1,3 +1,4 @@
+import { type AgentInputLimit } from "./agent-limits.js";
 type Verdict = "pass" | "warn" | "fail";
 export interface Check {
     verdict: Verdict;
@@ -16,6 +17,7 @@ export interface DockerTemplateInspection {
     }[];
 }
 export declare function dockerTemplateDoctorChecks(result: DockerTemplateInspection): Check[];
+export declare function agentInputLimitDoctorCheck(limit: AgentInputLimit): 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

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { bold, capture, dim, green, parseEnv, red, yellow } from "./util.js";
 import { diagnoseManageRestart, findMatchingAgentServiceUnit } from "./systemd.js";
+import { inspectEveAgent } from "./agent-limits.js";
 const MARK = {
     pass: green("✓"),
     warn: yellow("!"),
@@ -30,6 +31,26 @@ export function dockerTemplateDoctorChecks(result) {
         detail: issue.detail,
     }));
 }
+export function agentInputLimitDoctorCheck(limit) {
+    switch (limit.kind) {
+        case "explicit-numeric":
+            return { verdict: "pass", label: `Eve max input tokens/session: ${limit.value.toLocaleString("en-US")} (explicit)` };
+        case "explicit-uncapped":
+            return { verdict: "pass", label: "Eve max input tokens/session: uncapped (explicit)" };
+        case "inherited":
+            return {
+                verdict: "warn",
+                label: `Eve max input tokens/session: ${limit.value.toLocaleString("en-US")} (inherited default)`,
+                detail: "set limits.maxInputTokensPerSession explicitly in the root agent; use false only when the host policy intentionally permits an uncapped session",
+            };
+        case "unresolved":
+            return {
+                verdict: "warn",
+                label: "Eve max input tokens/session: unresolved",
+                detail: limit.reason,
+            };
+    }
+}
 /**
  * The inspector lives in @kybernesis/exe, next to the runtime that owns the
  * templates; create already resolves that package's scripts out of
@@ -481,16 +502,19 @@ export async function doctor() {
      * `env` here is the same merged view every other check reads: .env.local
      * underneath, the real environment on top.
      */
-    const info = capture("npx", ["eve", "info"], cwd, env);
+    const info = inspectEveAgent(cwd, env);
     if (info === null) {
-        add("fail", "eve info failed", "run: set -a && . ./.env.local && set +a && npx eve info — the agent's own error is in that output");
+        add("fail", "eve info failed", "run: set -a && . ./.env.local && set +a && npx eve info --json — the agent's own error is in that output");
+        add("warn", "Eve max input tokens/session: unresolved", "eve info failed before the compiled root policy could be inspected");
     }
     else {
-        const diag = /Diagnostics\s+(\d+) errors?, (\d+) warnings?/.exec(info);
-        if (diag && diag[1] === "0")
-            add("pass", `eve discovery clean (${diag[2]} warnings)`);
+        const diag = info.diagnostics;
+        if (diag && diag.errors === 0)
+            add("pass", `eve discovery clean (${diag.warnings} warnings)`);
         else
-            add("fail", `eve discovery: ${diag ? `${diag[1]} errors` : "unparsed"}`, "npx eve info");
+            add("fail", `eve discovery: ${diag ? `${diag.errors} errors` : "unparsed"}`, "npx eve info --json");
+        const limitCheck = agentInputLimitDoctorCheck(info.limit);
+        add(limitCheck.verdict, limitCheck.label, limitCheck.detail);
     }
     const portBusy = capture("lsof", ["-ti", ":2000"]);
     if (portBusy && portBusy.trim())

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",
@@ -366,6 +366,8 @@ import { exeModel } from "@kybernesis/exe";
 export default defineAgent({
   model: exeModel({ model: process.env.EXE_MODEL ?? ${JSON.stringify(model)}, createOpenAI }),
   modelContextWindowTokens: 200_000,
+  // This long-lived self-hosted process has no metered platform session ceiling.
+  limits: { maxInputTokensPerSession: false },
 });
 `;
     }

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

package/dist/upgrade.js

@@ -1,30 +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, red, run, yellow } from "./util.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 { EVE_VERSION, bold, capture, dim, green, parseEnv, red, run, yellow } from "./util.js";
+import { inspectEveAgent } from "./agent-limits.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);
@@ -61,6 +45,32 @@ function warnIfStale() {
         `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":
+            return `Eve max input tokens/session: ${limit.value.toLocaleString("en-US")} (explicit; unchanged)`;
+        case "explicit-uncapped":
+            return "Eve max input tokens/session: uncapped (explicit; unchanged)";
+        case "inherited":
+            return `Eve max input tokens/session: ${limit.value.toLocaleString("en-US")} inherited — set limits.maxInputTokensPerSession explicitly in agent/agent.ts; upgrade will not rewrite authored source`;
+        case "unresolved":
+            return `Eve max input tokens/session: unresolved (${limit.reason}); authored source was not changed`;
+    }
+}
+function reportAgentInputLimit(cwd) {
+    const envPath = join(cwd, ".env.local");
+    const env = {
+        ...(existsSync(envPath) ? parseEnv(readFileSync(envPath, "utf8")) : {}),
+        ...process.env,
+    };
+    const inspection = inspectEveAgent(cwd, env);
+    const limit = inspection?.limit ?? {
+        kind: "unresolved",
+        reason: "eve info --json failed",
+    };
+    const marker = limit.kind === "inherited" || limit.kind === "unresolved" ? yellow("!") : green("✓");
+    console.log(`  ${marker} ${agentInputLimitUpgradeMessage(limit)}`);
+}
 /**
  * Raise the local queue's delivery timeouts on an agent that already exists.
  *
@@ -303,111 +313,319 @@ 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];
+        section[target.name] = `^${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/* and eve range in package.json is the resolved ^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();
-    // 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])
+    reportAgentInputLimit(cwd);
+    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;
+        }
+    }
+    const installArgs = cleanInstall ? ["install"] : ["install", ...changed];
+    const installed = commandResult("npm", installArgs, 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.14.2",
-  "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
+  "version": "0.14.5",
+  "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent \u2014 plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",
   "homepage": "https://kybernesis.ai",

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"
 }
 ```