@kontextmind/kxm 0.7.165 → 0.7.166

package/plugins/kxm/src/config.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { tmpdir, homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { parse, stringify } from "yaml";
 import { redactSecrets } from "./redact.ts";
@@ -47,10 +47,55 @@ export interface KxmSyncTrackerConfig {
 
 export type KxmHubAutoStart = "off" | "background";
 
+export type KxmHubMode = "local" | "cloud";
+
+/** A secret reference. `op` is an `op://` reference resolved with `op read` at
+ * use time. `env` is an environment variable name. Neither field holds a token. */
+export interface HubKeyRef {
+  op?: string;
+  env?: string;
+}
+
+/** One hub endpoint. `project` is the id presented to that hub. `key` is a
+ * reference, never a literal token. */
+export interface HubEndpointConfig {
+  url?: string;
+  project?: string;
+  key?: HubKeyRef;
+}
+
 export interface KxmHubConfig {
   /** Pi extension hub startup: `background` starts a detached hub when no
    * healthy bound hub or live local claim exists; `off` never starts one. */
   autoStart: KxmHubAutoStart;
+  /** Which endpoint is in effect. Unset means local unless a cloud binding says otherwise. */
+  mode?: KxmHubMode;
+  local?: HubEndpointConfig;
+  cloud?: HubEndpointConfig;
+  /** Hub-process project id to key reference. Resolved in memory; never persisted. */
+  projects?: Record<string, HubKeyRef>;
+}
+
+/** A hub config value is a token, or a key reference that is not an `op://` ref or an env var name. */
+export class KxmHubConfigError extends Error {
+  readonly code = "hub_config_invalid";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "KxmHubConfigError";
+  }
+}
+
+const HUB_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const HUB_OP_REF = /^op:\/\/\S+\/\S+\/\S+$/;
+const LITERAL_SECRET_KEY = /^(token|secret|password|authToken|auth_token|apiKey|api_key|api_token|bearer|credential|access_token)$/i;
+
+export function isHubKeyEnvName(value: string): boolean {
+  return HUB_ENV_NAME.test(value);
+}
+
+export function isHubOpReference(value: string): boolean {
+  return HUB_OP_REF.test(value);
 }
 
 export type ImprovementPromotionPolicy = "manual_pr" | "critic_quorum" | "auto_threshold";
@@ -191,11 +236,174 @@ function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<
   return result as T;
 }
 
