@kontextmind/kxm 0.7.96 → 0.7.98

package/plugins/kxm/src/engine.ts

@@ -3,6 +3,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse } from "yaml";
 import { isRouteAdmitted, listRoleBindings } from "./routes.ts";
+import { oneShotWriterArgs } from "./harness.ts";
+import { applyAuthoringWitness, captureWorktreeWitness } from "./worktree-witness.ts";
 import {
   buildFormalContextPacket,
   buildHandoffManifest,
@@ -153,6 +155,8 @@ export interface KxmProducerRequest {
   readonly thinking?: string | undefined;
   readonly agentRole?: string | undefined;
   readonly harness?: string | undefined;
+  /** Live producers select an audited argv profile from this ceiling. */
+  readonly permission?: "read-only" | "edit" | undefined;
   readonly contextPacket?: FormalContextPacketV2 | undefined;
   readonly handoffManifest?: HandoffManifestV1 | undefined;
 }
@@ -1593,6 +1597,14 @@ function prepareDispatch(
       return { kind: "return", state, handoff: { ...routeResult.error, stepId } };
     }
     resolvedRoute = routeResult;
+    const writeRefusal = unsupportedLiveWrite(
+      context.projectRoot,
+      step,
+      agentId,
+      resolvedRoute.selector,
+      loadKxmRunPlanEnvelope(context.eventStore, run).projectLimits.maxConcurrentRuns,
+    );
+    if (writeRefusal) return { kind: "return", state, handoff: { ...writeRefusal, stepId } };
   }
 
   const used = state.stepAttempts[stepId] ?? 0;
@@ -1825,6 +1837,7 @@ function birthMember(
       signal: controller.signal,
       prompt: input.step.instructions ? `${input.step.instructions}\n\n${generatedPrompt}` : generatedPrompt,
       thinking: input.stepAttempt <= 1 ? "low" : "medium",
+      permission: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
       contextPacket,
       ...(resolvedRoute ? { provider: resolvedRoute.provider, model: resolvedRoute.model } : {}),
     },
@@ -1998,7 +2011,18 @@ async function drivePanel(
         if (!executingBound()) return { attemptId: member.attemptId, invoked: false, skipped: true };
         kxmPanelDispatchSeams.beforeInvoke?.(member);
         if (!executingBound()) return { attemptId: member.attemptId, invoked: false, skipped: true };
+        const live = member.producerId !== "driver-simulated";
+        const writes = Object.values(member.step.repositories).some((access) => access === "write");
+        const before = live ? captureWorktreeWitness(context.projectRoot) : undefined;
         const produced = await invokeProducer(producer, member.request);
+        if (live && produced.result && before) {
+          const after = captureWorktreeWitness(context.projectRoot);
+          return {
+            attemptId: member.attemptId,
+            invoked: true,
+            produced: { ...produced, result: applyAuthoringWitness(produced.result, { writes, before, after }) },
+          };
+        }
         return { attemptId: member.attemptId, invoked: true, produced };
       } catch (error) {
         member.controller.abort();
@@ -2722,11 +2746,102 @@ function unsupportedStep(
       return { reason: "step_unsupported", field: "repositories", detail: `invalid repository access '${access}' on ${repoId}` };
     }
   }
