@kontextmind/kxm 0.7.126 → 0.7.127

package/plugins/kxm/dist/server.js

@@ -14943,6 +14943,59 @@ var KXM_YAML_LIMITS = Object.freeze({
   maxKeys: 8192
 });
 
+// plugins/kxm/src/policy-draft.mjs
+var POLICY_DRAFT_PURPOSES = Object.freeze([
+  "writer",
+  "planner",
+  "reviewer-arch",
+  "reviewer-cli",
+  "experiment"
+]);
+var POLICY_DRAFT_PERMISSIONS = Object.freeze(["edit", "read-only"]);
+var POLICY_DRAFT_STATUSES = Object.freeze(["admitted", "candidate", "retired"]);
+var EFFORTS = Object.freeze(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+var MODES = Object.freeze(["headless", "interactive", "either"]);
+var MODEL_KEYS = Object.freeze([
+  "schema",
+  "id",
+  "harness",
+  "model",
+  "vendor",
+  "status",
+  "permissions",
+  "origin",
+  "thinking",
+  "tags",
+  "capabilities",
+  "priority",
+  "fallbacks",
+  "limits"
+]);
+var ROLE_KEYS = Object.freeze([
+  "schema",
+  "id",
+  "purpose",
+  "permission",
+  "description",
+  "extends",
+  "roster",
+  "skills",
+  "tools",
+  "produces",
+  "consumes",
+  "policy"
+]);
+var ORIGIN_KEYS = Object.freeze(["source", "sha256"]);
+var LIMIT_KEYS = Object.freeze(["contextTokens", "outputTokens", "timeoutMs"]);
+var TOOL_KEYS = Object.freeze(["preset", "allow", "deny"]);
+var TEMPLATE_KEYS = Object.freeze(["template", "schema"]);
+var POLICY_KEYS = Object.freeze(["vendorIndependenceRequired", "maxTransitions", "requiresGateVerification", "fallback"]);
+var FALLBACK_KEYS = Object.freeze(["onError", "maxSwitches", "revert"]);
+var FALLBACK_ERRORS = Object.freeze(["rate_limit", "transport", "provider_unavailable"]);
+var FALLBACK_REVERT = Object.freeze(["next_run", "never"]);
+var ROSTER_ENTRY_KEYS = Object.freeze(["route", "effort", "mode"]);
+var CRITIC_PURPOSES = Object.freeze(["reviewer-arch", "reviewer-cli"]);
+
 // plugins/kxm/src/template.ts
 var import_yaml2 = __toESM(require_dist(), 1);
 
@@ -15439,7 +15492,8 @@ var RESOURCE_SCHEMA = Object.freeze({
   project: { identity: "kxm.project.v1", file: "project.schema.json" },
   repository: { identity: "kxm.repository.v1", file: "repository.schema.json" },
   agent: { identity: "kxm.agent.v1", file: "agent.schema.json" },
-  model: { identity: "kxm.model.v1", file: "model.schema.json" },
+  model: { identity: "kxm.model.v2", file: "model.schema.json" },
+  role: { identity: "kxm.role.v2", file: "role.schema.json" },
   environment: { identity: "kxm.environment.v1", file: "environment.schema.json" },
   workflow: { identity: "kxm.workflow.v1", file: "workflow.schema.json" },
   "gate-registry": { identity: "kxm.gate-registry.v1", file: "gate-registry.schema.json" }

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.126",
+  "version": "0.7.127",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm/SKILL.md

@@ -19,7 +19,7 @@ writers, or replace `.kxm/roster.yaml` trusted policy.
 | Session status, dashboard screens, studio layout | `kxm-session` | `session`, `dash`, `studio` |
 | Delegate to or answer another agent | `kxm-peer` | `peer` (`peer await` is capped at 60 seconds) |
 | Work inside a durable workflow run, gates, signed callbacks | `kxm-workflow` | `workflow`, `gate` |
-| Role definitions, role hosts, model rosters | `kxm-definitions` | `role` |
+| Role definitions and model rosters | `kxm-definitions` | `role` |
 | Create, drive, inspect, or cancel a run, use a worktree lane, land a branch, run the developer assignment loop, or build and serve the docs site | `kxm-runs` | `run`, `runs`, `lane`, `land`, `assign`, `docs` |
 | What we know or decided, recall, context footprint, Git memory | `kxm-context-memory` | `context`, `memory`, `explain` |
 | Turn a repeated practice into a governed skill | `kxm-skill-lifecycle` | `skills` |

package/plugins/kxm/skills/kxm-definitions/SKILL.md

@@ -15,7 +15,6 @@ or permission to execute an assignment.
 ```bash
 kxm role list --scope all --json
 kxm role get writer --scope local --json
-kxm role hosts --json
 kxm role --help
 ```
 
@@ -29,19 +28,16 @@ changes every project or the trusted developer runner.
 |---|---|---|
 | `kxm role list` | List configured roles | `--scope all\|global\|local` |
 | `kxm role get <roleId>` | Read role YAML and details | `--scope all\|global\|local` |
-| `kxm role add [roleId]` | Add a YAML definition or construct a role | `--file`, `--description`, `--skills`, `--harness`, `--model`, `--scope`, `--overwrite`, `--pick` |
-| `kxm role modify [roleId]` | Change description, skill references, or model roster | `--description`, `--add-skill`, `--remove-skill`, `--add-model <harness:model>`, `--remove-model`, `--scope`, `--pick` |
+| `kxm role add [roleId]` | Add a YAML definition or construct a role | `--file`, `--description`, `--skills`, `--route` (repeatable; the first id is primary and must name `.kxm/models/<route-id>.yaml`), `--scope`, `--overwrite`, `--pick` |
+| `kxm role modify [roleId]` | Change description, skill references, or the route roster | `--description`, `--add-skill`, `--remove-skill`, `--add-route <route-id>`, `--remove-route <route-id>`, `--scope`, `--pick` |
 | `kxm role remove [roleId]` | Remove a definition | `--scope`, `--pick` |
-| `kxm role hosts` | List role seats and the host, model, and effort each resolves to, with the source of that decision | `--scope all\|global\|local` |
-| `kxm role set-host <seatId> <host>` | Bind a role seat to a host in `.kxm/role-hosts.yaml` | `--model`, `--effort low\|medium\|high\|xhigh`, `--scope global\|local` |
 | `kxm role resume <runId> [ruling]` | Resume an audit-escalated run with an operator directive | `[ruling]` free text |
 
 Use `--json` for structured output. Inspect command-specific `--help` before
 constructing a mutation; do not invent `create`, `update`, `delete`, `validate`,
 or `apply` subcommands under `kxm role`.
 
-`kxm role hosts` reads only. `kxm role set-host` writes `.kxm/role-hosts.yaml`
-(or the global file); show the user the resulting diff. `kxm role resume`
+`kxm role resume`
 records the operator's ruling on an audit escalation: run it only with the
 ruling the user gave you, and preview a KXM run with `--dry-run` first.
 

package/plugins/kxm/src/autocomplete.ts

@@ -57,7 +57,7 @@ const SUBCOMMANDS: Record<string, string[]> = {
   goal: ["create", "list", "get"],
   task: ["create", "list", "get", "run", "sync"],
   studio: ["layout", "serve"],
-  role: ["list", "get", "add", "remove", "modify", "hosts", "set-host", "resume"],
+  role: ["list", "get", "add", "remove", "modify", "resume"],
 };
 
 export function generateShellCompletion(shell: SupportedShell): string {

package/plugins/kxm/src/cli/project.ts

@@ -897,7 +897,13 @@ export async function cmdModelsScreen(runtime: Runtime): Promise<number> {
       if (!Number.isInteger(index) || !models[index]) continue;
       const model = models[index];
       if (command === "a" || command === "d") setRouteState(runtime.dirs.workdir, model, command === "a" ? "admitted" : "disabled");
-      else if (command === "r" || command === "x") setRouteState(runtime.dirs.workdir, model, "admitted", (await ask("role: ")).trim(), command === "x");
+      else if (command === "r" || command === "x") {
+        try {
+          setRouteState(runtime.dirs.workdir, model, "admitted", (await ask("role: ")).trim(), command === "x");
+        } catch (error) {
+          runtime.io.stderr(`${error instanceof Error ? error.message : "unknown route"}\n`);
+        }
+      }
     }
   } finally { rl.close(); }
 }

package/plugins/kxm/src/cli/roles.ts

@@ -5,17 +5,13 @@ import { createInterface } from "node:readline";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { DatabaseSync, openReadOnlyDatabase } from "../sqlite.ts";
 import {
-  DEFAULT_ROLES,
-  DEFAULT_ROLE_SEATS,
   listRoles,
   getRole,
   addRole,
   removeRole,
   modifyRole,
-  loadRoleHostsConfig,
-  setRoleSeatHost,
-  resolveRoleSeat,
   parseRoleFile,
+  rolePurposeForId,
   type KxmRoleDefinition,
 } from "../role.ts";
 import { discoverKxmProjectRoot, kxmRoleWriteIssues } from "../project-config.ts";
@@ -112,7 +108,7 @@ export async function cmdRoleList(
   const lines: string[] = ["ROLES:"];
   for (const r of roles) {
     const scopeTag = r.scope === "overridden" ? "[local override]" : `[${r.scope}]`;
-    const modelTag = r.primaryModel ? `(${r.primaryHarness ?? "harness"}:${r.primaryModel})` : "";
+    const modelTag = r.primaryRoute ? `(${r.primaryRoute})` : "";
     lines.push(`  ${r.id.padEnd(16)} ${scopeTag.padEnd(16)} ${modelTag.padEnd(28)} ${r.description}`);
   }
   print(runtime.io, false, {}, `${lines.join("\n")}\n`);
@@ -149,8 +145,7 @@ export async function cmdRoleAdd(
     file?: string | undefined;
     description?: string | undefined;
     skills?: string | undefined;
-    harness?: string | undefined;
-    model?: string | undefined;
+    route?: string[] | undefined;
     scope?: "global" | "local" | undefined;
     overwrite?: boolean | undefined;
     pick?: string | boolean | undefined;
@@ -159,12 +154,7 @@ export async function cmdRoleAdd(
   const scope = options.scope ?? "local";
   let base: KxmRoleDefinition | undefined;
   if (!roleId || options.pick) {
-    const candidates: PickCandidate[] = Object.values(DEFAULT_ROLES).map((r) => ({
-      id: r.id,
-      description: r.description,
-      label: "template",
-      payload: r,
-    }));
+    const candidates: PickCandidate[] = [];
     if (scope === "local") {
       const globalRoles = listRoles({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
       for (const gr of globalRoles) {
@@ -175,7 +165,7 @@ export async function cmdRoleAdd(
         }
       }
     }
-    const picked = await resolvePickItem(runtime.io, `Select a role template to add (${scope})`, candidates, options.pick, runtime.env);
+    const picked = await resolvePickItem(runtime.io, `Select a global role to add (${scope})`, candidates, options.pick, runtime.env);
     if (!picked) {
       if (!roleId) {
         runtime.io.stderr("role add failed: missing roleId or pick selection\n");
@@ -188,24 +178,50 @@ export async function cmdRoleAdd(
   }
 
   const skills = options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
-  const roster = options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : undefined;
+  const routes = (options.route ?? []).filter((route) => route.length > 0);
+  const roster = routes.length > 0 ? routes.map((route) => ({ route })) : undefined;
+  // A constructed or copied role takes --route, and the first id is the primary.
+  // A missing model file is the same refusal as modify --add-route. --file is checked
+  // after its roster is parsed, for both local and global scope.
+  const projectRoot = discoverKxmProjectRoot(runtime.cwd) ?? runtime.cwd;
+  const refuseMissingRoute = (routeId: string): boolean => {
+    const modelFile = join(projectRoot, ".kxm", "models", `${routeId}.yaml`);
+    if (existsSync(modelFile)) return false;
+    runtime.io.stderr(`kxm: route '${routeId}' is not a file under .kxm/models/\n`);
+    return true;
+  };
+  if (roster && !options.file) {
+    for (const entry of roster) {
+      if (refuseMissingRoute(entry.route)) return 1;
+    }
+  }
+  const purpose = rolePurposeForId(roleId ?? "experiment");
   let roleDef: KxmRoleDefinition;
   if (options.file) {
     const filePath = resolve(runtime.cwd, options.file);
     const content = readFileSync(filePath, "utf8");
     roleDef = parseYaml(content) as KxmRoleDefinition;
     roleDef.id = roleId!;
+    roleDef.schema = "kxm.role.v2";
+    roleDef.purpose ??= rolePurposeForId(roleDef.id);
+    roleDef.permission ??= roleDef.purpose === "writer" ? "edit" : "read-only";
+    for (const entry of roleDef.roster ?? []) {
+      if (typeof entry?.route === "string" && entry.route.length > 0 && refuseMissingRoute(entry.route)) return 1;
+    }
   } else if (base) {
     roleDef = {
       ...base,
+      schema: "kxm.role.v2",
       description: options.description || base.description,
       skills: skills ?? base.skills,
       roster: roster ?? base.roster,
     };
   } else {
     roleDef = {
-      schema: "kxm.role.v1",
+      schema: "kxm.role.v2",
       id: roleId!,
+      purpose,
+      permission: purpose === "writer" ? "edit" : "read-only",
       description: options.description || `Role ${roleId}`,
       skills: skills ?? [],
       roster: roster ?? [],
@@ -327,8 +343,8 @@ export async function cmdRoleModify(
     description?: string | undefined;
     addSkill?: string | undefined;
     removeSkill?: string | undefined;
-    addModel?: string | undefined;
-    removeModel?: string | undefined;
+    addRoute?: string | undefined;
+    removeRoute?: string | undefined;
     scope?: "global" | "local" | undefined;
     pick?: string | boolean | undefined;
   },
@@ -379,14 +395,18 @@ export async function cmdRoleModify(
   }
 
   let roster = [...(role.roster ?? [])];
-  if (options.addModel) {
-    const [harnessOrModel, maybeModel] = options.addModel.split(":");
-    const harness = maybeModel ? harnessOrModel! : "pi";
-    const model = maybeModel || harnessOrModel!;
-    roster.push({ harness, model });
+  if (options.addRoute) {
+    const routeId = options.addRoute;
+    const projectRoot = discoverKxmProjectRoot(runtime.cwd) ?? runtime.cwd;
+    const modelFile = join(projectRoot, ".kxm", "models", `${routeId}.yaml`);
+    if (!existsSync(modelFile)) {
+      runtime.io.stderr(`kxm: route '${routeId}' is not a file under .kxm/models/\n`);
+      return 1;
+    }
+    if (!roster.some((entry) => entry.route === routeId)) roster.push({ route: routeId });
   }
-  if (options.removeModel) {
-    roster = roster.filter((entry) => entry.model !== options.removeModel);
+  if (options.removeRoute) {
+    roster = roster.filter((entry) => entry.route !== options.removeRoute);
   }
 
   const updates: Partial<KxmRoleDefinition> = {
@@ -419,130 +439,6 @@ export async function cmdRoleModify(
   }
 }
 
-export async function cmdRoleHosts(
-  runtime: Runtime,
-  options: { scope?: "all" | "global" | "local" | undefined } = {},
-): Promise<number> {
-  const hostsConfig = loadRoleHostsConfig({
-    scope: options.scope,
-    repoRoot: runtime.cwd,
-    userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
-  });
-
-  const seatIds = Array.from(
-    new Set([
-      ...Object.keys(DEFAULT_ROLE_SEATS),
-      ...Object.keys(hostsConfig.config.seats ?? {}),
-    ]),
-  ).sort();
-
-  const seats = seatIds.map((seatId) => {
-    const resolved = resolveRoleSeat(seatId, {
-      repoRoot: runtime.cwd,
-      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
-    });
-    return {
-      seatId,
-      host: resolved.host,
-      model: resolved.model,
-      provider: resolved.provider,
-      effort: resolved.effort,
-      source: resolved.source,
-      configuredHost: hostsConfig.config.seats?.[seatId]?.host,
-      configuredModel: hostsConfig.config.seats?.[seatId]?.model,
-    };
-  });
-
-  if (runtime.json) {
-    print(
-      runtime.io,
-      true,
-      {
-        ok: true,
-        command: "role hosts",
-        scope: hostsConfig.scope,
-        filePath: hostsConfig.filePath,
-        seats,
-        hostProviders: hostsConfig.config.hostProviders ?? {},
-      },
-      "",
-    );
-    return 0;
-  }
-
-  const lines: string[] = [
-    `ROLE SEATS (${hostsConfig.scope}${hostsConfig.filePath ? ` at ${hostsConfig.filePath}` : ""}):`,
-  ];
-  for (const s of seats) {
-    const modelStr = s.model ? ` [${s.model}]` : "";
-    const sourceTag = `(via ${s.source})`;
-    lines.push(`  ${s.seatId.padEnd(16)} -> host: ${s.host.padEnd(12)} ${modelStr.padEnd(30)} ${sourceTag}`);
-  }
-  if (hostsConfig.config.hostProviders && Object.keys(hostsConfig.config.hostProviders).length > 0) {
-    lines.push("\nHOST PROVIDERS:");
-    for (const [h, p] of Object.entries(hostsConfig.config.hostProviders)) {
-      lines.push(`  ${h.padEnd(16)} -> provider: ${p}`);
-    }
-  }
-  print(runtime.io, false, {}, `${lines.join("\n")}\n`);
-  return 0;
-}
-
-export async function cmdRoleSetHost(
-  runtime: Runtime,
-  seatId: string,
-  host: string,
-  options: {
-    model?: string | undefined;
-    effort?: "low" | "medium" | "high" | "xhigh" | undefined;
-    scope?: "global" | "local" | undefined;
-  } = {},
-): Promise<number> {
-  if (!seatId || !host) {
-    runtime.io.stderr("kxm role set-host requires <seatId> and <host>\n");
-    return 1;
-  }
-
-  try {
-    const result = setRoleSeatHost(seatId, host, {
-      model: options.model,
-      effort: options.effort,
-      scope: options.scope ?? "local",
-      repoRoot: runtime.cwd,
-      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
-      dryRun: runtime.dryRun,
-    });
-    if (runtime.dryRun) {
-      printPlan(
-        runtime,
-        { command: "role set-host", seatId, host, binding: result.binding, filePath: result.filePath, scope: result.scope },
-        [{ action: "write", target: result.filePath }],
-        `bind seat '${seatId}' to host '${host}'`,
-      );
-      return 0;
-    }
-
-    print(
-      runtime.io,
-      runtime.json,
-      {
-        ok: true,
-        command: "role set-host",
-        seatId,
-        host,
-        binding: result.binding,
-        filePath: result.filePath,
-        scope: result.scope,
-      },
-      `Bound seat '${seatId}' to host '${host}' in ${result.filePath}\n`,
-    );
-    return 0;
-  } catch (err: unknown) {
-    runtime.io.stderr(`role set-host failed: ${(err as Error).message}\n`);
-    return 1;
-  }
-}
-
 export async function cmdRoleResume(
   runtime: Runtime,
   runId: string,

package/plugins/kxm/src/cli.ts

@@ -48,8 +48,7 @@ import {
   cmdRoleAdd,
   cmdRoleRemove,
   cmdRoleModify,
-  cmdRoleHosts,
-  cmdRoleSetHost,
+
   cmdRoleResume,
 } from "./cli/roles.ts";
 
@@ -215,7 +214,7 @@ const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
   "peer list", "peer send", "peer get", "peer await", "peer cancel", "peer fanout", "peer inbox", "peer reply",
   "workflow list", "workflow get", "workflow checkpoint", "workflow record", "workflow wait", "workflow signal",
   "workflow start", "workflow export", "workflow definitions", "workflow add", "workflow remove", "workflow modify",
-  "role list", "role get", "role add", "role remove", "role modify", "role hosts", "role set-host", "role resume",
+  "role list", "role get", "role add", "role remove", "role modify", "role resume",
   "gate validate", "gate artifacts-exist", "gate degrade", "gate signal", "gate github watch",
   "improve report",
   "context get", "context recall", "context state", "context episode", "context promote", "context explain",
@@ -1026,12 +1025,11 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
     .option("--file <path>", "Path to YAML role definition file")
     .option("--description <text>", "Role description")
     .option("--skills <skills>", "Comma-separated skills list")
-    .option("--harness <harness>", "Primary harness name (e.g. grok, claude, agy, pi)")
-    .option("--model <model>", "Primary model identifier (e.g. grok-4.6, fable, gemini-3.8-flash-high)")
+    .option("--route <route-id>", "Route id under .kxm/models/. Repeat to set the roster; the first id is primary", (value: string, previous: string[] | undefined) => (previous ?? []).concat(value))
     .option("--scope <scope>", "Configuration scope: global or local (default: local)", "local")
     .option("--overwrite", "Overwrite existing role definition if present")
-    .option("--pick [selection]", "Pick from available role templates (index or id)")
-    .action(async function roleAddAction(this: Command, roleId?: string, options?: { file?: string; description?: string; skills?: string; harness?: string; model?: string; scope?: "global" | "local"; overwrite?: boolean; pick?: string | boolean }) {
+    .option("--pick [selection]", "Pick a global role to copy (index or id)")
+    .action(async function roleAddAction(this: Command, roleId?: string, options?: { file?: string; description?: string; skills?: string; route?: string[]; scope?: "global" | "local"; overwrite?: boolean; pick?: string | boolean }) {
       result.code = await cmdRoleAdd(runtimeFrom(ctx, this), roleId, options ?? {});
     });
   addGlobalOptions(role.command("remove [roleId]").description("Remove a role definition"))
@@ -1044,25 +1042,13 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
     .option("--description <text>", "Updated description")
     .option("--add-skill <skill>", "Skill to add")
     .option("--remove-skill <skill>", "Skill to remove")
-    .option("--add-model <harness:model>", "Model to add to roster")
-    .option("--remove-model <model>", "Model to remove from roster")
+    .option("--add-route <route-id>", "Route id to add to the roster. The id must name a file under .kxm/models/")
+    .option("--remove-route <route-id>", "Route id to remove from the roster")
     .option("--scope <scope>", "Configuration scope: global or local")
     .option("--pick [selection]", "Pick a role to modify (index or id)")
-    .action(async function roleModifyAction(this: Command, roleId?: string, options?: { description?: string; addSkill?: string; removeSkill?: string; addModel?: string; removeModel?: string; scope?: "global" | "local"; pick?: string | boolean }) {
+    .action(async function roleModifyAction(this: Command, roleId?: string, options?: { description?: string; addSkill?: string; removeSkill?: string; addRoute?: string; removeRoute?: string; scope?: "global" | "local"; pick?: string | boolean }) {
       result.code = await cmdRoleModify(runtimeFrom(ctx, this), roleId, options ?? {});
     });
-  addGlobalOptions(role.command("hosts").description("List role seats and resolved execution hosts from .kxm/role-hosts.yaml"))
-    .option("--scope <scope>", "Filter by scope: all, global, or local", "all")
-    .action(async function roleHostsAction(this: Command, options: { scope?: "all" | "global" | "local" }) {
-      result.code = await cmdRoleHosts(runtimeFrom(ctx, this), options);
-    });
-  addGlobalOptions(role.command("set-host <seatId> <host>").description("Bind a role seat to a host in .kxm/role-hosts.yaml"))
-    .option("--model <model>", "Model identifier for this seat")
-    .option("--effort <effort>", "Effort level: low, medium, high, xhigh")
-    .option("--scope <scope>", "Configuration scope: global or local (default: local)", "local")
-    .action(async function roleSetHostAction(this: Command, seatId: string, host: string, options: { model?: string; effort?: "low" | "medium" | "high" | "xhigh"; scope?: "global" | "local" }) {
-      result.code = await cmdRoleSetHost(runtimeFrom(ctx, this), seatId, host, options);
-    });
   addGlobalOptions(role.command("resume <runId> [ruling]").description("Resume an audit-escalated role run with an operator directive"))
     .action(async function roleResumeAction(this: Command, runId: string, ruling?: string) {
       result.code = await cmdRoleResume(runtimeFrom(ctx, this), runId, ruling);

package/plugins/kxm/src/engine.ts

@@ -1342,6 +1342,28 @@ export interface KxmPanelDispatchSeams {
 
 export const kxmPanelDispatchSeams: KxmPanelDispatchSeams = {};
 
+/** Selectors named by v2 route files: the model id, `vendor/model`, and `harness/model`. */
+function selectorsNamedByRoutes(projectRoot: string, routeIds: readonly string[]): string[] {
+  const selectors = new Set<string>();
+  for (const routeId of routeIds) {
+    const file = join(projectRoot, ".kxm", "models", `${routeId}.yaml`);
+    if (!existsSync(file)) continue;
+    let parsed: { harness?: unknown; model?: unknown; vendor?: unknown };
+    try {
+      parsed = parse(readFileSync(file, "utf8")) as { harness?: unknown; model?: unknown; vendor?: unknown };
+    } catch {
+      continue;
+    }
+    const model = typeof parsed.model === "string" ? parsed.model : "";
+    const vendor = typeof parsed.vendor === "string" ? parsed.vendor : "";
+    const harness = typeof parsed.harness === "string" ? parsed.harness : "";
+    if (model) selectors.add(model);
+    if (vendor && model) selectors.add(`${vendor}/${model}`);
+    if (harness && model) selectors.add(`${harness}/${model}`);
+  }
+  return [...selectors];
+}
+
 function unreconciledPanelAttemptId(state: KxmRunState): string | undefined {
   const current = state.currentStep;
   if (!current) return undefined;
@@ -1438,7 +1460,8 @@ function resolveProducerRoute(
   const role = agentId === "implementer" ? "writer" : agentId;
   const roleBindings = listRoleBindings(projectRoot);
   const roster = roleBindings[role];
-  if (roster && !roster.includes(selector)) {
+  const rosterSelectors = roster ? selectorsNamedByRoutes(projectRoot, roster) : undefined;
+  if (rosterSelectors && !rosterSelectors.includes(selector)) {
     return {
       error: {
         reason: "step_unsupported",

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

@@ -10,10 +10,11 @@
  * This module writes only current KXM project resources:
  *   - `.kxm/agents/<role-slug>.yaml`   (kxm.agent.v1)
  *   - `.kxm/workflows/<slug>.yaml`     (kxm.workflow.v1)
+ *   - `.kxm/roles/<role-slug>.yaml`    (kxm.role.v2)
+ *   - `.kxm/models/<route-id>.yaml`    (kxm.model.v2)
  *   - 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.
+ * `.kxm/roster.json`) or the trusted `.kxm/roster.yaml` policy.
  *
  * 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.
@@ -27,7 +28,8 @@
  * admission decision says so.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { stringify } from "yaml";
 import { type HarnessInventory } from "./harness.ts";
@@ -485,9 +487,14 @@ function workflowDocument(workflow: GuideWorkflow): Record<string, unknown> {
 
 /**
  * Render the planned KXM resource files (`.kxm/agents/*.yaml`,
- * `.kxm/workflows/*.yaml`). Pure: no disk access.
+ * `.kxm/workflows/*.yaml`). A Pi model origin hashes `.kxm/project.yaml`
+ * when that file exists, and is omitted when it does not.
  */
 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) {
@@ -496,10 +503,37 @@ export function renderGuideSetupFiles(projectRoot: string, plan: GuideSetupPlan)
   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 modelDocument: Record<string, unknown> = {
+      schema: "kxm.model.v2",
+      id: routeId,
+      harness: binding.harness,
+      model: binding.model,
+      vendor: binding.provider,
+      status: "admitted",
+      permissions: [writer ? "edit" : "read-only"],
+    };
+    if (binding.harness === "pi" && projectOrigin) modelDocument.origin = projectOrigin;
     files.push({
       path: join(projectRoot, ".kxm", "agents", `${role}.yaml`),
       content: stringify(agentDocument(role, stage, binding)),
     });
+    files.push({
+      path: join(projectRoot, ".kxm", "models", `${routeId}.yaml`),
+      content: stringify(modelDocument),
+    });
+    files.push({
+      path: join(projectRoot, ".kxm", "roles", `${role}.yaml`),
+      content: stringify({
+        schema: "kxm.role.v2",
+        id: role,
+        purpose: writer ? "writer" : "experiment",
+        permission: writer ? "edit" : "read-only",
+        description: stage.domain.slice(0, 2000),
+        roster: [{ route: routeId }],
+      }),
+    });
   }
   for (const workflow of plan.workflows) {
     files.push({

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

package/plugins/kxm/src/permission.ts

@@ -56,6 +56,7 @@ const PROSE_FIELDS: Readonly<Record<KxmResourceKind, ReadonlySet<string>>> = {
   repository: new Set(["description"]),
   agent: new Set(["purpose", "instructions"]),
   model: new Set([]),
+  role: new Set(["description"]),
   environment: new Set([]),
   workflow: new Set(["description"]),
   "gate-registry": new Set([]),
@@ -193,6 +194,16 @@ export function kxmAuthorityEntries(resource: { kind: KxmResourceKind; id?: stri
       }
       break;
     }
+    case "role": {
+      push("/schema", "resource-shape", value.schema);
+      push("/purpose", "resource-shape", value.purpose);
+      push("/permission", "resource-shape", value.permission);
+      push("/extends", "resource-shape", value.extends);
+      push("/roster", "resource-shape", value.roster);
+      push("/policy", "resource-shape", value.policy);
+      push("/tools", "tools", value.tools);
+      break;
+    }
     case "gate-registry": {
       push("/schema", "resource-shape", value.schema);
       const gates = asObject(value.gates) ?? {};