+function literalSecretMessage(path: string): string {
+  return `refusing literal hub token at ${path}: store an op:// reference (key.op) or an environment variable name (key.env), never the token`;
+}
+
+function rejectLiteralHubSecrets(value: unknown, path: string): void {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => rejectLiteralHubSecrets(item, `${path}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    const childPath = `${path}.${key}`;
+    if (typeof child === "string" && (key === "key" || LITERAL_SECRET_KEY.test(key))) {
+      throw new KxmHubConfigError(literalSecretMessage(childPath));
+    }
+    if (child && typeof child === "object") rejectLiteralHubSecrets(child, childPath);
+  }
+}
+
+function parseKeyRef(raw: unknown, path: string): HubKeyRef | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw === "string") throw new KxmHubConfigError(literalSecretMessage(path));
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new KxmHubConfigError(`${path} must be a key reference with op and/or env, never a token`);
+  }
+  const row = raw as Record<string, unknown>;
+  for (const key of Object.keys(row)) {
+    if (key !== "op" && key !== "env") {
+      throw new KxmHubConfigError(literalSecretMessage(`${path}.${key}`));
+    }
+  }
+  const ref: HubKeyRef = {};
+  if (row.op !== undefined) {
+    if (typeof row.op !== "string" || !isHubOpReference(row.op)) {
+      throw new KxmHubConfigError(`${path}.op must be an op://vault/item/field reference, not a token`);
+    }
+    ref.op = row.op;
+  }
+  if (row.env !== undefined) {
+    if (typeof row.env !== "string" || !isHubKeyEnvName(row.env)) {
+      throw new KxmHubConfigError(`${path}.env must be an environment variable name, not a token`);
+    }
+    ref.env = row.env;
+  }
+  if (!ref.op && !ref.env) throw new KxmHubConfigError(`${path} needs key.op, key.env, or both`);
+  return ref;
+}
+
+function parseEndpoint(raw: unknown, path: string): HubEndpointConfig | undefined {
+  if (raw === undefined) return undefined;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new KxmHubConfigError(`${path} must be an object with url, project, and key`);
+  }
+  const row = raw as Record<string, unknown>;
+  const endpoint: HubEndpointConfig = {};
+  if (row.url !== undefined) {
+    if (typeof row.url !== "string" || !isHubUrl(row.url)) {
+      throw new KxmHubConfigError(`${path}.url must be an http or https URL without credentials, query, or fragment`);
+    }
+    endpoint.url = row.url.replace(/\/$/, "");
+  }
+  if (row.project !== undefined) {
+    if (typeof row.project !== "string" || !isHubProjectId(row.project)) {
+      throw new KxmHubConfigError(`${path}.project must be a single-line project id, not a token`);
+    }
+    endpoint.project = row.project.trim();
+  }
+  const key = parseKeyRef(row.key, `${path}.key`);
+  if (key) endpoint.key = key;
+  for (const name of Object.keys(row)) {
+    if (name !== "url" && name !== "project" && name !== "key") {
+      if (typeof row[name] === "string") throw new KxmHubConfigError(literalSecretMessage(`${path}.${name}`));
+      throw new KxmHubConfigError(`${path}.${name} is not a hub endpoint field`);
+    }
+  }
+  return endpoint;
+}
+
+function isHubUrl(raw: string): boolean {
+  try {
+    const parsed = new URL(raw);
+    return (parsed.protocol === "http:" || parsed.protocol === "https:")
+      && parsed.username === ""
+      && parsed.password === ""
+      && parsed.search === ""
+      && parsed.hash === ""
+      && !raw.includes("?")
+      && !raw.includes("#");
+  } catch {
+    return false;
+  }
+}
+
+function isHubProjectId(raw: string): boolean {
+  const value = raw.trim();
+  return value.length > 0 && value.length <= 200 && !/[\s\r\n]/.test(value);
+}
+
+function parseProjectMap(raw: unknown): Record<string, HubKeyRef> | undefined {
+  if (raw === undefined) return undefined;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new KxmHubConfigError("hub.projects must be a map of project id to key reference, never a token");
+  }
+  const projects: Record<string, HubKeyRef> = {};
+  for (const [project, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!isHubProjectId(project)) {
+      throw new KxmHubConfigError(`hub.projects key ${JSON.stringify(project)} must be a project id, not a token`);
+    }
+    const ref = parseKeyRef(value, `hub.projects.${project}`);
+    if (!ref) throw new KxmHubConfigError(`hub.projects.${project} needs an op:// reference or an environment variable name`);
+    projects[project.trim()] = ref;
+  }
+  return projects;
+}
+
 /** Unknown `hub.autoStart` values fail closed to the default so a config typo
- * never silently changes hub startup behavior. */
+ * never silently changes hub startup behavior. Literal tokens under `hub` are
+ * refused. Key references stay unresolved. */
 function normalizeHubConfig(raw: unknown): KxmHubConfig {
   const autoStart = (raw as { autoStart?: unknown } | undefined)?.autoStart;
-  return { autoStart: autoStart === "off" || autoStart === "background" ? autoStart : DEFAULT_KXM_CONFIG.hub.autoStart };
+  const hub: KxmHubConfig = {
+    autoStart: autoStart === "off" || autoStart === "background" ? autoStart : DEFAULT_KXM_CONFIG.hub.autoStart,
+  };
+  if (raw === undefined) return hub;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new KxmHubConfigError("hub must be an object");
+  }
+  rejectLiteralHubSecrets(raw, "hub");
+  const row = raw as Record<string, unknown>;
+  if (row.mode !== undefined) {
+    if (row.mode !== "local" && row.mode !== "cloud") {
+      throw new KxmHubConfigError("hub.mode must be local or cloud");
+    }
+    hub.mode = row.mode;
+  }
+  const local = parseEndpoint(row.local, "hub.local");
+  const cloud = parseEndpoint(row.cloud, "hub.cloud");
+  const projects = parseProjectMap(row.projects);
+  if (local) hub.local = local;
+  if (cloud) hub.cloud = cloud;
+  if (projects && Object.keys(projects).length > 0) hub.projects = projects;
+  return hub;
+}
+
+/** Directory that holds this checkout's `.kxm/` config: the nearest
+ * `project.yaml` or `config.yaml`, otherwise `start`. */
+export function findConfigRoot(start: string): string {
+  let dir = resolve(start);
+  for (;;) {
+    if (existsSync(join(dir, ".kxm", "project.yaml")) || existsSync(join(dir, ".kxm", "config.yaml"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(start);
+    dir = parent;
+  }
+}
+
+/** User config directory for this env. A partial env (tests, a command env
+ * that is not the process env) does not read `~/.config/kxm`. */
+export function userConfigDirForEnv(env: NodeJS.ProcessEnv): string | undefined {
+  const explicit = env.KXM_USER_CONFIG_DIR?.trim();
+  if (explicit) return explicit;
+  if (env === process.env) return undefined;
+  return join(tmpdir(), "kxm-no-user-config");
+}
+
+export function loadHubSettings(start: string, env: NodeJS.ProcessEnv = process.env): KxmHubConfig {
+  const userConfigDir = userConfigDirForEnv(env);
+  return loadKxmConfig(findConfigRoot(start), userConfigDir === undefined ? {} : { userConfigDir }).hub;
 }
 
 function recordOf(raw: unknown): Record<string, unknown> {
@@ -352,10 +560,45 @@ export function setKxmConfigValue(
     cursor = cursor[p] as Record<string, unknown>;
   }
   cursor[parts[parts.length - 1]!] = value;
+  if (parts[0] === "hub") normalizeHubConfig(existing.hub);
   if (!options.dryRun) writeConfigFile(targetFile, existing);
   return { file: targetFile };
 }
 
+/** Record the non-secret parts of a hub bind: mode, URL, project id, and key
+ * reference. The resolved token is never written. */
+export function writeHubEndpoint(
+  start: string,
+  endpoint: { mode: KxmHubMode; url: string; project: string; key?: HubKeyRef },
+): { file: string } {
+  if (!isHubUrl(endpoint.url)) {
+    throw new KxmHubConfigError("hub url must be an http or https URL without credentials, query, or fragment");
+  }
+  if (!isHubProjectId(endpoint.project)) {
+    throw new KxmHubConfigError("hub project id must be a single-line project id, not a token");
+  }
+  if (endpoint.key) parseKeyRef(endpoint.key, `hub.${endpoint.mode}.key`);
+  const root = findConfigRoot(start);
+  const file = join(root, ".kxm", "config.yaml");
+  const existing = readConfigFile(file);
+  const hub = recordOf(existing.hub);
+  const current = recordOf(hub[endpoint.mode]);
+  current.url = endpoint.url.replace(/\/$/, "");
+  current.project = endpoint.project.trim();
+  if (endpoint.key && (endpoint.key.op || endpoint.key.env)) {
+    const key = recordOf(current.key);
+    if (endpoint.key.op) key.op = endpoint.key.op;
+    if (endpoint.key.env) key.env = endpoint.key.env;
+    current.key = key;
+  }
+  hub[endpoint.mode] = current;
+  hub.mode = endpoint.mode;
+  existing.hub = hub;
+  normalizeHubConfig(hub);
+  writeConfigFile(file, existing);
+  return { file };
+}
+
 /**
  * Remove a key so the next scope, then the built-in default, applies.
  *

package/plugins/kxm/src/extension.ts

@@ -7,8 +7,8 @@ import { HubClient, HubHttpError } from "./client.ts";
 import { loadKxmConfig } from "./config.ts";
 import { ensureHubRunning, hubAutoStartMode } from "./hub-autostart.ts";
 import { AgentProjectTokenMissingError, resolveAgentHubAuthToken } from "./hub-env.ts";
-import { CloudTokenError, resolveHubServerUrl } from "./hub-binding.ts";
-import { defaultProjectName } from "./project-name.ts";
+import { CloudTokenError } from "./hub-binding.ts";
+import { describeHubConnection, resolveProjectIdentity } from "./hub-identity.ts";
 import { nousFactoryWork, type NousRegistrationReport } from "./nous-pi.ts";
 import {
   antigravityRegistrationNotice,
@@ -347,7 +347,7 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
   }
 
   async function showKxmHub(ctx: { ui: { notify: (message: string, type: "info" | "warning" | "error") => void } }): Promise<void> {
-    const url = resolveHubServerUrl(process.env);
+    const url = describeHubConnection(process.cwd(), process.env).url;
     let health = "unreachable";
     try {
       const response = await fetch(`${url}/health`);
@@ -677,8 +677,9 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
       return;
     }
     currentPiSessionId = ctx.sessionManager?.getSessionId();
-    const serverUrl = resolveHubServerUrl(process.env);
-    const project = defaultProjectName(ctx.cwd, process.env);
+    const identity = resolveProjectIdentity(ctx.cwd, process.env);
+    const serverUrl = describeHubConnection(ctx.cwd, process.env).url;
+    const project = identity.project;
     const name = process.env.KXM_AGENT_NAME ?? pi.getSessionName() ?? `pi-${process.pid}`;
     agentName = name;
     projectName = project;
@@ -709,7 +710,7 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
     // stand in for a project token.
     let hubAuthToken: string | undefined;
     try {
-      hubAuthToken = resolveAgentHubAuthToken(process.env, project);
+      hubAuthToken = resolveAgentHubAuthToken(process.env, project, ctx.cwd);
     } catch (error) {
       const detail = error instanceof CloudTokenError
         ? error.message
@@ -719,7 +720,7 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
       return;
     }
     if (!hubAuthToken) {
-      ctx.ui.notify(new AgentProjectTokenMissingError(project).message, "error");
+      ctx.ui.notify(new AgentProjectTokenMissingError(identity).message, "error");
       await applySessionChrome(ctx, event, true);
       return;
     }

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

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { probeHubHealth, readHubBinding } from "./hub-binding.ts";
+import { describeHubConnection } from "./hub-identity.ts";
 import { resolveHubCredentials } from "./hub-env.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { redactSecrets } from "./redact.ts";
@@ -138,6 +139,25 @@ export async function ensureHubRunning(options: EnsureHubOptions): Promise<Ensur
     if (binding.cloud) return { status: "failed", reason: "cloud_hub_unreachable", logPath: "" };
   }
 
+  // A cloud endpoint in config is the same rule when no cloud binding is on disk:
+  // a dead forward must not start a local hub.
+  if (!binding?.cloud) {
+    try {
+      const connection = describeHubConnection(options.cwd, env);
+      if (connection.mode === "cloud") {
+        const { health } = await probeHubHealth(connection.url, fetchImpl);
+        if (health === "on") return { status: "bound-healthy", url: connection.url };
+        return { status: "failed", reason: "cloud_hub_unreachable", logPath: "" };
+      }
+    } catch (error) {
+      return {
+        status: "failed",
+        reason: error instanceof Error ? error.message : "hub_config_invalid",
+        logPath: "",
+      };
+    }
+  }
+
   // 2. A live local claim means a hub (started any way) already owns this
   //    workspace state — do not start a second one.
   const workdir = resolve(env.KXM_WORKDIR?.trim() || options.cwd);

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

@@ -2,6 +2,14 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { loadHubSettings } from "./config.ts";
+import {
+  describeHubConnection,
+  projectTokenMissingMessage,
+  resolveKeyReference,
+  type OpReader,
+  type ProjectIdentity,
+} from "./hub-identity.ts";
 import {
   CloudTokenError,
   HubBindingError,
@@ -10,7 +18,6 @@ import {
   resolveCloudHubToken,
   type HubBindingRecord,
 } from "./hub-binding.ts";
-import { defaultProjectName } from "./project-name.ts";
 
 export const HUB_ENV_SCHEMA = "kxm.hub-env.v1" as const;
 
@@ -239,9 +246,13 @@ function activeCloudBinding(env: NodeJS.ProcessEnv): HubBindingRecord | undefine
  * Non-cloud keeps the historical rule: only the explicit `KXM_AUTH_TOKEN`, never hub-env.
  * A cloud binding uses its named source and nothing else.
  */
-export function resolveControlPlaneAuthToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
-  const cloud = activeCloudBinding(env);
-  if (cloud) return resolveCloudHubToken(cloud, env);
+export function resolveControlPlaneAuthToken(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+  opRead?: OpReader,
+): string | undefined {
+  const cloud = cloudModeToken(cwd, env, undefined, opRead);
+  if (cloud) return cloud;
   return env.KXM_AUTH_TOKEN?.trim() || undefined;
 }
 
@@ -250,29 +261,46 @@ export function resolveControlPlaneAuthToken(env: NodeJS.ProcessEnv = process.en
  * The project id comes from the shared resolver. A cloud binding adds
  * `KXM_AUTH_TOKEN` in this object only — it is never written to the binding.
  */
+function cloudModeToken(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  explicitProject?: string,
+  opRead?: OpReader,
+): string | undefined {
+  const connection = describeHubConnection(cwd, env, explicitProject === undefined ? {} : { explicitProject });
+  if (connection.mode !== "cloud") return undefined;
+  const fromConfig = resolveKeyReference(connection.endpoint?.key, env, opRead);
+  if (fromConfig) return fromConfig.value;
+  if (connection.binding?.cloud) return resolveCloudHubToken(connection.binding, env);
+  throw new CloudTokenError(
+    "cloud_token_missing",
+    "cloud hub token is missing; the local hub-env token was not used",
+  );
+}
+
 export function agentSessionEnv(
   cwd: string,
   env: NodeJS.ProcessEnv = process.env,
   explicitProject?: string,
+  opRead?: OpReader,
 ): NodeJS.ProcessEnv {
-  const project = defaultProjectName(cwd, env, explicitProject);
-  const cloud = activeCloudBinding(env);
-  let serverUrl = env.KXM_SERVER_URL?.trim();
-  if (!serverUrl) {
-    try {
-      serverUrl = readHubBinding(env)?.url;
-    } catch (error) {
-      if (!(error instanceof HubBindingError)) throw error;
-    }
+  const connection = describeHubConnection(cwd, env, explicitProject === undefined ? {} : { explicitProject });
+  const session: NodeJS.ProcessEnv = { KXM_PROJECT: connection.project };
+  if (connection.url) session.KXM_SERVER_URL = connection.url.replace(/\/$/, "");
+  if (connection.mode === "cloud") {
+    const token = cloudModeToken(cwd, env, explicitProject, opRead);
+    if (token) session.KXM_AUTH_TOKEN = token;
   }
-  const session: NodeJS.ProcessEnv = { KXM_PROJECT: project };
-  if (serverUrl) session.KXM_SERVER_URL = serverUrl.replace(/\/$/, "");
-  if (cloud) session.KXM_AUTH_TOKEN = resolveCloudHubToken(cloud, env);
   return session;
 }
 
-export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, project?: string): boolean {
+export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, project?: string, cwd: string = process.cwd()): boolean {
   if (env.KXM_AUTH_TOKEN?.trim()) return true;
+  const settings = loadHubSettings(cwd, env);
+  const mode = settings.mode ?? (activeCloudBinding(env) ? "cloud" : "local");
+  const key = (mode === "cloud" ? settings.cloud : settings.local)?.key;
+  if (key?.op) return true;
+  if (key?.env && env[key.env]?.trim()) return true;
   let record: HubEnvRecord | undefined;
   try {
     record = readHubEnvRecord(env);
@@ -289,11 +317,18 @@ export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, pro
   return Object.values(tokens).some((token) => typeof token === "string" && token.trim().length > 0);
 }
 
-export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: string): string | undefined {
-  const cloud = activeCloudBinding(env);
-  if (cloud) return resolveCloudHubToken(cloud, env);
+export function resolveClientHubAuthToken(
+  env: NodeJS.ProcessEnv,
+  project: string,
+  cwd: string = process.cwd(),
+  opRead?: OpReader,
+): string | undefined {
+  const cloud = cloudModeToken(cwd, env, undefined, opRead);
+  if (cloud) return cloud;
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
+  const fromConfig = resolveKeyReference(describeHubConnection(cwd, env).endpoint?.key, env, opRead);
+  if (fromConfig) return fromConfig.value;
   const record = readHubEnvRecord(env);
   return record?.projectTokens?.[project]?.trim() || record?.authToken?.trim() || undefined;
 }
@@ -307,13 +342,20 @@ export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: strin
  * token for. Operator tools keep `resolveClientHubAuthToken`. Throws HubEnvError on a
  * malformed persisted record, same as `resolveClientHubAuthToken`.
  */
-export function resolveAgentHubAuthToken(env: NodeJS.ProcessEnv, project: string): string | undefined {
-  const cloud = activeCloudBinding(env);
+export function resolveAgentHubAuthToken(
+  env: NodeJS.ProcessEnv,
+  project: string,
+  cwd: string = process.cwd(),
+  opRead?: OpReader,
+): string | undefined {
+  const cloud = cloudModeToken(cwd, env, undefined, opRead);
   // A cloud binding's token is the remote hub's credential. It is not this
   // machine's hub-env admin token, which an agent must still never use.
-  if (cloud) return resolveCloudHubToken(cloud, env);
+  if (cloud) return cloud;
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
+  const fromConfig = resolveKeyReference(describeHubConnection(cwd, env).endpoint?.key, env, opRead);
+  if (fromConfig) return fromConfig.value;
   const tokens = readHubEnvRecord(env)?.projectTokens;
   if (!tokens || !Object.hasOwn(tokens, project)) return undefined;
   return tokens[project]?.trim() || undefined;
@@ -326,13 +368,19 @@ export function resolveAgentHubAuthToken(env: NodeJS.ProcessEnv, project: string
 export class AgentProjectTokenMissingError extends Error {
   readonly code = "project_token_missing";
   readonly project: string;
+  readonly projectSource: ProjectIdentity["source"] | "unknown";
+  readonly hint: string;
 
-  constructor(project: string) {
-    super(
-      `kxm has no project token for project ${project} on this machine. Set KXM_AUTH_TOKEN to that project's token, or add ${project} to the hub KXM_PROJECT_TOKENS (list every existing project too, because that variable replaces the saved map). An agent never uses the hub admin token.`,
-    );
+  constructor(projectOrIdentity: string | ProjectIdentity) {
+    const identity: ProjectIdentity = typeof projectOrIdentity === "string"
+      ? { project: projectOrIdentity, source: "env", sourceLabel: "the project id sent to the hub" }
+      : projectOrIdentity;
+    const message = projectTokenMissingMessage(identity);
+    super(message);
     this.name = "AgentProjectTokenMissingError";
-    this.project = project;
+    this.project = identity.project;
+    this.projectSource = typeof projectOrIdentity === "string" ? "unknown" : identity.source;
+    this.hint = message;
   }
 }
 
@@ -343,9 +391,13 @@ export class AgentProjectTokenMissingError extends Error {
  * refuse — handing the portal a 401 dressed as "configured" is worse than handing it none.
  * Throws on a malformed persisted record, same as `resolveClientHubAuthToken`.
  */
-export function resolveClientAdminAuthToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
-  const cloud = activeCloudBinding(env);
-  if (cloud) return resolveCloudHubToken(cloud, env);
+export function resolveClientAdminAuthToken(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+  opRead?: OpReader,
+): string | undefined {
+  const cloud = cloudModeToken(cwd, env, undefined, opRead);
+  if (cloud) return cloud;
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
   return readHubEnvRecord(env)?.authToken?.trim() || undefined;