@kybernesis/create 0.14.6 → 0.14.8

package/README.md

@@ -30,8 +30,45 @@ Scaffolds the full Kybernesis stack:
    the Slack connector browser flow, control-plane registration + grants,
    eval → deploy → the revoke demo)
 
-Non-interactive (CI / agents): pipe stdin from `/dev/null` and pass the name —
-all prompts take defaults (departments: finance, marketing, engineering).
+Non-interactive (CI / agents): pass the name and `--yes`; omitted options use
+the documented defaults.
+
+### Model reach
+
+The default route is unchanged: Vercel scaffolds author an AI Gateway model id,
+and exe scaffolds use `exeModel()` plus `EXE_MODEL` for the VM's attached LLM
+integration.
+
+To bill model calls to a Claude subscription instead of the exe gateway:
+
+```bash
+kyb init acme-atlas --host=exe --model-reach=claude-sub --yes
+# Factory/noninteractive equivalent:
+KYB_MODEL_REACH=claude-sub kyb init acme-atlas --host=exe --yes
+```
+
+An explicit `--model-reach` takes precedence over `KYB_MODEL_REACH`. The
+`claude-sub` reach is exe-only because its OAuth proxy must run on the same host.
+It currently supports the bare Anthropic id `claude-opus-5` only (the gateway
+form `anthropic/claude-opus-5` is normalized); other model ids are rejected
+because `@kybernesis/exe` certifies its exported context-window constant for that
+model only.
+
+The generated root and all generated model-bearing subagents use
+`createAnthropic` from `@ai-sdk/anthropic` with `claudeSubscription()` and
+`CLAUDE_SUBSCRIPTION_CONTEXT_WINDOW` from `@kybernesis/exe`. This is Eve 0.49's
+documented provider-authored AI SDK `LanguageModel` shape (`node_modules/eve/docs/agent-config.md`),
+not a gateway string. Subscription scaffolds do not write or read `EXE_MODEL`.
+On the host, stand up and authenticate the loopback-only proxy:
+
+```bash
+bash scripts/claude-subscription.sh up
+bash scripts/claude-subscription.sh login
+bash scripts/claude-subscription.sh status
+```
+
+The concrete provider and proxy contract is documented in
+`packages/exe/src/claude.ts` and `packages/exe/README.md`.
 
 ## `kyb doctor`
 
@@ -42,6 +79,7 @@ Run inside an agent project. Checks, with pass/warn/fail per line:
   (200 / wrong-key 403 / missing-workspace 404, each with the fix)
 - control-plane issuer JWKS reachable; `KYBERNESIS_AGENT` set
 - Slack connector UID present
+- model reach (`claude-sub`, `exe`, gateway, direct provider, or unresolved)
 - `eve info` discovery clean
 - port 2000 free (a running dev server makes `eve eval` exit early)
 

package/dist/agent-limits.d.ts

@@ -1,3 +1,4 @@
+import type { CompiledModelRouting } from "./model-reach.js";
 /** 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 = {
@@ -19,6 +20,7 @@ export interface EveInfoInspection {
     } | null;
     status: string | null;
     limit: AgentInputLimit;
+    modelRouting: CompiledModelRouting;
 }
 /**
  * Read the effective root policy from Eve's compiled artifact, never from

package/dist/agent-limits.js

@@ -21,7 +21,12 @@ export function parseEveInfoInspection(output, readText = (path) => readFileSync
         ? info.artifacts.compiledManifest
         : null;
     if (!manifestPath) {
-        return { diagnostics, status, limit: { kind: "unresolved", reason: "compiled manifest path was unavailable" } };
+        return {
+            diagnostics,
+            status,
+            limit: { kind: "unresolved", reason: "compiled manifest path was unavailable" },
+            modelRouting: { kind: "unresolved", reason: "compiled manifest path was unavailable" },
+        };
     }
     let manifest;
     try {
@@ -32,31 +37,39 @@ export function parseEveInfoInspection(output, readText = (path) => readFileSync
             diagnostics,
             status,
             limit: { kind: "unresolved", reason: `compiled manifest could not be read: ${error.message}` },
+            modelRouting: { 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" } };
+        return {
+            diagnostics,
+            status,
+            limit: { kind: "unresolved", reason: "compiled root config was unavailable" },
+            modelRouting: { kind: "unresolved", reason: "compiled root config was unavailable" },
+        };
     }
+    const modelRouting = parseModelRouting(manifest.config);
     const limits = manifest.config.limits;
     if (limits === undefined) {
-        return inherited(diagnostics, status);
+        return inherited(diagnostics, status, modelRouting);
     }
     if (!isRecord(limits)) {
-        return { diagnostics, status, limit: { kind: "unresolved", reason: "compiled root limits were malformed" } };
+        return { diagnostics, status, limit: { kind: "unresolved", reason: "compiled root limits were malformed" }, modelRouting };
     }
     if (!Object.hasOwn(limits, "maxInputTokensPerSession")) {
-        return inherited(diagnostics, status);
+        return inherited(diagnostics, status, modelRouting);
     }
     const value = limits.maxInputTokensPerSession;
     if (value === false)
-        return { diagnostics, status, limit: { kind: "explicit-uncapped" } };
+        return { diagnostics, status, limit: { kind: "explicit-uncapped" }, modelRouting };
     if (typeof value === "number" && Number.isFinite(value) && value > 0) {
-        return { diagnostics, status, limit: { kind: "explicit-numeric", value } };
+        return { diagnostics, status, limit: { kind: "explicit-numeric", value }, modelRouting };
     }
     return {
         diagnostics,
         status,
         limit: { kind: "unresolved", reason: "compiled maxInputTokensPerSession was neither a positive number nor false" },
+        modelRouting,
     };
 }
 /** Compile once through Eve's structured info contract and inspect its artifact. */
@@ -71,15 +84,40 @@ function parseDiagnostics(value) {
         ? { errors: value.errors, warnings: value.warnings }
         : null;
 }
