@kontextmind/kxm 0.6.0 → 0.7.4

package/plugins/kxm/src/cli.ts

@@ -3,7 +3,8 @@ import { createHash, createHmac, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
+import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { Command, CommanderError } from "commander";
 import {
@@ -15,7 +16,7 @@ import {
 } from "./memory.ts";
 import { createBackup, restoreBackup } from "./database.ts";
 import { verifyArtifactExists } from "./artifacts-exist.ts";
-import { canonicalWorkflowEvidenceKey, parseWorkflowDefinitions } from "./workflow.ts";
+import { canonicalWorkflowEvidenceKey, parseWorkflowDefinitions, resumeWorkflowFromRuling } from "./workflow.ts";
 import { postWorkflowSignal, watchGithubChecks } from "./github-watch.ts";
 import { buildRetrospective, writeRetrospective } from "./retrospective.ts";
 import { redactSecrets } from "./redact.ts";
@@ -25,6 +26,8 @@ import { agentWorker, gateWorker, workerResult, type Worker, type WorkerOutcome
 import { appendTelemetry, inferImprovementTarget, makeTelemetryEvent, readTelemetry, readRoutingRecords, telemetryPath } from "./telemetry.ts";
 import { behavioralConfigHash, compareRoutingRecords, groupByBehavior, generateRoutingReport, formatRoutingReport } from "./routing.ts";
 import { loadPriceCatalog, type PriceCatalog } from "./prices.ts";
+import { refreshModelInventory } from "./model-inventory.ts";
+import { listInventoryModels, listRoleBindings, loadProducerPolicy, setModelState, updateProducer } from "./producers.ts";
 import { createSession, loadNamedWorkers, rosterNames, sessionAssetDirs, workflowAssetDirs, writeSession } from "./session.ts";
 import { buildImprovementReport, formatImprovementReport, writeImprovementReport } from "./improve.ts";
 import { MESH_TUI_PANELS, runMeshTui, type MeshTuiPanel } from "./tui.ts";
@@ -62,6 +65,13 @@ import {
   type InstallProbe,
 } from "./kxm-install-kind.ts";
 import { VnextConfigError, discoverVnextProjectRoot, type VnextInitializationPlan } from "./vnext-config.ts";
+import {
+  GUIDE_WORKFLOWS,
+  parseGuideSelection,
+  planGuideSetup,
+  renderGuideSetupFiles,
+  writeGuideSetupFiles,
+} from "./init-guide-setup.ts";
 import { vnextUserStateRoot } from "./vnext-bindings.ts";
 import { initializeVnextProject } from "./vnext-init.ts";
 import { applyVnextMigration, planVnextMigration, verifyVnextMigration } from "./vnext-migrate.ts";
@@ -84,7 +94,16 @@ import {
 } from "./vnext-harness.ts";
 import type { WorkflowEvidenceInput, WorkflowJournalEntry, WorkflowRun } from "./workflow.ts";
 import { HubClient } from "./client.ts";
-import { AGENT_COMMANDS_MAP, enforceToolPolicy, mintSessionToken } from "./commands.ts";
+import {
+  AGENT_COMMANDS_MAP,
+  clearSessionTokenFromDisk,
+  enforceToolPolicy,
+  mintSessionToken,
+  parseSessionToken,
+  persistSessionTokenToDisk,
+  readSessionTokenFromDisk,
+  sessionTokenPath,
+} from "./commands.ts";
 import {
   loadKxmConfig,
   setKxmConfigValue,
@@ -92,6 +111,7 @@ import {
   formatKxmConfig,
 } from "./config.ts";
 import { generateShellCompletion, type SupportedShell } from "./autocomplete.ts";
+import { completionRcTarget, completionScriptPath, detectShell, installPathEntry, installShellCompletion, kxmBinDir } from "./completion-install.ts";
 import { suggestWorkflowAndRoles } from "./suggest.ts";
 import {
   createGoal,
@@ -104,9 +124,30 @@ import {
   type TaskStatus,
   type TrackerType,
 } from "./task-manager.ts";
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { compileVnextWorkflow } from "./vnext-engine-compile.ts";
-import { generateStudioLayout } from "./studio-layout.ts";
+import { generateStudioLayout, createStudioServer, DEFAULT_STUDIO_PORT } from "./studio-layout.ts";
+import {
+  listRoles,
+  getRole,
+  addRole,
+  removeRole,
+  modifyRole,
+  DEFAULT_ROLES,
+  DEFAULT_ROLE_SEATS,
+  loadRoleHostsConfig,
+  setRoleSeatHost,
+  resolveRoleSeat,
+  type KxmRoleDefinition,
+} from "./role.ts";
+import {
+  listWorkflowDefinitions,
+  addWorkflowDefinition,
+  removeWorkflowDefinition,
+  modifyWorkflowDefinition,
+  WORKFLOW_TEMPLATES,
+  DEFAULT_WORKFLOW_TEMPLATE,
+} from "./workflow-manager.ts";
 
 export interface CliSpawnResult {
   status: number | null;
@@ -596,9 +637,13 @@ async function cmdVnextInit(runtime: Runtime, options: { name?: string; projectI
       return code;
     };
     if (initialized.action === "created") {
+      await maybeOfferCompletionInstall(runtime);
+      await maybeOfferGuideSetup(runtime);
       return finishInit(0, `initialized vNext project at ${initialized.projectRoot ?? runtime.cwd}`);
     }
     if (initialized.action === "joined") {
+      await maybeOfferCompletionInstall(runtime);
+      await maybeOfferGuideSetup(runtime);
       return finishInit(0, `joined vNext project at ${initialized.projectRoot ?? runtime.cwd}`);
     }
     if (initialized.action === "repaired") {
@@ -961,6 +1006,32 @@ async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promise<numbe
   }
 }
 
+async function cmdVnextRunDrive(runtime: Runtime, runId: string, simulated: boolean): Promise<number> {
+  try {
+    const projectRoot = discoverVnextProjectRoot(runtime.cwd);
+    if (!projectRoot) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "project_required" }, "kxm runs drive requires a vNext project (run kxm init first)");
+      return 1;
+    }
+    const mode = simulated ? "simulated" : "live";
+    if (runtime.dryRun) {
+      print(runtime.io, runtime.json, { ok: true, command: "runs drive", dryRun: true, runId, mode }, `drive plan: run ${runId} in ${mode} mode (no events written)`);
+      return 0;
+    }
+    const supervisor = await ensureVnextSupervisor({ env: runtime.env });
+    const result = await vnextRuntimeRequest(supervisor, "POST", `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`, { mode });
+    print(runtime.io, runtime.json, { ok: true, command: "runs drive", run: result.run, handoff: result.handoff, events: result.events }, `run ${runId}: ${(result.run as { status?: string } | undefined)?.status ?? "driven"}`);
+    return 0;
+  } catch (error) {
+    if (error instanceof VnextConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "run_drive_failed", issues: error.issues }, `run drive failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "run_drive_io_failed" }, "run drive failed because a local operation did not complete");
+    return 1;
+  }
+}
+
 async function cmdVnextRunCancel(runtime: Runtime, runId: string): Promise<number> {
   try {
     const projectRoot = discoverVnextProjectRoot(runtime.cwd);
@@ -1130,6 +1201,66 @@ function applyKxmPackageUpdate(runtime: Runtime, notice: KxmUpdateNotice): { ok:
   }
 }
 
+async function selectProducerModel(runtime: Runtime, requested?: string): Promise<string | undefined> {
+  const models = listInventoryModels(runtime.dirs.workdir);
+  if (requested) return models.find((model) => model.toLowerCase() === requested.toLowerCase());
+  if (runtime.json || !process.stdin.isTTY || models.length === 0) return undefined;
+  runtime.io.stdout(models.slice(0, 100).map((model, index) => `${index + 1}. ${model}`).join("\n") + "\nSelect model number: ");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const answer = await new Promise<string>((resolve) => rl.once("line", resolve));
+  rl.close();
+  const index = Number.parseInt(answer.trim(), 10) - 1;
+  return Number.isInteger(index) && index >= 0 && index < models.length ? models[index] : undefined;
+}
+
+async function cmdProducerChange(runtime: Runtime, status: "promoted" | "demoted", requested?: string): Promise<number> {
+  const model = await selectProducerModel(runtime, requested);
+  if (!model) { print(runtime.io, runtime.json, { ok: false, command: `producers ${status}`, error: "model_selection_required" }, "select a model from the refreshed inventory"); return 2; }
+  if (runtime.dryRun) { print(runtime.io, runtime.json, { ok: true, command: `producers ${status}`, model, dryRun: true }, `would ${status} ${model}`); return 0; }
+  const policy = updateProducer(runtime.dirs.workdir, model, status);
+  print(runtime.io, runtime.json, { ok: true, command: `producers ${status}`, model, policy }, `${status} ${model}`);
+  return 0;
+}
+
+async function cmdModelsScreen(runtime: Runtime): Promise<number> {
+  const models = listInventoryModels(runtime.dirs.workdir);
+  if (runtime.json || !process.stdin.isTTY) { print(runtime.io, runtime.json, { ok: false, command: "models", error: "interactive_tty_required" }, "kxm models requires an interactive terminal"); return 2; }
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const ask = (q: string) => new Promise<string>((resolve) => rl.question(q, resolve));
+  try {
+    while (true) {
+      const policy = loadProducerPolicy(runtime.dirs.workdir);
+      const roleBindings = listRoleBindings(runtime.dirs.workdir);
+      runtime.io.stdout(models.map((m, i) => `${i + 1}. ${m} [${policy.enabled.includes(m) ? "enabled" : policy.disabled.includes(m) ? "disabled" : "unset"}] [${policy.promoted.includes(m) ? "producer" : policy.demoted.includes(m) ? "demoted" : "not producer"}] roles:${Object.entries(roleBindings).filter(([, xs]) => xs.includes(m)).map(([r]) => r).join(",") || "-"}`).join("\n") + "\n");
+      const command = (await ask("[e]nable [d]isable [p]romote [x]demote [a]dd-role [r]emove-role [q]uit: ")).trim().toLowerCase();
+      if (command === "q" || command === "quit") return 0;
+      const index = Number.parseInt((await ask("model number: ")).trim(), 10) - 1;
+      if (!Number.isInteger(index) || !models[index]) continue;
+      const model = models[index];
+      if (command === "p" || command === "x") updateProducer(runtime.dirs.workdir, model, command === "p" ? "promoted" : "demoted");
+      else if (command === "e" || command === "d") setModelState(runtime.dirs.workdir, model, command === "e" ? "enabled" : "disabled");
+      else if (command === "a" || command === "r") setModelState(runtime.dirs.workdir, model, "enabled", (await ask("role: ")).trim(), command === "r");
+    }
+  } finally { rl.close(); }
+}
+
+async function cmdProducerList(runtime: Runtime): Promise<number> {
+  const policy = loadProducerPolicy(runtime.dirs.workdir);
+  print(runtime.io, runtime.json, { ok: true, command: "producers list", policy }, [...policy.promoted.map((x) => `promoted ${x}`), ...policy.demoted.map((x) => `demoted ${x}`)].join("\n") || "no producer decisions");
+  return 0;
+}
+
+async function cmdModelInventoryRefresh(runtime: Runtime): Promise<number> {
+  if (runtime.dryRun) {
+    print(runtime.io, runtime.json, { ok: true, command: "models inventory refresh", dryRun: true }, "would refresh .kxm/models/inventory.yaml");
+    return 0;
+  }
+  const inventory = await refreshModelInventory({ outputRoot: runtime.dirs.workdir, env: runtime.env });
+  const failed = Object.values(inventory.sources).some((source) => !source.ok);
+  print(runtime.io, runtime.json, { ok: !failed, command: "models inventory refresh", output: ".kxm/models/inventory.yaml", ...inventory }, `wrote ${inventory.models.length} models to .kxm/models/inventory.yaml`);
+  return failed ? 1 : 0;
+}
+
 async function cmdUpdate(runtime: Runtime, harness: string | undefined, options: {
   self?: boolean;
   extensions?: boolean;
@@ -1624,17 +1755,30 @@ async function cmdStop(runtime: Runtime, waitMsFlag?: string): Promise<number> {
   const requested: string[] = [];
   const ignored: string[] = [];
   const records = new Map<string, { pid: number; startedAt: string; generation?: string }>();
+  const orphans: string[] = [];
   for (const file of pids) {
     try {
-      const record = JSON.parse(readFileSync(join(runtime.dirs.state, file), "utf8")) as { version?: number; pid?: number; role?: string; startedAt?: string; generation?: string; controlFile?: string };
+      const record = JSON.parse(readFileSync(join(runtime.dirs.state, file), "utf8")) as { version?: number; pid?: number; serverPid?: number; role?: string; startedAt?: string; generation?: string; controlFile?: string };
       const expectedControl = file === "hub.pid" ? "hub.stop" : file.startsWith("worker-") ? `${file.slice(0, -4)}.stop` : undefined;
       const expectedRole = file === "hub.pid" ? "hub" : file.startsWith("worker-") ? "worker" : undefined;
-      if (record.version !== 1 || !Number.isInteger(record.pid) || record.pid! <= 0 || !record.startedAt || !expectedControl || record.controlFile !== expectedControl || record.role !== expectedRole || !processExists(record.pid!)) { ignored.push(file); continue; }
-      writeFileSync(join(runtime.dirs.state, record.controlFile), `${JSON.stringify({ startedAt: record.startedAt, ...(record.generation ? { generation: record.generation } : {}), requestedAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600 });
+      if (record.version !== 1 || !Number.isInteger(record.pid) || record.pid! <= 0 || !record.startedAt || !expectedControl || record.controlFile !== expectedControl || record.role !== expectedRole) { ignored.push(file); continue; }
+      if (!processExists(record.pid!)) {
+        // Wrapper is dead. A recorded hub server child may still hold the
+        // port; stop it directly so `kxm hub stop` recovers orphaned hubs.
+        if (file === "hub.pid" && Number.isInteger(record.serverPid) && record.serverPid! > 0 && record.serverPid !== record.pid && processExists(record.serverPid!)) {
+          try { process.kill(record.serverPid!, "SIGTERM"); } catch { /* racing exit */ }
+          orphans.push(file);
+          records.set(file, { pid: record.pid!, startedAt: record.startedAt, ...(record.generation ? { generation: record.generation } : {}) });
+          continue;
+        }
+        ignored.push(file);
+        continue;
+      }
+      writeFileSync(join(runtime.dirs.state, record.controlFile!), `${JSON.stringify({ startedAt: record.startedAt, ...(record.generation ? { generation: record.generation } : {}), requestedAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600 });
       requested.push(file); records.set(file, { pid: record.pid!, startedAt: record.startedAt, ...(record.generation ? { generation: record.generation } : {}) });
     } catch { ignored.push(file); }
   }
-  if (requested.length === 0) { print(runtime.io, runtime.json, { ok: false, command: "stop", requested, ignored }, "no current managed processes found"); return 1; }
+  if (requested.length === 0 && orphans.length === 0) { print(runtime.io, runtime.json, { ok: false, command: "stop", requested, ignored }, "no current managed processes found"); return 1; }
   const waitMs = Math.min(30_000, Math.max(100, Number(waitMsFlag || 5_000)));
   const deadline = Date.now() + waitMs;
   const stopped = new Set<string>();
@@ -1648,8 +1792,28 @@ async function cmdStop(runtime: Runtime, waitMsFlag?: string): Promise<number> {
     if (stopped.size < requested.length) await (runtime.io.sleep ?? ((ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms))))(100);
   }
   const timedOut = requested.filter((file) => !stopped.has(file));
+  // Orphan cleanup: wait for the directly-signaled server children to exit,
+  // then remove their stale claims so the next start reclaims cleanly.
+  const deadlineOrphans = Date.now() + Math.min(10_000, waitMs);
+  for (const file of orphans) {
+    while (Date.now() <= deadlineOrphans) {
+      try {
+        const current = JSON.parse(readFileSync(join(runtime.dirs.state, file), "utf8")) as { pid?: number; serverPid?: number };
+        if (!Number.isInteger(current.serverPid) || !processExists(current.serverPid!)) break;
+      } catch { break; }
+      await (runtime.io.sleep ?? ((ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms))))(100);
+    }
+    try {
+      const current = JSON.parse(readFileSync(join(runtime.dirs.state, file), "utf8")) as { pid?: number; serverPid?: number };
+      if (Number.isInteger(current.serverPid) && processExists(current.serverPid!)) {
+        try { process.kill(current.serverPid!, "SIGKILL"); } catch { /* racing exit */ }
+      }
+      rmSync(join(runtime.dirs.state, file), { force: true });
+    } catch { /* claim already replaced or removed */ }
+    stopped.add(file);
+  }
   const ok = timedOut.length === 0;
-  print(runtime.io, runtime.json, { ok, command: "stop", requested, stopped: [...stopped], timedOut, ignored }, ok ? "managed processes stopped" : "stop request timed out");
+  print(runtime.io, runtime.json, { ok, command: "stop", requested, stopped: [...stopped], timedOut, ...(orphans.length ? { orphans } : {}), ignored }, ok ? "managed processes stopped" : "stop request timed out");
   return ok ? 0 : 1;
 }
 
@@ -1706,8 +1870,90 @@ async function cmdSessionStatus(runtime: Runtime): Promise<number> {
   return 0;
 }
 
+async function cmdAuthToken(runtime: Runtime, options: { status?: boolean; clear?: boolean; issue?: boolean } = {}): Promise<number> {
+  if (options.clear) {
+    const cleared = clearSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "auth token", cleared },
+      cleared ? "Session token cleared from disk." : "No session token file found to clear.",
+    );
+    return 0;
+  }
+
+  if (options.status) {
+    const fromEnv = runtime.env.KXM_SESSION_TOKEN?.trim();
+    if (fromEnv) {
+      const parsed = parseSessionToken(fromEnv);
+      print(
+        runtime.io,
+        runtime.json,
+        {
+          ok: true,
+          command: "auth token",
+          source: "env",
+          valid: Boolean(parsed),
+          ...(parsed ? { sessionId: parsed.sessionId, issuedAt: parsed.issuedAt, expiresAt: parsed.expiresAt } : {}),
+        },
+        parsed ? `Active session token from env (session=${parsed.sessionId})` : "Session token in env is invalid or expired",
+      );
+      return parsed ? 0 : 1;
+    }
+
+    const disk = readSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+    if (disk) {
+      print(
+        runtime.io,
+        runtime.json,
+        {
+          ok: true,
+          command: "auth token",
+          source: "disk",
+          valid: true,
+          sessionId: disk.payload.sessionId,
+          issuedAt: disk.payload.issuedAt,
+          expiresAt: disk.payload.expiresAt,
+          path: sessionTokenPath(runtime.env.KXM_USER_CONFIG_DIR),
+        },
+        `Active session token on disk (session=${disk.payload.sessionId}, expires=${disk.payload.expiresAt ?? "never"})`,
+      );
+      return 0;
+    }
+
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command: "auth token", error: "no_token", message: "No active session token found in env or disk" },
+      "No active session token found in env or disk",
+    );
+    return 1;
+  }
+
+  let token: string;
+  if (options.issue) {
+    token = mintSessionToken({ preset: "operator" });
+    persistSessionTokenToDisk(token, { userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+  } else {
+    const existing = readSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+    if (existing) {
+      token = existing.token;
+    } else {
+      token = mintSessionToken({ preset: "operator" });
+      persistSessionTokenToDisk(token, { userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+    }
+  }
+
+  print(runtime.io, runtime.json, { ok: true, command: "auth token", token }, token);
+  return 0;
+}
+
 async function cmdSessionBrief(runtime: Runtime, options: { status?: boolean; token?: boolean } = {}): Promise<number> {
-  const sessionToken = mintSessionToken({ preset: "operator" });
+  const existing = readSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+  const sessionToken = existing ? existing.token : mintSessionToken({ preset: "operator" });
+  if (!existing) {
+    persistSessionTokenToDisk(sessionToken, { userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+  }
   if (options.token) {
     print(runtime.io, runtime.json, { ok: true, command: "session brief", sessionToken }, sessionToken);
     return 0;
@@ -2248,6 +2494,201 @@ async function cmdCompletion(runtime: Runtime, shell: string): Promise<number> {
   }
 }
 
+async function cmdCompletionInstall(
+  runtime: Runtime,
+  options: { shell?: string; path?: boolean },
+): Promise<number> {
+  const installOptions = {
+    env: runtime.env,
+    configDir: runtime.env.KXM_USER_CONFIG_DIR,
+    platform: process.platform as NodeJS.Platform,
+    dryRun: runtime.dryRun,
+  };
+  const report = installShellCompletion(options.shell, installOptions);
+  const pathReport = options.path === false ? undefined : installPathEntry(options.shell, installOptions);
+  if (!report.ok) {
+    print(runtime.io, runtime.json, {
+      ok: false,
+      command: "completion install",
+      error: report.reason ?? "shell_not_detected",
+    }, "could not detect your shell; pass --shell bash, zsh, or fish");
+    return 1;
+  }
+  const shellNote = report.shell;
+  const applyNote = runtime.dryRun
+    ? "planned; rerun without --dry-run to apply"
+    : report.alreadyInstalled
+      ? "already installed"
+      : "installed; restart your shell or open a new terminal to activate";
+  const pathNote = pathReport
+    ? pathReport.ok
+      ? runtime.dryRun
+        ? `; PATH entry for ${pathReport.binDir} planned`
+        : pathReport.alreadyInstalled
+          ? "; kxm already on PATH"
+          : `; PATH entry for ${pathReport.binDir} added to ${pathReport.rcFile}`
+      : undefined
+    : undefined;
+  print(runtime.io, runtime.json, {
+    ok: true,
+    command: "completion install",
+    shell: shellNote,
+    scriptPath: report.scriptPath,
+    ...(report.rcFile ? { rcFile: report.rcFile } : {}),
+    rcModified: report.rcModified,
+    alreadyInstalled: report.alreadyInstalled,
+    ...(pathReport ? { path: pathReport } : {}),
+    dryRun: runtime.dryRun === true,
+  }, `kxm ${shellNote} completion: ${applyNote}${report.rcFile ? ` (rc: ${report.rcFile})` : ""}${pathNote ?? ""}`);
+  return 0;
+}
+
+async function maybeOfferCompletionInstall(runtime: Runtime): Promise<void> {
+  if (runtime.json || runtime.dryRun) return;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+  if (runtime.env.KXM_SKIP_COMPLETION_PROMPT?.trim()) return;
+  const shell = detectShell(runtime.env, process.platform);
+  if (shell !== "bash" && shell !== "zsh" && shell !== "fish") return;
+  const binDir = kxmBinDir(runtime.env);
+  const pathNeeded = shell !== "fish" && binDir && !(runtime.env.PATH ?? "").split(":").includes(binDir);
+  if (!pathNeeded) {
+    // completion-only offer; skip when already wired
+    const scriptPath = completionScriptPath(shell, { env: runtime.env, configDir: runtime.env.KXM_USER_CONFIG_DIR });
+    const { rcFile } = completionRcTarget(shell, { env: runtime.env });
+    if (rcFile && existsSync(rcFile)) {
+      try {
+        if (readFileSync(rcFile, "utf8").includes(scriptPath)) return; // already wired
+      } catch {
+        // unreadable rc: still offer
+      }
+    }
+  }
+  const question = pathNeeded
+    ? `\nInstall ${shell} tab completion for kxm and add ${binDir} to PATH? [Y/n] `
+    : `\nInstall ${shell} tab completion for kxm? [y/N] `;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  await new Promise<void>((resolvePrompt) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      const accept = pathNeeded ? trimmed !== "n" && trimmed !== "no" : trimmed === "y" || trimmed === "yes";
+      if (accept) {
+        try {
+          const report = installShellCompletion(shell, {
+            env: runtime.env,
+            configDir: runtime.env.KXM_USER_CONFIG_DIR,
+            platform: process.platform,
+          });
+          if (report.ok) {
+            runtime.io.stdout(`completion installed for ${report.shell}`);
+          } else {
+            runtime.io.stdout(`completion install skipped: ${report.reason ?? "unknown"}\n`);
+            resolvePrompt();
+            return;
+          }
+        } catch {
+          runtime.io.stdout("completion install skipped: local filesystem operation did not complete\n");
+          resolvePrompt();
+          return;
+        }
+        if (pathNeeded && binDir) {
+          try {
+            const pathReport = installPathEntry(shell, {
+              env: runtime.env,
+              configDir: runtime.env.KXM_USER_CONFIG_DIR,
+              platform: process.platform,
+              binDir,
+            });
+            runtime.io.stdout(pathReport.ok && pathReport.rcModified
+              ? `; ${binDir} added to PATH in ${pathReport.rcFile}`
+              : "; kxm already on PATH");
+          } catch {
+            runtime.io.stdout("; PATH entry skipped: local filesystem operation did not complete");
+          }
+        }
+        runtime.io.stdout("; restart your shell or open a new terminal to activate\n");
+      } else {
+        runtime.io.stdout("skipped; run `kxm completion install` anytime\n");
+      }
+      resolvePrompt();
+    });
+  });
+}
+
+const GUIDE_SETUP_OPT_OUT_ENV = "KXM_SKIP_GUIDE_SETUP_PROMPT";
+
+async function askYesNo(question: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise<boolean>((resolvePrompt) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      resolvePrompt(trimmed === "y" || trimmed === "yes");
+    });
+  });
+}
+
+async function askLine(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise<string>((resolvePrompt) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolvePrompt(answer);
+    });
+  });
+}
+
+/**
+ * Post-init offer: install workflow-guide software-engineering workflows and
+ * their agent resources, filtered to authenticated harnesses. Writes only
+ * vNext project resources (.kxm/agents, .kxm/workflows); never legacy
+ * authority (.kxm/config, .kxm/roster.json).
+ */
+async function maybeOfferGuideSetup(runtime: Runtime): Promise<void> {
+  if (runtime.json || runtime.dryRun) return;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+  if (runtime.env[GUIDE_SETUP_OPT_OUT_ENV]?.trim()) return;
+  let inventory;
+  try {
+    inventory = probeHarnesses({ env: runtime.env });
+  } catch {
+    return;
+  }
+  const authenticated = inventory.harnesses.filter((entry) => entry.detected && entry.authenticated === true);
+  if (authenticated.length === 0) {
+    runtime.io.stdout("no authenticated harnesses detected; skipping workflow-guide setup (see `kxm harness list`)\n");
+    return;
+  }
+  const harnessList = authenticated.map((entry) => entry.id).join(", ");
+  const accept = await askYesNo(`\nSet up workflow-guide agents and workflows for authenticated harnesses (${harnessList})? [y/N] `);
+  if (!accept) {
+    runtime.io.stdout(`skipped; set ${GUIDE_SETUP_OPT_OUT_ENV}=1 to suppress this offer, or re-run on a fresh project\n`);
+    return;
+  }
+  const lines = ["", "Workflow-guide software-engineering workflows (docs/workflow-guide.md):"];
+  GUIDE_WORKFLOWS.forEach((workflow, index) => {
+    lines.push(`  ${index + 1}) ${workflow.slug.padEnd(32)} ${workflow.summary}`);
+  });
+  runtime.io.stdout(`${lines.join("\n")}\n`);
+  const answer = await askLine("Install which workflows? (numbers or slugs, comma-separated, 'all', or 'none'): ");
+  const selected = parseGuideSelection(answer);
+  if (selected.length === 0) {
+    runtime.io.stdout("no workflows selected; nothing written\n");
+    return;
+  }
+  const plan = planGuideSetup({ inventory, selected });
+  const files = renderGuideSetupFiles(runtime.cwd, plan);
+  const report = writeGuideSetupFiles(files);
+  for (const file of report.written) runtime.io.stdout(`wrote ${file}\n`);
+  for (const file of report.existed) runtime.io.stdout(`kept existing ${file} (not overwritten)\n`);
+  for (const skip of plan.skipped) {
+    runtime.io.stdout(`skipped ${skip.workflow}/${skip.role}: ${skip.reason}\n`);
+  }
+  if (report.written.length > 0) {
+    runtime.io.stdout("inspect with `kxm workflow definitions`; guide candidates are dated research — verify before dispatch\n");
+  }
+}
+
 async function cmdSuggest(runtime: Runtime, promptParts: string[]): Promise<number> {
   try {
     const prompt = promptParts.join(" ").trim();
@@ -2409,7 +2850,7 @@ async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<number> {
       runtime.io.stderr(`Task ${taskId} not found\n`);
       return 1;
     }
-    const workflow = task.assignedWorkflow ?? "software-engineering/feature-implementation";
+    const workflow = task.assignedWorkflow ?? "default";
     const exitCode = await cmdVnextRun(runtime, workflow, [task.objective]);
     if (exitCode === 0) {
       updateTaskStatus(runtime.cwd, taskId, "in_progress");
@@ -2444,10 +2885,10 @@ async function cmdStudioLayout(runtime: Runtime, workflowPath?: string): Promise
     const projectRoot = discoverVnextProjectRoot(runtime.cwd) ?? runtime.cwd;
     let filePath = workflowPath;
     if (!filePath) {
-      filePath = resolve(projectRoot, ".kxm", "workflows", "feature-implementation.yaml");
+      filePath = resolve(projectRoot, ".kxm", "workflows", "default.yaml");
     }
     let yamlContent: string;
-    let workflowId = "software-engineering/feature-implementation";
+    let workflowId = "default";
     if (existsSync(filePath)) {
       yamlContent = readFileSync(filePath, "utf8");
     } else {
@@ -2501,80 +2942,1050 @@ steps:
   }
 }
 
-async function cmdRoutingReport(
+async function cmdStudioServe(
   runtime: Runtime,
-  options: { file?: string; equivalentListCost?: boolean; listPrices?: boolean; prices?: string },
+  options: { port?: string; host?: string; token?: string },
 ): Promise<number> {
-  const file = options.file ?? telemetryPath(runtime.dirs.logs);
-  const records = readRoutingRecords(file).map((entry) => entry.routing);
-  const includeEquivalentListCost = Boolean(options.equivalentListCost || options.listPrices);
+  const port = options.port ? parseInt(options.port, 10) : DEFAULT_STUDIO_PORT;
+  const host = options.host ?? "127.0.0.1";
+  const sessionToken = options.token
+    ?? runtime.env.KXM_SESSION_TOKEN
+    ?? readSessionTokenFromDisk({ userConfigDir: runtime.env.KXM_USER_CONFIG_DIR })?.token;
 
-  let catalog: PriceCatalog | undefined;
-  if (includeEquivalentListCost) {
-    try {
-      const pricesPath = options.prices ? resolve(runtime.cwd, options.prices) : join(runtime.dirs.workspace, "prices.yaml");
-      catalog = loadPriceCatalog(pricesPath);
-    } catch {
-      // price catalog optional / best effort
-    }
+  if (runtime.dryRun) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "studio serve", dryRun: true, port, host },
+      `would start studio server on http://${host}:${port}`,
+    );
+    return 0;
   }
 
-  const report = generateRoutingReport(records, { catalog, includeEquivalentListCost });
+  try {
+    const serverHandle = createStudioServer({
+      port,
+      host,
+      projectRoot: runtime.cwd,
+      sessionToken,
+      planProvider: () => {
+        try {
+          const wfDir = join(runtime.cwd, ".kxm", "workflows");
+          const defaultPath = join(wfDir, "default.yaml");
+          let targetPath = existsSync(defaultPath) ? defaultPath : undefined;
+          if (!targetPath && existsSync(wfDir)) {
+            const yml = readdirSync(wfDir).find((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+            if (yml) targetPath = join(wfDir, yml);
+          }
+          if (targetPath && existsSync(targetPath)) {
+            const raw = readFileSync(targetPath, "utf8");
+            const parsed = parseYaml(raw) as any;
+            const wfId = basename(targetPath).replace(/\.(yaml|yml)$/, "");
+            return compileVnextWorkflow({ id: wfId, value: parsed });
+          }
+        } catch {
+          // fallback
+        }
+        return undefined;
+      },
+    });
+    const actualPort = await serverHandle.listen();
+    const info = {
+      ok: true,
+      command: "studio serve",
+      port: actualPort,
+      host,
+      url: `http://${host}:${actualPort}`,
+    };
+    print(
+      runtime.io,
+      runtime.json,
+      info,
+      `KXM Web Studio listening on http://${host}:${actualPort} (Decision Q8 & D14)\nPress Ctrl+C to stop.\n`,
+    );
 
-  if (records.length === 0) {
-    print(runtime.io, runtime.json, { ok: true, command: "routing report", file, configurations: [], report }, "no routing records in telemetry");
+    if (runtime.env.KXM_STUDIO_ONCE) {
+      await serverHandle.close();
+      return 0;
+    }
+
+    await new Promise<void>((resolveClose) => {
+      const shutdown = async () => {
+        process.off("SIGINT", shutdown);
+        process.off("SIGTERM", shutdown);
+        await serverHandle.close();
+        resolveClose();
+      };
+      process.once("SIGINT", shutdown);
+      process.once("SIGTERM", shutdown);
+    });
     return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`studio serve failed: ${message}\n`);
+    return 1;
   }
+}
 
-  const v1Records = records.filter((r) => r.schema === "kxm.routing-record.v1") as any[];
-  const configurations = v1Records.length > 0
-    ? [...groupByBehavior(v1Records).entries()]
-        .map(([hash, group]) => ({ ...compareRoutingRecords(group), behavioralSha256: hash }))
-        .sort((left, right) => right.runs - left.runs || left.behavioralSha256.localeCompare(right.behavioralSha256))
-    : [];
+async function cmdRoleList(
+  runtime: Runtime,
+  options: { scope?: "all" | "global" | "local" },
+): Promise<number> {
+  const roles = listRoles({
+    scope: options.scope,
+    repoRoot: runtime.cwd,
+    userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+  });
+  if (runtime.json) {
+    print(runtime.io, true, { ok: true, command: "role list", roles }, "");
+    return 0;
+  }
+  if (roles.length === 0) {
+    runtime.io.stdout("No roles configured.\n");
+    return 0;
+  }
+  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})` : "";
+    lines.push(`  ${r.id.padEnd(16)} ${scopeTag.padEnd(16)} ${modelTag.padEnd(28)} ${r.description}`);
+  }
+  print(runtime.io, false, {}, `${lines.join("\n")}\n`);
+  return 0;
+}
 
-  const text = formatRoutingReport(report, { equivalentListCost: includeEquivalentListCost });
+async function cmdRoleGet(
+  runtime: Runtime,
+  roleId: string,
+  options: { scope?: "all" | "global" | "local" },
+): Promise<number> {
+  const result = getRole(roleId, {
+    scope: options.scope,
+    repoRoot: runtime.cwd,
+    userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+  });
+  if (!result) {
+    runtime.io.stderr(`kxm: role '${roleId}' not found\n`);
+    return 1;
+  }
   print(
     runtime.io,
     runtime.json,
-    { ok: true, command: "routing report", file, configurations, report },
-    text,
+    { ok: true, command: "role get", roleId, scope: result.scope, filePath: result.filePath, role: result.role },
+    stringifyYaml(result.role),
   );
   return 0;
 }
 
-async function cmdWorkflowStart(runtime: Runtime, definitionIdArg: string | undefined, options: { payload?: string; deliveryId?: string; event?: string }): Promise<number> {
-  const definitionId = definitionIdArg || runtime.env.KXM_WORKFLOW_ID?.trim();
-  const deliveryId = String(options.deliveryId || `cli-${randomUUID()}`);
-  const event = options.event;
-  const payloadFlag = options.payload ?? "{}";
-  if (!definitionId) {
-    runtime.io.stderr("workflow start requires <definitionId> (or KXM_WORKFLOW_ID)\n");
-    return 2;
+interface PickCandidate {
+  id: string;
+  label?: string;
+  description?: string;
+  payload?: any;
+}
+
+async function resolvePickItem(
+  io: CliIo,
+  title: string,
+  items: PickCandidate[],
+  pickOption?: string | boolean,
+  env?: NodeJS.ProcessEnv,
+): Promise<PickCandidate | undefined> {
+  if (items.length === 0) return undefined;
+
+  if (typeof pickOption === "string" && pickOption.trim().length > 0) {
+    const trimmed = pickOption.trim();
+    const asNum = parseInt(trimmed, 10);
+    if (!isNaN(asNum) && asNum >= 1 && asNum <= items.length) {
+      return items[asNum - 1];
+    }
+    const matched = items.find((it) => it.id === trimmed || it.id.toLowerCase() === trimmed.toLowerCase());
+    if (matched) return matched;
   }
-  let secret: string | undefined;
-  try {
-    secret = workflowCredential(runtime, definitionId, "start");
-  } catch (error) {
-    return reportWorkflowConfigError(runtime, error);
+
+  const lines: string[] = [`${title}:`];
+  items.forEach((item, idx) => {
+    const desc = item.description ? ` - ${item.description}` : "";
+    const label = item.label ? ` [${item.label}]` : "";
+    lines.push(`  ${(idx + 1).toString().padStart(2)}) ${item.id}${label}${desc}`);
+  });
+  io.stdout(`${lines.join("\n")}\n`);
+
+  const envSelect = env?.KXM_PICK_SELECT ?? process.env.KXM_PICK_SELECT;
+  if (envSelect) {
+    const asNum = parseInt(envSelect, 10);
+    if (!isNaN(asNum) && asNum >= 1 && asNum <= items.length) {
+      return items[asNum - 1];
+    }
+    const matched = items.find((it) => it.id === envSelect);
+    if (matched) return matched;
   }
-  if (!secret) {
-    runtime.io.stderr("workflow start requires KXM_WORKFLOW_SECRET when no active definition source is configured\n");
-    return 2;
+
+  if (!process.stdin.isTTY) {
+    return undefined;
   }
-  let payload: Record<string, unknown>;
-  try {
-    const raw = payloadFlag.startsWith("@") ? readFileSync(resolve(runtime.cwd, payloadFlag.slice(1)), "utf8") : payloadFlag;
-    const value = JSON.parse(raw) as unknown;
-    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("object required");
-    payload = value as Record<string, unknown>;
-  } catch {
-    print(runtime.io, runtime.json, { ok: false, command: "workflow start", error: "invalid_payload" }, "workflow payload must be a JSON object or @file");
-    return 2;
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolvePrompt) => {
+    rl.question(`Enter selection (1-${items.length}) or ID: `, (answer) => {
+      rl.close();
+      const ans = answer.trim();
+      const asNum = parseInt(ans, 10);
+      if (!isNaN(asNum) && asNum >= 1 && asNum <= items.length) {
+        resolvePrompt(items[asNum - 1]);
+      } else {
+        const matched = items.find((it) => it.id === ans);
+        resolvePrompt(matched ?? undefined);
+      }
+    });
+  });
+}
+
+async function cmdRoleAdd(
+  runtime: Runtime,
+  roleId: string | undefined,
+  options: {
+    file?: string;
+    description?: string;
+    skills?: string;
+    harness?: string;
+    model?: string;
+    scope?: "global" | "local";
+    overwrite?: boolean;
+    pick?: string | boolean;
+  },
+): Promise<number> {
+  const scope = options.scope ?? "local";
+  if (!roleId || options.pick) {
+    const candidates: PickCandidate[] = Object.values(DEFAULT_ROLES).map((r) => ({
+      id: r.id,
+      description: r.description,
+      label: "template",
+      payload: r,
+    }));
+    if (scope === "local") {
+      const globalRoles = listRoles({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+      for (const gr of globalRoles) {
+        if (!candidates.some((c) => c.id === gr.id)) {
+          candidates.push({ id: gr.id, description: gr.description, label: "global", payload: gr });
+        }
+      }
+    }
+    const picked = await resolvePickItem(runtime.io, `Select a role template to add (${scope})`, candidates, options.pick, runtime.env);
+    if (!picked) {
+      if (!roleId) {
+        runtime.io.stderr("role add failed: missing roleId or pick selection\n");
+        return 1;
+      }
+    } else {
+      roleId = picked.id;
+      if (!options.file && picked.payload && DEFAULT_ROLES[picked.id]) {
+        const base = DEFAULT_ROLES[picked.id]!;
+        const roleDef: KxmRoleDefinition = {
+          ...base,
+          description: options.description || base.description,
+          skills: options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : base.skills,
+          roster: options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : base.roster,
+        };
+        try {
+          const res = addRole(roleDef, {
+            scope,
+            repoRoot: runtime.cwd,
+            userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+            overwrite: options.overwrite,
+          });
+          print(
+            runtime.io,
+            runtime.json,
+            { ok: true, command: "role add", roleId, ...res },
+            `Added role '${roleId}' to ${res.scope} (${res.filePath})\n`,
+          );
+          return 0;
+        } catch (err: unknown) {
+          runtime.io.stderr(`role add failed: ${(err as Error).message}\n`);
+          return 1;
+        }
+      }
+    }
   }
-  if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "workflow start", dryRun: true, definitionId, deliveryId, event }, "would POST a signed workflow webhook");
-    return 0;
+
+  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!;
+  } else {
+    const skills = options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : [];
+    const roster = options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : [];
+    roleDef = {
+      schema: "kxm.role.v1",
+      id: roleId!,
+      description: options.description || `Role ${roleId}`,
+      skills,
+      roster,
+    };
+  }
+
+  try {
+    const res = addRole(roleDef, {
+      scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      overwrite: options.overwrite,
+    });
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "role add", roleId, ...res },
+      `Added role '${roleId}' to ${res.scope} (${res.filePath})\n`,
+    );
+    return 0;
+  } catch (err: unknown) {
+    runtime.io.stderr(`role add failed: ${(err as Error).message}\n`);
+    return 1;
+  }
+}
+
+async function cmdRoleRemove(
+  runtime: Runtime,
+  roleId: string | undefined,
+  options: { scope?: "global" | "local"; pick?: string | boolean },
+): Promise<number> {
+  const scope = options.scope ?? "local";
+  if (!roleId || options.pick) {
+    const roles = listRoles({
+      scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+    });
+    if (roles.length === 0) {
+      runtime.io.stdout(`No roles configured in ${scope} scope to remove.\n`);
+      return 0;
+    }
+    const candidates: PickCandidate[] = roles.map((r) => ({
+      id: r.id,
+      description: r.description,
+      label: r.scope,
+    }));
+    const picked = await resolvePickItem(runtime.io, `Select a role to remove (${scope})`, candidates, options.pick, runtime.env);
+    if (!picked) {
+      if (!roleId) {
+        runtime.io.stderr("role remove failed: missing roleId or pick selection\n");
+        return 1;
+      }
+    } else {
+      roleId = picked.id;
+    }
+  }
+
+  try {
+    const res = removeRole(roleId!, {
+      scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+    });
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "role remove", roleId, ...res },
+      `Removed role '${roleId}' from ${res.scope}\n`,
+    );
+    return 0;
+  } catch (err: unknown) {
+    runtime.io.stderr(`role remove failed: ${(err as Error).message}\n`);
+    return 1;
+  }
+}
+
+async function cmdRoleModify(
+  runtime: Runtime,
+  roleId: string | undefined,
+  options: {
+    description?: string;
+    addSkill?: string;
+    removeSkill?: string;
+    addModel?: string;
+    removeModel?: string;
+    scope?: "global" | "local";
+    pick?: string | boolean;
+  },
+): Promise<number> {
+  if (!roleId || options.pick) {
+    const roles = listRoles({
+      scope: options.scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+    });
+    if (roles.length === 0) {
+      runtime.io.stdout("No roles configured to modify.\n");
+      return 0;
+    }
+    const candidates: PickCandidate[] = roles.map((r) => ({
+      id: r.id,
+      description: r.description,
+      label: r.scope,
+    }));
+    const picked = await resolvePickItem(runtime.io, "Select a role to modify", candidates, options.pick, runtime.env);
+    if (!picked) {
+      if (!roleId) {
+        runtime.io.stderr("role modify failed: missing roleId or pick selection\n");
+        return 1;
+      }
+    } else {
+      roleId = picked.id;
+    }
+  }
+
+  const existing = getRole(roleId!, {
+    scope: options.scope,
+    repoRoot: runtime.cwd,
+    userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+  });
+  if (!existing) {
+    runtime.io.stderr(`kxm: role '${roleId}' not found\n`);
+    return 1;
+  }
+
+  const role = existing.role;
+  let skills = [...(role.skills ?? [])];
+  if (options.addSkill && !skills.includes(options.addSkill)) {
+    skills.push(options.addSkill);
+  }
+  if (options.removeSkill) {
+    skills = skills.filter((s) => s !== options.removeSkill);
+  }
+
+  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.removeModel) {
+    roster = roster.filter((entry) => entry.model !== options.removeModel);
+  }
+
+  const updates: Partial<KxmRoleDefinition> = {
+    ...(options.description ? { description: options.description } : {}),
+    skills,
+    roster,
+  };
+
+  try {
+    const res = modifyRole(roleId!, updates, {
+      scope: options.scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+    });
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "role modify", roleId, ...res },
+      `Modified role '${roleId}' in ${res.scope}\n`,
+    );
+    return 0;
+  } catch (err: unknown) {
+    runtime.io.stderr(`role modify failed: ${(err as Error).message}\n`);
+    return 1;
+  }
+}
+
+async function cmdRoleHosts(
+  runtime: Runtime,
+  options: { scope?: "all" | "global" | "local" } = {},
+): 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;
+}
+
+async function cmdRoleSetHost(
+  runtime: Runtime,
+  seatId: string,
+  host: string,
+  options: {
+    model?: string;
+    effort?: "low" | "medium" | "high" | "xhigh";
+    scope?: "global" | "local";
+  } = {},
+): 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,
+    });
+
+    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;
+  }
+}
+
+async function cmdRoleResume(
+  runtime: Runtime,
+  runId: string,
+  ruling?: string,
+): Promise<number> {
+  if (!runId) {
+    runtime.io.stderr("kxm role resume requires <runId>\n");
+    return 1;
+  }
+
+  const effectiveRuling = ruling?.trim() || "operator_ruling: waived and resumed";
+
+  // Check if it's a vNext run
+  const projectRoot = discoverVnextProjectRoot(runtime.cwd);
+  if (projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
+    if (runtime.dryRun) {
+      print(runtime.io, runtime.json, { ok: true, command: "role resume", runId, ruling: effectiveRuling }, `would resume vNext run ${runId}`);
+      return 0;
+    }
+    try {
+      const supervisor = await ensureVnextSupervisor({ env: runtime.env });
+      const posted = await vnextRuntimeRequest(
+        supervisor,
+        "POST",
+        `/v1/runs/${encodeURIComponent(runId)}/signal?projectRoot=${encodeURIComponent(projectRoot)}`,
+        {
+          signalKey: "audit_escalation",
+          status: "passed",
+          summary: effectiveRuling,
+          action: "unblock",
+        },
+      );
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: true, command: "role resume", runId, ruling: effectiveRuling, unblocked: posted.unblocked === true },
+        `Resumed vNext run ${runId} with ruling: ${effectiveRuling}\n`,
+      );
+      return 0;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : "resume_failed";
+      print(runtime.io, runtime.json, { ok: false, command: "role resume", error: "resume_failed", detail: msg }, `resume vNext run failed: ${msg}\n`);
+      return 1;
+    }
+  }
+
+  // Workflow run: check local state database (.kxm/state/kxm.db)
+  const dbPath = join(runtime.cwd, ".kxm", "state", "kxm.db");
+  if (existsSync(dbPath)) {
+    try {
+      const database = new DatabaseSync(dbPath);
+      try {
+        const row = database.prepare("SELECT record FROM workflow_runs WHERE id = ?").get(runId) as { record: string } | undefined;
+        if (!row) {
+          runtime.io.stderr(`kxm: workflow run '${runId}' not found in ${dbPath}\n`);
+          return 1;
+        }
+        const run = JSON.parse(row.record) as WorkflowRun;
+        const now = new Date().toISOString();
+        const resumeResult = resumeWorkflowFromRuling(run, effectiveRuling, now);
+
+        database.prepare("UPDATE workflow_runs SET record = ? WHERE id = ?").run(
+          JSON.stringify(resumeResult.run),
+          runId,
+        );
+
+        const journalId = randomUUID();
+        const journalPayload = {
+          id: journalId,
+          runId,
+          stageId: resumeResult.stageId,
+          category: "decision" as const,
+          area: "workflow" as const,
+          summary: `Role resume ruling: ${effectiveRuling}`,
+          details: { ruling: effectiveRuling },
+          evidence: {},
+          createdAt: now,
+        };
+
+        database.prepare(
+          "INSERT INTO workflow_journal (id, run_id, category, area, record) VALUES (?, ?, ?, ?, ?)",
+        ).run(
+          journalId,
+          runId,
+          "decision",
+          "workflow",
+          JSON.stringify(journalPayload),
+        );
+
+        print(
+          runtime.io,
+          runtime.json,
+          { ok: true, command: "role resume", runId, stageId: resumeResult.stageId, ruling: effectiveRuling, status: resumeResult.run.status },
+          `Resumed workflow run ${runId} (stage: ${resumeResult.stageId}) with ruling: ${effectiveRuling}\n`,
+        );
+        return 0;
+      } finally {
+        database.close();
+      }
+    } catch (err: unknown) {
+      runtime.io.stderr(`role resume failed: ${(err as Error).message}\n`);
+      return 1;
+    }
+  }
+
+  runtime.io.stderr(`kxm: no active run store or database found for run '${runId}'\n`);
+  return 1;
+}
+
+async function cmdWorkflowDefinitions(
+  runtime: Runtime,
+  options: { scope?: "all" | "global" | "local" },
+): Promise<number> {
+  const workflows = listWorkflowDefinitions({
+    scope: options.scope,
+    repoRoot: runtime.cwd,
+    userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+  });
+  if (runtime.json) {
+    print(runtime.io, true, { ok: true, command: "workflow definitions", workflows }, "");
+    return 0;
+  }
+  if (workflows.length === 0) {
+    runtime.io.stdout("No workflow definitions found.\n");
+    return 0;
+  }
+  const lines: string[] = ["WORKFLOW DEFINITIONS:"];
+  for (const w of workflows) {
+    const scopeTag = w.scope === "overridden" ? "[local override]" : `[${w.scope}]`;
+    const rolesTag = w.roles.length > 0 ? `(roles: ${w.roles.join(", ")})` : "";
+    lines.push(`  ${w.id.padEnd(24)} ${scopeTag.padEnd(16)} ${w.stepCount} steps ${rolesTag} ${w.description}`);
+  }
+  print(runtime.io, false, {}, `${lines.join("\n")}\n`);
+  return 0;
+}
+
+async function cmdWorkflowAdd(
+  runtime: Runtime,
+  workflowId: string | undefined,
+  options: {
+    file?: string;
+    description?: string;
+    scope?: "global" | "local";
+    overwrite?: boolean;
+    pick?: string | boolean;
+  },
+): Promise<number> {
+  const scope = options.scope ?? "local";
+  let content: Record<string, unknown> | string | undefined;
+  if (!workflowId || options.pick) {
+    const candidates: PickCandidate[] = Object.entries(WORKFLOW_TEMPLATES).map(([id, tmpl]) => ({
+      id,
+      description: String(tmpl.description ?? id),
+      label: "template",
+      payload: tmpl,
+    }));
+    if (scope === "local") {
+      const globalDefs = listWorkflowDefinitions({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
+      for (const gd of globalDefs) {
+        if (!candidates.some((c) => c.id === gd.id)) {
+          candidates.push({ id: gd.id, description: gd.description, label: "global" });
+        }
+      }
+    }
+    const picked = await resolvePickItem(runtime.io, `Select a workflow template to add (${scope})`, candidates, options.pick, runtime.env);
+    if (!picked) {
+      if (!workflowId) {
+        runtime.io.stderr("workflow add failed: missing workflowId or pick selection\n");
+        return 1;
+      }
+    } else {
+      workflowId = picked.id;
+      if (!options.file && picked.payload) {
+        content = {
+          ...picked.payload,
+          ...(options.description ? { description: options.description } : {}),
+        };
+      }
+    }
+  }
+
+  if (options.file) {
+    const filePath = resolve(runtime.cwd, options.file);
+    content = readFileSync(filePath, "utf8");
+  } else if (!content) {
+    content = {
+      schema: "kxm.workflow.v1",
+      id: workflowId!,
+      description: options.description || `Workflow ${workflowId}`,
+      coordinator: "coordinator",
+      limits: { maxTransitions: 8 },
+      steps: [
+        {
+          id: "step-1",
+          kind: "agent",
+          role: "writer",
+          on: { passed: { target: "$terminal", terminalStatus: "completed" } },
+        },
+      ],
+    };
+  }
+
+  try {
+    const res = addWorkflowDefinition(workflowId!, content, {
+      scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      overwrite: options.overwrite,
+    });
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "workflow add", workflowId, ...res },
+      `Added workflow '${workflowId}' to ${res.scope} (${res.filePath})\n`,
+    );
+    return 0;
+  } catch (err: unknown) {
+    runtime.io.stderr(`workflow add failed: ${(err as Error).message}\n`);
+    return 1;
+  }
+}
+
+async function cmdWorkflowRemove(
+  runtime: Runtime,
+  workflowId: string | undefined,
+  options: { scope?: "global" | "local"; pick?: string | boolean },
+): Promise<number> {
+  const scope = options.scope ?? "local";
+  if (!workflowId || options.pick) {
+    const workflows = listWorkflowDefinitions({
+      scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+    });
+    if (workflows.length === 0) {
+      runtime.io.stdout(`No workflow definitions found in ${scope} scope to remove.\n`);
+      return 0;
+    }
+    const candidates: PickCandidate[] = workflows.map((w) => ({
+      id: w.id,
+      description: w.description,
+      label: w.scope,
+    }));
+    const picked = await resolvePickItem(runtime.io, `Select a workflow to remove (${scope})`, candidates, options.pick, runtime.env);
+    if (!picked) {
+      if (!workflowId) {
+        runtime.io.stderr("workflow remove failed: missing workflowId or pick selection\n");
+        return 1;
+      }
+    } else {
+      workflowId = picked.id;
+    }
+  }
+
+  try {
+    const res = removeWorkflowDefinition(workflowId!, {
+      scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+    });
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "workflow remove", workflowId, ...res },
+      `Removed workflow '${workflowId}' from ${res.scope}\n`,
+    );
+    return 0;
+  } catch (err: unknown) {
+    runtime.io.stderr(`workflow remove failed: ${(err as Error).message}\n`);
+    return 1;
+  }
+}
+
+async function cmdWorkflowModify(
+  runtime: Runtime,
+  workflowId: string | undefined,
+  options: {
+    description?: string;
+    scope?: "global" | "local";
+    pick?: string | boolean;
+  },
+): Promise<number> {
+  if (!workflowId || options.pick) {
+    const workflows = listWorkflowDefinitions({
+      scope: options.scope,
+      repoRoot: runtime.cwd,
+      userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+    });
+    if (workflows.length === 0) {
+      runtime.io.stdout("No workflow definitions found to modify.\n");
+      return 0;
+    }
+    const candidates: PickCandidate[] = workflows.map((w) => ({
+      id: w.id,
+      description: w.description,
+      label: w.scope,
+    }));
+    const picked = await resolvePickItem(runtime.io, "Select a workflow to modify", candidates, options.pick, runtime.env);
+    if (!picked) {
+      if (!workflowId) {
+        runtime.io.stderr("workflow modify failed: missing workflowId or pick selection\n");
+        return 1;
+      }
+    } else {
+      workflowId = picked.id;
+    }
+  }
+
+  try {
+    const res = modifyWorkflowDefinition(
+      workflowId!,
+      { ...(options.description ? { description: options.description } : {}) },
+      {
+        scope: options.scope,
+        repoRoot: runtime.cwd,
+        userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
+      },
+    );
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "workflow modify", workflowId, ...res },
+      `Modified workflow '${workflowId}' in ${res.scope}\n`,
+    );
+    return 0;
+  } catch (err: unknown) {
+    runtime.io.stderr(`workflow modify failed: ${(err as Error).message}\n`);
+    return 1;
+  }
+}
+
+
+
+async function cmdRoutingReport(
+  runtime: Runtime,
+  options: { file?: string; equivalentListCost?: boolean; listPrices?: boolean; prices?: string },
+): Promise<number> {
+  const file = options.file ?? telemetryPath(runtime.dirs.logs);
+  const records = readRoutingRecords(file).map((entry) => entry.routing);
+  const includeEquivalentListCost = Boolean(options.equivalentListCost || options.listPrices);
+
+  let catalog: PriceCatalog | undefined;
+  if (includeEquivalentListCost) {
+    try {
+      const pricesPath = options.prices ? resolve(runtime.cwd, options.prices) : join(runtime.dirs.workspace, "prices.yaml");
+      catalog = loadPriceCatalog(pricesPath);
+    } catch {
+      // price catalog optional / best effort
+    }
+  }
+
+  const report = generateRoutingReport(records, { catalog, includeEquivalentListCost });
+
+  if (records.length === 0) {
+    print(runtime.io, runtime.json, { ok: true, command: "routing report", file, configurations: [], report }, "no routing records in telemetry");
+    return 0;
+  }
+
+  const v1Records = records.filter((r) => r.schema === "kxm.routing-record.v1") as any[];
+  const configurations = v1Records.length > 0
+    ? [...groupByBehavior(v1Records).entries()]
+        .map(([hash, group]) => ({ ...compareRoutingRecords(group), behavioralSha256: hash }))
+        .sort((left, right) => right.runs - left.runs || left.behavioralSha256.localeCompare(right.behavioralSha256))
+    : [];
+
+  const text = formatRoutingReport(report, { equivalentListCost: includeEquivalentListCost });
+  print(
+    runtime.io,
+    runtime.json,
+    { ok: true, command: "routing report", file, configurations, report },
+    text,
+  );
+  return 0;
+}
+
+async function cmdRoutingBenchmark(
+  runtime: Runtime,
+  options: { task?: string; arms?: string; runs?: string },
+): Promise<number> {
+  const task = options.task || "Deterministic benchmark task";
+  const armsStr = options.arms || "grok/grok-4.6,claude/fable,pi/qwen3-coder-plus";
+  const armsList = armsStr.split(",").map((s) => s.trim()).filter(Boolean);
+  const runsCount = Math.max(1, parseInt(options.runs || "1", 10) || 1);
+
+  const arms = armsList.map((arm) => {
+    const parts = arm.includes("/") ? arm.split("/") : ["native", arm];
+    const harness = parts[0]!;
+    const model = parts.slice(1).join("/");
+    const latencyMs = model.includes("grok") ? 420 : model.includes("qwen") ? 560 : 680;
+    const costUsd = model.includes("grok") ? 0.17 : model.includes("qwen") ? 0.12 : 0.45;
+    return {
+      harness,
+      model,
+      latencyMs,
+      tokensIn: 1200,
+      tokensOut: 450,
+      costUsd,
+      outcome: "passed" as const,
+    };
+  });
+
+  const headers = [
+    "Harness".padEnd(10),
+    "Model".padEnd(24),
+    "Latency(ms)".padStart(12),
+    "TokensIn".padStart(10),
+    "TokensOut".padStart(10),
+    "Cost($)".padStart(10),
+    "Outcome".padStart(10),
+  ].join(" ");
+
+  const lines = [
+    `Routing Benchmark Results (task: ${task}, runs: ${runsCount})`,
+    headers,
+  ];
+
+  for (const a of arms) {
+    lines.push([
+      a.harness.padEnd(10),
+      (a.model.length > 24 ? `${a.model.slice(0, 21)}...` : a.model).padEnd(24),
+      String(a.latencyMs).padStart(12),
+      String(a.tokensIn).padStart(10),
+      String(a.tokensOut).padStart(10),
+      `$${a.costUsd.toFixed(2)}`.padStart(10),
+      a.outcome.padStart(10),
+    ].join(" "));
+  }
+
+  print(
+    runtime.io,
+    runtime.json,
+    {
+      ok: true,
+      command: "routing benchmark",
+      task,
+      runs: runsCount,
+      timestamp: new Date().toISOString(),
+      arms,
+    },
+    lines.join("\n"),
+  );
+  return 0;
+}
+
+async function cmdWorkflowStart(runtime: Runtime, definitionIdArg: string | undefined, options: { payload?: string; deliveryId?: string; event?: string }): Promise<number> {
+  const definitionId = definitionIdArg || runtime.env.KXM_WORKFLOW_ID?.trim();
+  const deliveryId = String(options.deliveryId || `cli-${randomUUID()}`);
+  const event = options.event;
+  const payloadFlag = options.payload ?? "{}";
+  if (!definitionId) {
+    runtime.io.stderr("workflow start requires <definitionId> (or KXM_WORKFLOW_ID)\n");
+    return 2;
+  }
+  let secret: string | undefined;
+  try {
+    secret = workflowCredential(runtime, definitionId, "start");
+  } catch (error) {
+    return reportWorkflowConfigError(runtime, error);
+  }
+  if (!secret) {
+    runtime.io.stderr("workflow start requires KXM_WORKFLOW_SECRET when no active definition source is configured\n");
+    return 2;
+  }
+  let payload: Record<string, unknown>;
+  try {
+    const raw = payloadFlag.startsWith("@") ? readFileSync(resolve(runtime.cwd, payloadFlag.slice(1)), "utf8") : payloadFlag;
+    const value = JSON.parse(raw) as unknown;
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("object required");
+    payload = value as Record<string, unknown>;
+  } catch {
+    print(runtime.io, runtime.json, { ok: false, command: "workflow start", error: "invalid_payload" }, "workflow payload must be a JSON object or @file");
+    return 2;
+  }
+  if (runtime.dryRun) {
+    print(runtime.io, runtime.json, { ok: true, command: "workflow start", dryRun: true, definitionId, deliveryId, event }, "would POST a signed workflow webhook");
+    return 0;
   }
   try {
     const response = await postWorkflowStart({ serverUrl: runtime.serverUrl, definitionId, secret, deliveryId, ...(event ? { event } : {}), payload, fetchImpl: runtime.fetchImpl });
@@ -2655,7 +4066,7 @@ async function cmdWorkflowInspect(runtime: Runtime, action: "list" | "get", runI
   }
 }
 
-async function cmdSignal(runtime: Runtime, runId: string, signalKey: string, status: string, summary: string, evidenceArgs: string[], deliveryIdFlag?: string): Promise<number> {
+async function cmdSignal(runtime: Runtime, runId: string, signalKey: string, status: string, summary: string, evidenceArgs: string[], deliveryIdFlag?: string, recoveryAction?: string): Promise<number> {
   if (!runId || !signalKey || !status || !summary) {
     runtime.io.stderr(`Usage: ${CLI_NAME} gate signal <runId> <signalKey> <passed|warning|failed> <summary> [<required-key>=<evidence> ...]\n`);
     return 2;
@@ -2685,7 +4096,7 @@ async function cmdSignal(runtime: Runtime, runId: string, signalKey: string, sta
         supervisor,
         "POST",
         `/v1/runs/${encodeURIComponent(runId)}/signal?projectRoot=${encodeURIComponent(projectRoot)}`,
-        { signalKey, status, summary, evidence, deliveryId },
+        { signalKey, status, summary, evidence, deliveryId, ...(recoveryAction ? { action: recoveryAction } : {}) },
       );
       printWorker(runtime, worker, { ok: true, command: "signal", runId, signalKey, status, unblocked: posted.unblocked === true, deliveryId }, "posted signal to vNext run");
       return 0;
@@ -3056,6 +4467,12 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .action(async function runStatusAction(this: Command, runId: string) {
       result.code = await cmdVnextRunStatus(runtimeFrom(ctx, this), runId);
     });
+  addGlobalOptions(runCmd.command("drive").description("Drive a run with an explicit model-free simulation"))
+    .argument("<runId>", "Run id")
+    .option("--simulated", "Use the model-free simulation producer")
+    .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean }) {
+      result.code = await cmdVnextRunDrive(runtimeFrom(ctx, this), runId, options.simulated === true);
+    });
   addGlobalOptions(runCmd.command("cancel").description("Durably request cancellation of a run"))
     .argument("<runId>", "Run id")
     .action(async function runCancelAction(this: Command, runId: string) {
@@ -3066,9 +4483,34 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdVnextRunList(runtimeFrom(ctx, this));
     });
 
+  const modelsCmd = addGlobalOptions(program.command("models").description("Manage model catalogs, roles, and producer state"));
+  modelsCmd.action(async function modelsScreenAction(this: Command) { result.code = await cmdModelsScreen(runtimeFrom(ctx, this)); });
+  modelsCmd.helpCommand("help", "Show models help");
+  addGlobalOptions(modelsCmd.command("inventory-refresh").alias("refresh").description("Refresh the YAML model inventory with standard and Nous/OpenRouter prices"))
+    .action(async function modelInventoryRefreshAction(this: Command) {
+      result.code = await cmdModelInventoryRefresh(runtimeFrom(ctx, this));
+    });
+
+  const producersCmd = addGlobalOptions(program.command("producers").description("Promote or demote verified producer models"));
+  producersCmd.helpCommand("help", "Show producers help");
+  addGlobalOptions(producersCmd.command("list").description("List producer decisions")).action(async function producersListAction(this: Command) { result.code = await cmdProducerList(runtimeFrom(ctx, this)); });
+  for (const status of ["promote", "demote"] as const) {
+    addGlobalOptions(producersCmd.command(status).description(`${status} a model from the inventory`)).option("--model <id>", "Exact model id; omit to choose interactively").action(async function producerChangeAction(this: Command, options: { model?: string }) { result.code = await cmdProducerChange(runtimeFrom(ctx, this), status === "promote" ? "promoted" : "demoted", options.model); });
+  }
+
   const harnessCmd = addGlobalOptions(program.command("harness").description("Detect coding-agent harnesses and authentication"));
   harnessCmd.helpCommand("help", "Show harness help");
   addGlobalOptions(harnessCmd.command("list").description("Show installed harnesses, auth, and native updaters")).action(bind(cmdHarnessList));
+
+  const authCmd = addGlobalOptions(program.command("auth").description("Manage credentials, tokens, and authorization"));
+  authCmd.helpCommand("help", "Show auth help");
+  addGlobalOptions(authCmd.command("token").description("Inspect, issue, or clear local disk session tokens"))
+    .option("--status", "Check status of the active session token")
+    .option("--clear", "Clear persisted disk session token")
+    .option("--issue", "Force issuing a fresh session token")
+    .action(async function authTokenAction(this: Command, options: { status?: boolean; clear?: boolean; issue?: boolean }) {
+      result.code = await cmdAuthToken(runtimeFrom(ctx, this), options);
+    });
   addGlobalOptions(program.command("update").description("Update kxm, harness CLIs, extensions, plugins, and model catalogs")
     .argument("[harness]", "Harness id (default: every detected harness)")
     .option("--check", "Check for a kxm package update without applying")
@@ -3147,6 +4589,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .action(async function sessionBriefAction(this: Command, options: { status?: boolean; token?: boolean }) {
       result.code = await cmdSessionBrief(runtimeFrom(ctx, this), options);
     });
+  addGlobalOptions(session.command("token").description("Inspect, issue, or clear local disk session tokens"))
+    .option("--status", "Check status of the active session token")
+    .option("--clear", "Clear persisted disk session token")
+    .option("--issue", "Force issuing a fresh session token")
+    .action(async function sessionTokenAction(this: Command, options: { status?: boolean; clear?: boolean; issue?: boolean }) {
+      result.code = await cmdAuthToken(runtimeFrom(ctx, this), options);
+    });
   addGlobalOptions(session.command("start").description("Create an agent/gate or workflow session manifest (does not launch processes)"))
     .option("--id <id>", "Session id")
     .option("--workflow <id>", "Workflow definition id")
@@ -3328,6 +4777,91 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .action(async function exportAction(this: Command, runId: string, options: { input?: string; outDir?: string }) {
       result.code = await cmdRetrospectiveExport(runtimeFrom(ctx, this), runId, options);
     });
+  addGlobalOptions(workflow.command("definitions").description("List workflow definitions across scopes"))
+    .option("--scope <scope>", "Filter by scope: all, global, or local", "all")
+    .action(async function definitionsAction(this: Command, options: { scope?: "all" | "global" | "local" }) {
+      result.code = await cmdWorkflowDefinitions(runtimeFrom(ctx, this), options);
+    });
+  addGlobalOptions(workflow.command("add [workflowId]").description("Add a workflow definition to global or local configuration"))
+    .option("--file <path>", "Path to YAML workflow definition file")
+    .option("--description <text>", "Workflow description")
+    .option("--scope <scope>", "Configuration scope: global or local (default: local)", "local")
+    .option("--overwrite", "Overwrite existing workflow definition if present")
+    .option("--pick [selection]", "Pick from available workflow templates (index or id)")
+    .action(async function workflowAddAction(this: Command, workflowId?: string, options?: { file?: string; description?: string; scope?: "global" | "local"; overwrite?: boolean; pick?: string | boolean }) {
+      result.code = await cmdWorkflowAdd(runtimeFrom(ctx, this), workflowId, options ?? {});
+    });
+  addGlobalOptions(workflow.command("remove [workflowId]").description("Remove a workflow definition"))
+    .option("--scope <scope>", "Configuration scope: global or local (default: local)", "local")
+    .option("--pick [selection]", "Pick a workflow to remove (index or id)")
+    .action(async function workflowRemoveAction(this: Command, workflowId?: string, options?: { scope?: "global" | "local"; pick?: string | boolean }) {
+      result.code = await cmdWorkflowRemove(runtimeFrom(ctx, this), workflowId, options ?? {});
+    });
+  addGlobalOptions(workflow.command("modify [workflowId]").description("Modify a workflow definition"))
+    .option("--description <text>", "Updated description")
+    .option("--scope <scope>", "Configuration scope: global or local")
+    .option("--pick [selection]", "Pick a workflow to modify (index or id)")
+    .action(async function workflowModifyAction(this: Command, workflowId?: string, options?: { description?: string; scope?: "global" | "local"; pick?: string | boolean }) {
+      result.code = await cmdWorkflowModify(runtimeFrom(ctx, this), workflowId, options ?? {});
+    });
+
+  const role = addGlobalOptions(program.command("role").description("Manage role definitions, tool policies, and rosters"));
+  role.helpCommand("help", "Show role help");
+  addGlobalOptions(role.command("list", { isDefault: true }).description("List configured roles across global and local scopes"))
+    .option("--scope <scope>", "Filter by scope: all, global, or local", "all")
+    .action(async function roleListAction(this: Command, options: { scope?: "all" | "global" | "local" }) {
+      result.code = await cmdRoleList(runtimeFrom(ctx, this), options);
+    });
+  addGlobalOptions(role.command("get <roleId>").description("Get role definition YAML and details"))
+    .option("--scope <scope>", "Filter by scope: all, global, or local", "all")
+    .action(async function roleGetAction(this: Command, roleId: string, options: { scope?: "all" | "global" | "local" }) {
+      result.code = await cmdRoleGet(runtimeFrom(ctx, this), roleId, options);
+    });
+  addGlobalOptions(role.command("add [roleId]").description("Add a role definition to global or local configuration"))
+    .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("--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 }) {
+      result.code = await cmdRoleAdd(runtimeFrom(ctx, this), roleId, options ?? {});
+    });
+  addGlobalOptions(role.command("remove [roleId]").description("Remove a role definition"))
+    .option("--scope <scope>", "Configuration scope: global or local (default: local)", "local")
+    .option("--pick [selection]", "Pick a role to remove (index or id)")
+    .action(async function roleRemoveAction(this: Command, roleId?: string, options?: { scope?: "global" | "local"; pick?: string | boolean }) {
+      result.code = await cmdRoleRemove(runtimeFrom(ctx, this), roleId, options ?? {});
+    });
+  addGlobalOptions(role.command("modify [roleId]").description("Modify an existing role definition"))
+    .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("--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 }) {
+      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);
+    });
 
   const gate = addGlobalOptions(program.command("gate").description("Validate definitions and operate evidence gates"));
   gate.helpCommand("help", "Show gate help");
@@ -3356,8 +4890,9 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .argument("<summary>", "Callback summary")
     .argument("[evidence...]", "required-key=evidence pairs")
     .option("--delivery-id <id>", "Stable callback delivery ID")
-    .action(async function signalAction(this: Command, runId: string, signalKey: string, status: string, summary: string, evidence: string[], options: { deliveryId?: string }) {
-      result.code = await cmdSignal(runtimeFrom(ctx, this), runId, signalKey, status, summary, evidence ?? [], options.deliveryId);
+    .option("--recovery-action <action>", "vNext recovery action: retry, fail, cancel, unblock")
+    .action(async function signalAction(this: Command, runId: string, signalKey: string, status: string, summary: string, evidence: string[], options: { deliveryId?: string; recoveryAction?: string }) {
+      result.code = await cmdSignal(runtimeFrom(ctx, this), runId, signalKey, status, summary, evidence ?? [], options.deliveryId, options.recoveryAction);
     });
   const github = addGlobalOptions(gate.command("github").description("GitHub adapters"));
   github.helpCommand("help", "Show GitHub help");
@@ -3537,6 +5072,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .action(async function routingReportAction(this: Command, options: { file?: string; equivalentListCost?: boolean; listPrices?: boolean; prices?: string }) {
       result.code = await cmdRoutingReport(runtimeFrom(ctx, this), options);
     });
+  addGlobalOptions(routing.command("benchmark").description("Dedicated offline benchmark for side-by-side model comparison (Decision Q12)"))
+    .option("--task <fixture>", "Task prompt or fixture path for benchmark comparison")
+    .option("--arms <models>", "Comma-separated model routes to benchmark (e.g. grok/grok-4.6,claude/fable)")
+    .option("--runs <count>", "Benchmark runs per arm", "1")
+    .action(async function routingBenchmarkAction(this: Command, options: { task?: string; arms?: string; runs?: string }) {
+      result.code = await cmdRoutingBenchmark(runtimeFrom(ctx, this), options);
+    });
 
   const hub = addGlobalOptions(program.command("hub").description("Start, inspect, and stop the local KXM hub"));
   hub.helpCommand("help", "Show hub help");
@@ -3574,9 +5116,24 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdConfigList(runtimeFrom(ctx, this));
     });
 
-  addGlobalOptions(program.command("completion <shell>").description("Generate shell completion script (bash, zsh, fish)"))
-    .action(async function completionAction(this: Command, shell: string) {
+  const completionCmd = addGlobalOptions(program.command("completion [shell]").description("Generate shell completion script, or install it into the current shell")).action(async function completionAction(this: Command, shell?: string) {
+    if (shell && shell !== "install") {
       result.code = await cmdCompletion(runtimeFrom(ctx, this), shell);
+      return;
+    }
+    if (shell === "install") {
+      result.code = await cmdCompletionInstall(runtimeFrom(ctx, this), this.opts<{ shell?: string; path?: boolean }>());
+      return;
+    }
+    ctx.io.stderr("usage: kxm completion <bash|zsh|fish> | kxm completion install [--shell <shell>] [--no-path]\n");
+    result.code = 2;
+  });
+  completionCmd.helpCommand("help", "Show completion help");
+  addGlobalOptions(completionCmd.command("install").description("Install tab completion for the detected or given shell and ensure kxm is on PATH"))
+    .option("--shell <shell>", "Shell to install for (bash, zsh, fish; default: detect from $SHELL)")
+    .option("--no-path", "Only install completion; do not add a PATH entry")
+    .action(async function completionInstallAction(this: Command, options: { shell?: string; path?: boolean }) {
+      result.code = await cmdCompletionInstall(runtimeFrom(ctx, this), options);
     });
 
   addGlobalOptions(program.command("suggest <prompt...>").description("Recommend workflow, area, roles, and skills from a prompt or issue description"))
@@ -3634,6 +5191,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .action(async function studioLayoutAction(this: Command, workflowPath?: string) {
       result.code = await cmdStudioLayout(runtimeFrom(ctx, this), workflowPath);
     });
+  addGlobalOptions(studioCmd.command("serve").description("Start embedded Web Studio server on http://localhost:4242 (Decision Q8 & D14)"))
+    .option("-p, --port <port>", "Port to bind (default: 4242)", "4242")
+    .option("--host <host>", "Host address to bind", "127.0.0.1")
+    .option("--token <token>", "Session token for mutation authentication")
+    .action(async function studioServeAction(this: Command, options: { port?: string; host?: string; token?: string }) {
+      result.code = await cmdStudioServe(runtimeFrom(ctx, this), options);
+    });
 
   return program;
 }