@kontextmind/kxm 0.7.0 → 0.7.4

package/plugins/kxm/src/vnext-oneshot-producer.ts

@@ -195,6 +195,24 @@ export function createVnextOneShotProducer(options: VnextOneShotProducerOptions
         args = ["--model", resolved.model,
           ...(resolved.thinking ? ["--reasoning-effort", resolved.thinking] : []),
           ...permissionArgs, "--output-format", "json"];
+      } else if (harness === "agy") {
+        args = [
+          "-m",
+          resolved.model,
+          ...permissionArgs,
+          "--output-format",
+          "json",
+          "-p",
+        ];
+      } else if (harness === "kimi") {
+        args = [
+          "-m",
+          resolved.model,
+          ...permissionArgs,
+          "--output-format",
+          "stream-json",
+          "-p",
+        ];
       } else {
         throw new Error(`oneshot_harness_unsupported: ${harness} permission_profile_unaudited`);
       }

package/plugins/kxm/src/vnext-runtime-store.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
 import { VnextConfigError, validateRunEvent, vnextCanonicalJson, type JsonValue, type VnextConfigIssue, type VnextConfigOptions } from "./vnext-config.ts";
 import { vnextUserStateRoot } from "./vnext-bindings.ts";
 

package/plugins/kxm/src/workflow-tui.ts

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
 import { repoConfigDirectory } from "./config.ts";
 import { readRoutingRecords, telemetryPath } from "./telemetry.ts";
 

package/plugins/kxm/src/workflow.ts