-function inherited(diagnostics, status) {
+function inherited(diagnostics, status, modelRouting) {
     return {
         diagnostics,
         status,
         limit: { kind: "inherited", value: CERTIFIED_INHERITED_MAX_INPUT_TOKENS_PER_SESSION },
+        modelRouting,
     };
 }
+function parseModelRouting(config) {
+    if (config.dynamicModel !== undefined) {
+        return { kind: "unresolved", reason: "the root uses dynamic model selection" };
+    }
+    const model = config.model;
+    if (!isRecord(model) || !isRecord(model.routing)) {
+        return { kind: "unresolved", reason: "compiled model routing was unavailable" };
+    }
+    const routing = model.routing;
+    if (routing.kind === "gateway")
+        return { kind: "gateway" };
+    if (routing.kind === "external") {
+        return {
+            kind: "external",
+            ...(typeof routing.provider === "string" ? { provider: routing.provider } : {}),
+        };
+    }
+    return { kind: "unresolved", reason: "compiled model routing was unrecognized" };
+}
 function unresolved(reason) {
-    return { diagnostics: null, status: null, limit: { kind: "unresolved", reason } };
+    return {
+        diagnostics: null,
+        status: null,
+        limit: { kind: "unresolved", reason },
+        modelRouting: { kind: "unresolved", reason },
+    };
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/cli.js

@@ -60,6 +60,7 @@ function initOptions(rest) {
         channel: flag(rest, "channel"),
         host: flag(rest, "host"),
         model: flag(rest, "model"),
+        modelReach: flag(rest, "model-reach"),
         subagents: subs === undefined ? undefined : subs.split(',').map((s) => s.trim()).filter(Boolean),
         yes: rest.includes('--yes') || rest.includes('-y'),
     };
@@ -87,6 +88,20 @@ const COMMANDS = {
 function usage(command) {
     if (command && COMMANDS[command]) {
         console.log(`\n  ${bold(`kyb ${command}`)} — ${COMMANDS[command]}\n`);
+        if (command === "init") {
+            console.log(`  ${bold("kyb init [name]")} [options]
+      --channel=<kind>      ${dim("none|slack|imessage|telegram|discord|web")}
+      --host=<kind>         ${dim("vercel|exe (default: vercel)")}
+      --model=<id>          ${dim("gateway id; claude-sub requires bare claude-opus-5")}
+      --model-reach=<reach> ${dim("claude-sub (exe only; default: host route)")}
+      --subagents=a,b       ${dim("department subagents")}
+      --engineer            ${dim("add the engineer layer")}
+      --studio              ${dim("wire KYBER Studio local/manage routes")}
+      --yes, -y             ${dim("no prompts")}
+
+  ${dim("Factory env: KYB_MODEL_REACH=claude-sub (the CLI flag takes precedence).")}
+  ${dim("Claude subscription reach uses the loopback OAuth proxy; it does not read EXE_MODEL.")}\n`);
+        }
         return;
     }
     console.log(`\n  ${bold("kyb")} ${dim(VERSION)} — the Kybernesis agent CLI\n`);
@@ -192,7 +207,8 @@ ${dim("  npm i -g @kybernesis/create@latest")}
       --channel=<kind>  ${dim("none|slack|imessage|telegram|discord|web  (default: none)")}
       --host=<kind>     ${dim("vercel|exe                                (default: vercel)")}
       --subagents=a,b   ${dim("department subagents                      (default: none)")}
-      --model=<id>      ${dim("provider/model-id                         (default: sonnet 5)")}
+      --model=<id>      ${dim("provider/model-id; bare claude-opus-5 for claude-sub")}
+      --model-reach=<r> ${dim("claude-sub (exe only); env: KYB_MODEL_REACH")}
       --engineer        ${dim("add the engineer layer: workshop sandbox + vision dev loop")}
       --studio          ${dim("wire for KYBER Studio: local execution + management routes")}
       --yes             ${dim("no prompts; take flags and defaults")}

package/dist/deploy.js

@@ -1,4 +1,5 @@
 import { execFileSync, spawnSync } from "node:child_process";
+import { TEMPLATE_CONTAINER_PROBE, assessRestart, parseTemplateContainers } from "./sandbox-orphans.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { upsertEnv } from "./envfile.js";
@@ -239,6 +240,14 @@ export async function deploy(options) {
         '  SCRIPT="scripts/eve-server.sh"',
         "fi",
         'if [ -z "$SCRIPT" ]; then echo "FAILED: no restart script on the host"; exit 1; fi',
+        // An orphaned sandbox template container (a start killed mid-build; only
+        // `sleep` inside) makes every eve start hang forever. The packaged start
+        // script clears it too, but a host still running its own older copy
+        // would not, so the deploy does it first and says so (KYB-531).
+        "for c in $(command -v docker >/dev/null 2>&1 && docker ps --filter name=eve-sbx-tpl- --format '{{.Names}}' 2>/dev/null); do",
+        "  live=$(docker top \"$c\" 2>/dev/null | tail -n +2 | awk '{print $8}' | grep -vc '^sleep$')",
+        '  if [ "${live:-0}" = "0" ]; then echo "removing orphaned sandbox template container $c (only sleep inside; it would block every start)"; docker rm -f "$c" >/dev/null 2>&1 || true; fi',
+        "done",
         'echo "using $SCRIPT"',
         'setsid nohup bash "$SCRIPT" > /tmp/kyb-deploy.log 2>&1 < /dev/null &',
         "sleep 2",
@@ -266,23 +275,45 @@ export async function deploy(options) {
     let last = "";
     let seen = "";
     let lastChange = Date.now();
+    let lastBuildingNote = 0;
+    let stuck = null;
     while (Date.now() - startedAt < CEILING_MS) {
-        const out = execFileSync("ssh", [target, `tail -40 /tmp/kyb-deploy.log 2>/dev/null || true`], {
-            encoding: "utf8",
-        });
-        last = out;
-        if (out !== seen) {
-            for (const line of out.split("\n")) {
-                if (line && !seen.includes(line) && /npm|install|build|SOURCE IS NEWER|waiting|pid=|health:|FAILED/i.test(line)) {
+        // Two witnesses: the log, and the sandbox template containers. A cold
+        // template build is silent in the log for longer than the quiet limit,
+        // and judging it on the log alone is how a fine build got killed (KYB-531).
+        const out = execFileSync("ssh", [target, `tail -40 /tmp/kyb-deploy.log 2>/dev/null || true; echo __TEMPLATES__; ${TEMPLATE_CONTAINER_PROBE}`], { encoding: "utf8" });
+        const [logPart, probePart = ""] = out.split("__TEMPLATES__");
+        last = logPart;
+        if (logPart !== seen) {
+            for (const line of logPart.split("\n")) {
+                if (line && !seen.includes(line) && /npm|install|build|SOURCE IS NEWER|waiting|pid=|health:|FAILED|template|removing/i.test(line)) {
                     console.log(dim(`    ${line.trim().slice(0, 120)}`));
                 }
             }
-            seen = out;
+            seen = logPart;
+            lastChange = Date.now();
+        }
+        const verdict = assessRestart({
+            log: logPart,
+            templates: parseTemplateContainers(probePart),
+            quietMs: Date.now() - lastChange,
+            quietLimitMs: QUIET_LIMIT_MS,
+        });
+        if (verdict.state === "healthy" || verdict.state === "failed")
+            break;
+        if (verdict.state === "building") {
             lastChange = Date.now();
+            if (Date.now() - lastBuildingNote > 60_000) {
+                console.log(dim(`    still building the sandbox template (${Math.round((Date.now() - startedAt) / 60_000)} min): ${verdict.detail}`));
+                lastBuildingNote = Date.now();
+            }
         }
-        if (/health:|FAILED/.test(out))
+        else if (verdict.state === "orphaned") {
+            stuck = verdict.detail ?? null;
+            console.log(yellow(`\n  ! an orphaned sandbox template container is blocking the start: ${stuck}`));
             break;
-        if (Date.now() - lastChange > QUIET_LIMIT_MS) {
+        }
+        else if (verdict.state === "quiet") {
             console.log(yellow(`\n  ! nothing new on the host for ${Math.round(QUIET_LIMIT_MS / 60_000)} minutes — giving up on the wait`));
             break;
         }
@@ -296,8 +327,11 @@ export async function deploy(options) {
         .join("\n"));
     console.log(healthy
         ? green("\n  ✓ deployed and serving the current build")
-        : yellow("\n  ! the restart did not report health. It may still be building — this stops watching, it does not stop the host.\n" +
-            `    Watch it:  ssh ${target} 'tail -f /tmp/kyb-deploy.log'`));
+        : stuck
+            ? yellow(`\n  ! the restart cannot finish while that container exists. Remove it on the host, then run kyb deploy again.\n` +
+                `    ssh ${target} '${stuck.replace(/^.*remove it: /, "").replace(/\).*$/, "")}'`)
+            : yellow("\n  ! the restart did not report health. It may still be building — this stops watching, it does not stop the host.\n" +
+                `    Watch it:  ssh ${target} 'tail -f /tmp/kyb-deploy.log'`));
     if (!healthy)
         process.exitCode = 1;
 }

package/dist/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type AgentInputLimit } from "./agent-limits.js";
+import { type CompiledModelRouting } from "./model-reach.js";
 type Verdict = "pass" | "warn" | "fail";
 export interface Check {
     verdict: Verdict;
@@ -17,6 +18,7 @@ export interface DockerTemplateInspection {
     }[];
 }
 export declare function dockerTemplateDoctorChecks(result: DockerTemplateInspection): Check[];
+export declare function modelReachDoctorCheck(authoredSource: string | null, compiledRouting: CompiledModelRouting): Check;
 export declare function agentInputLimitDoctorCheck(limit: AgentInputLimit): Check;
 /**
  * The inspector lives in @kybernesis/exe, next to the runtime that owns the

package/dist/doctor.js

@@ -1,9 +1,11 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { TEMPLATE_CONTAINER_PROBE, parseTemplateContainers, templateContainerDoctorChecks } from "./sandbox-orphans.js";
 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";
+import { classifyModelReach } from "./model-reach.js";
 const MARK = {
     pass: green("✓"),
     warn: yellow("!"),
@@ -31,6 +33,24 @@ export function dockerTemplateDoctorChecks(result) {
         detail: issue.detail,
     }));
 }
+export function modelReachDoctorCheck(authoredSource, compiledRouting) {
+    const reach = classifyModelReach(authoredSource, compiledRouting);
+    switch (reach.kind) {
+        case "claude-sub":
+            return { verdict: "pass", label: "Model reach: claude-sub (Claude subscription)" };
+        case "exe":
+            return { verdict: "pass", label: "Model reach: exe (host LLM integration)" };
+        case "gateway":
+            return { verdict: "pass", label: "Model reach: gateway" };
+        case "direct-provider":
+            return {
+                verdict: "pass",
+                label: `Model reach: direct-provider${reach.provider ? ` (${reach.provider})` : ""}`,
+            };
+        case "unresolved":
+            return { verdict: "warn", label: "Model reach: unresolved", detail: reach.reason };
+    }
+}
 export function agentInputLimitDoctorCheck(limit) {
     switch (limit.kind) {
         case "explicit-numeric":
@@ -358,6 +378,11 @@ export async function doctor() {
          * eventually produces looks like anything except a full disk.
          */
         if (capture("sh", ["-c", "command -v docker >/dev/null && echo yes"])?.trim() === "yes") {
+            // A template container left behind by a killed start blocks every
+            // later start forever; a live one means "do not restart yet" (KYB-531).
+            for (const check of templateContainerDoctorChecks(parseTemplateContainers(capture("sh", ["-c", TEMPLATE_CONTAINER_PROBE])))) {
+                checks.push(check);
+            }
             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") {
@@ -502,9 +527,16 @@ export async function doctor() {
      * `env` here is the same merged view every other check reads: .env.local
      * underneath, the real environment on top.
      */
+    const rootAgentPath = join(cwd, "agent/agent.ts");
+    const rootAgentSource = existsSync(rootAgentPath) ? readFileSync(rootAgentPath, "utf8") : null;
     const info = inspectEveAgent(cwd, env);
     if (info === null) {
         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");
+        const reachCheck = modelReachDoctorCheck(rootAgentSource, {
+            kind: "unresolved",
+            reason: "eve info failed before compiled model routing could be inspected",
+        });
+        add(reachCheck.verdict, reachCheck.label, reachCheck.detail);
         add("warn", "Eve max input tokens/session: unresolved", "eve info failed before the compiled root policy could be inspected");
     }
     else {
@@ -513,6 +545,8 @@ export async function doctor() {
             add("pass", `eve discovery clean (${diag.warnings} warnings)`);
         else
             add("fail", `eve discovery: ${diag ? `${diag.errors} errors` : "unparsed"}`, "npx eve info --json");
+        const reachCheck = modelReachDoctorCheck(rootAgentSource, info.modelRouting);
+        add(reachCheck.verdict, reachCheck.label, reachCheck.detail);
         const limitCheck = agentInputLimitDoctorCheck(info.limit);
         add(limitCheck.verdict, limitCheck.label, limitCheck.detail);
     }

package/dist/init.d.ts

@@ -26,6 +26,8 @@ export interface InitOptions {
      * actually non-interactive.
      */
     model?: string;
+    /** One-shot route selector. `claude-sub` uses the host-local Claude OAuth proxy. */
+    modelReach?: string;
     /** Department subagents. Default NONE. */
     subagents?: string[];
     /** Skip prompts and take the flags/defaults as given. */

package/dist/init.js

@@ -7,6 +7,7 @@ import { configureArcana } from "./arcana.js";
 import { upsertEnv } from "./envfile.js";
 import { systemdRestartCommand } from "./systemd.js";
 import { sandboxCleanupScaffoldFiles } from "./sandbox-cleanup.js";
+import { MODEL_REACH_ENV, resolveModelScaffold } from "./model-reach.js";
 /**
  * The always-installed core. Everything else — channels, subagents, engineer,
  * host bindings — is opt-in, because assuming them means the FDE deletes files
@@ -18,7 +19,6 @@ const CORE_ITEMS = ["enterprise", "arcana", "evals"];
 // self-hosted agent it cannot get an OIDC token and the agent fails to boot.
 const ENGINEER_ITEMS_ALL = ["extension/agent-browser", "extension/github-tools"];
 const ENGINEER_ITEMS_VERCEL = ["connection/vercel"];
-const DEFAULT_MODEL = "anthropic/claude-sonnet-5";
 export async function init(rawName, options = {}) {
     const engineer = options.engineer === true;
     const studio = options.studio === true;
@@ -59,8 +59,20 @@ export async function init(rawName, options = {}) {
         console.error(`Directory ${name}/ already exists.`);
         process.exit(1);
     }
+    let model;
+    try {
+        model = resolveModelScaffold({
+            host,
+            cliReach: options.modelReach,
+            envReach: process.env[MODEL_REACH_ENV],
+            model: options.model,
+        });
+    }
+    catch (error) {
+        console.error(red(error.message));
+        process.exit(1);
+    }
     const plan = channelPlan(channel, name, host);
-    const model = options.model ?? DEFAULT_MODEL;
     console.log(bold(`\n1/6  Scaffolding eve agent (eve@${EVE_VERSION}) …`));
     // eve's scaffold ends by opening its interactive model picker
     // (`eve dev --input /model`), which exits non-zero wherever there is no
@@ -97,11 +109,17 @@ export async function init(rawName, options = {}) {
     for (const item of CORE_ITEMS) {
         run("npx", ["eve", "add", `@kybernesis/${item}`, "--overwrite"], { cwd: dir });
     }
-    // @ai-sdk/anthropic is for the EVAL JUDGE, not the agent: an agent judged
-    // by the model it runs on is a weak test.
+    // Anthropic is always the exe eval judge and is also the claude-sub agent
+    // provider. OpenAI is needed only by the ordinary exeModel gateway route.
     const extraDeps = [
         ...plan.deps,
-        ...(host === "exe" ? ["@kybernesis/exe", "@ai-sdk/openai", "@ai-sdk/anthropic"] : []),
+        ...(host === "exe"
+            ? [
+                "@kybernesis/exe",
+                ...(model.reach === "default" ? ["@ai-sdk/openai"] : []),
+                "@ai-sdk/anthropic",
+            ]
+            : []),
     ];
     if (extraDeps.length) {
         console.log(bold(`\n2b   Installing for ${channel}/${host}: ${extraDeps.join(", ")} …`));
@@ -197,7 +215,8 @@ export async function init(rawName, options = {}) {
          * with the model. Empty fails honestly; the host lists its own with
          * curl https://llm.int.exe.xyz/models.json
          */
-        known.EXE_MODEL = "";
+        if (model.reach === "default")
+            known.EXE_MODEL = "";
         /**
          * Longer than any turn, because the alternative is answering twice.
          *
@@ -299,7 +318,7 @@ export async function init(rawName, options = {}) {
         for (const dept of depts) {
             const base = join(dir, "agent/subagents", dept);
             mkdirSync(join(base, "connections"), { recursive: true });
-            writeFileSync(join(base, "agent.ts"), subagentAgentTs(dept));
+            writeFileSync(join(base, "agent.ts"), subagentAgentTs(dept, host, model));
             writeFileSync(join(base, "instructions.md"), subagentInstructionsMd(dept));
             writeFileSync(join(base, "connections/arcana.ts"), subagentArcanaTs(dept));
             if (existsSync(skillsSource)) {
@@ -340,13 +359,14 @@ export async function init(rawName, options = {}) {
         "self-testing (evals)",
         channel === "none" ? null : `${channel} channel`,
         host === "exe" ? "exe.dev host" : null,
+        model.reach === "claude-sub" ? "Claude subscription reach" : null,
         studio ? "KYBER Studio (local execution + management routes)" : null,
         engineer ? "engineer subagent (workshop + vision loop)" : null,
         depts.length ? `${depts.length} dept subagent(s)` : null,
     ].filter(Boolean);
     const steps = [
         `Arcana: create workspaces (${name}-company, ${name}-eval${depts.map((d) => `, ${name}-${d}`).join("")}) + scoped kb_ keys; fill .env.local from .env.example`,
-        ...hostSteps(host, name),
+        ...hostSteps(host, name, model),
         ...plan.steps,
         ...(engPlan?.steps ?? []),
         `Control plane: register agent "${name}" at ${issuer}/agents + grant the pilot cohort`,

package/dist/model-reach.d.ts

@@ -0,0 +1,44 @@
+import type { HostKind } from "./templates.js";
+export declare const MODEL_REACH_ENV = "KYB_MODEL_REACH";
+export declare const CLAUDE_SUBSCRIPTION_MODEL = "claude-opus-5";
+export type ScaffoldModelReach = "default" | "claude-sub";
+export interface ModelScaffoldConfig {
+    reach: ScaffoldModelReach;
+    model: string;
+}
+export type CompiledModelRouting = {
+    kind: "gateway";
+} | {
+    kind: "external";
+    provider?: string;
+} | {
+    kind: "unresolved";
+    reason: string;
+};
+export type DoctorModelReach = {
+    kind: "claude-sub";
+} | {
+    kind: "exe";
+} | {
+    kind: "gateway";
+} | {
+    kind: "direct-provider";
+    provider?: string;
+} | {
+    kind: "unresolved";
+    reason: string;
+};
+/** Resolve the one-shot scaffold selector. An explicit CLI value wins over Factory env. */
+export declare function resolveModelReach(cliValue?: string, envValue?: string): ScaffoldModelReach;
+/** Validate host/model compatibility before eve creates any files. */
+export declare function resolveModelScaffold(options: {
+    host: HostKind;
+    cliReach?: string;
+    envReach?: string;
+    model?: string;
+}): ModelScaffoldConfig;
+/**
+ * Classify the effective route from stable authored helpers first, then Eve's
+ * compiled routing. Provider=anthropic alone is not evidence of a subscription.
+ */
+export declare function classifyModelReach(authoredSource: string | null, compiledRouting: CompiledModelRouting): DoctorModelReach;

package/dist/model-reach.js

@@ -0,0 +1,52 @@
+export const MODEL_REACH_ENV = "KYB_MODEL_REACH";
+export const CLAUDE_SUBSCRIPTION_MODEL = "claude-opus-5";
+/** Resolve the one-shot scaffold selector. An explicit CLI value wins over Factory env. */
+export function resolveModelReach(cliValue, envValue) {
+    const selected = cliValue !== undefined ? cliValue : envValue;
+    if (selected === undefined)
+        return "default";
+    if (selected.trim() === "" && cliValue === undefined)
+        return "default";
+    if (selected.trim() === "claude-sub")
+        return "claude-sub";
+    throw new Error(`Unsupported model reach ${JSON.stringify(selected)}. Supported values: claude-sub (or omit it for the host default).`);
+}
+/** Validate host/model compatibility before eve creates any files. */
+export function resolveModelScaffold(options) {
+    const reach = resolveModelReach(options.cliReach, options.envReach);
+    if (reach === "default") {
+        return { reach, model: options.model ?? "anthropic/claude-sonnet-5" };
+    }
+    if (options.host !== "exe") {
+        throw new Error("Model reach claude-sub requires --host=exe because its OAuth proxy runs on the same machine as the agent.");
+    }
+    const model = (options.model ?? CLAUDE_SUBSCRIPTION_MODEL).replace(/^anthropic\//, "");
+    if (model !== CLAUDE_SUBSCRIPTION_MODEL) {
+        throw new Error(`Model reach claude-sub currently supports only ${CLAUDE_SUBSCRIPTION_MODEL}. ` +
+            "That is the model covered by @kybernesis/exe's certified context-window constant; use a bare Anthropic id.");
+    }
+    return { reach, model };
+}
+/**
+ * Classify the effective route from stable authored helpers first, then Eve's
+ * compiled routing. Provider=anthropic alone is not evidence of a subscription.
+ */
+export function classifyModelReach(authoredSource, compiledRouting) {
+    if (authoredSource !== null) {
+        const claudeSubscription = /\bclaudeSubscription\s*\(/.test(authoredSource);
+        const exeModel = /\bexeModel\s*\(/.test(authoredSource);
+        if (claudeSubscription && !exeModel)
+            return { kind: "claude-sub" };
+        if (exeModel && !claudeSubscription)
+            return { kind: "exe" };
+        if (claudeSubscription && exeModel) {
+            return { kind: "unresolved", reason: "root agent authors both claudeSubscription() and exeModel()" };
+        }
+    }
+    if (compiledRouting.kind === "gateway")
+        return { kind: "gateway" };
+    if (compiledRouting.kind === "external") {
+        return { kind: "direct-provider", ...(compiledRouting.provider ? { provider: compiledRouting.provider } : {}) };
+    }
+    return { kind: "unresolved", reason: compiledRouting.reason };
+}

package/dist/sandbox-orphans.d.ts

@@ -0,0 +1,56 @@
+import type { Check } from "./doctor.js";
+/**
+ * Docker sandbox template containers: the ones still building, and the ones
+ * left behind.
+ *
+ * eve builds each Docker sandbox template inside an `eve-sbx-tpl-*` container
+ * on first start. A cold build (apt-get, pnpm, playwright with its browsers)
+ * runs for minutes and prints nothing to the deploy log while it does. Two
+ * things went wrong with that on one deployment (KYB-531):
+ *
+ * - the host start script judged the start on a 45-second clock and printed
+ *   "FAILED to start" while the template was building, so the operator killed
+ *   the start;
+ * - the killed start left the container behind with `sleep 2147483647` as its
+ *   only process, and while it existed every later `eve start` blocked forever
+ *   at "initializing N sandbox templates" with nothing in any log to say why.
+ *
+ * Everything here reads one probe: each template container's name and how
+ * many processes inside it are not `sleep`. Building means at least one; an
+ * orphan means none.
+ */
+export interface TemplateContainer {
+    name: string;
+    /** Processes inside the container other than `sleep`. */
+    liveProcesses: number;
+}
+/**
+ * Shell that prints one `name count` line per `eve-sbx-tpl-*` container, or
+ * nothing when Docker is absent. The same probe serves doctor (locally), the
+ * deploy (over ssh), and the host start script.
+ */
+export declare const TEMPLATE_CONTAINER_PROBE: string;
+export declare function parseTemplateContainers(output: string | null | undefined): TemplateContainer[];
+export declare function orphanedTemplates(containers: readonly TemplateContainer[]): TemplateContainer[];
+export declare function buildingTemplates(containers: readonly TemplateContainer[]): TemplateContainer[];
+/** The exact command that clears an orphan; printed as the remedy and run by the start script. */
+export declare function removeOrphanCommand(name: string): string;
+export declare function templateContainerDoctorChecks(containers: readonly TemplateContainer[]): Check[];
+export type RestartState = "healthy" | "failed" | "building" | "orphaned" | "quiet" | "waiting";
+/**
+ * What a deploy should conclude from the host right now.
+ *
+ * The log alone was the whole verdict before, and a template build is silent
+ * in it. The template probe is the second witness: while something is building,
+ * silence is progress and the wait goes on; an orphan with nothing building
+ * and no server is a stuck host with a known remedy, not a slow one.
+ */
+export declare function assessRestart(input: {
+    log: string;
+    templates: readonly TemplateContainer[];
+    quietMs: number;
+    quietLimitMs: number;
+}): {
+    state: RestartState;
+    detail?: string;
+};

package/dist/sandbox-orphans.js

@@ -0,0 +1,77 @@
+/**
+ * Shell that prints one `name count` line per `eve-sbx-tpl-*` container, or
+ * nothing when Docker is absent. The same probe serves doctor (locally), the
+ * deploy (over ssh), and the host start script.
+ */
+export const TEMPLATE_CONTAINER_PROBE = [
+    "command -v docker >/dev/null 2>&1 || exit 0",
+    "for c in $(docker ps --filter name=eve-sbx-tpl- --format '{{.Names}}' 2>/dev/null); do",
+    "  live=$(docker top \"$c\" 2>/dev/null | tail -n +2 | awk '{print $8}' | grep -vc '^sleep$')",
+    '  echo "$c ${live:-0}"',
+    "done",
+].join("\n");
+export function parseTemplateContainers(output) {
+    return (output ?? "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("eve-sbx-tpl-"))
+        .map((line) => {
+        const [name, count] = line.split(/\s+/);
+        return { name, liveProcesses: Number(count) || 0 };
+    });
+}
+export function orphanedTemplates(containers) {
+    return containers.filter((c) => c.liveProcesses === 0);
+}
+export function buildingTemplates(containers) {
+    return containers.filter((c) => c.liveProcesses > 0);
+}
+/** The exact command that clears an orphan; printed as the remedy and run by the start script. */
+export function removeOrphanCommand(name) {
+    return `docker rm -f ${name}`;
+}
+export function templateContainerDoctorChecks(containers) {
+    const orphans = orphanedTemplates(containers);
+    const building = buildingTemplates(containers);
+    const checks = orphans.map((c) => ({
+        verdict: "fail",
+        label: `orphaned sandbox template container ${c.name}: every eve start will hang until it is removed`,
+        detail: `its only process is sleep; a start was killed mid-build. Remove it: ${removeOrphanCommand(c.name)}`,
+    }));
+    if (building.length) {
+        checks.push({
+            verdict: "warn",
+            label: `sandbox template building: ${building.map((c) => c.name).join(", ")}`,
+            detail: "a cold build takes minutes and the server binds its port only after it finishes; do not restart",
+        });
+    }
+    return checks;
+}
+/**
+ * What a deploy should conclude from the host right now.
+ *
+ * The log alone was the whole verdict before, and a template build is silent
+ * in it. The template probe is the second witness: while something is building,
+ * silence is progress and the wait goes on; an orphan with nothing building
+ * and no server is a stuck host with a known remedy, not a slow one.
+ */
+export function assessRestart(input) {
+    if (/health:\s*200/.test(input.log))
+        return { state: "healthy" };
+    if (/FAILED/.test(input.log))
+        return { state: "failed" };
+    const building = buildingTemplates(input.templates);
+    if (building.length) {
+        return { state: "building", detail: building.map((c) => c.name).join(", ") };
+    }
+    const orphans = orphanedTemplates(input.templates);
+    if (orphans.length) {
+        return {
+            state: "orphaned",
+            detail: orphans.map((c) => `${c.name} (remove it: ${removeOrphanCommand(c.name)})`).join("; "),
+        };
+    }
+    if (input.quietMs > input.quietLimitMs)
+        return { state: "quiet" };
+    return { state: "waiting" };
+}

package/dist/templates.d.ts

@@ -1,13 +1,14 @@
 /** File templates written by `kyb init`. Kept in sync with the proven Kyber patterns. */
+import type { ModelScaffoldConfig } from "./model-reach.js";
 export declare const DEPT_DESCRIPTIONS: Record<string, string>;
 export declare function deptDescription(dept: string): string;
 export declare function identityMd(displayName: string, depts: string[]): string;
-export declare function subagentAgentTs(dept: string): string;
+export declare function subagentAgentTs(dept: string, host: HostKind, model: ModelScaffoldConfig): string;
 export declare function subagentInstructionsMd(dept: string): string;
 export declare function subagentArcanaTs(dept: string): string;
 export declare function rootArcanaTs(): string;
 export declare function evalFileTs(displayName: string, depts: string[]): string;
-export declare function envExample(name: string, depts: string[], issuer: string, channelEnv?: string[], host?: "vercel" | "exe", model?: string): string;
+export declare function envExample(name: string, depts: string[], issuer: string, channelEnv?: string[], host?: "vercel" | "exe", model?: ModelScaffoldConfig): string;
 export declare function evalScript(name: string, depts: string[]): string;
 export type ChannelKind = "none" | "slack" | "imessage" | "telegram" | "discord" | "web";
 export declare const CHANNEL_KINDS: ChannelKind[];
@@ -26,8 +27,8 @@ export interface ChannelPlan {
 }
 export declare function channelPlan(kind: ChannelKind, name: string, host: HostKind): ChannelPlan;
 export type HostKind = "vercel" | "exe";
-export declare function hostAgentTs(host: HostKind, model: string): string;
-export declare function hostSteps(host: HostKind, name: string): string[];
+export declare function hostAgentTs(host: HostKind, model: ModelScaffoldConfig): string;
+export declare function hostSteps(host: HostKind, name: string, model: ModelScaffoldConfig): string[];
 export interface EngineerPlan {
     files: Array<{
         path: string;
@@ -36,7 +37,7 @@ export interface EngineerPlan {
     deps: string[];
     steps: string[];
 }
-export declare function engineerPlan(host: HostKind, model: string): EngineerPlan;
+export declare function engineerPlan(host: HostKind, model: ModelScaffoldConfig): EngineerPlan;
 /**
  * The eval judge, for an exe.dev host.
  *

package/dist/templates.js

@@ -33,14 +33,14 @@ concrete — chat is not a document editor. Prefer short paragraphs and bullet
 lists.
 ${delegation}`;
 }
-export function subagentAgentTs(dept) {
+export function subagentAgentTs(dept, host, model) {
+    const rendered = agentModelTemplate(host, model);
     return `import { defineAgent } from "eve";
-
+${rendered.imports}
 export default defineAgent({
   description:
     ${JSON.stringify(deptDescription(dept))},
-  model: "anthropic/claude-sonnet-5",
-});
+${rendered.fields}});
 `;
 }
 export function subagentInstructionsMd(dept) {
@@ -164,17 +164,22 @@ ${depts.length ? `  routing: [\n${routing}\n  ],\n` : ""}});
  * agent's machine.
  */
 function exeEnvBlock(name, model) {
-    return `# Self-hosted host + model (@kybernesis/exe)
-# EXE_MODEL must match the LLM integration you attached to the VM. A ChatGPT
+    const gatewayModel = model.reach === "default"
+        ? `# EXE_MODEL must match the LLM integration you attached to the VM. A ChatGPT
 # subscription serves OpenAI models; the code default will fail against one.
-# Set it explicitly rather than relying on ${model}.
-EXE_MODEL="${model}"
-# Preview URLs are built from this. There is no default on purpose.
+# Set it explicitly rather than relying on ${model.model}.
+EXE_MODEL="${model.model}"
+`
+        : `# Model reach: Claude subscription through the loopback OAuth proxy.
+# EXE_MODEL is intentionally absent: this agent never calls the exe LLM gateway.
+`;
+    return `# Self-hosted host + model (@kybernesis/exe)
+${gatewayModel}# Preview URLs are built from this. There is no default on purpose.
 EXE_VM_NAME="${name}"
 
 `;
 }
-export function envExample(name, depts, issuer, channelEnv = [], host = "vercel", model = "") {
+export function envExample(name, depts, issuer, channelEnv = [], host = "vercel", model = { reach: "default", model: "" }) {
     const deptVars = depts
         .map((d) => {
         const upper = d.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
@@ -354,31 +359,52 @@ export default discordChannel({ botToken: process.env.DISCORD_BOT_TOKEN! });
             };
     }
 }
-export function hostAgentTs(host, model) {
+/** One renderer for every model-bearing generated agent, root or subagent. */
+function agentModelTemplate(host, config) {
+    if (config.reach === "claude-sub") {
+        if (host !== "exe")
+            throw new Error("claude-sub model templates require an exe host");
+        return {
+            imports: `import { createAnthropic } from "@ai-sdk/anthropic";\n` +
+                `import { CLAUDE_SUBSCRIPTION_CONTEXT_WINDOW, claudeSubscription } from "@kybernesis/exe";\n\n`,
+            fields: `  model: claudeSubscription({ model: ${JSON.stringify(config.model)}, createAnthropic }),\n` +
+                `  modelContextWindowTokens: CLAUDE_SUBSCRIPTION_CONTEXT_WINDOW,\n`,
+        };
+    }
     if (host === "exe") {
-        return `import { defineAgent } from "eve";
-import { createOpenAI } from "@ai-sdk/openai";
-import { exeModel } from "@kybernesis/exe";
-
-// Model served by the exe.dev LLM integration — no provider key on the host.
-// exe injects the credential (managed gateway, your API key, or a connected
-// ChatGPT subscription) server-side.
-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 },
-});
-`;
+        return {
+            imports: `import { createOpenAI } from "@ai-sdk/openai";\n` +
+                `import { exeModel } from "@kybernesis/exe";\n\n`,
+            fields: `  model: exeModel({ model: process.env.EXE_MODEL ?? ${JSON.stringify(config.model)}, createOpenAI }),\n` +
+                `  modelContextWindowTokens: 200_000,\n`,
+        };
     }
+    return { imports: "", fields: `  model: ${JSON.stringify(config.model)},\n` };
+}
+export function hostAgentTs(host, model) {
+    const rendered = agentModelTemplate(host, model);
+    const comment = model.reach === "claude-sub"
+        ? `// Claude subscription model through the loopback OAuth proxy — no API key or exe gateway.\n`
+        : host === "exe"
+            ? `// Model served by the exe.dev LLM integration — no provider key on the host.\n// exe injects the credential (managed gateway, your API key, or a connected\n// ChatGPT subscription) server-side.\n`
+            : "";
     return `import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: ${JSON.stringify(model)},
-});
+${rendered.imports}${comment}export default defineAgent({
+${rendered.fields}${host === "exe" ? `  // This long-lived self-hosted process has no metered platform session ceiling.\n  limits: { maxInputTokensPerSession: false },\n` : ""}});
 `;
 }
-export function hostSteps(host, name) {
+export function hostSteps(host, name, model) {
+    if (host === "exe" && model.reach === "claude-sub") {
+        return [
+            `Create the VM:  ssh exe.dev new --name ${name}`,
+            `Start the loopback Claude OAuth proxy: bash scripts/claude-subscription.sh up`,
+            `Sign in with the client's Claude subscription: bash scripts/claude-subscription.sh login`,
+            `Prove the proxy is signed in and not exposed: bash scripts/claude-subscription.sh status`,
+            `Install Node 24 + deps on the VM, fill .env.local, then install the production service:`,
+            `    bash node_modules/@kybernesis/exe/scripts/install-service.sh`,
+            `The systemd unit exports .env.local, builds before every start, and is the single supervisor`,
+        ];
+    }
     if (host === "exe") {
         return [
             `Create the VM:  ssh exe.dev new --name ${name}`,
@@ -507,32 +533,17 @@ export default defineSandbox({
 }
 export function engineerPlan(host, model) {
     const onExe = host === "exe";
+    const renderedModel = agentModelTemplate(host, model);
     const files = [
         {
             path: "agent/subagents/builder/agent.ts",
-            content: onExe
-                ? `import { defineAgent } from "eve";
-import { createOpenAI } from "@ai-sdk/openai";
-import { exeModel } from "@kybernesis/exe";
-
-// The specialist the root agent delegates BUILDING to. \`description\` is what
+            content: `import { defineAgent } from "eve";
+${renderedModel.imports}// The specialist the root agent delegates BUILDING to. \`description\` is what
 // the root routes on — keep it about building, not answering.
 export default defineAgent({
   description:
     "Builds and runs software: scaffolds projects, writes code, installs dependencies, runs builds and dev servers, and visually verifies rendered pages. Use when the user asks for something to be BUILT, prototyped, deployed, or fixed in code — not for questions, planning, or scheduling.",
-  model: exeModel({ model: process.env.EXE_MODEL ?? ${JSON.stringify(model)}, createOpenAI }),
-  modelContextWindowTokens: 200_000,
-});
-`
-                : `import { defineAgent } from "eve";
-
-// The specialist the root agent delegates BUILDING to. \`description\` is what
-// the root routes on — keep it about building, not answering.
-export default defineAgent({
-  description:
-    "Builds and runs software: scaffolds projects, writes code, installs dependencies, runs builds and dev servers, and visually verifies rendered pages. Use when the user asks for something to be BUILT, prototyped, deployed, or fixed in code — not for questions, planning, or scheduling.",
-  model: ${JSON.stringify(model)},
-});
+${renderedModel.fields}});
 `,
         },
         {

package/dist/upgrade.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { upsertEnv } from "./envfile.js";
@@ -237,6 +237,33 @@ function repairHostArtifacts(cwd, deps) {
     const pruneSource = join(scripts, "docker-prune.sh");
     const pruneTarget = "/etc/cron.daily/kyb-docker-prune";
     const hasDocker = capture("sh", ["-c", "command -v docker >/dev/null && echo yes"])?.trim() === "yes";
+    // The host start script is package-owned too. It carried a 45-second
+    // verdict clock that called a cold sandbox template build a failure, and no
+    // sweep for the orphaned template container that a killed start leaves
+    // behind (KYB-531). An agent still running the copy `kyb init` made keeps
+    // both faults until something refreshes it; this does, on every upgrade.
+    const serverSource = join(scripts, "eve-server.sh");
+    const serverTarget = join(cwd, "scripts/eve-server.sh");
+    if (existsSync(serverSource) && existsSync(serverTarget)) {
+        reconcileHostArtifact({
+            targetPath: serverTarget,
+            desiredContent: readFileSync(serverSource),
+            expectedMode: 0o755,
+            installIfMissing: false,
+            owner: "@kybernesis/exe/scripts/eve-server.sh",
+            update: () => {
+                try {
+                    copyFileSync(serverSource, serverTarget);
+                    chmodSync(serverTarget, 0o755);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            manualCommand: `cp ${shellQuote(serverSource)} scripts/eve-server.sh && chmod +x scripts/eve-server.sh`,
+        });
+    }
     if (existsSync(pruneSource)) {
         const pruneResult = reconcileHostArtifact({
             targetPath: pruneTarget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.14.6",
+  "version": "0.14.8",
   "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/eve-building/SKILL.md

@@ -25,6 +25,18 @@ Direct provider: install `@ai-sdk/<provider>`, pass `anthropic("claude-opus-4-8"
 `defineDynamic({ fallback, events })` — prefer `session.started` scope (prompt
 caches are per model). Docs: `agent-config.md`.
 
+For an exe-hosted agent that must use a client's Claude subscription instead of
+the exe LLM gateway, scaffold with `--host=exe --model-reach=claude-sub` (or set
+`KYB_MODEL_REACH=claude-sub` for Factory invocation; the CLI flag wins). The
+certified shape is `createAnthropic` from `@ai-sdk/anthropic` passed to
+`claudeSubscription({ model: "claude-opus-5", createAnthropic })`, with
+`CLAUDE_SUBSCRIPTION_CONTEXT_WINDOW`, both from `@kybernesis/exe`. Use the bare
+Anthropic id, never `anthropic/...`; do not reuse that context-window constant
+for another model. The generated agent does not use `exeModel` or `EXE_MODEL`.
+Run `scripts/claude-subscription.sh up`, `login`, then `status` on the host; the
+OAuth proxy must stay loopback-only. Provider details:
+`packages/exe/src/claude.ts` and `packages/exe/README.md`.
+
 ## Channels (agent/channels/, one file per surface)
 
 Filename = channel id. eve normalizes every surface into one runtime — tools/