@kontextmind/kxm 0.7.0 → 0.7.10

package/plugins/kxm/src/cli.ts

@@ -1,3800 +1,180 @@
-import { spawn, spawnSync } from "node:child_process";
-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 { createInterface } from "node:readline";
+/**
+ * KontextMind (KXM) CLI Program and Entrypoint.
+ *
+ * Provides Commander command definitions and argument routing for:
+ * - Workflow modes & context explain (`kxm explain`)
+ * - Multiplexed remote SSH operations (`kxm ssh`)
+ * - Role & workflow governance (`kxm role`, `kxm workflow`, `kxm gate`, `kxm signal`)
+ * - Task & goal management (`kxm goal`, `kxm task`, `kxm suggest`, `kxm studio`)
+ * - Knowledge, skills, and memory (`kxm context`, `kxm skills`, `kxm memory`)
+ * - vNext runtime & initialization (`kxm init`, `kxm migrate`, `kxm trust`, `kxm run`, `kxm harness`)
+ * - Hub, workers, and dashboard (`kxm hub`, `kxm worker`, `kxm dash`, `kxm session`, `kxm auth`)
+ * - System, update, and configuration (`kxm update`, `kxm config`, `kxm completion`, `kxm improve`)
+ */
+
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command, CommanderError } from "commander";
-import {
-  createMemoryNote,
-  formatMemoryBriefText,
-  generateMemoryBrief,
-  syncHarnessMemory,
-  type MemoryScope,
-} from "./memory.ts";
-import { createBackup, restoreBackup } from "./database.ts";
-import { verifyArtifactExists } from "./artifacts-exist.ts";
-import { canonicalWorkflowEvidenceKey, parseWorkflowDefinitions } from "./workflow.ts";
-import { postWorkflowSignal, watchGithubChecks } from "./github-watch.ts";
-import { buildRetrospective, writeRetrospective } from "./retrospective.ts";
-import { redactSecrets } from "./redact.ts";
-import { SkillLifecycle, type SkillEvaluationKind, type SkillState } from "./skills.ts";
-import { writeCompiledWiki } from "./wiki.ts";
-import { agentWorker, gateWorker, workerResult, type Worker, type WorkerOutcome } from "./envelope.ts";
-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";
-import { formatSessionBriefText, loadSessionBrief, loadSessionBriefAsync, type SessionHubStatus } from "./session-work.ts";
-import {
-  HUB_BINDING_SCHEMA,
-  HubBindingError,
-  hubBindingFile,
-  probeHubHealth,
-  readHubBinding,
-  removeHubBinding,
-  validateHubUrl,
-  writeHubBinding,
-  type HubHealth,
-} from "./hub-binding.ts";
-import {
-  fetchLatestKxmVersion,
-  kxmReleaseAssetName,
-  noticeFromVersions,
-  planKxmPackageUpdate,
-  readInstalledKxmVersion,
-  readUpdateCache,
-  verifyReleaseAssetDigest,
-  writeUpdateCache,
-  KxmUpdateConfigError,
-  type KxmPackageUpdateStep,
-  type KxmUpdateConfig,
-  type KxmUpdateNotice,
-} from "./kxm-update.ts";
-import { loadKxmUpdateConfig } from "./kxm-update-config.ts";
-import {
-  classifyInstallRoot,
-  resolveInstallKind,
-  type InstallKindReport,
-  type InstallProbe,
-} from "./kxm-install-kind.ts";
-import { VnextConfigError, discoverVnextProjectRoot, type VnextInitializationPlan } from "./vnext-config.ts";
-import { vnextUserStateRoot } from "./vnext-bindings.ts";
-import { initializeVnextProject } from "./vnext-init.ts";
-import { applyVnextMigration, planVnextMigration, verifyVnextMigration } from "./vnext-migrate.ts";
-import { diffVnextProjectAgainstRevision, formatVnextPermissionDiff } from "./vnext-permission.ts";
-import { readVnextLocalBindings } from "./vnext-bindings.ts";
-import { loadVnextProject } from "./vnext-config.ts";
-import {
-  ensureVnextSupervisor,
-  vnextRuntimeRequest,
-  vnextSupervisorStatus,
-} from "./vnext-runtime-supervisor.ts";
-import { vnextRuntimePaths } from "./vnext-runtime-store.ts";
-import {
-  formatHarnessInventory,
-  formatHarnessUpdate,
-  planHarnessUpdate,
-  probeHarnesses,
-  runHarnessUpdate,
-  type HarnessUpdateScope,
-} from "./vnext-harness.ts";
-import type { WorkflowEvidenceInput, WorkflowJournalEntry, WorkflowRun } from "./workflow.ts";
-import { HubClient } from "./client.ts";
-import {
-  AGENT_COMMANDS_MAP,
-  clearSessionTokenFromDisk,
-  enforceToolPolicy,
-  mintSessionToken,
-  parseSessionToken,
-  persistSessionTokenToDisk,
-  readSessionTokenFromDisk,
-  sessionTokenPath,
-} from "./commands.ts";
-import {
-  loadKxmConfig,
-  setKxmConfigValue,
-  getKxmConfigValue,
-  formatKxmConfig,
-} from "./config.ts";
-import { generateShellCompletion, type SupportedShell } from "./autocomplete.ts";
-import { suggestWorkflowAndRoles } from "./suggest.ts";
-import {
-  createGoal,
-  createTask,
-  listGoals,
-  listTasks,
-  getTask,
-  updateTaskStatus,
-  syncTaskWithTracker,
-  type TaskStatus,
-  type TrackerType,
-} from "./task-manager.ts";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-import { compileVnextWorkflow } from "./vnext-engine-compile.ts";
-import { generateStudioLayout, createStudioServer, DEFAULT_STUDIO_PORT } from "./studio-layout.ts";
-import {
-  listRoles,
-  getRole,
-  addRole,
-  removeRole,
-  modifyRole,
-  DEFAULT_ROLES,
-  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;
-  stdout: string;
-  stderr: string;
-  error?: Error;
-}
-
-export interface CliIo {
-  stdout: (text: string) => void;
-  stderr: (text: string) => void;
-  fetchImpl?: typeof fetch;
-  now?: () => number;
-  sleep?: (ms: number) => Promise<void>;
-  spawnHub?: (extraEnv: NodeJS.ProcessEnv) => number | Promise<number>;
-  spawnWorker?: (extraEnv: NodeJS.ProcessEnv) => number | Promise<number>;
-  installProbe?: Partial<InstallProbe>;
-  spawnSync?: (command: string, args: readonly string[]) => CliSpawnResult;
-}
-
-const CLI_NAME = "kxm";
-const repoRoot = resolve(fileURLToPath(new URL("../../../", import.meta.url)));
-const USAGE_ERROR_CODES = new Set([
-  "commander.help",
-  "commander.helpDisplayed",
-  "commander.unknownCommand",
-  "commander.unknownOption",
-  "commander.missingArgument",
-  "commander.missingMandatoryOptionValue",
-  "commander.invalidArgument",
-  "commander.excessArguments",
-  "commander.variadicArgNotLast",
-  "commander.invalidOptionArgument",
-  "commander.optionMissingArgument",
-]);
-
-interface CliContext {
-  env: NodeJS.ProcessEnv;
-  io: CliIo;
-  cwd: string;
-}
-
-interface GlobalOpts {
-  json?: boolean;
-  dryRun?: boolean;
-  workspace?: string;
-}
-
-interface Runtime extends CliContext, Required<Pick<GlobalOpts, "json" | "dryRun">> {
-  workspaceFlag?: string;
-  dirs: ReturnType<typeof workspaceDirs>;
-  serverUrl: string;
-  boundHubUrl?: string;
-  fetchImpl: typeof fetch;
-}
-
-function spawnScript(scriptName: string, extraEnv: NodeJS.ProcessEnv = {}): Promise<number> {
-  return new Promise((resolveExit) => {
-    const child = spawn(process.execPath, [join(repoRoot, "scripts", scriptName)], {
-      stdio: "inherit",
-      env: { ...process.env, ...extraEnv },
-    });
-    child.once("error", () => resolveExit(1));
-    child.once("exit", (code) => resolveExit(code ?? 1));
-  });
-}
-
-function parseEvidencePairs(values: string[]): WorkflowEvidenceInput {
-  const evidence = new Map<string, string>();
-  for (const value of values) {
-    const separator = value.indexOf("=");
-    if (separator <= 0 || separator === value.length - 1) {
-      throw new Error("evidence must use <required-key>=<evidence> syntax");
-    }
-    const requirement = canonicalWorkflowEvidenceKey(value.slice(0, separator));
-    const proof = value.slice(separator + 1).trim();
-    if (!requirement || !proof) throw new Error("evidence must use <required-key>=<evidence> syntax");
-    if (evidence.has(requirement)) throw new Error(`duplicate normalized evidence key: ${requirement}`);
-    evidence.set(requirement, proof);
-  }
-  return Object.fromEntries(evidence);
-}
-
-const CLI_RESULT_SCHEMA = "kxm.cli-result.v1";
-
-/** Every CLI payload carries a schema tag; payloads that already declare one
- * (worker envelopes) keep theirs. `ok:false` goes to stderr in both modes so
- * agents can split results from errors without parsing. */
-function print(io: CliIo, jsonMode: boolean, payload: object, text: string): void {
-  const tagged = { schema: CLI_RESULT_SCHEMA, ...payload } as Record<string, unknown>;
-  const safePayload = JSON.stringify(redactCliValue(tagged));
-  const line = jsonMode ? `${safePayload}\n` : `${redactSecrets(text)}\n`;
-  if (tagged.ok === false) io.stderr(line);
-  else io.stdout(line);
-}
-
-function printWorker(
-  runtime: Runtime,
-  worker: Worker,
-  payload: Record<string, unknown> & { command: string; ok: boolean },
-  text: string,
-  outcome?: WorkerOutcome,
-): void {
-  const sessionId = runtime.env.KXM_SESSION_ID?.trim();
-  const envelope = workerResult(worker, {
-    ...payload,
-    summary: text,
-    ...(outcome ? { outcome } : {}),
-    ...(sessionId ? { sessionId } : {}),
-  });
-  if (!runtime.dryRun) {
-    try {
-      const safeEnvelope = redactCliValue(envelope) as typeof envelope;
-      appendTelemetry(telemetryPath(runtime.dirs.logs), makeTelemetryEvent({
-        envelope: safeEnvelope,
-        ...(sessionId ? { sessionId } : {}),
-        host: hostMode(runtime),
-        target: inferImprovementTarget({
-          ...(worker.project ? { project: worker.project } : {}),
-          env: runtime.env,
-        }),
-      }));
-    } catch {
-      // Telemetry must never fail the operator command.
-    }
-  }
-  print(runtime.io, runtime.json, envelope, text);
-}
-
-function hostMode(runtime: Runtime): "local" | "hub" {
-  try {
-    const hostname = new URL(runtime.serverUrl).hostname;
-    if (hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1") return "local";
-  } catch {
-    // Default local when the hub URL is not a URL.
-  }
-  return "hub";
-}
-
-function gateOf(runtime: Runtime, name: string): ReturnType<typeof gateWorker> {
-  const project = runtime.env.KXM_PROJECT?.trim();
-  return gateWorker({ name, ...(project ? { project } : {}) });
-}
-
-function redactCliValue(value: unknown, field = ""): unknown {
-  if (typeof value === "string") {
-    // These fields are public audit digests, not credentials. Preserve
-    // them only by exact field name and shape; every other 64-hex value keeps
-    // the conservative generic redaction behavior.
-    if (
-      (field === "requestSha256"
-        || field === "replySha256"
-        || field === "behavioralSha256"
-        || field === "workflowDefinitionSha256"
-        || field === "verifierConfigSha256"
-        || field === "rolePromptSha256"
-        || field === "contentSha256"
-        || field === "configRevision"
-        || field === "baseSha256"
-        || field === "localSha256"
-        || field === "targetSha256"
-        || field === "sourceTemplateRevision"
-        || field === "targetTemplateRevision"
-        || field === "sourceDigest"
-        || field === "decisionDigest"
-        || field === "receiptSha256"
-        || field === "sha256"
-        || field === "valueSha256"
-        || field === "baseRevision"
-        || field === "candidateRevision"
-        || field === "baseValueSha256"
-        || field === "candidateValueSha256")
-      && /^(?:sha256:)?[a-f0-9]{64}$/.test(value)
-    ) return value;
-    return redactSecrets(value);
-  }
-  if (Array.isArray(value)) return value.map((candidate) => redactCliValue(candidate));
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>)
-        .map(([key, candidate]) => [key, redactCliValue(candidate, key)]),
-    );
-  }
-  return value;
-}
-
-function workspaceDirs(cwd: string, workspaceFlag: string | undefined, env: NodeJS.ProcessEnv) {
-  const workdir = resolve(env.KXM_WORKDIR?.trim() || cwd);
-  const workspace = resolve(workdir, workspaceFlag || env.KXM_WORKSPACE_DIR?.trim() || ".kxm");
-  const derive = workspaceFlag !== undefined;
-  return {
-    workdir,
-    workspace,
-    config: derive ? join(workspace, "config") : resolve(workdir, env.KXM_CONFIG_DIR?.trim() || join(workspace, "config")),
-    logs: derive ? join(workspace, "logs") : resolve(workdir, env.KXM_LOGS_DIR?.trim() || join(workspace, "logs")),
-    assets: derive ? join(workspace, "assets") : resolve(workdir, env.KXM_ASSETS_DIR?.trim() || join(workspace, "assets")),
-    state: derive ? join(workspace, "state") : resolve(workdir, env.KXM_STATE_DIR?.trim() || join(workspace, "state")),
-  };
-}
-
-function maskEnvName(name: string): boolean {
-  return /TOKEN|SECRET|KEY|PASSWORD/i.test(name);
-}
-
-function redactConfiguredValues(text: string, env: NodeJS.ProcessEnv): string {
-  let safe = text;
-  for (const [name, value] of Object.entries(env)) {
-    if (!maskEnvName(name) || !value || value.length < 4) continue;
-    safe = safe.replaceAll(value, "[redacted]");
-  }
-  const trailingNewline = safe.endsWith("\n") ? "\n" : "";
-  try {
-    const parsed = JSON.parse(safe) as unknown;
-    return `${JSON.stringify(redactCliValue(parsed))}${trailingNewline}`;
-  } catch {
-    // Human-readable output and diagnostics keep conservative generic
-    // redaction, including opaque 64-hex values.
-  }
-  return redactSecrets(safe);
-}
-
-function processExists(pid: number): boolean {
-  try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; }
-}
-
-/** Authenticated hub POST for context operations. The CLI operates as the
- * control plane: the administrative token scopes one project per request. */
-export async function hubContextPost(input: {
-  serverUrl: string;
-  path: string;
-  body: Record<string, unknown>;
-  authToken?: string;
-  fetchImpl: typeof fetch;
-}): Promise<{ ok: boolean; status: number; body: unknown }> {
-  const response = await input.fetchImpl(`${input.serverUrl.replace(/\/$/, "")}${input.path}`, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      ...(input.authToken ? { authorization: `Bearer ${input.authToken}` } : {}),
-    },
-    body: JSON.stringify(input.body),
-  });
-  const text = redactSecrets((await response.text()).slice(0, 64_000));
-  let body: unknown = text;
-  try {
-    body = JSON.parse(text);
-  } catch {
-    // Keep text for diagnostics without treating it as a secret.
-  }
-  return { ok: response.ok, status: response.status, body };
-}
-
-async function hubGet(url: string, fetchImpl: typeof fetch): Promise<{ ok: boolean; status: number; body: unknown }> {
-  try {
-    const response = await fetchImpl(url);
-    const text = redactSecrets((await response.text()).slice(0, 8_000));
-    let body: unknown = text;
-    try {
-      body = JSON.parse(text);
-    } catch {
-      // Keep text for diagnostics without treating it as a secret.
-    }
-    return { ok: response.ok, status: response.status, body };
-  } catch {
-    return { ok: false, status: 0, body: { error: "hub_unreachable" } };
-  }
-}
-
-function localWorkflowSnapshot(dataPath: string, runId?: string): { runs: WorkflowRun[]; journal: WorkflowJournalEntry[] } {
-  if (!existsSync(dataPath)) throw new Error("state_database_not_found");
-  const database = new DatabaseSync(dataPath, { readOnly: true });
-  try {
-    const rows = runId
-      ? database.prepare("SELECT record FROM workflow_runs WHERE id = ?").all(runId) as Array<{ record: string }>
-      : database.prepare("SELECT record FROM workflow_runs ORDER BY rowid DESC LIMIT 200").all() as Array<{ record: string }>;
-    const runs = rows.map((row) => JSON.parse(row.record) as WorkflowRun);
-    const journal = runId
-      ? (database.prepare("SELECT record FROM workflow_journal WHERE run_id = ? ORDER BY rowid").all(runId) as Array<{ record: string }>).map((row) => JSON.parse(row.record) as WorkflowJournalEntry)
-      : [];
-    return { runs, journal };
-  } finally { database.close(); }
-}
-
-async function postWorkflowStart(input: { serverUrl: string; definitionId: string; secret: string; deliveryId: string; event?: string; payload: Record<string, unknown>; fetchImpl: typeof fetch }): Promise<{ status: number; runId?: string; duplicate?: boolean }> {
-  const payload = input.event && input.payload.event === undefined ? { ...input.payload, event: input.event } : input.payload;
-  const body = JSON.stringify(payload);
-  const signature = `sha256=${createHmac("sha256", input.secret).update(body).digest("hex")}`;
-  const response = await input.fetchImpl(`${input.serverUrl.replace(/\/$/, "")}/v1/webhooks/${encodeURIComponent(input.definitionId)}`, {
-    method: "POST",
-    headers: { "content-type": "application/json", "x-hub-signature-256": signature, "x-kxm-delivery-id": input.deliveryId, ...(input.event ? { "x-github-event": input.event } : {}) },
-    body,
-  });
-  const responseText = (await response.text()).slice(0, 8_000);
-  let parsed: { run?: { id?: string }; duplicate?: boolean } = {};
-  try { parsed = JSON.parse(responseText) as typeof parsed; } catch { /* bounded adapter error */ }
-  if (!response.ok) throw new Error(`workflow_start_http_${response.status}`);
-  return { status: response.status, ...(parsed.run?.id ? { runId: parsed.run.id } : {}), duplicate: parsed.duplicate === true };
-}
-
-async function postWorkflowDegradation(input: {
-  serverUrl: string;
-  authToken: string;
-  runId: string;
-  stageId: string;
-  requirementKey: string;
-  reason: string;
-  fetchImpl: typeof fetch;
-}): Promise<{ status: number; duplicate: boolean; approvalId?: string }> {
-  const response = await input.fetchImpl(
-    `${input.serverUrl.replace(/\/$/, "")}/v1/workflows/${encodeURIComponent(input.runId)}/degradations`,
-    {
-      method: "POST",
-      headers: {
-        authorization: `Bearer ${input.authToken}`,
-        "content-type": "application/json",
-      },
-      body: JSON.stringify({
-        stageId: input.stageId,
-        requirementKey: input.requirementKey,
-        reason: input.reason,
-      }),
-    },
-  );
-  const text = (await response.text()).slice(0, 8_000);
-  let parsed: { duplicate?: boolean; approval?: { id?: string } } = {};
-  try { parsed = JSON.parse(text) as typeof parsed; } catch { /* bounded adapter error */ }
-  if (!response.ok) throw new Error(`workflow_degradation_http_${response.status}`);
-  return {
-    status: response.status,
-    duplicate: parsed.duplicate === true,
-    ...(parsed.approval?.id ? { approvalId: parsed.approval.id } : {}),
-  };
-}
-
-function addGlobalOptions(command: Command): Command {
-  return command
-    .option("--json", "Print machine-readable JSON")
-    .option("--dry-run", "Plan without making changes")
-    .option("--workspace <dir>", "Workspace directory");
-}
-
-function runtimeFrom(ctx: CliContext, command: Command): Runtime {
-  const opts = command.optsWithGlobals() as GlobalOpts;
-  const envServerUrl = ctx.env.KXM_SERVER_URL?.trim();
-  let boundHubUrl: string | undefined;
-  try {
-    boundHubUrl = readHubBinding(ctx.env)?.url;
-  } catch (error) {
-    if (error instanceof HubBindingError) {
-      ctx.io.stderr(`kxm: ignoring malformed hub binding at ${hubBindingFile(ctx.env)}; run kxm hub bind <url> again\n`);
-    } else {
-      throw error;
-    }
-  }
-  return {
-    ...ctx,
-    json: Boolean(opts.json),
-    dryRun: Boolean(opts.dryRun),
-    ...(opts.workspace === undefined ? {} : { workspaceFlag: opts.workspace }),
-    dirs: workspaceDirs(ctx.cwd, opts.workspace, ctx.env),
-    serverUrl: envServerUrl || boundHubUrl || "http://127.0.0.1:7331",
-    ...(boundHubUrl ? { boundHubUrl } : {}),
-    fetchImpl: ctx.io.fetchImpl ?? fetch,
-  };
-}
-
-function workspaceEnv(runtime: Runtime): NodeJS.ProcessEnv {
-  return {
-    KXM_WORKDIR: runtime.dirs.workdir,
-    KXM_WORKSPACE_DIR: runtime.dirs.workspace,
-    KXM_CONFIG_DIR: runtime.dirs.config,
-    KXM_LOGS_DIR: runtime.dirs.logs,
-    KXM_ASSETS_DIR: runtime.dirs.assets,
-    KXM_STATE_DIR: runtime.dirs.state,
-  };
-}
-
-function activeWorkflowDefinition(runtime: Runtime, definitionId: string) {
-  const inline = runtime.env.KXM_WEBHOOK_WORKFLOWS?.trim();
-  const file = runtime.env.KXM_WEBHOOK_WORKFLOWS_FILE?.trim();
-  if (inline && file) {
-    throw new Error("configure only one of KXM_WEBHOOK_WORKFLOWS or KXM_WEBHOOK_WORKFLOWS_FILE");
-  }
-  if (!inline && !file) return undefined;
-  let raw: string;
-  if (file) {
-    try {
-      raw = readFileSync(resolve(runtime.cwd, file), "utf8");
-    } catch {
-      throw new Error("workflow definition file is unavailable");
-    }
-  } else {
-    raw = inline!;
-  }
-  const definition = parseWorkflowDefinitions(raw, runtime.env).find((candidate) => candidate.id === definitionId);
-  if (!definition) throw new Error(`workflow definition not found: ${definitionId}`);
-  return definition;
-}
-
-function workflowCredential(runtime: Runtime, definitionId: string, kind: "start" | "signal"): string | undefined {
-  const definition = activeWorkflowDefinition(runtime, definitionId);
-  if (definition) return kind === "start" ? definition.secret : definition.signalSecret ?? definition.secret;
-  return kind === "start"
-    ? runtime.env.KXM_WORKFLOW_SECRET?.trim()
-    : runtime.env.KXM_WORKFLOW_SIGNAL_SECRET?.trim();
-}
-
-function reportWorkflowConfigError(runtime: Runtime, error: unknown): number {
-  const message = error instanceof Error ? redactSecrets(error.message) : "invalid workflow configuration";
-  runtime.io.stderr(`${message}\n`);
-  return 2;
-}
-
-function initPlanPayload(plan: VnextInitializationPlan): Record<string, unknown> {
-  return {
-    mode: plan.mode,
-    inspectedFrom: plan.inspectedFrom,
-    ...(plan.projectRoot ? { projectRoot: plan.projectRoot } : {}),
-    ...(plan.legacyRoot ? { legacyRoot: plan.legacyRoot } : {}),
-    changesRequired: plan.changesRequired,
-    legacyInputs: plan.legacyInputs,
-    issues: plan.issues,
-    ...(plan.configRevision ? { configRevision: plan.configRevision } : {}),
-  };
-}
-
-function explicitRepositoryBindings(values: readonly string[]): Readonly<Record<string, string>> {
-  const result: Record<string, string> = Object.create(null) as Record<string, string>;
-  for (const value of values) {
-    const separator = value.indexOf("=");
-    const repositoryId = separator < 0 ? "" : value.slice(0, separator).trim();
-    const path = separator < 0 ? "" : value.slice(separator + 1).trim();
-    if (!repositoryId || !path) {
-      throw new VnextConfigError([{
-        phase: "discovery",
-        code: "repository_binding_argument_invalid",
-        file: "--repository",
-        message: "repository bindings must use <id=absolute-path>",
-      }]);
-    }
-    if (Object.hasOwn(result, repositoryId)) {
-      throw new VnextConfigError([{
-        phase: "discovery",
-        code: "repository_binding_argument_duplicate",
-        file: "--repository",
-        message: `repository binding ${repositoryId} was supplied more than once`,
-      }]);
-    }
-    result[repositoryId] = path;
-  }
-  return result;
-}
-
-async function cmdVnextInit(runtime: Runtime, options: { name?: string; projectId?: string; repository?: string[] }): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "init",
-      error: "workspace_option_unsupported",
-    }, "kxm init discovers the authoritative Git root from the current directory; --workspace is not supported");
-    return 2;
-  }
-  try {
-    const initialized = initializeVnextProject(runtime.cwd, {
-      ...(options.name?.trim() ? { projectName: options.name.trim() } : {}),
-      ...(options.projectId?.trim() ? { projectId: options.projectId.trim() } : {}),
-      repositoryBindings: explicitRepositoryBindings(options.repository ?? []),
-      localStateRoot: vnextUserStateRoot({ env: runtime.env }),
-      dryRun: runtime.dryRun,
-    });
-    const payload = {
-      ok: initialized.action !== "planned" || runtime.dryRun,
-      command: "init",
-      action: initialized.action,
-      ...initPlanPayload(initialized.plan),
-      files: initialized.files,
-      ...(initialized.configRevision ? { configRevision: initialized.configRevision } : {}),
-      ...(initialized.localBindingFile ? { localBindingFile: initialized.localBindingFile } : {}),
-      ...(initialized.bindingsChanged === undefined ? {} : { bindingsChanged: initialized.bindingsChanged }),
-      ...(initialized.repairPlan === undefined ? {} : { repairPlan: initialized.repairPlan }),
-      ...(initialized.resumePending === undefined ? {} : { resumePending: initialized.resumePending }),
-      ...(initialized.transactionKind === undefined ? {} : { transactionKind: initialized.transactionKind }),
-      plannedOnly: initialized.action === "planned",
-    };
-    const finishInit = (code: number, text: string): number => {
-      print(runtime.io, runtime.json, payload, text);
-      return code;
-    };
-    if (initialized.action === "created") {
-      return finishInit(0, `initialized vNext project at ${initialized.projectRoot ?? runtime.cwd}`);
-    }
-    if (initialized.action === "joined") {
-      return finishInit(0, `joined vNext project at ${initialized.projectRoot ?? runtime.cwd}`);
-    }
-    if (initialized.action === "repaired") {
-      return finishInit(0, `repaired vNext project at ${initialized.projectRoot ?? runtime.cwd}`);
-    }
-    if (initialized.action === "resumed") {
-      return finishInit(0, `resumed vNext ${initialized.transactionKind ?? "initialization"} at ${initialized.projectRoot ?? runtime.cwd}`);
-    }
-    if (initialized.action === "validated") {
-      return finishInit(0, `validated vNext project at ${initialized.projectRoot ?? runtime.cwd}`);
-    }
-    if (runtime.dryRun) {
-      return finishInit(0, `init plan: ${initialized.plan.mode}`);
-    }
-    const next = initialized.plan.mode === "migrate"
-      ? "legacy state requires reviewed migration; conversion is not available in this implementation slice"
-      : initialized.repairPlan?.issues.length
-        ? "managed-template repair is blocked by conflicts or authority changes; local files were preserved"
-        : "partial or provenance-free vNext state requires explicit repair; no files were overwritten";
-    return finishInit(1, next);
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, {
-        ok: false,
-        command: "init",
-        error: "vnext_initialization_failed",
-        issues: error.issues,
-      }, `vNext initialization failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "init",
-      error: "vnext_initialization_io_failed",
-    }, "vNext initialization failed because a local filesystem operation did not complete");
-    return 1;
-  }
-}
-
-async function cmdVnextMigratePlan(runtime: Runtime): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "migrate plan",
-      error: "workspace_option_unsupported",
-    }, "kxm migrate discovers the authoritative Git root from the current directory; --workspace is not supported");
-    return 2;
-  }
-  try {
-    const result = planVnextMigration(runtime.cwd, {});
-    const ambiguities = (result.plan.ambiguities as Array<{ key: string; message: string }> | undefined) ?? [];
-    const unmapped = (result.plan.unmapped as unknown[] | undefined) ?? [];
-    const payload = {
-      ok: result.plan.canApply === true,
-      command: "migrate plan",
-      plan: result.plan,
-      plannedOnly: result.plan.canApply !== true,
-    };
-    if (result.plan.canApply === true) {
-      print(runtime.io, runtime.json, payload, `migration plan: ${ambiguities.length} ambiguities, ${unmapped.length} preserved fields; ready to apply`);
-      return 0;
-    }
-    print(
-      runtime.io,
-      runtime.json,
-      payload,
-      `migration plan requires ${ambiguities.length} reviewed decision(s):\n${ambiguities.map((candidate) => `  - ${candidate.key}: ${candidate.message}`).join("\n")}`,
-    );
-    return 1;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "migrate plan", error: "migration_plan_failed", issues: error.issues }, `migration plan failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "migrate plan", error: "migration_plan_io_failed" }, "migration plan failed because a local filesystem operation did not complete");
-    return 1;
-  }
-}
-
-async function cmdVnextMigrateApply(runtime: Runtime, options: { decisions?: string; projectId?: string; name?: string }): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "migrate apply",
-      error: "workspace_option_unsupported",
-    }, "kxm migrate discovers the authoritative Git root from the current directory; --workspace is not supported");
-    return 2;
-  }
-  try {
-    const result = applyVnextMigration(runtime.cwd, {
-      ...(options.decisions?.trim() ? { decisionsFile: options.decisions.trim() } : {}),
-      ...(options.projectId?.trim() ? { projectId: options.projectId.trim() } : {}),
-      ...(options.name?.trim() ? { projectName: options.name.trim() } : {}),
-      localStateRoot: vnextUserStateRoot({ env: runtime.env }),
-      dryRun: runtime.dryRun,
-    });
-    const payload = {
-      ok: result.action !== "planned" || (runtime.dryRun === true && result.plan?.canApply === true),
-      command: "migrate apply",
-      action: result.action,
-      files: result.files,
-      ...(result.configRevision ? { configRevision: result.configRevision } : {}),
-      ...(result.receiptPath ? { receiptPath: result.receiptPath } : {}),
-      plannedOnly: result.action === "planned",
-    };
-    if (result.action === "applied") {
-      print(runtime.io, runtime.json, payload, `migration applied: ${result.files.length} resources installed, receipt at ${result.receiptPath ?? ""}`);
-      return 0;
-    }
-    if (result.action === "already-migrated") {
-      print(runtime.io, runtime.json, payload, "migration receipt already exists; nothing to apply");
-      return 0;
-    }
-    if (runtime.dryRun && result.plan?.canApply === true) {
-      print(runtime.io, runtime.json, payload, `migration dry run: ${result.files.length} resources would be installed`);
-      return 0;
-    }
-    const ambiguities = (result.plan?.ambiguities as Array<{ key: string; message: string }> | undefined) ?? [];
-    print(
-      runtime.io,
-      runtime.json,
-      { ...payload, plan: result.plan },
-      `migration blocked by ${ambiguities.length} unresolved decision(s); review 'kxm migrate plan' and pass --decisions:\n${ambiguities.map((candidate) => `  - ${candidate.key}: ${candidate.message}`).join("\n")}`,
-    );
-    return 1;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "migrate apply", error: "migration_apply_failed", issues: error.issues }, `migration apply failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "migrate apply", error: "migration_apply_io_failed" }, "migration apply failed because a local filesystem operation did not complete");
-    return 1;
-  }
-}
-
-async function cmdVnextMigrateVerify(runtime: Runtime): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "migrate verify",
-      error: "workspace_option_unsupported",
-    }, "kxm migrate discovers the authoritative Git root from the current directory; --workspace is not supported");
-    return 2;
-  }
-  let result: ReturnType<typeof verifyVnextMigration>;
-  try {
-    result = verifyVnextMigration(runtime.cwd, {});
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "migrate verify", error: "migration_verify_failed", issues: error.issues }, `migration verification failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "migrate verify", error: "migration_verify_io_failed" }, "migration verification failed because a local filesystem operation did not complete");
-    return 1;
-  }
-  const payload = {
-    ok: result.ok,
-    command: "migrate verify",
-    ...(result.configRevision ? { configRevision: result.configRevision } : {}),
-    issues: result.issues,
-  };
-  if (result.ok) {
-    print(runtime.io, runtime.json, payload, `migration receipt verified: legacy sources unchanged, target bundle matches ${result.configRevision ?? ""}`);
-    return 0;
-  }
-  print(runtime.io, runtime.json, payload, `migration verification failed:\n${result.issues.map((issue) => `  - ${issue.file}: ${issue.code}: ${issue.message}`).join("\n")}`);
-  return 1;
-}
-
-async function cmdBackup(runtime: Runtime, options: { out?: string }): Promise<number> {
-  try {
-    const { manifest, outDir } = createBackup({
-      projectRoot: runtime.cwd,
-      ...(options.out ? { outDir: resolve(runtime.cwd, options.out) } : {}),
-    });
-    const payload = {
-      ok: true,
-      command: "backup",
-      backupId: manifest.backupId,
-      outDir,
-      manifest,
-    };
-    const summary = [
-      `Created SQLite backup with ${manifest.stores.length} store(s):`,
-      ...manifest.stores.map((s) => `  - ${s.storeId}: ${s.sourcePath} -> ${s.backupFile} (schema v${s.schemaVersion}, ${s.bytes} bytes, sha256 ${s.sha256.slice(0, 12)}...)`),
-      `Manifest: ${join(outDir, "manifest.json")}`,
-    ].join("\n");
-    print(runtime.io, runtime.json, payload, summary);
-    return 0;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "backup", error: "backup_failed", issues: error.issues }, `backup failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "backup", error: "backup_failed", message: error instanceof Error ? error.message : String(error) }, `backup failed: ${error instanceof Error ? error.message : String(error)}`);
-    return 1;
-  }
-}
-
-async function cmdRestore(runtime: Runtime, manifestArg: string): Promise<number> {
-  try {
-    const result = restoreBackup(resolve(runtime.cwd, manifestArg), {
-      projectRoot: runtime.cwd,
-    });
-    const payload = {
-      ok: true,
-      command: "restore",
-      backupId: result.backupId,
-      manifestPath: result.manifestPath,
-      restoredStores: result.restoredStores,
-    };
-    const summary = [
-      `Restored ${result.restoredStores.length} SQLite store(s) from ${result.manifestPath}:`,
-      ...result.restoredStores.map((s) => `  - ${s.storeId}: -> ${s.sourcePath} (schema v${s.schemaVersion}, integrity ${s.integrity})`),
-    ].join("\n");
-    print(runtime.io, runtime.json, payload, summary);
-    return 0;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "restore", error: "restore_failed", issues: error.issues }, `restore failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "restore", error: "restore_failed", message: error instanceof Error ? error.message : String(error) }, `restore failed: ${error instanceof Error ? error.message : String(error)}`);
-    return 1;
-  }
-}
-
-async function cmdVnextTrust(runtime: Runtime, check: boolean, options: { base?: string }): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: check ? "trust check" : "trust diff",
-      error: "workspace_option_unsupported",
-    }, "kxm trust discovers the authoritative Git root from the current directory; --workspace is not supported");
-    return 2;
-  }
-  const command = check ? "trust check" : "trust diff";
-  try {
-    // Host-local member bindings travel with the user state, not Git; pass
-    // them so member repositories diff with the same identities on both sides.
-    const projectRoot = discoverVnextProjectRoot(runtime.cwd) ?? runtime.cwd;
-    const bindings = readVnextLocalBindings(projectRoot, { stateRoot: vnextUserStateRoot({ env: runtime.env }) });
-    const diff = diffVnextProjectAgainstRevision(projectRoot, options.base?.trim() || "HEAD", {
-      repositoryBindings: bindings?.repositories ?? {},
-    });
-    const payload = {
-      ok: !check || !diff.requiresReview,
-      command,
-      baseRevision: diff.baseRevision,
-      candidateRevision: diff.candidateRevision,
-      requiresReview: diff.requiresReview,
-      expansions: diff.expansions.length,
-      narrowings: diff.narrowings.length,
-      neutralChanges: diff.neutralChanges.length,
-      changes: diff.changes,
-    };
-    const text = formatVnextPermissionDiff(diff);
-    if (check && diff.requiresReview) {
-      print(runtime.io, runtime.json, payload, `${text}\ntrust check failed: review every expansion above before merging`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, payload, text);
-    return 0;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command, error: "trust_diff_failed", issues: error.issues }, `permission diff failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command, error: "trust_diff_io_failed" }, "permission diff failed because a local filesystem or Git operation did not complete");
-    return 1;
-  }
-}
-
-/** No step engine exists yet: `kxm run` durably accepts a run and stops.
- * The run engine replaces this notice with real progress. */
-const RUN_ENGINE_PHASE = "pre-3a";
-const RUN_ENGINE_NOTICE = "runs remain created until the run engine lands; no steps execute yet";
-
-async function cmdVnextRun(runtime: Runtime, workflow: string | undefined, promptParts: string[]): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "run",
-      error: "workspace_option_unsupported",
-    }, "kxm run discovers the authoritative project from the current directory; --workspace is not supported");
-    return 2;
-  }
-  if (!workflow) {
-    print(runtime.io, runtime.json, { ok: false, command: "run", error: "workflow_required" }, "usage: kxm run <workflow> [prompt]");
-    return 2;
-  }
-  try {
-    const projectRoot = discoverVnextProjectRoot(runtime.cwd);
-    if (!projectRoot) {
-      print(runtime.io, runtime.json, { ok: false, command: "run", error: "project_required" }, "kxm run requires a vNext project (run kxm init first)");
-      return 1;
-    }
-    const bundle = loadVnextProject(projectRoot, {});
-    if (!bundle.workflows.has(workflow)) {
-      print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_workflow_unknown", workflow }, `workflow ${workflow} does not exist in this project`);
-      return 1;
-    }
-    if (runtime.dryRun) {
-      print(runtime.io, runtime.json, {
-        ok: true,
-        command: "run",
-        dryRun: true,
-        projectRoot,
-        workflowId: workflow,
-        configRevision: bundle.configRevision,
-      }, `run plan: workflow ${workflow} at ${bundle.configRevision.slice(0, 19)}… (no run created)`);
-      return 0;
-    }
-    const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-    const prompt = promptParts.join(" ").trim();
-    const acceptance = await vnextRuntimeRequest(supervisor, "POST", "/v1/runs", {
-      projectRoot,
-      workflowId: workflow,
-      prompt,
-    });
-    const run = acceptance.run as { runId: string; homeRuntimeId: string; status: string; configRevision: string };
-    print(runtime.io, runtime.json, {
-      ok: true,
-      command: "run",
-      phase: RUN_ENGINE_PHASE,
-      idempotent: acceptance.idempotent === true,
-      run,
-      supervisor: { runtimeId: supervisor.runtimeId, port: supervisor.port, started: supervisor.started },
-    }, `run ${run.status}: ${run.runId} (home ${run.homeRuntimeId.slice(0, 12)}…, config ${run.configRevision.slice(0, 19)}…)\n${RUN_ENGINE_NOTICE}`);
-    return 0;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_failed", issues: error.issues }, `run failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_io_failed" }, "run failed because a local operation did not complete");
-    return 1;
-  }
-}
-
-async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promise<number> {
-  try {
-    const projectRoot = discoverVnextProjectRoot(runtime.cwd);
-    if (!projectRoot) {
-      print(runtime.io, runtime.json, { ok: false, command: "runs status", error: "project_required" }, "kxm runs status requires a vNext project (run kxm init first)");
-      return 1;
-    }
-    const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-    const result = await vnextRuntimeRequest(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
-    const run = result.run as { runId: string; status: string; workflowId: string; configRevision: string; updatedAt: string };
-    print(runtime.io, runtime.json, { ok: true, command: "runs status", run }, `run ${run.runId}: ${run.status} (workflow ${run.workflowId}, updated ${run.updatedAt})`);
-    return 0;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "runs status", error: "run_status_failed", issues: error.issues }, `run status failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "runs status", error: "run_status_io_failed" }, "run status failed because a local operation did not complete");
-    return 1;
-  }
-}
-
-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);
-    if (!projectRoot) {
-      print(runtime.io, runtime.json, { ok: false, command: "runs cancel", error: "project_required" }, "kxm runs cancel requires a vNext project (run kxm init first)");
-      return 1;
-    }
-    if (runtime.dryRun) {
-      print(runtime.io, runtime.json, { ok: true, command: "runs cancel", dryRun: true, runId }, `cancel plan: run ${runId} (no events written)`);
-      return 0;
-    }
-    const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-    const result = await vnextRuntimeRequest(supervisor, "POST", `/v1/runs/${encodeURIComponent(runId)}/cancel?projectRoot=${encodeURIComponent(projectRoot)}`, {});
-    const run = result.run as { runId: string; status: string };
-    print(runtime.io, runtime.json, {
-      ok: true,
-      command: "runs cancel",
-      idempotent: result.idempotent === true,
-      run,
-    }, `run ${run.runId}: ${run.status}`);
-    return 0;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "runs cancel", error: "run_cancel_failed", issues: error.issues }, `run cancel failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "runs cancel", error: "run_cancel_io_failed" }, "run cancel failed because a local operation did not complete");
-    return 1;
-  }
-}
-
-async function cmdVnextRunList(runtime: Runtime): Promise<number> {
-  try {
-    const projectRoot = discoverVnextProjectRoot(runtime.cwd);
-    if (!projectRoot) {
-      print(runtime.io, runtime.json, { ok: false, command: "runs list", error: "project_required" }, "kxm runs list requires a vNext project (run kxm init first)");
-      return 1;
-    }
-    const bundle = loadVnextProject(projectRoot, {});
-    const projectId = String(bundle.project.value.id);
-    const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-    const result = await vnextRuntimeRequest(supervisor, "GET", `/v1/projects/${encodeURIComponent(projectId)}/runs?projectRoot=${encodeURIComponent(projectRoot)}`);
-    const runs = (result.runs ?? []) as Array<{ runId: string; status: string; workflowId: string; createdAt: string }>;
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "runs list", runs },
-      runs.length === 0 ? "no runs" : runs.map((run) => `${run.runId}  ${run.status}  ${run.workflowId}  ${run.createdAt}`).join("\n"),
-    );
-    return 0;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "runs list", error: "run_list_failed", issues: error.issues }, `run list failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "runs list", error: "run_list_io_failed" }, "run list failed because a local operation did not complete");
-    return 1;
-  }
-}
-
-async function cmdHarnessList(runtime: Runtime): Promise<number> {
-  const inventory = probeHarnesses({ env: runtime.env });
-  print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));
-  return 0;
-}
-
-function installProbeFrom(runtime: Runtime): InstallProbe {
-  const partial = runtime.io.installProbe ?? {};
-  return {
-    moduleDir: partial.moduleDir ?? dirname(fileURLToPath(import.meta.url)),
-    repoRoot: partial.repoRoot ?? repoRoot,
-    homeDir: partial.homeDir ?? homedir(),
-    platform: partial.platform ?? process.platform,
-    env: partial.env ?? runtime.env,
-  };
-}
-
-function cliSpawn(runtime: Runtime, command: string, args: readonly string[], extra?: { timeout?: number }): CliSpawnResult {
-  if (runtime.io.spawnSync) return runtime.io.spawnSync(command, args);
-  const result = spawnSync(command, [...args], {
-    encoding: "utf8",
-    windowsHide: true,
-    shell: process.platform === "win32",
-    ...extra,
-  });
-  return {
-    status: result.status,
-    stdout: typeof result.stdout === "string" ? result.stdout : "",
-    stderr: typeof result.stderr === "string" ? result.stderr : "",
-    ...(result.error ? { error: result.error } : {}),
-  };
-}
-
-function npmGlobalRootFn(runtime: Runtime): () => string | undefined {
-  return () => {
-    const result = cliSpawn(runtime, "npm", ["root", "-g"], { timeout: 5_000 });
-    if (result.error || result.status !== 0) return undefined;
-    const out = result.stdout.trim();
-    return out || undefined;
-  };
-}
-
-function warnIgnoredProjectUpdateYaml(runtime: Runtime): void {
-  const projectFile = join(runtime.dirs.workspace, "update.yaml");
-  if (!existsSync(projectFile)) return;
-  const userFile = join(vnextUserStateRoot({ env: runtime.env }), "update.yaml");
-  runtime.io.stderr(`kxm: ignoring .kxm/update.yaml in ${runtime.dirs.workdir}; update settings are read only from ${userFile}\n`);
-}
-
-function installKindPayload(report: InstallKindReport): { installKind: string; root: string } {
-  return { installKind: report.kind, root: report.root };
-}
-
-function formatPackageUpdateStep(step: KxmPackageUpdateStep): string {
-  if (step.kind === "verify") return `verify sha256 ${step.path}`;
-  return `${step.command} ${step.args.join(" ")}`;
-}
-
-async function refreshKxmUpdateNotice(runtime: Runtime, config?: KxmUpdateConfig): Promise<KxmUpdateNotice> {
-  const resolved = config ?? loadKxmUpdateConfig(runtime.env);
-  const current = readInstalledKxmVersion(repoRoot);
-  const fetched = await fetchLatestKxmVersion(resolved.source, runtime.env, runtime.fetchImpl);
-  const notice = noticeFromVersions(current, fetched.latest, resolved, fetched.error, fetched.asset);
-  writeUpdateCache(runtime.dirs.state, notice);
-  return notice;
-}
-
-function applyKxmPackageUpdate(runtime: Runtime, notice: KxmUpdateNotice): { ok: boolean; detail: string; error?: string } {
-  if (!notice.latest) return { ok: false, detail: "no_latest_version" };
-  if (notice.source === "github" && !notice.asset?.sha256) {
-    const name = kxmReleaseAssetName(notice.latest);
-    return {
-      ok: false,
-      error: "release_digest_missing",
-      detail: `release v${notice.latest} has no sha256 digest for ${name}; refusing to install`,
-    };
-  }
-  const releaseDir = mkdtempSync(join(tmpdir(), "kxm-pkg-update-"));
-  try {
-    const planned = planKxmPackageUpdate(notice.source, notice.latest, releaseDir, notice.asset);
-    if (runtime.dryRun) {
-      return { ok: true, detail: planned.map(formatPackageUpdateStep).join(" && ") };
-    }
-    for (const step of planned) {
-      if (step.kind === "verify") {
-        if (!verifyReleaseAssetDigest(step.path, step.sha256)) {
-          const actual = existsSync(step.path)
-            ? createHash("sha256").update(readFileSync(step.path)).digest("hex")
-            : "missing";
-          return {
-            ok: false,
-            error: "release_digest_mismatch",
-            detail: `${kxmReleaseAssetName(notice.latest)} sha256 ${actual} does not match release digest ${step.sha256}; refusing to install`,
-          };
-        }
-        continue;
-      }
-      const result = cliSpawn(runtime, step.command, step.args);
-      if (result.status !== 0) {
-        const detail = (result.stderr || result.stdout || result.error?.message || "update_failed").trim().slice(0, 500);
-        return { ok: false, detail };
-      }
-    }
-    return { ok: true, detail: `installed ${notice.latest} from ${notice.source}` };
-  } finally {
-    rmSync(releaseDir, { recursive: true, force: true });
-  }
-}
-
-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;
-  models?: boolean;
-  check?: boolean;
-  kxm?: boolean;
-}): Promise<number> {
-  if (options.check && (options.kxm || options.self || options.extensions || options.models || harness)) {
-    print(runtime.io, runtime.json, { ok: false, command: "update", error: "scope_conflict" }, "--check cannot be combined with other update flags");
-    return 2;
-  }
-  const selected = [options.self, options.extensions, options.models].filter(Boolean).length;
-  if (selected > 1) {
-    print(runtime.io, runtime.json, { ok: false, command: "update", error: "scope_conflict" }, "specify at most one of --self, --extensions, or --models");
-    return 2;
-  }
-  warnIgnoredProjectUpdateYaml(runtime);
-  const probe = installProbeFrom(runtime);
-  const classified = classifyInstallRoot(probe);
-  const current = readInstalledKxmVersion(repoRoot);
-  let notice: KxmUpdateNotice;
-  let kindReport = classified;
-  if (classified.kind === "source") {
-    if (options.check) {
-      const message = `kxm ${current} (running from source at ${classified.root})`;
-      print(runtime.io, runtime.json, {
-        ok: true,
-        command: "update check",
-        current,
-        available: false,
-        auto: false,
-        source: "github",
-        installKind: "source",
-        root: classified.root,
-        message,
-      }, message);
-      return 0;
-    }
-    if (options.kxm) {
-      print(runtime.io, runtime.json, {
-        ok: false,
-        command: "update",
-        error: "install_kind_source",
-        installKind: "source",
-        root: classified.root,
-        instruction: classified.instruction,
-      }, classified.instruction);
-      return 2;
-    }
-    notice = {
-      current,
-      available: false,
-      auto: false,
-      source: "github",
-      message: `kxm ${current} (running from source)`,
-    };
-  } else {
-    try {
-      notice = await refreshKxmUpdateNotice(runtime);
-    } catch (error) {
-      if (error instanceof KxmUpdateConfigError) {
-        print(runtime.io, runtime.json, { ok: false, command: "update", error: error.code, ...installKindPayload(classified) }, error.message);
-        return 2;
-      }
-      throw error;
-    }
-  }
-  if (options.check) {
-    print(runtime.io, runtime.json, {
-      ok: true,
-      command: "update check",
-      ...notice,
-      ...installKindPayload(classified),
-    }, notice.message);
-    return 0;
-  }
-  const applyKxm = Boolean(options.kxm || notice.auto);
-  let kxmApply: { ok: boolean; detail: string; error?: string } | undefined;
-  if (applyKxm) {
-    const resolved = resolveInstallKind(probe, npmGlobalRootFn(runtime));
-    kindReport = resolved;
-    if (resolved.kind !== "npm-global") {
-      if (options.kxm) {
-        print(runtime.io, runtime.json, {
-          ok: false,
-          command: "update",
-          error: `install_kind_${resolved.kind}`,
-          installKind: resolved.kind,
-          root: resolved.root,
-          instruction: resolved.instruction,
-          notice,
-        }, resolved.instruction);
-        return 2;
-      }
-      if (notice.available) runtime.io.stderr(`kxm: ${resolved.instruction}\n`);
-    } else if (notice.available) {
-      kxmApply = applyKxmPackageUpdate(runtime, notice);
-      if (!kxmApply.ok && options.kxm) {
-        print(runtime.io, runtime.json, {
-          ok: false,
-          command: "update",
-          error: kxmApply.error,
-          kxm: kxmApply,
-          notice,
-          ...installKindPayload(resolved),
-        }, kxmApply.detail);
-        return 1;
-      }
-    }
-  }
-  const skipHarness = Boolean(options.kxm && selected === 0 && !harness && !notice.auto);
-  if (skipHarness) {
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: kxmApply?.ok !== false, command: "update", dryRun: runtime.dryRun, notice, kxm: kxmApply, ...installKindPayload(kindReport) },
-      kxmApply?.detail ?? notice.message,
-    );
-    return kxmApply?.ok === false ? 1 : 0;
-  }
-  const scope: HarnessUpdateScope = options.self ? "self" : options.extensions ? "extensions" : options.models ? "models" : "all";
-  const inventory = probeHarnesses({ env: runtime.env });
-  const planned = planHarnessUpdate(inventory, { ...(harness ? { harness } : {}), scope });
-  const steps = runHarnessUpdate(planned, { env: runtime.env, dryRun: runtime.dryRun });
-  const failed = steps.some((step) => step.outcome === "failed") || kxmApply?.ok === false;
-  const skippedUnknown = steps.some((step) => step.detail === "unknown_harness");
-  const text = [notice.available ? notice.message : undefined, kxmApply?.detail, formatHarnessUpdate(steps)].filter(Boolean).join("\n");
-  print(runtime.io, runtime.json, {
-    ok: !failed && !skippedUnknown,
-    command: "update",
-    dryRun: runtime.dryRun,
-    scope,
-    notice,
-    ...(kxmApply ? { kxm: kxmApply } : {}),
-    steps,
-    ...installKindPayload(kindReport),
-  }, text);
-  if (skippedUnknown) return 2;
-  return failed ? 1 : 0;
-}
-
-async function cmdVnextRuntime(runtime: Runtime, action: string): Promise<number> {
-  const paths = vnextRuntimePaths({ env: runtime.env });
-  try {
-    if (action === "start") {
-      if (runtime.dryRun) {
-        print(runtime.io, runtime.json, { ok: true, command: "runtime start", dryRun: true }, "runtime supervisor would auto-start");
-        return 0;
-      }
-      const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-      print(runtime.io, runtime.json, {
-        ok: true,
-        command: "runtime start",
-        runtimeId: supervisor.runtimeId,
-        port: supervisor.port,
-        started: supervisor.started,
-      }, `runtime supervisor ${supervisor.started ? "started" : "already running"}: ${supervisor.runtimeId} on 127.0.0.1:${supervisor.port}`);
-      return 0;
-    }
-    if (action === "status") {
-      const status = vnextSupervisorStatus(paths);
-      print(runtime.io, runtime.json, { ok: true, command: "runtime status", ...status }, status.running
-        ? `runtime supervisor running: ${status.runtimeId} pid ${status.pid} on 127.0.0.1:${status.port}`
-        : "runtime supervisor is not running");
-      return status.running ? 0 : 1;
-    }
-    if (action === "stop") {
-      const status = vnextSupervisorStatus(paths);
-      if (!status.running || !status.port) {
-        print(runtime.io, runtime.json, { ok: true, command: "runtime stop", stopped: false }, "runtime supervisor is not running");
-        return 0;
-      }
-      if (runtime.dryRun) {
-        print(runtime.io, runtime.json, { ok: true, command: "runtime stop", dryRun: true }, `would stop runtime supervisor pid ${status.pid}`);
-        return 0;
-      }
-      // The stop request posts a bearer token, so prove the listener is the
-      // real supervisor (keyed healthz challenge) before sending it.
-      const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-      await vnextRuntimeRequest(supervisor, "POST", "/v1/shutdown", {});
-      print(runtime.io, runtime.json, { ok: true, command: "runtime stop", stopped: true }, `runtime supervisor ${status.runtimeId} stopping`);
-      return 0;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "runtime", error: "unknown_action" }, `unknown runtime action: ${action}`);
-    return 2;
-  } catch (error) {
-    if (error instanceof VnextConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "runtime", error: "runtime_failed", issues: error.issues }, `runtime failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "runtime", error: "runtime_io_failed" }, "runtime failed because a local operation did not complete");
-    return 1;
-  }
-}
-
-async function cmdValidate(runtime: Runtime, fileFlag?: string): Promise<number> {
-  const worker = gateOf(runtime, "validate");
-  const explicitFile = fileFlag?.trim();
-  const configuredFile = runtime.env.KXM_WEBHOOK_WORKFLOWS_FILE?.trim();
-  const inline = runtime.env.KXM_WEBHOOK_WORKFLOWS?.trim();
-  if (!explicitFile && configuredFile && inline) {
-    printWorker(
-      runtime,
-      worker,
-      { ok: false, command: "validate", error: "ambiguous_workflow_source" },
-      "configure only one of KXM_WEBHOOK_WORKFLOWS or KXM_WEBHOOK_WORKFLOWS_FILE",
-    );
-    return 2;
-  }
-  if (!explicitFile && !configuredFile && !inline) {
-    printWorker(
-      runtime,
-      worker,
-      { ok: false, command: "validate", error: "workflow_source_required" },
-      "provide --file or configure exactly one workflow source environment variable",
-    );
-    return 2;
-  }
-
-  const selectedFile = explicitFile || configuredFile;
-  const file = selectedFile ? resolve(runtime.cwd, selectedFile) : undefined;
-  if (file && !existsSync(file)) {
-    printWorker(runtime, worker, { ok: false, command: "validate", error: "file_not_found", file }, `workflow file not found: ${file}`);
-    return 1;
-  }
-  try {
-    const raw = file ? readFileSync(file, "utf8") : inline!;
-    const warnings: string[] = [];
-    const definitions = parseWorkflowDefinitions(raw, runtime.env, (message) => warnings.push(message));
-    const secretEnvs = definitions.map((definition) => ({
-      id: definition.id,
-      secretConfigured: Boolean(definition.secret),
-      signalSecretConfigured: Boolean(definition.signalSecret),
-    }));
-    const source = file ? "file" : "inline";
-    printWorker(
-      runtime,
-      worker,
-      { ok: true, command: "validate", source, ...(file ? { file } : {}), workflows: secretEnvs, warnings },
-      `validated ${definitions.length} workflow(s) from ${source}${warnings.length ? ` with ${warnings.length} warning(s)` : ""}`,
-      warnings.length ? "warning" : undefined,
-    );
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? redactSecrets(error.message) : "invalid_workflow";
-    printWorker(runtime, worker, { ok: false, command: "validate", error: message }, message);
-    return 1;
-  }
-}
-
-async function cmdArtifactsExist(runtime: Runtime, pathFlag: string): Promise<number> {
-  const worker = gateOf(runtime, "artifacts-exist");
-  const checked = verifyArtifactExists(runtime.dirs.assets, resolve(runtime.cwd, pathFlag));
-  if (!checked.ok) {
-    printWorker(
-      runtime,
-      worker,
-      { ok: false, command: "artifacts-exist", error: checked.error, path: checked.path },
-      `artifact verification failed: ${checked.error}`,
-    );
-    return 1;
-  }
-  printWorker(
-    runtime,
-    worker,
-    { ok: true, command: "artifacts-exist", path: checked.path, bytes: checked.bytes },
-    "artifact exists and is non-empty under workspace assets",
-  );
-  return 0;
-}
-
-async function cmdStatus(runtime: Runtime): Promise<number> {
-  const health = await hubGet(`${runtime.serverUrl}/health`, runtime.fetchImpl);
-  const ready = await hubGet(`${runtime.serverUrl}/ready`, runtime.fetchImpl);
-  const payload = { ok: health.ok && ready.ok, command: "hub view", health: health.body, ready: ready.body };
-  print(runtime.io, runtime.json, payload, `hub health=${health.ok} ready=${ready.ok}`);
-  return payload.ok ? 0 : 1;
-}
-
-async function cmdDash(runtime: Runtime, options: { screen?: string } = {}): Promise<number> {
-  const requested = options.screen?.trim();
-  if (requested && !(MESH_TUI_PANELS as readonly string[]).includes(requested)) {
-    print(runtime.io, runtime.json, { ok: false, command: "dash", error: "unknown_screen" }, `unknown screen ${requested}; use agents, tasks, workflows, plans, inbox, procs, or spend`);
-    return 2;
-  }
-  const screen = requested as MeshTuiPanel | undefined;
-  const dataPath = resolve(runtime.dirs.workdir, runtime.env.KXM_DATA_PATH?.trim() || join(runtime.dirs.state, "kxm.db"));
-  if (runtime.dryRun) {
-    print(runtime.io, runtime.json, {
-      ok: true,
-      command: "dash",
-      dryRun: true,
-      serverUrl: runtime.serverUrl,
-      transport: "sse",
-      ...(screen ? { screen } : {}),
-    }, "would start kxm dash");
-    return 0;
-  }
-  if (runtime.json) {
-    runtime.io.stderr("kxm dash does not support --json; use kxm hub view\n");
-    return 2;
-  }
-  const project = runtime.env.KXM_PROJECT?.trim() || basename(runtime.dirs.workdir) || "project";
-  const authToken = runtime.env.KXM_AUTH_TOKEN?.trim();
-  return await runMeshTui({
-    serverUrl: runtime.serverUrl,
-    dataPath,
-    stateDir: runtime.dirs.state,
-    project,
-    env: runtime.env,
-    ...(authToken ? { authToken } : {}),
-    ...(screen ? { screen } : {}),
-    fetchImpl: runtime.fetchImpl,
-    stdout: runtime.io.stdout,
-    stdin: process.stdin,
-    isTty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
-  });
-}
-
-async function cmdHub(runtime: Runtime): Promise<number> {
-  let refresh: Promise<unknown> | undefined;
-  if (!runtime.dryRun) {
-    const probe = installProbeFrom(runtime);
-    if (classifyInstallRoot(probe).kind !== "source") {
-      warnIgnoredProjectUpdateYaml(runtime);
-      const cached = readUpdateCache(runtime.dirs.state);
-      if (cached?.available) runtime.io.stderr(`${cached.message}\n`);
-      let config: KxmUpdateConfig | undefined;
-      try {
-        config = loadKxmUpdateConfig(runtime.env);
-      } catch (error) {
-        if (error instanceof KxmUpdateConfigError) {
-          const yamlPath = join(vnextUserStateRoot({ env: runtime.env }), "update.yaml");
-          runtime.io.stderr(`kxm: ${error.message}; update check skipped; fix or remove ${yamlPath}\n`);
-        } else {
-          throw error;
-        }
-      }
-      if (config) {
-        refresh = refreshKxmUpdateNotice(runtime, config).then((notice) => {
-          if (notice.available && !cached?.available) runtime.io.stderr(`${notice.message}\n`);
-        }).catch(() => undefined);
-      }
-    }
-  }
-  const extraEnv = workspaceEnv(runtime);
-  if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "hub start", dryRun: true, workspace: runtime.dirs.workspace }, "would start hub");
-    return 0;
-  }
-  const code = await (runtime.io.spawnHub ?? ((launchEnv) => spawnScript("kxm-hub.mjs", launchEnv)))(extraEnv);
-  if (refresh) await refresh;
-  return code;
-}
-
-function formatHubBindHealth(health: HubHealth): string {
-  if (health === "on") return "health=on";
-  if (health === "off") return "health=off (nothing answered; run kxm hub start)";
-  return "health=unknown (no reply within 300 ms)";
-}
-
-async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<number> {
-  let url: string;
-  try {
-    url = validateHubUrl(rawUrl);
-  } catch (error) {
-    if (error instanceof HubBindingError) {
-      print(
-        runtime.io,
-        runtime.json,
-        { ok: false, command: "hub bind", error: "hub_url_invalid" },
-        "hub bind needs an http or https URL without credentials, query, or fragment",
-      );
-      return 2;
-    }
-    throw error;
-  }
-  const file = hubBindingFile(runtime.env);
-  if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "hub bind", dryRun: true, url, file }, `would bind hub ${url}`);
-    return 0;
-  }
-  writeHubBinding({ schema: HUB_BINDING_SCHEMA, url, boundAt: new Date().toISOString() }, runtime.env);
-  const { health, probeMs } = await probeHubHealth(url, runtime.fetchImpl);
-  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, file, health, probeMs }, `bound hub ${url} · ${formatHubBindHealth(health)}`);
-  return 0;
-}
-
-async function cmdHubUnbind(runtime: Runtime): Promise<number> {
-  const file = hubBindingFile(runtime.env);
-  if (runtime.dryRun) {
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "hub unbind", dryRun: true, ...(runtime.boundHubUrl ? { url: runtime.boundHubUrl } : {}), file },
-      `would unbind hub${runtime.boundHubUrl ? ` ${runtime.boundHubUrl}` : ""}`,
-    );
-    return 0;
-  }
-  let url: string | undefined;
-  let malformed = false;
-  try {
-    url = readHubBinding(runtime.env)?.url;
-  } catch (error) {
-    if (error instanceof HubBindingError) malformed = true;
-    else throw error;
-  }
-  if (!malformed && !url) {
-    print(runtime.io, runtime.json, { ok: false, command: "hub unbind", error: "hub_not_bound" }, `no hub binding at ${file}`);
-    return 1;
-  }
-  removeHubBinding(runtime.env);
-  if (malformed) {
-    print(runtime.io, runtime.json, { ok: true, command: "hub unbind", file }, "unbound hub (record was malformed)");
-    return 0;
-  }
-  print(runtime.io, runtime.json, { ok: true, command: "hub unbind", url, file }, `unbound hub ${url}`);
-  return 0;
-}
-
-async function cmdWorker(runtime: Runtime, options: {
-  name?: string;
-  project?: string;
-  model?: string;
-  fallbackModels?: string;
-  tools?: string;
-  sessionIsolation?: string;
-  continue?: boolean;
-  freshStart?: boolean;
-}): Promise<number> {
-  const name = options.name?.trim() || runtime.env.KXM_AGENT_NAME?.trim();
-  const project = options.project?.trim() || runtime.env.KXM_PROJECT?.trim();
-  const model = options.model?.trim() || runtime.env.KXM_WORKER_MODEL?.trim();
-  const fallbackModels = options.fallbackModels?.trim() || runtime.env.KXM_WORKER_FALLBACK_MODELS?.trim();
-  const tools = options.tools?.trim() || runtime.env.KXM_WORKER_TOOLS?.trim();
-  const sessionIsolation = options.sessionIsolation?.trim() || runtime.env.KXM_WORKER_SESSION_ISOLATION?.trim() || "off";
-  if (sessionIsolation !== "workflow" && sessionIsolation !== "off") {
-    runtime.io.stderr("worker --session-isolation must be workflow or off\n");
-    return 2;
-  }
-  const extraEnv = {
-    ...workspaceEnv(runtime),
-    ...(name ? { KXM_AGENT_NAME: name } : {}),
-    ...(project ? { KXM_PROJECT: project } : {}),
-    ...(model ? { KXM_WORKER_MODEL: model } : {}),
-    ...(fallbackModels ? { KXM_WORKER_FALLBACK_MODELS: fallbackModels } : {}),
-    ...(tools ? { KXM_WORKER_TOOLS: tools } : {}),
-    KXM_WORKER_SESSION_ISOLATION: sessionIsolation,
-    ...(options.continue === false ? { KXM_WORKER_CONTINUE: "false" } : {}),
-    ...(options.freshStart ? { KXM_WORKER_INITIAL_CONTINUE: "false" } : {}),
-  };
-  if (runtime.dryRun) {
-    printWorker(runtime, agentWorker({
-      name: name || "required",
-      project: project || "required",
-      ...(model ? { model } : {}),
-    }), {
-      ok: true,
-      command: "worker",
-      dryRun: true,
-      workspace: runtime.dirs.workspace,
-      name: name || "required",
-      project: project || "required",
-      model: model || "provider default",
-      fallbackModels: fallbackModels || "none",
-      tools: tools || "Pi defaults",
-      sessionIsolation,
-      continue: options.continue !== false,
-      freshStart: Boolean(options.freshStart),
-    }, "would start worker");
-    return 0;
-  }
-  if (!name || !project) {
-    runtime.io.stderr("worker requires --name and --project (or KXM_AGENT_NAME and KXM_PROJECT)\n");
-    return 2;
-  }
-  return await (runtime.io.spawnWorker ?? ((launchEnv) => spawnScript("kxm-worker.mjs", launchEnv)))(extraEnv);
-}
-
-async function cmdStop(runtime: Runtime, waitMsFlag?: string): Promise<number> {
-  const pids = existsSync(runtime.dirs.state)
-    ? readdirSync(runtime.dirs.state).filter((name) => name.endsWith(".pid"))
-    : [];
-  if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "stop", dryRun: true, pidFiles: pids }, "would signal pid files");
-    return 0;
-  }
-  if (pids.length === 0) {
-    print(runtime.io, runtime.json, { ok: false, command: "stop", error: "no_pid_files" }, "no hub/worker pid files found");
-    return 1;
-  }
-  const requested: string[] = [];
-  const ignored: string[] = [];
-  const records = new Map<string, { pid: number; startedAt: string; generation?: 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 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 });
-      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; }
-  const waitMs = Math.min(30_000, Math.max(100, Number(waitMsFlag || 5_000)));
-  const deadline = Date.now() + waitMs;
-  const stopped = new Set<string>();
-  while (Date.now() <= deadline && stopped.size < requested.length) {
-    for (const [file, record] of records) {
-      try {
-        const current = JSON.parse(readFileSync(join(runtime.dirs.state, file), "utf8")) as { pid?: number; startedAt?: string; generation?: string };
-        if (current.pid !== record.pid || current.startedAt !== record.startedAt || current.generation !== record.generation || !processExists(record.pid)) stopped.add(file);
-      } catch { stopped.add(file); }
-    }
-    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));
-  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");
-  return ok ? 0 : 1;
-}
-
-async function cmdSessionStatus(runtime: Runtime): Promise<number> {
-  const stateDir = runtime.dirs.state;
-  const names = existsSync(stateDir) ? readdirSync(stateDir) : [];
-  const claims = [];
-  for (const file of names.filter((name) => name.endsWith(".pid"))) {
-    try {
-      const record = JSON.parse(readFileSync(join(stateDir, file), "utf8")) as { pid?: number; role?: string; startedAt?: string; generation?: string };
-      claims.push({
-        file,
-        role: record.role,
-        pid: record.pid,
-        startedAt: record.startedAt,
-        live: Number.isInteger(record.pid) && record.pid! > 0 && processExists(record.pid!),
-      });
-    } catch {
-      claims.push({ file, live: false, error: "invalid_pid_record" });
-    }
-  }
-  const recoveries = [];
-  for (const file of names.filter((name) => name.startsWith("worker-recovery-") && name.endsWith(".json"))) {
-    try {
-      const envelope = JSON.parse(readFileSync(join(stateDir, file), "utf8")) as {
-        reason?: string;
-        agentName?: string;
-        project?: string;
-        createdAt?: string;
-        runId?: string | null;
-        stageId?: string | null;
-        freshSession?: boolean;
-      };
-      recoveries.push({
-        file,
-        reason: envelope.reason,
-        agentName: envelope.agentName,
-        project: envelope.project,
-        createdAt: envelope.createdAt,
-        runId: envelope.runId ?? undefined,
-        stageId: envelope.stageId ?? undefined,
-        freshSession: envelope.freshSession === true,
-      });
-    } catch {
-      recoveries.push({ file, error: "invalid_recovery_envelope" });
-    }
-  }
-  print(
-    runtime.io,
-    runtime.json,
-    { ok: true, command: "session status", claims, recoveries },
-    `${claims.length} session claim(s), ${recoveries.length} recovery envelope(s)`,
-  );
-  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 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;
-  }
-
-  const dataPath = resolve(runtime.dirs.workdir, runtime.env.KXM_DATA_PATH?.trim() || join(runtime.dirs.state, "kxm.db"));
-  const env = {
-    ...runtime.env,
-    KXM_STATE_DIR: runtime.dirs.state,
-    KXM_DATA_PATH: runtime.env.KXM_DATA_PATH?.trim() || dataPath,
-  };
-
-  let hub: SessionHubStatus | undefined;
-  const targetUrl = runtime.env.KXM_SERVER_URL?.trim() || runtime.boundHubUrl || readHubBinding(runtime.env)?.url;
-  if (targetUrl) {
-    const { health } = await probeHubHealth(targetUrl, runtime.fetchImpl, 300);
-    hub = {
-      state: health,
-      evidence: health === "unknown" ? "timeout" : "probed",
-      online: health === "on",
-      url: targetUrl,
-    };
-  } else {
-    hub = { state: "off", evidence: "unconfigured", online: false };
-  }
-
-  const brief = await loadSessionBriefAsync(runtime.dirs.workdir, env, undefined, hub, {
-    fetchImpl: runtime.fetchImpl,
-    sessionToken,
-  });
-
-  if (options.status) {
-    print(runtime.io, runtime.json, brief, brief.statusLine);
-    return 0;
-  }
-  print(
-    runtime.io,
-    runtime.json,
-    brief,
-    `${formatSessionBriefText(brief)}\n\nSession token: ${sessionToken}\n`,
-  );
-  return 0;
-}
-
-async function cmdSessionStart(runtime: Runtime, options: { id?: string; workflow?: string; mix?: string }): Promise<number> {
-  const id = options.id?.trim() || `session_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
-  const workflowId = options.workflow?.trim();
-  const mix = options.mix?.trim();
-  if (workflowId && mix) {
-    runtime.io.stderr("session start takes --workflow or --mix, not both\n");
-    return 2;
-  }
-  if (!workflowId && !mix) {
-    runtime.io.stderr("session start requires --workflow <id> or --mix <agent,gate,...>\n");
-    return 2;
-  }
-  const project = runtime.env.KXM_PROJECT?.trim();
-  let workers: Worker[];
-  try {
-    const names = mix
-      ? mix.split(",").map((name) => name.trim()).filter(Boolean)
-      : rosterNames(runtime.dirs.config);
-    workers = loadNamedWorkers(runtime.dirs.config, names, project);
-  } catch (error) {
-    const errorName = error && typeof error === "object" && "name" in error ? String(error.name) : "";
-    if (errorName !== "SessionConfigError") throw error;
-    const message = error instanceof Error ? redactSecrets(error.message) : "invalid session configuration";
-    runtime.io.stderr(`${message}\n`);
-    return 2;
-  }
-  const session = createSession({
-    id,
-    host: hostMode(runtime),
-    mode: workflowId ? "workflow" : "mix",
-    workers,
-    assetsDir: runtime.dirs.assets,
-    ...(workflowId ? { workflowId } : {}),
-  });
-  const created = [
-    ...sessionAssetDirs(runtime.dirs.assets, session.id),
-    ...(workflowId ? workflowAssetDirs(runtime.dirs.assets, workflowId) : []),
-  ];
-  if (!runtime.dryRun) {
-    for (const directory of created) mkdirSync(directory, { recursive: true });
-    writeSession(runtime.dirs.assets, session);
-  }
-  print(runtime.io, runtime.json, {
-    ok: true,
-    command: "session start",
-    dryRun: runtime.dryRun || undefined,
-    session,
-    created,
-  }, `session ${session.id} (${session.mode})`);
-  return 0;
-}
-
-async function cmdImprove(runtime: Runtime, options: { file?: string; target?: string; outDir?: string } = {}): Promise<number> {
-  const file = options.file ? resolve(runtime.cwd, options.file) : telemetryPath(runtime.dirs.logs);
-  const routingRecords = existsSync(file)
-    ? readRoutingRecords(file).map((entry) => entry.routing)
-    : [];
-
-  const candidatesDir = options.outDir
-    ? resolve(runtime.cwd, options.outDir)
-    : join(runtime.cwd, ".kxm", "candidates");
-
-  const report = buildImprovementReport(routingRecords, {
-    candidatesDir,
-    projectRoot: runtime.cwd,
-    dryRun: runtime.dryRun,
-  });
-
-  const reportDir = join(runtime.dirs.assets, "improvements");
-  const reportPath = writeImprovementReport(reportDir, report, runtime.dryRun);
-
-  const text = formatImprovementReport(report);
-  print(runtime.io, runtime.json, {
-    ok: true,
-    command: "improve",
-    dryRun: runtime.dryRun || undefined,
-    path: reportPath,
-    events: report.recordsCount,
-    recordsCount: report.recordsCount,
-    groupsCount: report.groups.length,
-    candidatesCount: report.candidates.length,
-    candidates: report.candidates,
-    report,
-  }, text);
-  return 0;
-}
-
-function parseContextKinds(value: string | undefined): string[] | undefined {
-  if (!value) return undefined;
-  return value.split(",").map((kind) => kind.trim()).filter((kind) => kind.length > 0);
-}
-
-async function cmdContextGet(runtime: Runtime, project: string, options: { role: string; task: string; run?: string; stage?: string; budget?: string; kinds?: string }): Promise<number> {
-  const budget = options.budget === undefined ? undefined : Number(options.budget);
-  if (options.budget !== undefined && (!Number.isInteger(budget) || (budget as number) < 512 || (budget as number) > 200_000)) {
-    runtime.io.stderr("context get --budget must be an integer between 512 and 200000\n");
-    return 2;
-  }
-  const body: Record<string, unknown> = {
-    project,
-    role: options.role,
-    task: options.task,
-  };
-  if (options.run) body.workflowRunId = options.run;
-  if (options.stage) body.stageId = options.stage;
-  if (budget !== undefined) body.budgetTokens = budget;
-  const kinds = parseContextKinds(options.kinds);
-  if (kinds) body.includeKinds = kinds;
-  const response = await hubContextPost({
-    serverUrl: runtime.serverUrl,
-    path: "/v1/context/get",
-    body,
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
-    fetchImpl: runtime.fetchImpl,
-  });
-  print(runtime.io, runtime.json, { ok: response.ok, command: "context get", status: response.status, ...(response.body as object) }, `context get ${response.ok ? "assembled" : `failed (${response.status})`}`);
-  return response.ok ? 0 : 1;
-}
-
-async function cmdContextRecall(runtime: Runtime, project: string, options: { query?: string; kinds?: string; limit?: string }): Promise<number> {
-  const body: Record<string, unknown> = { project };
-  if (options.query) body.query = options.query;
-  const kinds = parseContextKinds(options.kinds);
-  if (kinds) body.kinds = kinds;
-  if (options.limit) body.limit = Number(options.limit);
-  const response = await hubContextPost({
-    serverUrl: runtime.serverUrl,
-    path: "/v1/context/recall",
-    body,
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
-    fetchImpl: runtime.fetchImpl,
-  });
-  print(runtime.io, runtime.json, { ok: response.ok, command: "context recall", status: response.status, ...(response.body as object) }, `context recall ${response.ok ? "complete" : `failed (${response.status})`}`);
-  return response.ok ? 0 : 1;
-}
-
-async function cmdContextState(runtime: Runtime, project: string, key: string, options: { asOf?: string }): Promise<number> {
-  const body: Record<string, unknown> = { project, key };
-  if (options.asOf) body.asOf = options.asOf;
-  const response = await hubContextPost({
-    serverUrl: runtime.serverUrl,
-    path: "/v1/context/state",
-    body,
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
-    fetchImpl: runtime.fetchImpl,
-  });
-  print(runtime.io, runtime.json, { ok: response.ok, command: "context state", status: response.status, ...(response.body as object) }, `context state ${response.ok ? "resolved" : `failed (${response.status})`}`);
-  return response.ok ? 0 : 1;
-}
-
-async function cmdContextEpisode(runtime: Runtime, project: string, options: { run?: string }): Promise<number> {
-  const body: Record<string, unknown> = { project };
-  if (options.run) body.workflowRunId = options.run;
-  const response = await hubContextPost({
-    serverUrl: runtime.serverUrl,
-    path: "/v1/context/episode",
-    body,
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
-    fetchImpl: runtime.fetchImpl,
-  });
-  print(runtime.io, runtime.json, { ok: response.ok, command: "context episode", status: response.status, ...(response.body as object) }, `context episode ${response.ok ? "complete" : `failed (${response.status})`}`);
-  return response.ok ? 0 : 1;
-}
-
-async function cmdContextPromote(runtime: Runtime, project: string, proposalId: string, options: { evidence: string }): Promise<number> {
-  const evidence = options.evidence.split(",").map((ref) => ref.trim()).filter((ref) => ref.length > 0);
-  if (evidence.length === 0) {
-    runtime.io.stderr("context promote --evidence must contain at least one durable evidence reference\n");
-    return 2;
-  }
-  const response = await hubContextPost({
-    serverUrl: runtime.serverUrl,
-    path: "/v1/context/state/promote",
-    body: { project, proposalId, evidence },
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
-    fetchImpl: runtime.fetchImpl,
-  });
-  print(runtime.io, runtime.json, { ok: response.ok, command: "context promote", status: response.status, ...(response.body as object) }, `context promote ${response.ok ? "recorded" : `failed (${response.status})`}`);
-  return response.ok ? 0 : 1;
-}
-
-async function cmdContextExplain(runtime: Runtime, project: string, itemId: string): Promise<number> {
-  const response = await hubContextPost({
-    serverUrl: runtime.serverUrl,
-    path: "/v1/context/explain",
-    body: { project, id: itemId },
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
-    fetchImpl: runtime.fetchImpl,
-  });
-  print(runtime.io, runtime.json, { ok: response.ok, command: "context explain", status: response.status, ...(response.body as object) }, `context explain ${response.ok ? "complete" : `failed (${response.status})`}`);
-  return response.ok ? 0 : 1;
-}
-
-async function cmdContextWikiCompile(runtime: Runtime, project: string, options: { out?: string }): Promise<number> {
-  const response = await hubContextPost({
-    serverUrl: runtime.serverUrl,
-    path: "/v1/context/wiki/compile",
-    body: { project },
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
-    fetchImpl: runtime.fetchImpl,
-  });
-  if (!response.ok) {
-    print(runtime.io, runtime.json, { ok: false, command: "context wiki-compile", status: response.status, body: response.body }, `wiki compile failed (${response.status})`);
-    return 1;
-  }
-  const compiled = response.body as { audit: { pages: string[]; contradictions: number }; pages: { path: string; content: string }[] };
-  let written: string[] = [];
-  if (options.out) {
-    const pages = new Map(compiled.pages.map((page) => [page.path, page.content]));
-    written = writeCompiledWiki(options.out, { pages, index: pages.get(".kxm/knowledge/wiki/index.md") ?? "", audit: { project, pages: compiled.audit.pages, stateItems: 0, contextItems: 0, contradictions: compiled.audit.contradictions, compiledAt: "" } });
-  }
-  print(runtime.io, runtime.json, { ok: true, command: "context wiki-compile", project, pages: compiled.audit.pages, openContradictions: compiled.audit.contradictions, ...(written.length > 0 ? { written: written.length, outDir: options.out } : { dryRun: true }) }, `compiled ${compiled.audit.pages.length} wiki page(s)${written.length > 0 ? ` to ${options.out}` : " (dry-run)"}`);
-  return 0;
-}
-
-async function cmdContextWikiLint(runtime: Runtime, project: string): Promise<number> {
-  const response = await hubContextPost({
-    serverUrl: runtime.serverUrl,
-    path: "/v1/context/wiki/compile",
-    body: { project },
-    ...(runtime.env.KXM_AUTH_TOKEN?.trim() ? { authToken: runtime.env.KXM_AUTH_TOKEN.trim() } : {}),
-    fetchImpl: runtime.fetchImpl,
-  });
-  if (!response.ok) {
-    print(runtime.io, runtime.json, { ok: false, command: "context wiki-lint", status: response.status, body: response.body }, `wiki lint failed (${response.status})`);
-    return 1;
-  }
-  const compiled = response.body as {
-    audit: { stateItems: number; contextItems: number; contradictions: number; compiledAt: string };
-    lint: { severity: string; rule: string; path: string; message: string }[];
-  };
-  const issues = compiled.lint;
-  print(runtime.io, runtime.json, { ok: issues.length === 0, command: "context wiki-lint", project, issues, audit: compiled.audit }, issues.length === 0 ? "wiki lint clean" : `wiki lint found ${issues.length} issue(s)`);
-  return issues.every((issue) => issue.severity !== "error") ? 0 : 1;
-}
-
-function skillStateFromFlag(value: string): SkillState {
-  if (value === "candidate" || value === "promoted" || value === "quarantined" || value === "rejected") return value;
-  throw new Error(`invalid skill state ${value}`);
-}
-
-function skillsRoot(runtime: Runtime): string {
-  return join(runtime.dirs.workdir, ".kxm", "skills");
-}
-
-function csv(value: string | undefined): string[] | undefined {
-  if (!value) return undefined;
-  const items = value.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
-  return items.length > 0 ? items : undefined;
-}
-
-async function cmdSkillsCreate(runtime: Runtime, options: { file: string; name: string; description?: string; createdBy: string; run?: string; journal?: string; receipt?: string; harness: string; models: string; supersedes?: string }): Promise<number> {
-  if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "skills create", dryRun: true, name: options.name }, "would create skill candidate");
-    return 0;
-  }
-  const lifecycle = new SkillLifecycle(skillsRoot(runtime));
-  try {
-    const metadata = lifecycle.create({
-      name: options.name,
-      description: options.description ?? "",
-      content: readFileSync(options.file, "utf8"),
-      createdBy: options.createdBy,
-      sources: {
-        runIds: csv(options.run) ?? [],
-        journalEntryIds: csv(options.journal) ?? [],
-        evidenceReceipts: csv(options.receipt) ?? [],
-      },
-      compatibility: { harness: options.harness, models: csv(options.models) ?? [] },
-      ...(options.supersedes ? { supersedes: options.supersedes } : {}),
-    });
-    print(runtime.io, runtime.json, { ok: true, command: "skills create", metadata }, `created skill candidate ${metadata.id}`);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`skills create failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdSkillsEvaluate(runtime: Runtime, skillId: string, options: { kind: string; evaluator: string; fail?: boolean; score?: string; details?: string }): Promise<number> {
-  const lifecycle = new SkillLifecycle(skillsRoot(runtime));
-  try {
-    const outcome = lifecycle.evaluate(skillId, {
-      kind: options.kind as SkillEvaluationKind,
-      evaluatorVersion: options.evaluator,
-      passed: options.fail !== true,
-      ...(options.score !== undefined ? { score: Number(options.score) } : {}),
-      ...(options.details ? { details: options.details } : {}),
-    });
-    print(runtime.io, runtime.json, { ok: true, command: "skills evaluate", skillId, quarantined: outcome.quarantined, evaluation: outcome.evaluation }, `recorded ${options.kind} evaluation${outcome.quarantined ? " (candidate quarantined)" : ""}`);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`skills evaluate failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdSkillsPromote(runtime: Runtime, skillId: string, options: { decidedBy: string; evidence: string; reason?: string }): Promise<number> {
-  const lifecycle = new SkillLifecycle(skillsRoot(runtime));
-  try {
-    const promoted = lifecycle.promote(skillId, {
-      decidedBy: options.decidedBy,
-      reason: options.reason ?? "passed protected evaluation",
-      evidenceRefs: csv(options.evidence) ?? [],
-    });
-    print(runtime.io, runtime.json, { ok: true, command: "skills promote", skillId, metadata: promoted, patchPath: promoted.patchPath }, `promoted skill ${skillId} (patch: ${promoted.patchPath})`);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`skills promote failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdSkillsReject(runtime: Runtime, skillId: string, options: { decidedBy: string; reason?: string }): Promise<number> {
-  const lifecycle = new SkillLifecycle(skillsRoot(runtime));
-  try {
-    const metadata = lifecycle.reject(skillId, { decidedBy: options.decidedBy, reason: options.reason ?? "rejected" });
-    print(runtime.io, runtime.json, { ok: true, command: "skills reject", skillId, metadata }, `rejected skill ${skillId} (history retained)`);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`skills reject failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdSkillsList(runtime: Runtime, options: { state: string }): Promise<number> {
-  try {
-    const lifecycle = new SkillLifecycle(skillsRoot(runtime));
-    const state = skillStateFromFlag(options.state);
-    const items = lifecycle.list(state).map((metadata) => ({
-      id: metadata.id,
-      name: metadata.name,
-      version: metadata.version,
-      createdBy: metadata.createdBy,
-      createdAt: metadata.createdAt,
-      models: metadata.compatibility.models,
-    }));
-    print(runtime.io, runtime.json, { ok: true, command: "skills list", state: options.state, skills: items }, `${items.length} ${state} skill(s)`);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`skills list failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdSkillsVerify(runtime: Runtime, skillId: string, options: { state: string }): Promise<number> {
-  try {
-    const lifecycle = new SkillLifecycle(skillsRoot(runtime));
-    const state = skillStateFromFlag(options.state);
-    const metadata = lifecycle.verify(state, skillId);
-    print(runtime.io, runtime.json, { ok: true, command: "skills verify", skillId, state: options.state, contentSha256: metadata.contentSha256 }, `skill ${skillId} integrity verified`);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`skills verify failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdMemoryBrief(runtime: Runtime): Promise<number> {
-  try {
-    const brief = generateMemoryBrief(runtime.cwd);
-    const text = formatMemoryBriefText(brief);
-    print(runtime.io, runtime.json, { ok: true, command: "memory brief", brief }, text);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`memory brief failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdMemoryNote(
-  runtime: Runtime,
-  fact: string,
-  options: { scope?: string; kind?: string; body?: string },
-): Promise<number> {
-  try {
-    const { record, path } = createMemoryNote(runtime.cwd, fact, {
-      scope: (options.scope ?? "project") as MemoryScope,
-      ...(options.kind !== undefined ? { kind: options.kind } : {}),
-      ...(options.body !== undefined ? { body: options.body } : {}),
-    });
-    const relPath = relative(runtime.cwd, path);
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "memory note", candidate: record, path: relPath },
-      `Recorded memory candidate ${record.id} in ${relPath} (promoted via PR)`,
-    );
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`memory note failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdMemorySync(runtime: Runtime): Promise<number> {
-  try {
-    const result = syncHarnessMemory(runtime.cwd);
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "memory sync", ...result },
-      `Synced project memory across AGENTS.md, CLAUDE.md, and GEMINI.md`,
-    );
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`memory sync failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdConfigGet(runtime: Runtime, key: string): Promise<number> {
-  try {
-    const config = loadKxmConfig(runtime.cwd);
-    const value = getKxmConfigValue(config, key);
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "config get", key, value },
-      value !== undefined ? String(value) : "(undefined)",
-    );
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`config get failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdConfigSet(
-  runtime: Runtime,
-  key: string,
-  value: string,
-  options: { scope: string },
-): Promise<number> {
-  try {
-    const scope = options.scope === "user" ? "user" : "project";
-    let parsedVal: unknown = value;
-    try {
-      parsedVal = JSON.parse(value);
-    } catch {
-      // keep string
-    }
-    setKxmConfigValue(runtime.cwd, key, parsedVal, { scope });
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "config set", key, value: parsedVal, scope },
-      `Set ${key} = ${value} in ${scope} config`,
-    );
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`config set failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdConfigList(runtime: Runtime): Promise<number> {
-  try {
-    const config = loadKxmConfig(runtime.cwd);
-    const text = formatKxmConfig(config);
-    print(runtime.io, runtime.json, { ok: true, command: "config list", config }, text);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`config list failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdCompletion(runtime: Runtime, shell: string): Promise<number> {
-  try {
-    if (shell !== "bash" && shell !== "zsh" && shell !== "fish") {
-      runtime.io.stderr(`unsupported shell: ${shell}; must be bash, zsh, or fish\n`);
-      return 1;
-    }
-    const script = generateShellCompletion(shell as SupportedShell);
-    runtime.io.stdout(script);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`completion generation failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdSuggest(runtime: Runtime, promptParts: string[]): Promise<number> {
-  try {
-    const prompt = promptParts.join(" ").trim();
-    if (!prompt) {
-      runtime.io.stderr("prompt must be non-empty\n");
-      return 2;
-    }
-    const inventory = probeHarnesses({ env: runtime.env });
-    const availableHarnesses = inventory.harnesses.map((h) => ({
-      harness: h.id,
-      auth: h.authenticated === true ? "authenticated" : "unauthenticated",
-    }));
-    const suggestion = suggestWorkflowAndRoles(prompt, { availableHarnesses });
-
-    const text = [
-      `Suggested Workflow: ${suggestion.workflowId} (${suggestion.area})`,
-      `Confidence: ${(suggestion.confidence * 100).toFixed(0)}%`,
-      `Reasons: ${suggestion.reasons.join("; ")}`,
-      `Suggested Skills: ${suggestion.suggestedSkills.join(", ") || "none"}`,
-      `Roles:`,
-      `  Planner:     ${suggestion.roles.planner.harness} (${suggestion.roles.planner.model})`,
-      `  Writer:      ${suggestion.roles.writer.harness} (${suggestion.roles.writer.model})`,
-      `  Critics:     ${suggestion.roles.critics.map((c) => `${c.harness}:${c.model}`).join(", ")}`,
-      `  Verifier:    ${suggestion.roles.verifier.command}`,
-      ``,
-      `Execute with:`,
-      `  ${suggestion.suggestedCommand}`,
-    ].join("\n");
-
-    print(runtime.io, runtime.json, { ok: true, command: "suggest", prompt, ...suggestion }, text);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`suggest failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdGoalCreate(
-  runtime: Runtime,
-  title: string,
-  options: { area?: string; metric?: string[]; targetDate?: string },
-): Promise<number> {
-  try {
-    const goal = createGoal(runtime.cwd, {
-      title,
-      area: options.area,
-      successMetrics: options.metric,
-      targetDate: options.targetDate,
-    });
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "goal create", goal },
-      `Created goal ${goal.id}: ${goal.title}`,
-    );
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`goal create failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdGoalList(runtime: Runtime): Promise<number> {
-  try {
-    const goals = listGoals(runtime.cwd);
-    const text = goals.length === 0
-      ? "No goals recorded in .kxm/goals/"
-      : goals.map((g) => `[${g.status}] ${g.id}: ${g.title} (${g.area})`).join("\n");
-    print(runtime.io, runtime.json, { ok: true, command: "goal list", count: goals.length, goals }, text);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`goal list failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdTaskCreate(
-  runtime: Runtime,
-  title: string,
-  options: { goal?: string; objective?: string; workflow?: string; tracker?: string; issue?: string },
-): Promise<number> {
-  try {
-    const task = createTask(runtime.cwd, {
-      title,
-      goalId: options.goal,
-      objective: options.objective ?? title,
-      assignedWorkflow: options.workflow,
-      trackerSync: options.tracker && options.issue
-        ? { tracker: options.tracker as TrackerType, issueKey: options.issue }
-        : undefined,
-    });
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "task create", task },
-      `Created task ${task.id}: ${task.title} [${task.status}]`,
-    );
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`task create failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdTaskList(
-  runtime: Runtime,
-  options: { goal?: string; status?: string },
-): Promise<number> {
-  try {
-    const tasks = listTasks(runtime.cwd, {
-      goalId: options.goal,
-      status: options.status as TaskStatus | undefined,
-    });
-    const text = tasks.length === 0
-      ? "No tasks recorded in .kxm/tasks/"
-      : tasks.map((t) => `[${t.status}] ${t.id}: ${t.title}${t.assignedWorkflow ? ` -> ${t.assignedWorkflow}` : ""}`).join("\n");
-    print(runtime.io, runtime.json, { ok: true, command: "task list", count: tasks.length, tasks }, text);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`task list failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdTaskGet(runtime: Runtime, taskId: string): Promise<number> {
-  try {
-    const task = getTask(runtime.cwd, taskId);
-    if (!task) {
-      runtime.io.stderr(`Task ${taskId} not found\n`);
-      return 1;
-    }
-    const text = [
-      `Task: ${task.id}`,
-      `Title: ${task.title}`,
-      `Status: ${task.status}`,
-      `Objective: ${task.objective}`,
-      task.assignedWorkflow ? `Workflow: ${task.assignedWorkflow}` : "",
-      task.workflowRunId ? `Active Run: ${task.workflowRunId}` : "",
-      task.trackerSync ? `Tracker: ${task.trackerSync.tracker} (#${task.trackerSync.issueKey}) [${task.trackerSync.syncStatus}]` : "",
-    ].filter(Boolean).join("\n");
-    print(runtime.io, runtime.json, { ok: true, command: "task get", task }, text);
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`task get failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdTaskRun(runtime: Runtime, taskId: string): Promise<number> {
-  try {
-    const task = getTask(runtime.cwd, taskId);
-    if (!task) {
-      runtime.io.stderr(`Task ${taskId} not found\n`);
-      return 1;
-    }
-    const workflow = task.assignedWorkflow ?? "default";
-    const exitCode = await cmdVnextRun(runtime, workflow, [task.objective]);
-    if (exitCode === 0) {
-      updateTaskStatus(runtime.cwd, taskId, "in_progress");
-    }
-    return exitCode;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`task run failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdTaskSync(runtime: Runtime, taskId: string): Promise<number> {
-  try {
-    const synced = syncTaskWithTracker(runtime.cwd, taskId);
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "task sync", task: synced },
-      `Synced task ${taskId} with ${synced.trackerSync?.tracker} #${synced.trackerSync?.issueKey}`,
-    );
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`task sync failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdStudioLayout(runtime: Runtime, workflowPath?: string): Promise<number> {
-  try {
-    const projectRoot = discoverVnextProjectRoot(runtime.cwd) ?? runtime.cwd;
-    let filePath = workflowPath;
-    if (!filePath) {
-      filePath = resolve(projectRoot, ".kxm", "workflows", "default.yaml");
-    }
-    let yamlContent: string;
-    let workflowId = "default";
-    if (existsSync(filePath)) {
-      yamlContent = readFileSync(filePath, "utf8");
-    } else {
-      yamlContent = `schema: kxm.workflow.v1
-description: Feature implementation workflow
-coordinator: coordinator
-limits:
-  maxTransitions: 12
-steps:
-  - id: plan
-    kind: agent
-    agent: planner
-    maxAttempts: 2
-    on:
-      passed: implement
-      failed:
-        target: $terminal
-        terminalStatus: failed
-  - id: implement
-    kind: agent
-    agent: writer
-    maxAttempts: 3
-    on:
-      passed: verify
-      failed:
-        target: $terminal
-        terminalStatus: failed
-  - id: verify
-    kind: gate
-    gate: verify-gate
-    expect: pass
-    maxAttempts: 2
-    on:
-      passed:
-        target: $terminal
-        terminalStatus: completed
-      failed:
-        target: implement
-        maxTransitions: 2
-`;
-    }
-    const parsedYaml = parseYaml(yamlContent) as any;
-    const plan = compileVnextWorkflow({ id: workflowId, value: parsedYaml });
-    const layout = generateStudioLayout(plan);
-    print(runtime.io, runtime.json, { ok: true, command: "studio layout", layout }, JSON.stringify(layout, null, 2));
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    runtime.io.stderr(`studio layout failed: ${message}\n`);
-    return 1;
-  }
-}
-
-async function cmdStudioServe(
-  runtime: Runtime,
-  options: { port?: string; host?: string; token?: string },
-): Promise<number> {
-  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;
-
-  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;
-  }
-
-  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 (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;
-  }
-}
-
-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;
-}
-
-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: "role get", roleId, scope: result.scope, filePath: result.filePath, role: result.role },
-    stringifyYaml(result.role),
-  );
-  return 0;
-}
-
-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;
-  }
-
-  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 (!process.stdin.isTTY) {
-    return undefined;
-  }
-
-  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;
-        }
-      }
-    }
-  }
-
-  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 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,
-    };
-  });
+import { readInstalledKxmVersion } from "./kxm-update.ts";
+import { HubClient } from "./client.ts";
+import {
+  AGENT_COMMANDS_MAP,
+  enforceToolPolicy,
+} from "./commands.ts";
+import { discoverVnextProjectRoot } from "./vnext-config.ts";
+import { ensureVnextSupervisor, vnextRuntimeRequest } from "./vnext-runtime-supervisor.ts";
 
-  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(" ");
+// Submodule imports
+import {
+  print,
+  runtimeFrom,
+  redactConfiguredValues,
+  type CliContext,
+  type CliIo,
+  type CliSpawnResult,
+  type Runtime,
+} from "./cli/types.ts";
 
-  const lines = [
-    `Routing Benchmark Results (task: ${task}, runs: ${runsCount})`,
-    headers,
-  ];
+import {
+  cmdRoleList,
+  cmdRoleGet,
+  cmdRoleAdd,
+  cmdRoleRemove,
+  cmdRoleModify,
+  cmdRoleHosts,
+  cmdRoleSetHost,
+  cmdRoleResume,
+} from "./cli/roles.ts";
 
-  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(" "));
-  }
+import {
+  cmdWorkflowDefinitions,
+  cmdWorkflowAdd,
+  cmdWorkflowRemove,
+  cmdWorkflowModify,
+  cmdWorkflowStart,
+  cmdWorkflowDegrade,
+  cmdWorkflowInspect,
+  cmdSignal,
+  cmdGithubWatch,
+  cmdRetrospectiveExport,
+} from "./cli/workflows.ts";
 
-  print(
-    runtime.io,
-    runtime.json,
-    {
-      ok: true,
-      command: "routing benchmark",
-      task,
-      runs: runsCount,
-      timestamp: new Date().toISOString(),
-      arms,
-    },
-    lines.join("\n"),
-  );
-  return 0;
-}
+import {
+  cmdSuggest,
+  cmdGoalCreate,
+  cmdGoalList,
+  cmdTaskCreate,
+  cmdTaskList,
+  cmdTaskGet,
+  cmdTaskRun,
+  cmdTaskSync,
+  cmdStudioLayout,
+  cmdStudioServe,
+} from "./cli/tasks.ts";
 
-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 });
-    print(runtime.io, runtime.json, { ok: true, command: "workflow start", definitionId, deliveryId, ...response }, `started workflow ${response.runId ?? "accepted"}`);
-    return 0;
-  } catch {
-    print(runtime.io, runtime.json, { ok: false, command: "workflow start", error: "workflow_start_failed" }, "signed workflow start failed");
-    return 1;
-  }
-}
+import {
+  hubContextPost,
+  cmdContextGet,
+  cmdContextRecall,
+  cmdContextState,
+  cmdContextEpisode,
+  cmdContextPromote,
+  cmdContextExplain,
+  cmdContextWikiCompile,
+  cmdContextWikiLint,
+  cmdSkillsCreate,
+  cmdSkillsEvaluate,
+  cmdSkillsPromote,
+  cmdSkillsReject,
+  cmdSkillsList,
+  cmdSkillsVerify,
+  cmdMemoryBrief,
+  cmdMemoryNote,
+  cmdMemorySync,
+} from "./cli/context-skills.ts";
 
-async function cmdWorkflowDegrade(runtime: Runtime, runId: string, stageId: string, options: { requirement?: string; reason?: string }): Promise<number> {
-  const requirementKey = options.requirement?.trim() ?? "";
-  const reason = options.reason?.trim() ?? "";
-  const adminToken = runtime.env.KXM_AUTH_TOKEN?.trim();
-  if (!runId || !stageId || !requirementKey || !reason || !adminToken) {
-    runtime.io.stderr("workflow degrade requires <runId> <stageId>, --requirement, --reason, and KXM_AUTH_TOKEN\n");
-    return 2;
-  }
-  const worker = gateOf(runtime, "degrade");
-  if (runtime.dryRun) {
-    printWorker(
-      runtime,
-      worker,
-      { ok: true, command: "workflow degrade", dryRun: true, runId, stageId, requirementKey },
-      `would approve configured degraded quorum for ${runId}/${stageId}/${requirementKey}`,
-    );
-    return 0;
-  }
-  try {
-    const result = await postWorkflowDegradation({
-      serverUrl: runtime.serverUrl,
-      authToken: adminToken,
-      runId,
-      stageId,
-      requirementKey,
-      reason,
-      fetchImpl: runtime.fetchImpl,
-    });
-    printWorker(
-      runtime,
-      worker,
-      { ok: true, command: "workflow degrade", runId, stageId, requirementKey, ...result },
-      result.duplicate ? "degraded quorum was already approved" : "approved configured degraded quorum",
-    );
-    return 0;
-  } catch {
-    printWorker(
-      runtime,
-      worker,
-      { ok: false, command: "workflow degrade", error: "workflow_degradation_failed", runId, stageId, requirementKey },
-      "workflow degradation approval failed",
-    );
-    return 1;
-  }
-}
+import {
+  cmdVnextInit,
+  cmdVnextMigratePlan,
+  cmdVnextMigrateApply,
+  cmdVnextMigrateVerify,
+  cmdBackup,
+  cmdRestore,
+  cmdVnextTrust,
+  cmdVnextRun,
+  cmdVnextRunStatus,
+  cmdVnextRunDrive,
+  cmdVnextRunCancel,
+  cmdVnextRunList,
+  cmdHarnessList,
+  cmdProducerChange,
+  cmdModelsScreen,
+  cmdProducerList,
+  cmdModelInventoryRefresh,
+  cmdVnextRuntime,
+} from "./cli/vnext.ts";
 
-async function cmdWorkflowInspect(runtime: Runtime, action: "list" | "get", runId?: string): Promise<number> {
-  const dataPath = resolve(runtime.dirs.workdir, runtime.env.KXM_DATA_PATH?.trim() || join(runtime.dirs.state, "kxm.db"));
-  if (action === "get" && !runId) {
-    runtime.io.stderr(`Usage: ${CLI_NAME} workflow get <runId>\n`);
-    return 2;
-  }
-  try {
-    const snapshot = localWorkflowSnapshot(dataPath, runId);
-    if (runId && snapshot.runs.length === 0) {
-      print(runtime.io, runtime.json, { ok: false, command: "workflow get", error: "workflow_not_found" }, "workflow not found");
-      return 1;
-    }
-    const value = action === "get"
-      ? { ok: true, command: "workflow get", run: snapshot.runs[0], journal: snapshot.journal }
-      : { ok: true, command: "workflow list", runs: snapshot.runs };
-    print(runtime.io, runtime.json, value, action === "get" ? `workflow ${runId}` : `${snapshot.runs.length} workflow(s)`);
-    return 0;
-  } catch {
-    print(runtime.io, runtime.json, { ok: false, command: `workflow ${action}`, error: "state_unavailable" }, "local workflow state is unavailable");
-    return 1;
-  }
-}
+import {
+  cmdStatus,
+  cmdDash,
+  cmdHub,
+  cmdHubBind,
+  cmdHubUnbind,
+  cmdWorker,
+  cmdStop,
+  cmdSessionStatus,
+  cmdAuthToken,
+  cmdSessionBrief,
+  cmdSessionStart,
+} from "./cli/hub.ts";
 
-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;
-  }
-  if (status !== "passed" && status !== "warning" && status !== "failed") {
-    runtime.io.stderr("status must be passed, warning, or failed\n");
-    return 2;
-  }
-  let evidence: WorkflowEvidenceInput;
-  try {
-    evidence = parseEvidencePairs(evidenceArgs);
-  } catch (error) {
-    runtime.io.stderr(`${error instanceof Error ? error.message : "invalid evidence"}\n`);
-    return 2;
-  }
-  const worker = gateOf(runtime, "signal");
-  const projectRoot = discoverVnextProjectRoot(runtime.cwd);
-  if (projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
-    if (runtime.dryRun) {
-      printWorker(runtime, worker, { ok: true, command: "signal", runId, signalKey, status, summary, evidence }, "would post signal to vNext run");
-      return 0;
-    }
-    const deliveryId = String(deliveryIdFlag || `cli-signal:${randomUUID()}`);
-    try {
-      const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-      const posted = await vnextRuntimeRequest(
-        supervisor,
-        "POST",
-        `/v1/runs/${encodeURIComponent(runId)}/signal?projectRoot=${encodeURIComponent(projectRoot)}`,
-        { 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;
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : "signal_failed";
-      printWorker(runtime, worker, { ok: false, command: "signal", error: "signal_failed", detail: msg, deliveryId }, "signal to vNext run failed");
-      return 1;
-    }
-  }
+import {
+  cmdExplain,
+  cmdSshInfo,
+  cmdSshRun,
+  cmdSshFile,
+  cmdSshClose,
+  cmdUpdate,
+  cmdValidate,
+  cmdArtifactsExist,
+  cmdImprove,
+  cmdConfigGet,
+  cmdConfigSet,
+  cmdConfigList,
+  cmdCompletion,
+  cmdCompletionInstall,
+  cmdRoutingReport,
+  cmdRoutingBenchmark,
+  maybeOfferCompletionInstall,
+  maybeOfferGuideSetup,
+} from "./cli/system.ts";
+
+// Re-export public API types and functions
+export type { CliIo, CliSpawnResult };
+export { hubContextPost };
 
-  const definitionId = runtime.env.KXM_WORKFLOW_ID?.trim();
-  if (!definitionId) {
-    runtime.io.stderr("signal requires KXM_WORKFLOW_ID\n");
-    return 2;
-  }
-  let signalSecret: string | undefined;
-  try {
-    signalSecret = workflowCredential(runtime, definitionId, "signal");
-  } catch (error) {
-    return reportWorkflowConfigError(runtime, error);
-  }
-  if (!signalSecret) {
-    runtime.io.stderr("signal requires KXM_WORKFLOW_SIGNAL_SECRET when no active definition source is configured\n");
-    return 2;
-  }
-  if (runtime.dryRun) {
-    printWorker(runtime, worker, { ok: true, command: "signal", runId, signalKey, status, summary, evidence }, "would post signed signal");
-    return 0;
-  }
-  const deliveryId = String(deliveryIdFlag || `cli-signal:${randomUUID()}`);
-  try {
-    const posted = await postWorkflowSignal({
-      serverUrl: runtime.serverUrl,
-      definitionId,
-      signalSecret,
-      runId,
-      signalKey,
-      status,
-      summary,
-      evidence,
-      deliveryId,
-      fetchImpl: runtime.fetchImpl,
-    });
-    printWorker(runtime, worker, { ok: true, command: "signal", duplicate: posted.duplicate, deliveryId }, "posted signed signal");
-    return 0;
-  } catch {
-    printWorker(runtime, worker, { ok: false, command: "signal", error: "signal_failed", deliveryId }, "signed signal failed");
-    return 1;
-  }
-}
+const CLI_NAME = "kxm";
+const repoRoot = resolve(fileURLToPath(new URL("../../../", import.meta.url)));
 
-async function cmdGithubWatch(runtime: Runtime, options: {
-  runId?: string;
-  stageId?: string;
-  signalKey?: string;
-  repo?: string;
-  pr?: string;
-  required?: string;
-  timeoutMs?: string;
-  intervalMs?: string;
-  deliveryId?: string;
-}): Promise<number> {
-  const token = runtime.env.GITHUB_TOKEN?.trim() || runtime.env.GH_TOKEN?.trim();
-  const definitionId = runtime.env.KXM_WORKFLOW_ID?.trim();
-  const runId = String(options.runId || "");
-  const stageId = String(options.stageId || "");
-  const signalKey = String(options.signalKey || "");
-  const repo = String(options.repo || "");
-  const pr = Number(options.pr);
-  if (!definitionId || !runId || !stageId || !signalKey || !repo || !Number.isInteger(pr)) {
-    runtime.io.stderr("github watch requires KXM_WORKFLOW_ID, --run-id, --stage-id, --signal-key, --repo, --pr\n");
-    return 2;
-  }
-  let signalSecret: string | undefined;
-  try {
-    signalSecret = workflowCredential(runtime, definitionId, "signal");
-  } catch (error) {
-    return reportWorkflowConfigError(runtime, error);
-  }
-  if (!signalSecret) {
-    runtime.io.stderr("github watch requires KXM_WORKFLOW_SIGNAL_SECRET when no active definition source is configured\n");
-    return 2;
-  }
-  const result = await watchGithubChecks({
-    serverUrl: runtime.serverUrl,
-    definitionId,
-    signalSecret,
-    runId,
-    stageId,
-    signalKey,
-    repo,
-    pr,
-    required: options.required
-      ? [...new Set(String(options.required).split(",").map((name) => name.trim()).filter(Boolean))]
-      : [],
-    timeoutMs: Number(options.timeoutMs || 1_800_000),
-    intervalMs: Number(options.intervalMs || 15_000),
-    ...(options.deliveryId ? { deliveryId: options.deliveryId } : {}),
-    ...(token ? { token } : {}),
-    dryRun: runtime.dryRun,
-    fetchImpl: runtime.fetchImpl,
-    ...(runtime.io.now ? { now: runtime.io.now } : {}),
-    ...(runtime.io.sleep ? { sleep: runtime.io.sleep } : {}),
-  });
-  const worker = gateOf(runtime, "github-watch");
-  const payload = {
-    ok: result.exitCode === 0,
-    command: "github watch",
-    posted: result.posted,
-    status: result.status,
-    summary: result.summary,
-    evidence: result.evidence,
-    deliveryId: result.deliveryId,
-    skipped: result.skipped,
-  };
-  const outcome: WorkerOutcome = result.exitCode === 0
-    ? (result.status === "warning" ? "warning" : "passed")
-    : "failed";
-  if (JSON.stringify(payload).includes(token ?? "___never___") || Object.keys(runtime.env).some((key) => maskEnvName(key) && JSON.stringify(payload).includes(String(runtime.env[key])))) {
-    printWorker(runtime, worker, { ok: false, command: "github watch", error: "redaction_failure" }, "refusing to print a payload that contains a secret");
-    return 1;
-  }
-  printWorker(runtime, worker, payload, result.summary, outcome);
-  return result.exitCode;
-}
+const USAGE_ERROR_CODES = new Set([
+  "commander.help",
+  "commander.helpDisplayed",
+  "commander.unknownCommand",
+  "commander.unknownOption",
+  "commander.missingArgument",
+  "commander.missingMandatoryOptionValue",
+  "commander.invalidArgument",
+  "commander.excessArguments",
+  "commander.variadicArgNotLast",
+  "commander.invalidOptionArgument",
+  "commander.optionMissingArgument",
+]);
 
-async function cmdRetrospectiveExport(runtime: Runtime, runId: string, options: { input?: string; outDir?: string }): Promise<number> {
-  if (!runId) {
-    runtime.io.stderr(`Usage: ${CLI_NAME} workflow export <runId>\n`);
-    return 2;
-  }
-  const snapshotFlag = String(options.input || "");
-  const snapshotPath = snapshotFlag ? resolve(runtime.cwd, snapshotFlag) : "";
-  let snapshot: { run: WorkflowRun; journal: WorkflowJournalEntry[] };
-  try {
-    if (snapshotPath) {
-      if (!existsSync(snapshotPath)) throw new Error("snapshot_missing");
-      snapshot = JSON.parse(readFileSync(snapshotPath, "utf8")) as typeof snapshot;
-    } else {
-      const dataPath = resolve(runtime.dirs.workdir, runtime.env.KXM_DATA_PATH?.trim() || join(runtime.dirs.state, "kxm.db"));
-      const local = localWorkflowSnapshot(dataPath, runId);
-      if (!local.runs[0]) throw new Error("workflow_not_found");
-      snapshot = { run: local.runs[0], journal: local.journal };
-    }
-    if (snapshot.run.id !== runId) throw new Error("run_id_mismatch");
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : "snapshot_invalid";
-    print(runtime.io, runtime.json, { ok: false, command: "retrospective export", error: reason }, "retrospective source is invalid or unavailable");
-    return 1;
-  }
-  const doc = buildRetrospective(snapshot.run, snapshot.journal);
-  const outDir = resolve(runtime.cwd, String(options.outDir || join(runtime.dirs.assets, "retrospectives")));
-  const assetsRoot = resolve(runtime.dirs.assets);
-  const assetsPrefix = `${assetsRoot}${process.platform === "win32" ? "\\" : "/"}`;
-  if (outDir !== assetsRoot && !outDir.startsWith(assetsPrefix)) {
-    print(runtime.io, runtime.json, { ok: false, command: "retrospective export", error: "output_outside_workspace_assets" }, "retrospectives must stay under the workspace assets directory");
-    return 2;
-  }
-  if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "retrospective export", dryRun: true, runId: doc.runId }, `would export ${doc.runId}`);
-    return 0;
-  }
-  const written = writeRetrospective(outDir, doc);
-  print(runtime.io, runtime.json, { ok: true, command: "retrospective export", ...written, reviewDecision: doc.reviewDecision }, `exported ${written.jsonPath}`);
-  return 0;
+function addGlobalOptions(command: Command): Command {
+  return command
+    .option("--json", "Print machine-readable JSON")
+    .option("--dry-run", "Plan without making changes")
+    .option("--workspace <dir>", "Workspace directory");
 }
 
 async function ensureCliClient(runtime: Runtime): Promise<HubClient> {
@@ -3956,10 +336,14 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .option("--project-id <id>", "Stable project ID for controlled provisioning")
     .option("--repository <id=absolute-path>", "Bind a member repository outside Git configuration", (value, previous: string[]) => [...previous, value], [])
     .action(async function initAction(this: Command, options: { name?: string; projectId?: string; repository?: string[] }) {
-      result.code = await cmdVnextInit(runtimeFrom(ctx, this), options);
+      result.code = await cmdVnextInit(runtimeFrom(ctx, this), options, {
+        maybeOfferCompletionInstall,
+        maybeOfferGuideSetup,
+      });
     });
 
-  const migrate = addGlobalOptions(program.command("migrate").description("Plan, apply, and verify legacy JSON configuration migration"));  migrate.helpCommand("help", "Show migrate help");
+  const migrate = addGlobalOptions(program.command("migrate").description("Plan, apply, and verify legacy JSON configuration migration"));
+  migrate.helpCommand("help", "Show migrate help");
   addGlobalOptions(migrate.command("plan").description("Compute the deterministic legacy-to-vNext migration plan without writes"))
     .action(async function migratePlanAction(this: Command) {
       result.code = await cmdVnextMigratePlan(runtimeFrom(ctx, this));
@@ -4379,6 +763,22 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .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");
@@ -4597,6 +997,41 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdRoutingBenchmark(runtimeFrom(ctx, this), options);
     });
 
+  addGlobalOptions(
+    program
+      .command("explain")
+      .description("Pre-flight context footprint and token cost inspection for workflow modes")
+      .option("--mode <name>", "Major mode (coder, planner, auditor, browser)", "coder")
+      .option("--domains <list>", "Comma-separated domain modules (git, k8s, database, browser)")
+      .option("--model <id>", "Target model identifier (e.g. grok/grok-4.6, claude/fable)")
+  ).action(async function explainAction(this: Command, options: { mode?: string; domains?: string; model?: string }) {
+    result.code = await cmdExplain(runtimeFrom(ctx, this), options);
+  });
+
+  const sshCmd = addGlobalOptions(program.command("ssh").description("Multiplexed remote SSH execution and worker orchestration"));
+  sshCmd.helpCommand("help", "Show ssh help");
+  addGlobalOptions(sshCmd.command("info [host]").description("Discover SSH host aliases and parameters safely without opening sockets"))
+    .action(async function sshInfoAction(this: Command, host?: string) {
+      result.code = await cmdSshInfo(runtimeFrom(ctx, this), host);
+    });
+  addGlobalOptions(sshCmd.command("run <host> <command...>").description("Execute a command on a remote SSH host via multiplexed ControlMaster socket"))
+    .option("--sudo", "Execute remote command with sudo privileges")
+    .action(async function sshRunAction(this: Command, host: string, commandParts: string[], options: { sudo?: boolean }) {
+      result.code = await cmdSshRun(runtimeFrom(ctx, this), host, commandParts, options);
+    });
+  addGlobalOptions(sshCmd.command("file <host> <path>").description("Read or write remote files over SSH"))
+    .option("--content <text>", "Content to write to remote file")
+    .option("--read", "Read remote file content")
+    .option("--append", "Append content to remote file")
+    .option("--sudo", "Use sudo privileges on remote file")
+    .action(async function sshFileAction(this: Command, host: string, filePath: string, options: { content?: string; read?: boolean; append?: boolean; sudo?: boolean }) {
+      result.code = await cmdSshFile(runtimeFrom(ctx, this), host, filePath, options);
+    });
+  addGlobalOptions(sshCmd.command("close <host>").description("Close active ControlMaster socket for an SSH host"))
+    .action(async function sshCloseAction(this: Command, host: string) {
+      result.code = await cmdSshClose(runtimeFrom(ctx, this), host);
+    });
+
   const hub = addGlobalOptions(program.command("hub").description("Start, inspect, and stop the local KXM hub"));
   hub.helpCommand("help", "Show hub help");
   addGlobalOptions(hub.command("view").description("Check hub /health and /ready")).action(bind(cmdStatus));
@@ -4633,9 +1068,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"))
@@ -4712,9 +1162,6 @@ function mapCommanderError(error: CommanderError): number {
 
 const MESH_REMOVED_TEXT = "kxm mesh was removed. Use kxm init, kxm hub start|view|stop, and node scripts/smoke-multi-pi.mjs (KXM_SMOKE=1).";
 
-/** Detect `mesh` as the first command token after recognized nonterminal global
- * options so `kxm --json mesh` fails closed. `--version`, `--help`, and unknown
- * options are left for Commander. */
 function removedMeshInvocation(argv: string[]): { invoked: boolean; json: boolean } {
   let json = false;
   let invoked = false;