@kontextmind/kxm 0.7.164 → 0.7.166

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.164",
+  "version": "0.7.166",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm-hub-ops/SKILL.md

@@ -46,7 +46,7 @@ the hub admin token or a project token.
 |---|---|---|
 | `kxm hub start` | Start the hub in the foreground | `--json` |
 | `kxm hub stop` | Request managed hub and worker shutdown | `--wait-ms <ms>` |
-| `kxm hub bind <url>` | Bind this machine to a running hub | http or https URL |
+| `kxm hub bind <url>` | Bind this machine to a running hub and record the non-secret endpoint in `.kxm/config.yaml` | http or https URL. `--token-env` and `--key-op` for either mode. `--cloud` with `--token-env`, `--token-command`, or `--key-op` for an SSH forward to loopback. The token is not stored |
 | `kxm hub unbind` | Remove this machine's hub binding | `--json` |
 | `kxm restore <manifest>` | Replace this project's live stores from a verified backup manifest | `--all-projects`, `--json` |
 
@@ -60,15 +60,27 @@ kxm restore .kxm/backups/pre-upgrade/manifest.json
   `KXM_AUTH_TOKEN` is unset it generates a long random admin token once and
   persists it in `hub-env.json` (schema `kxm.hub-env.v1`, mode `0600`) under
   the user state root, then reuses it on every restart.
-- `KXM_PROJECT_TOKENS` must list every project's token. It replaces the saved
-  token map rather than merging with it, and the replacement is saved. When a
-  hub already serves other projects, build the full map with the merge
-  command in the KXM documentation's Claude Code quick start
+- `KXM_PROJECT_TOKENS` must list every project's token when it is set. It
+  replaces the saved token map rather than merging with it, and the
+  replacement is saved. The same map can instead live in `.kxm/config.yaml`
+  as `hub.projects`, with `op://` references or environment variable names.
+  That map is resolved in memory and is not saved. When a hub already serves
+  other projects, build the full map with the merge command in the KXM
+  documentation's Claude Code quick start
   (docs/start/quickstart-claude-code.md, section "Start the hub") before
   restarting the hub.
+- `kxm hub view` prints the mode, URL, project id, and key source. It does
+  not print the token. The project id is the flag, then `KXM_PROJECT`, then
+  `hub.local.project` or `hub.cloud.project`, then `.kxm/project.yaml`, then
+  the package name, then the directory name.
 - `kxm hub bind` to a remote (non-loopback) URL fails closed with
   `hub_bind_unauthenticated` unless a credential for the current project
   resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`.
+- `kxm hub bind --cloud` is the bind for a loopback SSH forward of a remote
+  hub. It never falls back to this machine's hub-env token. Pass
+  `--token-env KXMD_HUB_TOKEN`, `--key-op op://Private/kxmd/project-token`,
+  or `--token-command "op read op://..."`. The non-secret fields are written
+  to `.kxm/config.yaml`. See docs/operations.md, section "Cross-box peer attach".
 - Hub PID claims record the wrapper and server child PID. A dead wrapper's
   claim is reclaimed automatically, an orphaned server is terminated first,
   and `kxm hub stop` recovers such orphans directly.

package/plugins/kxm/src/cli/context-skills.ts

@@ -10,6 +10,8 @@ import {
 } from "../memory.ts";
 import { SkillLifecycle, type SkillEvaluationKind, type SkillState } from "../skills.ts";
 import { writeCompiledWiki } from "../wiki.ts";
+import { CloudTokenError } from "../hub-binding.ts";
+import { resolveControlPlaneAuthToken } from "../hub-env.ts";
 import { print, printPlan, type Runtime } from "./types.ts";
 
 /** Authenticated hub POST for context operations. The CLI operates as the
@@ -19,13 +21,33 @@ export async function hubContextPost(input: {
   path: string;
   body: Record<string, unknown>;
   authToken?: string | undefined;
+  /** When set, a cloud binding's token source replaces the explicit env token. */
+  env?: NodeJS.ProcessEnv | undefined;
+  command?: string | undefined;
+  io?: Runtime["io"] | undefined;
+  json?: boolean | undefined;
   fetchImpl: typeof fetch;
