evolcore 0.0.24 → 0.0.26

package/dist/cli/handoff-command.js

@@ -106,13 +106,13 @@ export function parseReturn(args) {
 function printReturn(result) {
     if (result.ok) {
         if (result.code === 'HANDOFF_RETURN_ALREADY_APPLIED') {
-            console.log(`✓ handoff ${result.handoff_id} 已接收过相同结果，未重复处理`);
+            console.log(`✓ handoff ${result.handoff_id} 已接收过相同结果，未重复处理${result.result_id ? ` result_id=${result.result_id}` : ''}`);
         }
         else if (result.state === 'completed') {
             console.log(`✓ handoff ${result.handoff_id} 已确认完成，不回流来源会话`);
         }
         else {
-            console.log(`✓ handoff ${result.handoff_id} 回流结果已接收`);
+            console.log(`✓ handoff ${result.handoff_id} 回流结果已接收${result.result_id ? ` result_id=${result.result_id}` : ''}；后续仍可用同一 ID 追加结果`);
         }
         return;
     }
@@ -156,8 +156,10 @@ export async function cmdHandoff(args) {
         console.log(`用法: ec handoff <command> [args]
 
 Commands:
-  return [handoff-id] [content]       确认完成；required 策略需提供回流内容
+  return [handoff-id] [content]       提交一个回流结果；required 可用同一 ID 追加多个结果
   return [handoff-id] --text-from-file <path>
+  recover-return <handoff-id> [content]  owner-authorized recovery after target session replacement
+  recover-return <handoff-id> --text-from-file <path>
   status <handoff-id>                查询 handoff 状态
   list [--state <state>] [--session <id>] [--limit <n>] [--agent <aid>]
   trace <handoff-id> [--limit <n>] [--agent <aid>]`);
@@ -194,6 +196,36 @@ Commands:
         printReturn(result);
         return;
     }
+    if (sub === 'recover-return') {
+        let parsed;
+        try {
+            parsed = parseReturn(args.slice(1));
+        }
+        catch (error) {
+            console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (!parsed.handoffId) {
+            console.error('✗ recover-return 必须指定 handoff ID');
+            process.exitCode = 1;
+            return;
+        }
+        const result = await ipcQuery(resolvePaths().socket, {
+            type: 'handoff-recover-return',
+            sessionId: process.env.EVOLCORE_SESSION_ID,
+            handoffId: parsed.handoffId,
+            content: parsed.content,
+            delegationToken: process.env[AGENT_DELEGATION_TOKEN_ENV],
+        }, 5000);
+        if (!result) {
+            console.error('✗ daemon 暂时不可用');
+            process.exitCode = 1;
+            return;
+        }
+        printReturn(result);
+        return;
+    }
     if (sub === 'status') {
         const handoffId = args[1];
         if (!handoffId || !HANDOFF_ID_RE.test(handoffId)) {

package/dist/cli/index.js

@@ -47,7 +47,8 @@ AUN:
   storage           底层对象存储命令
   rpc               调用底层 AUN RPC
   menu-client       向远程 daemon 发送标准 Menu 请求
-  contact           联系人黑名单管理
+  diag              邀请远程诊断 Agent，或 stop 撤销诊断授权
+  contact           联系人、待审申请与黑名单管理
   net               AUN 网络链路诊断
 
 配置与诊断:
@@ -351,6 +352,11 @@ export async function main(args) {
             await cmdRpc(args.slice(1));
             break;
         }
+        case 'diag': {
+            const { cmdDiag } = await import('./diag.js');
+            await cmdDiag(args.slice(1));
+            break;
+        }
         case 'menu-client': {
             const { suppressSdkLogs } = await import('../aun/aid/index.js');
             suppressSdkLogs();

package/dist/cli/managed-command-guard.js

@@ -5,6 +5,9 @@ const MANAGED_TASK_COMMANDS = new Set([
     'config',
     'contact',
     'ctl',
+    // These commands are authenticated again by their daemon IPC entrypoints.
+    'diag',
+    'menu-client',
     'fs',
     'group',
     'handoff',

package/dist/cli/menu-client.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { getArgValue, wantsHelp } from './help.js';
 import { executeMenuClientRequest, MenuClientError } from '../aun/menu-client.js';
+import { AGENT_DELEGATION_TOKEN_ENV } from '../core/auth/agent-delegation.js';
 function parseDurationMs(value) {
     if (value === undefined)
         return undefined;
@@ -11,14 +12,14 @@ function parseDurationMs(value) {
     const unit = match[2].toLowerCase();
     return amount * (unit === 'ms' ? 1 : unit === 's' ? 1_000 : unit === 'm' ? 60_000 : 3_600_000);
 }
-function readRequest(args) {
+function readRequest(args, readFile = (file) => fs.readFileSync(file, 'utf8')) {
     const file = getArgValue(args, '--request-file');
     const inline = getArgValue(args, '--request-json');
     if (!!file === !!inline)
         throw new MenuClientError('INVALID_ARGUMENT', '--request-file and --request-json are mutually exclusive');
     let raw;
     try {
-        raw = file ? fs.readFileSync(file, 'utf8') : inline;
+        raw = file ? readFile(file) : inline;
     }
     catch (error) {
         throw new MenuClientError('INVALID_ARGUMENT', `Unable to read request: ${error?.message ?? String(error)}`);
@@ -36,8 +37,12 @@ function readRequest(args) {
 function validateOptions(args) {
     const valueOptions = new Set(['--request-file', '--request-json', '--timeout', '--remote-token', '--ecweb-token', '--app', '--aun-path', '--format']);
     const booleanOptions = new Set(['--encrypt', '--no-encrypt']);
+    const seen = new Set();
     for (let index = 0; index < args.length; index += 1) {
         const option = args[index];
+        if (seen.has(option))
+            throw new MenuClientError('INVALID_ARGUMENT', `Duplicate option: ${option}`);
+        seen.add(option);
         if (booleanOptions.has(option))
             continue;
         if (!valueOptions.has(option))
@@ -54,6 +59,23 @@ function validateOptions(args) {
     if (format !== undefined && format !== 'json')
         throw new MenuClientError('INVALID_ARGUMENT', '--format currently supports only json');
 }
+export function parseMenuClientArgs(args, readFile) {
+    if (args[0] !== 'request')
+        throw new MenuClientError('INVALID_ARGUMENT', 'menu-client currently supports only the request subcommand');
+    const fromAid = args[1]?.trim();
+    const targetAid = args[2]?.trim();
+    if (!fromAid || !targetAid)
+        throw new MenuClientError('INVALID_ARGUMENT', 'request requires <from-aid> and <daemon-aid>');
+    const options = args.slice(3);
+    validateOptions(options);
+    return {
+        fromAid, targetAid, request: readRequest(options, readFile),
+        timeoutMs: parseDurationMs(getArgValue(options, '--timeout')),
+        encrypt: !options.includes('--no-encrypt'),
+        remoteAccessToken: getArgValue(options, '--remote-token') ?? getArgValue(options, '--ecweb-token'),
+        slotId: getArgValue(options, '--app'), aunPath: getArgValue(options, '--aun-path'),
+    };
+}
 export async function cmdMenuClient(args) {
     if (wantsHelp(args)) {
         console.log(`用法: ec menu-client request <from-aid> <daemon-aid> [选项]
@@ -70,26 +92,19 @@ export async function cmdMenuClient(args) {
   --format json            输出标准 menu.response JSON`);
         return;
     }
-    if (args[0] !== 'request')
-        throw new MenuClientError('INVALID_ARGUMENT', 'menu-client currently supports only the request subcommand');
-    const fromAid = args[1]?.trim();
-    const targetAid = args[2]?.trim();
-    if (!fromAid || !targetAid)
-        throw new MenuClientError('INVALID_ARGUMENT', 'request requires <from-aid> and <daemon-aid>');
-    const options = args.slice(3);
-    validateOptions(options);
-    const request = readRequest(options);
-    const timeoutMs = parseDurationMs(getArgValue(args, '--timeout'));
-    const encrypt = args.includes('--no-encrypt') ? false : true;
-    const response = await executeMenuClientRequest({
-        fromAid,
-        targetAid,
-        request,
-        timeoutMs,
-        encrypt,
-        remoteAccessToken: getArgValue(args, '--remote-token') ?? getArgValue(args, '--ecweb-token'),
-        slotId: getArgValue(args, '--app'),
-        aunPath: getArgValue(args, '--aun-path'),
-    });
+    let response;
+    if (process.env.EVOLCORE_SESSION_ID) {
+        const { ipcQuery } = await import('../ipc.js');
+        const { resolvePaths } = await import('../paths.js');
+        const result = await ipcQuery(resolvePaths().socket, {
+            type: 'menu-client.request', argv: args, sessionId: process.env.EVOLCORE_SESSION_ID,
+            delegationToken: process.env[AGENT_DELEGATION_TOKEN_ENV],
+        }, 250_000);
+        if (!result?.ok)
+            throw new MenuClientError(result?.code ?? 'DAEMON_UNAVAILABLE', result?.error ?? 'Managed Menu daemon is unavailable');
+        response = result.response;
+    }
+    else
+        response = await executeMenuClientRequest(parseMenuClientArgs(args));
     console.log(JSON.stringify(response, null, 2));
 }

package/dist/cli/restart-monitor.js

@@ -15,6 +15,7 @@ import { shouldSuppressRealRestart } from '../utils/restart-safety.js';
 import { rotateStdoutLog } from '../utils/log-writer.js';
 import { inspectDataMigrationRequirement } from '../core/data-migration.js';
 import { DAEMON_SHUTDOWN_TIMEOUT_MS, requestDaemonShutdown } from './daemon-commands.js';
+import { getProcessStartTime, startTimeMatches } from '../utils/process-introspect.js';
 const execFileAsync = promisify(execFile);
 /**
  * The package this monitor operates on, which is not always the one it runs
@@ -43,6 +44,15 @@ function cleanEnv() {
         delete process.env[key];
     }
 }
+function isPidReused(pid, expectedStartedAt) {
+    if (expectedStartedAt === undefined)
+        return false;
+    const actualStartedAt = getProcessStartTime(pid);
+    return actualStartedAt !== null && !startTimeMatches(expectedStartedAt, actualStartedAt);
+}
+function reportPidReused(pid, log) {
+    log(`Process ${pid} no longer refers to the recorded daemon; treating the original process as exited`);
+}
 export async function cmdRestartMonitor() {
     // Defense in depth: a unit test that accidentally executes the real restart
     // path must not detach a persistent daemon from the test worker.
@@ -117,9 +127,11 @@ export async function cmdRestartMonitor() {
     }
     // Test daemons live in one temporary HOME per test, so the current HOME's
     // instance registry cannot see them. Their strict environment markers make
-    // them safe to reap globally on every real restart.
+    // them safe to reap globally on every real restart. Keep one process-table
+    // snapshot for both orphan categories; each Windows CIM scan is expensive.
+    const orphanSnapshot = findOrphanProcesses();
     {
-        const leakedTestDaemons = findOrphanProcesses().filter(o => o.confirmedTestDaemon);
+        const leakedTestDaemons = orphanSnapshot.filter(o => o.confirmedTestDaemon);
         if (leakedTestDaemons.length > 0) {
             const killed = killOrphans(leakedTestDaemons);
             log(`Cleaned ${killed.length} leaked test daemon(s): ${killed.join(', ')}`);
@@ -130,7 +142,7 @@ export async function cmdRestartMonitor() {
     // still alive. Refuse to create a second daemon when an unregistered process
     // from this package is found; a duplicate would connect AUN and kick the
     // existing session before failing on IPC/port ownership.
-    const runtimeOrphans = findOrphanProcesses().filter(o => {
+    const runtimeOrphans = orphanSnapshot.filter(o => {
         if (o.confirmedTestDaemon)
             return false;
         const homeMatches = o.evolcoreHome && normalizePath(o.evolcoreHome) === normalizePath(p.root);
@@ -165,6 +177,7 @@ export async function cmdRestartMonitor() {
     const aliveMains = oldStatus.mains.filter(m => m.alive);
     if (aliveMains.length > 0) {
         const oldPids = aliveMains.map(m => m.record.pid);
+        const expectedStarts = new Map(aliveMains.map(m => [m.record.pid, m.record.startedAt]));
         log(`Monitoring ${oldPids.length} main process(es): ${oldPids.join(', ')}`);
         const gracefulPid = await requestDaemonShutdown(p.socket, DAEMON_SHUTDOWN_TIMEOUT_MS, 'restart-monitor', new Set(oldPids));
         // 没有收到 IPC shutdown 确认的进程才走信号兜底
@@ -177,15 +190,39 @@ export async function cmdRestartMonitor() {
             }
         }
         const exited = await Promise.all(oldPids.map(async (oldPid) => {
+            const expectedStartedAt = expectedStarts.get(oldPid);
+            if (isPidReused(oldPid, expectedStartedAt)) {
+                reportPidReused(oldPid, log);
+                return true;
+            }
             if (await platform.waitForProcessExit(oldPid, 30_000)) {
+                if (isPidReused(oldPid, expectedStartedAt)) {
+                    reportPidReused(oldPid, log);
+                    return true;
+                }
                 log(`Process ${oldPid} has exited`);
                 return true;
             }
-            log(`ERROR: Process ${oldPid} still running after 30s, force killing`);
+            if (isPidReused(oldPid, expectedStartedAt)) {
+                reportPidReused(oldPid, log);
+                return true;
+            }
+            const state = platform.getProcessState(oldPid);
+            log(`ERROR: Process ${oldPid} still running after 30s${state ? ` (state=${state})` : ''}, force killing`);
+            if (isPidReused(oldPid, expectedStartedAt)) {
+                reportPidReused(oldPid, log);
+                return true;
+            }
             platform.killProcess(oldPid, true);
             const forced = await platform.waitForProcessExit(oldPid, 5_000);
-            if (!forced)
-                log(`ERROR: Process ${oldPid} survived forced termination`);
+            if (isPidReused(oldPid, expectedStartedAt)) {
+                reportPidReused(oldPid, log);
+                return true;
+            }
+            if (!forced) {
+                const finalState = platform.getProcessState(oldPid);
+                log(`ERROR: Process ${oldPid} survived forced termination${finalState ? ` (state=${finalState})` : ''}`);
+            }
             return forced;
         }));
         if (exited.some(result => !result)) {
@@ -194,7 +231,9 @@ export async function cmdRestartMonitor() {
             cleanupPendingFile(pendingFile, log);
             process.exit(1);
         }
-        await sleep(3000);
+        // waitForProcessExit above already observed the old daemon exit. A fixed
+        // three-second delay only serialized the restart path and was not needed
+        // for instance-file cleanup.
         cleanupInstances();
     }
     // 版本检查与自动升级
@@ -202,7 +241,10 @@ export async function cmdRestartMonitor() {
     // 升级会原地替换整包，先留一个可回退的产物副本。备份放 EVOLCORE_HOME 而非包目录：
     // Linux/macOS 的全局目录常常不可写，而 HOME 一定可写。
     const upgradeBackup = await backupDistForUpgrade(p, log);
-    const upgrade = await tryUpgrade();
+    const [upgrade, ecwebUpgrade] = await Promise.all([
+        tryUpgrade(),
+        tryUpgradeGlobalPkg(() => resolveGlobalPkg(WEB_PACKAGE_NAME), WEB_PACKAGE_NAME),
+    ]);
     let upgradeRolledBack;
     switch (upgrade.status) {
         case 'upgraded':
@@ -243,8 +285,8 @@ export async function cmdRestartMonitor() {
             await notifyDaemonOwners(p, `⚠️ evolcore 升级失败，使用当前版本继续\n${upgrade.error ?? ''}`.trim(), log);
             break;
     }
-    // EC Web 是独立全局包，已安装时单独检查升级。
-    const ecwebUpgrade = await tryUpgradeGlobalPkg(() => resolveGlobalPkg(WEB_PACKAGE_NAME), WEB_PACKAGE_NAME);
+    // EC Web 是独立全局包，已安装时单独检查升级；与 EvolCore registry
+    // 查询并行执行，npm 安装阶段由 npm-ops 的全局锁串行化。
     switch (ecwebUpgrade.status) {
         case 'upgraded':
             log(`✅ ${WEB_PACKAGE_NAME} upgraded: ${ecwebUpgrade.from} → ${ecwebUpgrade.to}`);
@@ -710,6 +752,11 @@ async function revertToPreviousBuild(log) {
  * back up or the copy failed — the caller then knows rollback is unavailable.
  */
 async function backupDistForUpgrade(p, log) {
+    // Linked/source checkouts cannot be upgraded by npm. Copying dist/ here was
+    // pure restart overhead and made every source restart rewrite the artifact
+    // tree even when no build was needed.
+    if (fs.existsSync(path.join(targetPackageRoot(), 'src')))
+        return null;
     const distDir = path.join(targetPackageRoot(), 'dist');
     if (!distArtifactIsUsable(distDir))
         return null;

package/dist/config/builtin-roles.js

@@ -34,6 +34,7 @@ export function getManagementCommandPermissions(role) {
         'contact.read': { allow: true, scopes: ['agent'] },
         'contact.add': { allow: true, scopes: ['relation'], constraints: { ownPeerOnly: true, privateOnly: true } },
         'contact.block': { allow: true, scopes: ['agent'], constraints: { requireAgentAdmin: true } },
+        'contact.review': { allow: true, scopes: ['agent'], constraints: { requireAgentAdmin: true } },
         'connect.write': { allow: true, scopes: ['agent'], constraints: { requireAgentAdmin: true } },
         'connect.access.write': { allow: true, scopes: ['agent'], constraints: { requireAgentOwner: true } },
         'role.assign': { allow: true, scopes: ['agent'] },
@@ -51,6 +52,7 @@ export function getManagementCommandPermissions(role) {
         'ec.aid.lookup': { allow: true, scopes: ['agent'] },
         'ec.aid.agentmd.get': { allow: true, scopes: ['agent'] },
         'ec.aid.agentmd.put': { allow: true, dangerous: true, scopes: ['agent'], constraints: { targetCurrentAgentOnly: true, requireAgentAdmin: true } },
+        'ec.aid.avatar': { allow: true, dangerous: true, scopes: ['agent'], constraints: { targetCurrentAgentOnly: true, requireAgentOwner: true } },
         'ec.fs.mkdir': { allow: true, permissionMode: 'auto', scopes: ['relation'], constraints: { groupOnly: true, currentRelationOnly: true, targetCurrentAgentOnly: true } },
         'ec.fs.upload': { allow: true, permissionMode: 'auto', scopes: ['relation'], constraints: { groupOnly: true, currentRelationOnly: true, targetCurrentAgentOnly: true } },
         'ec.fs.copy': { allow: true, permissionMode: 'auto', scopes: ['relation'], constraints: { groupOnly: true, currentRelationOnly: true, targetCurrentAgentOnly: true } },

package/dist/config/config-manager.js

@@ -679,6 +679,21 @@ function groupFor(target, sel) {
 function normalizeAgentConfigForWrite(value) {
     const mutable = normalizeBaseagentEffortCompat({ ...value });
     normalizeShowActivitiesCompat(mutable);
+    if (Object.prototype.hasOwnProperty.call(mutable, 'owners')) {
+        if (!Array.isArray(mutable.owners)) {
+            throw new ConfigError('VALIDATION_ERROR', 'owners must be an array');
+        }
+        const owners = [];
+        for (const rawOwner of mutable.owners) {
+            if (typeof rawOwner !== 'string' || !rawOwner.trim() || !isValidAid(rawOwner.trim())) {
+                throw new ConfigError('VALIDATION_ERROR', `Invalid owner AID: ${JSON.stringify(rawOwner)}`);
+            }
+            const owner = rawOwner.trim();
+            if (!owners.includes(owner))
+                owners.push(owner);
+        }
+        mutable.owners = owners;
+    }
     // AID 格式校验
     if (mutable.aid && !isValidAid(mutable.aid)) {
         throw new ConfigError('VALIDATION_ERROR', `Invalid aid "${mutable.aid}" (must be a valid multi-level domain like mybot.agentid.pub)`);

package/dist/config/config-operation-service.js

@@ -5,6 +5,9 @@ import { currentVersion, fieldSchemaDefault, isSchemaName, listSchemaNames, list
 import fs from 'fs';
 import path from 'path';
 import { resolvePaths, agentDir, agentRelationConfig } from '../paths.js';
+import { roleMenuQuery, roleMenuUpdate } from '../core/command/role-menu.js';
+import { parsePeerKey } from '../core/relation/peer-identity.js';
+import { isExplicitGroupId } from '../aun/group-identity.js';
 export const AUTHENTICATED_CONFIG_ROLE_ENV = 'EVOLCORE_AUTHENTICATED_CONFIG_ROLE';
 export function executeResolvedConfigCommand(command, options = {}) {
     try {
@@ -23,6 +26,134 @@ export function executeResolvedConfigCommand(command, options = {}) {
         return { ok: false, code: 'CONFIG_ERROR', error: error instanceof Error ? error.message : String(error) };
     }
 }
+/**
+ * Execute a config command that may use an asynchronous domain service.
+ * Relation role assignments are intentionally handled here instead of by
+ * mutateConfig(), so Role Menu remains the single write path for validation,
+ * revisions, journaling, and audit.
+ */
+export async function executeResolvedConfigCommandAsync(command, options = {}) {
+    try {
+        if (isRelationRoleCommand(command)) {
+            return await executeRelationRoleCommand(command, options);
+        }
+        return executeResolvedConfigCommand(command, options);
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            return { ok: false, code: error.code, error: error.message, ...(error.data !== undefined ? { data: error.data } : {}) };
+        const roleError = error;
+        return {
+            ok: false,
+            code: roleError?.code || 'CONFIG_ERROR',
+            error: roleError?.message || String(error),
+            ...(roleError?.data !== undefined ? { data: roleError.data } : {}),
+        };
+    }
+}
+function isRelationRoleCommand(command) {
+    return command.kind === 'field'
+        && command.field === 'role'
+        && command.configScope === 'relation'
+        && (command.operationId === 'role.relation.read'
+            || command.operationId === 'role.assign'
+            || command.operationId === 'role.revoke');
+}
+async function executeRelationRoleCommand(op, options) {
+    if (!op.self || !op.peerKey) {
+        return { ok: false, code: 'PEER_REQUIRED', error: 'role requires --self <aid> --peer <peer-aid>' };
+    }
+    const target = roleTargetFromPeerKey(op.peerKey);
+    const context = options.roleContext ?? {
+        self: op.self,
+        actorRole: options.role || 'owner',
+        actorRoleSource: 'local-cli',
+        isDaemonOwner: false,
+        fromControlChannel: false,
+        aunAvailable: true,
+    };
+    if (context.self !== op.self) {
+        return { ok: false, code: 'SCOPE_MISMATCH', error: 'Role target does not match the receiving Agent' };
+    }
+    const targetArgs = { self: op.self, view: 'target', target };
+    const current = await roleMenuQuery(context, targetArgs);
+    const explicitRole = current?.assignment?.explicitRole
+        ?? current?.assignment?.explicitDefaultRole
+        ?? null;
+    const effectiveRole = current?.effectiveRole?.roleId
+        ?? current?.baselineRole?.roleId
+        ?? null;
+    const effectiveRoleSource = current?.effectiveRole?.source
+        ?? current?.baselineRole?.source
+        ?? 'none';
+    const roleDetails = { explicitRole, effectiveRole, effectiveRoleSource };
+    if (op.subcommand === 'get') {
+        return {
+            ok: true,
+            subcommand: 'get',
+            field: op.field,
+            value: explicitRole,
+            scope: op.configScope,
+            roleDetails,
+        };
+    }
+    const nextValue = op.subcommand === 'unset' ? null : op.value;
+    const updated = await roleMenuUpdate(context, {
+        self: op.self,
+        resource: 'assignment',
+        target,
+        expectedPolicyRevision: current.policyRevision,
+        expectedRelationRevision: current.relationRevision,
+    }, JSON.stringify(nextValue));
+    const updatedExplicitRole = updated?.assignment?.explicitRole
+        ?? updated?.assignment?.explicitDefaultRole
+        ?? null;
+    const updatedEffectiveRole = updated?.effectiveRole?.roleId
+        ?? updated?.baselineRole?.roleId
+        ?? null;
+    const updatedEffectiveRoleSource = updated?.effectiveRole?.source
+        ?? updated?.baselineRole?.source
+        ?? 'none';
+    const updatedDetails = {
+        explicitRole: updatedExplicitRole,
+        effectiveRole: updatedEffectiveRole,
+        effectiveRoleSource: updatedEffectiveRoleSource,
+    };
+    if (op.subcommand === 'unset') {
+        return {
+            ok: true,
+            subcommand: 'unset',
+            field: op.field,
+            removed: updated.changed === true,
+            scope: op.configScope,
+            roleDetails: updatedDetails,
+        };
+    }
+    return {
+        ok: true,
+        subcommand: 'set',
+        field: op.field,
+        value: updatedExplicitRole,
+        scope: op.configScope,
+        file: 'relation-config',
+        roleDetails: updatedDetails,
+    };
+}
+function roleTargetFromPeerKey(peerKey) {
+    let parsed;
+    try {
+        parsed = parsePeerKey(peerKey);
+    }
+    catch {
+        throw new ConfigError('INVALID_SELECTOR', `Invalid relation peer key: ${peerKey}`);
+    }
+    if (parsed.channelType !== 'aun') {
+        throw new ConfigError('NOT_SUPPORTED', 'Relation role assignments currently support AUN peers only');
+    }
+    return isExplicitGroupId(parsed.channelId)
+        ? { kind: 'group', groupId: parsed.channelId }
+        : { kind: 'private', peerAid: parsed.channelId };
+}
 export function executeResolvedConfigOperation(op, options = {}) {
     try {
         const missingAgent = selectedAgentError(op);
@@ -298,10 +429,25 @@ function getWithSchemaDefault(op, absent, note) {
     return { ok: true, subcommand: 'get', field: op.field, value: absent, scope: op.configScope, ...nt };
 }
 function executeSet(op, options) {
+    if (op.field === 'role') {
+        return {
+            ok: false,
+            code: 'ROLE_POLICY_MANAGED',
+            error: 'Relation role assignments require the asynchronous role assignment service',
+        };
+    }
     if (!op.route)
         return { ok: false, code: 'UNKNOWN_FIELD', error: `Unknown config field: ${op.field}` };
     const selector = selectorFor(op, options);
-    mutateConfig(op.route.target, selector, existing => {
+    const mutation = mutateConfig(op.route.target, selector, existing => {
+        if (op.field === 'owners' && op.route.target === ConfigTarget.Agent) {
+            const nextOwners = Array.isArray(op.value) ? op.value : [];
+            if (nextOwners.length === 0) {
+                throw new ConfigError('LAST_OWNER_PROTECTED', 'owners must contain at least one owner');
+            }
+            setNested(existing, op.field, nextOwners);
+            return nextOwners;
+        }
         if (op.route.merge === 'list') {
             const previous = getNested(existing, op.field);
             const previousItems = Array.isArray(previous) ? previous : [];
@@ -316,25 +462,41 @@ function executeSet(op, options) {
                 }
             });
             setNested(existing, op.field, merged);
+            return merged;
         }
         else {
             setNested(existing, op.field, op.value);
+            return op.value;
         }
     });
     return {
         ok: true,
         subcommand: 'set',
         field: op.field,
-        value: op.value,
+        value: mutation.value,
         scope: op.configScope,
         file: op.route.schema,
     };
 }
 function executeUnset(op, options) {
+    if (op.field === 'role') {
+        return {
+            ok: false,
+            code: 'ROLE_POLICY_MANAGED',
+            error: 'Relation role assignments require the asynchronous role assignment service',
+        };
+    }
     if (!op.route)
         return { ok: false, code: 'UNKNOWN_FIELD', error: `Unknown config field: ${op.field}` };
     const selector = selectorFor(op, options);
-    const { value: removed } = mutateConfig(op.route.target, selector, existing => {
+    const target = op.route.target;
+    const { value: removed } = mutateConfig(target, selector, existing => {
+        if (op.field === 'owners' && target === ConfigTarget.Agent) {
+            const current = getNested(existing, op.field);
+            if (Array.isArray(current) && current.length > 0) {
+                throw new ConfigError('LAST_OWNER_PROTECTED', 'cannot unset owners while an Agent still has owners; use owners replace with another owner');
+            }
+        }
         const parts = op.field.split('.');
         let current = existing;
         for (let i = 0; i < parts.length - 1; i++) {