@kontextmind/kxm 0.7.18 → 0.7.20

package/plugins/kxm/dist/mcp-server.js

@@ -7187,9 +7187,6 @@ var require_dist = __commonJS({
   }
 });
 
-// plugins/kxm/src/mcp-server.ts
-import { basename } from "node:path";
-
 // node_modules/zod/v4/core/core.js
 var _a;
 // @__NO_SIDE_EFFECTS__
@@ -16169,10 +16166,24 @@ var HubClient = class {
   }
 };
 
+// plugins/kxm/src/project-name.ts
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+function defaultProjectName(cwd, env = process.env) {
+  const fromEnv = env.KXM_PROJECT?.trim();
+  if (fromEnv) return fromEnv;
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+    if (typeof pkg.name === "string" && pkg.name.trim().length > 0) return pkg.name.trim();
+  } catch {
+  }
+  return basename(cwd);
+}
+
 // plugins/kxm/src/commands.ts
-import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync as readFileSync2, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join as join2, resolve } from "node:path";
 function requiredString(value, name) {
   if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} is required`);
   return value.trim();
@@ -16908,10 +16919,10 @@ function parseSessionToken(token) {
 }
 function resolveUserConfigDirectory(overrideDir) {
   if (overrideDir) return resolve(overrideDir);
-  return resolve(process.env.KXM_USER_CONFIG_DIR?.trim() || join(homedir(), ".config", "kxm"));
+  return resolve(process.env.KXM_USER_CONFIG_DIR?.trim() || join2(homedir(), ".config", "kxm"));
 }
 function sessionTokenPath(userConfigDir) {
-  return join(resolveUserConfigDirectory(userConfigDir), "session.token");
+  return join2(resolveUserConfigDirectory(userConfigDir), "session.token");
 }
 function matchToolPattern(pattern, toolName) {
   if (pattern === "*" || pattern === toolName) return true;
@@ -17007,7 +17018,7 @@ function enforceToolPolicy(commandName, env = process.env, options) {
   if (existsSync(tokenFile)) {
     let tokenRaw;
     try {
-      tokenRaw = readFileSync(tokenFile, "utf8").trim();
+      tokenRaw = readFileSync2(tokenFile, "utf8").trim();
     } catch {
       return { allowed: false, error: "session_token_invalid", detail: "Session token file on disk could not be read" };
     }
@@ -17036,7 +17047,7 @@ async function deliverInboxNotification(messageId, delivered, notify) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.18";
+var VERSION = "0.7.20";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
 var meshClient;
@@ -17109,7 +17120,7 @@ async function ensureClient() {
       serverUrl: process.env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331",
       name: process.env.KXM_AGENT_NAME?.trim() || `claude-${process.pid}`,
       purpose: process.env.KXM_AGENT_PURPOSE?.trim() || "Claude Code implementation and review agent",
-      project: process.env.KXM_PROJECT?.trim() || basename(projectDir),
+      project: defaultProjectName(projectDir, process.env),
       model: "claude-code",
       ...authToken ? { authToken } : {}
     });

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxm-claude-plugin",
-  "version": "0.7.18",
+  "version": "0.7.20",
   "private": true,
   "type": "module",
   "engines": {

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

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { redactSecrets } from "../redact.ts";
+import { defaultProjectName } from "../project-name.ts";
 import { agentWorker, type Worker } from "../envelope.ts";
 import { MESH_TUI_PANELS, runMeshTui, type MeshTuiPanel } from "../tui.ts";
 import { formatSessionBriefText, loadSessionBriefAsync, type SessionHubStatus } from "../session-work.ts";
@@ -130,7 +131,7 @@ 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 = runtime.env.KXM_PROJECT?.trim() || basename(runtime.dirs.workdir) || "project";
+  const project = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
   const authToken = runtime.env.KXM_AUTH_TOKEN?.trim();
   return await runMeshTui({
     serverUrl: runtime.serverUrl,

package/plugins/kxm/src/cli.ts

@@ -12,11 +12,12 @@
  * - System, update, and configuration (`kxm update`, `kxm config`, `kxm completion`, `kxm improve`)
  */
 
-import { basename, dirname, join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command, CommanderError } from "commander";
 import { readInstalledKxmVersion } from "./kxm-update.ts";
 import { HubClient } from "./client.ts";
+import { defaultProjectName } from "./project-name.ts";
 import {
   AGENT_COMMANDS_MAP,
   enforceToolPolicy,
@@ -179,7 +180,7 @@ function addGlobalOptions(command: Command): Command {
 
 async function ensureCliClient(runtime: Runtime): Promise<HubClient> {
   const serverUrl = runtime.serverUrl;
-  const project = runtime.env.KXM_PROJECT?.trim() || basename(runtime.dirs.workspace || runtime.cwd);
+  const project = defaultProjectName(runtime.cwd, runtime.env);
   const name = runtime.env.KXM_AGENT_NAME?.trim() || `cli-${process.pid}`;
   const purpose = runtime.env.KXM_AGENT_PURPOSE?.trim() || "CLI agent client";
   const authToken = runtime.env.KXM_AUTH_TOKEN?.trim();

package/plugins/kxm/src/config.ts

@@ -45,6 +45,14 @@ export interface KxmSyncTrackerConfig {
   };
 }
 
+export type KxmHubAutoStart = "off" | "background";
+
+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;
+}
+
 export type ImprovementPromotionPolicy = "manual_pr" | "critic_quorum" | "auto_threshold";
 
 export interface KxmImprovementConfig {
@@ -90,6 +98,7 @@ export interface KxmResolvedConfig {
   defaults: KxmProjectDefaults;
   dash: KxmDashConfig;
   sync: KxmSyncTrackerConfig;
+  hub: KxmHubConfig;
   improvement: KxmImprovementConfig;
   routing: KxmRoutingConfig;
   telemetry: KxmTelemetryConfig;
@@ -118,6 +127,9 @@ export const DEFAULT_KXM_CONFIG: Omit<KxmResolvedConfig, "loadedFrom"> = {
   sync: {
     defaultTracker: "none",
   },
+  hub: {
+    autoStart: "background",
+  },
   improvement: {
     promotionPolicy: "manual_pr",
     telemetryHalfLifeDays: 14,
@@ -176,6 +188,13 @@ function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<
   return result as T;
 }
 
+/** Unknown `hub.autoStart` values fail closed to the default so a config typo
+ * never silently changes hub startup behavior. */
+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 };
+}
+
 export function loadKxmConfig(
   repoRoot = process.cwd(),
   options: { userConfigDir?: string } = {},
@@ -221,6 +240,7 @@ export function loadKxmConfig(
     defaults: (mergedAll.defaults as KxmProjectDefaults) ?? {},
     dash: (mergedAll.dash as KxmDashConfig) ?? {},
     sync: (mergedAll.sync as KxmSyncTrackerConfig) ?? {},
+    hub: normalizeHubConfig(mergedAll.hub),
     improvement: (mergedAll.improvement as KxmImprovementConfig) ?? DEFAULT_KXM_CONFIG.improvement,
     routing: (mergedAll.routing as KxmRoutingConfig) ?? DEFAULT_KXM_CONFIG.routing,
     telemetry: (mergedAll.telemetry as KxmTelemetryConfig) ?? DEFAULT_KXM_CONFIG.telemetry,

package/plugins/kxm/src/extension.ts

@@ -1,9 +1,13 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { AGENT_COMMANDS, enforceToolPolicy } from "./commands.ts";
 import { HubClient, HubHttpError } from "./client.ts";
+import { loadKxmConfig } from "./config.ts";
+import { ensureHubRunning, hubAutoStartMode } from "./hub-autostart.ts";
+import { readHubEnvRecord } from "./hub-env.ts";
+import { defaultProjectName } from "./project-name.ts";
 import { nousFactoryWork, type NousRegistrationReport } from "./nous-pi.ts";
 import {
   antigravityRegistrationNotice,
@@ -673,7 +677,7 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
     }
     currentPiSessionId = ctx.sessionManager?.getSessionId();
     const serverUrl = process.env.KXM_SERVER_URL ?? "http://127.0.0.1:7331";
-    const project = process.env.KXM_PROJECT ?? basename(ctx.cwd);
+    const project = defaultProjectName(ctx.cwd, process.env);
     const name = process.env.KXM_AGENT_NAME ?? pi.getSessionName() ?? `pi-${process.pid}`;
     agentName = name;
     projectName = project;
@@ -681,12 +685,42 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
     removeMatchingLegacyRecoveryContext();
     const purpose = process.env.KXM_AGENT_PURPOSE ?? "General-purpose coding agent";
     const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+    let autoStartToken: string | undefined;
+    try {
+      const config = loadKxmConfig(ctx.cwd);
+      if (hubAutoStartMode(config) === "background") {
+        const ensured = await ensureHubRunning({ config, cwd: ctx.cwd });
+        if (ensured.status === "started") {
+          autoStartToken = ensured.authToken;
+          ctx.ui.notify(
+            `kxm hub started in the background (pid ${ensured.pid}); logs: ${ensured.logPath}`
+              + (ensured.authTokenSource === "generated" ? "; new admin token generated and persisted to user state" : ""),
+            "info",
+          );
+        } else if (ensured.status === "failed") {
+          ctx.ui.notify(`kxm hub auto-start failed: ${ensured.reason} (log: ${ensured.logPath})`, "warning");
+        }
+      }
+    } catch (error) {
+      ctx.ui.notify(`kxm hub auto-start failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
+    }
+    // Authenticate with the explicit env token first, then the token resolved
+    // by auto-start, then the credential persisted for this machine's hubs.
+    const envAuthToken = process.env.KXM_AUTH_TOKEN?.trim();
+    let hubAuthToken = envAuthToken || autoStartToken;
+    if (!hubAuthToken) {
+      try {
+        hubAuthToken = readHubEnvRecord()?.authToken?.trim() || undefined;
+      } catch (error) {
+        ctx.ui.notify(`kxm could not read persisted hub credentials: ${error instanceof Error ? error.message : String(error)}`, "warning");
+      }
+    }
     client = new HubClient({
       serverUrl,
       name,
       purpose,
       project,
-      ...(process.env.KXM_AUTH_TOKEN ? { authToken: process.env.KXM_AUTH_TOKEN } : {}),
+      ...(hubAuthToken ? { authToken: hubAuthToken } : {}),
       ...(model ? { model } : {}),
     });
     notify = (message, type) => ctx.ui.notify(message, type);

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

