@kontextmind/kxm 0.7.95 → 0.7.97

package/plugins/kxm/src/cli.ts

@@ -18,7 +18,7 @@ import { Command, CommanderError } from "commander";
 import { readInstalledKxmVersion } from "./kxm-update.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { HubClient } from "./client.ts";
-import { resolveClientHubAuthToken } from "./hub-env.ts";
+import { AgentProjectTokenMissingError, resolveAgentHubAuthToken } from "./hub-env.ts";
 import { defaultProjectName } from "./project-name.ts";
 import {
   AGENT_COMMANDS_MAP,
@@ -27,6 +27,7 @@ import {
 import { discoverKxmProjectRoot } from "./project-config.ts";
 import { JOURNAL_CATEGORIES } from "./workflow.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "./runtime-supervisor.ts";
+import { projectRuntimeOwnsRun } from "./runtime-store.ts";
 
 // Submodule imports
 import {
@@ -234,14 +235,17 @@ async function ensureCliClient(runtime: Runtime): Promise<HubClient> {
   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 = resolveClientHubAuthToken(runtime.env, project);
+  // These commands act as a peer agent, so they take the agent credential: never the
+  // persisted admin token, which the hub accepts for any project without its own token.
+  const authToken = resolveAgentHubAuthToken(runtime.env, project);
+  if (!authToken) throw new AgentProjectTokenMissingError(project);
   const client = new HubClient({
     serverUrl,
     name,
     project,
     purpose,
     fetchImpl: runtime.fetchImpl,
-    ...(authToken ? { authToken } : {}),
+    authToken,
   });
   await client.start(() => {});
   return client;
@@ -308,11 +312,12 @@ async function dispatchAgentCliCommand(
     }
   }
 
-  // Handle KXM run binding for workflow wait
+  // A workflow wait on a run this project's Runtime owns goes to the Runtime; any other
+  // run id, including a hub workflow run of the same shape, goes to the hub.
   if (toolName === "kxm_workflow_wait") {
     const runId = typeof args.runId === "string" ? args.runId : undefined;
     const projectRoot = discoverKxmProjectRoot(runtime.cwd);
-    if (runId && projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
+    if (runId && projectRoot && projectRuntimeOwnsRun(projectRoot, runId, runtime.env)) {
       if (runtime.dryRun) {
         print(runtime.io, runtime.json, { ok: true, command: "workflow wait", runId, dryRun: true }, `would wait for signal on KXM run ${runId}`);
         return 0;
@@ -349,6 +354,15 @@ async function dispatchAgentCliCommand(
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof AgentProjectTokenMissingError) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, error: error.code, project: error.project, nextAction: "export_kxm_auth_token", detail: message },
+        message,
+      );
+      return 2;
+    }
     print(runtime.io, runtime.json, { ok: false, error: "command_failed", detail: message }, `command failed: ${message}`);
     return 1;
   } finally {
@@ -402,7 +416,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       });
     });
 
-  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of all stores with a hashed manifest"))
+  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of the project hub store with a hashed manifest (Runtime stores under the user state root are not included)"))
     .option("--out <dir>", "Directory to write backup and manifest")
     .action(async function backupAction(this: Command, options: { out?: string }) {
       result.code = await cmdBackup(runtimeFrom(ctx, this), options);
@@ -415,7 +429,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
 
   addGlobalOptions(program.command("run").description("Create a KXM run (offline-first; kxm runs drive <runId> --simulated executes it model-free)")
     .argument("[workflow]", "Workflow id to run")
-    .argument("[prompt...]", "Run prompt (hashed, never stored raw)")
+    .argument("[prompt...]", "Run prompt (events keep its hash; the full text is kept in a local 0600 sidecar file)")
     .action(async function runAction(this: Command, workflow: string | undefined, promptParts: string[]) {
       result.code = await cmdKxmRun(runtimeFrom(ctx, this), workflow, promptParts);
     }));
@@ -426,7 +440,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .action(async function runStatusAction(this: Command, runId: string) {
       result.code = await cmdKxmRunStatus(runtimeFrom(ctx, this), runId);
     });
-  addGlobalOptions(runCmd.command("drive").description("Drive a run with an explicit model-free simulation"))
+  addGlobalOptions(runCmd.command("drive").description("Drive a run with live harness calls, or with the model-free simulation when --simulated is passed"))
     .argument("<runId>", "Run id")
     .option("--simulated", "Use the model-free simulation producer")
     .option("--wait", "Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement")

package/plugins/kxm/src/client.ts

@@ -259,6 +259,8 @@ export class HubClient {
     ttlMs?: number;
     timeoutMs?: number;
     signal?: AbortSignal;
+    hops?: number;
+    maxHops?: number;
   }): Promise<FanoutResult[]> {
     const targets = [...new Set(options.targets.map((target) => target.trim().toLowerCase()).filter(Boolean))];
     if (targets.length < 1 || targets.length > 3) throw new Error("fanout requires between one and three unique targets");
@@ -280,6 +282,8 @@ export class HubClient {
             ),
           } : {}),
           ...(options.ttlMs ? { ttlMs: options.ttlMs } : {}),