-}): Promise<{ ok: boolean; status: number; body: unknown }> {
+}): Promise<{ ok: boolean; status: number; body: unknown; exitCode?: number }> {
+  let authToken = input.authToken;
+  if (input.env) {
+    try {
+      authToken = resolveControlPlaneAuthToken(input.env);
+    } catch (error) {
+      if (error instanceof CloudTokenError) {
+        const command = input.command ?? "context";
+        if (input.io) {
+          print(input.io, Boolean(input.json), { ok: false, command, error: error.code, detail: error.message }, error.message);
+        }
+        return { ok: false, status: 0, body: { error: error.code, detail: error.message }, exitCode: 2 };
+      }
+      throw error;
+    }
+  }
   const response = await input.fetchImpl(`${input.serverUrl.replace(/\/$/, "")}${input.path}`, {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      ...(input.authToken ? { authorization: `Bearer ${input.authToken}` } : {}),
+      ...(authToken ? { authorization: `Bearer ${authToken}` } : {}),
     },
     body: JSON.stringify(input.body),
   });
@@ -64,9 +86,13 @@ export async function cmdContextGet(runtime: Runtime, project: string, options:
     serverUrl: runtime.serverUrl,
     path: "/v1/context/get",
     body,
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
+    env: runtime.env,
+    command: "context",
+    io: runtime.io,
+    json: runtime.json,
     fetchImpl: runtime.fetchImpl,
   });
+  if (response.exitCode) return response.exitCode;
   print(runtime.io, runtime.json, { ok: response.ok, command: "context get", status: response.status, ...(response.body as object) }, `context get ${response.ok ? "assembled" : `failed (${response.status})`}`);
   return response.ok ? 0 : 1;
 }
@@ -81,9 +107,13 @@ export async function cmdContextRecall(runtime: Runtime, project: string, option
     serverUrl: runtime.serverUrl,
     path: "/v1/context/recall",
     body,
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
+    env: runtime.env,
+    command: "context",
+    io: runtime.io,
+    json: runtime.json,
     fetchImpl: runtime.fetchImpl,
   });
+  if (response.exitCode) return response.exitCode;
   print(runtime.io, runtime.json, { ok: response.ok, command: "context recall", status: response.status, ...(response.body as object) }, `context recall ${response.ok ? "complete" : `failed (${response.status})`}`);
   return response.ok ? 0 : 1;
 }
@@ -95,9 +125,13 @@ export async function cmdContextState(runtime: Runtime, project: string, key: st
     serverUrl: runtime.serverUrl,
     path: "/v1/context/state",
     body,
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
+    env: runtime.env,
+    command: "context",
+    io: runtime.io,
+    json: runtime.json,
     fetchImpl: runtime.fetchImpl,
   });
+  if (response.exitCode) return response.exitCode;
   print(runtime.io, runtime.json, { ok: response.ok, command: "context state", status: response.status, ...(response.body as object) }, `context state ${response.ok ? "resolved" : `failed (${response.status})`}`);
   return response.ok ? 0 : 1;
 }
@@ -109,9 +143,13 @@ export async function cmdContextEpisode(runtime: Runtime, project: string, optio
     serverUrl: runtime.serverUrl,
     path: "/v1/context/episode",
     body,
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
+    env: runtime.env,
+    command: "context",
+    io: runtime.io,
+    json: runtime.json,
     fetchImpl: runtime.fetchImpl,
   });
+  if (response.exitCode) return response.exitCode;
   print(runtime.io, runtime.json, { ok: response.ok, command: "context episode", status: response.status, ...(response.body as object) }, `context episode ${response.ok ? "complete" : `failed (${response.status})`}`);
   return response.ok ? 0 : 1;
 }