@@ -0,0 +1,214 @@
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { probeHubHealth, readHubBinding } from "./hub-binding.ts";
+import { resolveHubCredentials } from "./hub-env.ts";
+import { redactSecrets } from "./redact.ts";
+
+/** Background hub auto-start for harness extensions (Pi TUI, one-shot CLIs).
+ *
+ * On extension load: reuse a healthy bound hub, then a live local `hub.pid`
+ * claim, and only then spawn the detached `kxm-hub.mjs` wrapper. Credentials
+ * are resolved before launch, so a first run generates the admin token and
+ * persists it (`0600`) under the user state root, exactly as
+ * `kxm hub start` does. The single-hub-per-user invariants (exclusive PID
+ * claim, reclaimed dead wrappers) come from the wrapper itself. */
+
+export const HUB_AUTOSTART_LOG_NAME = "hub-autostart.log";
+const CLAIM_POLL_MS = 50;
+const DEFAULT_CLAIM_TIMEOUT_MS = 3000;
+
+export type HubAutoStartMode = "off" | "background";
+
+export type EnsureHubResult =
+  | { status: "disabled" }
+  | { status: "bound-healthy"; url: string }
+  | { status: "url-healthy"; url: string }
+  | { status: "claim-alive"; pid: number }
+  | { status: "started"; pid: number; logPath: string; authToken: string | undefined; authTokenSource: string }
+  | { status: "failed"; reason: string; logPath: string };
+
+export interface HubSpawnOptions {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  stdio: ["ignore", number, number];
+  detached: boolean;
+  windowsHide: boolean;
+}
+
+export interface HubSpawned {
+  pid?: number | undefined;
+  once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+}
+
+export type HubSpawner = (command: string, args: readonly string[], options: HubSpawnOptions) => HubSpawned;
+
+export interface EnsureHubOptions {
+  config: { hub?: { autoStart?: unknown } } | undefined;
+  cwd: string;
+  env?: NodeJS.ProcessEnv | undefined;
+  fetchImpl?: typeof fetch | undefined;
+  spawner?: HubSpawner | undefined;
+  processExists?: ((pid: number) => boolean) | undefined;
+  scriptPath?: string | undefined;
+  sleep?: ((ms: number) => Promise<void>) | undefined;
+  now?: (() => number) | undefined;
+  claimTimeoutMs?: number | undefined;
+}
+
+/** Resolve the configured auto-start mode; unknown values fail closed to the
+ * default so a typo never silently disables (or re-enables) hub startup. */
+export function hubAutoStartMode(config: { hub?: { autoStart?: unknown } } | undefined): HubAutoStartMode {
+  const raw = config?.hub?.autoStart;
+  return raw === "off" || raw === "background" ? raw : "background";
+}
+
+function defaultProcessExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+export interface HubClaimSnapshot {
+  pid: number;
+  serverPid: number | undefined;
+}
+
+/** Read the workspace hub PID claim. A missing or malformed claim is not
+ * live; the wrapper fails closed on malformed claims when it starts, so the
+ * extension must not try to clean claims up itself. */
+export function readLiveHubClaim(stateDir: string, processExists: (pid: number) => boolean = defaultProcessExists): HubClaimSnapshot | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(join(stateDir, "hub.pid"), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const record = parsed as { version?: unknown; role?: unknown; pid?: unknown; serverPid?: unknown };
+  if (record.version !== 1 || record.role !== "hub" || !Number.isInteger(record.pid)) return undefined;
+  const pid = record.pid as number;
+  if (pid <= 0 || !processExists(pid)) return undefined;
+  return {
+    pid,
+    ...(Number.isInteger(record.serverPid) && (record.serverPid as number) > 0 ? { serverPid: record.serverPid as number } : { serverPid: undefined }),
+  };
+}
+
+/** The hub wrapper script next to the checked-out KXM repo. The extension and
+ * the CLI both resolve the same path so auto-start launches the identical
+ * supervision wrapper as `kxm hub start`. */
+export function defaultHubWrapperScriptPath(moduleUrl: string = import.meta.url): string {
+  return resolve(dirname(fileURLToPath(moduleUrl)), "../../../scripts/kxm-hub.mjs");
+}
+
+function defaultHubSpawner(command: string, args: readonly string[], options: HubSpawnOptions): HubSpawned {
+  const child = spawn(command, [...args], options);
+  child.unref();
+  return child;
+}
+
+function logTail(logPath: string, maxChars = 2000): string {
+  try {
+    return redactSecrets(readFileSync(logPath, "utf8").trim().slice(-maxChars));
+  } catch {
+    return "";
+  }
+}
+
+/** Ensure a hub is available, starting a detached one only when no healthy
+ * bound hub and no live local claim exists. Never throws for ordinary
+ * failures; structured results let callers notify without blocking load. */
+export async function ensureHubRunning(options: EnsureHubOptions): Promise<EnsureHubResult> {
+  const env = options.env ?? process.env;
+  if (hubAutoStartMode(options.config) !== "background") return { status: "disabled" };
+
+  // 1. A bound hub that answers health is authoritative — reuse it.
+  const binding = readHubBinding(env);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  if (binding) {
+    const { health } = await probeHubHealth(binding.url, fetchImpl);
+    if (health === "on") return { status: "bound-healthy", url: binding.url };
+  }
+
+  // 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);
+  const workspaceDir = resolve(workdir, env.KXM_WORKSPACE_DIR?.trim() || ".kxm");
+  const stateDir = resolve(workdir, env.KXM_STATE_DIR?.trim() || join(workspaceDir, "state"));
+  const logsDir = resolve(workdir, env.KXM_LOGS_DIR?.trim() || join(workspaceDir, "logs"));
+  const processExists = options.processExists ?? defaultProcessExists;
+  const live = readLiveHubClaim(stateDir, processExists);
+  if (live) return { status: "claim-alive", pid: live.pid };
+
+  // 3. A hub already serving the configured URL (for example one launched
+  //    directly by a harness, without a claim or binding) is reused too: the
+  //    client will connect there regardless, so spawning a duplicate would
+  //    only fail to bind the same port.
+  const serverUrl = (env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331").replace(/\/+$/, "");
+  if (serverUrl !== binding?.url) {
+    const { health } = await probeHubHealth(serverUrl, fetchImpl);
+    if (health === "on") return { status: "url-healthy", url: serverUrl };
+  }
+
+  // 4. Resolve credentials before launch so the key exists by the time the
+  //    wrapper starts: env wins, then the persisted user-state file, then a
+  //    generated token persisted with 0600 for later restarts and workers.
+  const credentials = resolveHubCredentials({ env });
+  const logPath = join(logsDir, HUB_AUTOSTART_LOG_NAME);
+  mkdirSync(logsDir, { recursive: true });
+  const logFd = openSync(logPath, "a");
+  let child: HubSpawned;
+  try {
+    child = (options.spawner ?? defaultHubSpawner)(process.execPath, [options.scriptPath ?? defaultHubWrapperScriptPath()], {
+      cwd: workdir,
+      env: {
+        ...env,
+        KXM_WORKDIR: workdir,
+        KXM_WORKSPACE_DIR: workspaceDir,
+        KXM_STATE_DIR: stateDir,
+        KXM_LOGS_DIR: logsDir,
+        ...(credentials.authToken ? { KXM_AUTH_TOKEN: credentials.authToken } : {}),
+      },
+      stdio: ["ignore", logFd, logFd],
+      detached: process.platform !== "win32",
+      windowsHide: true,
+    });
+  } finally {
+    closeSync(logFd);
+  }
+
+  // 4. Verify the wrapper claimed the hub. A simultaneous loader may have won
+  //    the exclusive claim first; that is a live hub, not a failure.
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolveSleep) => setTimeout(resolveSleep, ms)));
+  const now = options.now ?? Date.now;
+  const timeoutMs = options.claimTimeoutMs ?? DEFAULT_CLAIM_TIMEOUT_MS;
+  let earlyExit: { code: number | null; signal: NodeJS.Signals | null } | undefined;
+  child.once("exit", (code, signal) => {
+    earlyExit = { code, signal };
+  });
+  const deadline = now() + timeoutMs;
+  for (;;) {
+    if (earlyExit) {
+      // A simultaneous loader may have won the exclusive claim first; that
+      // is a live hub, not a failure.
+      const raced = readLiveHubClaim(stateDir, processExists);
+      if (raced) return { status: "claim-alive", pid: raced.pid };
+      const detail = logTail(logPath);
+      const reason = `hub wrapper exited before claiming the hub (code ${earlyExit.code ?? "null"}${earlyExit.signal ? `, signal ${earlyExit.signal}` : ""})${detail ? `: ${detail}` : ""}`;
+      return { status: "failed", reason, logPath };
+    }
+    const claimed = readLiveHubClaim(stateDir, processExists);
+    if (claimed) return { status: "started", pid: claimed.pid, logPath, authToken: credentials.authToken, authTokenSource: credentials.authTokenSource };
+    if (now() >= deadline) {
+      return child.pid
+        ? { status: "started", pid: child.pid, logPath, authToken: credentials.authToken, authTokenSource: credentials.authTokenSource }
+        : { status: "failed", reason: `hub wrapper did not claim the hub within ${timeoutMs} ms`, logPath };
+    }
+    await sleep(CLAIM_POLL_MS);
+  }
+}

