@kybernesis/create 0.13.4 → 0.14.0

package/README.md

@@ -54,6 +54,12 @@ 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`.
 
+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
+command if non-interactive sudo is unavailable. A missing systemd unit is not
+created implicitly, and refreshing an existing unit does not restart the agent.
+
 ## Design notes
 
 - **Zero runtime dependencies** — node builtins only (`spawnSync`, `readline`,

package/dist/add.d.ts

@@ -15,3 +15,9 @@
  * already an agent, which is all "add" ever meant.
  */
 export declare function add(what: string | undefined, rest: string[]): Promise<void>;
+/**
+ * `kyb add memory` — recall before every turn, from Arcana, as an eve memory
+ * slot. Needs eve ≥ 0.49 (the memory API) and the Arcana key and workspace
+ * the agent already has; refuses to overwrite a slot someone has authored.
+ */
+export declare function addMemory(cwd?: string): void;

package/dist/add.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { bold, dim, green, red, run, yellow } from "./util.js";
-import { CHANNEL_KINDS, channelPlan } from "./templates.js";
+import { CHANNEL_KINDS, arcanaMemorySlotTs, channelPlan } from "./templates.js";
 /**
  * `kyb add channel <kind>` — put another surface on an agent that already exists.
  *
@@ -19,9 +19,12 @@ import { CHANNEL_KINDS, channelPlan } from "./templates.js";
  * already an agent, which is all "add" ever meant.
  */
 export async function add(what, rest) {
+    if (what === "memory")
+        return addMemory();
     if (what !== "channel") {
         console.error(red(`kyb add: don't know how to add "${what ?? ""}".`));
         console.log(dim(`  kyb add channel <${CHANNEL_KINDS.filter((k) => k !== "none").join("|")}>`));
+        console.log(dim(`  kyb add memory   ${dim("— an eve 0.49 memory slot backed by Arcana (recall before every turn)")}`));
         process.exitCode = 1;
         return;
     }
@@ -108,3 +111,31 @@ function appendEnvExample(dir, kind, lines) {
     writeFileSync(path, `${existing.replace(/\n*$/, "\n")}\n# ${kind}\n${fresh.join("\n")}\n`);
     return fresh.length;
 }