@@ -135,9 +173,13 @@ export async function cmdContextPromote(runtime: Runtime, project: string, propo
     serverUrl: runtime.serverUrl,
     path: "/v1/context/state/promote",
     body: { project, proposalId, evidence },
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
+    env: runtime.env,
+    command: "context",
+    io: runtime.io,
+    json: runtime.json,
     fetchImpl: runtime.fetchImpl,
   });
+  if (response.exitCode) return response.exitCode;
   print(runtime.io, runtime.json, { ok: response.ok, command: "context promote", status: response.status, ...(response.body as object) }, `context promote ${response.ok ? "recorded" : `failed (${response.status})`}`);
   return response.ok ? 0 : 1;
 }
@@ -147,9 +189,13 @@ export async function cmdContextExplain(runtime: Runtime, project: string, itemI
     serverUrl: runtime.serverUrl,
     path: "/v1/context/explain",
     body: { project, id: itemId },
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
+    env: runtime.env,
+    command: "context",
+    io: runtime.io,
+    json: runtime.json,
     fetchImpl: runtime.fetchImpl,
   });
+  if (response.exitCode) return response.exitCode;
   print(runtime.io, runtime.json, { ok: response.ok, command: "context explain", status: response.status, ...(response.body as object) }, `context explain ${response.ok ? "complete" : `failed (${response.status})`}`);
   return response.ok ? 0 : 1;
 }
@@ -159,9 +205,13 @@ export async function cmdContextWikiCompile(runtime: Runtime, project: string, o
     serverUrl: runtime.serverUrl,
     path: "/v1/context/wiki/compile",
     body: { project },
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
+    env: runtime.env,
+    command: "context",
+    io: runtime.io,
+    json: runtime.json,
     fetchImpl: runtime.fetchImpl,
   });
+  if (response.exitCode) return response.exitCode;
   if (!response.ok) {
     print(runtime.io, runtime.json, { ok: false, command: "context wiki-compile", status: response.status, body: response.body }, `wiki compile failed (${response.status})`);
     return 1;
@@ -191,9 +241,13 @@ export async function cmdContextWikiLint(runtime: Runtime, project: string): Pro
     serverUrl: runtime.serverUrl,
     path: "/v1/context/wiki/compile",
     body: { project },
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
+    env: runtime.env,
+    command: "context",
+    io: runtime.io,
+    json: runtime.json,
     fetchImpl: runtime.fetchImpl,
   });
