@kontextmind/kxm 0.7.97 → 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/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/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.97";
+const VERSION = "0.7.98";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

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/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/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 };
+}