@kontextmind/kxm 0.7.95 → 0.7.97

package/plugins/kxm/dist/core.js

@@ -981,6 +981,13 @@ var HubHttpError = class extends Error {
 };
 
 // plugins/kxm/src/commands.ts
+function forwardedHops(handling) {
+  if (!handling?.length) return void 0;
+  return {
+    hops: Math.max(...handling.map((message) => message.hops)) + 1,
+    maxHops: Math.min(...handling.map((message) => message.maxHops))
+  };
+}
 function requiredString(value, name) {
   if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} is required`);
   return value.trim();
@@ -1110,12 +1117,13 @@ var AGENT_COMMANDS = [
       required: ["target", "content"],
       additionalProperties: false
     },
-    async execute(client, args) {
+    async execute(client, args, context) {
       const delivery = optionalString2(args.delivery);
       const correlationId = optionalString2(args.correlationId);
       const idempotencyKey = optionalString2(args.idempotencyKey);
       const workflowContext = optionalWorkflowContext(args.workflowContext);
       const message = await client.send({
+        ...forwardedHops(context?.handling),
         target: requiredString(args.target, "target"),
         content: requiredString(args.content, "content"),
         ...delivery ? { delivery } : {},
@@ -1193,6 +1201,7 @@ var AGENT_COMMANDS = [
       const targets = Array.isArray(args.targets) ? args.targets.map((t) => requiredString(t, "target")) : [];
       return {
         responses: await client.fanout({
+          ...forwardedHops(context?.handling),
           targets,
           content: requiredString(args.content, "content"),
           ...optionalString2(args.correlationId) ? { correlationId: optionalString2(args.correlationId) } : {},
@@ -2156,6 +2165,7 @@ export {
   enforceToolPolicy,
   evaluateCircuitBreaker,
   formatRoutingReport,
+  forwardedHops,
   gateWorker,
   generateRoutingReport,
   getCliAgentCommands,

package/plugins/kxm/dist/extension.js

@@ -14799,7 +14799,9 @@ var HubClient = class {
               options.workflowContext
             )
           } : {},
-          ...options.ttlMs ? { ttlMs: options.ttlMs } : {}
+          ...options.ttlMs ? { ttlMs: options.ttlMs } : {},
+          ...options.hops !== void 0 ? { hops: options.hops } : {},
+          ...options.maxHops !== void 0 ? { maxHops: options.maxHops } : {}
         });
         const completed = await this.awaitResponse(
           message.id,
@@ -15106,6 +15108,13 @@ async function hubJsonRequest(options, path, init, headers) {
 }
 
 // plugins/kxm/src/commands.ts
+function forwardedHops(handling) {
+  if (!handling?.length) return void 0;
+  return {
+    hops: Math.max(...handling.map((message) => message.hops)) + 1,
+    maxHops: Math.min(...handling.map((message) => message.maxHops))
+  };
+}
 function requiredString(value, name) {
   if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} is required`);
   return value.trim();
@@ -15235,12 +15244,13 @@ var AGENT_COMMANDS = [
       required: ["target", "content"],
       additionalProperties: false
     },