+  if (response.exitCode) return response.exitCode;
   if (!response.ok) {
     print(runtime.io, runtime.json, { ok: false, command: "context wiki-lint", status: response.status, body: response.body }, `wiki lint failed (${response.status})`);
     return 1;

package/plugins/kxm/src/cli/hub.ts

@@ -3,20 +3,27 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 import { join, resolve } from "node:path";
 import { redactSecrets } from "../redact.ts";
 import { defaultProjectName } from "../project-name.ts";
-import { hasClientHubCredential, resolveClientHubAuthToken } from "../hub-env.ts";
+import { agentSessionEnv, hasClientHubCredential, HubEnvError, readHubEnvRecord, resolveClientHubAuthToken } from "../hub-env.ts";
+import { deleteKxmConfigValue, findConfigRoot, isHubOpReference, KxmHubConfigError, writeHubEndpoint } from "../config.ts";
+import { describeHubConnection, opReferenceFromTokenCommand, resolveProjectIdentity } from "../hub-identity.ts";
 import { agentWorker, type Worker } from "../envelope.ts";
 import { MESH_TUI_PANELS, runMeshTui, type MeshTuiPanel } from "../tui.ts";
 import { formatSessionBriefText, loadSessionBriefAsync, readCachedSessionBrief, type SessionHubStatus } from "../session-work.ts";
 import {
   HUB_BINDING_SCHEMA,
+  CloudTokenError,
   HubBindingError,
   hubBindingFile,
   probeHubHealth,
   hubBindingScope,
+  effectiveHubBindingScope,
+  isCloudTokenEnvName,
   readHubBinding,
   removeHubBinding,
+  splitTokenCommand,
   validateHubUrl,
   writeHubBinding,
+  type HubBindingRecord,
   type HubHealth,
 } from "../hub-binding.ts";
 import {
@@ -57,9 +64,13 @@ import {
   type Runtime,
 } from "./types.ts";
 
-export async function hubGet(url: string, fetchImpl: typeof fetch): Promise<{ ok: boolean; status: number; body: unknown }> {
+export async function hubGet(
+  url: string,
+  fetchImpl: typeof fetch,
+  headers?: Record<string, string>,
+): Promise<{ ok: boolean; status: number; body: unknown }> {
   try {
-    const response = await fetchImpl(url);
+    const response = await fetchImpl(url, headers ? { headers } : undefined);
     const text = redactSecrets((await response.text()).slice(0, 8_000));
     let body: unknown = text;
     try {
@@ -147,24 +158,59 @@ export async function refreshKxmUpdateNotice(
 }
 
 export async function cmdStatus(runtime: Runtime): Promise<number> {
-  const health = await hubGet(`${runtime.serverUrl}/health`, runtime.fetchImpl);
-  const ready = await hubGet(`${runtime.serverUrl}/ready`, runtime.fetchImpl);
+  const connection = describeHubConnection(runtime.dirs.workdir, runtime.env, {
+    hasSavedProjectToken: (project) => {
+      try {
+        const token = readHubEnvRecord(runtime.env)?.projectTokens?.[project];
+        return typeof token === "string" && token.trim().length > 0;
+      } catch {
+        return false;
+      }
+    },
+  });
+  let headers: Record<string, string> | undefined;
+  try {
+    if (connection.mode === "cloud") {
+      const token = resolveClientHubAuthToken(runtime.env, connection.project, runtime.dirs.workdir);
+      if (token) headers = { authorization: `Bearer ${token}` };
+    }
+  } catch (error) {
+    if (error instanceof CloudTokenError) {
+      print(runtime.io, runtime.json, { ok: false, command: "hub view", error: error.code, detail: error.message }, error.message);
+      return 2;
+    }
+    if (!(error instanceof HubBindingError)) throw error;
+  }
+  const health = await hubGet(`${runtime.serverUrl}/health`, runtime.fetchImpl, headers);
+  const ready = await hubGet(`${runtime.serverUrl}/ready`, runtime.fetchImpl, headers);
   // Scope on the status line deliberately: "attached across a network" and "attached on
   // this box" are otherwise indistinguishable, and only one of them ships a token.
   // Scope is a property of the URL actually contacted, not of whichever file the
   // binding came from: KXM_SERVER_URL overrides the binding, and labelling the binding
   // while probing an override would report "loopback" about a remote request.
-  const effectiveScope = hubBindingScope(runtime.serverUrl);
-  const overridden = Boolean(runtime.boundHubUrl && runtime.boundHubUrl !== runtime.serverUrl);
+  // A cloud mode is remote when the contacted URL is that endpoint, including a
+  // loopback SSH forward.
+  const effectiveScope = connection.scope;
+  const overridden = connection.urlSource === "env";
+  const identity = {
+    mode: connection.mode,
+    modeSource: connection.modeSource,
+    url: connection.url,
+    urlSource: connection.urlSource,
+    project: connection.project,
+    projectSource: connection.source,
+    keySource: connection.keySource,
+  };
   const payload = {
     ok: health.ok && ready.ok,
     command: "hub view",
     target: { url: runtime.serverUrl, scope: effectiveScope, ...(overridden ? { source: "env" } : {}) },
+    identity,
     health: health.body,
     ready: ready.body,
   };
   print(runtime.io, runtime.json, payload,
-    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""}`);
+    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} · mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}`);
   return payload.ok ? 0 : 1;
 }
 
@@ -191,8 +237,17 @@ export async function cmdDash(runtime: Runtime, options: { screen?: string | und
     runtime.io.stderr("kxm dash does not support --json; use kxm hub view\n");
     return 2;
   }
-  const project = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
-  const authToken = resolveClientHubAuthToken(runtime.env, project);
+  const project = resolveProjectIdentity(runtime.dirs.workdir, runtime.env).project || "project";
+  let authToken: string | undefined;
+  try {
+    authToken = resolveClientHubAuthToken(runtime.env, project, runtime.dirs.workdir);
+  } catch (error) {
+    if (error instanceof CloudTokenError) {
+      print(runtime.io, runtime.json, { ok: false, command: "dash", error: error.code, detail: error.message }, error.message);
+      return 2;
+    }
+    throw error;
+  }
   return await runMeshTui({
     serverUrl: runtime.serverUrl,
     dataPath,
@@ -254,7 +309,14 @@ export function formatHubBindHealth(health: HubHealth): string {
 const HUB_BIND_UNAUTHENTICATED_HINT =
   "export KXM_AUTH_TOKEN (or point KXM_STATE_HOME at the hub-env record that already holds one), then re-run; the hub itself requires a token beyond loopback";
 
-export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<number> {
+export interface HubBindOptions {
+  cloud?: boolean | undefined;
+  tokenEnv?: string | undefined;
+  tokenCommand?: string | undefined;
+  keyOp?: string | undefined;
+}
+
+export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubBindOptions = {}): Promise<number> {
   let url: string;
   try {
     url = validateHubUrl(rawUrl);
@@ -270,7 +332,61 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<numb
     }
     throw error;
   }
-  const scope = hubBindingScope(url);
+  const cloud = options.cloud === true;
+  const tokenEnv = options.tokenEnv?.trim() || undefined;
+  const tokenCommand = options.tokenCommand?.trim() || undefined;
+  const keyOp = options.keyOp?.trim() || opReferenceFromTokenCommand(tokenCommand ?? "") || undefined;
+  if (options.keyOp?.trim() && !isHubOpReference(options.keyOp.trim())) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command: "hub bind", error: "hub_config_invalid", url },
+      "--key-op must be an op://vault/item/field reference, not a token; no binding was written",
+    );
+    return 2;
+  }
+  if (tokenCommand && !cloud) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command: "hub bind", error: "cloud_flag_required", url },
+      "--token-command requires --cloud; no binding was written",
+    );
+    return 2;
+  }
+  if (cloud && !tokenEnv && !tokenCommand && !keyOp) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command: "hub bind", error: "cloud_token_source_required", url },
+      "--cloud needs --token-env, --token-command, --key-op, or a combination; the token is not stored",
+    );
+    return 2;
+  }
+  if (tokenEnv && !isCloudTokenEnvName(tokenEnv)) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command: "hub bind", error: "cloud_token_env_invalid", url },
+      "--token-env must be an environment variable name; no binding was written",
+    );
+    return 2;
+  }
+  if (cloud && tokenCommand) {
+    try {
+      splitTokenCommand(tokenCommand);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "hub bind", error: "cloud_token_command_invalid", url, detail },
+        `${detail}; no binding was written`,
+      );
+      return 2;
+    }
+  }
+  const scope = cloud ? "remote" : hubBindingScope(url);
   // Scope-scoped on purpose, and only for **this command**. A remote binding puts a
   // bearer on a network path, so it is refused when nothing can authenticate it; a
   // stored-but-unusable URL otherwise reads later like a network fault and gets debugged
