evolcore 0.0.1 → 0.0.2

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

@@ -0,0 +1,623 @@
+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');
+  if (fs.existsSync(legacyPidFile)) {
+    candidates.push({
+      pid: Number(fs.readFileSync(legacyPidFile, 'utf8').trim()),
+      source: legacyPidFile,
+    });
+  }
+
+  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();
+}