-  if (producerId !== "driver-simulated" && Object.values(step.repositories).some((access) => access === "write")) {
+  return undefined;
+}
+
+function readYamlRecord(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = parse(readFileSync(path, "utf8")) as unknown;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function agentHarness(projectRoot: string, agentId: string): string | undefined {
+  const harness = readYamlRecord(join(projectRoot, ".kxm", "agents", `${agentId}.yaml`))?.harness;
+  return typeof harness === "string" && harness.length > 0 ? harness : undefined;
+}
+
+function projectDefaultHarness(projectRoot: string): string {
+  const harness = readYamlRecord(join(projectRoot, ".kxm", "project.yaml"))?.defaultHarness;
+  return typeof harness === "string" && harness.length > 0 ? harness : "pi";
+}
+
+/**
+ * Live write steps run only on an audited writer profile, and only when the
+ * developer roster (when present) lists that harness and model as an edit writer.
+ * A missing roster is a fresh project: route admission is the other gate.
+ *
+ * The authoring witness fingerprints the one project checkout around each
+ * spawn, so it can only attribute a change to a lone writer. A write step with
+ * more than one assignment would run several writers there (and member n runs
+ * as allowedAgents[n], which the writer check below never sees), and a
+ * project that admits concurrent runs lets another run's writer edit the tree
+ * mid-attempt. Both hand off.
+ */
+function unsupportedLiveWrite(
+  projectRoot: string,
+  step: KxmCompiledStep,
+  agentId: string,
+  selector: string,
+  maxConcurrentRuns: number,
+): Omit<KxmRunHandoff, "stepId"> | undefined {
+  if (!Object.values(step.repositories).some((access) => access === "write")) return undefined;
+  if (step.assignments.maximum !== 1) {
+    return {
+      reason: "step_unsupported",
+      field: "assignments.maximum",
+      detail: "live write steps run a single assignment; the checkout witness cannot attribute edits between writers",
+    };
+  }
+  if (maxConcurrentRuns !== 1) {
+    return {
+      reason: "step_unsupported",
+      field: "limits.maxConcurrentRuns",
+      detail: "live write steps require limits.maxConcurrentRuns of 1; concurrent runs share one checkout",
+    };
+  }
+  const harness = agentHarness(projectRoot, agentId) ?? projectDefaultHarness(projectRoot);
+  if (!oneShotWriterArgs(harness)) {
     return {
       reason: "step_unsupported",
       field: "repositories",
-      detail: "live write steps are unsupported until writer sandboxing witness passes",
+      detail: `live write steps require an audited writer profile; ${harness} has none`,
+    };
+  }
+  const rosterPath = join(projectRoot, ".kxm", "roster.yaml");
+  if (!existsSync(rosterPath)) return undefined;
+  const roster = readYamlRecord(rosterPath);
+  if (!roster || roster.schema !== "kxm.developer-roster.v1") {
+    return { reason: "step_unsupported", field: "model", detail: "live write steps require a readable kxm.developer-roster.v1" };
+  }
+  const routes = roster.routes;
+  const lineup = roster.lineup;
+  const writerIds = lineup && typeof lineup === "object" && !Array.isArray(lineup)
+    ? (lineup as Record<string, unknown>).writer
+    : undefined;
+  if (!routes || typeof routes !== "object" || Array.isArray(routes) || !Array.isArray(writerIds)) {
+    return { reason: "step_unsupported", field: "model", detail: "developer roster has no writer lineup" };
+  }
+  const allowed = writerIds.some((id) => {
+    if (typeof id !== "string") return false;
+    const route = (routes as Record<string, unknown>)[id];
+    if (!route || typeof route !== "object" || Array.isArray(route)) return false;
+    const record = route as Record<string, unknown>;
+    if (record.harness !== harness || record.status !== "admitted") return false;
+    if (!Array.isArray(record.permissions) || !record.permissions.includes("edit")) return false;
+    const model = typeof record.model === "string" ? record.model : "";
+    const vendor = typeof record.vendor === "string" ? record.vendor : "";
+    return model === selector || (vendor.length > 0 && `${vendor}/${model}` === selector);
+  });
+  if (!allowed) {
+    return {
+      reason: "step_unsupported",
+      field: "model",
+      detail: `live write route ${selector} on ${harness} is not on the developer roster writer lineup`,
     };
   }
   return undefined;

package/plugins/kxm/src/extension.ts

@@ -6,7 +6,7 @@ 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 { AgentProjectTokenMissingError, resolveAgentHubAuthToken } from "./hub-env.ts";
 import { defaultProjectName } from "./project-name.ts";
 import { nousFactoryWork, type NousRegistrationReport } from "./nous-pi.ts";
 import {
@@ -685,13 +685,11 @@ 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" : ""),
@@ -704,23 +702,29 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
     } 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;
+    // An agent session registers with KXM_AUTH_TOKEN or this project's saved project
+    // token only. The hub admits its admin token to any project missing from its token
+    // map, so neither the persisted admin token nor the one auto-start resolved may
+    // stand in for a project token.
+    let hubAuthToken: string | undefined;
+    try {
+      hubAuthToken = resolveAgentHubAuthToken(process.env, project);
+    } catch (error) {
+      ctx.ui.notify(`kxm could not read persisted hub credentials: ${error instanceof Error ? error.message : String(error)}`, "error");
+      await applySessionChrome(ctx, event, true);
+      return;
+    }
     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");
-      }
+      ctx.ui.notify(new AgentProjectTokenMissingError(project).message, "error");
+      await applySessionChrome(ctx, event, true);
+      return;
     }
     client = new HubClient({
       serverUrl,
       name,
       purpose,
       project,
-      ...(hubAuthToken ? { authToken: hubAuthToken } : {}),
+      authToken: hubAuthToken,
       ...(model ? { model } : {}),
     });
     notify = (message, type) => ctx.ui.notify(message, type);
