@kontextmind/kxm 0.7.167 → 0.7.169

package/plugins/kxm/src/engine.ts

@@ -113,7 +113,7 @@ import {
   type KxmRunRecord,
   type KxmRunStatus,
 } from "./runtime-store.ts";
-import { KxmConfigError, kxmCanonicalJson, lookupKxmResource, type JsonValue, type KxmProjectBundle } from "./project-config.ts";
+import { KxmConfigError, kxmCanonicalJson, lookupKxmResource, toolPresetExceedsRoleMessage, toolPresetProfile, type JsonValue, type KxmProjectBundle } from "./project-config.ts";
 import { evaluateArtifactsGate } from "./engine-artifacts.ts";
 import { createCommandObserver } from "./engine-command.ts";
 import {
@@ -1726,6 +1726,85 @@ function unsupportedAgentStepTimeout(step: KxmCompiledStep, limitMs: number): Om
   };
 }
 
+function narrowerPermission(left: "read-only" | "edit", right: "read-only" | "edit"): "read-only" | "edit" {
+  return left === "read-only" || right === "read-only" ? "read-only" : "edit";
+}
+
+function stepRepositoryPermission(step: KxmCompiledStep): "read-only" | "edit" {
+  return Object.values(step.repositories).some((access) => access === "write") ? "edit" : "read-only";
+}
+
+function stepAccessDetail(step: KxmCompiledStep): string {
+  const entries = Object.entries(step.repositories);
+  if (entries.length === 0) return "none";
+  return entries
+    .map(([id, access]) => `${id} ${access}`)
+    .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
+    .join(", ");
+}
+
+function yamlToolsPreset(doc: Record<string, unknown> | undefined): string | undefined {
+  const tools = doc?.tools;
+  if (!tools || typeof tools !== "object" || Array.isArray(tools)) return undefined;
+  const preset = (tools as { preset?: unknown }).preset;
+  return typeof preset === "string" && preset.length > 0 ? preset : undefined;
+}
+
+/**
+ * Dispatch permission is the narrowest of the role permission, the preset
+ * profile, and the step repository access. A wider agent preset, or a write
+ * step on a read-only chain, is step_unsupported.
+ */
+function resolveToolDispatch(
+  projectRoot: string,
+  step: KxmCompiledStep,
+  agentId: string,
+): { permission: "read-only" | "edit" } | { error: Omit<KxmRunHandoff, "stepId"> } {
+  const stepPermission = stepRepositoryPermission(step);
+  if (step.kind !== "agent" && step.kind !== "moa") return { permission: stepPermission };
+  const agentFile = findYamlBasename(join(projectRoot, ".kxm", "agents"), agentId, "agent") ?? agentId;
+  const agent = readYamlFile(join(projectRoot, ".kxm", "agents", `${agentFile}.yaml`));
+  const roleId = typeof agent?.role === "string" ? agent.role : "";
+  if (!roleId) return { permission: stepPermission };
+  const roleDoc = readYamlFile(join(projectRoot, ".kxm", "roles", `${roleId}.yaml`));
+  const rawPermission = roleDoc?.permission;
+  const rolePermission: "edit" | "read-only" | undefined = rawPermission === "edit" || rawPermission === "read-only" ? rawPermission : undefined;
+  if (!rolePermission) return { permission: stepPermission };
+  const rolePreset = yamlToolsPreset(roleDoc);
+  const agentPreset = yamlToolsPreset(agent);
+  const rolePresetProfile = rolePreset ? toolPresetProfile(rolePreset) : undefined;
+  if (rolePreset && rolePresetProfile === "edit" && rolePermission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "tools.preset",
+        detail: `tools.preset ${rolePreset} exceeds role ${roleId} permission read-only`,
+      },
+    };
+  }
+  if (agentPreset) {
+    const exceeds = toolPresetExceedsRoleMessage(agentPreset, roleId, rolePermission, rolePreset);
+    if (exceeds) {
+      return { error: { reason: "step_unsupported", field: "tools.preset", detail: exceeds } };
+    }
+  }
+  let chain: "read-only" | "edit" = rolePermission;
+  if (rolePresetProfile) chain = narrowerPermission(chain, rolePresetProfile);
+  const agentProfile = agentPreset ? toolPresetProfile(agentPreset) : undefined;
+  if (agentProfile) chain = narrowerPermission(chain, agentProfile);
+  const permission = narrowerPermission(chain, stepPermission);
+  if (stepPermission === "edit" && permission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "permission",
+        detail: `role permission ${rolePermission} resolves to ${chain}; step access ${stepAccessDetail(step)}`,
+      },
+    };
+  }
+  return { permission };
+}
+
 function executingSingletonAttempt(
   plan: KxmCompiledPlan,
   state: KxmRunState,
@@ -1944,12 +2023,21 @@ function prepareDispatch(
   const wideTimeout = unsupportedAgentStepTimeout(step, projectAgentStepTimeoutMs(context, run));
   if (wideTimeout) return { kind: "return", state, handoff: { ...wideTimeout, stepId } };
 
+  const firstListed = step.assignments.allowedAgents[0];
+  const firstAgentId = (step.kind === "agent" || step.kind === "moa")
+    ? (firstListed ? firstListed : step.agent)
+    : undefined;
+  if (firstAgentId) {
+    const toolDispatch = resolveToolDispatch(context.projectRoot, step, firstAgentId);
+    if ("error" in toolDispatch) {
+      return { kind: "return", state, handoff: { ...toolDispatch.error, stepId } };
+    }
+  }
+
   let resolvedRoute: ResolvedProducerRoute | undefined;
   if (producerId !== "driver-simulated") {
-    const allowed = step.assignments.allowedAgents;
-    const agentId = (allowed && allowed.length > 0 && allowed[0])
-      ? allowed[0]!
-      : (step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator");
+    const agentId = firstAgentId
+      ?? ((step.kind === "agent" || step.kind === "moa") ? step.agent : "coordinator");
     const routeResult = resolveProducerRoute(context.projectRoot, step, agentId);
     if ("error" in routeResult) {
       return { kind: "return", state, handoff: { ...routeResult.error, stepId } };
@@ -2092,6 +2180,10 @@ function birthMember(
   const agentId = (allowed && allowed.length > born && allowed[born])
     ? allowed[born]!
     : (input.step.kind === "agent" || input.step.kind === "moa" ? input.step.agent : "coordinator");
+  const toolDispatch = resolveToolDispatch(context.projectRoot, input.step, agentId);
+  if ("error" in toolDispatch) {
+    return { handoff: { ...toolDispatch.error, stepId: input.stepId } };
+  }
   let resolvedRoute = input.resolvedRoute;
   if (!resolvedRoute && input.producerId && input.producerId !== "driver-simulated") {
     const routeResult = resolveProducerRoute(context.projectRoot, input.step, agentId);
@@ -2183,7 +2275,7 @@ function birthMember(
       stepAttempt: input.stepAttempt,
       objective: promptText,
       allowedOutcomes: [...input.step.outcomes],
-      permissionCeiling: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
+      permissionCeiling: toolDispatch.permission,
     },
     acceptanceCriteria: input.step.requiredEvidence.map((ev) => ({
       id: ev.key,
@@ -2227,7 +2319,7 @@ function birthMember(
       allowedOutcomes: input.step.outcomes,
       signal: controller.signal,
       prompt: input.step.instructions ? `${input.step.instructions}\n\n${generatedPrompt}` : generatedPrompt,
-      permission: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
+      permission: toolDispatch.permission,
       ...((input.step.kind === "agent" || input.step.kind === "moa") && input.step.timeoutMs !== undefined
         ? { timeoutMs: input.step.timeoutMs }
         : {}),
@@ -3144,6 +3236,11 @@ export function kxmLiveRunPrerequisites(
     if (step.kind !== "agent" && step.kind !== "moa") continue;
     const agentIds = step.assignments.allowedAgents.length > 0 ? step.assignments.allowedAgents : [step.agent];
     for (const agentId of agentIds) {
+      const toolDispatch = resolveToolDispatch(projectRoot, step, agentId);
+      if ("error" in toolDispatch) {
+        prerequisites.push({ ...toolDispatch.error, stepId });
+        continue;
+      }
       const route = resolveProducerRoute(projectRoot, step, agentId);
       if ("error" in route) {
         const detail = route.error.detail === "producer_route_unsupported: agent step model is not honored"
@@ -3153,7 +3250,7 @@ export function kxmLiveRunPrerequisites(
         continue;
       }
       const harness = route.harness;
-      const permission = Object.values(step.repositories).includes("write") ? "edit" : "read-only";
+      const permission = toolDispatch.permission;
       if (!BUILTIN_HARNESSES.some((entry) => entry.id === harness && entry.oneShot) || !oneShotPermissionArgs(harness, permission)) {
         prerequisites.push({ reason: "step_unsupported", stepId, field: "harness", detail: `${agentId}: ${harness} has no audited ${permission} one-shot profile; use a supported workflow or execute this work directly in ${harness}, without substituting another harness` });
         continue;

package/plugins/kxm/src/hub-binding.ts

@@ -74,6 +74,15 @@ export function hubBindingFile(env: NodeJS.ProcessEnv = process.env): string {
   return join(resolveUserStateRoot(env), "hub-binding.json");
 }
 
+/**
+ * Cloud token source for a machine-wide bind. Kept out of `hub-binding.json`
+ * so a 0.7.159 reader, which accepts only `schema`, `url`, and `boundAt`,
+ * does not throw and stop syncing.
+ */
+export function hubBindingCloudFile(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveUserStateRoot(env), "hub-binding.cloud.json");
+}
+
 export function validateHubUrl(raw: string): string {
   let parsed: URL;
   try {
@@ -247,40 +256,50 @@ function isAbortError(error: unknown): boolean {
   );
 }
 
-export function readHubBinding(env: NodeJS.ProcessEnv = process.env): HubBindingRecord | undefined {
-  const file = hubBindingFile(env);
-  if (!existsSync(file)) return undefined;
+const LEGACY_BINDING_KEYS = ["schema", "url", "boundAt"] as const;
+const BINDING_KEYS = new Set<string>([...LEGACY_BINDING_KEYS, "cloud", "tokenEnv", "tokenCommand"]);
+
+export interface HubBindingLoad {
+  record?: HubBindingRecord;
+  /**
+   * Set when this build ignores the file and continues against the local hub.
+   * A newer schema, or a cloud record an older process cannot read, must not
+   * throw into the Runtime sync loop.
+   */
+  warning?: string;
+}
+
+function bindingFallbackWarning(file: string, reason: string): string {
+  return `hub binding at ${file} ${reason}; falling back to the local hub. Restart the Runtime supervisor, the hub, and workers after upgrading and before a cloud bind.`;
+}
+
+function writeBindingJson(file: string, value: unknown): void {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = join(dirname(file), `.${file.endsWith("cloud.json") ? "hub-binding-cloud" : "hub-binding"}-${process.pid}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function parseBindingObject(file: string): Record<string, unknown> | HubBindingError {
+  if (!existsSync(file)) return new HubBindingError(`missing hub binding at ${file}`);
   let parsed: unknown;
   try {
     parsed = JSON.parse(readFileSync(file, "utf8"));
   } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return new HubBindingError(`malformed hub binding at ${file}`);
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
-  }
-  const row = parsed as Record<string, unknown>;
-  const keys = Object.keys(row);
-  const allowed = new Set(["schema", "url", "boundAt", "cloud", "tokenEnv", "tokenCommand"]);
-  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
-  if (
-    keys.some((key) => !allowed.has(key))
-    || (!cloudish && keys.length !== 3)
-    || row.schema !== HUB_BINDING_SCHEMA
-    || typeof row.url !== "string"
-    || typeof row.boundAt !== "string"
-    || !isIsoTimestamp(row.boundAt)
-  ) {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
-  }
-  let url: string;
-  try {
-    url = validateHubUrl(row.url);
-  } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return new HubBindingError(`malformed hub binding at ${file}`);
   }
-  if (!cloudish) return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
-  if (row.cloud !== true) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return parsed as Record<string, unknown>;
+}
+
+function cloudRecordFromRow(file: string, row: Record<string, unknown>, url: string, boundAt: string): HubBindingRecord | undefined {
+  if (row.cloud !== true) return undefined;
   let tokenEnv: string | undefined;
   let tokenCommand: string | undefined;
   if (row.tokenEnv !== undefined) {
@@ -302,34 +321,272 @@ export function readHubBinding(env: NodeJS.ProcessEnv = process.env): HubBinding
   return {
     schema: HUB_BINDING_SCHEMA,
     url,
-    boundAt: row.boundAt,
+    boundAt,
     cloud: true,
     ...(tokenEnv ? { tokenEnv } : {}),
     ...(tokenCommand ? { tokenCommand } : {}),
   };
 }
 
-export function writeHubBinding(record: HubBindingRecord, env: NodeJS.ProcessEnv = process.env): string {
+/**
+ * The reader shipped in 0.7.159. It accepts only `schema`, `url`, and
+ * `boundAt`. Extra keys throw `malformed hub binding`, which stopped sync.
+ * New cloud binds keep this file in that shape, or omit it, so this reader
+ * falls through to the local hub instead of throwing.
+ */
+export function readLegacyV1HubBinding(env: NodeJS.ProcessEnv = process.env): HubBindingRecord | undefined {
   const file = hubBindingFile(env);
-  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
-  const temporary = join(dirname(file), `.hub-binding-${process.pid}.tmp`);
+  if (!existsSync(file)) return undefined;
+  const parsed = parseBindingObject(file);
+  if (parsed instanceof HubBindingError) throw parsed;
+  const keys = Object.keys(parsed);
+  if (
+    keys.length !== 3
+    || keys.some((key) => !LEGACY_BINDING_KEYS.includes(key as typeof LEGACY_BINDING_KEYS[number]))
+    || parsed.schema !== HUB_BINDING_SCHEMA
+    || typeof parsed.url !== "string"
+    || typeof parsed.boundAt !== "string"
+    || !isIsoTimestamp(parsed.boundAt)
+  ) {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  let url: string;
   try {
-    writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-    renameSync(temporary, file);
-  } finally {
-    rmSync(temporary, { force: true });
+    url = validateHubUrl(parsed.url);
+  } catch {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  return { schema: HUB_BINDING_SCHEMA, url, boundAt: parsed.boundAt };
+}
+
+function interpretBindingFile(file: string): HubBindingLoad & { legacyCloud?: boolean } {
+  if (!existsSync(file)) return {};
+  const parsed = parseBindingObject(file);
+  if (parsed instanceof HubBindingError) throw parsed;
+  const keys = Object.keys(parsed);
+  const unknown = keys.filter((key) => !BINDING_KEYS.has(key));
+  if (parsed.schema !== HUB_BINDING_SCHEMA || unknown.length > 0) {
+    return { warning: bindingFallbackWarning(file, `is newer than this build understands (${String(parsed.schema)})`) };
+  }
+  if (typeof parsed.url !== "string" || typeof parsed.boundAt !== "string" || !isIsoTimestamp(parsed.boundAt)) {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  let url: string;
+  try {
+    url = validateHubUrl(parsed.url);
+  } catch {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
+  if (!cloudish) {
+    if (keys.length !== 3) throw new HubBindingError(`malformed hub binding at ${file}`);
+    return { record: { schema: HUB_BINDING_SCHEMA, url, boundAt: parsed.boundAt } };
+  }
+  const record = cloudRecordFromRow(file, parsed, url, parsed.boundAt);
+  if (!record) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return { record, legacyCloud: true };
+}
+
+/**
+ * Cloud metadata wins over a local `hub-binding.json`. A legacy cloud record
+ * that still lives in `hub-binding.json` is moved aside so a 0.7.159 process
+ * no longer throws on the next read.
+ */
+export function loadHubBinding(env: NodeJS.ProcessEnv = process.env): HubBindingLoad {
+  const cloudFile = hubBindingCloudFile(env);
+  const cloud = interpretBindingFile(cloudFile);
+  if (cloud.warning && !cloud.record) {
+    const local = existsSync(hubBindingFile(env)) ? interpretBindingFile(hubBindingFile(env)) : {};
+    if (local.record && !local.record.cloud) return { record: local.record, warning: cloud.warning };
+    return { warning: cloud.warning };
+  }
+  if (cloud.record?.cloud) return { record: cloud.record, ...(cloud.warning ? { warning: cloud.warning } : {}) };
+  const main = interpretBindingFile(hubBindingFile(env));
+  if (main.legacyCloud && main.record) {
+    writeBindingJson(cloudFile, main.record);
+    rmSync(hubBindingFile(env), { force: true });
+    return {
+      record: main.record,
+      warning: bindingFallbackWarning(
+        hubBindingFile(env),
+        "stored a cloud bind in the pre-0.7.160 file",
+      ),
+    };
+  }
+  return { ...(main.record ? { record: main.record } : {}), ...(main.warning ? { warning: main.warning } : {}) };
+}
+
+export function readHubBinding(env: NodeJS.ProcessEnv = process.env): HubBindingRecord | undefined {
+  return loadHubBinding(env).record;
+}
+
+export function writeHubBinding(record: HubBindingRecord, env: NodeJS.ProcessEnv = process.env): string {
+  if (record.cloud) {
+    const file = hubBindingCloudFile(env);
+    writeBindingJson(file, record);
+    // A 0.7.159 reader throws on extra keys and stops sync. Leave a local
+    // three-key file alone so that reader keeps the local hub. Drop a file
+    // that points at this cloud URL, or that already carries cloud keys.
+    const main = hubBindingFile(env);
+    if (existsSync(main)) {
+      try {
+        const legacy = readLegacyV1HubBinding(env);
+        if (!legacy || legacy.url === record.url) rmSync(main, { force: true });
+      } catch (error) {
+        if (!(error instanceof HubBindingError)) throw error;
+        rmSync(main, { force: true });
+      }
+    }
+    return file;
   }
+  rmSync(hubBindingCloudFile(env), { force: true });
+  const file = hubBindingFile(env);
+  writeBindingJson(file, {
+    schema: HUB_BINDING_SCHEMA,
+    url: record.url,
+    boundAt: record.boundAt,
+  });
   return file;
 }
 
 export function removeHubBinding(env: NodeJS.ProcessEnv = process.env): boolean {
-  const file = hubBindingFile(env);
+  const files = [hubBindingFile(env), hubBindingCloudFile(env)];
+  let removed = false;
+  for (const file of files) {
+    try {
+      rmSync(file);
+      removed = true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+  return removed;
+}
+
+export type HubProbeKind = "hub" | "auth_proxy" | "redirect" | "not_hub" | "unreachable" | "timeout";
+
+export interface HubProbe {
+  health: HubHealth;
+  probeMs: number;
+  kind: HubProbeKind;
+  detail: string;
+  status: number;
+}
+
+export interface HubEndpointVerdict {
+  ok: boolean;
+  status: number;
+  kind: HubProbeKind;
+  detail: string;
+  /** Hub JSON when the body matches. Never the raw HTML of a login page. */
+  body: unknown;
+}
+
+function contentTypeBase(header: string | null): string {
+  return (header ?? "").split(";")[0]!.trim().toLowerCase();
+}
+
+function looksLikeHtml(contentType: string, body: string): boolean {
+  if (contentType === "text/html" || contentType === "application/xhtml+xml") return true;
+  const sample = body.slice(0, 800).trim().toLowerCase();
+  return sample.startsWith("<!doctype html")
+    || sample.startsWith("<html")
+    || (sample.includes("<form") && (sample.includes("login") || sample.includes("authentik") || sample.includes("password")));
+}
+
+function jsonObject(text: string): Record<string, unknown> | undefined {
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `/health` is `{ ok: true, agents: <number> }`. `/ready` adds `storage`. */
+export function hubEndpointShape(role: "health" | "ready", body: Record<string, unknown>): boolean {
+  if (role === "health") return body.ok === true && typeof body.agents === "number";
+  return body.ok === true && (body.storage === "sqlite" || body.storage === "memory");
+}
+
+/**
+ * A kxm hub answers JSON with the documented shape and `application/json`.
+ * An auth proxy's 30x or HTML login page is not that, even on HTTP 200.
+ */
+export function classifyHubResponse(input: {
+  role: "health" | "ready";
+  status: number;
+  contentType: string | null;
+  bodyText: string;
+}): HubEndpointVerdict {
+  const contentType = contentTypeBase(input.contentType);
+  if (input.status >= 300 && input.status < 400) {
+    return {
+      ok: false,
+      status: input.status,
+      kind: "redirect",
+      detail: `HTTP ${input.status} redirect; this looks like an auth proxy or a redirect, not a kxm hub`,
+      body: { error: "auth_proxy", detail: `HTTP ${input.status} redirect` },
+    };
+  }
+  if (looksLikeHtml(contentType, input.bodyText)) {
+    return {
+      ok: false,
+      status: input.status,
+      kind: "auth_proxy",
+      detail: `HTTP ${input.status} returned an HTML login page${contentType ? ` (${contentType})` : ""}; this looks like an auth proxy, not a kxm hub`,
+      body: { error: "auth_proxy", detail: "HTML login page" },
+    };
+  }
+  const jsonType = contentType === "application/json" || contentType === "text/plain" || contentType === "";
+  const body = jsonType ? jsonObject(input.bodyText) : undefined;
+  if (body && hubEndpointShape(input.role, body) && input.status >= 200 && input.status < 300) {
+    if (contentType !== "" && contentType !== "application/json" && contentType !== "text/plain") {
+      return {
+        ok: false,
+        status: input.status,
+        kind: "not_hub",
+        detail: `HTTP ${input.status} content-type ${contentType} is not application/json`,
+        body: { error: "not_hub", detail: contentType },
+      };
+    }
+    return { ok: true, status: input.status, kind: "hub", detail: "kxm hub", body };
+  }
+  const typeNote = contentType && contentType !== "application/json" ? ` content-type ${contentType}` : "";
+  return {
+    ok: false,
+    status: input.status,
+    kind: "not_hub",
+    detail: `HTTP ${input.status}${typeNote} is not a kxm hub ${input.role} response`,
+    body: { error: "not_hub", detail: `HTTP ${input.status}${typeNote}` },
+  };
+}
+
+export async function readHubEndpoint(
+  url: string,
+  role: "health" | "ready",
+  fetchImpl: typeof fetch,
+  init: { headers?: Record<string, string>; signal?: AbortSignal } = {},
+): Promise<HubEndpointVerdict> {
   try {
-    rmSync(file);
-    return true;
+    const response = await fetchImpl(`${url}/${role}`, {
+      ...(init.headers ? { headers: init.headers } : {}),
+      ...(init.signal ? { signal: init.signal } : {}),
+      redirect: "manual",
+    });
+    const bodyText = await response.text();
+    return classifyHubResponse({
+      role,
+      status: response.status,
+      contentType: response.headers.get("content-type"),
+      bodyText,
+    });
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
-    throw error;
+    if (isAbortError(error)) {
+      return { ok: false, status: 0, kind: "timeout", detail: "no reply within the probe budget", body: { error: "hub_unreachable" } };
+    }
+    return { ok: false, status: 0, kind: "unreachable", detail: "nothing answered", body: { error: "hub_unreachable" } };
   }
 }
 
@@ -337,25 +594,14 @@ export async function probeHubHealth(
   url: string,
   fetchImpl: typeof fetch,
   timeoutMs = HUB_HEALTH_PROBE_MS,
-): Promise<{ health: HubHealth; probeMs: number }> {
+): Promise<HubProbe> {
   const started = Date.now();
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const response = await fetchImpl(`${url}/health`, { signal: controller.signal });
-    if (!response.ok) return { health: "unknown", probeMs: Date.now() - started };
-    let body: unknown;
-    try {
-      body = await response.json();
-    } catch {
-      return { health: "unknown", probeMs: Date.now() - started };
-    }
-    if (body && typeof body === "object" && (body as { ok?: unknown }).ok === true) {
-      return { health: "on", probeMs: Date.now() - started };
-    }
-    return { health: "unknown", probeMs: Date.now() - started };
-  } catch (error) {
-    return { health: isAbortError(error) ? "unknown" : "off", probeMs: Date.now() - started };
+    const verdict = await readHubEndpoint(url, "health", fetchImpl, { signal: controller.signal });
+    const health: HubHealth = verdict.kind === "hub" ? "on" : verdict.kind === "unreachable" ? "off" : "unknown";
+    return { health, probeMs: Date.now() - started, kind: verdict.kind, detail: verdict.detail, status: verdict.status };
   } finally {
     clearTimeout(timer);
   }

package/plugins/kxm/src/hub-identity.ts

@@ -210,18 +210,26 @@ function keySourceFor(input: {
   hasSavedProjectToken?: (project: string) => boolean;
 }): string {
   const ref = input.endpoint?.key;
-  if (input.mode === "local" && input.env.KXM_AUTH_TOKEN?.trim()) return "env:KXM_AUTH_TOKEN";
-  if (ref?.env && input.env[ref.env]?.trim()) return `env:${ref.env}`;
-  if (ref?.op) return `op:${ref.op}`;
-  if (ref?.env) return `env:${ref.env}`;
+  const envName = (name: string | undefined): string | undefined => {
+    if (!name) return undefined;
+    return input.env[name]?.trim() ? `env:${name}` : undefined;
+  };
+  // Name the source that would actually supply a token. An unset variable is
+  // not that source, even when config still lists it.
   if (input.mode === "cloud") {
-    if (input.binding?.tokenEnv) return `env:${input.binding.tokenEnv}`;
-    if (input.binding?.tokenCommand) {
-      const op = opReferenceFromTokenCommand(input.binding.tokenCommand);
-      return op ? `op:${op}` : "command";
-    }
+    const fromEnv = envName(ref?.env);
+    if (fromEnv) return fromEnv;
+    if (ref?.op) return `op:${ref.op}`;
+    const fromBindingEnv = envName(input.binding?.tokenEnv);
+    if (fromBindingEnv) return fromBindingEnv;
+    if (input.binding?.tokenCommand) return "token-command";
     return "missing";
   }
+  const fromAuth = envName("KXM_AUTH_TOKEN");
+  if (fromAuth) return fromAuth;
+  const fromEnv = envName(ref?.env);
+  if (fromEnv) return fromEnv;
+  if (ref?.op) return `op:${ref.op}`;
   if (input.hasSavedProjectToken?.(input.project)) return "hub-env";
   return "missing";
 }