+          ...(options.hops !== undefined ? { hops: options.hops } : {}),
+          ...(options.maxHops !== undefined ? { maxHops: options.maxHops } : {}),
         });
         const completed = await this.awaitResponse(
           message.id,

package/plugins/kxm/src/commands.ts

@@ -74,6 +74,26 @@ export interface CommandExecutionContext {
   signal?: AbortSignal | undefined;
   inbox?: Map<string, MessageRecord> | undefined;
   notifiedInbox?: Set<string> | undefined;
+  /** Inbound requests this session is handling: the Pi extension's active request, the MCP
+   * server's open inbox. A request sent meanwhile is one more hop along their chain. */
+  handling?: readonly Pick<MessageRecord, "hops" | "maxHops">[] | undefined;
+}
+
+/**
+ * Hop fields for a request sent while handling inbound work: one hop past the furthest
+ * handled request, under the tightest limit among them, so the hub's `hop_limit_reached`
+ * refusal bounds a chain of agents forwarding to each other. Handling nothing starts a new
+ * chain with the hub defaults. When several requests are open the furthest one counts, so a
+ * forwarding loop cannot reset its count because an unrelated request arrived beside it.
+ */
+export function forwardedHops(
+  handling: CommandExecutionContext["handling"],
+): { hops: number; maxHops: number } | undefined {
+  if (!handling?.length) return undefined;
+  return {
+    hops: Math.max(...handling.map((message) => message.hops)) + 1,
+    maxHops: Math.min(...handling.map((message) => message.maxHops)),
+  };
 }
 
 export interface AgentCommand {
@@ -260,12 +280,13 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
       required: ["target", "content"],
       additionalProperties: false,
     },
-    async execute(client, args) {
+    async execute(client, args, context) {
       const delivery = optionalString(args.delivery) as DeliveryMode | undefined;
       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 } : {}),
@@ -346,6 +367,7 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
         : [];
       return {
         responses: await client.fanout({
+          ...forwardedHops(context?.handling),
           targets,
           content: requiredString(args.content, "content"),
           ...(optionalString(args.correlationId) ? { correlationId: optionalString(args.correlationId)! } : {}),

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/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. */

package/plugins/kxm/src/init-guide-setup.ts

@@ -1,7 +1,7 @@
 /**
  * Interactive post-init setup for workflow-guide agents and workflows.
  *
- * Source of truth: `docs/workflow-guide.md`. The catalog below transcribes the
+ * Source of truth: `docs/reference/workflow-catalog.md`. The catalog below transcribes the
  * software-engineering area (workflows, stages, role slugs, and the guide's
  * ordered candidate lists). Guide candidates are dated research; each role's
  * first candidate whose harness is installed AND authenticated wins. No

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

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.95";
+const VERSION = "0.7.97";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
@@ -190,7 +190,14 @@ 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 = asRecord(request.params.arguments);
-    const result = await cmd.execute(client, args, { signal: extra.signal, inbox, notifiedInbox });
+    // Every open inbound request is work this session is handling; a request it sends
+    // meanwhile continues their hop chain.
+    const result = await cmd.execute(client, args, {
+      signal: extra.signal,
+      inbox,
+      notifiedInbox,
+      handling: [...inbox.values()],
+    });
     return textResult(result);
   } catch (error) {
     return {

package/plugins/kxm/src/modes.ts

@@ -99,7 +99,7 @@ export const DEFAULT_MODES_CONFIG: ModesConfig = 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" as const,
       model: "grok/grok-4.6",
     },

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

@@ -51,6 +51,29 @@ export function projectRuntimeKey(projectRoot: string): string {
   return createHash("sha256").update(folded, "utf8").digest("hex").slice(0, 24);
 }
 
+/** 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");
+}
+
+/**
+ * Whether this project's Runtime event store holds `runId`. Hub workflow runs and Runtime
+ * runs share the `run_<32 hex>` shape, so a command addressed by run id asks the owning
+ * store instead of guessing from the id. Read-only; a project whose Runtime never ran
+ * owns no runs.
+ */
+export function projectRuntimeOwnsRun(projectRoot: string, runId: string, env: NodeJS.ProcessEnv): boolean {
+  const path = kxmProjectRunEventsPath(projectRoot, env);
+  if (!existsSync(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) !== undefined;
+  } finally {
+    database.close();
+  }
+}
+
 function checkedParent(path: string, description: string): void {
   const parent = dirname(path);
   if (!existsSync(parent)) mkdirSync(parent, { recursive: true, mode: 0o700 });