+/**
+ * `kyb add memory` — recall before every turn, from Arcana, as an eve memory
+ * slot. Needs eve ≥ 0.49 (the memory API) and the Arcana key and workspace
+ * the agent already has; refuses to overwrite a slot someone has authored.
+ */
+export function addMemory(cwd = resolve(process.cwd())) {
+    if (!existsSync(join(cwd, "package.json")) || !existsSync(join(cwd, "agent"))) {
+        console.error(red("kyb add memory: run this inside an agent directory."));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(bold("kyb add memory"));
+    if (existsSync(join(cwd, "agent/memory.ts"))) {
+        console.log(yellow("  agent/memory.ts exists (the single-slot form); eve allows one form or the other. Leaving it alone."));
+        return;
+    }
+    const target = join(cwd, "agent/memory/arcana.ts");
+    if (existsSync(target)) {
+        console.log(yellow("  agent/memory/arcana.ts already exists — leaving it alone."));
+        return;
+    }
+    const extensionMounted = existsSync(join(cwd, "agent/extensions/arcana.ts"));
+    mkdirSync(join(cwd, "agent/memory"), { recursive: true });
+    writeFileSync(target, arcanaMemorySlotTs({ extensionMounted }));
+    console.log(green("  + agent/memory/arcana.ts"));
+    console.log(dim(`    recall before every turn from ARCANA_COMPANY_WORKSPACE; capture off; ${extensionMounted ? "tools from the extension" : "remember/recall/search as memory__* tools"}`));
+    console.log(dim("    needs eve >= 0.49 and @kybernesis/arcana >= 0.4 — kyb upgrade carries both. Then: npx eve info"));
+}

package/dist/cli.js

@@ -194,6 +194,7 @@ ${dim("  npm i -g @kybernesis/create@latest")}
       --yes             ${dim("no prompts; take flags and defaults")}
   ${bold("kyb add channel <kind>")}
       ${dim("slack|imessage|telegram|discord|web — writes the channel, deps and env")}
+  ${bold("kyb add memory")}      ${dim("eve 0.49 memory slot backed by Arcana: recall before every turn")}
   ${bold("kyb doctor")}          preflight checks (keys, issuer, envs, discovery)
   ${bold("kyb skills")}          install/refresh the FDE skill suite for Claude Code
       --global          ${dim("install to ~/.claude/skills instead of this repo")}

package/dist/credential.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { upsertEnv } from "./envfile.js";
+import { systemdRestartCommand } from "./systemd.js";
 import { signIn } from "./register.js";
 import { bold, dim, green, red, yellow } from "./util.js";
 /**
@@ -135,14 +136,15 @@ export async function credential(options) {
         return;
     }
     console.log(dim("  Restarting so the agent reads it …"));
+    const restart = systemdRestartCommand(name);
     try {
-        execFileSync("ssh", [target, `cd ~/${name} && bash scripts/eve-server.sh restart >/dev/null 2>&1 &`], {
+        execFileSync("ssh", [target, `${restart} >/dev/null 2>&1 &`], {
             encoding: "utf8",
         });
-        console.log(green("  ✓ restart triggered"));
+        console.log(green("  ✓ systemd restart triggered"));
     }
     catch {
-        console.log(yellow(`  ! could not restart — run: ssh ${target} 'cd ~/${name} && bash scripts/eve-server.sh restart'`));
+        console.log(yellow(`  ! could not restart — run: ssh ${target} '${restart}'`));
     }
     console.log(dim(`\n  Check what it can now reach:\n` +
         `    ssh ${target} 'cd ~/${name} && CRED=$(grep -m1 "^KYBERNESIS_AGENT_CREDENTIAL=" .env.local | cut -d= -f2- | tr -d "\\"") && curl -s -H "authorization: Bearer $CRED" ${issuer}/api/agent/peers'\n`));

package/dist/docker-templates.d.ts

@@ -0,0 +1,46 @@
+export declare const DOCKER_TEMPLATE_MARKER_DIRECTORY = ".eve/sandbox-cache/docker/templates";
+export declare const DOCKER_TEMPLATE_IMAGE_REPOSITORY = "eve-sandbox-template";
+export interface DockerTemplateFileSystem {
+    exists(path: string): boolean;
+    readFile(path: string): string;
+    readDir(path: string): readonly {
+        name: string;
+        isDirectory: boolean;
+        isFile: boolean;
+    }[];
+    mtimeMs(path: string): number;
+}
+export interface DockerCommandResult {
+    ok: boolean;
+    stderr?: string;
+}
+export type DockerCommand = (command: string, args: readonly string[]) => DockerCommandResult | Promise<DockerCommandResult>;
+export interface DockerTemplateIssue {
+    kind: "missing-marker" | "missing-image" | "docker-error";
+    subject: string;
+    detail: string;
+}
+export type DockerTemplateInspection = {
+    status: "skipped";
+    sandboxes: readonly string[];
+    images: readonly string[];
+    issues: readonly [];
+} | {
+    status: "present";
+    sandboxes: readonly string[];
+    images: readonly string[];
+    issues: readonly [];
+} | {
+    status: "failed";
+    sandboxes: readonly string[];
+    images: readonly string[];
+    issues: readonly DockerTemplateIssue[];
+};
+export interface InspectDockerTemplatesOptions {
+    appDir: string;
+    fs?: DockerTemplateFileSystem;
+    runDocker?: DockerCommand;
+    dockerPath?: string;
+}
+export declare function discoverDockerTemplateSandboxes(appDir: string, fs?: DockerTemplateFileSystem): string[];
+export declare function inspectDockerTemplates(options: InspectDockerTemplatesOptions): Promise<DockerTemplateInspection>;

package/dist/docker-templates.js

@@ -0,0 +1,254 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+export const DOCKER_TEMPLATE_MARKER_DIRECTORY = ".eve/sandbox-cache/docker/templates";
+export const DOCKER_TEMPLATE_IMAGE_REPOSITORY = "eve-sandbox-template";
+const SANDBOX_EXTENSIONS = ["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs"];
+const REPAIR_GUIDANCE = "Run `eve build`, then restart so sandbox prewarm runs before serving traffic.";
+const nodeFileSystem = {
+    exists(path) {
+        try {
+            statSync(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    readFile: (path) => readFileSync(path, "utf8"),
+    readDir: (path) => readdirSync(path, { withFileTypes: true }).map((entry) => ({
+        name: entry.name,
+        isDirectory: entry.isDirectory(),
+        isFile: entry.isFile(),
+    })),
+    mtimeMs: (path) => statSync(path).mtimeMs,
+};
+function defaultDockerCommand(command, args) {
+    const result = spawnSync(command, [...args], { encoding: "utf8" });
+    return {
+        ok: result.status === 0,
+        stderr: [result.stderr, result.error?.message].filter(Boolean).join("\n").trim(),
+    };
+}
+function stripComments(source) {
+    let output = "";
+    let state = "code";
+    for (let index = 0; index < source.length; index += 1) {
+        const char = source[index];
+        const next = source[index + 1];
+        if (state === "line") {
+            if (char === "\n") {
+                output += char;
+                state = "code";
+            }
+            else
+                output += " ";
+            continue;
+        }
+        if (state === "block") {
+            if (char === "*" && next === "/") {
+                output += "  ";
+                index += 1;
+                state = "code";
+            }
+            else
+                output += char === "\n" ? "\n" : " ";
+            continue;
+        }
+        if (state === "code") {
+            if (char === "/" && next === "/") {
+                output += "  ";
+                index += 1;
+                state = "line";
+                continue;
+            }
+            if (char === "/" && next === "*") {
+                output += "  ";
+                index += 1;
+                state = "block";
+                continue;
+            }
+            if (char === "'")
+                state = "single";
+            else if (char === '"')
+                state = "double";
+            else if (char === "`")
+                state = "template";
+            output += char;
+            continue;
+        }
+        output += char;
+        if (char === "\\") {
+            if (next !== undefined) {
+                output += next;
+                index += 1;
+            }
+        }
+        else if ((state === "single" && char === "'") ||
+            (state === "double" && char === '"') ||
+            (state === "template" && char === "`")) {
+            state = "code";
+        }
+    }
+    return output;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function usesDockerBackend(source) {
+    const code = stripComments(source);
+    const calls = [];
+    for (const match of code.matchAll(/import\s*\{([^}]+)\}\s*from\s*["']eve\/sandbox\/docker["']/g)) {
+        for (const specifier of match[1].split(",")) {
+            const imported = /^\s*docker(?:\s+as\s+([A-Za-z_$][\w$]*))?\s*$/.exec(specifier);
+            if (imported)
+                calls.push(imported[1] ?? "docker");
+        }
+    }
+    for (const match of code.matchAll(/import\s*\*\s*as\s*([A-Za-z_$][\w$]*)\s*from\s*["']eve\/sandbox\/docker["']/g)) {
+        calls.push(`${match[1]}.docker`);
+    }
+    if (calls.length === 0)
+        return false;
+    const callPattern = calls.map(escapeRegExp).join("|");
+    if (new RegExp(`\\bbackend\\s*:\\s*(?:${callPattern})\\s*\\(`).test(code))
+        return true;
+    const dockerVariables = new Set();
+    for (const match of code.matchAll(new RegExp(`\\b(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*(?:${callPattern})\\s*\\(`, "g"))) {
+        dockerVariables.add(match[1]);
+    }
+    for (const variable of dockerVariables) {
+        const escaped = escapeRegExp(variable);
+        if (new RegExp(`\\bbackend\\s*:\\s*${escaped}\\b`).test(code))
+            return true;
+        if (new RegExp(`[{,]\\s*backend\\s*[,}]`).test(code) && variable === "backend")
+            return true;
+    }
+    return false;
+}
+function hasWorkspaceResources(fs, sandboxFile) {
+    const sandboxDir = dirname(sandboxFile);
+    if (basename(sandboxDir) !== "sandbox")
+        return false;
+    const workspace = join(sandboxDir, "workspace");
+    try {
+        return fs.readDir(workspace).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function requiresTemplate(fs, sandboxFile, source) {
+    return /\b(?:async\s+)?bootstrap\s*(?:\(|:)/.test(stripComments(source)) || hasWorkspaceResources(fs, sandboxFile);
+}
+function sandboxFiles(fs, agentDir) {
+    const files = [];
+    for (const extension of SANDBOX_EXTENSIONS) {
+        for (const path of [
+            join(agentDir, `sandbox.${extension}`),
+            join(agentDir, "sandbox", `sandbox.${extension}`),
+        ]) {
+            if (fs.exists(path))
+                files.push(path);
+        }
+    }
+    return files;
+}
+export function discoverDockerTemplateSandboxes(appDir, fs = nodeFileSystem) {
+    const appAgentDir = join(appDir, "agent");
+    const discovered = [];
+    const visitAgent = (agentDir) => {
+        for (const sandboxFile of sandboxFiles(fs, agentDir)) {
+            let source;
+            try {
+                source = fs.readFile(sandboxFile);
+            }
+            catch {
+                continue;
+            }
+            if (usesDockerBackend(source) && requiresTemplate(fs, sandboxFile, source)) {
+                discovered.push(relative(appDir, sandboxFile));
+            }
+        }
+        const subagentsDir = join(agentDir, "subagents");
+        let entries;
+        try {
+            entries = fs.readDir(subagentsDir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory)
+                visitAgent(join(subagentsDir, entry.name));
+        }
+    };
+    if (fs.exists(appAgentDir))
+        visitAgent(appAgentDir);
+    return discovered.sort();
+}
+function markerReference(fs, markerPath) {
+    try {
+        const content = fs.readFile(markerPath).trim();
+        if (content)
+            return content;
+    }
+    catch {
+        // Eve's marker basename is also the image tag, so unreadable content has a safe fallback.
+    }
+    return `${DOCKER_TEMPLATE_IMAGE_REPOSITORY}:${basename(markerPath)}`;
+}
+function isMissingImage(stderr) {
+    return /no such (?:image|object)/i.test(stderr);
+}
+export async function inspectDockerTemplates(options) {
+    const fs = options.fs ?? nodeFileSystem;
+    const sandboxes = discoverDockerTemplateSandboxes(options.appDir, fs);
+    if (sandboxes.length === 0)
+        return { status: "skipped", sandboxes, images: [], issues: [] };
+    const markerDir = join(options.appDir, DOCKER_TEMPLATE_MARKER_DIRECTORY);
+    let markers = [];
+    try {
+        markers = fs.readDir(markerDir)
+            .filter((entry) => entry.isFile)
+            .map((entry) => ({ path: join(markerDir, entry.name), mtimeMs: fs.mtimeMs(join(markerDir, entry.name)) }))
+            .sort((left, right) => right.mtimeMs - left.mtimeMs || left.path.localeCompare(right.path))
+            .slice(0, sandboxes.length);
+    }
+    catch {
+        markers = [];
+    }
+    const images = markers.map((marker) => markerReference(fs, marker.path));
+    const issues = [];
+    for (const sandbox of sandboxes.slice(markers.length)) {
+        issues.push({
+            kind: "missing-marker",
+            subject: sandbox,
+            detail: `No current Docker template marker exists for ${sandbox}. ${REPAIR_GUIDANCE}`,
+        });
+    }
+    const runDocker = options.runDocker ?? defaultDockerCommand;
+    const dockerPath = options.dockerPath ?? process.env.EVE_DOCKER_PATH ?? "docker";
+    for (const image of images) {
+        let result;
+        try {
+            result = await runDocker(dockerPath, ["image", "inspect", image]);
+        }
+        catch (error) {
+            result = { ok: false, stderr: error instanceof Error ? error.message : String(error) };
+        }
+        if (result.ok)
+            continue;
+        const stderr = result.stderr?.trim() || "Docker returned an unknown error";
+        issues.push({
+            kind: isMissingImage(stderr) ? "missing-image" : "docker-error",
+            subject: image,
+            detail: isMissingImage(stderr)
+                ? `Docker template image ${image} is missing. ${REPAIR_GUIDANCE}`
+                : `Could not inspect Docker template image ${image}: ${stderr}. ${REPAIR_GUIDANCE}`,
+        });
+    }
+    return issues.length === 0
+        ? { status: "present", sandboxes, images, issues: [] }
+        : { status: "failed", sandboxes, images, issues };
+}

package/dist/doctor.d.ts

@@ -1 +1,28 @@
+type Verdict = "pass" | "warn" | "fail";
+export interface Check {
+    verdict: Verdict;
+    label: string;
+    detail?: string;
+}
+/** The shape @kybernesis/exe's inspector returns; declared here so create keeps zero runtime deps. */
+export interface DockerTemplateInspection {
+    status: "skipped" | "present" | "failed";
+    sandboxes: readonly string[];
+    images: readonly string[];
+    issues: readonly {
+        kind: "missing-marker" | "missing-image" | "incomplete-set" | "docker-error";
+        subject: string;
+        detail: string;
+    }[];
+}
+export declare function dockerTemplateDoctorChecks(result: DockerTemplateInspection): Check[];
+/**
+ * The inspector lives in @kybernesis/exe, next to the runtime that owns the
+ * templates; create already resolves that package's scripts out of
+ * node_modules at runtime, and does the same here rather than carry a second
+ * copy of a heuristic this subtle. No exe package means no Docker host, and
+ * no check.
+ */
+export declare function inspectDockerTemplatesViaExe(cwd: string): Promise<DockerTemplateInspection | null>;
 export declare function doctor(): Promise<void>;
+export {};

package/dist/doctor.js

@@ -1,11 +1,49 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 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";
 const MARK = {
     pass: green("✓"),
     warn: yellow("!"),
     fail: red("✗"),
 };
+export function dockerTemplateDoctorChecks(result) {
+    if (result.status === "skipped")
+        return [];
+    if (result.status === "present") {
+        return [{
+                verdict: "pass",
+                label: `Docker sandbox templates provisioned (${result.images.length}/${result.sandboxes.length})`,
+            }];
+    }
+    return result.issues.map((issue) => ({
+        // A set the newest build did not fully cover still serves: the uncovered
+        // scope builds on first use. A current marker with no image, or a daemon
+        // that will not answer, is a fault.
+        verdict: issue.kind === "incomplete-set" ? "warn" : "fail",
+        label: issue.kind === "missing-marker"
+            ? `Docker sandbox template unresolved: ${issue.subject}`
+            : issue.kind === "incomplete-set"
+                ? `Docker sandbox templates incomplete: ${issue.subject}`
+                : `Docker sandbox template unavailable: ${issue.subject}`,
+        detail: issue.detail,
+    }));
+}
+/**
+ * The inspector lives in @kybernesis/exe, next to the runtime that owns the
+ * templates; create already resolves that package's scripts out of
+ * node_modules at runtime, and does the same here rather than carry a second
+ * copy of a heuristic this subtle. No exe package means no Docker host, and
+ * no check.
+ */
+export async function inspectDockerTemplatesViaExe(cwd) {
+    const module = join(cwd, "node_modules/@kybernesis/exe/dist/docker-templates.js");
+    if (!existsSync(module))
+        return null;
+    const { inspectDockerTemplates } = (await import(pathToFileURL(module).href));
+    return inspectDockerTemplates({ appDir: cwd });
+}
 async function head(url, headers) {
     try {
         const res = await fetch(url, { headers, signal: AbortSignal.timeout(6000) });
@@ -17,6 +55,7 @@ async function head(url, headers) {
 }
 export async function doctor() {
     const cwd = process.cwd();
+    const installedAgentService = findMatchingAgentServiceUnit(cwd);
     const checks = [];
     const add = (verdict, label, detail) => checks.push({ verdict, label, detail });
     // ── project shape ──────────────────────────────────────────────────────
@@ -209,6 +248,10 @@ export async function doctor() {
     const selfHosted = Boolean(deps["@kybernesis/exe"]) ||
         existsSync(join(cwd, "agent/sandbox/sandbox.ts")) &&
             readFileSync(join(cwd, "agent/sandbox/sandbox.ts"), "utf8").includes("docker(");
+    const templateInspection = await inspectDockerTemplatesViaExe(cwd);
+    for (const check of templateInspection ? dockerTemplateDoctorChecks(templateInspection) : []) {
+        add(check.verdict, check.label, check.detail);
+    }
     if (selfHosted) {
         // Vercel Connect needs Vercel OIDC — it CANNOT work off-Vercel, for Slack,
         // the Vercel MCP connection, or anything else. Every such connection has to
@@ -243,11 +286,21 @@ export async function doctor() {
          * operator that warnings here are decoration.
          */
         const supervisor = join(cwd, "scripts/eve-server.sh");
-        if (existsSync(supervisor)) {
-            add("pass", "scripts/eve-server.sh present (exports .env.local, starts via the eve CLI)");
+        if (installedAgentService) {
+            if (installedAgentService.contents.includes("ExecStartPre=/bin/bash -lc 'set -a && . ./.env.local && set +a && npx eve build'")) {
+                add("pass", `systemd ${installedAgentService.values.name}-agent builds before every start`);
+            }
+            else {
+                add("fail", `systemd ${installedAgentService.values.name}-agent has no build-before-start gate`, "run kyb upgrade to refresh an unchanged package unit; if customized, move overrides to `sudo systemctl edit " +
+                    `${installedAgentService.values.name}-agent` +
+                    "` and follow the exact repair command it prints");
+            }
+        }
+        else if (existsSync(supervisor)) {
+            add("pass", "scripts/eve-server.sh present (exports .env.local, builds if stale, starts via the eve CLI)");
         }
         else {
-            add("warn", "self-hosted: export .env.local into the server process", "eve start does NOT read it; use the supervision script from @kybernesis/exe (scripts/eve-server.sh)");
+            add("warn", "self-hosted: export .env.local into the server process", "eve start does NOT read it; install systemd with node_modules/@kybernesis/exe/scripts/install-service.sh");
             add("warn", "self-hosted: start via `npx eve start`, not `node .output/server/index.mjs`", "sandbox templates are prewarmed by the CLI; starting the server directly skips prewarm and every sandbox tool fails with SandboxTemplateNotProvisionedError");
         }
         /**
@@ -287,7 +340,7 @@ 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 images and abandoned session containers accumulate by the gigabyte; `kyb upgrade` installs /etc/cron.daily/kyb-docker-prune");
+                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");
@@ -376,13 +429,10 @@ export async function doctor() {
         // remaining requirement (a writable working copy) is a property of the
         // host, and on a read-only bundle the routes refuse with that reason.
         const manageFile = join(cwd, "agent/channels/kyb.ts");
-        const restartWired = existsSync(manageFile) && /^\s*restartCommand\s*:/m.test(readFileSync(manageFile, "utf8"));
-        if (restartWired) {
-            add("pass", "management routes can restart the agent after an install");
-        }
-        else {
-            add("warn", "management routes have no restartCommand", "installing edits this repo and rebuilds; without a restart the response says a restart is still required. Set restartCommand in agent/channels/kyb.ts (self-hosted: \"bash scripts/eve-server.sh restart\")");
-        }
+        const manageSource = existsSync(manageFile) ? readFileSync(manageFile, "utf8") : "";
+        const restartCommand = /\brestartCommand\s*:\s*["'`]([^"'`]+)["'`]/m.exec(manageSource)?.[1];
+        const diagnosis = diagnoseManageRestart(installedAgentService?.values.name ?? null, restartCommand);
+        add(diagnosis.verdict, diagnosis.label, diagnosis.detail);
     }
     // ── engineer subagent (build capability scoped to a subagent) ──────────
     const builderDir = join(cwd, "agent/subagents/builder");

package/dist/host-artifacts.d.ts

@@ -0,0 +1,24 @@
+export type HostArtifactInspection = {
+    state: "missing";
+} | {
+    state: "current";
+} | {
+    state: "drifted";
+    differences: Array<"content" | "mode">;
+} | {
+    state: "unreadable";
+    error: Error;
+};
+export type HostArtifactReconcileResult = "missing" | "current" | "updated" | "failed" | "unreadable";
+export interface HostArtifactOptions {
+    targetPath: string;
+    desiredContent: Uint8Array;
+    expectedMode: number;
+    installIfMissing: boolean;
+    owner: string;
+    update: () => boolean;
+    manualCommand: string;
+    log?: (message: string) => void;
+}
+export declare function inspectHostArtifact(targetPath: string, desiredContent: Uint8Array, expectedMode: number): HostArtifactInspection;
+export declare function reconcileHostArtifact(options: HostArtifactOptions): HostArtifactReconcileResult;

package/dist/host-artifacts.js

@@ -0,0 +1,57 @@
+import { readFileSync, statSync } from "node:fs";
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+export function inspectHostArtifact(targetPath, desiredContent, expectedMode) {
+    let stat;
+    try {
+        stat = statSync(targetPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { state: "missing" };
+        return { state: "unreadable", error: asError(error) };
+    }
+    let installed;
+    try {
+        installed = readFileSync(targetPath);
+    }
+    catch (error) {
+        return { state: "unreadable", error: asError(error) };
+    }
+    const differences = [];
+    if (!installed.equals(Buffer.from(desiredContent)))
+        differences.push("content");
+    if ((stat.mode & 0o777) !== expectedMode)
+        differences.push("mode");
+    return differences.length === 0 ? { state: "current" } : { state: "drifted", differences };
+}
+export function reconcileHostArtifact(options) {
+    const log = options.log ?? console.log;
+    const before = inspectHostArtifact(options.targetPath, options.desiredContent, options.expectedMode);
+    if (before.state === "current")
+        return "current";
+    if (before.state === "missing" && !options.installIfMissing)
+        return "missing";
+    if (before.state === "unreadable") {
+        log(`  ! could not verify ${options.targetPath} against ${options.owner}: ${before.error.message}\n` +
+            `    Check it manually. To restore the package-owned file, run:\n` +
+            `    ${options.manualCommand}`);
+        return "unreadable";
+    }
+    if (before.state === "drifted") {
+        log(`  ! ${options.targetPath} differs from ${options.owner} ` +
+            `(${before.differences.join(" and ")}); replacing the installed file.`);
+    }
+    if (!options.update()) {
+        log(`  ! could not update ${options.targetPath}. Run:\n    ${options.manualCommand}`);
+        return "failed";
+    }
+    const after = inspectHostArtifact(options.targetPath, options.desiredContent, options.expectedMode);
+    if (after.state !== "current") {
+        log(`  ! ${options.targetPath} is still not current after the update. Run:\n    ${options.manualCommand}`);
+        return "failed";
+    }
+    log(`  + ${before.state === "missing" ? "installed" : "refreshed"} ${options.targetPath} from ${options.owner}`);
+    return "updated";
+}