@@ -893,9 +897,11 @@ export default function piMeshExtension(pi: ExtensionAPI): void | Promise<void>
         if (!policy.allowed) {
           throw new Error(`tool_policy_denied: ${policy.detail ?? policy.error}`);
         }
+        // A request sent while handling the active inbound request continues its hop chain.
+        const handling = activeInbound ? [activeInbound] : [];
         return result(
           await workflowCall(() =>
-            cmd.execute(requireClient(), (params ?? {}) as Record<string, unknown>, { signal }),
+            cmd.execute(requireClient(), (params ?? {}) as Record<string, unknown>, { signal, handling }),
           ),
         );
       },

package/plugins/kxm/src/github-watch.ts

@@ -1,6 +1,6 @@
-import { createHmac, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { redactSecrets } from "./redact.ts";
-import type { WorkflowEvidenceInput } from "./workflow.ts";
+import { workflowWebhookHeaders, type WorkflowEvidenceInput } from "./workflow.ts";
 
 export type WatchStatus = "passed" | "failed" | "warning";
 
@@ -109,7 +109,6 @@ export async function postWorkflowSignal(input: {
   fetchImpl?: typeof fetch;
 }): Promise<{ httpStatus: number; duplicate: boolean }> {
   const body = JSON.stringify({ status: input.status, summary: input.summary, evidence: input.evidence });
-  const signature = `sha256=${createHmac("sha256", input.signalSecret).update(body).digest("hex")}`;
   const endpoint = [
     input.serverUrl.replace(/\/$/, ""),
     "v1/webhooks",
@@ -123,8 +122,12 @@ export async function postWorkflowSignal(input: {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      "x-hub-signature-256": signature,
-      "x-kxm-delivery-id": input.deliveryId,
+      ...workflowWebhookHeaders({
+        secret: input.signalSecret,
+        scope: { definitionId: input.definitionId, runId: input.runId, signalKey: input.signalKey },
+        deliveryId: input.deliveryId,
+        body,
+      }),
     },
     body,
   }, input.timeoutMs ?? 15_000);

package/plugins/kxm/src/harness.ts

@@ -518,6 +518,35 @@ export function oneShotReadOnlyArgs(harness: string): readonly string[] | undefi
   return Object.hasOwn(READ_ONLY_ONESHOT_ARGS, harness) ? READ_ONLY_ONESHOT_ARGS[harness as keyof typeof READ_ONLY_ONESHOT_ARGS] : undefined;
 }
 
+/**
+ * Audited edit profiles. These are a writer containment, not read-only flags
+ * with the sandbox removed. They match the assignment helper
+ * (`scripts/harness-run.mjs` `buildArgv` for `permission: "edit"` with hooks
+ * and skills refused):
+ *
+ * - Pi: `-a` auto-approves tools so the process can edit the checkout, while
+ *   extensions, skills, prompt templates, and session persistence stay off.
+ *   `--no-tools` is the read-only profile and is not used here.
+ * - Grok: `--always-approve` so edits are not an interactive prompt, with
+ *   subagents and web search disabled. Grok has no audited read-only edit
+ *   mix; the read-only one-shot flags stay on the read-only profile.
+ *
+ * Claude, Codex, agy, and Kimi stay read-only. A live write step on a harness
+ * without an entry here hands off instead of spawning unconstrained.
+ */
+const WRITER_ONESHOT_ARGS = Object.freeze({
+  pi: Object.freeze(["-a", "--no-extensions", "--no-skills", "--no-prompt-templates", "--no-session"]),
+  grok: Object.freeze(["--always-approve", "--no-subagents", "--disable-web-search"]),
+});
+
+export function oneShotWriterArgs(harness: string): readonly string[] | undefined {
+  return Object.hasOwn(WRITER_ONESHOT_ARGS, harness) ? WRITER_ONESHOT_ARGS[harness as keyof typeof WRITER_ONESHOT_ARGS] : undefined;
+}
+
+export function oneShotPermissionArgs(harness: string, permission: "read-only" | "edit"): readonly string[] | undefined {
+  return permission === "edit" ? oneShotWriterArgs(harness) : oneShotReadOnlyArgs(harness);
+}
+
 export const BUILTIN_HARNESSES: readonly HarnessCatalogEntry[] = Object.freeze([
   {
     id: "pi",

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

@@ -236,7 +236,8 @@ export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: strin
 }
 
 /**
- * Token an agent session (the Claude MCP server) registers with: explicit `KXM_AUTH_TOKEN`,
+ * Token an agent session (the Claude MCP server, the Pi extension, the `kxm peer` and
+ * `kxm workflow` agent commands) registers with: explicit `KXM_AUTH_TOKEN`,
  * else the persisted project token for `project`, else nothing. It never returns the
  * persisted admin token. The hub accepts the admin token for any project missing from its
  * project-token map, so an agent falling back to it would join a project nobody issued it a
@@ -251,6 +252,23 @@ export function resolveAgentHubAuthToken(env: NodeJS.ProcessEnv, project: string
   return tokens[project]?.trim() || undefined;
 }
 
+/**
+ * Refusal for an agent session that has neither `KXM_AUTH_TOKEN` nor a saved project
+ * token for its project. The fix is the operator's, so the message names it.
+ */
+export class AgentProjectTokenMissingError extends Error {
+  readonly code = "project_token_missing";
+  readonly project: string;
+
+  constructor(project: string) {
+    super(
+      `kxm has no project token for project ${project} on this machine. Set KXM_AUTH_TOKEN to that project's token, or add ${project} to the hub KXM_PROJECT_TOKENS (list every existing project too, because that variable replaces the saved map). An agent never uses the hub admin token.`,
+    );
+    this.name = "AgentProjectTokenMissingError";
+    this.project = project;
+  }
+}
+
 /**
  * Admin-scoped hub reads (`/v1/ops/snapshot`, …) are rejected with 401 by a project token,
  * so this variant resolves the admin credential only: explicit `KXM_AUTH_TOKEN`, else the

package/plugins/kxm/src/hub.ts

@@ -70,6 +70,8 @@ import {
   verifyWorkflowEvidenceReferences,
   workflowDefinitionHash,
   workflowEvidenceStrings,
+  workflowWebhookSignature,
+  WORKFLOW_WEBHOOK_MAX_SKEW_SECONDS,
   type ImprovementArea,
   type JournalCategory,
   type WebhookWorkflowDefinition,
@@ -81,6 +83,7 @@ import {
   type WorkflowSignalReceipt,
   type WorkflowStageState,
   type WorkflowVerifiedEvidence,
+  type WorkflowWebhookScope,
 } from "./workflow.ts";
 
 export interface RateLimitOptions {
@@ -971,20 +974,77 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
     return typeof candidate === "string" && candidate.trim() ? candidate.trim() : undefined;
   }
 
-  function verifyWebhookSignature(request: IncomingMessage, body: Buffer, secret: string): void {
-    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: string): void {
     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")}`;
+  }
+
+  /** Jira and GitHub sign only the body, so a provider delivery ID is unsigned
+   * routing data. Returns that provider's own delivery header. */
+  function verifyProviderWebhookSignature(
+    request: IncomingMessage,
+    body: Buffer,
+    definition: WebhookWorkflowDefinition,
+  ): string {
+    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=${createHmac("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 });
+  }
+
+  /** The KXM sender contract (see workflowWebhookSignedMaterial): the
+   * signature binds the delivery ID, timestamp, and route scope. A valid
+   * signature outside the skew window is refused as expired. */
+  function verifyKxmWebhookSignature(
+    request: IncomingMessage,
+    body: Buffer,
+    secret: string,
+    scope: WorkflowWebhookScope,
+  ): string {
+    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() / 1_000 - 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(
@@ -1013,7 +1073,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
       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.",
@@ -1335,16 +1395,17 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         const definition = webhookWorkflows.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 = createHash("sha256").update(rawBody).digest("hex");
         const existingReceipt = run.signalReceipts?.find((receipt) => receipt.deliveryId === deliveryId);
         if (existingReceipt) {
@@ -1491,7 +1552,13 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         const definition = webhookWorkflows.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);
+        // A KXM sender signs the delivery ID and timestamp. A Jira or GitHub
+        // delivery signs only its body, so for those the body is the replay
+        // identity: it may start one run, under one delivery ID.
+        const bodyOnlySignature = request.headers["x-kxm-signature"] === undefined;
+        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) {
@@ -1502,17 +1569,30 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           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 = createHash("sha256").update(rawBody).digest("hex");
         const existing = [...workflowRuns.values()].find(
           (run) => run.definitionId === definition.id && run.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(
+          (run) => run.definitionId === definition.id && run.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");
@@ -1562,7 +1642,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           definitionId: definition.id,
           source: definition.source,
           deliveryId,
-          payloadHash: createHash("sha256").update(rawBody).digest("hex"),
+          payloadHash,
           definitionHash: workflowDefinitionHash(definition),
           ...(event ? { event } : {}),
           project: definition.project,
@@ -1593,7 +1673,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           project: definition.project,
           target: target.id,
         });
-        json(response, 202, { run, duplicate: false });
+        json(response, 202, { run, runId: run.id, duplicate: false });
         return;
       }
 
@@ -2693,7 +2773,11 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         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/src/improve-sources.ts

@@ -1,8 +1,8 @@
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
 import { discoverKxmProjectRoot } from "./project-config.ts";
-import { kxmRuntimePaths, projectRuntimeKey } from "./runtime-store.ts";
+import { kxmProjectRunEventsPath } from "./runtime-store.ts";
 import { parseRoutingRecordV2, ROUTING_RECORD_V2_SCHEMA, type RoutingRecord, type RoutingRecordV2 } from "./routing.ts";
 import { readRoutingRecords, telemetryPath } from "./telemetry.ts";
 
@@ -45,11 +45,6 @@ const ENGINE_EVENTS_SQL = "SELECT run_id, sequence, event_type, payload FROM eve
 /** The simulated producer's harness label; its attempts measure nothing. */
 const SIMULATED_HARNESS = "driver-simulated";
 
-/** The project's Runtime event store, derived exactly as the Runtime derives it. */
-export function kxmProjectRunEventsPath(projectRoot: string, env: NodeJS.ProcessEnv): string {
-  return join(kxmRuntimePaths({ env }).projectsDir, projectRuntimeKey(projectRoot), "run-events.db");
-}
-
 interface RunLog {
   lastStatus?: string;
   /** Latest step.entered sequence per step. */