package/plugins/kxm/src/mcp-server.ts

@@ -1,13 +1,13 @@
-import { basename } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { HubClient } from "./client.ts";
+import { defaultProjectName } from "./project-name.ts";
 import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } from "./commands.ts";
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.18";
+const VERSION = "0.7.20";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;
@@ -88,7 +88,7 @@ async function ensureClient(): Promise<HubClient> {
       serverUrl: process.env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331",
       name: process.env.KXM_AGENT_NAME?.trim() || `claude-${process.pid}`,
       purpose: process.env.KXM_AGENT_PURPOSE?.trim() || "Claude Code implementation and review agent",
-      project: process.env.KXM_PROJECT?.trim() || basename(projectDir),
+      project: defaultProjectName(projectDir, process.env),
       model: "claude-code",
       ...(authToken ? { authToken } : {}),
     });

package/plugins/kxm/src/project-name.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+/** Default project identity for a workspace.
+ *
+ * Precedence: `KXM_PROJECT` environment, then the workspace `package.json`
+ * `name`, then the workspace directory name. The package.json read is
+ * best-effort and never walks upward: a missing, malformed, or name-less
+ * file falls through to the directory name. */
+export function defaultProjectName(cwd: string, env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.KXM_PROJECT?.trim();
+  if (fromEnv) return fromEnv;
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")) as { name?: unknown };
+    if (typeof pkg.name === "string" && pkg.name.trim().length > 0) return pkg.name.trim();
+  } catch {
+    // No readable package.json: fall through to the directory name.
+  }
+  return basename(cwd);
+}