@@ -280,13 +396,13 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<numb
   // fail `kxm peer list` on loopback. Narrowing the claim is the point; the first version
   // of this guard checked the record *before* the scope and refused loopback binds that had
   // always worked, which is a regression against behaviour predating this slice.
-  if (scope === "remote") {
+  if (!cloud && scope === "remote") {
     // The project that will actually authenticate: a record holding only another
     // project's token cannot authorise this one.
-    const bindProject = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
+    const bindProject = resolveProjectIdentity(runtime.dirs.workdir, runtime.env).project || "project";
     let credentialReady = false;
     try {
-      credentialReady = hasClientHubCredential(runtime.env, bindProject);
+      credentialReady = hasClientHubCredential(runtime.env, bindProject, runtime.dirs.workdir);
     } catch (error) {
       // A malformed record is a readable configuration failure, not an uncaught throw
       // past a user-facing entry point.
@@ -329,14 +445,55 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<numb
     }
   }
   const file = hubBindingFile(runtime.env);
+  const bindingCommand = tokenCommand ?? (cloud && keyOp ? `op read ${keyOp}` : undefined);
+  const cloudFields = cloud
+    ? { cloud: true as const, ...(tokenEnv ? { tokenEnv } : {}), ...(bindingCommand ? { tokenCommand: bindingCommand } : {}) }
+    : {};
+  const record: HubBindingRecord = {
+    schema: HUB_BINDING_SCHEMA,
+    url,
+    boundAt: new Date().toISOString(),
+    ...cloudFields,
+  };
+  const identity = resolveProjectIdentity(runtime.dirs.workdir, runtime.env);
+  const configFile = join(findConfigRoot(runtime.dirs.workdir), ".kxm", "config.yaml");
+  const key = {
+    ...(keyOp ? { op: keyOp } : {}),
+    ...(tokenEnv ? { env: tokenEnv } : {}),
+  };
+  const cloudNote = cloud ? " · token is not stored" : "";
   if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "hub bind", dryRun: true, url, scope, file }, `would bind hub ${url} (${scope})`);
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "hub bind", dryRun: true, url, scope, file, configFile, project: identity.project, ...cloudFields },
+      `would bind hub ${url} (${scope})${cloudNote}`,
+    );
     return 0;
   }
