evolcore 0.0.25 → 0.0.27

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

@@ -1,202 +1,202 @@
-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 BUILTIN_ROLES = ['owner', 'admin', 'member', 'visitor'];
-const MANAGEMENT_ROLES = new Set(['owner', 'admin']);
-
-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 === '--home') options.home = argv[++i];
-    else if (arg === '--help' || arg === '-h') options.help = true;
-    else throw new Error(`Unknown argument: ${arg}`);
-  }
-  return options;
-}
-
-function resolveHome(explicit) {
-  return path.resolve(explicit || process.env.EVOLCORE_HOME || 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.5.json')),
-    registry: ajv.compile(load('role-registry.schema.1.json')),
-    role: ajv.compile(load('role-config.schema.1.json')),
-  };
-}
-
-function readJson(file) {
-  const text = fs.readFileSync(file, 'utf8');
-  return { value: JSON.parse(text), text };
-}
-
-function isRecord(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function normalizeRoleEffortCompat(value) {
-  if (!isRecord(value) || !isRecord(value.permissions)
-    || !Object.prototype.hasOwnProperty.call(value.permissions, 'baseagents.codex.reasoning')) return value;
-  const permissions = { ...value.permissions };
-  if (!Object.prototype.hasOwnProperty.call(permissions, 'baseagents.codex.effort')) {
-    permissions['baseagents.codex.effort'] = permissions['baseagents.codex.reasoning'];
-  }
-  delete permissions['baseagents.codex.reasoning'];
-  return { ...value, permissions };
-}
-
-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 validateOrThrow(validate, value, file) {
-  if (validate(value)) return;
-  const detail = (validate.errors ?? []).map(error => `${error.instancePath || '/'} ${error.message}`).join('; ');
-  throw new Error(`${file}: ${detail}`);
-}
-
-function validateRoleOrThrow(validate, value, file) {
-  validateOrThrow(validate, value, file);
-  for (const [field, permission] of Object.entries(value.permissions ?? {})) {
-    if (!isRecord(permission)) continue;
-    if (Array.isArray(permission.allowedValues) && !permission.allowedValues.includes(permission.default)) {
-      throw new Error(`${file}: permissions.${field}.default must be included in allowedValues`);
-    }
-    if (Array.isArray(permission.allowedModels)
-      && typeof permission.default === 'string'
-      && !permission.allowedModels.some(pattern => wildcardMatch(pattern, permission.default))) {
-      throw new Error(`${file}: permissions.${field}.default must be allowed by allowedModels`);
-    }
-  }
-}
-
-function wildcardMatch(pattern, value) {
-  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
-  return new RegExp(`^${escaped}$`).test(value);
-}
-
-function change(file, kind, before, value) {
-  const after = `${JSON.stringify(value, null, 2)}\n`;
-  return before === after ? null : { file, kind, before, after };
-}
-
-function appendChange(changes, file, kind, before, value) {
-  const item = change(file, kind, before, value);
-  if (!item) return false;
-  changes.push(item);
-  return true;
-}
-
-function planMigration(home) {
-  const validators = loadValidators();
-  const agentsRoot = path.join(home, 'agents');
-  if (!fs.existsSync(agentsRoot)) return { home, changes: [], summary: { agentsScanned: 0, agentsMigrated: 0, rolesWritten: 0 } };
-  const changes = [];
-  const summary = { agentsScanned: 0, agentsMigrated: 0, rolesWritten: 0 };
-
-  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 agentFile = path.join(agentsRoot, entry.name, 'config.json');
-    if (!fs.existsSync(agentFile)) continue;
-    summary.agentsScanned += 1;
-    const { value: input, text: agentText } = readJson(agentFile);
-    if (!isRecord(input)) throw new Error(`${agentFile}: Agent config must be an object`);
-    if (typeof input.$schema_version === 'number' && input.$schema_version > 5) {
-      throw new Error(`${agentFile}: unsupported future Agent schema version ${input.$schema_version}`);
-    }
-
-    const rolesDir = path.join(agentsRoot, entry.name, 'roles');
-    const registryFile = path.join(rolesDir, 'index.json');
-    if (fs.existsSync(registryFile) && input.roles !== undefined) {
-      throw new Error(`${agentFile}: both config.roles and roles/index.json exist; resolve the ambiguous role source before migration`);
-    }
-    if (input.$schema_version === 5 && input.roles === undefined && fs.existsSync(registryFile)) {
-      const { value: registry } = readJson(registryFile);
-      validateOrThrow(validators.registry, registry, registryFile);
-      for (const roleId of registry.roles) {
-        const roleFile = path.join(rolesDir, `${roleId}.json`);
-        if (!fs.existsSync(roleFile)) continue;
-        const { value: roleValue, text: roleText } = readJson(roleFile);
-        const normalizedRole = normalizeRoleEffortCompat(roleValue);
-        validateRoleOrThrow(validators.role, normalizedRole, roleFile);
-        if (appendChange(changes, roleFile, 'role-config', roleText, normalizedRole)) {
-          summary.rolesWritten += 1;
-        }
-      }
-      continue;
-    }
-
-    const policy = isRecord(input.roles) ? input.roles : {};
-    const definitions = isRecord(policy.definitions) ? policy.definitions : {};
-    for (const roleId of Object.keys(definitions)) {
-      if (!/^[a-z0-9_-]+$/.test(roleId) || MANAGEMENT_ROLES.has(roleId)) {
-        throw new Error(`${agentFile}: invalid role id ${JSON.stringify(roleId)}`);
-      }
-    }
-    const roleIds = [...new Set([...BUILTIN_ROLES, ...Object.keys(definitions)])];
-    const defaultRoles = {
-      private: policy.defaultRoles?.private ?? null,
-      group: policy.defaultRoles?.group ?? null,
-    };
-    for (const scene of ['private', 'group']) {
-      const selected = defaultRoles[scene];
-      if (selected !== null && (MANAGEMENT_ROLES.has(selected) || !roleIds.includes(selected))) {
-        throw new Error(`${agentFile}: roles.defaultRoles.${scene} references an invalid role`);
-      }
-    }
-    const registry = { $schema_version: 1, roles: roleIds, defaultRoles };
-    validateOrThrow(validators.registry, registry, registryFile);
-
-    const relationsDir = path.join(agentsRoot, entry.name, 'relations');
-    if (fs.existsSync(relationsDir)) {
-      const visit = dir => {
-        for (const relationEntry of fs.readdirSync(dir, { withFileTypes: true })) {
-          const full = path.join(dir, relationEntry.name);
-          if (relationEntry.isDirectory()) visit(full);
-          else if (relationEntry.isFile() && relationEntry.name === 'config.json') {
-            const relation = readJson(full).value;
-            if (relation.role !== undefined && relation.role !== null
-              && (MANAGEMENT_ROLES.has(relation.role) || !roleIds.includes(relation.role))) {
-              throw new Error(`${full}: role references an invalid or unregistered role`);
-            }
-          }
-        }
-      };
-      visit(relationsDir);
-    }
-
-    const existingRegistry = fs.existsSync(registryFile) ? fs.readFileSync(registryFile, 'utf8') : null;
-    appendChange(changes, registryFile, 'role-registry', existingRegistry, registry);
-    for (const [roleId, definition] of Object.entries(definitions)) {
-      const roleFile = path.join(rolesDir, `${roleId}.json`);
-      const roleValue = normalizeRoleEffortCompat({ $schema_version: 1, ...definition });
-      validateRoleOrThrow(validators.role, roleValue, roleFile);
-      if (appendChange(changes, roleFile, 'role-config', fs.existsSync(roleFile) ? fs.readFileSync(roleFile, 'utf8') : null, roleValue)) {
-        summary.rolesWritten += 1;
-      }
-    }
-
-    const output = { ...input, $schema_version: 5 };
-    delete output.roles;
-    validateOrThrow(validators.agent, output, agentFile);
-    appendChange(changes, agentFile, 'agent', agentText, output);
-    summary.agentsMigrated += 1;
-  }
-  return { home, changes, summary };
-}
-
+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 BUILTIN_ROLES = ['owner', 'admin', 'member', 'visitor'];
+const MANAGEMENT_ROLES = new Set(['owner', 'admin']);
+
+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 === '--home') options.home = argv[++i];
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return options;
+}
+
+function resolveHome(explicit) {
+  return path.resolve(explicit || process.env.EVOLCORE_HOME || 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.5.json')),
+    registry: ajv.compile(load('role-registry.schema.1.json')),
+    role: ajv.compile(load('role-config.schema.1.json')),
+  };
+}
+
+function readJson(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  return { value: JSON.parse(text), text };
+}
+
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeRoleEffortCompat(value) {
+  if (!isRecord(value) || !isRecord(value.permissions)
+    || !Object.prototype.hasOwnProperty.call(value.permissions, 'baseagents.codex.reasoning')) return value;
+  const permissions = { ...value.permissions };
+  if (!Object.prototype.hasOwnProperty.call(permissions, 'baseagents.codex.effort')) {
+    permissions['baseagents.codex.effort'] = permissions['baseagents.codex.reasoning'];
+  }
+  delete permissions['baseagents.codex.reasoning'];
+  return { ...value, permissions };
+}
+
+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 validateOrThrow(validate, value, file) {
+  if (validate(value)) return;
+  const detail = (validate.errors ?? []).map(error => `${error.instancePath || '/'} ${error.message}`).join('; ');
+  throw new Error(`${file}: ${detail}`);
+}
+
+function validateRoleOrThrow(validate, value, file) {
+  validateOrThrow(validate, value, file);
+  for (const [field, permission] of Object.entries(value.permissions ?? {})) {
+    if (!isRecord(permission)) continue;
+    if (Array.isArray(permission.allowedValues) && !permission.allowedValues.includes(permission.default)) {
+      throw new Error(`${file}: permissions.${field}.default must be included in allowedValues`);
+    }
+    if (Array.isArray(permission.allowedModels)
+      && typeof permission.default === 'string'
+      && !permission.allowedModels.some(pattern => wildcardMatch(pattern, permission.default))) {
+      throw new Error(`${file}: permissions.${field}.default must be allowed by allowedModels`);
+    }
+  }
+}
+
+function wildcardMatch(pattern, value) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`).test(value);
+}
+
+function change(file, kind, before, value) {
+  const after = `${JSON.stringify(value, null, 2)}\n`;
+  return before === after ? null : { file, kind, before, after };
+}
+
+function appendChange(changes, file, kind, before, value) {
+  const item = change(file, kind, before, value);
+  if (!item) return false;
+  changes.push(item);
+  return true;
+}
+
+function planMigration(home) {
+  const validators = loadValidators();
+  const agentsRoot = path.join(home, 'agents');
+  if (!fs.existsSync(agentsRoot)) return { home, changes: [], summary: { agentsScanned: 0, agentsMigrated: 0, rolesWritten: 0 } };
+  const changes = [];
+  const summary = { agentsScanned: 0, agentsMigrated: 0, rolesWritten: 0 };
+
+  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 agentFile = path.join(agentsRoot, entry.name, 'config.json');
+    if (!fs.existsSync(agentFile)) continue;
+    summary.agentsScanned += 1;
+    const { value: input, text: agentText } = readJson(agentFile);
+    if (!isRecord(input)) throw new Error(`${agentFile}: Agent config must be an object`);
+    if (typeof input.$schema_version === 'number' && input.$schema_version > 5) {
+      throw new Error(`${agentFile}: unsupported future Agent schema version ${input.$schema_version}`);
+    }
+
+    const rolesDir = path.join(agentsRoot, entry.name, 'roles');
+    const registryFile = path.join(rolesDir, 'index.json');
+    if (fs.existsSync(registryFile) && input.roles !== undefined) {
+      throw new Error(`${agentFile}: both config.roles and roles/index.json exist; resolve the ambiguous role source before migration`);
+    }
+    if (input.$schema_version === 5 && input.roles === undefined && fs.existsSync(registryFile)) {
+      const { value: registry } = readJson(registryFile);
+      validateOrThrow(validators.registry, registry, registryFile);
+      for (const roleId of registry.roles) {
+        const roleFile = path.join(rolesDir, `${roleId}.json`);
+        if (!fs.existsSync(roleFile)) continue;
+        const { value: roleValue, text: roleText } = readJson(roleFile);
+        const normalizedRole = normalizeRoleEffortCompat(roleValue);
+        validateRoleOrThrow(validators.role, normalizedRole, roleFile);
+        if (appendChange(changes, roleFile, 'role-config', roleText, normalizedRole)) {
+          summary.rolesWritten += 1;
+        }
+      }
+      continue;
+    }
+
+    const policy = isRecord(input.roles) ? input.roles : {};
+    const definitions = isRecord(policy.definitions) ? policy.definitions : {};
+    for (const roleId of Object.keys(definitions)) {
+      if (!/^[a-z0-9_-]+$/.test(roleId) || MANAGEMENT_ROLES.has(roleId)) {
+        throw new Error(`${agentFile}: invalid role id ${JSON.stringify(roleId)}`);
+      }
+    }
+    const roleIds = [...new Set([...BUILTIN_ROLES, ...Object.keys(definitions)])];
+    const defaultRoles = {
+      private: policy.defaultRoles?.private ?? null,
+      group: policy.defaultRoles?.group ?? null,
+    };
+    for (const scene of ['private', 'group']) {
+      const selected = defaultRoles[scene];
+      if (selected !== null && (MANAGEMENT_ROLES.has(selected) || !roleIds.includes(selected))) {
+        throw new Error(`${agentFile}: roles.defaultRoles.${scene} references an invalid role`);
+      }
+    }
+    const registry = { $schema_version: 1, roles: roleIds, defaultRoles };
+    validateOrThrow(validators.registry, registry, registryFile);
+
+    const relationsDir = path.join(agentsRoot, entry.name, 'relations');
+    if (fs.existsSync(relationsDir)) {
+      const visit = dir => {
+        for (const relationEntry of fs.readdirSync(dir, { withFileTypes: true })) {
+          const full = path.join(dir, relationEntry.name);
+          if (relationEntry.isDirectory()) visit(full);
+          else if (relationEntry.isFile() && relationEntry.name === 'config.json') {
+            const relation = readJson(full).value;
+            if (relation.role !== undefined && relation.role !== null
+              && (MANAGEMENT_ROLES.has(relation.role) || !roleIds.includes(relation.role))) {
+              throw new Error(`${full}: role references an invalid or unregistered role`);
+            }
+          }
+        }
+      };
+      visit(relationsDir);
+    }
+
+    const existingRegistry = fs.existsSync(registryFile) ? fs.readFileSync(registryFile, 'utf8') : null;
+    appendChange(changes, registryFile, 'role-registry', existingRegistry, registry);
+    for (const [roleId, definition] of Object.entries(definitions)) {
+      const roleFile = path.join(rolesDir, `${roleId}.json`);
+      const roleValue = normalizeRoleEffortCompat({ $schema_version: 1, ...definition });
+      validateRoleOrThrow(validators.role, roleValue, roleFile);
+      if (appendChange(changes, roleFile, 'role-config', fs.existsSync(roleFile) ? fs.readFileSync(roleFile, 'utf8') : null, roleValue)) {
+        summary.rolesWritten += 1;
+      }
+    }
+
+    const output = { ...input, $schema_version: 5 };
+    delete output.roles;
+    validateOrThrow(validators.agent, output, agentFile);
+    appendChange(changes, agentFile, 'agent', agentText, output);
+    summary.agentsMigrated += 1;
+  }
+  return { home, changes, summary };
+}
+
 function assertDaemonStopped(home) {
   const candidates = [];
   const pidFile = path.join(home, 'daemon.pid');
@@ -209,169 +209,169 @@ 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 { candidates.push({ pid: Number(JSON.parse(fs.readFileSync(file, 'utf8'))?.pid), source: file }); } catch {}
-    }
-  }
-  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-v5-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;
-      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) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const mode = fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o600;
-  const temp = `${file}.role-v5-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`;
-  fs.writeFileSync(temp, content, { mode });
-  fs.renameSync(temp, file);
-}
-
-function migrationJournalPath(home) {
-  return path.join(home, 'data', 'role-v5-migration.json');
-}
-
-function writeMigrationJournal(plan, state) {
-  atomicWrite(migrationJournalPath(plan.home), `${JSON.stringify({
-    schemaVersion: 1,
-    state,
-    home: plan.home,
-    changes: plan.changes,
-  }, null, 2)}\n`);
-}
-
-function removeMigrationJournal(home) {
-  fs.rmSync(migrationJournalPath(home), { force: true });
-}
-
-function recoverMigrationJournal(home) {
-  const file = migrationJournalPath(home);
-  if (!fs.existsSync(file)) return;
-  let journal;
-  try { journal = JSON.parse(fs.readFileSync(file, 'utf8')); }
-  catch { throw new Error(`Role config v5 migration journal is unreadable: ${file}`); }
-  if (journal?.schemaVersion !== 1
-    || !['prepared', 'committed'].includes(journal.state)
-    || path.resolve(journal.home) !== home
-    || !Array.isArray(journal.changes)) {
-    throw new Error(`Role config v5 migration journal is invalid: ${file}`);
-  }
-  const rootPrefix = home + path.sep;
-  for (const item of journal.changes) {
-    const target = path.resolve(item?.file || '');
-    if (!target.startsWith(rootPrefix)
-      || (item.before !== null && typeof item.before !== 'string')
-      || typeof item.after !== 'string') {
-      throw new Error(`Role config v5 migration journal contains an unsafe change: ${file}`);
-    }
-  }
-  if (journal.state === 'prepared') {
-    for (const item of [...journal.changes].reverse()) {
-      if (item.before === null) fs.rmSync(item.file, { force: true });
-      else atomicWrite(item.file, item.before);
-    }
-  }
-  removeMigrationJournal(home);
-}
-
-function applyMigration(plan) {
-  if (!plan.changes.length) return null;
-  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const backup = path.join(plan.home, 'backups', 'role-v5-migration', stamp);
-  fs.mkdirSync(backup, { recursive: true });
-  for (const item of plan.changes) {
-    if (item.before === null) continue;
-    const dest = path.join(backup, 'files', path.relative(plan.home, item.file));
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.writeFileSync(dest, item.before);
-  }
-  fs.writeFileSync(path.join(backup, 'manifest.json'), `${JSON.stringify({
-    schemaVersion: 1,
-    createdAt: new Date().toISOString(),
-    summary: plan.summary,
-    files: plan.changes.map(item => ({ path: path.relative(plan.home, item.file), kind: item.kind })),
-  }, null, 2)}\n`);
-  writeMigrationJournal(plan, 'prepared');
-  try {
-    for (const item of plan.changes) {
-      atomicWrite(item.file, item.after);
-    }
-    writeMigrationJournal(plan, 'committed');
-    removeMigrationJournal(plan.home);
-  } catch (error) {
-    recoverMigrationJournal(plan.home);
-    throw error;
-  }
-  return backup;
-}
-
-export function runMigration(options = {}) {
-  const home = resolveHome(options.home);
-  const releaseLock = acquireMigrationLock(home);
-  try {
-    assertDaemonStopped(home);
-    recoverMigrationJournal(home);
-    const plan = planMigration(home);
-    const backup = options.apply ? applyMigration(plan) : null;
-    return { ok: true, mode: options.apply ? 'applied' : 'dry-run', home, changedFiles: plan.changes.length, backup, summary: plan.summary };
-  } finally {
-    releaseLock();
-  }
-}
-
-async function main() {
-  try {
-    const options = parseArgs(process.argv.slice(2));
-    if (options.help) {
-      console.log('Usage: node kits/migrations/migrate-role-config-v5.mjs [--apply] [--home <path>] [--json]');
-      return;
-    }
-    const result = runMigration(options);
-    if (options.json) console.log(JSON.stringify(result));
-    else console.log(`Role config v5 migration (${result.mode}): ${result.changedFiles} file(s)`);
-  } 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 { candidates.push({ pid: Number(JSON.parse(fs.readFileSync(file, 'utf8'))?.pid), source: file }); } catch {}
+    }
+  }
+  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-v5-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;
+      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) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const mode = fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o600;
+  const temp = `${file}.role-v5-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`;
+  fs.writeFileSync(temp, content, { mode });
+  fs.renameSync(temp, file);
+}
+
+function migrationJournalPath(home) {
+  return path.join(home, 'data', 'role-v5-migration.json');
+}
+
+function writeMigrationJournal(plan, state) {
+  atomicWrite(migrationJournalPath(plan.home), `${JSON.stringify({
+    schemaVersion: 1,
+    state,
+    home: plan.home,
+    changes: plan.changes,
+  }, null, 2)}\n`);
+}
+
+function removeMigrationJournal(home) {
+  fs.rmSync(migrationJournalPath(home), { force: true });
+}
+
+function recoverMigrationJournal(home) {
+  const file = migrationJournalPath(home);
+  if (!fs.existsSync(file)) return;
+  let journal;
+  try { journal = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch { throw new Error(`Role config v5 migration journal is unreadable: ${file}`); }
+  if (journal?.schemaVersion !== 1
+    || !['prepared', 'committed'].includes(journal.state)
+    || path.resolve(journal.home) !== home
+    || !Array.isArray(journal.changes)) {
+    throw new Error(`Role config v5 migration journal is invalid: ${file}`);
+  }
+  const rootPrefix = home + path.sep;
+  for (const item of journal.changes) {
+    const target = path.resolve(item?.file || '');
+    if (!target.startsWith(rootPrefix)
+      || (item.before !== null && typeof item.before !== 'string')
+      || typeof item.after !== 'string') {
+      throw new Error(`Role config v5 migration journal contains an unsafe change: ${file}`);
+    }
+  }
+  if (journal.state === 'prepared') {
+    for (const item of [...journal.changes].reverse()) {
+      if (item.before === null) fs.rmSync(item.file, { force: true });
+      else atomicWrite(item.file, item.before);
+    }
+  }
+  removeMigrationJournal(home);
+}
+
+function applyMigration(plan) {
+  if (!plan.changes.length) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backup = path.join(plan.home, 'backups', 'role-v5-migration', stamp);
+  fs.mkdirSync(backup, { recursive: true });
+  for (const item of plan.changes) {
+    if (item.before === null) continue;
+    const dest = path.join(backup, 'files', path.relative(plan.home, item.file));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, item.before);
+  }
+  fs.writeFileSync(path.join(backup, 'manifest.json'), `${JSON.stringify({
+    schemaVersion: 1,
+    createdAt: new Date().toISOString(),
+    summary: plan.summary,
+    files: plan.changes.map(item => ({ path: path.relative(plan.home, item.file), kind: item.kind })),
+  }, null, 2)}\n`);
+  writeMigrationJournal(plan, 'prepared');
+  try {
+    for (const item of plan.changes) {
+      atomicWrite(item.file, item.after);
+    }
+    writeMigrationJournal(plan, 'committed');
+    removeMigrationJournal(plan.home);
+  } catch (error) {
+    recoverMigrationJournal(plan.home);
+    throw error;
+  }
+  return backup;
+}
+
+export function runMigration(options = {}) {
+  const home = resolveHome(options.home);
+  const releaseLock = acquireMigrationLock(home);
+  try {
+    assertDaemonStopped(home);
+    recoverMigrationJournal(home);
+    const plan = planMigration(home);
+    const backup = options.apply ? applyMigration(plan) : null;
+    return { ok: true, mode: options.apply ? 'applied' : 'dry-run', home, changedFiles: plan.changes.length, backup, summary: plan.summary };
+  } finally {
+    releaseLock();
+  }
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log('Usage: node kits/migrations/migrate-role-config-v5.mjs [--apply] [--home <path>] [--json]');
+      return;
+    }
+    const result = runMigration(options);
+    if (options.json) console.log(JSON.stringify(result));
+    else console.log(`Role config v5 migration (${result.mode}): ${result.changedFiles} file(s)`);
+  } 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();