evolcore 0.0.25 → 0.0.26

package/kits/migrations/migrate-role-config-v4.mjs

@@ -1,454 +1,454 @@
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import Ajv from 'ajv';
-
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const SCHEMA_DIR = path.resolve(SCRIPT_DIR, '..', 'schemas');
-const PERMISSION_MODES = new Set(['readonly', 'auto', 'request', 'bypass']);
-const MODEL_FIELD_RE = /^baseagents\.[a-z0-9_-]+\.model$/;
-const ROLE_ENUM_FIELD_VALUES = {
-  'chatmode.private': new Set(['interactive', 'proactive']),
-  'chatmode.group': new Set(['interactive', 'proactive']),
-  'baseagents.claude.effort': new Set(['auto', 'low', 'medium', 'high', 'xhigh', 'max']),
-  'baseagents.codex.reasoning': new Set(['auto', 'low', 'medium', 'high', 'xhigh']),
-};
-const BUILTIN_ROLES = new Set(['member', 'visitor']);
-const ROLE_POLICY_KEYS = new Set(['defaultRoles', 'definitions']);
-
-function usage() {
-  return `Usage:
-  node kits/migrations/migrate-role-config-v4.mjs [--home <EVOLCORE_HOME>] [--json]
-  node kits/migrations/migrate-role-config-v4.mjs --apply [--home <EVOLCORE_HOME>] [--json]
-
-The default mode is dry-run. Stop the EvolCore daemon before running this migration.
-Every applied migration creates a backup under:
-  <EVOLCORE_HOME>/backups/role-v4-migration/<timestamp>/`;
-}
-
-function parseArgs(argv) {
-  const options = { apply: false, json: false, home: undefined };
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--apply') options.apply = true;
-    else if (arg === '--json') options.json = true;
-    else if (arg === '--help' || arg === '-h') options.help = true;
-    else if (arg === '--home') {
-      const value = argv[++i];
-      if (!value) throw new Error('--home requires a path');
-      options.home = value;
-    } else {
-      throw new Error(`Unknown argument: ${arg}`);
-    }
-  }
-  return options;
-}
-
-function resolveHome(explicitHome) {
-  if (explicitHome) return path.resolve(explicitHome);
-  if (process.env.EVOLCORE_HOME) return path.resolve(process.env.EVOLCORE_HOME);
-  if (fs.existsSync(path.join(process.cwd(), 'agents'))) return process.cwd();
-  return path.join(os.homedir(), '.evolcore');
-}
-
-function loadValidators() {
-  const ajv = new Ajv({ allErrors: true, strict: false });
-  const load = name => JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, name), 'utf8'));
-  return {
-    agent: ajv.compile(load('agent-config.schema.4.json')),
-    relation: ajv.compile(load('relation-config.schema.4.json')),
-  };
-}
-
-function isRecord(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function isValidAid(name) {
-  const labels = name.split('.');
-  return labels.length >= 3
-    && labels.every(label => /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label));
-}
-
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
-function normalizePermissionMode(value) {
-  if (typeof value !== 'string') return null;
-  if (PERMISSION_MODES.has(value)) return value;
-  if (value === 'edit') return 'request';
-  if (value === 'plan' || value === 'noask') return 'readonly';
-  return null;
-}
-
-function wildcardMatch(pattern, value) {
-  return pattern === '*' || (pattern.endsWith('*') ? value.startsWith(pattern.slice(0, -1)) : pattern === value);
-}
-
-function migratePermissionModePolicy(value, fallback) {
-  const policy = isRecord(value) ? value : {};
-  const defaultValue = normalizePermissionMode(policy.default) ?? fallback;
-  const allowedValues = Array.isArray(policy.allowedValues)
-    ? [...new Set(policy.allowedValues.map(normalizePermissionMode).filter(Boolean))]
-    : [];
-  if (allowedValues.length && !allowedValues.includes(defaultValue)) allowedValues.unshift(defaultValue);
-  return {
-    default: defaultValue,
-    allowOverride: false,
-    ...(allowedValues.length ? { allowedValues } : {}),
-    ...(typeof policy.reason === 'string' ? { reason: policy.reason } : {}),
-  };
-}
-
-function migrateModelPolicy(field, value) {
-  if (!isRecord(value)) throw new Error(`${field} must be an object`);
-  const defaultModel = typeof value.default === 'string' ? value.default.trim() : '';
-  if (!defaultModel) throw new Error(`${field}.default must be a non-empty string`);
-  const allowedModels = Array.isArray(value.allowedModels)
-    ? [...new Set(value.allowedModels.filter(item => typeof item === 'string' && item.trim()).map(item => item.trim()))]
-    : [];
-  if (!allowedModels.some(pattern => wildcardMatch(pattern, defaultModel))) allowedModels.unshift(defaultModel);
-  return {
-    default: defaultModel,
-    allowOverride: typeof value.allowOverride === 'boolean' ? value.allowOverride : false,
-    allowedModels,
-    ...(typeof value.reason === 'string' ? { reason: value.reason } : {}),
-  };
-}
-
-function migrateEnumPolicy(field, value) {
-  const allowedOptions = ROLE_ENUM_FIELD_VALUES[field];
-  if (!isRecord(value)) throw new Error(field + ' must be an object');
-  const defaultValue = typeof value.default === 'string' ? value.default.trim() : '';
-  if (!allowedOptions.has(defaultValue)) {
-    throw new Error(field + '.default has unsupported value: ' + String(value.default));
-  }
-  const hasAllowedValues = Array.isArray(value.allowedValues);
-  const allowedValues = hasAllowedValues
-    ? [...new Set(value.allowedValues
-      .filter(item => typeof item === 'string')
-      .map(item => item.trim())
-      .filter(item => allowedOptions.has(item)))]
-    : [];
-  if (hasAllowedValues && !allowedValues.includes(defaultValue)) allowedValues.unshift(defaultValue);
-  return {
-    default: defaultValue,
-    allowOverride: typeof value.allowOverride === 'boolean' ? value.allowOverride : false,
-    ...(hasAllowedValues ? { allowedValues } : {}),
-    ...(typeof value.reason === 'string' ? { reason: value.reason } : {}),
-  };
-}
-
-function migrateRoleDefinition(roleId, definition, legacyAgentMode, summary) {
-  if (!isRecord(definition)) throw new Error(`roles.definitions.${roleId} must be an object`);
-  if (typeof definition.description !== 'string') throw new Error(`roles.definitions.${roleId}.description must be a string`);
-  if (!isRecord(definition.permissions)) throw new Error(`roles.definitions.${roleId}.permissions must be an object`);
-  if (definition.commandPermissions !== undefined && !isRecord(definition.commandPermissions)) {
-    throw new Error(`roles.definitions.${roleId}.commandPermissions must be an object`);
-  }
-
-  const permissions = definition.permissions;
-  const ownMode = isRecord(permissions.permissionMode)
-    ? normalizePermissionMode(permissions.permissionMode.default)
-    : null;
-  const fallbackMode = ownMode
-    ?? (roleId === 'member' ? 'auto' : roleId === 'visitor' ? 'readonly' : legacyAgentMode)
-    ?? 'readonly';
-  const migratedPermissions = {
-    permissionMode: migratePermissionModePolicy(permissions.permissionMode, fallbackMode),
-  };
-  const commandPermissions = { ...(definition.commandPermissions ?? {}) };
-
-  for (const [field, policy] of Object.entries(permissions)) {
-    if (field === 'permissionMode') continue;
-    if (MODEL_FIELD_RE.test(field)) {
-      migratedPermissions[field] = migrateModelPolicy(`roles.definitions.${roleId}.permissions.${field}`, policy);
-      continue;
-    }
-    if (Object.prototype.hasOwnProperty.call(ROLE_ENUM_FIELD_VALUES, field)) {
-      migratedPermissions[field] = migrateEnumPolicy(field, policy);
-      continue;
-    }
-    if (isRecord(policy) && typeof policy.allow === 'boolean') {
-      if (field !== 'permission.update' && !Object.prototype.hasOwnProperty.call(commandPermissions, field)) {
-        commandPermissions[field] = clone(policy);
-        summary.movedCommandPermissions += 1;
-      }
-    } else {
-      summary.droppedUnsupportedRoleConstraints += 1;
-    }
-  }
-
-  if (Object.prototype.hasOwnProperty.call(commandPermissions, 'permission.update')) {
-    delete commandPermissions['permission.update'];
-    summary.removedObsoletePermissionUpdates += 1;
-  }
-
-  const migrated = {
-    ...definition,
-    permissions: migratedPermissions,
-  };
-  if (Object.keys(commandPermissions).length) migrated.commandPermissions = commandPermissions;
-  else delete migrated.commandPermissions;
-  if (JSON.stringify(definition) !== JSON.stringify(migrated)) summary.normalizedRoleDefinitions += 1;
-  return migrated;
-}
-
-function legacyRoleDescription(roleId) {
-  if (roleId === 'member') return 'Trusted user with own-scope access';
-  if (roleId === 'visitor') return 'Low-trust visitor with minimal own-scope access';
-  return `Migrated legacy role: ${roleId}`;
-}
-
-function migrateLegacyV2Role(roleId, override, legacyAgentMode, summary) {
-  if (!isRecord(override)) throw new Error(`roles.${roleId} must be an object`);
-
-  const explicitMode = override.permissionMode === undefined
-    ? null
-    : normalizePermissionMode(override.permissionMode);
-  if (override.permissionMode !== undefined && !explicitMode) {
-    throw new Error(`roles.${roleId}.permissionMode has unsupported value: ${String(override.permissionMode)}`);
-  }
-  const fallbackMode = explicitMode
-    ?? (roleId === 'member' ? 'auto' : roleId === 'visitor' ? 'readonly' : legacyAgentMode)
-    ?? 'readonly';
-  const permissions = {
-    permissionMode: {
-      default: fallbackMode,
-      allowOverride: false,
-    },
-  };
-
-  if (override.baseagents !== undefined && !isRecord(override.baseagents)) {
-    throw new Error(`roles.${roleId}.baseagents must be an object`);
-  }
-  for (const [baseagentId, baseagentOverride] of Object.entries(override.baseagents ?? {})) {
-    if (!isRecord(baseagentOverride)) {
-      summary.droppedUnsupportedRoleConstraints += 1;
-      continue;
-    }
-    for (const [field, value] of Object.entries(baseagentOverride)) {
-      if (field === 'model') {
-        if (typeof value !== 'string' || !value.trim()) {
-          throw new Error(`roles.${roleId}.baseagents.${baseagentId}.model must be a non-empty string`);
-        }
-        const model = value.trim();
-        permissions[`baseagents.${baseagentId}.model`] = {
-          default: model,
-          allowOverride: false,
-          allowedModels: [model],
-        };
-        continue;
-      }
-
-      const roleField = 'baseagents.' + baseagentId + '.' + field;
-      const allowedOptions = ROLE_ENUM_FIELD_VALUES[roleField];
-      if (allowedOptions) {
-        if (typeof value !== 'string' || !allowedOptions.has(value.trim())) {
-          throw new Error('roles.' + roleId + '.baseagents.' + baseagentId + '.' + field
-            + ' has unsupported value: ' + String(value));
-        }
-        const defaultValue = value.trim();
-        permissions[roleField] = {
-          default: defaultValue,
-          allowOverride: false,
-          allowedValues: [defaultValue],
-        };
-        continue;
-      }
-
-      summary.droppedUnsupportedRoleConstraints += 1;
-    }
-  }
-
-  summary.migratedLegacyV2Roles += 1;
-  return {
-    description: legacyRoleDescription(roleId),
-    permissions,
-  };
-}
-
-function removeLegacySessionRenewModel(config, summary) {
-  if (!isRecord(config.session_renew) || !Object.prototype.hasOwnProperty.call(config.session_renew, 'model')) return;
-  config.session_renew = { ...config.session_renew };
-  delete config.session_renew.model;
-  summary.removedSessionRenewModels += 1;
-}
-
-function migrateAgentConfig(input, summary) {
-  if (!isRecord(input)) throw new Error('Agent config must be an object');
-  if (typeof input.$schema_version === 'number' && input.$schema_version > 4) {
-    throw new Error(`Unsupported future Agent schema version: ${input.$schema_version}`);
-  }
-  const output = clone(input);
-  const legacyAgentMode = normalizePermissionMode(output.permissionMode);
-  if (Object.prototype.hasOwnProperty.call(output, 'permissionMode')) {
-    delete output.permissionMode;
-    summary.removedAgentPermissionModes += 1;
-  }
-  removeLegacySessionRenewModel(output, summary);
-  output.$schema_version = 4;
-
-  if (output.roles !== undefined && !isRecord(output.roles)) throw new Error('roles must be an object');
-  if (isRecord(output.roles)) {
-    if (output.roles.definitions !== undefined && !isRecord(output.roles.definitions)) {
-      throw new Error('roles.definitions must be an object');
-    }
-    const definitions = { ...(output.roles.definitions ?? {}) };
-    for (const [roleId, override] of Object.entries(output.roles)) {
-      if (ROLE_POLICY_KEYS.has(roleId)) continue;
-      if (Object.prototype.hasOwnProperty.call(definitions, roleId)) {
-        throw new Error(`roles.${roleId} conflicts with roles.definitions.${roleId}`);
-      }
-      definitions[roleId] = migrateLegacyV2Role(roleId, override, legacyAgentMode, summary);
-    }
-
-    const migratedRoles = {};
-    if (output.roles.defaultRoles !== undefined) migratedRoles.defaultRoles = output.roles.defaultRoles;
-    if (Object.keys(definitions).length) {
-      migratedRoles.definitions = definitions;
-      for (const [roleId, definition] of Object.entries(migratedRoles.definitions)) {
-        migratedRoles.definitions[roleId] = migrateRoleDefinition(roleId, definition, legacyAgentMode, summary);
-      }
-    }
-    output.roles = migratedRoles;
-  }
-
-  const roleNames = new Set([...BUILTIN_ROLES, ...Object.keys(output.roles?.definitions ?? {})]);
-  for (const scene of ['private', 'group']) {
-    const role = output.roles?.defaultRoles?.[scene];
-    if (role !== undefined && role !== null && !roleNames.has(role)) {
-      throw new Error(`roles.defaultRoles.${scene} references unknown role: ${String(role)}`);
-    }
-  }
-  return { output, roleNames };
-}
-
-function migrateRelationConfig(input, roleNames, summary) {
-  if (!isRecord(input)) throw new Error('Relation config must be an object');
-  if (typeof input.$schema_version === 'number' && input.$schema_version > 4) {
-    throw new Error(`Unsupported future Relation schema version: ${input.$schema_version}`);
-  }
-  const output = clone(input);
-  const legacyRoles = isRecord(output.roles) ? output.roles : null;
-  const assigned = legacyRoles && Object.prototype.hasOwnProperty.call(legacyRoles, 'assigned')
-    ? legacyRoles.assigned
-    : undefined;
-  if (assigned !== undefined && output.role !== undefined && assigned !== output.role) {
-    throw new Error(`role conflicts with legacy roles.assigned (${String(output.role)} != ${String(assigned)})`);
-  }
-  if (output.role === undefined && assigned !== undefined) {
-    output.role = assigned;
-    summary.migratedRelationAssignments += 1;
-  }
-  if (isRecord(legacyRoles?.members)) {
-    summary.discardedMemberOverrides += Object.keys(legacyRoles.members).length;
-  }
-  if (Object.prototype.hasOwnProperty.call(output, 'roles')) delete output.roles;
-  if (Object.prototype.hasOwnProperty.call(output, 'permissionMode')) {
-    delete output.permissionMode;
-    summary.removedRelationPermissionModes += 1;
-  }
-  removeLegacySessionRenewModel(output, summary);
-  output.$schema_version = 4;
-  if (output.role !== undefined && output.role !== null && !roleNames.has(output.role)) {
-    throw new Error(`role references unknown role: ${String(output.role)}`);
-  }
-  return output;
-}
-
-function readJson(file) {
-  try {
-    const text = fs.readFileSync(file, 'utf8');
-    return { value: JSON.parse(text), text };
-  } catch (error) {
-    throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-
-function walkRelationConfigs(root) {
-  if (!fs.existsSync(root)) return [];
-  const files = [];
-  const visit = dir => {
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) visit(full);
-      else if (entry.isFile() && entry.name === 'config.json') files.push(full);
-    }
-  };
-  visit(root);
-  return files.sort();
-}
-
-function validationError(validate) {
-  return (validate.errors ?? []).map(error => {
-    const extra = error.params?.additionalProperty ? ` (${error.params.additionalProperty})` : '';
-    return `${error.instancePath || '/'} ${error.message}${extra}`;
-  }).join('; ');
-}
-
-function planMigration(home) {
-  const agentsRoot = path.join(home, 'agents');
-  if (!fs.existsSync(agentsRoot)) throw new Error(`Agents directory not found: ${agentsRoot}`);
-  const validators = loadValidators();
-  const summary = {
-    agentsScanned: 0,
-    relationsScanned: 0,
-    agentsChanged: 0,
-    relationsChanged: 0,
-    removedAgentPermissionModes: 0,
-    removedRelationPermissionModes: 0,
-    migratedRelationAssignments: 0,
-    discardedMemberOverrides: 0,
-    migratedLegacyV2Roles: 0,
-    normalizedRoleDefinitions: 0,
-    movedCommandPermissions: 0,
-    droppedUnsupportedRoleConstraints: 0,
-    removedObsoletePermissionUpdates: 0,
-    removedSessionRenewModels: 0,
-  };
-  const changes = [];
-
-  for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-    if (!entry.isDirectory() || !isValidAid(entry.name)) continue;
-    const agentDir = path.join(agentsRoot, entry.name);
-    const agentFile = path.join(agentDir, 'config.json');
-    if (!fs.existsSync(agentFile)) continue;
-    summary.agentsScanned += 1;
-    const { value: agentInput, text: agentText } = readJson(agentFile);
-    const { output: agentOutput, roleNames } = migrateAgentConfig(agentInput, summary);
-    if (!validators.agent(agentOutput)) throw new Error(`${agentFile}: ${validationError(validators.agent)}`);
-    if (JSON.stringify(agentInput) !== JSON.stringify(agentOutput)) {
-      changes.push(changeRecord(home, agentFile, 'agent', agentText, agentOutput));
-      summary.agentsChanged += 1;
-    }
-
-    for (const relationFile of walkRelationConfigs(path.join(agentDir, 'relations'))) {
-      summary.relationsScanned += 1;
-      const { value: relationInput, text: relationText } = readJson(relationFile);
-      const relationOutput = migrateRelationConfig(relationInput, roleNames, summary);
-      if (!validators.relation(relationOutput)) throw new Error(`${relationFile}: ${validationError(validators.relation)}`);
-      if (JSON.stringify(relationInput) !== JSON.stringify(relationOutput)) {
-        changes.push(changeRecord(home, relationFile, 'relation', relationText, relationOutput));
-        summary.relationsChanged += 1;
-      }
-    }
-  }
-  return { home, changes, summary };
-}
-
-function changeRecord(home, file, kind, beforeText, after) {
-  return {
-    file,
-    relative: path.relative(home, file),
-    kind,
-    beforeText,
-    afterText: `${JSON.stringify(after, null, 2)}\n`,
-  };
-}
-
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import Ajv from 'ajv';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(SCRIPT_DIR, '..', 'schemas');
+const PERMISSION_MODES = new Set(['readonly', 'auto', 'request', 'bypass']);
+const MODEL_FIELD_RE = /^baseagents\.[a-z0-9_-]+\.model$/;
+const ROLE_ENUM_FIELD_VALUES = {
+  'chatmode.private': new Set(['interactive', 'proactive']),
+  'chatmode.group': new Set(['interactive', 'proactive']),
+  'baseagents.claude.effort': new Set(['auto', 'low', 'medium', 'high', 'xhigh', 'max']),
+  'baseagents.codex.reasoning': new Set(['auto', 'low', 'medium', 'high', 'xhigh']),
+};
+const BUILTIN_ROLES = new Set(['member', 'visitor']);
+const ROLE_POLICY_KEYS = new Set(['defaultRoles', 'definitions']);
+
+function usage() {
+  return `Usage:
+  node kits/migrations/migrate-role-config-v4.mjs [--home <EVOLCORE_HOME>] [--json]
+  node kits/migrations/migrate-role-config-v4.mjs --apply [--home <EVOLCORE_HOME>] [--json]
+
+The default mode is dry-run. Stop the EvolCore daemon before running this migration.
+Every applied migration creates a backup under:
+  <EVOLCORE_HOME>/backups/role-v4-migration/<timestamp>/`;
+}
+
+function parseArgs(argv) {
+  const options = { apply: false, json: false, home: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--apply') options.apply = true;
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--home') {
+      const value = argv[++i];
+      if (!value) throw new Error('--home requires a path');
+      options.home = value;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function resolveHome(explicitHome) {
+  if (explicitHome) return path.resolve(explicitHome);
+  if (process.env.EVOLCORE_HOME) return path.resolve(process.env.EVOLCORE_HOME);
+  if (fs.existsSync(path.join(process.cwd(), 'agents'))) return process.cwd();
+  return path.join(os.homedir(), '.evolcore');
+}
+
+function loadValidators() {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const load = name => JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, name), 'utf8'));
+  return {
+    agent: ajv.compile(load('agent-config.schema.4.json')),
+    relation: ajv.compile(load('relation-config.schema.4.json')),
+  };
+}
+
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isValidAid(name) {
+  const labels = name.split('.');
+  return labels.length >= 3
+    && labels.every(label => /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label));
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizePermissionMode(value) {
+  if (typeof value !== 'string') return null;
+  if (PERMISSION_MODES.has(value)) return value;
+  if (value === 'edit') return 'request';
+  if (value === 'plan' || value === 'noask') return 'readonly';
+  return null;
+}
+
+function wildcardMatch(pattern, value) {
+  return pattern === '*' || (pattern.endsWith('*') ? value.startsWith(pattern.slice(0, -1)) : pattern === value);
+}
+
+function migratePermissionModePolicy(value, fallback) {
+  const policy = isRecord(value) ? value : {};
+  const defaultValue = normalizePermissionMode(policy.default) ?? fallback;
+  const allowedValues = Array.isArray(policy.allowedValues)
+    ? [...new Set(policy.allowedValues.map(normalizePermissionMode).filter(Boolean))]
+    : [];
+  if (allowedValues.length && !allowedValues.includes(defaultValue)) allowedValues.unshift(defaultValue);
+  return {
+    default: defaultValue,
+    allowOverride: false,
+    ...(allowedValues.length ? { allowedValues } : {}),
+    ...(typeof policy.reason === 'string' ? { reason: policy.reason } : {}),
+  };
+}
+
+function migrateModelPolicy(field, value) {
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  const defaultModel = typeof value.default === 'string' ? value.default.trim() : '';
+  if (!defaultModel) throw new Error(`${field}.default must be a non-empty string`);
+  const allowedModels = Array.isArray(value.allowedModels)
+    ? [...new Set(value.allowedModels.filter(item => typeof item === 'string' && item.trim()).map(item => item.trim()))]
+    : [];
+  if (!allowedModels.some(pattern => wildcardMatch(pattern, defaultModel))) allowedModels.unshift(defaultModel);
+  return {
+    default: defaultModel,
+    allowOverride: typeof value.allowOverride === 'boolean' ? value.allowOverride : false,
+    allowedModels,
+    ...(typeof value.reason === 'string' ? { reason: value.reason } : {}),
+  };
+}
+
+function migrateEnumPolicy(field, value) {
+  const allowedOptions = ROLE_ENUM_FIELD_VALUES[field];
+  if (!isRecord(value)) throw new Error(field + ' must be an object');
+  const defaultValue = typeof value.default === 'string' ? value.default.trim() : '';
+  if (!allowedOptions.has(defaultValue)) {
+    throw new Error(field + '.default has unsupported value: ' + String(value.default));
+  }
+  const hasAllowedValues = Array.isArray(value.allowedValues);
+  const allowedValues = hasAllowedValues
+    ? [...new Set(value.allowedValues
+      .filter(item => typeof item === 'string')
+      .map(item => item.trim())
+      .filter(item => allowedOptions.has(item)))]
+    : [];
+  if (hasAllowedValues && !allowedValues.includes(defaultValue)) allowedValues.unshift(defaultValue);
+  return {
+    default: defaultValue,
+    allowOverride: typeof value.allowOverride === 'boolean' ? value.allowOverride : false,
+    ...(hasAllowedValues ? { allowedValues } : {}),
+    ...(typeof value.reason === 'string' ? { reason: value.reason } : {}),
+  };
+}
+
+function migrateRoleDefinition(roleId, definition, legacyAgentMode, summary) {
+  if (!isRecord(definition)) throw new Error(`roles.definitions.${roleId} must be an object`);
+  if (typeof definition.description !== 'string') throw new Error(`roles.definitions.${roleId}.description must be a string`);
+  if (!isRecord(definition.permissions)) throw new Error(`roles.definitions.${roleId}.permissions must be an object`);
+  if (definition.commandPermissions !== undefined && !isRecord(definition.commandPermissions)) {
+    throw new Error(`roles.definitions.${roleId}.commandPermissions must be an object`);
+  }
+
+  const permissions = definition.permissions;
+  const ownMode = isRecord(permissions.permissionMode)
+    ? normalizePermissionMode(permissions.permissionMode.default)
+    : null;
+  const fallbackMode = ownMode
+    ?? (roleId === 'member' ? 'auto' : roleId === 'visitor' ? 'readonly' : legacyAgentMode)
+    ?? 'readonly';
+  const migratedPermissions = {
+    permissionMode: migratePermissionModePolicy(permissions.permissionMode, fallbackMode),
+  };
+  const commandPermissions = { ...(definition.commandPermissions ?? {}) };
+
+  for (const [field, policy] of Object.entries(permissions)) {
+    if (field === 'permissionMode') continue;
+    if (MODEL_FIELD_RE.test(field)) {
+      migratedPermissions[field] = migrateModelPolicy(`roles.definitions.${roleId}.permissions.${field}`, policy);
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(ROLE_ENUM_FIELD_VALUES, field)) {
+      migratedPermissions[field] = migrateEnumPolicy(field, policy);
+      continue;
+    }
+    if (isRecord(policy) && typeof policy.allow === 'boolean') {
+      if (field !== 'permission.update' && !Object.prototype.hasOwnProperty.call(commandPermissions, field)) {
+        commandPermissions[field] = clone(policy);
+        summary.movedCommandPermissions += 1;
+      }
+    } else {
+      summary.droppedUnsupportedRoleConstraints += 1;
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(commandPermissions, 'permission.update')) {
+    delete commandPermissions['permission.update'];
+    summary.removedObsoletePermissionUpdates += 1;
+  }
+
+  const migrated = {
+    ...definition,
+    permissions: migratedPermissions,
+  };
+  if (Object.keys(commandPermissions).length) migrated.commandPermissions = commandPermissions;
+  else delete migrated.commandPermissions;
+  if (JSON.stringify(definition) !== JSON.stringify(migrated)) summary.normalizedRoleDefinitions += 1;
+  return migrated;
+}
+
+function legacyRoleDescription(roleId) {
+  if (roleId === 'member') return 'Trusted user with own-scope access';
+  if (roleId === 'visitor') return 'Low-trust visitor with minimal own-scope access';
+  return `Migrated legacy role: ${roleId}`;
+}
+
+function migrateLegacyV2Role(roleId, override, legacyAgentMode, summary) {
+  if (!isRecord(override)) throw new Error(`roles.${roleId} must be an object`);
+
+  const explicitMode = override.permissionMode === undefined
+    ? null
+    : normalizePermissionMode(override.permissionMode);
+  if (override.permissionMode !== undefined && !explicitMode) {
+    throw new Error(`roles.${roleId}.permissionMode has unsupported value: ${String(override.permissionMode)}`);
+  }
+  const fallbackMode = explicitMode
+    ?? (roleId === 'member' ? 'auto' : roleId === 'visitor' ? 'readonly' : legacyAgentMode)
+    ?? 'readonly';
+  const permissions = {
+    permissionMode: {
+      default: fallbackMode,
+      allowOverride: false,
+    },
+  };
+
+  if (override.baseagents !== undefined && !isRecord(override.baseagents)) {
+    throw new Error(`roles.${roleId}.baseagents must be an object`);
+  }
+  for (const [baseagentId, baseagentOverride] of Object.entries(override.baseagents ?? {})) {
+    if (!isRecord(baseagentOverride)) {
+      summary.droppedUnsupportedRoleConstraints += 1;
+      continue;
+    }
+    for (const [field, value] of Object.entries(baseagentOverride)) {
+      if (field === 'model') {
+        if (typeof value !== 'string' || !value.trim()) {
+          throw new Error(`roles.${roleId}.baseagents.${baseagentId}.model must be a non-empty string`);
+        }
+        const model = value.trim();
+        permissions[`baseagents.${baseagentId}.model`] = {
+          default: model,
+          allowOverride: false,
+          allowedModels: [model],
+        };
+        continue;
+      }
+
+      const roleField = 'baseagents.' + baseagentId + '.' + field;
+      const allowedOptions = ROLE_ENUM_FIELD_VALUES[roleField];
+      if (allowedOptions) {
+        if (typeof value !== 'string' || !allowedOptions.has(value.trim())) {
+          throw new Error('roles.' + roleId + '.baseagents.' + baseagentId + '.' + field
+            + ' has unsupported value: ' + String(value));
+        }
+        const defaultValue = value.trim();
+        permissions[roleField] = {
+          default: defaultValue,
+          allowOverride: false,
+          allowedValues: [defaultValue],
+        };
+        continue;
+      }
+
+      summary.droppedUnsupportedRoleConstraints += 1;
+    }
+  }
+
+  summary.migratedLegacyV2Roles += 1;
+  return {
+    description: legacyRoleDescription(roleId),
+    permissions,
+  };
+}
+
+function removeLegacySessionRenewModel(config, summary) {
+  if (!isRecord(config.session_renew) || !Object.prototype.hasOwnProperty.call(config.session_renew, 'model')) return;
+  config.session_renew = { ...config.session_renew };
+  delete config.session_renew.model;
+  summary.removedSessionRenewModels += 1;
+}
+
+function migrateAgentConfig(input, summary) {
+  if (!isRecord(input)) throw new Error('Agent config must be an object');
+  if (typeof input.$schema_version === 'number' && input.$schema_version > 4) {
+    throw new Error(`Unsupported future Agent schema version: ${input.$schema_version}`);
+  }
+  const output = clone(input);
+  const legacyAgentMode = normalizePermissionMode(output.permissionMode);
+  if (Object.prototype.hasOwnProperty.call(output, 'permissionMode')) {
+    delete output.permissionMode;
+    summary.removedAgentPermissionModes += 1;
+  }
+  removeLegacySessionRenewModel(output, summary);
+  output.$schema_version = 4;
+
+  if (output.roles !== undefined && !isRecord(output.roles)) throw new Error('roles must be an object');
+  if (isRecord(output.roles)) {
+    if (output.roles.definitions !== undefined && !isRecord(output.roles.definitions)) {
+      throw new Error('roles.definitions must be an object');
+    }
+    const definitions = { ...(output.roles.definitions ?? {}) };
+    for (const [roleId, override] of Object.entries(output.roles)) {
+      if (ROLE_POLICY_KEYS.has(roleId)) continue;
+      if (Object.prototype.hasOwnProperty.call(definitions, roleId)) {
+        throw new Error(`roles.${roleId} conflicts with roles.definitions.${roleId}`);
+      }
+      definitions[roleId] = migrateLegacyV2Role(roleId, override, legacyAgentMode, summary);
+    }
+
+    const migratedRoles = {};
+    if (output.roles.defaultRoles !== undefined) migratedRoles.defaultRoles = output.roles.defaultRoles;
+    if (Object.keys(definitions).length) {
+      migratedRoles.definitions = definitions;
+      for (const [roleId, definition] of Object.entries(migratedRoles.definitions)) {
+        migratedRoles.definitions[roleId] = migrateRoleDefinition(roleId, definition, legacyAgentMode, summary);
+      }
+    }
+    output.roles = migratedRoles;
+  }
+
+  const roleNames = new Set([...BUILTIN_ROLES, ...Object.keys(output.roles?.definitions ?? {})]);
+  for (const scene of ['private', 'group']) {
+    const role = output.roles?.defaultRoles?.[scene];
+    if (role !== undefined && role !== null && !roleNames.has(role)) {
+      throw new Error(`roles.defaultRoles.${scene} references unknown role: ${String(role)}`);
+    }
+  }
+  return { output, roleNames };
+}
+
+function migrateRelationConfig(input, roleNames, summary) {
+  if (!isRecord(input)) throw new Error('Relation config must be an object');
+  if (typeof input.$schema_version === 'number' && input.$schema_version > 4) {
+    throw new Error(`Unsupported future Relation schema version: ${input.$schema_version}`);
+  }
+  const output = clone(input);
+  const legacyRoles = isRecord(output.roles) ? output.roles : null;
+  const assigned = legacyRoles && Object.prototype.hasOwnProperty.call(legacyRoles, 'assigned')
+    ? legacyRoles.assigned
+    : undefined;
+  if (assigned !== undefined && output.role !== undefined && assigned !== output.role) {
+    throw new Error(`role conflicts with legacy roles.assigned (${String(output.role)} != ${String(assigned)})`);
+  }
+  if (output.role === undefined && assigned !== undefined) {
+    output.role = assigned;
+    summary.migratedRelationAssignments += 1;
+  }
+  if (isRecord(legacyRoles?.members)) {
+    summary.discardedMemberOverrides += Object.keys(legacyRoles.members).length;
+  }
+  if (Object.prototype.hasOwnProperty.call(output, 'roles')) delete output.roles;
+  if (Object.prototype.hasOwnProperty.call(output, 'permissionMode')) {
+    delete output.permissionMode;
+    summary.removedRelationPermissionModes += 1;
+  }
+  removeLegacySessionRenewModel(output, summary);
+  output.$schema_version = 4;
+  if (output.role !== undefined && output.role !== null && !roleNames.has(output.role)) {
+    throw new Error(`role references unknown role: ${String(output.role)}`);
+  }
+  return output;
+}
+
+function readJson(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    return { value: JSON.parse(text), text };
+  } catch (error) {
+    throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function walkRelationConfigs(root) {
+  if (!fs.existsSync(root)) return [];
+  const files = [];
+  const visit = dir => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(full);
+      else if (entry.isFile() && entry.name === 'config.json') files.push(full);
+    }
+  };
+  visit(root);
+  return files.sort();
+}
+
+function validationError(validate) {
+  return (validate.errors ?? []).map(error => {
+    const extra = error.params?.additionalProperty ? ` (${error.params.additionalProperty})` : '';
+    return `${error.instancePath || '/'} ${error.message}${extra}`;
+  }).join('; ');
+}
+
+function planMigration(home) {
+  const agentsRoot = path.join(home, 'agents');
+  if (!fs.existsSync(agentsRoot)) throw new Error(`Agents directory not found: ${agentsRoot}`);
+  const validators = loadValidators();
+  const summary = {
+    agentsScanned: 0,
+    relationsScanned: 0,
+    agentsChanged: 0,
+    relationsChanged: 0,
+    removedAgentPermissionModes: 0,
+    removedRelationPermissionModes: 0,
+    migratedRelationAssignments: 0,
+    discardedMemberOverrides: 0,
+    migratedLegacyV2Roles: 0,
+    normalizedRoleDefinitions: 0,
+    movedCommandPermissions: 0,
+    droppedUnsupportedRoleConstraints: 0,
+    removedObsoletePermissionUpdates: 0,
+    removedSessionRenewModels: 0,
+  };
+  const changes = [];
+
+  for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || !isValidAid(entry.name)) continue;
+    const agentDir = path.join(agentsRoot, entry.name);
+    const agentFile = path.join(agentDir, 'config.json');
+    if (!fs.existsSync(agentFile)) continue;
+    summary.agentsScanned += 1;
+    const { value: agentInput, text: agentText } = readJson(agentFile);
+    const { output: agentOutput, roleNames } = migrateAgentConfig(agentInput, summary);
+    if (!validators.agent(agentOutput)) throw new Error(`${agentFile}: ${validationError(validators.agent)}`);
+    if (JSON.stringify(agentInput) !== JSON.stringify(agentOutput)) {
+      changes.push(changeRecord(home, agentFile, 'agent', agentText, agentOutput));
+      summary.agentsChanged += 1;
+    }
+
+    for (const relationFile of walkRelationConfigs(path.join(agentDir, 'relations'))) {
+      summary.relationsScanned += 1;
+      const { value: relationInput, text: relationText } = readJson(relationFile);
+      const relationOutput = migrateRelationConfig(relationInput, roleNames, summary);
+      if (!validators.relation(relationOutput)) throw new Error(`${relationFile}: ${validationError(validators.relation)}`);
+      if (JSON.stringify(relationInput) !== JSON.stringify(relationOutput)) {
+        changes.push(changeRecord(home, relationFile, 'relation', relationText, relationOutput));
+        summary.relationsChanged += 1;
+      }
+    }
+  }
+  return { home, changes, summary };
+}
+
+function changeRecord(home, file, kind, beforeText, after) {
+  return {
+    file,
+    relative: path.relative(home, file),
+    kind,
+    beforeText,
+    afterText: `${JSON.stringify(after, null, 2)}\n`,
+  };
+}
+
 function assertDaemonStopped(home) {
   const candidates = [];
   const legacyPidFile = path.join(home, 'daemon.pid');
@@ -464,166 +464,166 @@ function assertDaemonStopped(home) {
   } catch (error) {
     if (error?.code !== 'ENOENT') throw error;
   }
-
-  const instanceDir = path.join(home, 'data', 'instance');
-  if (fs.existsSync(instanceDir)) {
-    for (const name of fs.readdirSync(instanceDir)) {
-      if (!/^main-\d+\.json$/.test(name)) continue;
-      const file = path.join(instanceDir, name);
-      try {
-        const record = JSON.parse(fs.readFileSync(file, 'utf8'));
-        candidates.push({ pid: Number(record?.pid), source: file });
-      } catch {
-        // A broken instance record is ignored here; daemon startup owns its cleanup.
-      }
-    }
-  }
-
-  for (const { pid, source } of candidates) {
-    if (!Number.isInteger(pid) || pid <= 0) continue;
-    try {
-      process.kill(pid, 0);
-    } catch (error) {
-      if (error?.code === 'ESRCH') continue;
-      if (error?.code !== 'EPERM') throw error;
-    }
-    throw new Error(`EvolCore daemon appears to be running (pid=${pid}, record=${source}); stop it before migration`);
-  }
-}
-
-function acquireMigrationLock(home) {
-  const lockDir = path.join(home, 'data', 'role-v4-migration.lock');
-  const ownerFile = path.join(lockDir, 'owner.json');
-  fs.mkdirSync(path.dirname(lockDir), { recursive: true });
-
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      fs.mkdirSync(lockDir);
-      fs.writeFileSync(ownerFile, `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }, null, 2)}\n`);
-      return () => fs.rmSync(lockDir, { recursive: true, force: true });
-    } catch (error) {
-      if (error?.code !== 'EEXIST') throw error;
-      let ownerPid = null;
-      try {
-        ownerPid = Number(JSON.parse(fs.readFileSync(ownerFile, 'utf8'))?.pid);
-      } catch {
-        throw new Error(`Role config migration lock is unreadable: ${lockDir}`);
-      }
-      if (Number.isInteger(ownerPid) && ownerPid > 0) {
-        try {
-          process.kill(ownerPid, 0);
-          throw new Error(`Another role config migration is already running (pid=${ownerPid})`);
-        } catch (ownerError) {
-          if (ownerError?.code === 'EPERM') {
-            throw new Error(`Another role config migration is already running (pid=${ownerPid})`);
-          }
-          if (ownerError?.code !== 'ESRCH') throw ownerError;
-        }
-      }
-      fs.rmSync(lockDir, { recursive: true, force: true });
-    }
-  }
-  throw new Error(`Unable to acquire role config migration lock: ${lockDir}`);
-}
-
-function atomicWrite(file, content) {
-  const mode = fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o600;
-  const temp = `${file}.role-v4-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`;
-  fs.writeFileSync(temp, content, { mode });
-  fs.renameSync(temp, file);
-}
-
-function createBackup(plan) {
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const backupRoot = path.join(plan.home, 'backups', 'role-v4-migration', timestamp);
-  for (const change of plan.changes) {
-    const destination = path.join(backupRoot, 'files', change.relative);
-    fs.mkdirSync(path.dirname(destination), { recursive: true });
-    fs.writeFileSync(destination, change.beforeText, 'utf8');
-  }
-  fs.writeFileSync(path.join(backupRoot, 'manifest.json'), `${JSON.stringify({
-    schemaVersion: 1,
-    createdAt: new Date().toISOString(),
-    home: plan.home,
-    summary: plan.summary,
-    files: plan.changes.map(change => ({ path: change.relative, kind: change.kind })),
-  }, null, 2)}\n`);
-  return backupRoot;
-}
-
-function applyMigration(plan) {
-  if (!plan.changes.length) return null;
-  assertDaemonStopped(plan.home);
-  const backup = createBackup(plan);
-  const written = [];
-  try {
-    for (const change of plan.changes) {
-      atomicWrite(change.file, change.afterText);
-      written.push(change);
-    }
-  } catch (error) {
-    for (const change of written.reverse()) atomicWrite(change.file, change.beforeText);
-    throw error;
-  }
-  return backup;
-}
-
-function presentResult(plan, applied, backup) {
-  return {
-    ok: true,
-    mode: applied ? 'applied' : 'dry-run',
-    home: plan.home,
-    changedFiles: plan.changes.length,
-    backup,
-    summary: plan.summary,
-  };
-}
-
-function printHuman(result) {
-  console.log(`Role config v4 migration (${result.mode})`);
-  console.log(`Home: ${result.home}`);
-  console.log(`Changed files: ${result.changedFiles}`);
-  console.log(`Agents: ${result.summary.agentsChanged}/${result.summary.agentsScanned}`);
-  console.log(`Relations: ${result.summary.relationsChanged}/${result.summary.relationsScanned}`);
-  console.log(`Migrated legacy v2 roles: ${result.summary.migratedLegacyV2Roles}`);
-  console.log(`Discarded member overrides: ${result.summary.discardedMemberOverrides}`);
-  console.log(`Moved command permissions: ${result.summary.movedCommandPermissions}`);
-  console.log(`Dropped unsupported role constraints: ${result.summary.droppedUnsupportedRoleConstraints}`);
-  if (result.backup) console.log(`Backup: ${result.backup}`);
-  if (result.mode === 'dry-run' && result.changedFiles) console.log('Run again with --apply after reviewing this result.');
-}
-
-export function runMigration(options = {}) {
-  const home = resolveHome(options.home);
-  assertDaemonStopped(home);
-  const releaseLock = options.apply ? acquireMigrationLock(home) : null;
-  try {
-    const plan = planMigration(home);
-    const backup = options.apply ? applyMigration(plan) : null;
-    return presentResult(plan, !!options.apply, backup);
-  } finally {
-    releaseLock?.();
-  }
-}
-
-async function main() {
-  try {
-    const options = parseArgs(process.argv.slice(2));
-    if (options.help) {
-      console.log(usage());
-      return;
-    }
-    const result = runMigration(options);
-    if (options.json) console.log(JSON.stringify(result));
-    else printHuman(result);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (process.argv.includes('--json')) console.log(JSON.stringify({ ok: false, error: message }));
-    else console.error(`Migration failed: ${message}`);
-    process.exitCode = 1;
-  }
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  await main();
-}
+
+  const instanceDir = path.join(home, 'data', 'instance');
+  if (fs.existsSync(instanceDir)) {
+    for (const name of fs.readdirSync(instanceDir)) {
+      if (!/^main-\d+\.json$/.test(name)) continue;
+      const file = path.join(instanceDir, name);
+      try {
+        const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+        candidates.push({ pid: Number(record?.pid), source: file });
+      } catch {
+        // A broken instance record is ignored here; daemon startup owns its cleanup.
+      }
+    }
+  }
+
+  for (const { pid, source } of candidates) {
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    try {
+      process.kill(pid, 0);
+    } catch (error) {
+      if (error?.code === 'ESRCH') continue;
+      if (error?.code !== 'EPERM') throw error;
+    }
+    throw new Error(`EvolCore daemon appears to be running (pid=${pid}, record=${source}); stop it before migration`);
+  }
+}
+
+function acquireMigrationLock(home) {
+  const lockDir = path.join(home, 'data', 'role-v4-migration.lock');
+  const ownerFile = path.join(lockDir, 'owner.json');
+  fs.mkdirSync(path.dirname(lockDir), { recursive: true });
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fs.mkdirSync(lockDir);
+      fs.writeFileSync(ownerFile, `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }, null, 2)}\n`);
+      return () => fs.rmSync(lockDir, { recursive: true, force: true });
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      let ownerPid = null;
+      try {
+        ownerPid = Number(JSON.parse(fs.readFileSync(ownerFile, 'utf8'))?.pid);
+      } catch {
+        throw new Error(`Role config migration lock is unreadable: ${lockDir}`);
+      }
+      if (Number.isInteger(ownerPid) && ownerPid > 0) {
+        try {
+          process.kill(ownerPid, 0);
+          throw new Error(`Another role config migration is already running (pid=${ownerPid})`);
+        } catch (ownerError) {
+          if (ownerError?.code === 'EPERM') {
+            throw new Error(`Another role config migration is already running (pid=${ownerPid})`);
+          }
+          if (ownerError?.code !== 'ESRCH') throw ownerError;
+        }
+      }
+      fs.rmSync(lockDir, { recursive: true, force: true });
+    }
+  }
+  throw new Error(`Unable to acquire role config migration lock: ${lockDir}`);
+}
+
+function atomicWrite(file, content) {
+  const mode = fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o600;
+  const temp = `${file}.role-v4-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`;
+  fs.writeFileSync(temp, content, { mode });
+  fs.renameSync(temp, file);
+}
+
+function createBackup(plan) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupRoot = path.join(plan.home, 'backups', 'role-v4-migration', timestamp);
+  for (const change of plan.changes) {
+    const destination = path.join(backupRoot, 'files', change.relative);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.writeFileSync(destination, change.beforeText, 'utf8');
+  }
+  fs.writeFileSync(path.join(backupRoot, 'manifest.json'), `${JSON.stringify({
+    schemaVersion: 1,
+    createdAt: new Date().toISOString(),
+    home: plan.home,
+    summary: plan.summary,
+    files: plan.changes.map(change => ({ path: change.relative, kind: change.kind })),
+  }, null, 2)}\n`);
+  return backupRoot;
+}
+
+function applyMigration(plan) {
+  if (!plan.changes.length) return null;
+  assertDaemonStopped(plan.home);
+  const backup = createBackup(plan);
+  const written = [];
+  try {
+    for (const change of plan.changes) {
+      atomicWrite(change.file, change.afterText);
+      written.push(change);
+    }
+  } catch (error) {
+    for (const change of written.reverse()) atomicWrite(change.file, change.beforeText);
+    throw error;
+  }
+  return backup;
+}
+
+function presentResult(plan, applied, backup) {
+  return {
+    ok: true,
+    mode: applied ? 'applied' : 'dry-run',
+    home: plan.home,
+    changedFiles: plan.changes.length,
+    backup,
+    summary: plan.summary,
+  };
+}
+
+function printHuman(result) {
+  console.log(`Role config v4 migration (${result.mode})`);
+  console.log(`Home: ${result.home}`);
+  console.log(`Changed files: ${result.changedFiles}`);
+  console.log(`Agents: ${result.summary.agentsChanged}/${result.summary.agentsScanned}`);
+  console.log(`Relations: ${result.summary.relationsChanged}/${result.summary.relationsScanned}`);
+  console.log(`Migrated legacy v2 roles: ${result.summary.migratedLegacyV2Roles}`);
+  console.log(`Discarded member overrides: ${result.summary.discardedMemberOverrides}`);
+  console.log(`Moved command permissions: ${result.summary.movedCommandPermissions}`);
+  console.log(`Dropped unsupported role constraints: ${result.summary.droppedUnsupportedRoleConstraints}`);
+  if (result.backup) console.log(`Backup: ${result.backup}`);
+  if (result.mode === 'dry-run' && result.changedFiles) console.log('Run again with --apply after reviewing this result.');
+}
+
+export function runMigration(options = {}) {
+  const home = resolveHome(options.home);
+  assertDaemonStopped(home);
+  const releaseLock = options.apply ? acquireMigrationLock(home) : null;
+  try {
+    const plan = planMigration(home);
+    const backup = options.apply ? applyMigration(plan) : null;
+    return presentResult(plan, !!options.apply, backup);
+  } finally {
+    releaseLock?.();
+  }
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log(usage());
+      return;
+    }
+    const result = runMigration(options);
+    if (options.json) console.log(JSON.stringify(result));
+    else printHuman(result);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (process.argv.includes('--json')) console.log(JSON.stringify({ ok: false, error: message }));
+    else console.error(`Migration failed: ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}