-  writeHubBinding({ schema: HUB_BINDING_SCHEMA, url, boundAt: new Date().toISOString() }, runtime.env);
+  try {
+    writeHubEndpoint(runtime.dirs.workdir, {
+      mode: cloud ? "cloud" : "local",
+      url,
+      project: identity.project,
+      ...(key.op || key.env ? { key } : {}),
+    });
+  } catch (error) {
+    if (error instanceof KxmHubConfigError) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "hub bind", error: error.code, detail: error.message },
+        `${error.message}; no binding was written`,
+      );
+      return 2;
+    }
+    throw error;
+  }
+  writeHubBinding({ ...record, boundAt: new Date().toISOString() }, runtime.env);
   const { health, probeMs } = await probeHubHealth(url, runtime.fetchImpl);
-  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, scope, file, health, probeMs },
-    `bound hub ${url} · ${scope} · ${formatHubBindHealth(health)}${scope === "remote" ? " · token leaves this machine" : ""}`);
+  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, scope, file, configFile, project: identity.project, health, probeMs, ...cloudFields },
+    `bound hub ${url} · ${scope} · ${formatHubBindHealth(health)}${cloud ? cloudNote : scope === "remote" ? " · token leaves this machine" : ""}`);
   return 0;
 }
 
@@ -364,6 +521,7 @@ export async function cmdHubUnbind(runtime: Runtime): Promise<number> {
     return 1;
   }
   removeHubBinding(runtime.env);