@@ -3,11 +3,17 @@ import {
   MAX_MESSAGE_TTL_MS,
   MIN_MESSAGE_TTL_MS,
   ProtocolError,
+  TERMINAL_RECEIPT_SCHEMA,
   newId,
   requireString,
+  validateTerminalReceipt,
   type ImprovementArea,
   type JournalCategory,
   type MessageRecord,
+  type TerminalReceipt,
+  type TerminalReceiptEvidence,
+  type TerminalReceiptMetrics,
+  type TerminalReceiptStatus,
   type WorkflowCheckpointStatus,
   type WorkflowEvidenceInput,
   type WorkflowEvidenceReference,
@@ -18,11 +24,16 @@ import {
 export type {
   ImprovementArea,
   JournalCategory,
+  TerminalReceipt,
+  TerminalReceiptEvidence,
+  TerminalReceiptMetrics,
+  TerminalReceiptStatus,
   WorkflowCheckpointStatus,
   WorkflowEvidenceInput,
   WorkflowEvidenceReference,
   WorkflowEvidenceReferenceInput,
 } from "./protocol.ts";
+export { TERMINAL_RECEIPT_SCHEMA, validateTerminalReceipt } from "./protocol.ts";
 
 export type WorkflowRunStatus = "running" | "waiting" | "completed" | "failed";
 export type WorkflowStageStatus = "pending" | "in_progress" | "waiting" | WorkflowCheckpointStatus;
@@ -153,6 +164,8 @@ export interface WorkflowStageDefinition {
   instructions: string;
   requiredEvidence: string[];
   maxAttempts: number;
+  /** Bounded in-place retry limit before audit escalation (default: 2). */
+  autoResumeLimit?: number;
   area?: ImprovementArea;
   evidencePolicies?: WorkflowEvidencePolicies;
   /** Typed outcome map (v0.5). Keys are outcome identities ("passed",
@@ -250,6 +263,13 @@ export interface WorkflowStageState extends WorkflowStageDefinition {
   startedAt?: string;
   completedAt?: string;
   updatedAt?: string;
+  receipt?: TerminalReceipt;
+  auditEscalation?: {
+    reason: string;
+    timestamp: string;
+    ruling?: string;
+    receipt?: TerminalReceipt;
+  };
 }
 
 export interface CapturedOracle {
@@ -1003,12 +1023,18 @@ export function parseWorkflowDefinitions(
         && (!Number.isInteger(stageMaxTransitions) || (stageMaxTransitions as number) < 1 || (stageMaxTransitions as number) > 100)) {
         throw new Error(`stage ${stageId} maxTransitions must be an integer between 1 and 100`);
       }
+      const autoResumeLimit = stage.autoResumeLimit;
+      if (autoResumeLimit !== undefined
+        && (!Number.isInteger(autoResumeLimit) || (autoResumeLimit as number) < 1 || (autoResumeLimit as number) > 20)) {
+        throw new Error(`stage ${stageId} autoResumeLimit must be an integer between 1 and 20`);
+      }
       return {
         id: stageId,
         label: requireString(stage.label ?? stageId, "stage.label", { max: 128 }),
         instructions: requireString(stage.instructions, "stage.instructions", { max: 4_000 }),
         requiredEvidence,
         maxAttempts: maxAttempts as number,
+        ...(autoResumeLimit !== undefined ? { autoResumeLimit: autoResumeLimit as number } : {}),
         ...(area ? { area } : {}),
         ...(evidencePolicies ? { evidencePolicies } : {}),
         ...(on ? { on } : {}),
@@ -1377,6 +1403,31 @@ export function checkpointRun(
       delete run.currentStage;
       return { retry: false, completed: false, run };
     }
+    if (stage.autoResumeLimit !== undefined && stage.attempts >= stage.autoResumeLimit) {
+      stage.status = "in_progress";
+      const reason = summary || `autoResumeLimit of ${stage.autoResumeLimit} reached on stage ${stage.id}`;
+      const receipt = validateTerminalReceipt({
+        schema: TERMINAL_RECEIPT_SCHEMA,
+        status: "audit_escalation",
+        seat: stage.id,
+        runId: run.id,
+        stageId: stage.id,
+        timestamp,
+        host: "pi",
+        model: "default",
+        escalationReason: reason,
+      });
+      const expiresAt = new Date(Date.parse(timestamp) + 24 * 60 * 60 * 1000).toISOString();
+      waitForWorkflowSignal(run, stage.id, "audit_escalation", reason, timestamp, expiresAt);
+      stage.receipt = receipt;
+      stage.auditEscalation = {
+        reason,
+        timestamp,
+        receipt,
+      };
+      return { retry: false, completed: false, run };
+    }
+    stage.status = status;
     // Declared failure outcomes create typed transitions (bounded); the
     // outcome identity defaults to the checkpoint status.
     const outcomeKey = outcome ?? status;
@@ -1546,3 +1597,96 @@ export function approveWorkflowDegradation(
   run.updatedAt = timestamp;
   return { run, approval, created: true };
 }
+
+export function escalateWorkflowStage(
+  run: WorkflowRun,
+  stageId: string,
+  reason: string,
+  timestamp: string,
+  options: {
+    seat?: string;
+    host?: string;
+    model?: string;
+    evidence?: TerminalReceiptEvidence;
+    metrics?: TerminalReceiptMetrics;
+  } = {},
+): { run: WorkflowRun; receipt: TerminalReceipt } {
+  if (run.status !== "running") throw new ProtocolError(409, `workflow is ${run.status}`, "workflow_terminal");
+  const stage = run.stages.find((s) => s.id === stageId);
+  if (!stage) throw new ProtocolError(404, `workflow stage not found: ${stageId}`, "workflow_stage_not_found");
+  if (stage.id !== run.currentStage || stage.status !== "in_progress") {
+    throw new ProtocolError(409, `stage ${stageId} is not currently active`, "workflow_stage_out_of_order");
+  }
+
+  const receipt: TerminalReceipt = validateTerminalReceipt({
+    schema: TERMINAL_RECEIPT_SCHEMA,
+    status: "audit_escalation",
+    seat: options.seat ?? stage.id,
+    runId: run.id,
+    stageId,
+    timestamp,
+    host: options.host ?? "pi",
+    model: options.model ?? "default",
+    escalationReason: reason,
+    ...(options.evidence ? { evidence: options.evidence } : {}),
+    ...(options.metrics ? { metrics: options.metrics } : {}),
+  });
+
+  const expiresAt = new Date(Date.parse(timestamp) + 24 * 60 * 60 * 1000).toISOString();
+  waitForWorkflowSignal(run, stageId, "audit_escalation", reason, timestamp, expiresAt);
+
+  stage.receipt = receipt;
+  stage.auditEscalation = {
+    reason,
+    timestamp,
+    receipt,
+  };
+
+  return { run, receipt };
+}
+
+export function resumeWorkflowFromRuling(
+  run: WorkflowRun,
+  ruling: string,
+  timestamp: string,
+  options: {
+    status?: WorkflowCheckpointStatus;
+    evidence?: WorkflowEvidenceInput;
+  } = {},
+): { retry: boolean; completed: boolean; run: WorkflowRun; stageId: string } {
+  if (run.status !== "waiting" || !run.waiting) {
+    throw new ProtocolError(409, `workflow is ${run.status}`, "workflow_not_waiting");
+  }
+  if (run.waiting.signalKey !== "audit_escalation") {
+    throw new ProtocolError(
+      409,
+      `workflow is waiting for signal '${run.waiting.signalKey}', not 'audit_escalation'`,
+      "workflow_signal_mismatch",
+    );
+  }
+
+  const stageId = run.waiting.stageId;
+  const stage = run.stages.find((s) => s.id === stageId);
+  if (!stage) throw new ProtocolError(404, `workflow stage not found: ${stageId}`, "workflow_stage_not_found");
+
+  const status = options.status ?? "passed";
+  const evidence = options.evidence ?? {};
+
+  if (stage.auditEscalation) {
+    stage.auditEscalation.ruling = ruling;
+    if (stage.auditEscalation.receipt) {
+      stage.auditEscalation.receipt.ruling = ruling;
+    }
+  }
+  stage.summary = `Resumed by operator ruling: ${ruling}`;
+
+  return resumeWorkflowFromSignal(
+    run,
+    "audit_escalation",
+    status,
+    `Resumed: ${ruling}`,
+    evidence,
+    timestamp,
+  );
+}
+

package/scripts/kxm-bump-version.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+/**
+ * Bump the package version across all tracked surfaces.
+ *
+ * Usage:
+ *   node scripts/kxm-bump-version.mjs <new-version>       # explicit version
+ *   node scripts/kxm-bump-version.mjs patch               # bump patch
+ *   node scripts/kxm-bump-version.mjs minor               # bump minor
+ *   node scripts/kxm-bump-version.mjs major               # bump major
+ *
+ * Surfaces updated (must stay in sync with scripts/check-versions.mjs):
+ *   1. package.json                          .version
+ *   2. package-lock.json                     .version + .packages[""].version
+ *   3. plugins/kxm/package.json              .version
+ *   4. plugins/kxm/.claude-plugin/plugin.json .version
+ *   5. .claude-plugin/marketplace.json       .plugins[name=kxm].version
+ *   6. plugins/kxm/src/mcp-server.ts         const VERSION = "..."
+ *   7. plugins/kxm/dist/mcp-server.js        const VERSION = "..." (rebuilt)
+ *
+ * After running this script, run `npm run build` to rebuild dist bundles.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/;
+
+export function parseSemver(version) {
+  const match = SEMVER_RE.exec(version);
+  if (!match) return undefined;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4],
+    build: match[5],
+  };
+}
+
+export function bumpVersion(current, kind) {
+  const parsed = parseSemver(current);
+  if (!parsed) throw new Error(`invalid current version: ${current}`);
+  switch (kind) {
+    case "major":
+      return `${parsed.major + 1}.0.0`;
+    case "minor":
+      return `${parsed.major}.${parsed.minor + 1}.0`;
+    case "patch":
+      return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}`;
+    default:
+      throw new Error(`unknown bump kind: ${kind} (use major, minor, or patch)`);
+  }
+}
+
+/** Replace a version string in a JSON file using targeted string patching. */
+function patchJsonVersion(filePath, oldVersion, newVersion) {
+  const raw = readFileSync(filePath, "utf8");
+  const escaped = oldVersion.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`("version"\\s*:\\s*)"${escaped}"`, "g");
+  const patched = raw.replace(pattern, `$1"${newVersion}"`);
+  if (patched === raw) {
+    throw new Error(`no version field found to patch in ${filePath}`);
+  }
+  writeFileSync(filePath, patched, "utf8");
+}
+
+/** Replace a version string in a TypeScript/JavaScript source file. */
+function patchSourceVersion(filePath, newVersion) {
+  const raw = readFileSync(filePath, "utf8");
+  const patched = raw.replace(
+    /const VERSION = "[^"]+"/,
+    `const VERSION = "${newVersion}"`,
+  );
+  if (patched === raw) {
+    throw new Error(`no VERSION constant found in ${filePath}`);
+  }
+  writeFileSync(filePath, patched, "utf8");
+}
+
+export function applyVersionBump(root, newVersion) {
+  if (!parseSemver(newVersion)) {
+    throw new Error(`invalid semver: ${newVersion}`);
+  }
+
+  // Read current version
+  const pkgPath = resolve(root, "package.json");
+  const oldVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+
+  // JSON surfaces (targeted patch preserves formatting)
+  const jsonFiles = [
+    "package.json",
+    "package-lock.json",
+    "plugins/kxm/package.json",
+    "plugins/kxm/.claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+  ];
+  for (const rel of jsonFiles) {
+    patchJsonVersion(resolve(root, rel), oldVersion, newVersion);
+  }
+
+  // TypeScript source
+  patchSourceVersion(resolve(root, "plugins/kxm/src/mcp-server.ts"), newVersion);
+
+  // Generated dist (update in place if it exists; check:generated rebuilds anyway)
+  const distPath = resolve(root, "plugins/kxm/dist/mcp-server.js");
+  try {
+    patchSourceVersion(distPath, newVersion);
+  } catch {
+    // dist may not exist yet; will be rebuilt by npm run build
+  }
+
+  return { oldVersion, newVersion };
+}
+
+export function main(argv = process.argv.slice(2), root = process.cwd()) {
+  const arg = argv[0];
+  if (!arg) {
+    process.stderr.write("usage: node scripts/kxm-bump-version.mjs <version|patch|minor|major>\n");
+    return 1;
+  }
+
+  const pkgPath = resolve(root, "package.json");
+  const currentVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+
+  let newVersion;
+  if (SEMVER_RE.test(arg)) {
+    newVersion = arg;
+  } else {
+    newVersion = bumpVersion(currentVersion, arg);
+  }
+
+  if (newVersion === currentVersion) {
+    process.stdout.write(`version unchanged: ${currentVersion}\n`);
+    return 0;
+  }
+
+  const result = applyVersionBump(root, newVersion);
+  process.stdout.write(`bumped ${result.oldVersion} -> ${result.newVersion}\n`);
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = main();
+}

package/scripts/kxm-hub.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 import { spawn, spawnSync } from "node:child_process";
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -15,6 +17,19 @@ const startedAt = new Date().toISOString();
 const controlFile = "hub.stop";
 const controlPath = join(stateDir, controlFile);
 
+// --- Persistent hub credentials (kxm.hub-env.v1) -------------------------
+// Precedence: KXM_AUTH_TOKEN/KXM_PROJECT_TOKENS env, then the persisted
+// user-state file, then a generated admin token that is persisted so later
+// restarts, workers, and dashboards reuse the same credential.
+function resolveUserStateRoot() {
+  const explicit = process.env.KXM_STATE_HOME?.trim();
+  if (explicit) return resolve(explicit);
+  const home = homedir();
+  if (process.platform === "win32") return resolve(process.env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"), "KXM");
+  if (process.platform === "darwin") return resolve(home, "Library", "Application Support", "KXM");
+  return resolve(process.env.XDG_STATE_HOME?.trim() || join(home, ".local", "state"), "kxm");
+}
+
 function processExists(pid) {
   try {
     process.kill(pid, 0);
@@ -24,6 +39,119 @@ function processExists(pid) {
   }
 }
 
+function parseHubEnvFile() {
+  const file = join(resolveUserStateRoot(), "hub-env.json");
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { file, record: undefined };
+    throw new Error(`KXM hub could not read the persisted hub env at ${file}: ${error.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`KXM hub env file is malformed at ${file}; fix or remove it (it holds only KXM_AUTH_TOKEN/KXM_PROJECT_TOKENS values): ${error.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.schema !== "kxm.hub-env.v1") {
+    throw new Error(`KXM hub env file at ${file} does not use schema kxm.hub-env.v1`);
+  }
+  return { file, record: parsed };
+}
+
+function generateAdminToken() {
+  return `kxm_admin_${randomBytes(24).toString("base64url")}`;
+}
+
+function persistHubEnv(file, record) {
+  mkdirSync(resolve(file, ".."), { recursive: true });
+  const temporary = join(resolve(file, ".."), `.hub-env-${process.pid}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(record, undefined, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(temporary, file);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+function parseProjectTokensEnv(raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new Error("KXM_PROJECT_TOKENS must be a JSON object of project names to tokens");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("KXM_PROJECT_TOKENS must be a JSON object of project names to tokens");
+  }
+  for (const [project, token] of Object.entries(parsed)) {
+    if (!project.trim() || typeof token !== "string" || !token.trim()) {
+      throw new Error("KXM_PROJECT_TOKENS must contain non-empty project names and token strings");
+    }
+  }
+  return parsed;
+}
+
+/** Resolve credentials, persisting generated/env values into the user-state file. */
+function resolveCredentials() {
+  const { file, record } = parseHubEnvFile();
+  const envToken = process.env.KXM_AUTH_TOKEN?.trim();
+  const envProjectTokens = parseProjectTokensEnv(process.env.KXM_PROJECT_TOKENS);
+  let authToken = envToken || record?.authToken;
+  let authTokenSource = envToken ? "env" : record?.authToken ? "file" : "none";
+  if (!authToken) {
+    authToken = generateAdminToken();
+    authTokenSource = "generated";
+  }
+  const projectTokens = envProjectTokens || record?.projectTokens;
+  const projectTokensSource = envProjectTokens ? "env" : record?.projectTokens ? "file" : "none";
+  const envChanged = (authTokenSource === "env" && record?.authToken !== authToken)
+    || (projectTokensSource === "env" && JSON.stringify(record?.projectTokens ?? undefined) !== JSON.stringify(projectTokens ?? undefined));
+  if (authTokenSource === "generated" || envChanged) {
+    persistHubEnv(file, {
+      schema: "kxm.hub-env.v1",
+      createdAt: record?.createdAt || new Date().toISOString(),
+      ...(authToken ? { authToken } : {}),
+      ...(projectTokens ? { projectTokens } : {}),
+    });
+  }
+  return { authToken, authTokenSource, projectTokens, projectTokensSource, file };
+}
+
+let credentials;
+try {
+  credentials = resolveCredentials();
+} catch (error) {
+  process.stderr.write(`kxm hub: ${error.message}\n`);
+  process.exit(1);
+}
+const launchEnv = { ...process.env };
+if (credentials.authToken) launchEnv.KXM_AUTH_TOKEN = credentials.authToken;
+if (credentials.projectTokens) launchEnv.KXM_PROJECT_TOKENS = JSON.stringify(credentials.projectTokens);
+if (credentials.authTokenSource !== "env") {
+  process.stdout.write(`kxm hub: using ${credentials.authTokenSource === "generated" ? "newly generated" : "persisted"} KXM_AUTH_TOKEN from ${credentials.file}\n`);
+}
+
+function terminateTree(pid) {
+  // Best-effort cleanup of an orphaned hub server whose wrapper died
+  // without reclaiming (e.g. SIGKILL). The wrapper could not be stopped
+  // gracefully in that state, so the server is asked to shut down first and
+  // forced after a short grace period.
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    if (!processExists(pid)) return;
+    const wait = Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    if (wait !== "timed-out") return;
+  }
+  try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+}
+
 function claimPidFile() {
   const record = { version: 1, pid: process.pid, role: "hub", startedAt, controlFile };
   for (let attempt = 0; attempt < 3; attempt += 1) {
@@ -50,9 +178,16 @@ function claimPidFile() {
       if (existing?.version === 1 && existing.role === "hub" && Number.isInteger(existing.pid) && processExists(existing.pid)) {
         throw new Error(`KXM hub is already managed by PID ${existing.pid}`);
       }
-      // A well-formed claim whose owner is dead is safe to reclaim. Keep
+      // A well-formed claim whose wrapper is dead is safe to reclaim. Keep
       // malformed claims fail-closed because they may belong to another tool.
       if (existing?.version === 1 && existing.role === "hub" && Number.isInteger(existing.pid) && !processExists(existing.pid)) {
+        // The wrapper is gone. An orphaned server child recorded by the dead
+        // wrapper is cleaned up before reclaiming so a SIGKILLed wrapper does
+        // not leave a port-holding server behind.
+        if (Number.isInteger(existing.serverPid) && existing.serverPid !== existing.pid && processExists(existing.serverPid)) {
+          process.stderr.write(`kxm hub: cleaning up orphaned hub server PID ${existing.serverPid} from a dead wrapper\n`);
+          terminateTree(existing.serverPid);
+        }
         rmSync(pidPath, { force: true });
         continue;
       }
@@ -79,8 +214,15 @@ const child = spawn(process.execPath, [
   ...process.argv.slice(2),
 ], {
   stdio: ["inherit", "inherit", "inherit", "ipc"],
-  env: process.env,
+  env: launchEnv,
 });
+// Record the server child PID inside the claim so a later wrapper can clean
+// up an orphaned server if this wrapper is killed without running cleanupPid.
+if (child.pid) {
+  try {
+    writeFileSync(pidPath, `${JSON.stringify({ version: 1, pid: process.pid, serverPid: child.pid, role: "hub", startedAt, controlFile })}\n`, "utf8");
+  } catch { /* claim already written; serverPid tracking is best-effort */ }
+}
 let stopping = false;
 
 child.once("error", (error) => {

package/scripts/kxm-publish-npm.mjs

@@ -275,7 +275,9 @@ export async function main(env = process.env, stdout = process.stdout, stderr =
   const token = env.GITHUB_TOKEN || env.GH_TOKEN;
   const npmToken = env.NODE_AUTH_TOKEN || env.NPM_TOKEN;
   const repo = env.GITHUB_REPOSITORY;
-  const tag = env.GITHUB_REF_NAME || env.TAG;
+  // KXM_RELEASE_TAG is explicit for workflow_dispatch runs; GITHUB_REF_NAME
+  // is the branch name for that event, not the requested release tag.
+  const tag = env.KXM_RELEASE_TAG || env.TAG || env.GITHUB_REF_NAME;
   const assetName = env.KXM_ASSET;
   const assetPath = env.KXM_ASSET_PATH;
   const declaredSha256 = env.KXM_ASSET_SHA256;

package/scripts/kxm-release-github.mjs

@@ -427,7 +427,9 @@ export function fileSha256(path) {
 export async function main(env = process.env, stdout = process.stdout, stderr = process.stderr) {
   const token = env.GITHUB_TOKEN || env.GH_TOKEN;
   const repo = env.GITHUB_REPOSITORY;
-  const tag = env.GITHUB_REF_NAME;
+  // KXM_RELEASE_TAG is explicit for workflow_dispatch runs; GITHUB_REF_NAME
+  // is the branch name for that event, not the requested release tag.
+  const tag = env.KXM_RELEASE_TAG || env.TAG || env.GITHUB_REF_NAME;
   const assetName = env.KXM_ASSET;
   const assetPath = env.KXM_ASSET_PATH;
   const declared = env.KXM_ASSET_SHA256;