-    async execute(client, args) {
+    async execute(client, args, context) {
       const delivery = optionalString(args.delivery);
       const correlationId = optionalString(args.correlationId);
       const idempotencyKey = optionalString(args.idempotencyKey);
       const workflowContext = optionalWorkflowContext(args.workflowContext);
       const message = await client.send({
+        ...forwardedHops(context?.handling),
         target: requiredString(args.target, "target"),
         content: requiredString(args.content, "content"),
         ...delivery ? { delivery } : {},
@@ -15318,6 +15328,7 @@ var AGENT_COMMANDS = [
       const targets = Array.isArray(args.targets) ? args.targets.map((t) => requiredString(t, "target")) : [];
       return {
         responses: await client.fanout({
+          ...forwardedHops(context?.handling),
           targets,
           content: requiredString(args.content, "content"),
           ...optionalString(args.correlationId) ? { correlationId: optionalString(args.correlationId) } : {},
@@ -16370,6 +16381,24 @@ function resolveHubCredentials(options = {}) {
     written: needsPersist === true
   };
 }
+function resolveAgentHubAuthToken(env, project) {
+  const envToken = env.KXM_AUTH_TOKEN?.trim();
+  if (envToken) return envToken;
+  const tokens = readHubEnvRecord(env)?.projectTokens;
+  if (!tokens || !Object.hasOwn(tokens, project)) return void 0;
+  return tokens[project]?.trim() || void 0;
+}
+var AgentProjectTokenMissingError = class extends Error {
+  code = "project_token_missing";
+  project;
+  constructor(project) {
+    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.`
+    );
+    this.name = "AgentProjectTokenMissingError";
+    this.project = project;
+  }
+};
 
 // plugins/kxm/src/repo-root.ts
 import { existsSync as existsSync5 } from "node:fs";
@@ -38060,13 +38089,11 @@ function piMeshExtension(pi) {
     removeMatchingLegacyRecoveryContext();
     const purpose = process.env.KXM_AGENT_PURPOSE ?? "General-purpose coding agent";
     const model = ctx2.model ? `${ctx2.model.provider}/${ctx2.model.id}` : void 0;
-    let autoStartToken;
     try {
       const config2 = loadKxmConfig(ctx2.cwd);
       if (hubAutoStartMode(config2) === "background") {
         const ensured = await ensureHubRunning({ config: config2, cwd: ctx2.cwd });
         if (ensured.status === "started") {
-          autoStartToken = ensured.authToken;
           ctx2.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"
@@ -38078,21 +38105,25 @@ function piMeshExtension(pi) {
     } catch (error2) {
       ctx2.ui.notify(`kxm hub auto-start failed: ${error2 instanceof Error ? error2.message : String(error2)}`, "warning");
     }
-    const envAuthToken = process.env.KXM_AUTH_TOKEN?.trim();
-    let hubAuthToken = envAuthToken || autoStartToken;
+    let hubAuthToken;
+    try {
+      hubAuthToken = resolveAgentHubAuthToken(process.env, project);
+    } catch (error2) {
+      ctx2.ui.notify(`kxm could not read persisted hub credentials: ${error2 instanceof Error ? error2.message : String(error2)}`, "error");
+      await applySessionChrome(ctx2, event, true);
+      return;
+    }
     if (!hubAuthToken) {
-      try {
-        hubAuthToken = readHubEnvRecord()?.authToken?.trim() || void 0;
-      } catch (error2) {
-        ctx2.ui.notify(`kxm could not read persisted hub credentials: ${error2 instanceof Error ? error2.message : String(error2)}`, "warning");
-      }
+      ctx2.ui.notify(new AgentProjectTokenMissingError(project).message, "error");
+      await applySessionChrome(ctx2, event, true);
+      return;
     }
     client = new HubClient({
       serverUrl,
       name,
       purpose,
       project,
-      ...hubAuthToken ? { authToken: hubAuthToken } : {},
+      authToken: hubAuthToken,
       ...model ? { model } : {}
     });
     notify = (message, type) => ctx2.ui.notify(message, type);
@@ -38248,9 +38279,10 @@ function piMeshExtension(pi) {
         if (!policy.allowed) {
           throw new Error(`tool_policy_denied: ${policy.detail ?? policy.error}`);
         }
+        const handling = activeInbound ? [activeInbound] : [];
         return result(
           await workflowCall(
-            () => cmd.execute(requireClient(), params ?? {}, { signal })
+            () => cmd.execute(requireClient(), params ?? {}, { signal, handling })
           )
         );
       }

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

@@ -15999,7 +15999,9 @@ var HubClient = class {
               options.workflowContext
             )
           } : {},
-          ...options.ttlMs ? { ttlMs: options.ttlMs } : {}
+          ...options.ttlMs ? { ttlMs: options.ttlMs } : {},
+          ...options.hops !== void 0 ? { hops: options.hops } : {},
+          ...options.maxHops !== void 0 ? { maxHops: options.maxHops } : {}
         });
         const completed = await this.awaitResponse(
           message.id,
@@ -16398,6 +16400,13 @@ function defaultProjectName(cwd, env = process.env) {
 import { chmodSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
+function forwardedHops(handling) {
+  if (!handling?.length) return void 0;
+  return {
+    hops: Math.max(...handling.map((message) => message.hops)) + 1,
+    maxHops: Math.min(...handling.map((message) => message.maxHops))
+  };
+}
 function requiredString(value, name) {
   if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} is required`);
   return value.trim();
@@ -16527,12 +16536,13 @@ var AGENT_COMMANDS = [
       required: ["target", "content"],
       additionalProperties: false
     },
-    async execute(client, args) {
+    async execute(client, args, context) {
       const delivery = optionalString(args.delivery);
       const correlationId = optionalString(args.correlationId);
       const idempotencyKey = optionalString(args.idempotencyKey);
       const workflowContext = optionalWorkflowContext(args.workflowContext);
       const message = await client.send({
+        ...forwardedHops(context?.handling),
         target: requiredString(args.target, "target"),
         content: requiredString(args.content, "content"),
         ...delivery ? { delivery } : {},
@@ -16610,6 +16620,7 @@ var AGENT_COMMANDS = [
       const targets = Array.isArray(args.targets) ? args.targets.map((t) => requiredString(t, "target")) : [];
       return {
         responses: await client.fanout({
+          ...forwardedHops(context?.handling),
           targets,
           content: requiredString(args.content, "content"),
           ...optionalString(args.correlationId) ? { correlationId: optionalString(args.correlationId) } : {},
@@ -17285,7 +17296,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.95";
+var VERSION = "0.7.97";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
@@ -17442,7 +17453,12 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const cmd = AGENT_COMMANDS_MAP.get(request.params.name);
     if (!cmd) throw new Error(`unknown tool: ${request.params.name}`);
     const args = asRecord2(request.params.arguments);
-    const result = await cmd.execute(client, args, { signal: extra.signal, inbox, notifiedInbox });
+    const result = await cmd.execute(client, args, {
+      signal: extra.signal,
+      inbox,
+      notifiedInbox,
+      handling: [...inbox.values()]
+    });
     return textResult(result);
   } catch (error2) {
     return {

package/plugins/kxm/dist/runtime-supervisor.js

@@ -17440,9 +17440,6 @@ import { createHash as createHash4, randomUUID } from "node:crypto";
 import { existsSync as existsSync5, lstatSync as lstatSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, realpathSync as realpathSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname5, join as join5, resolve as resolve4 } from "node:path";
 
-// plugins/kxm/src/bindings.ts
-import { homedir } from "node:os";
-
 // plugins/kxm/src/sqlite.ts
 import { createRequire } from "node:module";
 var requireFromHere = createRequire(import.meta.url);
@@ -17483,6 +17480,7 @@ var DatabaseSync = class {
 };
 
 // plugins/kxm/src/bindings.ts
+import { homedir } from "node:os";
 import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, parse, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
 var MAX_BINDING_RECORD_BYTES = 256 * 1024;
 var BINDING_LABEL = "Runtime-local repository bindings";

package/plugins/kxm/dist/runtime.js

@@ -17610,9 +17610,6 @@ import { createHash as createHash5, randomUUID } from "node:crypto";
 import { existsSync as existsSync5, lstatSync as lstatSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, realpathSync as realpathSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname5, join as join5, resolve as resolve4 } from "node:path";
 
-// plugins/kxm/src/bindings.ts
-import { homedir } from "node:os";
-
 // plugins/kxm/src/sqlite.ts
 import { createRequire } from "node:module";
 var requireFromHere = createRequire(import.meta.url);
@@ -17653,6 +17650,7 @@ var DatabaseSync = class {
 };
 
 // plugins/kxm/src/bindings.ts
+import { homedir } from "node:os";
 import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, parse, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
 var MAX_BINDING_RECORD_BYTES = 256 * 1024;
 var BINDING_LABEL = "Runtime-local repository bindings";
@@ -18555,6 +18553,20 @@ function projectRuntimeKey(projectRoot) {
   const folded = process.platform === "win32" ? canonical.toLocaleLowerCase("en-US") : canonical;
   return createHash5("sha256").update(folded, "utf8").digest("hex").slice(0, 24);
 }
+function kxmProjectRunEventsPath(projectRoot, env) {
+  return join5(kxmRuntimePaths({ env }).projectsDir, projectRuntimeKey(projectRoot), "run-events.db");
+}
+function projectRuntimeOwnsRun(projectRoot, runId, env) {
+  const path = kxmProjectRunEventsPath(projectRoot, env);
+  if (!existsSync5(path)) return false;
+  const database = new DatabaseSync(path, { readOnly: true });
+  try {
+    database.exec("PRAGMA busy_timeout = 5000");
+    return database.prepare("SELECT 1 FROM runs WHERE run_id = ?").get(runId) !== void 0;
+  } finally {
+    database.close();
+  }
+}
 var KXM_REGISTRY_SCHEMA_VERSION = 1;
 var REGISTRY_TABLES = {
   supervisor: ["singleton_id", "runtime_id", "pid", "port", "token_hash", "started_at", "heartbeat_at", "state"],
@@ -32067,7 +32079,7 @@ var DEFAULT_MODES_CONFIG = Object.freeze({
     browser: {
       description: "Web application exploration, screenshotting, and UI testing",
       baseTools: ["read", "bash"],
-      contextFiles: ["docs/browser-automation.md"],
+      contextFiles: ["docs/guides/browser-automation.md"],
       thinkingLevel: "medium",
       model: "grok/grok-4.6"
     }
@@ -33023,6 +33035,7 @@ export {
   kxmMonotonicNs,
   kxmPolicyRevisions,
   kxmProjectAdmissionLimits,
+  kxmProjectRunEventsPath,
   kxmRunRevisionDrift,
   kxmRuntimePaths,
   kxmRuntimeRequest,
@@ -33062,6 +33075,7 @@ export {
   probeHarnessesForModelAsync,
   projectKxmRunReadOnly,
   projectRuntimeKey,
+  projectRuntimeOwnsRun,
   pruneSocketDir,
   readKxmRunStatus,
   readKxmSupervisorToken,

package/plugins/kxm/dist/server.js

@@ -14779,7 +14779,7 @@ var require_dist = __commonJS({
 });
 
 // plugins/kxm/src/hub.ts
-import { createHash as createHash5, createHmac } from "node:crypto";
+import { createHash as createHash5, createHmac as createHmac2 } from "node:crypto";
 import { existsSync as existsSync6 } from "node:fs";
 import { createServer } from "node:http";
 import { isIP } from "node:net";
@@ -15650,7 +15650,7 @@ function workflowScopeExtras(operation, assignedCoordinatorName) {
 import { createHash as createHash3, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
 
 // plugins/kxm/src/workflow.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash2, createHmac } from "node:crypto";
 
 // plugins/kxm/src/relevance.ts
 var RELEVANCE_STOPWORDS = Object.freeze(/* @__PURE__ */ new Set([
@@ -16572,6 +16572,30 @@ function canonicalWorkflowDefinitionJson(definition) {
 function workflowDefinitionHash(definition) {
   return createHash2("sha256").update(canonicalWorkflowDefinitionJson(definition), "utf8").digest("hex");
 }
+var WORKFLOW_WEBHOOK_SIGNATURE_VERSION = "kxm-webhook-v1";
+var WORKFLOW_WEBHOOK_MAX_SKEW_SECONDS = 300;
+function workflowWebhookSignedMaterial(scope, timestamp, deliveryId, body) {
+  const fields = [
+    WORKFLOW_WEBHOOK_SIGNATURE_VERSION,
+    scope.runId === void 0 ? "start" : "signal",
+    timestamp,
+    deliveryId,
+    scope.definitionId,
+    scope.runId ?? "",
+    scope.signalKey ?? ""
+  ];
+  if (fields.some((field) => /[\r\n]/.test(field))) {
+    throw new ProtocolError(400, "webhook signature fields must not contain line breaks", "webhook_signature_field_invalid");
+  }
+  return Buffer.concat([
+    Buffer.from(`${fields.join("\n")}
+`, "utf8"),
+    typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body)
+  ]);
+}
+function workflowWebhookSignature(secret, scope, timestamp, deliveryId, body) {
+  return `sha256=${createHmac("sha256", secret).update(workflowWebhookSignedMaterial(scope, timestamp, deliveryId, body)).digest("hex")}`;
+}
 function resolveOutcomeRule(stage, outcomeKey) {
   const raw = stage.on?.[outcomeKey];
   return raw === void 0 ? void 0 : normalizeOutcomeValue(raw, `stage ${stage.id} on.${outcomeKey}`);
@@ -16895,6 +16919,13 @@ var HubHttpError = class extends Error {
 };
 
 // plugins/kxm/src/commands.ts
+function forwardedHops(handling) {
+  if (!handling?.length) return void 0;
+  return {
+    hops: Math.max(...handling.map((message) => message.hops)) + 1,
+    maxHops: Math.min(...handling.map((message) => message.maxHops))
+  };
+}
 function requiredString(value, name) {
   if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} is required`);
   return value.trim();
@@ -17024,12 +17055,13 @@ var AGENT_COMMANDS = [
       required: ["target", "content"],
       additionalProperties: false
     },
-    async execute(client, args) {
+    async execute(client, args, context) {
       const delivery = optionalString2(args.delivery);
       const correlationId = optionalString2(args.correlationId);
       const idempotencyKey = optionalString2(args.idempotencyKey);
       const workflowContext = optionalWorkflowContext(args.workflowContext);
       const message = await client.send({
+        ...forwardedHops(context?.handling),
         target: requiredString(args.target, "target"),
         content: requiredString(args.content, "content"),
         ...delivery ? { delivery } : {},
@@ -17107,6 +17139,7 @@ var AGENT_COMMANDS = [
       const targets = Array.isArray(args.targets) ? args.targets.map((t) => requiredString(t, "target")) : [];
       return {
         responses: await client.fanout({
+          ...forwardedHops(context?.handling),
           targets,
           content: requiredString(args.content, "content"),
           ...optionalString2(args.correlationId) ? { correlationId: optionalString2(args.correlationId) } : {},
@@ -21089,20 +21122,59 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
     const candidate = payload.webhookEvent ?? payload.event;
     return typeof candidate === "string" && candidate.trim() ? candidate.trim() : void 0;
   }
-  function verifyWebhookSignature(request, body, secret) {
-    const signature = request.headers["x-hub-signature-256"] ?? request.headers["x-hub-signature"];
-    if (typeof signature !== "string") {
-      throw new ProtocolError(401, "webhook signature is required", "webhook_signature_missing");
-    }
+  function requireSha256Signature(signature) {
     const separator = signature.indexOf("=");
     const algorithm = separator > 0 ? signature.slice(0, separator).toLowerCase() : "";
     if (algorithm !== "sha256") {
       throw new ProtocolError(401, "webhook signature must use sha256", "webhook_signature_unsupported");
     }
-    const expected = `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
+  }
+  function verifyProviderWebhookSignature(request, body, definition) {
+    if (definition.source === "generic") {
+      throw new ProtocolError(
+        401,
+        "generic workflow webhooks require x-kxm-signature over the timestamp, delivery ID, definition, and body",
+        "webhook_signature_missing"
+      );
+    }
+    const signature = request.headers["x-hub-signature-256"] ?? request.headers["x-hub-signature"];
+    if (typeof signature !== "string") {
+      throw new ProtocolError(401, "webhook signature is required", "webhook_signature_missing");
+    }
+    requireSha256Signature(signature);
+    const expected = `sha256=${createHmac2("sha256", definition.secret).update(body).digest("hex")}`;
     if (!safeTokenEqual(signature, expected)) {
       throw new ProtocolError(401, "webhook signature is invalid", "webhook_signature_invalid");
     }
+    const deliveryHeader = definition.source === "jira" ? request.headers["x-atlassian-webhook-identifier"] : request.headers["x-github-delivery"];
+    return requireString(deliveryHeader, "webhook delivery identifier", { max: 128 });
+  }
+  function verifyKxmWebhookSignature(request, body, secret, scope) {
+    const signature = request.headers["x-kxm-signature"];
+    if (typeof signature !== "string") {
+      throw new ProtocolError(
+        401,
+        "KXM webhooks require x-kxm-signature over the timestamp, delivery ID, route, and body",
+        "webhook_signature_missing"
+      );
+    }
+    requireSha256Signature(signature);
+    const timestamp = request.headers["x-kxm-timestamp"];
+    if (typeof timestamp !== "string" || !/^[0-9]{1,12}$/.test(timestamp)) {
+      throw new ProtocolError(401, "x-kxm-timestamp must be Unix seconds", "webhook_timestamp_invalid");
+    }
+    const deliveryId = requireString(request.headers["x-kxm-delivery-id"], "webhook delivery identifier", { max: 128 });
+    if (!safeTokenEqual(signature, workflowWebhookSignature(secret, scope, timestamp, deliveryId, body))) {
+      throw new ProtocolError(401, "webhook signature is invalid", "webhook_signature_invalid");
+    }
+    if (Math.abs(Date.now() / 1e3 - Number(timestamp)) > WORKFLOW_WEBHOOK_MAX_SKEW_SECONDS) {
+      throw new ProtocolError(
+        401,
+        `webhook timestamp is outside the ${WORKFLOW_WEBHOOK_MAX_SKEW_SECONDS}-second window; re-sign at send time`,
+        "webhook_timestamp_expired"
+      );
+    }
+    return deliveryId;
   }
   function workflowPrompt(definition, runId, payload) {
     const rendered = renderWorkflowPrompt(definition.promptTemplate, payload);
@@ -21125,7 +21197,7 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
       stageList,
       "",
       `At every stage, record material knowledge with kxm_workflow_record in one of these categories: ${JOURNAL_CATEGORIES.join(", ")}. Pass the stageId the entry belongs to; the hub binds the attempt and, when you omit area, uses the stage's declared area.`,
-      "Keep repository-local configuration in .kxm/config, logs in .kxm/logs, and durable workflow artifacts in .kxm/assets; never commit runtime logs, state, or secrets.",
+      "Keep reviewed configuration as YAML directly under .kxm/ (such as .kxm/project.yaml and .kxm/workflows/), logs in .kxm/logs, and durable workflow artifacts in .kxm/assets. Never create .kxm/config, which KXM refuses, and never commit runtime logs, .kxm/state, or secrets.",
       "Complete each stage with kxm_workflow_checkpoint. Supply evidence as an object whose keys exactly match the stage's required evidence keys. Unrelated keys never satisfy a requirement. A warning or failure must be corrected and checkpointed again until it passes or the attempt limit is reached.",
       "For a peer-evidence requirement, send or fan out with workflowContext containing this run ID, the exact stage ID, requirement key, and current 1-based attempt. At checkpoint, cite only the returned message IDs under evidenceRefs; the hub derives producer and reply provenance.",
       "When an external system must finish asynchronously, call kxm_workflow_wait with a stable signal key and any already-verified keyed evidence. That evidence is accumulated with the signed callback before the stage can pass; then settle the turn.",
@@ -21463,14 +21535,17 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
         const definition = webhookWorkflows2.get(definitionId);
         if (!definition) throw new ProtocolError(404, "webhook workflow not found", "webhook_not_found");
         const rawBody = await readBody(request);
-        verifyWebhookSignature(request, rawBody, definition.signalSecret ?? definition.secret);
+        const deliveryId = verifyKxmWebhookSignature(
+          request,
+          rawBody,
+          definition.signalSecret ?? definition.secret,
+          { definitionId: definition.id, runId, signalKey }
+        );
         const body = parseJsonBody(rawBody);
         const run = workflowRuns.get(runId);
         if (!run || run.definitionId !== definition.id) {
           throw new ProtocolError(404, "workflow run not found", "workflow_not_found");
         }
-        const deliveryHeader = request.headers["x-atlassian-webhook-identifier"] ?? request.headers["x-github-delivery"] ?? request.headers["x-kxm-delivery-id"];
-        const deliveryId = requireString(deliveryHeader, "webhook delivery identifier", { max: 128 });
         const payloadHash = createHash5("sha256").update(rawBody).digest("hex");
         const existingReceipt = run.signalReceipts?.find((receipt2) => receipt2.deliveryId === deliveryId);
         if (existingReceipt) {
@@ -21616,7 +21691,8 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
         const definition = webhookWorkflows2.get(definitionId);
         if (!definition) throw new ProtocolError(404, "webhook workflow not found", "webhook_not_found");
         const rawBody = await readBody(request);
-        verifyWebhookSignature(request, rawBody, definition.secret);
+        const bodyOnlySignature = request.headers["x-kxm-signature"] === void 0;
+        const deliveryId = bodyOnlySignature ? verifyProviderWebhookSignature(request, rawBody, definition) : verifyKxmWebhookSignature(request, rawBody, definition.secret, { definitionId: definition.id });
         const payload = parseJsonBody(rawBody);
         const event = webhookEvent(request, payload);
         if (definition.event && event !== definition.event) {
@@ -21627,15 +21703,30 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
           response.writeHead(204, { "cache-control": "no-store" }).end();
           return;
         }
-        const deliveryHeader = request.headers["x-atlassian-webhook-identifier"] ?? request.headers["x-github-delivery"] ?? request.headers["x-kxm-delivery-id"];
-        const deliveryId = requireString(deliveryHeader, "webhook delivery identifier", { max: 128 });
+        const payloadHash = createHash5("sha256").update(rawBody).digest("hex");
         const existing = [...workflowRuns.values()].find(
           (run2) => run2.definitionId === definition.id && run2.deliveryId === deliveryId
         );
         if (existing) {
-          json(response, 200, { run: existing, duplicate: true });
+          if (existing.payloadHash !== payloadHash) {
+            throw new ProtocolError(
+              409,
+              "webhook delivery identifier was already used for a different body",
+              "webhook_delivery_conflict"
+            );
+          }
+          json(response, 200, { duplicate: true, runId: existing.id, status: existing.status });
           return;
         }
+        if (bodyOnlySignature && [...workflowRuns.values()].some(
+          (run2) => run2.definitionId === definition.id && run2.payloadHash === payloadHash
+        )) {
+          throw new ProtocolError(
+            409,
+            "this signed body already started a run under another delivery identifier",
+            "webhook_payload_replayed"
+          );
+        }
         const target = findKnownTarget(definition.project, definition.target);
         const createdAt = nowIso();
         const runId = newId("run");
@@ -21685,7 +21776,7 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
           definitionId: definition.id,
           source: definition.source,
           deliveryId,
-          payloadHash: createHash5("sha256").update(rawBody).digest("hex"),
+          payloadHash,
           definitionHash: workflowDefinitionHash(definition),
           ...event ? { event } : {},
           project: definition.project,
@@ -21716,7 +21807,7 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
           project: definition.project,
           target: target.id
         });
-        json(response, 202, { run, duplicate: false });
+        json(response, 202, { run, runId: run.id, duplicate: false });
         return;
       }
       if (method === "GET" && url.pathname === "/metrics") {
@@ -22656,7 +22747,11 @@ data: ${JSON.stringify({ agent: publicAgent(current, staleAfterMs) })}
         const hops = parseBoundedInteger(body.hops, "hops", 0, 0, 100);
         const maxHops = parseBoundedInteger(body.maxHops, "maxHops", DEFAULT_MAX_HOPS, 1, 20);
         if (hops >= maxHops) {
-          throw new ProtocolError(400, `hop limit reached (${hops}/${maxHops})`, "hop_limit_reached");
+          throw new ProtocolError(
+            400,
+            `hop limit reached (${hops}/${maxHops}): this request would extend a chain of forwarded requests past its limit; answer the inbound request directly`,
+            "hop_limit_reached"
+          );
         }
         const ttlMs = parseBoundedInteger(
           body.ttlMs,

package/plugins/kxm/package.json

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

package/plugins/kxm/skills/kxm/references/protocol.md

@@ -112,7 +112,9 @@ token before committing anything shared — a refusal means stop, not retry.
 - `replied`: contains the recipient's final reply.
 - `cancelled`: sender cancelled queued or delivered work.
 - `expired`: the request exceeded its TTL before a reply.
-- `error`: terminal failure.
+- `error`: reserved. The protocol declares it, but the hub never sets it, so
+  it is not a failure path to wait for. A `kxm_fanout` entry with
+  `status: "error"` reports a local send or wait failure, not this state.
 
 Messages use a 24-hour default TTL and terminal records are retained for seven days by default. TTL begins when the message is sent and includes queued time; normally omit it for model work. A fanout's local wait ending does not change message state and returns a recoverable pending handle. Inspect it with `kxm_get` or repeat the exact request using the same correlation and idempotency prefix. Never create a replacement key while the original is pending, and never count a pending peer as workflow evidence. A stable `idempotencyKey` deduplicates an exact retry from the same sender. Durable `kxm_fanout` calls should use the workflow run ID as `correlationId` and a stage-specific `idempotencyKeyPrefix`; the client scopes the resulting key by correlation and normalized target. State is persisted in SQLite by the standard hub executable.
 

package/plugins/kxm/skills/kxm-browser-auth/SKILL.md

@@ -24,7 +24,7 @@ Always retrieve credentials and API keys directly from `pass-cli`:
 pass-cli item view --vault-name "<vault>" --item-title "<title>" --field password
 
 # Retrieve Steel infrastructure API key
-pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --field STEEL_API_KEY
+pass-cli item view --vault-name "<vault>" --item-title "<steel-item>" --field STEEL_API_KEY
 ```
 
 ### 2. Secret Redaction Invariants

package/plugins/kxm/skills/kxm-browser-diagnostics/SKILL.md

@@ -13,8 +13,8 @@ Use this skill to investigate and resolve connectivity failures, CDP attachment
 
 - **Symptom**: `Failed to fetch Steel session (401)` or `Connection refused`.
 - **Diagnosis**:
-  - Verify Steel API endpoint is reachable: `curl -sI https://steel.kontextmind.com/v1/health`.
-  - Check `STEEL_API_KEY` in `pass-cli`: `pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)"`.
+  - Verify Steel API endpoint is reachable: `curl -sI "$STEEL_API_URL/v1/health"`.
+  - Check that `STEEL_API_KEY` is set in the environment (`test -n "$STEEL_API_KEY" && echo set`); never print its value.
 - **Remedy**: Update expired or missing API key in your session environment.
 
 ### 2. CDP WebSocket Attachment Failure
@@ -35,14 +35,14 @@ Use this skill to investigate and resolve connectivity failures, CDP attachment
 
 ### 4. Interactive Takeover Viewer Inaccessible
 
-- **Symptom**: `https://steel.kontextmind.com/ui` opens but cannot interact with elements.
+- **Symptom**: `$STEEL_UI_URL` opens but cannot interact with elements.
 - **Diagnosis**: Self-hosted Steel OSS serves the session screencast and devtools.
-- **Remedy**: Connect directly to the devtools inspector URL: `https://steel.kontextmind.com/v1/devtools/inspector.html` or open the browser devtools panel to perform input actions.
+- **Remedy**: Connect directly to the devtools inspector URL: `$STEEL_API_URL/v1/devtools/inspector.html` or open the browser devtools panel to perform input actions.
 
 ### 5. Orphaned Browser Processes & Cleanup
 
 - **Symptom**: Node memory pressure or high active session counts.
-- **Diagnosis**: Query active sessions list: `curl -s https://steel.kontextmind.com/v1/sessions`.
+- **Diagnosis**: Query active sessions list: `printf 'x-steel-api-key: %s\n' "$STEEL_API_KEY" | curl -sS -H @- "$STEEL_API_URL/v1/sessions"`.
 - **Remedy**:
   - Iterate through inactive sessions and post `/release` for each stale ID.
   - Ensure all automation scripts wrap browser usage in `try...finally` to release sessions reliably.