+  deleteKxmConfigValue(findConfigRoot(runtime.dirs.workdir), "hub.mode");
   if (malformed) {
     print(runtime.io, runtime.json, { ok: true, command: "hub unbind", file }, "unbound hub (record was malformed)");
     return 0;
@@ -383,7 +541,7 @@ export async function cmdWorker(runtime: Runtime, options: {
   freshStart?: boolean | undefined;
 }): Promise<number> {
   const name = options.name?.trim() || runtime.env.KXM_AGENT_NAME?.trim();
-  const project = options.project?.trim() || runtime.env.KXM_PROJECT?.trim();
+  const project = defaultProjectName(runtime.dirs.workdir, runtime.env, options.project);
   const model = options.model?.trim() || runtime.env.KXM_WORKER_MODEL?.trim();
   const fallbackModels = options.fallbackModels?.trim() || runtime.env.KXM_WORKER_FALLBACK_MODELS?.trim();
   const tools = options.tools?.trim() || runtime.env.KXM_WORKER_TOOLS?.trim();
@@ -392,10 +550,22 @@ export async function cmdWorker(runtime: Runtime, options: {
     runtime.io.stderr("worker --session-isolation must be workflow or off\n");
     return 2;
   }
+  let sessionEnv: NodeJS.ProcessEnv = { KXM_PROJECT: project };
+  if (!runtime.dryRun) {
+    try {
+      sessionEnv = agentSessionEnv(runtime.dirs.workdir, runtime.env, options.project);
+    } catch (error) {
+      if (error instanceof CloudTokenError || error instanceof HubEnvError) {
+        runtime.io.stderr(`${error.message}\n`);
+        return 2;
+      }
+      throw error;
+    }
+  }
   const extraEnv = {
     ...workspaceEnv(runtime),
+    ...sessionEnv,
     ...(name ? { KXM_AGENT_NAME: name } : {}),
-    ...(project ? { KXM_PROJECT: project } : {}),
     ...(model ? { KXM_WORKER_MODEL: model } : {}),
     ...(fallbackModels ? { KXM_WORKER_FALLBACK_MODELS: fallbackModels } : {}),
     ...(tools ? { KXM_WORKER_TOOLS: tools } : {}),
@@ -675,7 +845,7 @@ export async function cmdSessionBrief(runtime: Runtime, options: { status?: bool
       evidence: health === "unknown" ? "timeout" : "probed",
       online: health === "on",
       url: targetUrl,
-      scope: hubBindingScope(targetUrl),
+      scope: effectiveHubBindingScope(targetUrl, runtime.env),
     };
   } else {
     hub = { state: "off", evidence: "unconfigured", online: false };

package/plugins/kxm/src/cli/project.ts

@@ -29,6 +29,8 @@ import {
 import { kxmRuntimePaths, runtimeError } from "../runtime-store.ts";
 import { assembleTenantStatus, formatTenantStatus } from "../tenant-status.ts";
 import { resolveClientAdminAuthToken } from "../hub-env.ts";
+import { defaultProjectName } from "../project-name.ts";
+import { effectiveHubBindingScope } from "../hub-binding.ts";
 import {
   formatHarnessInventory,
   probeHarnessesAsync,
@@ -779,7 +781,7 @@ export async function cmdKxmRunList(runtime: Runtime): Promise<number> {
   }
 }
 
-export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
+export async function cmdTenantStatus(runtime: Runtime, options: { project?: string | undefined } = {}): Promise<number> {
   let projectRoot: string | undefined;
   let projectId: string;
   try {
@@ -789,7 +791,8 @@ export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
       return 1;
     }
     const bundle = loadKxmProject(projectRoot, {});
-    projectId = String(bundle.project.value.id);
+    const yamlProjectId = String(bundle.project.value.id);
+    projectId = defaultProjectName(runtime.cwd, runtime.env, options.project);
     const root = projectRoot;
 
     const payload = await assembleTenantStatus({
@@ -799,6 +802,7 @@ export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
       // and resolve it inside the hub source so a malformed persisted record degrades that
       // one source instead of aborting the Runtime read with it.
       resolveAdminToken: () => resolveClientAdminAuthToken(runtime.env),
+      bindingScope: effectiveHubBindingScope(runtime.serverUrl, runtime.env),
       fetchImpl: runtime.fetchImpl,
       runtime: {
         listRuns: async () => {
@@ -808,7 +812,7 @@ export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
           if (!handle) {
             throw runtimeError("runtime_supervisor_not_running", "runtime", "no live runtime supervisor on this box");
           }
-          const result = await kxmRuntimeRequest(handle, "GET", `/v1/projects/${encodeURIComponent(projectId)}/runs?projectRoot=${encodeURIComponent(root)}`);
+          const result = await kxmRuntimeRequest(handle, "GET", `/v1/projects/${encodeURIComponent(yamlProjectId)}/runs?projectRoot=${encodeURIComponent(root)}`);
           const runs = (result.runs ?? []) as Array<Record<string, unknown>>;
           return runs.map((run) => ({
             runId: String(run.runId ?? ""),

package/plugins/kxm/src/cli/types.ts

@@ -8,9 +8,11 @@ import { gateWorker, workerResult, type Worker, type WorkerOutcome } from "../en
 import { canonicalWorkflowEvidenceKey, type WorkflowEvidenceInput } from "../workflow.ts";
 import {
   HubBindingError,
+  effectiveHubBindingScope,
   hubBindingFile,
   readHubBinding,
 } from "../hub-binding.ts";
+import { describeHubConnection } from "../hub-identity.ts";
 import type { InstallProbe } from "../kxm-install-kind.ts";
 
 export interface CliSpawnResult {
@@ -165,6 +167,16 @@ export function printWorker(
 }
 
 export function hostMode(runtime: Runtime): "local" | "hub" {
+  try {
+    if (describeHubConnection(runtime.cwd, runtime.env).scope === "remote") return "hub";
+  } catch {
+    // A malformed binding is classified from the URL below.
+  }
+  try {
+    if (effectiveHubBindingScope(runtime.serverUrl, runtime.env) === "remote") return "hub";
+  } catch {
+    // A malformed binding is classified from the URL below.
+  }
   try {
     const hostname = new URL(runtime.serverUrl).hostname;
     if (hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1") return "local";
@@ -276,13 +288,14 @@ export function runtimeFrom(ctx: CliContext, command: Command): Runtime {
       throw error;
     }
   }
+  const connection = describeHubConnection(ctx.cwd, ctx.env);
   return {
     ...ctx,
     json: Boolean(opts.json),
     dryRun: Boolean(opts.dryRun),
     ...(opts.workspace === undefined ? {} : { workspaceFlag: opts.workspace }),
     dirs: workspaceDirs(ctx.cwd, opts.workspace, ctx.env),
-    serverUrl: envServerUrl || boundHubUrl || "http://127.0.0.1:7331",
+    serverUrl: connection.url || envServerUrl || boundHubUrl || "http://127.0.0.1:7331",
     ...(boundHubUrl ? { boundHubUrl } : {}),
     fetchImpl: ctx.io.fetchImpl ?? fetch,
   };

package/plugins/kxm/src/cli/workflows.ts

@@ -37,6 +37,8 @@ import {
   type Runtime,
 } from "./types.ts";
 import { resolvePickItem, type PickCandidate } from "./roles.ts";
+import { CloudTokenError } from "../hub-binding.ts";
+import { resolveControlPlaneAuthToken } from "../hub-env.ts";
 
 const CLI_NAME = "kxm";
 
@@ -480,7 +482,16 @@ export async function cmdWorkflowStart(runtime: Runtime, definitionIdArg: string
 export async function cmdWorkflowDegrade(runtime: Runtime, runId: string, stageId: string, options: { requirement?: string | undefined; reason?: string | undefined }): Promise<number> {
   const requirementKey = options.requirement?.trim() ?? "";
   const reason = options.reason?.trim() ?? "";
-  const adminToken = runtime.env.KXM_AUTH_TOKEN?.trim();
+  let adminToken: string | undefined;
+  try {
+    adminToken = resolveControlPlaneAuthToken(runtime.env);
+  } catch (error) {
+    if (error instanceof CloudTokenError) {
+      runtime.io.stderr(`${error.message}\n`);
+      return 2;
+    }
+    throw error;
+  }
   if (!runId || !stageId || !requirementKey || !reason || !adminToken) {
     runtime.io.stderr("workflow degrade requires <runId> <stageId>, --requirement, --reason, and KXM_AUTH_TOKEN\n");
     return 2;