evolcore 0.0.1 → 0.0.3

package/dist/config/boot-log.js

@@ -0,0 +1,266 @@
+/**
+ * boot-log —— 启动日志与自检回落（design §九 + 双指针模型）。
+ *
+ * boot-log.jsonl：每次成功启动追加一行（最近 300 条，超限按月归档）。
+ * 自检模式：逐版本回落尝试，**展开版本到 W 并真实启动**（不是内存探测）。
+ *   - P4:进入时若 W≠w-version,先把 W 存档（successCount=0）
+ *   - 回落序列：从 current 往老遍历，跳过 successCount==0 的版本（例外：最新两个无条件参与）
+ *   - 回落 = 展开版本到 W + writeWVersion，current 不动
+ *   - Q-C:全失败 → 还原成最新版本
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolvePaths } from '../paths.js';
+import { logger } from '../utils/logger.js';
+import { readCurrent, readWVersion, writeWVersion, materializeVersion, listAllVersions, diffVersions, snapshot, isConfigSnapshotsEnabled, } from './snapshot.js';
+const MAX_LINES = 300;
+const KEEP_MIN = 150;
+const FALLBACK_MAX_TRIES = 20;
+const FALLBACK_MAX_MS = 120_000;
+export function appendBootLog(entry) {
+    if (!isConfigSnapshotsEnabled())
+        return;
+    const p = resolvePaths().configBootLog;
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf-8');
+    archiveIfNeeded(p);
+}
+/** 读最近 n 条 boot-log（含归档回溯）。 */
+export function readBootLog(n) {
+    const p = resolvePaths().configBootLog;
+    let lines = [];
+    try {
+        lines = fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean);
+    }
+    catch { /* none */ }
+    if (lines.length < n) {
+        const archDir = resolvePaths().configBootLogArchiveDir;
+        if (fs.existsSync(archDir)) {
+            const archFiles = fs.readdirSync(archDir).filter(f => f.endsWith('.jsonl')).sort().reverse();
+            for (const f of archFiles) {
+                const more = fs.readFileSync(path.join(archDir, f), 'utf-8').split('\n').filter(Boolean);
+                lines = [...more, ...lines];
+                if (lines.length >= n)
+                    break;
+            }
+        }
+    }
+    return lines.slice(-n).map(l => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return null;
+    } }).filter(Boolean);
+}
+function archiveIfNeeded(file) {
+    let lines;
+    try {
+        lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+    }
+    catch {
+        return;
+    }
+    if (lines.length <= MAX_LINES)
+        return;
+    const archDir = resolvePaths().configBootLogArchiveDir;
+    fs.mkdirSync(archDir, { recursive: true });
+    const monthOf = (l) => {
+        try {
+            return JSON.parse(l).bootedAt.slice(0, 7);
+        }
+        catch {
+            return 'unknown';
+        }
+    };
+    const thisMonth = monthOf(lines[lines.length - 1]);
+    const keep = [];
+    const archived = {};
+    for (const l of lines) {
+        const m = monthOf(l);
+        if (m === thisMonth)
+            keep.push(l);
+        else
+            (archived[m] = archived[m] || []).push(l);
+    }
+    // 本月不足 KEEP_MIN，则从归档里补最新的回来
+    if (keep.length < KEEP_MIN) {
+        const flatArch = lines.filter(l => monthOf(l) !== thisMonth);
+        const need = KEEP_MIN - keep.length;
+        const backfill = flatArch.slice(-need);
+        keep.unshift(...backfill);
+        // 从 archived 中移除 backfill
+        const backfillSet = new Set(backfill);
+        for (const m of Object.keys(archived))
+            archived[m] = archived[m].filter(l => !backfillSet.has(l));
+    }
+    for (const [m, ls] of Object.entries(archived)) {
+        if (ls.length === 0)
+            continue;
+        fs.appendFileSync(path.join(archDir, `${m}.jsonl`), ls.join('\n') + '\n', 'utf-8');
+    }
+    fs.writeFileSync(file, keep.join('\n') + '\n', 'utf-8');
+}
+/**
+ * 自检模式：逐版本展开到 W，真实探测配置加载，找到第一个可用版本。
+ *   - P4: W≠w-version → 先把 W 存档（保留你的改动，即使是坏的）
+ *   - 回落序列: 从 current 往老，跳过 successCount==0（例外：序列中最新两个无条件参与）
+ *   - 展开 = 覆盖 W + writeWVersion；current 始终不动
+ *   - Q-C: 全失败 → 还原成最新版本（W 原样回来）
+ * probe: 注入点，默认用 loadAllAgents 检测配置层，也用于测试。
+ */
+export async function selfDiagnose(probe, now = () => Date.now()) {
+    if (!isConfigSnapshotsEnabled()) {
+        return {
+            ok: false,
+            selectedVersion: readCurrent(),
+            actualVersion: readWVersion(),
+            fellBack: false,
+            triedVersions: [],
+            message: '配置快照功能已关闭；请先设置 configSnapshots=true',
+        };
+    }
+    const selected = readCurrent();
+    const wVer = readWVersion();
+    const root = resolvePaths().root;
+    // P4: W 有未存改动 → 先把 W 存档（坏的也存，保留改动）
+    // 判断：w-version 不存在，或 W 内容 ≠ w-version 指向的内容
+    const wHasChanges = !wVer || await workingDiffersFromVersion(wVer.delta);
+    if (wHasChanges) {
+        snapshot('manual', { description: 'diagnose: archive current W before fallback' });
+        // snapshot 已经更新了 current + w-version 到新版本
+    }
+    // 构建候选序列（从 current 往老遍历）
+    const allVersions = listAllVersions().sort((a, b) => cmpVer(b.version, a.version)); // 降序
+    const cur = readCurrent(); // P4 后重读（可能已更新）
+    const startIdx = cur ? allVersions.findIndex(m => m.version === cur.delta) : 0;
+    const sequence = startIdx >= 0 ? allVersions.slice(startIdx) : allVersions;
+    // 回落资格：successCount>0，或属序列中最新两个
+    const candidates = sequence.filter((m, i) => i < 2 || m.successCount > 0);
+    if (candidates.length === 0) {
+        const latest = allVersions[0]?.version;
+        if (latest)
+            await expandToW(latest, root);
+        return {
+            ok: false, selectedVersion: selected, actualVersion: null, fellBack: false, triedVersions: [],
+            message: '✗ 自检失败：无可用候选版本（所有版本 successCount=0）。已还原到最新版本。',
+        };
+    }
+    const probeFn = probe ?? await makeDefaultProbe();
+    const tried = [];
+    const t0 = now();
+    let tryCount = 0;
+    for (const candidate of candidates) {
+        if (tryCount > 0) {
+            if (tryCount > FALLBACK_MAX_TRIES) {
+                await expandToW(allVersions[0].version, root); // Q-C
+                return breakerResult('tries', selected, tried);
+            }
+            if (now() - t0 > FALLBACK_MAX_MS) {
+                await expandToW(allVersions[0].version, root); // Q-C
+                return breakerResult('time', selected, tried);
+            }
+        }
+        tryCount++;
+        tried.push(candidate.version);
+        // 展开到 W
+        await expandToW(candidate.version, root);
+        let ok = false;
+        try {
+            ok = probeFn();
+        }
+        catch {
+            ok = false;
+        }
+        if (ok) {
+            const actual = findVersionPtr(candidate.version, allVersions);
+            const fellBack = !selected || selected.delta !== candidate.version;
+            if (fellBack)
+                printFallbackInfo(selected, actual);
+            return { ok: true, selectedVersion: selected, actualVersion: actual, fellBack, triedVersions: tried };
+        }
+    }
+    // Q-C: 全失败 → 还原最新版本
+    if (allVersions.length > 0)
+        await expandToW(allVersions[0].version, root);
+    return {
+        ok: false, selectedVersion: selected, actualVersion: null, fellBack: false, triedVersions: tried,
+        message: `✗ 自检失败：已尝试 ${tried.length} 个候选版本（${tried.join('→')}）仍无可用。已还原最新版本。`,
+    };
+}
+async function expandToW(version, root) {
+    const all = listAllVersions();
+    const m = all.find(x => x.version === version);
+    if (!m)
+        return;
+    const full = m.baseVersion || version;
+    const files = materializeVersion(full, version);
+    // 删除 W 中不在目标版本的配置文件
+    const { collectConfigFiles } = await import('./snapshot.js');
+    const existing = collectConfigFiles(root);
+    for (const rel of existing) {
+        if (!files.has(rel)) {
+            try {
+                fs.unlinkSync(path.join(root, rel));
+            }
+            catch { /* */ }
+        }
+    }
+    for (const [rel, content] of files) {
+        const dest = path.join(root, rel);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, content, 'utf-8');
+    }
+    writeWVersion({ full, delta: version });
+}
+async function workingDiffersFromVersion(version) {
+    const { diffWorkingVsVersion } = await import('./snapshot.js');
+    const d = diffWorkingVsVersion(version);
+    if ('error' in d)
+        return true;
+    return d.added.length + d.modified.length + d.deleted.length > 0;
+}
+async function makeDefaultProbe() {
+    // 延迟 import 避免循环依赖：config-store → config，boot-log 在 config
+    const { loadAllAgents } = await import('../config-store.js');
+    return () => {
+        try {
+            const { agents } = loadAllAgents();
+            return agents.length > 0;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+function cmpVer(a, b) {
+    return parseInt(a.slice(1)) - parseInt(b.slice(1));
+}
+function findVersionPtr(version, all) {
+    const m = all.find(x => x.version === version);
+    return { full: m?.baseVersion || version, delta: version };
+}
+function breakerResult(kind, selected, tried) {
+    const msg = kind === 'tries'
+        ? `✗ 自检失败：回落尝试达到 ${FALLBACK_MAX_TRIES} 次上限（${tried.join('→')}）。已还原最新版本。`
+        : `✗ 自检失败：回落耗时超过 2 分钟（已尝试 ${tried.join('→')}）。已还原最新版本。`;
+    return { ok: false, selectedVersion: selected, actualVersion: null, fellBack: false, triedVersions: tried, breaker: kind, message: msg };
+}
+function printFallbackInfo(selected, actual) {
+    const lines = [`⚠ 当前版本 ${selected?.delta ?? '?'} 启动失败，已回落到 ${actual.delta}。`];
+    // 参数级差异：actual(W现状) vs selected(失败版本)
+    if (selected) {
+        const d = diffVersions(actual.delta, selected.delta);
+        if (!('error' in d)) {
+            const changed = [...d.modified, ...d.added, ...d.deleted];
+            if (changed.length)
+                lines.push(`  变化文件：${changed.join(', ')}`);
+        }
+        lines.push(`  失败版本 vs 回落版本的参数差异：ec config diff ${actual.delta} ${selected.delta}`);
+    }
+    lines.push(`  current.json 仍指向 ${selected?.delta ?? '?'}（未改写）。`);
+    lines.push(`  采用回落版本：ec config restore ${actual.delta}`);
+    logger.warn(lines.join('\n'));
+    console.error(lines.join('\n'));
+}
+/** restore 回落版本到工作目录（采用某可用版本时调用）。委托 snapshot.restore。 */
+export { readCurrent };

package/dist/config/builtin-role-templates.js

@@ -0,0 +1,42 @@
+import fs from 'fs';
+import path from 'path';
+import { kitsRoleTemplatesDir } from '../paths.js';
+import { validateRoleConfig } from './role-schema.js';
+import { expectedRoleRank } from './role-ranks.js';
+export const BUILTIN_ROLE_IDS = ['owner', 'admin', 'member', 'visitor'];
+export function validateBuiltinRoleTemplateDefinition(roleId, raw) {
+    const issues = validateRoleConfig(raw);
+    if (issues.length) {
+        return {
+            definition: null,
+            error: `built-in role template failed validation: ${issues.map(issue => `${issue.field} ${issue.message}`).join('; ')}`,
+        };
+    }
+    const { $schema_version: _schemaVersion, ...definition } = raw;
+    if (BUILTIN_ROLE_IDS.includes(roleId)) {
+        const expectedRank = expectedRoleRank(roleId);
+        if (definition.rank !== expectedRank) {
+            return {
+                definition: null,
+                error: `built-in role template rank must be ${expectedRank}`,
+            };
+        }
+    }
+    return { definition: definition };
+}
+/** Load the versioned package template that defines a built-in role policy. */
+export function readBuiltinRoleTemplate(roleId) {
+    const file = path.join(kitsRoleTemplatesDir(), `${roleId}.json`);
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        return {
+            definition: null,
+            file,
+            error: `cannot read built-in role template: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return { ...validateBuiltinRoleTemplateDefinition(roleId, raw), file };
+}

package/dist/config/builtin-roles.js

@@ -0,0 +1,91 @@
+import { readBuiltinRoleTemplate } from './builtin-role-templates.js';
+import { expectedRoleRank } from './role-ranks.js';
+export { expectedRoleRank, ROLE_RANKS } from './role-ranks.js';
+export const BUILTIN_USER_ROLES = ['member', 'visitor'];
+export const MANAGEMENT_ROLES = ['owner', 'admin'];
+export function isManagementRole(role) {
+    return role === 'owner' || role === 'admin';
+}
+export function isReservedRoleName(role) {
+    return isManagementRole(role);
+}
+/** Built-in user policy data comes exclusively from kits/templates/roles. */
+export function getBuiltinRolesConfig() {
+    return {
+        $schema_version: 1,
+        defaultRoles: { private: null, group: null },
+        roles: Object.fromEntries(BUILTIN_USER_ROLES.flatMap(roleId => {
+            const definition = readBuiltinRoleTemplate(roleId).definition;
+            return definition ? [[roleId, definition]] : [];
+        })),
+    };
+}
+/**
+ * Management grants are a code-level ceiling, not configurable role policy.
+ * A role file may narrow these rules but can never add a management grant.
+ */
+export function getManagementCommandPermissions(role) {
+    return {
+        'contact.read': { allow: true, scopes: ['agent'] },
+        'contact.block': { allow: true, scopes: ['agent'] },
+        'role.assign': { allow: true, scopes: ['agent'] },
+        'role.revoke': { allow: true, scopes: ['agent'] },
+        'role.policy.read': { allow: true, scopes: ['agent'] },
+        'role.relation.read': { allow: true, scopes: ['agent'] },
+        'role.policy.write': { allow: true, dangerous: true, scopes: ['agent'], constraints: { requireAgentAdmin: true } },
+        '*': { allow: true },
+        'agent.reload': { allow: true, dangerous: true, scopes: ['agent'], constraints: { targetCurrentAgentOnly: true, requireAgentAdmin: true } },
+        'dangerous:*': { allow: true, dangerous: true, constraints: { requireDaemonOwner: true } },
+    };
+}
+export function applyManagementRoleCeiling(role, configured) {
+    const fallback = {
+        description: role === 'owner' ? 'Agent owner' : 'Agent administrator',
+        rank: expectedRoleRank(role),
+        allowAccess: true,
+        permissions: {
+            permissionMode: { default: 'request', allowOverride: false },
+        },
+        commandPermissions: getManagementCommandPermissions(role),
+    };
+    const policy = configured ?? readBuiltinRoleTemplate(role).definition ?? fallback;
+    return {
+        ...policy,
+        rank: expectedRoleRank(role),
+        allowAccess: true,
+        commandPermissions: narrowManagementCommandPermissions(getManagementCommandPermissions(role), policy.commandPermissions || {}),
+    };
+}
+export function getManagementRoleDefinition(role) {
+    return applyManagementRoleCeiling(role);
+}
+function narrowManagementCommandPermissions(ceiling, configured) {
+    const merged = {};
+    for (const [operation, permission] of Object.entries(ceiling)) {
+        const override = configured[operation];
+        if (!override || typeof override !== 'object') {
+            merged[operation] = { ...permission };
+            continue;
+        }
+        const next = { ...permission };
+        if (override.allow === false)
+            next.allow = false;
+        if (override.dangerous === false)
+            next.dangerous = false;
+        if (Array.isArray(permission.scopes) && Array.isArray(override.scopes)) {
+            next.scopes = permission.scopes.filter(scope => override.scopes.includes(scope));
+        }
+        else if (!Array.isArray(permission.scopes) && Array.isArray(override.scopes)) {
+            next.scopes = [...override.scopes];
+        }
+        merged[operation] = next;
+    }
+    // Exact or namespace denies may narrow grants inherited through the ceiling's
+    // wildcard. New allow rules are ignored because they could bypass ceiling constraints.
+    for (const [operation, permission] of Object.entries(configured)) {
+        if (!Object.hasOwn(merged, operation) && permission?.allow === false) {
+            merged[operation] = { ...permission, allow: false };
+        }
+    }
+    return merged;
+}

package/dist/config/config-batch-get.js

@@ -0,0 +1,11 @@
+import { normalizeCliArgv } from '../cli/cli-argv.js';
+export function splitConfigBatchGetArgv(inputArgv) {
+    const argv = normalizeCliArgv(inputArgv);
+    if (argv[0] !== 'config' || argv[1] !== 'get')
+        return null;
+    const fields = [];
+    let i = 2;
+    for (; i < argv.length && !argv[i].startsWith('-'); i++)
+        fields.push(argv[i]);
+    return { fields, rest: argv.slice(i) };
+}

package/dist/config/config-field-policy.js

@@ -0,0 +1,261 @@
+const BEHAVIOR_TOP_FIELDS = new Set([
+    'active_baseagent',
+    'chatmode',
+    'mentionMode',
+    'responseMode',
+    'responseModeParams',
+    'flush_delay',
+    'debounce',
+    'show_activities',
+    'session_renew',
+    'group_venue_sync',
+    'render',
+    'sessionManifests',
+    'enable_rich_content',
+]);
+const BASEAGENT_BEHAVIOR_FIELDS = new Set([
+    'model',
+    'effort',
+    'reasoning',
+    'agentProgressSummaries',
+    'excludeDynamicSections',
+    'enableRequestUserInput',
+    'approvalsReviewer',
+    'mode',
+    'useVertex',
+]);
+const SUPPORTED_BASEAGENTS = new Set(['claude', 'codex', 'gemini', 'hermes']);
+const SENSITIVE_TOP_FIELDS = new Set([
+    '$schema_version',
+    'aid',
+    'enabled',
+    'lifecycle',
+    'initialized',
+    'owners',
+    'admins',
+    'channels',
+    'aun',
+    'models',
+    'projects',
+    'capabilities',
+    'debug',
+    'observable',
+    'roles',
+    'role',
+    'extra_backup',
+]);
+const CRITICAL_AGENT_FIELDS = new Set(['owners', 'admins', 'roles']);
+const EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+function scalar(rolePermissionKey, valueKind) {
+    return { class: 'safe-scalar', rolePermissionKey, valueKind };
+}
+function readonlyObject(rolePermissionKey) {
+    return { class: 'safe-readonly-object', rolePermissionKey };
+}
+export function isBehaviorConfigFieldPath(fieldPath) {
+    const parts = fieldPath.split('.');
+    if (parts[0] === 'baseagents') {
+        return parts.length >= 3 && BASEAGENT_BEHAVIOR_FIELDS.has(parts[2]);
+    }
+    return BEHAVIOR_TOP_FIELDS.has(parts[0]);
+}
+export function resolveConfigFieldRule(fieldPath) {
+    const field = fieldPath.trim();
+    if (!field)
+        return { class: 'unknown' };
+    const parts = field.split('.');
+    const top = parts[0];
+    if (SENSITIVE_TOP_FIELDS.has(top))
+        return { class: 'sensitive' };
+    if (top === 'baseagents') {
+        if (parts.length < 3)
+            return { class: 'sensitive' };
+        const [, baseagent, leaf] = parts;
+        if (!SUPPORTED_BASEAGENTS.has(baseagent))
+            return { class: 'unknown' };
+        const permissionKey = `baseagents.${baseagent}.${leaf}`;
+        if (leaf === 'model' && parts.length === 3)
+            return scalar(permissionKey, 'string');
+        if ((leaf === 'effort' || leaf === 'reasoning') && parts.length === 3)
+            return scalar(permissionKey, 'effort');
+        if (baseagent === 'claude' && (leaf === 'agentProgressSummaries' || leaf === 'excludeDynamicSections') && parts.length === 3) {
+            return scalar(permissionKey, 'boolean');
+        }
+        if (baseagent === 'codex' && leaf === 'enableRequestUserInput' && parts.length === 3) {
+            return scalar(permissionKey, 'boolean');
+        }
+        if (baseagent === 'codex' && leaf === 'approvalsReviewer' && parts.length === 3) {
+            return scalar(permissionKey, 'approvals-reviewer');
+        }
+        if (baseagent === 'gemini' && leaf === 'mode' && parts.length === 3)
+            return scalar(permissionKey, 'gemini-mode');
+        if (baseagent === 'gemini' && leaf === 'useVertex' && parts.length === 3)
+            return scalar(permissionKey, 'boolean');
+        return { class: 'sensitive' };
+    }
+    if (field === 'active_baseagent')
+        return scalar(field, 'baseagent');
+    if (field === 'flush_delay' || field === 'debounce')
+        return scalar(field, 'nonnegative-number');
+    if (field === 'mentionMode')
+        return scalar(field, 'mention-mode');
+    if (field === 'show_activities')
+        return scalar(field, 'show-activities');
+    if (field === 'enable_rich_content')
+        return scalar(field, 'boolean');
+    if (field === 'responseMode')
+        return scalar(field, 'string');
+    if (field === 'configSnapshots')
+        return scalar('configSnapshots', 'boolean');
+    if (top === 'chatmode') {
+        if (parts.length === 1)
+            return readonlyObject('chatmode');
+        if (parts.length === 2 && ['private', 'group', 'nothuman'].includes(parts[1])) {
+            return scalar('chatmode', 'chatmode');
+        }
+        return { class: 'unknown' };
+    }
+    if (top === 'responseMode') {
+        if (parts.length === 1)
+            return scalar('responseMode', 'string');
+        return { class: 'unknown' };
+    }
+    if (top === 'responseModeParams') {
+        // responseModeParams 是按模式分桶的字典，整体只读，子路径黑箱
+        return readonlyObject('responseModeParams');
+    }
+    if (top === 'session_renew') {
+        if (parts.length === 1)
+            return readonlyObject('session_renew');
+        if (parts.length !== 2)
+            return { class: 'unknown' };
+        if (parts[1] === 'enabled')
+            return scalar('session_renew', 'boolean');
+        if (parts[1] === 'after_hours')
+            return scalar('session_renew', 'positive-number');
+        if (parts[1] === 'effort')
+            return scalar('session_renew', 'effort');
+        if (parts[1] === 'fallback_action')
+            return scalar('session_renew', 'session-renew-action');
+        return { class: 'unknown' };
+    }
+    if (top === 'render') {
+        if (parts.length === 1)
+            return readonlyObject('render');
+        if (parts.length === 2 && ['private', 'group', 'inject'].includes(parts[1]))
+            return scalar('render', 'string');
+        return { class: 'unknown' };
+    }
+    if (top === 'sessionManifests') {
+        if (parts.length === 1)
+            return readonlyObject('sessionManifests');
+        if (parts.length === 2 && /^[A-Za-z0-9_-]+$/.test(parts[1]))
+            return scalar('sessionManifests', 'manifest-file');
+        return { class: 'unknown' };
+    }
+    if (top === 'group_venue_sync')
+        return parts.length === 1
+            ? readonlyObject('group_venue_sync')
+            : { class: 'unknown' };
+    return { class: 'unknown' };
+}
+export function isSafeBehaviorConfigField(fieldPath) {
+    const rule = resolveConfigFieldRule(fieldPath);
+    return rule.class === 'safe-scalar' || rule.class === 'safe-readonly-object';
+}
+export function isCriticalAgentControlField(fieldPath) {
+    return CRITICAL_AGENT_FIELDS.has(fieldPath.split('.')[0]);
+}
+export function resolveRoleFieldPermission(permissions, fieldPath) {
+    const rule = resolveConfigFieldRule(fieldPath);
+    if (!rule.rolePermissionKey)
+        return undefined;
+    return permissions[fieldPath] ?? permissions[rule.rolePermissionKey];
+}
+/**
+ * Map relation-scoped config fields back to their public command capability.
+ *
+ * The generic `config set/unset` transport must not become a permission bypass
+ * for the structured Menu operations that own these fields.
+ */
+export function relationFieldWriteOperation(fieldPath) {
+    const field = fieldPath.trim();
+    if (field === 'chatmode.private' || field === 'chatmode.group') {
+        return 'chatmode.update';
+    }
+    if (field === 'mentionMode')
+        return 'mentionmode.update';
+    if (/^baseagents\.[^.]+\.model$/.test(field))
+        return 'model.use';
+    if (/^baseagents\.[^.]+\.(?:effort|reasoning)$/.test(field)) {
+        return 'model.effort';
+    }
+    return undefined;
+}
+export function parseConfigFieldValue(fieldPath, rawValue) {
+    const rule = resolveConfigFieldRule(fieldPath);
+    if (rule.class !== 'safe-scalar' || !rule.valueKind) {
+        return { ok: false, reason: `Config field ${fieldPath} does not support scalar writes` };
+    }
+    if (typeof rawValue !== 'string')
+        return { ok: false, reason: `Config field ${fieldPath} requires a string CLI value` };
+    const raw = rawValue.trim();
+    switch (rule.valueKind) {
+        case 'string':
+            return raw ? { ok: true, value: raw } : { ok: false, reason: `Config field ${fieldPath} cannot be empty` };
+        case 'baseagent':
+            return SUPPORTED_BASEAGENTS.has(raw)
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} must name a supported baseagent` };
+        case 'boolean':
+            if (raw === 'true')
+                return { ok: true, value: true };
+            if (raw === 'false')
+                return { ok: true, value: false };
+            return { ok: false, reason: `Config field ${fieldPath} must be true or false` };
+        case 'nonnegative-number': {
+            const value = Number(raw);
+            return Number.isFinite(value) && value >= 0
+                ? { ok: true, value }
+                : { ok: false, reason: `Config field ${fieldPath} must be a non-negative number` };
+        }
+        case 'positive-number': {
+            const value = Number(raw);
+            return Number.isFinite(value) && value > 0
+                ? { ok: true, value }
+                : { ok: false, reason: `Config field ${fieldPath} must be a positive number` };
+        }
+        case 'effort':
+            return EFFORTS.has(raw)
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} must be one of ${[...EFFORTS].join(', ')}; use unset for auto` };
+        case 'chatmode':
+            return raw === 'interactive' || raw === 'proactive'
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} must be interactive or proactive` };
+        case 'mention-mode':
+            return raw === 'disabled' || raw === 'mention-only'
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} must be disabled or mention-only` };
+        case 'show-activities':
+            return raw === 'all' || raw === 'text' || raw === 'none'
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} must be all, text, or none` };
+        case 'approvals-reviewer':
+            return ['user', 'auto_review', 'guardian_subagent'].includes(raw)
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} has an invalid approvals reviewer` };
+        case 'gemini-mode':
+            return raw === 'cli' || raw === 'sdk'
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} must be cli or sdk` };
+        case 'manifest-file':
+            return /^[A-Za-z0-9_-]+\.json$/.test(raw)
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} must be a JSON filename without path separators` };
+        case 'session-renew-action':
+            return raw === 'continue' || raw === 'new'
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `Config field ${fieldPath} must be continue or new` };
+    }
+}