@kontextmind/kxm 0.7.96 → 0.7.98

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

@@ -10,15 +10,21 @@
  * This module writes only current KXM project resources:
  *   - `.kxm/agents/<role-slug>.yaml`   (kxm.agent.v1)
  *   - `.kxm/workflows/<slug>.yaml`     (kxm.workflow.v1)
+ *   - admitted selectors appended to `.kxm/routes.yaml`
  * It never writes retired legacy authority (`.kxm/config`, retired
  * `.kxm/roster.json`) or the trusted `.kxm/roster.yaml` policy
  * and does not use the kxm.role.v1 subsystem.
+ *
+ * Guide research ids are not dispatch ids. Only the admitted map below is
+ * written, and only when that harness is authenticated. Google goes through
+ * the Pi `antigravity` provider. Unmapped ids are skipped.
  */
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { stringify } from "yaml";
-import { NATIVE_HARNESS_PROVIDERS, type HarnessInventory } from "./harness.ts";
+import { type HarnessInventory } from "./harness.ts";
+import { loadRoutePolicy } from "./routes.ts";
 
 export interface GuideCandidate {
   readonly vendor: string;
@@ -41,19 +47,17 @@ export interface GuideWorkflow {
   readonly stages: readonly GuideStage[];
 }
 
-/** Vendor prefix → native harness, using the guide's vendor spellings.
- * Everything else routes via Pi/OpenRouter. Native-vendor candidates never
- * fall back to OpenRouter when their native harness is unavailable: fail
- * closed instead of billing the same vendor through a second provider. */
-const NATIVE_VENDOR_HARNESS: Readonly<Record<string, string>> = Object.freeze({
-  anthropic: "claude",
-  openai: "codex",
-  "x-ai": "grok",
-  xai: "grok",
-  google: "agy",
-  moonshotai: "kimi",
-  moonshot: "kimi",
-  deepseek: "deepseek",
+/** Research id → the admitted harness/provider/model drive will actually accept.
+ * Anything absent is skipped, even when its harness is logged in. */
+const ADMITTED_GUIDE_BINDINGS: Readonly<Record<string, AgentBinding>> = Object.freeze({
+  "anthropic/claude-fable-5.1": { harness: "claude", provider: "anthropic", model: "fable" },
+  "anthropic/fable": { harness: "claude", provider: "anthropic", model: "fable" },
+  "openai/gpt-5.6-sol": { harness: "codex", provider: "openai", model: "gpt-5.6-sol" },
+  "x-ai/grok-4.6": { harness: "grok", provider: "xai", model: "grok-4.6" },
+  "xai/grok-4.6": { harness: "grok", provider: "xai", model: "grok-4.6" },
+  "google/gemini-3.8-flash": { harness: "pi", provider: "antigravity", model: "gemini-3.8-flash-high" },
+  "google/gemini-3.8-flash-high": { harness: "pi", provider: "antigravity", model: "gemini-3.8-flash-high" },
+  "qwen/qwen3-coder-plus": { harness: "pi", provider: "openrouter", model: "qwen/qwen3-coder-plus" },
 });
 
 /** Guide candidates are ordered by preference; the first eligible wins. */
@@ -380,25 +384,17 @@ function authenticatedHarnesses(inventory: HarnessInventory): ReadonlySet<string
 }
 
 /**
- * Resolve a guide candidate to a dispatch binding, or undefined when no
- * candidate's harness is authenticated. Non-native vendors route through the
- * Pi OpenRouter provider (guide ids are already OpenRouter-style slugs).
+ * Resolve a guide candidate to an admitted dispatch binding, or undefined when
+ * no candidate is both on the admitted map and authenticated on its harness.
  */
 export function resolveCandidate(
   candidates: readonly GuideCandidate[],
   eligible: ReadonlySet<string>,
 ): AgentBinding | undefined {
   for (const candidate of candidates) {
-    const nativeHarness = NATIVE_VENDOR_HARNESS[candidate.vendor];
-    if (nativeHarness) {
-      if (eligible.has(nativeHarness)) {
-        return { harness: nativeHarness, provider: NATIVE_HARNESS_PROVIDERS[nativeHarness]!, model: candidate.model };
-      }
-      continue;
-    }
-    if (eligible.has("pi")) {
-      return { harness: "pi", provider: "openrouter", model: `${candidate.vendor}/${candidate.model}` };
-    }
+    const mapped = ADMITTED_GUIDE_BINDINGS[`${candidate.vendor}/${candidate.model}`];
+    if (!mapped || !eligible.has(mapped.harness)) continue;
+    return mapped;
   }
   return undefined;
 }
@@ -424,7 +420,7 @@ export function planGuideSetup(options: {
           workflow: workflow.slug,
           stage: stage.slug,
           role: stage.role,
-          reason: "no guide candidate has an authenticated harness (see `kxm harness list`)",
+          reason: "no admitted guide candidate has an authenticated harness (see `kxm harness list`)",
         });
         covered = false;
         continue;
@@ -465,6 +461,7 @@ function workflowDocument(workflow: GuideWorkflow): Record<string, unknown> {
       id: stage.slug,
       kind: "agent",
       agent: stage.role,
+      repositories: { control: isWriterRole(stage.role) ? "write" : "read" },
       maxAttempts: 2,
       on: {
         passed: last ? { target: "$terminal", terminalStatus: "completed" } : workflow.stages[index + 1]!.slug,
@@ -508,6 +505,24 @@ export function renderGuideSetupFiles(projectRoot: string, plan: GuideSetupPlan)
   return files;
 }
 
+/** Append the plan's admitted selectors to `.kxm/routes.yaml`. Does not write role files. */
+export function mergeGuideRouteAdmission(projectRoot: string, plan: GuideSetupPlan): string[] {
+  const policy = loadRoutePolicy(projectRoot);
+  const added: string[] = [];
+  for (const binding of plan.agents.values()) {
+    const selector = `${binding.provider}/${binding.model}`;
+    if (policy.disabled.includes(selector) || policy.admitted.includes(selector)) continue;
+    policy.admitted.push(selector);
+    added.push(selector);
+  }
+  if (added.length === 0) return added;
+  policy.updatedAt = new Date().toISOString();
+  const path = join(projectRoot, ".kxm", "routes.yaml");
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, stringify(policy), "utf8");
+  return added;
+}
+
 export interface WriteReport {
   readonly written: string[];
   readonly existed: string[];

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.96";
+const VERSION = "0.7.98";
 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/oneshot-producer.ts

@@ -7,7 +7,7 @@ import {
   BUILTIN_HARNESSES,
   NATIVE_HARNESS_PROVIDERS,
   probeHarnessAssignmentAsync,
-  oneShotReadOnlyArgs,
+  oneShotPermissionArgs,
   type HarnessAssignmentProbeOptions,
   type HarnessStatus,
   type HarnessCatalogEntry,
@@ -128,11 +128,11 @@ export function createKxmOneShotProducer(options: KxmOneShotProducerOptions = {}
         };
       }
     }
-    const defaultModel = options.defaultModel ?? (
-      harness === "codex" ? "gpt-5.6-sol" : harness === "kimi" ? "kimi-for-coding" : harness === "agy" ? "gemini-3.8-flash-high" : "claude-3-7-sonnet"
-    );
-    const parsed = parseModelString(defaultModel, harness);
-    return { provider: parsed.provider, model: parsed.model, thinking: request.thinking };
+    if (options.defaultModel) {
+      const parsed = parseModelString(options.defaultModel, harness);
+      return { provider: parsed.provider, model: parsed.model, thinking: request.thinking };
+    }
+    throw new Error("producer_route_not_admitted");
   }
 
   async function checkAuth(harness: string, provider: string, model: string, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<HarnessStatus> {
@@ -167,8 +167,13 @@ export function createKxmOneShotProducer(options: KxmOneShotProducerOptions = {}
       if (request.signal.aborted) return cancelled();
       const catalogEntry = (options.catalog ?? BUILTIN_HARNESSES).find((h) => h.id === harness);
       if (!catalogEntry?.oneShot) throw new Error(`oneshot_harness_unsupported: ${harness}`);
-      const permissionArgs = oneShotReadOnlyArgs(harness);
-      if (!permissionArgs) throw new Error(`oneshot_harness_unsupported: ${harness} permission_profile_unaudited`);
+      const permission = request.permission === "edit" || request.contextPacket?.task.permissionCeiling === "edit"
+        ? "edit"
+        : "read-only";
+      const permissionArgs = oneShotPermissionArgs(harness, permission);
+      if (!permissionArgs) {
+        throw new Error(`oneshot_harness_unsupported: ${harness} ${permission === "edit" ? "writer_profile_unaudited" : "permission_profile_unaudited"}`);
+      }
       // Pin the environment for auth and execution; don't observe subscription
       // auth under one environment and then spawn under changed API-key settings.
       const env = { ...(options.env ?? process.env) };
@@ -287,6 +292,9 @@ export function createKxmOneShotProducer(options: KxmOneShotProducerOptions = {}
       const providerMetadata: Record<string, string | number | boolean> = {
         processStatus: aborted ? "aborted" : transportFailed ? "failed" : "completed",
         executionEvidenceId: evidence.id,
+        permission,
+        permissionProfile: permission === "edit" ? "writer" : "read-only",
+        authored: false,
       };
       if (procResult.code !== null && Number.isFinite(procResult.code)) providerMetadata.processExitCode = procResult.code;
       if (procResult.signal) providerMetadata.processSignal = procResult.signal;

package/plugins/kxm/src/prices.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { parse } from "yaml";
+import { parse, stringify } from "yaml";
 
 export * from "./price-calc.ts";
 import type { PriceCatalog, ModelPriceRow, PriceTier } from "./price-calc.ts";
@@ -167,3 +167,34 @@ export function loadPriceCatalogForEstimate(options?: {
   return { catalog, unavailable: false, stale: false };
 }
 
+/**
+ * Stamp the existing project list-price file as today's estimate.
+ * This does not fetch vendor rates. Until a catalog's date is today,
+ * `loadPriceCatalogForEstimate` keeps the estimate unknown.
+ */
+export function acknowledgePriceCatalog(projectRoot: string, now = new Date()): PriceCatalog {
+  const path = join(projectRoot, ".kxm", "prices.yaml");
+  const loaded = loadPriceCatalog(projectRoot);
+  if (!loaded) throw new Error("price catalog missing");
+  const date = now.toISOString().slice(0, 10);
+  const body = {
+    schema: loaded.schema,
+    date,
+    currency: loaded.currency ?? "USD",
+    models: loaded.models,
+  };
+  const stamped: PriceCatalog = { ...body, sha256: hashPriceCatalog(body) };
+  writeFileSync(path, stringify({
+    schema: stamped.schema,
+    date: stamped.date,
+    sha256: stamped.sha256,
+    currency: stamped.currency ?? "USD",
+    models: stamped.models,
+  }), "utf8");
+  const again = loadPriceCatalog(projectRoot);
+  if (!again || again.date !== date || again.sha256 !== stamped.sha256) {
+    throw new Error("price catalog acknowledge failed verification");
+  }
+  return again;
+}
+

package/plugins/kxm/src/routing.ts

@@ -422,7 +422,8 @@ export interface RoutingComparison {
   blocked: number;
   failed: number;
   reworkRate: number;
-  totalCostUsd: number;
+  totalCostUsd: number | null;
+  missingCostRuns: number;
   totalTokensIn: number;
   totalTokensOut: number;
   totalHumanInterventions: number;
@@ -445,6 +446,8 @@ export function compareRoutingRecords(records: RoutingRecord[]): RoutingComparis
   const blocked = settled.filter((record) => record.finalOutcome === "blocked").length;
   const failed = settled.filter((record) => record.finalOutcome === "failed").length;
   const reworked = records.filter((record) => record.retries > 0 || record.transitions > 0).length;
+  const missingCostRuns = records.filter((record) => typeof record.costUsd !== "number" || !Number.isFinite(record.costUsd)).length;
+  const summedCost = records.reduce((sum, record) => sum + (typeof record.costUsd === "number" && Number.isFinite(record.costUsd) ? record.costUsd : 0), 0);
   return {
     behavioralSha256,
     runs: records.length,
@@ -452,7 +455,8 @@ export function compareRoutingRecords(records: RoutingRecord[]): RoutingComparis
     blocked,
     failed,
     reworkRate: records.length === 0 ? 0 : Math.round((reworked / records.length) * 100) / 100,
-    totalCostUsd: Math.round(records.reduce((sum, record) => sum + (record.costUsd ?? 0), 0) * 10_000) / 10_000,
+    totalCostUsd: missingCostRuns > 0 ? null : Math.round(summedCost * 10_000) / 10_000,
+    missingCostRuns,
     totalTokensIn: records.reduce((sum, record) => sum + (record.tokensIn ?? 0), 0),
     totalTokensOut: records.reduce((sum, record) => sum + (record.tokensOut ?? 0), 0),
     totalHumanInterventions: records.reduce((sum, record) => sum + record.humanInterventions, 0),
@@ -748,9 +752,11 @@ export function generateRoutingReport(
 
     const meteredCostUsd = Math.round(meteredCostTotal * 10_000) / 10_000;
     const costPerAcceptedUsd = acceptedCount > 0
-      ? (meteredCostUsd > 0 || unmeteredAttempts > 0
-          ? Math.round((meteredCostUsd / acceptedCount) * 10_000) / 10_000
-          : (unknownCostAttempts === attempts ? null : 0))
+      ? (unknownCostAttempts > 0
+          ? null
+          : (meteredCostUsd > 0 || unmeteredAttempts > 0
+              ? Math.round((meteredCostUsd / acceptedCount) * 10_000) / 10_000
+              : 0))
       : null;
 
     const flagged = unknownCostAttempts > 0;
@@ -817,8 +823,8 @@ export function generateRoutingReport(
       return a.reworkRate - b.reworkRate;
     }
 
-    // 2. Cost: unknown is never ranked cheapest. Any unknown-cost attempt makes the
-    // route's cost a lower bound (unmetered or metered attempts beside it do not price it).
+    // 2. Cost: unknown is never ranked cheapest. Any unknown-cost attempt leaves the
+    // route's cost unknown (unmetered or metered attempts beside it do not price it).
     const aCostUnknown = a.unknownCostAttempts > 0;
     const bCostUnknown = b.unknownCostAttempts > 0;
     if (aCostUnknown && !bCostUnknown) return 1;

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 });

package/plugins/kxm/src/studio-layout.ts

@@ -420,13 +420,14 @@ export function createStudioServer(options: StudioServerOptions = {}): StudioSer
         return;
       }
 
-      res.writeHead(200, { "Content-Type": "application/json" });
+      res.writeHead(501, { "Content-Type": "application/json" });
       res.end(JSON.stringify({
-        ok: true,
+        ok: false,
+        executed: false,
         mutationId,
         command,
-        mappedToCli: true,
-        executedAt: new Date().toISOString(),
+        mappedToCli: false,
+        error: "mutation_handler_missing",
       }));
       return;
     }

package/plugins/kxm/src/template.ts

@@ -174,6 +174,37 @@ function coreTemplate(projectId: string, projectName: string, variant: KxmTempla
     }],
   ]);
   if (variant === "v4-registry") {
+    const coordinator = files.get(".kxm/agents/coordinator.yaml");
+    if (coordinator) {
+      files.set(".kxm/agents/coordinator.yaml", {
+        ...coordinator,
+        harness: "claude",
+        model: { provider: "anthropic", model: "fable" },
+      });
+    }
+    const implementer = files.get(".kxm/agents/implementer.yaml");
+    if (implementer) {
+      files.set(".kxm/agents/implementer.yaml", {
+        ...implementer,
+        harness: "grok",
+        model: { provider: "xai", model: "grok-4.6" },
+      });
+    }
+    const workflow = files.get(".kxm/workflows/default.yaml");
+    if (workflow) {
+      const limits = { ...(workflow.limits as JsonObject) };
+      delete limits.maxAgentTimeMs;
+      files.set(".kxm/workflows/default.yaml", { ...workflow, limits });
+    }
+    // The two models the template names, and nothing else. A fresh project can
+    // be driven without falling through to an unadmitted default model.
+    files.set(".kxm/routes.yaml", {
+      schema: "kxm.routes.v2",
+      updatedAt: "2026-09-23T00:00:00.000Z",
+      admitted: ["anthropic/fable", "xai/grok-4.6"],
+      disabled: [],
+      roles: { implementer: ["xai/grok-4.6"] },
+    });
     files.set(".kxm/gates.yaml", {
       schema: "kxm.gate-registry.v1",
       gates: { test: { kind: "command", argv: ["npm", "test"], timeoutMs: 3_600_000 } },

package/plugins/kxm/src/workflow.ts

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 import {
   IMPROVEMENT_AREAS,
   MAX_MESSAGE_TTL_MS,
@@ -1386,6 +1386,75 @@ export function workflowDefinitionHash(definition: WebhookWorkflowDefinition): s
   return createHash("sha256").update(canonicalWorkflowDefinitionJson(definition), "utf8").digest("hex");
 }
 
+/** The KXM-owned webhook sender contract: every signal callback, and any
+ * workflow start that is not a Jira or GitHub provider delivery. The HMAC
+ * covers a fixed-arity header block and the exact body bytes, so a captured
+ * request cannot be replayed under another delivery ID, against another run
+ * or signal key, or outside the timestamp window. */
+export const WORKFLOW_WEBHOOK_SIGNATURE_VERSION = "kxm-webhook-v1";
+export const WORKFLOW_WEBHOOK_MAX_SKEW_SECONDS = 300;
+
+/** What a signature is bound to. A start names only the definition; a signal
+ * callback also names the run and signal key from its route. */
+export type WorkflowWebhookScope =
+  | { definitionId: string; runId?: undefined; signalKey?: undefined }
+  | { definitionId: string; runId: string; signalKey: string };
+
+/** The exact bytes a KXM webhook signature covers: seven newline-terminated
+ * fields (version, kind, timestamp, delivery ID, definition ID, run ID, signal
+ * key; the last two empty for a start) followed by the raw body. No field may
+ * contain a line break, so the encoding is unambiguous. */
+export function workflowWebhookSignedMaterial(
+  scope: WorkflowWebhookScope,
+  timestamp: string,
+  deliveryId: string,
+  body: string | Uint8Array,
+): Buffer {
+  const fields = [
+    WORKFLOW_WEBHOOK_SIGNATURE_VERSION,
+    scope.runId === undefined ? "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")}\n`, "utf8"),
+    typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body),
+  ]);
+}
+
+export function workflowWebhookSignature(
+  secret: string,
+  scope: WorkflowWebhookScope,
+  timestamp: string,
+  deliveryId: string,
+  body: string | Uint8Array,
+): string {
+  return `sha256=${createHmac("sha256", secret).update(workflowWebhookSignedMaterial(scope, timestamp, deliveryId, body)).digest("hex")}`;
+}
+
+/** Headers for one KXM webhook send. Sign at send time: a transport retry
+ * re-signs with a fresh timestamp and keeps the same delivery ID and body. */
+export function workflowWebhookHeaders(input: {
+  secret: string;
+  scope: WorkflowWebhookScope;
+  deliveryId: string;
+  body: string;
+  nowMs?: number;
+}): Record<string, string> {
+  const timestamp = String(Math.floor((input.nowMs ?? Date.now()) / 1_000));
+  return {
+    "x-kxm-delivery-id": input.deliveryId,
+    "x-kxm-timestamp": timestamp,
+    "x-kxm-signature": workflowWebhookSignature(input.secret, input.scope, timestamp, input.deliveryId, input.body),
+  };
+}
+
 /** Resolve a declared transition rule for a stage outcome, or undefined when
  * the outcome keeps the v0.4 default edges. */
 function resolveOutcomeRule(stage: WorkflowStageState, outcomeKey: string): WorkflowTransitionRule | undefined {

package/plugins/kxm/src/worktree-witness.ts

@@ -0,0 +1,71 @@
+import { spawnSync } from "node:child_process";
+import type { KxmProducerResult } from "./engine.ts";
+
+/**
+ * Fingerprint of a checkout taken around a live producer spawn.
+ * Porcelain alone misses a content edit that keeps the same status line, so the
+ * witness also includes unstaged and staged diffs.
+ */
+export interface WorktreeWitness {
+  readonly unwitnessed: boolean;
+  readonly fingerprint: string;
+}
+
+function gitText(cwd: string, args: readonly string[]): string | undefined {
+  const result = spawnSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: 15_000,
+  });
+  if (result.error || result.status !== 0) return undefined;
+  return result.stdout ?? "";
+}
+
+export function captureWorktreeWitness(cwd: string): WorktreeWitness {
+  const porcelain = gitText(cwd, ["status", "--porcelain=v1", "-uall"]);
+  const diff = gitText(cwd, ["diff", "--no-ext-diff"]);
+  const staged = gitText(cwd, ["diff", "--cached", "--no-ext-diff"]);
+  if (porcelain === undefined || diff === undefined || staged === undefined) {
+    return { unwitnessed: true, fingerprint: "" };
+  }
+  return { unwitnessed: false, fingerprint: `${porcelain}\0${diff}\0${staged}` };
+}
+
+export function worktreeChanged(before: WorktreeWitness, after: WorktreeWitness): boolean {
+  if (before.unwitnessed || after.unwitnessed) return false;
+  return before.fingerprint !== after.fingerprint;
+}
+
+/**
+ * A live `passed` is an authoring success only when the step declared write
+ * and the checkout fingerprint changed. A read-only step that mutates the tree
+ * cannot stay `passed`. Metadata `authored` is set here, not trusted from the
+ * producer.
+ */
+export function applyAuthoringWitness(
+  result: KxmProducerResult,
+  input: { writes: boolean; before: WorktreeWitness; after: WorktreeWitness },
+): KxmProducerResult {
+  const changed = worktreeChanged(input.before, input.after);
+  const unwitnessed = input.before.unwitnessed || input.after.unwitnessed;
+  const providerMetadata: Record<string, string | number | boolean> = { ...(result.providerMetadata ?? {}) };
+  if (input.writes) {
+    if (unwitnessed || !changed) {
+      providerMetadata.authored = false;
+      providerMetadata.authoringWitness = unwitnessed ? "unwitnessed" : "unchanged";
+      if (result.outcome === "passed") return { ...result, outcome: "failed", providerMetadata };
+    } else {
+      providerMetadata.authored = true;
+      providerMetadata.authoringWitness = "changed";
+    }
+  } else {
+    providerMetadata.authored = false;
+    if (!unwitnessed && changed) {
+      providerMetadata.authoringWitness = "readonly_mutated";
+      if (result.outcome === "passed") return { ...result, outcome: "failed", providerMetadata };
+    } else {
+      providerMetadata.authoringWitness = unwitnessed ? "unwitnessed" : "read-only";
+    }
+  }
+  return { ...result, providerMetadata };
+}

package/schemas/backup-manifest.schema.json

@@ -31,6 +31,17 @@
       "minItems": 1,
       "maxItems": 64
     },
+    "files": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/backupFileRecord" },
+      "maxItems": 64
+    },
+    "complete": { "type": "boolean" },
+    "omitted": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 256 },
+      "maxItems": 64
+    },
     "manifestSha256": {
       "$ref": "common.schema.json#/$defs/sha256"
     }
@@ -84,6 +95,28 @@
         }
       },
       "additionalProperties": false
+    },
+    "backupFileRecord": {
+      "type": "object",
+      "required": ["id", "sourcePath", "backupFile", "sha256", "bytes"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-zA-Z0-9_.:-]+$"
+        },
+        "sourcePath": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "backupFile": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^[a-zA-Z0-9_.-]+$"
+        },
+        "sha256": { "$ref": "common.schema.json#/$defs/sha256" },
+        "bytes": { "type": "integer", "minimum": 0, "maximum": 107374182400 }
+      },
+      "additionalProperties": false
     }
   }
 }

package/scripts/smoke-multi-pi.mjs

@@ -423,10 +423,14 @@ export async function runRealSmoke(options = {}) {
         stage = "workflow-journal-checkpoint";
         const resumedOperator = values["durable-restart-resume"];
         const payload = JSON.stringify({ event: "smoke.requested" });
+        // KXM webhook contract (workflowWebhookSignedMaterial in plugins/kxm/src/workflow.ts).
+        const deliveryId = `smoke-${randomUUID()}`;
+        const timestamp = String(Math.floor(Date.now() / 1_000));
+        const signedMaterial = ["kxm-webhook-v1", "start", timestamp, deliveryId, "real-pi-smoke", "", ""].join("\n") + "\n" + payload;
         const started = await api(baseUrl, "/v1/webhooks/real-pi-smoke", {
           method: "POST",
           authToken,
-          headers: { "x-mesh-event": "smoke.requested", "x-kxm-delivery-id": `smoke-${randomUUID()}`, "x-hub-signature": `sha256=${createHmac("sha256", webhookSecret).update(payload).digest("hex")}` },
+          headers: { "x-kxm-delivery-id": deliveryId, "x-kxm-timestamp": timestamp, "x-kxm-signature": `sha256=${createHmac("sha256", webhookSecret).update(signedMaterial).digest("hex")}` },
           body: payload,
         });
         await api(baseUrl, `/v1/workflows/${encodeURIComponent(started.run.id)}/journal`, {