@kontextmind/kxm 0.7.130 → 0.7.131

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

@@ -12,9 +12,10 @@
  *   - `.kxm/workflows/<slug>.yaml`     (kxm.workflow.v1)
  *   - `.kxm/roles/<role-slug>.yaml`    (kxm.role.v2)
  *   - `.kxm/models/<route-id>.yaml`    (kxm.model.v2)
+ *   - `plans/evidence/route-guide-qwen-pi.md` when a Pi binding matches that note
  *   - 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.
+ * It never writes retired legacy authority (`.kxm/config` or
+ * `.kxm/roster.json`). Role and model files are the dispatch authority.
  *
  * Guide research ids are not dispatch ids. Only the admitted map below is
  * written, and only when that harness is authenticated. Unmapped ids are skipped.
@@ -28,8 +29,7 @@
  * admission decision says so.
  */
 
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { stringify } from "yaml";
 import { type HarnessInventory } from "./harness.ts";
@@ -446,13 +446,12 @@ function isWriterRole(roleSlug: string): boolean {
   return WRITER_ROLE_PATTERN.test(roleSlug);
 }
 
-function agentDocument(roleSlug: string, stage: GuideStage, binding: AgentBinding): Record<string, unknown> {
+function agentDocument(roleSlug: string, stage: GuideStage): Record<string, unknown> {
   const writer = isWriterRole(roleSlug);
   return {
     schema: "kxm.agent.v1",
     purpose: `${stage.domain} (workflow-guide ${stage.title}; candidate verification is the operator's responsibility)`,
-    harness: binding.harness,
-    model: { provider: binding.provider, model: binding.model },
+    role: roleSlug,
     tools: { preset: writer ? "workspace-writer" : "read-only" },
     defaultRepositoryAccess: writer ? "none" : "read",
     repositories: { control: writer ? "write" : "read" },
@@ -485,26 +484,78 @@ function workflowDocument(workflow: GuideWorkflow): Record<string, unknown> {
   };
 }
 
+/**
+ * Evidence written into the user's project for the one admitted guided Pi model.
+ * The hash is of these exact bytes. A Pi binding that is not this vendor, model
+ * id, and harness gets no model file and no origin.
+ */
+const GUIDE_PI_EVIDENCE_SOURCE = "plans/evidence/route-guide-qwen-pi.md";
+const GUIDE_PI_EVIDENCE_SHA256 = "109f39728b251dd0565e275ae689a6e1d9b889a488d996b157d500c538115759";
+const GUIDE_PI_NOTE = {
+  harness: "pi",
+  vendor: "openrouter",
+  model: "qwen/qwen3-coder-plus",
+  reason: "Qwen has no supported native harness on this runner, and the operator admitted that exact model for guided setup.",
+  provingCommand: "pi auth check --provider openrouter",
+} as const;
+
+const GUIDE_PI_EVIDENCE_NOTE = `---
+schema: "kxm.doc.v1"
+id: "RES-GUIDE-QWEN-PI"
+type: "research"
+title: "Research: guided setup Pi Qwen origin"
+project: "kxm"
+status: "approved"
+owner: "@operator"
+created: "2026-09-26"
+updated: "2026-09-26"
+authority: "evidence"
+confidence: "verified"
+summary: "Guided setup pins every Pi model origin to this note so a later project.yaml edit cannot change the hash."
+tags: ["routing", "qwen", "pi", "init-guide"]
+related: []
+details:
+  research_status: "complete"
+  target_decision_date: "2026-09-26"
+---
+
+# route-guide-qwen-pi
+
+Dated 2026-09-26. Route ids are the guided role slugs. Harness \`${GUIDE_PI_NOTE.harness}\`. Model id \`${GUIDE_PI_NOTE.model}\`. Vendor \`${GUIDE_PI_NOTE.vendor}\`. Admitted because ${GUIDE_PI_NOTE.reason} Auth was proved with \`${GUIDE_PI_NOTE.provingCommand}\`.
+`;
+
+function guidePiNoteMatches(binding: AgentBinding): boolean {
+  return binding.harness === GUIDE_PI_NOTE.harness
+    && binding.provider === GUIDE_PI_NOTE.vendor
+    && binding.model === GUIDE_PI_NOTE.model;
+}
+
 /**
  * Render the planned KXM resource files (`.kxm/agents/*.yaml`,
- * `.kxm/workflows/*.yaml`). A Pi model origin hashes `.kxm/project.yaml`
- * when that file exists, and is omitted when it does not.
+ * `.kxm/workflows/*.yaml`, and the Pi evidence note when a binding matches it).
+ * The Pi origin is the hash of `plans/evidence/route-guide-qwen-pi.md` written
+ * into the project, whether or not `.kxm/project.yaml` exists.
  */
 export function renderGuideSetupFiles(projectRoot: string, plan: GuideSetupPlan): GuideSetupFile[] {
-  const projectYaml = join(projectRoot, ".kxm", "project.yaml");
-  const projectOrigin = existsSync(projectYaml)
-    ? { source: ".kxm/project.yaml", sha256: createHash("sha256").update(readFileSync(projectYaml)).digest("hex") }
-    : undefined;
   const files: GuideSetupFile[] = [];
   const roleStages = new Map<string, GuideStage>();
   for (const workflow of plan.workflows) {
     for (const stage of workflow.stages) roleStages.set(stage.role, stage);
   }
+  let evidenceQueued = false;
   for (const [role, binding] of [...plan.agents.entries()].sort(([a], [b]) => a.localeCompare(b))) {
     const stage = roleStages.get(role);
     if (!stage) continue;
     const routeId = role.replaceAll("_", "-");
     const writer = isWriterRole(role);
+    const piMatch = binding.harness === "pi" && guidePiNoteMatches(binding);
+    if (binding.harness === "pi" && !piMatch) {
+      files.push({
+        path: join(projectRoot, ".kxm", "agents", `${role}.yaml`),
+        content: stringify(agentDocument(role, stage)),
+      });
+      continue;
+    }
     const modelDocument: Record<string, unknown> = {
       schema: "kxm.model.v2",
       id: routeId,
@@ -514,10 +565,19 @@ export function renderGuideSetupFiles(projectRoot: string, plan: GuideSetupPlan)
       status: "admitted",
       permissions: [writer ? "edit" : "read-only"],
     };
-    if (binding.harness === "pi" && projectOrigin) modelDocument.origin = projectOrigin;
+    if (piMatch) {
+      modelDocument.origin = { source: GUIDE_PI_EVIDENCE_SOURCE, sha256: GUIDE_PI_EVIDENCE_SHA256 };
+      if (!evidenceQueued) {
+        files.push({
+          path: join(projectRoot, GUIDE_PI_EVIDENCE_SOURCE),
+          content: GUIDE_PI_EVIDENCE_NOTE,
+        });
+        evidenceQueued = true;
+      }
+    }
     files.push({
       path: join(projectRoot, ".kxm", "agents", `${role}.yaml`),
-      content: stringify(agentDocument(role, stage, binding)),
+      content: stringify(agentDocument(role, stage)),
     });
     files.push({
       path: join(projectRoot, ".kxm", "models", `${routeId}.yaml`),

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.130";
+const VERSION = "0.7.131";
 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

@@ -29,7 +29,6 @@ import {
 export interface KxmOneShotProducerOptions {
   projectRoot?: string | undefined;
   evidenceRoot?: string | undefined;
-  defaultHarness?: string | undefined;
   defaultModel?: string | undefined;
   defaultProvider?: string | undefined;
   inventory?: HarnessInventory | undefined;
@@ -39,9 +38,7 @@ export interface KxmOneShotProducerOptions {
   timeoutMs?: number | undefined;
   spawnProcess?: KxmOneShotSpawn | undefined;
   probeHarness?: ((options: Omit<HarnessAssignmentProbeOptions, "runCommand"> & { signal?: AbortSignal | undefined }) => HarnessStatus | Promise<HarnessStatus>) | undefined;
-  resolveHarness?: ((agentId: string, runId: string) => string | undefined) | undefined;
   resolveModel?: ((agentId: string, runId: string) => {
-    harness?: string | undefined;
     provider?: string | undefined;
     model?: string | undefined;
     thinking?: string | undefined;
@@ -66,21 +63,12 @@ function determineOutcome(text: string, allowedOutcomes: readonly string[]): str
 }
 
 export function createKxmOneShotProducer(options: KxmOneShotProducerOptions = {}): KxmOneShotProducer {
-  const defaultHarness = options.defaultHarness ?? "claude";
   const running = new Map<AbortController, Promise<KxmProducerResult>>();
   let closed = false;
 
-  function resolveHarnessForRequest(request: KxmProducerRequest): string {
+  function requireHarness(request: KxmProducerRequest): string {
     if (request.harness) return request.harness;
-    if (options.resolveHarness) {
-      const resolved = options.resolveHarness(request.agentId, request.runId);
-      if (resolved) return resolved;
-    }
-    if (options.resolveModel) {
-      const resolved = options.resolveModel(request.agentId, request.runId);
-      if (resolved?.harness) return resolved.harness;
-    }
-    return defaultHarness;
+    throw new Error("producer_harness_required");
   }
 
   function parseModelString(spec: string, harness: string): { provider: string; model: string } {
@@ -155,7 +143,7 @@ export function createKxmOneShotProducer(options: KxmOneShotProducerOptions = {}
 
   async function executeRequest(request: KxmProducerRequest): Promise<KxmProducerResult> {
       const startTime = Date.now();
-      const harness = resolveHarnessForRequest(request);
+      const harness = requireHarness(request);
       const resolved = resolveModelForRequest(request, harness);
 
       if (closed) throw new Error("oneshot_producer_closed");

package/plugins/kxm/src/project-config.ts

@@ -13,7 +13,7 @@ import { pathToFileURL } from "node:url";
 import { validatePolicyDraft } from "./policy-draft.mjs";
 import { resolveKxmTemplateBaseline } from "./template.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
-import { BUILTIN_HARNESS_IDS, DEFAULT_HARNESS, validateHarnessModelPair } from "./harness.ts";
+import { BUILTIN_HARNESS_IDS, DEFAULT_HARNESS } from "./harness.ts";
 
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 export type JsonObject = { [key: string]: JsonValue };
@@ -522,6 +522,7 @@ function listNamedResources(
   logicalDirectory: string,
   kind: "agent" | "model" | "role" | "workflow",
   replacedId?: string,
+  collected?: KxmConfigIssue[],
 ): Map<string, KxmResource> {
   const resources = new Map<string, KxmResource>();
   if (!existsSync(directory)) return resources;
@@ -561,7 +562,10 @@ function listNamedResources(
       else throw error;
     }
   }
-  if (issues.length > 0) throw new KxmConfigError(issues);
+  if (issues.length > 0) {
+    if (collected) collected.push(...issues);
+    else throw new KxmConfigError(issues);
+  }
   return resources;
 }
 
@@ -925,6 +929,9 @@ function validateWorkflow(
     for (const repositoryId of Object.keys(objectValue(step.repositories) ?? {})) {
       if (!repositories.has(repositoryId)) issues.push(issue("reference", "repository_unknown", file, `${stepId} references unknown repository ${repositoryId}`));
     }
+    if ((kind === "agent" || kind === "moa") && step.model !== undefined) {
+      issues.push(issue("semantic", "producer_route_unsupported", file, `${stepId} model is not honored; remove model from the step`));
+    }
     selectorCandidates(step.model, models, file, `${stepId}.model`, issues);
 
     const assignment = objectValue(step.assignments);
@@ -1128,7 +1135,7 @@ function validateBundle(
   options: KxmConfigOptions,
   gateRegistry?: KxmResource,
   projectRoot?: string,
-  writerRole?: string,
+  roles: ReadonlyMap<string, KxmResource> = new Map(),
 ): KxmConfigIssue[] {
   const issues: KxmConfigIssue[] = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate): candidate is JsonObject => Boolean(candidate));
@@ -1173,28 +1180,17 @@ function validateBundle(
   if (!harnesses.has(defaultHarness)) issues.push(issue("reference", "harness_unknown", project.logicalPath, `defaultHarness ${defaultHarness} is not registered`));
 
   for (const agent of agents.values()) {
+    if (agent.value.model !== undefined || agent.value.harness !== undefined) {
+      issues.push(issue("semantic", "retired_agent_routing_fields", agent.logicalPath, "routing resolves from role; remove model and harness"));
+    }
     validateToolPolicy(agent, objectValue(agent.value.tools), "tools", issues);
     const executor = stringValue(agent.value.executor);
     if (executor && !executors.has(executor)) issues.push(issue("reference", "executor_unknown", agent.logicalPath, `executor ${executor} is not registered`));
-    const harness = stringValue(agent.value.harness) ?? defaultHarness;
-    if (!harnesses.has(harness)) issues.push(issue("reference", "harness_unknown", agent.logicalPath, `harness ${harness} is not registered`));
     const preset = stringValue(objectValue(agent.value.tools)?.preset);
     if (preset && !presets.has(preset)) issues.push(issue("reference", "tool_preset_unknown", agent.logicalPath, `tool preset ${preset} is not registered`));
     for (const repositoryId of Object.keys(objectValue(agent.value.repositories) ?? {})) {
       if (!repositoryIds.has(repositoryId)) issues.push(issue("reference", "repository_unknown", agent.logicalPath, `references unknown repository ${repositoryId}`));
     }
-    const candidates = selectorCandidates(agent.value.model, models, agent.logicalPath, "model", issues);
-    const declaredHarness = stringValue(agent.value.harness);
-    if (declaredHarness && harnesses.has(declaredHarness)) {
-      for (const candidate of candidates) {
-        const candidateProvider = stringValue(candidate.value.provider);
-        const candidateModel = stringValue(candidate.value.model);
-        const validation = validateHarnessModelPair(declaredHarness, { provider: candidateProvider, model: candidateModel });
-        if (!validation.valid) {
-          issues.push(issue("semantic", validation.issue ?? "harness_unhosted_model", agent.logicalPath, validation.message ?? `harness ${declaredHarness} cannot host model ${candidateModel ?? candidate.logicalPath}`));
-        }
-      }
-    }
   }
   validateModelReferences(models, issues);
 
@@ -1202,62 +1198,73 @@ function validateBundle(
   if (!workflows.has(defaultWorkflow)) issues.push(issue("reference", "default_workflow_unknown", project.logicalPath, `default workflow ${defaultWorkflow} does not exist`));
   for (const workflow of workflows.values()) validateWorkflow(workflow, agents, models, repositoryIds, gates, issues);
 
+  // Developer policy is the role files under .kxm/roles/ (with the model
+  // files they name). scripts/harness-run.mjs only supplies ceilings.
+  if (projectRoot && existsSync(join(projectRoot, ".kxm", "roster.yaml"))) {
+    issues.push(issue("semantic", "retired_roster_file", ".kxm/roster.yaml", "create the role and model files and delete roster.yaml"));
+  }
+  if (projectRoot && existsSync(join(projectRoot, ".kxm", "roles"))) {
+    issues.push(...developerRolePolicyIssues(projectRoot));
+  }
   if (projectRoot) {
-    const writerRolePath = join(projectRoot, ".kxm", "roles", "writer.yaml");
-    const implementerAgent = agents.get("implementer") ?? agents.get("writer");
-    if ((writerRole !== undefined || existsSync(writerRolePath)) && implementerAgent) {
+    issues.push(...rosterModelIssues(projectRoot, roles));
+    issues.push(...originHashIssues(projectRoot, models));
+  }
+
+  return sortIssues(issues);
+}
+
+function rosterModelIssues(projectRoot: string, roles: ReadonlyMap<string, KxmResource>): KxmConfigIssue[] {
+  const issues: KxmConfigIssue[] = [];
+  for (const role of roles.values()) {
+    for (const entry of valuesOf(role.value, "roster")) {
+      const route = stringValue(objectValue(entry)?.route);
+      if (!route) continue;
+      const logical = `.kxm/models/${route}.yaml`;
+      const file = join(projectRoot, ".kxm", "models", `${route}.yaml`);
+      let harness: string | undefined;
       try {
-        const rawRole = parseRestrictedYaml(writerRole ?? readFileSync(writerRolePath, "utf8"));
-        const roleObj = objectValue(rawRole);
-        const rosterEntries = valuesOf(roleObj ?? {}, "roster")
-          .map((candidate) => objectValue(candidate))
-          .filter((entry): entry is JsonObject => Boolean(entry));
-        const enabledRosterModels = rosterEntries.flatMap((entry) => {
-          const direct = stringValue(entry.model);
-          const route = stringValue(entry.route);
-          const named: string[] = direct ? [direct] : [];
-          if (route) {
-            const modelFile = join(projectRoot, ".kxm", "models", `${route}.yaml`);
-            if (existsSync(modelFile)) {
-              try {
-                const modelDoc = objectValue(parseRestrictedYaml(readFileSync(modelFile, "utf8"), modelFile));
-                const model = modelDoc ? stringValue(modelDoc.model) : undefined;
-                const vendor = modelDoc ? stringValue(modelDoc.vendor) : undefined;
-                const harness = modelDoc ? stringValue(modelDoc.harness) : undefined;
-                if (model) named.push(model);
-                if (vendor && model) named.push(`${vendor}/${model}`);
-                if (harness && model) named.push(`${harness}/${model}`);
-              } catch { /* schema issues are reported by resource validation */ }
-            }
-          }
-          return named;
-        });
-
-        const agentModelObj = objectValue(implementerAgent.value.model);
-        const agentModelStr = stringValue(implementerAgent.value.model);
-        const agentProvider = agentModelObj ? stringValue(agentModelObj.provider) : undefined;
-        const agentModel = agentModelObj ? stringValue(agentModelObj.model) : agentModelStr;
-        const canonicalAgentModel = agentProvider && agentModel ? `${agentProvider}/${agentModel}` : agentModel;
-
-        if (enabledRosterModels.length > 0 && canonicalAgentModel) {
-          const matches = enabledRosterModels.some((rm) => rm === canonicalAgentModel || rm === agentModel || rm.endsWith(`/${agentModel}`));
-          if (!matches) {
-            issues.push(issue("semantic", "role_roster_conflicts_with_agent", ".kxm/roles/writer.yaml", `role roster in .kxm/roles/writer.yaml does not include agent model ${canonicalAgentModel} from ${implementerAgent.logicalPath}`));
-          }
-        }
-      } catch (error) {
-        if (error instanceof KxmConfigError) {
-          issues.push(...error.issues);
-        }
+        if (existsSync(file)) harness = stringValue(parseRestrictedYaml(readFileSync(file, "utf8"), logical).harness);
+      } catch {
+        harness = undefined;
+      }
+      if (!harness) {
+        issues.push(issue("semantic", "roster_model_unreadable", role.logicalPath, `roster route ${route} does not resolve to a readable ${logical} carrying harness`));
       }
     }
   }
+  return issues;
+}
 
-  if (projectRoot && existsSync(join(projectRoot, ".kxm", "roster.yaml"))) {
-    issues.push(...developerRolePolicyIssues(projectRoot));
+function originHashIssues(projectRoot: string, models: ReadonlyMap<string, KxmResource>): KxmConfigIssue[] {
+  const issues: KxmConfigIssue[] = [];
+  for (const model of models.values()) {
+    const origin = objectValue(model.value.origin);
+    const source = origin ? stringValue(origin.source) : undefined;
+    const digest = origin ? stringValue(origin.sha256) : undefined;
+    if (!source || !digest) continue;
+    const file = resolve(projectRoot, source);
+    const escaped = relative(projectRoot, file);
+    if (isAbsolute(source) || escaped.startsWith("..") || isAbsolute(escaped)) {
+      issues.push(issue("semantic", "origin_evidence_missing", model.logicalPath, `missing evidence bytes for ${source}`));
+      continue;
+    }
+    let actual: string;
+    try {
+      actual = createHash("sha256").update(readFileSync(file, "utf8"), "utf8").digest("hex");
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === "EACCES" || code === "EPERM" || code === "EISDIR") {
+        issues.push(issue("semantic", "origin_evidence_missing", model.logicalPath, `missing evidence bytes for ${source}`));
+        continue;
+      }
+      throw error;
+    }
+    if (actual !== digest) {
+      issues.push(issue("semantic", "origin_hash_mismatch", model.logicalPath, "origin evidence hash does not match supplied bytes"));
+    }
   }
-
-  return sortIssues(issues);
+  return issues;
 }
 
 function developerCeilings(): {
@@ -1294,6 +1301,10 @@ function developerCeilings(): {
 }
 
 function developerRolePolicyIssues(projectRoot: string): KxmConfigIssue[] {
+  // Product checkouts also have .kxm/roles/ for dispatch. The ceiling check
+  // is this package's developer policy, so it runs when the loaded project
+  // is that package.
+  if (resolve(projectRoot) !== findKxmRepoRoot(import.meta.url)) return [];
   const rolesDir = join(projectRoot, ".kxm", "roles");
   const modelsDir = join(projectRoot, ".kxm", "models");
   const roles: Record<string, JsonObject> = {};
@@ -1314,6 +1325,7 @@ function developerRolePolicyIssues(projectRoot: string): KxmConfigIssue[] {
           parseIssues.push(...error.issues);
           continue;
         }
+        throw error;
       }
     }
   };
@@ -1328,7 +1340,7 @@ function developerRolePolicyIssues(projectRoot: string): KxmConfigIssue[] {
   }
   const ceilings = developerCeilings();
   if (!ceilings.ok) {
-    return [...parseIssues, issue("semantic", "developer_ceilings_unavailable", ".kxm/roster.yaml", `developer ceilings could not be loaded: ${ceilings.detail}`)];
+    return [...parseIssues, issue("semantic", "developer_ceilings_unavailable", ".kxm/models", `developer ceilings could not be loaded: ${ceilings.detail}`)];
   }
   const result = validatePolicyDraft({ models, roles, evidence }, {
     ceilings: ceilings.ROUTES,
@@ -1489,7 +1501,8 @@ function loadProjectBundle(
   if (earlyIssues.length > 0) throw new KxmConfigError(earlyIssues);
 
   const agents = listNamedResources(registry, root, join(root, ".kxm", "agents"), ".kxm/agents", "agent");
-  const models = listNamedResources(registry, root, join(root, ".kxm", "models"), ".kxm/models", "model");
+  const modelIssues: KxmConfigIssue[] = [];
+  const models = listNamedResources(registry, root, join(root, ".kxm", "models"), ".kxm/models", "model", undefined, modelIssues);
   const roles = listNamedResources(registry, root, join(root, ".kxm", "roles"), ".kxm/roles", "role", writerRole === undefined ? undefined : "writer");
   if (writerRole !== undefined) {
     const logicalPath = ".kxm/roles/writer.yaml";
@@ -1620,9 +1633,9 @@ function loadProjectBundle(
       }
     }
   }
-  if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
+  if (loadIssues.length > 0) throw new KxmConfigError([...loadIssues, ...modelIssues]);
 
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
+  const issues = [...modelIssues, ...validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, roles)];
   if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...roles.values(), ...workflows.values(), ...environments, ...(gateRegistry ? [gateRegistry] : [])]
     .sort((left, right) => compareCodeUnits(left.logicalPath, right.logicalPath));

package/plugins/kxm/src/routes.ts

@@ -5,15 +5,15 @@ import { rolePurposeForId } from "./role.ts";
 
 const RETIRED_POLICY = ".kxm/producers.yaml";
 
-export interface RoutePolicy { schema: "kxm.routes.v2"; updatedAt: string; admitted: string[]; disabled: string[]; roles: Record<string, string[]>; }
-const empty = (): RoutePolicy => ({ schema: "kxm.routes.v2", updatedAt: new Date().toISOString(), admitted: [], disabled: [], roles: {} });
+export interface RoutePolicy { schema: "kxm.routes.v2"; updatedAt: string; admitted: string[]; disabled: string[]; }
+const empty = (): RoutePolicy => ({ schema: "kxm.routes.v2", updatedAt: new Date().toISOString(), admitted: [], disabled: [] });
 export function loadRoutePolicy(root: string): RoutePolicy {
   if (existsSync(join(root, RETIRED_POLICY))) throw new Error(`retired ${RETIRED_POLICY} present; use .kxm/routes.yaml (kxm.routes.v2)`);
   const path = join(root, ".kxm", "routes.yaml");
   if (!existsSync(path)) return empty();
   const value = parse(readFileSync(path, "utf8")) as Partial<RoutePolicy>;
   if (value?.schema !== "kxm.routes.v2" || !Array.isArray(value.admitted)) throw new Error("invalid .kxm/routes.yaml");
-  return { schema: "kxm.routes.v2", updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date().toISOString(), admitted: value.admitted.filter((x): x is string => typeof x === "string"), disabled: Array.isArray(value.disabled) ? value.disabled.filter((x): x is string => typeof x === "string") : [], roles: value.roles && typeof value.roles === "object" ? Object.fromEntries(Object.entries(value.roles).filter(([, v]) => Array.isArray(v)).map(([k, v]) => [k, (v as unknown[]).filter((x): x is string => typeof x === "string")])) : {} };
+  return { schema: "kxm.routes.v2", updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date().toISOString(), admitted: value.admitted.filter((x): x is string => typeof x === "string"), disabled: Array.isArray(value.disabled) ? value.disabled.filter((x): x is string => typeof x === "string") : [] };
 }
 export function updateRouteState(root: string, model: string, state: "admitted" | "disabled"): RoutePolicy {
   return setRouteState(root, model, state);
@@ -33,21 +33,7 @@ export function setRouteState(root: string, model: string, state: "admitted" | "
       if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) roleFile = parsed as Record<string, unknown>;
     }
     const roster = Array.isArray(roleFile.roster) ? roleFile.roster.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)) : [];
-    const modelsDir = join(root, ".kxm", "models");
-    let routeId: string | undefined;
-    if (existsSync(modelsDir)) {
-      for (const name of readdirSync(modelsDir)) {
-        if (!name.endsWith(".yaml") || name === "inventory.yaml") continue;
-        const parsedModel = parse(readFileSync(join(modelsDir, name), "utf8")) as { vendor?: unknown; model?: unknown; schema?: unknown };
-        if (parsedModel?.schema !== "kxm.model.v2") continue;
-        const vendor = typeof parsedModel.vendor === "string" ? parsedModel.vendor : "";
-        const named = typeof parsedModel.model === "string" ? parsedModel.model : "";
-        if (named === model || (vendor && `${vendor}/${named}` === model)) {
-          routeId = name.slice(0, -5);
-          break;
-        }
-      }
-    }
+    const routeId = routeIdForInventoryModel(root, model);
     if (!routeId) throw new Error(`unknown route: no v2 model file matches '${model}'`);
     const existing = roster.findIndex((entry) => entry.route === routeId || entry.model === model);
     if (removeRole) { if (existing >= 0) roster.splice(existing, 1); }
@@ -68,6 +54,28 @@ export function setRouteState(root: string, model: string, state: "admitted" | "
   return policy;
 }
 
+/** Route-file id whose vendor/model matches an inventory selector, if one exists. */
+export function routeIdForInventoryModel(root: string, model: string): string | undefined {
+  const modelsDir = join(root, ".kxm", "models");
+  if (!existsSync(modelsDir)) return undefined;
+  for (const name of readdirSync(modelsDir)) {
+    if (!name.endsWith(".yaml") || name === "inventory.yaml") continue;
+    const parsedModel = parse(readFileSync(join(modelsDir, name), "utf8")) as { vendor?: unknown; model?: unknown; schema?: unknown };
+    if (parsedModel?.schema !== "kxm.model.v2") continue;
+    const vendor = typeof parsedModel.vendor === "string" ? parsedModel.vendor : "";
+    const named = typeof parsedModel.model === "string" ? parsedModel.model : "";
+    if (named === model || (vendor && `${vendor}/${named}` === model)) return name.slice(0, -5);
+  }
+  return undefined;
+}
+
+/** Role ids whose roster names the model file that matches this inventory selector. */
+export function rolesForInventoryModel(root: string, inventoryId: string): string[] {
+  const routeId = routeIdForInventoryModel(root, inventoryId);
+  if (!routeId) return [];
+  return Object.entries(listRoleBindings(root)).filter(([, ids]) => ids.includes(routeId)).map(([role]) => role);
+}
+
 export function listRoleBindings(root: string): Record<string, string[]> {
   const dir = join(root, ".kxm", "roles"); const result: Record<string, string[]> = {};
   if (!existsSync(dir)) return result;

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

@@ -28,7 +28,6 @@ import {
   type KxmRuntimeContext,
 } from "./runtime-service.ts";
 import { createKxmOneShotProducer } from "./oneshot-producer.ts";
-import { isRouteAdmitted } from "./routes.ts";
 import { KxmRunScheduler, createKxmSimulatedProducer, recordDriveReceipt, recoverKxmRun, kxmDrivePollProjection } from "./engine.ts";
 import { kxmDriveSession, kxmOpenDriveSessions } from "./runtime-owner.ts";
 import { RuntimeHubClient, HubHttpError, type SyncPushResponse } from "./client.ts";
@@ -919,23 +918,6 @@ async function startKxmRuntimeSupervisorInner(
               ? createKxmOneShotProducer({
                   projectRoot,
                   timeoutMs: kxmProjectAdmissionLimits(bundle).agentStepTimeoutMs,
-                  defaultHarness: String(bundle.project.value.defaultHarness ?? "pi"),
-                  resolveHarness: (agentId) => {
-                    const agent = bundle.agents.get(agentId);
-                    return typeof agent?.value.harness === "string" ? agent.value.harness : undefined;
-                  },
-                  resolveModel: (agentId) => {
-                    const agent = bundle.agents.get(agentId);
-                    const model = agent?.value.model;
-                    if (!model || typeof model !== "object" || Array.isArray(model)) return undefined;
-                    const value = model as Record<string, unknown>;
-                    const provider = typeof value.provider === "string" ? value.provider : undefined;
-                    const modelName = typeof value.model === "string" ? value.model : undefined;
-                    if (!provider || !modelName || !isRouteAdmitted(projectRoot, `${provider}/${modelName}`)) {
-                      throw new Error("producer_route_not_admitted");
-                    }
-                    return { provider, model: modelName };
-                  },
                 })
               : createKxmSimulatedProducer(async () => {
                   if (delayMs > 0) {

package/plugins/kxm/src/suggest.ts

@@ -191,10 +191,10 @@ export function suggestWorkflowAndRoles(
       supported: true,
       prerequisites: [
         "Run kxm init in the target repository if needed, then install the exact template with the suggested command. If that workflow ID already exists, stop and review it; the commands below apply only to a newly installed template, not an existing definition with potentially different agents or permissions.",
-        ...roles.map((role) => `Set harness: ${role.harness} and model: <your authenticated compatible model selector> in .kxm/agents/${role.agent}.yaml. Admit that exact selector in .kxm/routes.yaml and ensure it is not disabled; this recommendation does not choose a model or change routing.`),
+        ...roles.map((role) => `Set role on .kxm/agents/${role.agent}.yaml to a role whose roster names an admitted route for harness ${role.harness}. Admit that route's selector in .kxm/routes.yaml and ensure it is not disabled; this recommendation does not choose a model or change routing.`),
         ...(writeStep ? [
           `Keep each writer step at assignments.maximum: 1 and set limits.maxConcurrentRuns: 1 in .kxm/project.yaml; the live ${selected.id} writer profile requires a lone writer in the checkout.`,
-          `If .kxm/roster.yaml exists, it must be readable kxm.developer-roster.v1 with a lineup.writer route matching harness: ${selected.id} and the selected writer model (model or vendor/model), status: admitted, and permissions containing edit.`,
+          `The writer role roster must name a route whose harness is ${selected.id}, whose status is admitted, and whose permissions contain edit.`,
           "Configure the test gate in .kxm/gates.yaml with kind: command and argv for this repository's actual verification command. A scaffold/example command or simulation is not evidence that the implementation works.",
         ] : []),
         `Validate the installed workflow with kxm gate validate --file .kxm/workflows/${bestPattern.id}.yaml and the project configuration with kxm init --dry-run before creating a run.`,

package/plugins/kxm/src/template.ts

@@ -175,21 +175,9 @@ 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" },
-      });
-    }
+    if (coordinator) files.set(".kxm/agents/coordinator.yaml", { ...coordinator, role: "planner" });
     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" },
-      });
-    }
+    if (implementer) files.set(".kxm/agents/implementer.yaml", { ...implementer, role: "writer" });
     const workflow = files.get(".kxm/workflows/default.yaml");
     if (workflow) {
       const limits = { ...(workflow.limits as JsonObject) };

package/schemas/agent.schema.json

@@ -12,6 +12,14 @@
     "model": { "$ref": "common.schema.json#/$defs/modelSelector" },
     "executor": { "$ref": "common.schema.json#/$defs/identifier" },
     "harness": { "$ref": "common.schema.json#/$defs/identifier" },
+    "role": { "$ref": "common.schema.json#/$defs/identifier" },
+    "effort": { "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"] },
+    "skills": {
+      "type": "array",
+      "items": { "$ref": "common.schema.json#/$defs/identifier" },
+      "maxItems": 64,
+      "uniqueItems": true
+    },
     "tools": { "$ref": "common.schema.json#/$defs/toolPolicy" },
     "defaultRepositoryAccess": { "$ref": "common.schema.json#/$defs/repositoryAccess" },
     "repositories": {

package/scripts/roster-policy.d.mts

@@ -7,7 +7,6 @@ export interface RosterRoute {
   readonly status: 'admitted' | 'retired';
 }
 export interface RosterPolicy {
-  readonly schema: 'kxm.developer-roster.v1';
   readonly routes: Readonly<Record<string, RosterRoute>>;
   readonly lineup: Readonly<Record<string, readonly string[]>>;
   readonly required_critics: Readonly<Record<'review-arch' | 'review-cli', string>>;
@@ -15,9 +14,11 @@ export interface RosterPolicy {
 }
 export interface PolicyIdentity { readonly commit: string; readonly blob: string; readonly sha256: string }
 export interface LoadedPolicy { readonly identity: PolicyIdentity; readonly policy: RosterPolicy }
+export function refuseRetiredRosterFile(root: string): void;
 export function loadTrustedRosterPolicy(): LoadedPolicy;
 export function resolveBoundPolicy(identity: PolicyIdentity): LoadedPolicy;
 export function canonicalVendor(value: string): string;
+export function assembleRosterPolicy(models: readonly Record<string, unknown>[], roles: readonly Record<string, unknown>[]): RosterPolicy;
 export function validateRosterDocument(
   policy: RosterPolicy,
   readBlob: (source: string) => string | Uint8Array | null | undefined,