@lesliechan721/aw 0.1.0-beta.4 → 0.1.0-beta.40

package/dist/src/utils/plugin-config.js

@@ -1,20 +1,73 @@
 import crypto from 'node:crypto';
-import { AsyncLocalStorage } from 'node:async_hooks';
 import * as nodeFs from 'node:fs/promises';
 import path from 'node:path';
 import fs from 'fs-extra';
+import { canonicalizePluginConfigValues, formatPluginConfigIssue, getPluginConfigDependencyKeys, matchPluginConfigPreset, redactPluginConfigValue, stablePluginConfigStringify, validatePluginConfigCandidate, validatePluginConfigDocument, validatePluginConfigValue as validateCorePluginConfigValue, } from '@lesliechan721/aw-plugin-core/manifest';
 import { assertTestReadablePath, assertTestWritablePath, } from './test-path-fence.js';
-import { markActiveMarketplaceDurableCommit, withActiveMarketplaceRuntimeLease, } from './active-marketplace-runtime-lock.js';
 import { canonicalizePathThroughExistingAncestor, resolveAwHome, resolveRepoRootSync, } from './paths.js';
-import { acquireProcessLock } from './process-lock.js';
-const configCommitStorage = new AsyncLocalStorage();
-function markConfigDurableCommit() {
-    let context = configCommitStorage.getStore();
-    while (context) {
-        context.durableCommit = true;
-        context = context.parent;
+import { assertRealFileParentWithinRoot, assertSafeFileMutationPath, atomicReplaceSafeFile, } from './safe-fs.js';
+import { assertProjectSharedConfigPathVisible, PROJECT_CONFIG_SHAREABILITY_UNVERIFIED_WARNING, } from './project-boundary.js';
+export function codexNativeRefreshKeys(manifest) {
+    return new Set((manifest.artifacts?.targets ?? []).flatMap((target) => target.platform === 'codex'
+        && target.target === 'codex.skill'
+        && target.delivery?.mode === 'codex-native'
+        ? target.refreshKeys
+        : []));
+}
+function readPluginConfigBinding(value, scope) {
+    if (!isRecord(value))
+        return null;
+    if (scope === 'user') {
+        return value.kind === 'source'
+            && typeof value.sourceIdentity === 'string'
+            && /^sha256:[0-9a-f]{64}$/u.test(value.sourceIdentity)
+            && Object.keys(value).every((key) => ['kind', 'sourceIdentity'].includes(key))
+            ? { kind: 'source', sourceIdentity: value.sourceIdentity }
+            : null;
+    }
+    return value.kind === 'catalog'
+        && typeof value.logicalIdentity === 'string'
+        && value.logicalIdentity.trim().length > 0
+        && Object.keys(value).every((key) => ['kind', 'logicalIdentity'].includes(key))
+        ? { kind: 'catalog', logicalIdentity: value.logicalIdentity }
+        : null;
+}
+const PLUGIN_CONFIG_ENVELOPE_V5_KEYS = new Set([
+    'schemaVersion',
+    'sourceId',
+    'pluginName',
+    'binding',
+    'values',
+]);
+function readPluginConfigEnvelopeV5(value, scope) {
+    if (!isRecord(value)
+        || value.schemaVersion !== 5
+        || typeof value.sourceId !== 'string'
+        || typeof value.pluginName !== 'string'
+        || !isRecord(value.values)
+        || Object.keys(value).some((key) => !PLUGIN_CONFIG_ENVELOPE_V5_KEYS.has(key))) {
+        return null;
+    }
+    const binding = readPluginConfigBinding(value.binding, scope);
+    if (!binding)
+        return null;
+    return {
+        schemaVersion: 5,
+        sourceId: value.sourceId,
+        pluginName: value.pluginName,
+        binding,
+        values: value.values,
+    };
+}
+export class PluginConfigResetError extends Error {
+    code;
+    osCode;
+    constructor(code, message, osCode) {
+        super(`${code}: ${message}`);
+        this.name = 'PluginConfigResetError';
+        this.code = code;
+        this.osCode = osCode;
     }
-    markActiveMarketplaceDurableCommit();
 }
 export class PluginConfigSchemaResolutionError extends Error {
     code;
@@ -40,16 +93,12 @@ const CONFIG_DIR = 'plugin-config';
 const CONFIG_FILE = 'config.json';
 let atomicConfigBeforeRenameHookForTests;
 let atomicConfigAfterRenameHookForTests;
-let configFileLockBeforeReleaseHookForTests;
 export function setAtomicConfigBeforeRenameHookForTests(hook) {
     atomicConfigBeforeRenameHookForTests = hook;
 }
 export function setAtomicConfigAfterRenameHookForTests(hook) {
     atomicConfigAfterRenameHookForTests = hook;
 }
-export function setConfigFileLockBeforeReleaseHookForTests(hook) {
-    configFileLockBeforeReleaseHookForTests = hook;
-}
 function assertConfigPathBoundary(allowedRoot, candidatePath) {
     const root = path.resolve(allowedRoot);
     const candidate = path.resolve(candidatePath);
@@ -113,179 +162,40 @@ async function inspectConfigInventoryStoreRoot(boundaryRoot, storeRoot) {
     }
     return true;
 }
-async function readConfigDirectoryIdentity(directoryPath) {
-    const stats = await fs.lstat(directoryPath);
-    if (stats.isSymbolicLink() || !stats.isDirectory()) {
-        throw new Error(`Config parent must be a real directory: ${directoryPath}`);
-    }
-    return {
-        dev: stats.dev,
-        ino: stats.ino,
-        realPath: await fs.realpath(directoryPath),
-    };
-}
-function assertConfigDirectoryStable(label, before, after) {
-    if (before.dev !== after.dev || before.ino !== after.ino || before.realPath !== after.realPath) {
-        throw new Error(`${label} identity changed before atomic config replacement.`);
-    }
-}
-function assertRealConfigBoundary(root, parent) {
-    const relative = path.relative(root.realPath, parent.realPath);
-    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-        throw new Error('Config parent realpath escapes its allowed root.');
-    }
-}
 async function prepareConfigFileParent(filePath, allowedRoot) {
     assertConfigPathBoundary(allowedRoot, filePath);
     await assertNoConfigSymlink(allowedRoot, filePath);
     await fs.ensureDir(path.dirname(filePath));
     await assertNoConfigSymlink(allowedRoot, filePath);
 }
-export function resolveConfigFileLockPath(filePath) {
-    return path.join(path.dirname(filePath), `.${path.basename(filePath)}.aw.lock`);
-}
-async function releaseConfigFileLock(lease) {
-    let lastError;
-    for (let attempt = 1; attempt <= 3; attempt += 1) {
-        try {
-            await configFileLockBeforeReleaseHookForTests?.(lease.lockPath, attempt);
-            await lease.release();
-            return null;
-        }
-        catch (error) {
-            lastError = error;
-            if (attempt < 3) {
-                await new Promise((resolve) => setTimeout(resolve, 10));
-            }
-        }
-    }
-    try {
-        await lease.release();
-    }
-    catch {
-        // Preserve the first release diagnostic. A final direct retry avoids a hook-created self-lock.
-    }
-    return lastError;
-}
-function emitConfigReleaseWarning(message) {
-    try {
-        process.emitWarning(message, { code: 'AW_CONFIG_LOCK_RELEASE_FAILED' });
-    }
-    catch {
-        // Diagnostics cannot replace the primary action result or error.
-    }
-}
-export async function withConfigFileLock(options) {
+export async function withConfigFileMutation(options) {
     await prepareConfigFileParent(options.filePath, options.allowedRoot);
-    const lockPath = resolveConfigFileLockPath(options.filePath);
-    await assertNoConfigSymlink(options.allowedRoot, lockPath);
-    const lease = await acquireProcessLock({ lockPath });
-    let result;
-    let actionError;
-    let actionSucceeded = false;
-    const commitContext = {
-        parent: configCommitStorage.getStore(),
-        durableCommit: false,
-    };
-    try {
-        await assertNoConfigSymlink(options.allowedRoot, options.filePath);
-        result = await configCommitStorage.run(commitContext, options.action);
-        actionSucceeded = true;
-    }
-    catch (error) {
-        actionError = error;
-    }
-    const releaseError = await releaseConfigFileLock(lease);
-    if (!actionSucceeded) {
-        if (releaseError) {
-            emitConfigReleaseWarning('Config action failed, and its process lock release also failed.');
-        }
-        throw actionError;
-    }
-    if (releaseError) {
-        if (commitContext.durableCommit) {
-            emitConfigReleaseWarning('Config action completed successfully, but its process lock could not be released after 3 attempts. The committed result remains successful; the lock can require process exit or manual recovery before another update.');
-        }
-        else {
-            throw releaseError;
-        }
-    }
-    return result;
+    await assertNoConfigSymlink(options.allowedRoot, options.filePath);
+    return options.action();
 }
-export async function withPluginConfigTransactionLease(options) {
-    const storePath = resolvePluginConfigStorePath({
+export async function atomicReplaceConfigFile(options) {
+    await atomicReplaceSafeFile({
         ...options,
-        ...(options.scope === 'project' ? { access: 'write' } : {}),
-    });
-    const allowedRoot = resolvePluginConfigAllowedRoot(options);
-    return withConfigFileLock({
-        filePath: `${storePath}.transaction`,
-        allowedRoot,
-        action: options.action,
+        label: 'Config path',
+        temporaryTag: 'tmp',
+        beforeRename: atomicConfigBeforeRenameHookForTests,
+        afterRename: async (targetPath) => {
+            await atomicConfigAfterRenameHookForTests?.(targetPath).catch(() => undefined);
+        },
     });
 }
-export async function atomicReplaceConfigFile(options) {
-    await prepareConfigFileParent(options.filePath, options.allowedRoot);
-    const rootPath = path.resolve(options.allowedRoot);
-    const parentPath = path.dirname(path.resolve(options.filePath));
-    const rootIdentity = await readConfigDirectoryIdentity(rootPath);
-    const parentIdentity = await readConfigDirectoryIdentity(parentPath);
-    assertRealConfigBoundary(rootIdentity, parentIdentity);
-    const currentTarget = await lstatIfExists(options.filePath);
-    if (currentTarget && (!currentTarget.isFile() || currentTarget.isSymbolicLink())) {
-        throw new Error(`Config target must be a regular file: ${options.filePath}`);
-    }
-    const temporaryPath = path.join(parentPath, `.${path.basename(options.filePath)}.tmp-${process.pid}-${crypto.randomUUID()}`);
-    assertConfigPathBoundary(options.allowedRoot, temporaryPath);
-    let handle;
-    try {
-        handle = await nodeFs.open(temporaryPath, 'wx', options.mode ?? (currentTarget ? currentTarget.mode & 0o777 : 0o600));
-        await handle.writeFile(options.content, 'utf8');
-        await handle.sync();
-        await handle.close();
-        handle = undefined;
-        await atomicConfigBeforeRenameHookForTests?.(options.filePath, temporaryPath);
-        await assertNoConfigSymlink(options.allowedRoot, options.filePath);
-        const currentRootIdentity = await readConfigDirectoryIdentity(rootPath);
-        const currentParentIdentity = await readConfigDirectoryIdentity(parentPath);
-        assertRealConfigBoundary(currentRootIdentity, currentParentIdentity);
-        assertConfigDirectoryStable('Config allowed root', rootIdentity, currentRootIdentity);
-        assertConfigDirectoryStable('Config parent', parentIdentity, currentParentIdentity);
-        const targetBeforeRename = await lstatIfExists(options.filePath);
-        if (targetBeforeRename && (!targetBeforeRename.isFile() || targetBeforeRename.isSymbolicLink())) {
-            throw new Error(`Config target must be a regular file: ${options.filePath}`);
-        }
-        await nodeFs.rename(temporaryPath, options.filePath);
-        markConfigDurableCommit();
-        // rename is the commit point. Diagnostics and durability work after it are best effort,
-        // because reporting failure here would leave the new generation on disk without giving
-        // the caller a safe way to restore the old generation.
-        await atomicConfigAfterRenameHookForTests?.(options.filePath).catch(() => undefined);
-        await (async () => {
-            const finalTarget = await fs.lstat(options.filePath);
-            if (!finalTarget.isFile() || finalTarget.isSymbolicLink()) {
-                throw new Error('Atomic config replacement produced an invalid target.');
-            }
-            if (await fs.readFile(options.filePath, 'utf8') !== options.content) {
-                throw new Error('Atomic config replacement content differs from the committed content.');
-            }
-        })().catch(() => undefined);
-        const directoryHandle = await nodeFs.open(parentPath, 'r').catch(() => null);
-        await directoryHandle?.sync().catch(() => undefined);
-        await directoryHandle?.close().catch(() => undefined);
-    }
-    finally {
-        await handle?.close().catch(() => undefined);
-        await nodeFs.rm(temporaryPath, { force: true }).catch(() => undefined);
-    }
-}
 export async function atomicRemoveConfigFile(options) {
     await prepareConfigFileParent(options.filePath, options.allowedRoot);
-    const rootPath = path.resolve(options.allowedRoot);
-    const parentPath = path.dirname(path.resolve(options.filePath));
-    const rootIdentity = await readConfigDirectoryIdentity(rootPath);
-    const parentIdentity = await readConfigDirectoryIdentity(parentPath);
-    assertRealConfigBoundary(rootIdentity, parentIdentity);
+    await assertSafeFileMutationPath({
+        filePath: options.filePath,
+        allowedRoot: options.allowedRoot,
+        label: 'Config path',
+    });
+    await assertRealFileParentWithinRoot({
+        filePath: options.filePath,
+        allowedRoot: options.allowedRoot,
+        label: 'Config path',
+    });
     const currentTarget = await lstatIfExists(options.filePath);
     if (!currentTarget)
         return false;
@@ -293,12 +203,16 @@ export async function atomicRemoveConfigFile(options) {
         throw new Error(`Config target must be a regular file: ${options.filePath}`);
     }
     await atomicConfigBeforeRenameHookForTests?.(options.filePath, options.filePath);
-    await assertNoConfigSymlink(options.allowedRoot, options.filePath);
-    const currentRootIdentity = await readConfigDirectoryIdentity(rootPath);
-    const currentParentIdentity = await readConfigDirectoryIdentity(parentPath);
-    assertRealConfigBoundary(currentRootIdentity, currentParentIdentity);
-    assertConfigDirectoryStable('Config allowed root', rootIdentity, currentRootIdentity);
-    assertConfigDirectoryStable('Config parent', parentIdentity, currentParentIdentity);
+    await assertSafeFileMutationPath({
+        filePath: options.filePath,
+        allowedRoot: options.allowedRoot,
+        label: 'Config path',
+    });
+    await assertRealFileParentWithinRoot({
+        filePath: options.filePath,
+        allowedRoot: options.allowedRoot,
+        label: 'Config path',
+    });
     const targetBeforeRemove = await lstatIfExists(options.filePath);
     if (!targetBeforeRemove)
         return false;
@@ -306,18 +220,22 @@ export async function atomicRemoveConfigFile(options) {
         throw new Error(`Config target must be a regular file: ${options.filePath}`);
     }
     await nodeFs.unlink(options.filePath);
-    markConfigDurableCommit();
     await atomicConfigAfterRenameHookForTests?.(options.filePath).catch(() => undefined);
-    const directoryHandle = await nodeFs.open(parentPath, 'r').catch(() => null);
-    await directoryHandle?.sync().catch(() => undefined);
-    await directoryHandle?.close().catch(() => undefined);
     return true;
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function formatValue(value) {
-    return typeof value === 'string' ? value : JSON.stringify(value);
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return stablePluginConfigStringify(value);
+    }
+    if (isRecord(value) || Array.isArray(value)) {
+        return stablePluginConfigStringify(value);
+    }
+    return JSON.stringify(value);
 }
 async function calculateConfigManifestDigest(filePath) {
     const hash = crypto.createHash('sha256');
@@ -341,7 +259,7 @@ function createConfigSchemaEvidenceFromCurrentCatalog(plugin, manifestDigest) {
     };
 }
 function getStoreEntries(values) {
-    return { ...values };
+    return Object.fromEntries(Object.entries(values));
 }
 export function assertSafePluginConfigSegment(pluginName) {
     if (typeof pluginName !== 'string' || pluginName.trim() === '') {
@@ -375,22 +293,15 @@ export function resolvePluginConfigStorePath(options) {
     const root = options.scope === 'user'
         ? resolveAwHome(options.env)
         : path.join(resolveAwProjectRoot(options.cwd), '.agent-workflows');
-    const configDir = options.scope === 'project' && options.projectLayer === 'local'
-        ? 'plugin-config.local'
-        : CONFIG_DIR;
-    const filePath = path.join(root, configDir, ...(sourceId ? [sourceId] : []), pluginName, CONFIG_FILE);
+    const filePath = path.join(root, CONFIG_DIR, ...(sourceId ? [sourceId] : []), pluginName, CONFIG_FILE);
     if (options.scope !== 'project') {
         return filePath;
     }
     if (options.access === 'read') {
-        return assertTestReadablePath(filePath, options.projectLayer === 'local'
-            ? 'project local plugin config store (.agent-workflows/plugin-config.local)'
-            : 'project shared plugin config store (.agent-workflows/plugin-config)', '用 registerReadonlyFixtureRoot() 或 runWithRepositoryCwdAsReadOnly() 登记只读 project fixture 根；需要写入时改用 withSafeTestCwd() 或 registerWritableStateRoot()。');
+        return assertTestReadablePath(filePath, 'project plugin config store (.agent-workflows/plugin-config)', '用 registerReadonlyFixtureRoot() 或 runWithRepositoryCwdAsReadOnly() 登记只读 project fixture 根；需要写入时改用 withSafeTestCwd() 或 registerWritableStateRoot()。');
     }
     if (options.access === 'write') {
-        return assertTestWritablePath(filePath, options.projectLayer === 'local'
-            ? 'project local plugin config store (.agent-workflows/plugin-config.local)'
-            : 'project shared plugin config store (.agent-workflows/plugin-config)', '用 withSafeTestCwd() 切到测试可写 cwd，或通过 registerWritableStateRoot() 登记 project fixture 根。');
+        return assertTestWritablePath(filePath, 'project plugin config store (.agent-workflows/plugin-config)', '用 withSafeTestCwd() 切到测试可写 cwd，或通过 registerWritableStateRoot() 登记 project fixture 根。');
     }
     return filePath;
 }
@@ -401,56 +312,167 @@ export function resolvePluginConfigStoreTargets(options) {
                 path: resolvePluginConfigStorePath(options),
             }];
     }
-    return [
-        {
-            storeKind: 'projectShared',
-            path: resolvePluginConfigStorePath({
-                ...options,
-                projectLayer: 'shared',
-            }),
-            projectLayer: 'shared',
-        },
-        {
-            storeKind: 'projectLocal',
-            path: resolvePluginConfigStorePath({
-                ...options,
-                projectLayer: 'local',
-            }),
-            projectLayer: 'local',
-        },
-    ];
+    return [{
+            storeKind: 'project',
+            path: resolvePluginConfigStorePath(options),
+        }];
 }
-async function readStoreFile(filePath) {
-    const value = await fs.readJson(filePath);
-    if (!isRecord(value)) {
-        throw new Error(`Invalid plugin config store "${filePath}": expected a JSON object.`);
+function isPluginConfigScalar(value) {
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isPluginConfigObject(value) {
+    if (!isRecord(value))
+        return false;
+    return Object.values(value).every((property) => {
+        if (isPluginConfigScalar(property))
+            return true;
+        if (Array.isArray(property)) {
+            const elementType = typeof property[0];
+            return Object.keys(property).length === property.length
+                && property.every((item, index) => Object.hasOwn(property, index)
+                    && typeof item === elementType
+                    && isPluginConfigScalar(item));
+        }
+        return isRecord(property) && Object.values(property).every(isPluginConfigScalar);
+    });
+}
+function isPluginConfigValue(value) {
+    if (isPluginConfigScalar(value))
+        return true;
+    if (Array.isArray(value)) {
+        if (Object.keys(value).length !== value.length)
+            return false;
+        const first = value[0];
+        const elementType = isRecord(first) ? 'object' : typeof first;
+        return value.every((item, index) => Object.hasOwn(value, index)
+            && (isRecord(item) ? 'object' : typeof item) === elementType
+            && (isPluginConfigScalar(item) || isPluginConfigObject(item)));
     }
-    return value;
+    return isPluginConfigObject(value);
 }
-async function readNamespacedStoreFile(options) {
-    const raw = await fs.readJson(options.filePath);
-    if (!isRecord(raw) || raw.schemaVersion !== 2 || !isRecord(raw.values)) {
-        throw new Error(`legacyStateUnsupported: invalid or legacy plugin config store "${options.filePath}".`);
+function invalidStore(filePath, code, message, rawDigest) {
+    return {
+        path: filePath,
+        exists: true,
+        state: 'invalid',
+        values: {},
+        ...(rawDigest ? { rawDigest } : {}),
+        invalidCode: code,
+        issues: [message],
+    };
+}
+function readyStore(filePath, values, rawDigest) {
+    return {
+        path: filePath,
+        exists: true,
+        state: 'ready',
+        values: canonicalizePluginConfigValues(values),
+        ...(rawDigest ? { rawDigest } : {}),
+        issues: [],
+    };
+}
+export function assertReadyPluginConfigStore(store) {
+    if (store.state !== 'invalid')
+        return;
+    throw new Error(`${store.invalidCode}: Invalid plugin config store "${store.path}". ${store.issues.join(' ')}`);
+}
+async function parseStoreJson(filePath) {
+    const content = await fs.readFile(filePath);
+    const rawDigest = `sha256:${crypto.createHash('sha256').update(content).digest('hex')}`;
+    try {
+        return {
+            state: 'parsed',
+            value: JSON.parse(content.toString('utf8')),
+            rawDigest,
+        };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return {
+                state: 'invalidJson',
+                store: invalidStore(filePath, 'invalidJson', 'The store is not valid JSON.', rawDigest),
+            };
+        }
+        throw error;
     }
-    if (raw.sourceId !== options.sourceId || raw.pluginName !== options.pluginName) {
-        throw new Error('Plugin config target identity does not match its namespaced path.');
+}
+function validateStoreValues(options) {
+    if (!isRecord(options.values)) {
+        return invalidStore(options.filePath, 'invalidValues', 'The values field must be an object.', options.rawDigest);
     }
-    if (raw.sourceIdentity !== options.sourceIdentity) {
-        throw new Error('sourceChanged: plugin config source identity does not match the configured source.');
+    const values = Object.create(null);
+    const issues = [];
+    for (const [key, value] of Object.entries(options.values)) {
+        if (!isPluginConfigValue(value)) {
+            issues.push(`Config "${key}" is not a supported config value.`);
+            continue;
+        }
+        values[key] = value;
     }
-    return raw.values;
+    return issues.length > 0
+        ? invalidStore(options.filePath, 'invalidValues', issues.join(' '), options.rawDigest)
+        : readyStore(options.filePath, values, options.rawDigest);
+}
+async function readStoreFile(filePath) {
+    const parsed = await parseStoreJson(filePath);
+    if (parsed.state === 'invalidJson')
+        return parsed.store;
+    return validateStoreValues({ filePath, values: parsed.value, rawDigest: parsed.rawDigest });
+}
+async function readNamespacedStoreFile(options) {
+    const parsed = await parseStoreJson(options.filePath);
+    if (parsed.state === 'invalidJson')
+        return parsed.store;
+    const raw = parsed.value;
+    if (!isRecord(raw) || raw.schemaVersion !== 5) {
+        return invalidStore(options.filePath, 'schemaVersionUnsupported', 'Only plugin config store schemaVersion 5 is supported.', parsed.rawDigest);
+    }
+    const envelope = readPluginConfigEnvelopeV5(raw, options.scope);
+    if (!envelope) {
+        return invalidStore(options.filePath, 'schemaVersionUnsupported', 'The plugin config store schemaVersion 5 envelope is invalid.', parsed.rawDigest);
+    }
+    if (envelope.sourceId !== options.sourceId
+        || envelope.pluginName !== options.pluginName) {
+        return invalidStore(options.filePath, 'identityMismatch', 'The store identity does not match its source and namespaced path.', parsed.rawDigest);
+    }
+    const binding = envelope.binding;
+    const matchesBinding = options.scope === 'user'
+        ? binding?.kind === 'source'
+            && typeof options.sourceIdentity === 'string'
+            && binding.sourceIdentity === options.sourceIdentity
+        : binding?.kind === 'catalog'
+            && typeof options.logicalIdentity === 'string'
+            && binding.logicalIdentity === options.logicalIdentity;
+    if (!matchesBinding) {
+        return invalidStore(options.filePath, 'identityMismatch', options.scope === 'user'
+            ? 'The user store is not bound to the requested source identity.'
+            : 'The project store is not bound to the requested Catalog logical identity.', parsed.rawDigest);
+    }
+    return validateStoreValues({
+        filePath: options.filePath,
+        values: envelope.values,
+        rawDigest: parsed.rawDigest,
+    });
 }
 function namespacedConfigContent(options) {
+    const values = canonicalizePluginConfigValues(options.values);
     if (!options.sourceId)
-        return `${JSON.stringify(options.values, null, 2)}\n`;
-    if (!options.sourceIdentity)
-        throw new Error('sourceIdentity is required for namespaced plugin config.');
+        return `${JSON.stringify(values, null, 2)}\n`;
+    const binding = options.scope === 'user'
+        ? options.sourceIdentity
+            ? { kind: 'source', sourceIdentity: options.sourceIdentity }
+            : (() => { throw new Error('sourceChanged: user plugin config requires a source identity.'); })()
+        : options.logicalIdentity
+            ? { kind: 'catalog', logicalIdentity: options.logicalIdentity }
+            : (() => { throw new Error('catalogUnavailable: project plugin config requires verified Catalog logical identity evidence.'); })();
     const envelope = {
-        schemaVersion: 2,
+        schemaVersion: 5,
         sourceId: options.sourceId,
-        sourceIdentity: options.sourceIdentity,
         pluginName: options.pluginName,
-        values: options.values,
+        binding,
+        values,
     };
     return `${JSON.stringify(envelope, null, 2)}\n`;
 }
@@ -462,18 +484,12 @@ async function assertNoLegacyConfigCoexistence(options) {
         scope: options.scope,
         cwd: options.cwd,
         env: options.env,
-        projectLayer: options.projectLayer,
         ...(options.scope === 'project' ? { access: 'read' } : {}),
     });
     if (await lstatIfExists(legacyPath)) {
         throw new Error('legacyStateUnsupported: legacy and namespaced plugin config stores cannot coexist.');
     }
 }
-async function withUserPluginConfigRuntimeLease(options, action) {
-    return options.scope === 'user' || options.sourceId !== undefined
-        ? withActiveMarketplaceRuntimeLease(options.env, action)
-        : action();
-}
 export async function readPluginConfigStore(options) {
     const filePath = resolvePluginConfigStorePath({
         ...options,
@@ -481,14 +497,11 @@ export async function readPluginConfigStore(options) {
     });
     const allowedRoot = resolvePluginConfigAllowedRoot(options);
     if (options.sourceId) {
-        if (!options.sourceIdentity)
-            throw new Error('sourceIdentity is required for namespaced plugin config.');
         const legacyPath = resolvePluginConfigStorePath({
             pluginName: options.pluginName,
             scope: options.scope,
             cwd: options.cwd,
             env: options.env,
-            projectLayer: options.projectLayer,
             ...(options.scope === 'project' ? { access: 'read' } : {}),
         });
         if (await inspectConfigReadTarget(allowedRoot, legacyPath)) {
@@ -499,21 +512,21 @@ export async function readPluginConfigStore(options) {
         return {
             path: filePath,
             exists: false,
+            state: 'missing',
             values: {},
+            issues: [],
         };
     }
-    return {
-        path: filePath,
-        exists: true,
-        values: options.sourceId
-            ? await readNamespacedStoreFile({
-                filePath,
-                sourceId: options.sourceId,
-                sourceIdentity: options.sourceIdentity,
-                pluginName: options.pluginName,
-            })
-            : await readStoreFile(filePath),
-    };
+    return options.sourceId
+        ? readNamespacedStoreFile({
+            filePath,
+            sourceId: options.sourceId,
+            scope: options.scope,
+            sourceIdentity: options.sourceIdentity,
+            logicalIdentity: options.logicalIdentity,
+            pluginName: options.pluginName,
+        })
+        : readStoreFile(filePath);
 }
 export async function readNamespacedPluginConfigStoreIdentity(options) {
     const filePath = resolvePluginConfigStorePath({
@@ -522,15 +535,21 @@ export async function readNamespacedPluginConfigStoreIdentity(options) {
     });
     if (!await inspectConfigReadTarget(resolvePluginConfigAllowedRoot(options), filePath))
         return null;
-    const raw = await fs.readJson(filePath);
-    if (!isRecord(raw) || raw.schemaVersion !== 2 || !isRecord(raw.values)
-        || raw.sourceId !== options.sourceId || raw.pluginName !== options.pluginName
-        || typeof raw.sourceIdentity !== 'string') {
-        throw new Error('legacyStateUnsupported: invalid namespaced plugin config store.');
-    }
+    const parsed = await parseStoreJson(filePath);
+    if (parsed.state === 'invalidJson') {
+        throw new Error(`${parsed.store.invalidCode}: invalid namespaced plugin config store.`);
+    }
+    const envelope = readPluginConfigEnvelopeV5(parsed.value, options.scope);
+    if (!envelope
+        || envelope.sourceId !== options.sourceId
+        || envelope.pluginName !== options.pluginName) {
+        throw new Error('schemaVersionUnsupported: invalid namespaced plugin config store.');
+    }
+    const store = validateStoreValues({ filePath, values: envelope.values });
+    assertReadyPluginConfigStore(store);
     return {
-        sourceIdentity: raw.sourceIdentity,
-        store: { path: filePath, exists: true, values: raw.values },
+        binding: envelope.binding,
+        store,
     };
 }
 async function listConfigStoreDirectoryPluginNames(storeRoot) {
@@ -561,15 +580,72 @@ export async function listPluginConfigStorePluginNames(options) {
     const storeRoots = options.scope === 'user'
         ? [path.join(resolveAwHome(options.env), CONFIG_DIR)]
         : options.scope === 'project'
-            ? [path.join(projectRoot, '.agent-workflows', options.projectLayer === 'local' ? 'plugin-config.local' : CONFIG_DIR)]
+            ? [path.join(projectRoot, '.agent-workflows', CONFIG_DIR)]
             : [
                 path.join(resolveAwHome(options.env), CONFIG_DIR),
                 path.join(projectRoot, '.agent-workflows', CONFIG_DIR),
-                path.join(projectRoot, '.agent-workflows', 'plugin-config.local'),
             ];
     const pluginNames = (await Promise.all(storeRoots.map((storeRoot) => listConfigStoreDirectoryPluginNames(storeRoot)))).flat();
     return [...new Set(pluginNames)].sort((left, right) => left.localeCompare(right));
 }
+export async function listNamespacedPluginConfigStoreIdentities(options) {
+    const boundaryRoot = options.scope === 'user'
+        ? resolveAwHome(options.env)
+        : resolveAwProjectRoot(options.cwd);
+    if (options.scope === 'user') {
+        await canonicalizePathThroughExistingAncestor(boundaryRoot);
+    }
+    else {
+        await fs.realpath(boundaryRoot);
+    }
+    const storeRoot = path.join(boundaryRoot, ...(options.scope === 'project' ? ['.agent-workflows'] : []), CONFIG_DIR);
+    if (!await inspectConfigInventoryStoreRoot(boundaryRoot, storeRoot))
+        return [];
+    const output = [];
+    for (const sourceEntry of await fs.readdir(storeRoot, { withFileTypes: true })) {
+        if (!sourceEntry.isDirectory() || sourceEntry.isSymbolicLink())
+            continue;
+        let sourceId;
+        try {
+            sourceId = assertSafePluginConfigSegment(sourceEntry.name);
+        }
+        catch {
+            continue;
+        }
+        const sourceRoot = path.join(storeRoot, sourceId);
+        let pluginEntries;
+        try {
+            await assertNoConfigSymlink(boundaryRoot, sourceRoot);
+            pluginEntries = await fs.readdir(sourceRoot, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const pluginEntry of pluginEntries) {
+            if (!pluginEntry.isDirectory() || pluginEntry.isSymbolicLink())
+                continue;
+            let pluginName;
+            try {
+                pluginName = assertSafePluginConfigSegment(pluginEntry.name);
+                await assertNoConfigSymlink(boundaryRoot, path.join(sourceRoot, pluginName));
+            }
+            catch {
+                continue;
+            }
+            let target;
+            try {
+                target = await lstatIfExists(path.join(sourceRoot, pluginName, CONFIG_FILE));
+            }
+            catch {
+                continue;
+            }
+            if (!target)
+                continue;
+            output.push({ sourceId, pluginName, pluginId: `${sourceId}/${pluginName}` });
+        }
+    }
+    return output.sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+}
 export async function listNamespacedPluginConfigStores(options) {
     const boundaryRoot = options.scope === 'user'
         ? resolveAwHome(options.env)
@@ -580,9 +656,7 @@ export async function listNamespacedPluginConfigStores(options) {
     else {
         await fs.realpath(boundaryRoot);
     }
-    const storeRoot = path.join(boundaryRoot, ...(options.scope === 'project' ? ['.agent-workflows'] : []), options.scope === 'project' && options.projectLayer === 'local'
-        ? 'plugin-config.local'
-        : CONFIG_DIR);
+    const storeRoot = path.join(boundaryRoot, ...(options.scope === 'project' ? ['.agent-workflows'] : []), CONFIG_DIR);
     const output = [];
     if (!await inspectConfigInventoryStoreRoot(boundaryRoot, storeRoot))
         return output;
@@ -604,18 +678,24 @@ export async function listNamespacedPluginConfigStores(options) {
             const filePath = path.join(storeRoot, sourceId, pluginName, CONFIG_FILE);
             if (!await inspectConfigReadTarget(storeRoot, filePath))
                 continue;
-            const raw = await fs.readJson(filePath);
-            if (!isRecord(raw) || raw.schemaVersion !== 2 || !isRecord(raw.values)
-                || raw.sourceId !== sourceId || raw.pluginName !== pluginName
-                || typeof raw.sourceIdentity !== 'string') {
-                throw new Error(`legacyStateUnsupported: invalid namespaced plugin config store "${filePath}".`);
+            const parsed = await parseStoreJson(filePath);
+            if (parsed.state === 'invalidJson') {
+                throw new Error(`${parsed.store.invalidCode}: invalid namespaced plugin config store "${filePath}".`);
             }
+            const envelope = readPluginConfigEnvelopeV5(parsed.value, options.scope);
+            if (!envelope
+                || envelope.sourceId !== sourceId
+                || envelope.pluginName !== pluginName) {
+                throw new Error(`schemaVersionUnsupported: invalid namespaced plugin config store "${filePath}".`);
+            }
+            const store = validateStoreValues({ filePath, values: envelope.values });
+            assertReadyPluginConfigStore(store);
             output.push({
                 sourceId,
-                sourceIdentity: raw.sourceIdentity,
+                binding: envelope.binding,
                 pluginName,
                 pluginId: `${sourceId}/${pluginName}`,
-                values: raw.values,
+                values: store.values,
             });
         }
     }
@@ -628,22 +708,50 @@ export async function writePluginConfigStore(options) {
         ...(options.scope === 'project' ? { access: 'write' } : {}),
     });
     const allowedRoot = resolvePluginConfigAllowedRoot(options);
-    await withUserPluginConfigRuntimeLease(options, async () => {
-        await withConfigFileLock({
-            filePath,
-            allowedRoot,
-            action: async () => atomicReplaceConfigFile({
+    const validated = validateStoreValues({ filePath, values: options.values });
+    assertReadyPluginConfigStore(validated);
+    const warnings = [];
+    await withConfigFileMutation({
+        filePath,
+        allowedRoot,
+        action: async () => {
+            if (!options.sourceId && Object.keys(validated.values).length === 0) {
+                return atomicRemoveConfigFile({ filePath, allowedRoot });
+            }
+            if (options.sourceId && await lstatIfExists(filePath)) {
+                const current = await readNamespacedStoreFile({
+                    filePath,
+                    sourceId: options.sourceId,
+                    scope: options.scope,
+                    sourceIdentity: options.sourceIdentity,
+                    logicalIdentity: options.logicalIdentity,
+                    pluginName: options.pluginName,
+                });
+                assertReadyPluginConfigStore(current);
+            }
+            if (options.scope === 'project') {
+                const visibility = await assertProjectSharedConfigPathVisible({
+                    cwd: options.cwd,
+                    targetPath: filePath,
+                    env: options.env,
+                });
+                if (visibility?.state === 'unverified') {
+                    warnings.push(PROJECT_CONFIG_SHAREABILITY_UNVERIFIED_WARNING);
+                }
+            }
+            return atomicReplaceConfigFile({
                 filePath,
                 allowedRoot,
-                content: namespacedConfigContent(options),
+                content: namespacedConfigContent({ ...options, values: validated.values }),
                 mode: 0o600,
-            }),
-        });
+            });
+        },
     });
     return {
         pluginName: options.pluginName,
         scope: options.scope,
         path: filePath,
+        warnings,
     };
 }
 export async function patchPluginConfigStore(options) {
@@ -654,33 +762,50 @@ export async function patchPluginConfigStore(options) {
     });
     const allowedRoot = resolvePluginConfigAllowedRoot(options);
     const removedKeys = options.removeKeys ?? [];
-    await withUserPluginConfigRuntimeLease(options, async () => {
-        await withConfigFileLock({
-            filePath,
-            allowedRoot,
-            action: async () => {
-                await options.reviewPreflight?.();
-                const current = (await lstatIfExists(filePath))
-                    ? options.sourceId
-                        ? await readNamespacedStoreFile({
-                            filePath,
-                            sourceId: options.sourceId,
-                            sourceIdentity: options.sourceIdentity,
-                            pluginName: options.pluginName,
-                        })
-                        : await readStoreFile(filePath)
-                    : {};
-                if (options.requireExistingRemoveKeys) {
-                    const missingKey = removedKeys.find((key) => !Object.hasOwn(current, key));
-                    if (missingKey)
-                        throw new Error(`Unknown config key "${missingKey}".`);
-                }
-                const next = { ...current };
-                for (const key of removedKeys) {
-                    delete next[key];
-                }
-                for (const [key, value] of Object.entries(options.updates)) {
-                    next[key] = value;
+    const warnings = [];
+    await withConfigFileMutation({
+        filePath,
+        allowedRoot,
+        action: async () => {
+            await options.reviewPreflight?.();
+            const current = (await lstatIfExists(filePath))
+                ? options.sourceId
+                    ? await readNamespacedStoreFile({
+                        filePath,
+                        sourceId: options.sourceId,
+                        scope: options.scope,
+                        sourceIdentity: options.sourceIdentity,
+                        logicalIdentity: options.logicalIdentity,
+                        pluginName: options.pluginName,
+                    })
+                    : await readStoreFile(filePath)
+                : readyStore(filePath, {});
+            assertReadyPluginConfigStore(current);
+            if (options.requireExistingRemoveKeys) {
+                const missingKey = removedKeys.find((key) => !Object.hasOwn(current.values, key));
+                if (missingKey)
+                    throw new Error(`Unknown config key "${missingKey}".`);
+            }
+            const next = { ...current.values };
+            for (const key of removedKeys) {
+                delete next[key];
+            }
+            for (const [key, value] of Object.entries(options.updates)) {
+                next[key] = value;
+            }
+            if (Object.keys(next).length === 0) {
+                await atomicRemoveConfigFile({ filePath, allowedRoot });
+            }
+            else {
+                if (options.scope === 'project') {
+                    const visibility = await assertProjectSharedConfigPathVisible({
+                        cwd: options.cwd,
+                        targetPath: filePath,
+                        env: options.env,
+                    });
+                    if (visibility?.state === 'unverified') {
+                        warnings.push(PROJECT_CONFIG_SHAREABILITY_UNVERIFIED_WARNING);
+                    }
                 }
                 await atomicReplaceConfigFile({
                     filePath,
@@ -688,65 +813,170 @@ export async function patchPluginConfigStore(options) {
                     content: namespacedConfigContent({ ...options, values: next }),
                     mode: 0o600,
                 });
-            },
-        });
+            }
+        },
     });
     return {
         pluginName: options.pluginName,
         scope: options.scope,
         path: filePath,
+        warnings,
         updatedKeys: Object.keys(options.updates),
         removedKeys,
     };
 }
 export async function resetPluginConfigStore(options) {
-    await assertNoLegacyConfigCoexistence(options);
     const filePath = resolvePluginConfigStorePath({
         ...options,
         ...(options.scope === 'project' ? { access: 'write' } : {}),
     });
     const allowedRoot = resolvePluginConfigAllowedRoot(options);
-    const existed = await withUserPluginConfigRuntimeLease(options, async () => {
-        return withConfigFileLock({
-            filePath,
-            allowedRoot,
-            action: async () => {
-                await options.reviewPreflight?.();
-                const target = await lstatIfExists(filePath);
-                if (!target)
-                    return false;
-                if (!target.isFile() || target.isSymbolicLink()) {
-                    throw new Error(`Config target must be a regular file: ${filePath}`);
-                }
-                if (options.sourceId) {
-                    if (!options.sourceIdentity) {
-                        throw new Error('sourceIdentity is required for namespaced plugin config.');
-                    }
-                    await readNamespacedStoreFile({
-                        filePath,
-                        sourceId: options.sourceId,
-                        sourceIdentity: options.sourceIdentity,
-                        pluginName: options.pluginName,
-                    });
-                }
-                else {
-                    await readStoreFile(filePath);
-                }
-                return atomicRemoveConfigFile({ filePath, allowedRoot });
-            },
-        });
+    const publicTarget = `${options.scope}/plugin-config/${[
+        options.sourceId,
+        options.pluginName,
+        CONFIG_FILE,
+    ].filter(Boolean).join('/')}`;
+    const { root, candidate } = assertConfigPathBoundary(allowedRoot, filePath);
+    let current = root;
+    try {
+        for (const segment of path.relative(root, path.dirname(candidate)).split(path.sep).filter(Boolean)) {
+            const stats = await lstatIfExists(current);
+            if (!stats) {
+                return {
+                    pluginName: options.pluginName,
+                    scope: options.scope,
+                    storeKind: options.scope,
+                    path: filePath,
+                    existed: false,
+                    deleted: false,
+                    resetDisposition: 'absent',
+                };
+            }
+            if (stats.isSymbolicLink() || !stats.isDirectory()) {
+                throw new PluginConfigResetError('configResetTargetUnsupported', `${publicTarget} has an unsafe ancestor. Repair it manually, then retry config reset.`);
+            }
+            current = path.join(current, segment);
+        }
+        const parentStats = await lstatIfExists(current);
+        if (!parentStats) {
+            return {
+                pluginName: options.pluginName,
+                scope: options.scope,
+                storeKind: options.scope,
+                path: filePath,
+                existed: false,
+                deleted: false,
+                resetDisposition: 'absent',
+            };
+        }
+        if (parentStats.isSymbolicLink() || !parentStats.isDirectory()) {
+            throw new PluginConfigResetError('configResetTargetUnsupported', `${publicTarget} has an unsafe ancestor. Repair it manually, then retry config reset.`);
+        }
+        await options.reviewPreflight?.();
+        const target = await lstatIfExists(filePath);
+        if (!target) {
+            return {
+                pluginName: options.pluginName,
+                scope: options.scope,
+                storeKind: options.scope,
+                path: filePath,
+                existed: false,
+                deleted: false,
+                resetDisposition: 'absent',
+            };
+        }
+        if (target.isFile() || target.isSymbolicLink()) {
+            await assertNoConfigSymlink(allowedRoot, path.dirname(filePath));
+            await nodeFs.unlink(filePath);
+            return {
+                pluginName: options.pluginName,
+                scope: options.scope,
+                storeKind: options.scope,
+                path: filePath,
+                existed: true,
+                deleted: true,
+                resetDisposition: target.isSymbolicLink() ? 'unlinkedSymlink' : 'deletedFile',
+            };
+        }
+        if (target.isDirectory()) {
+            const timestamp = new Date().toISOString().replace(/[-:]/gu, '').replace(/\..*$/u, '');
+            const quarantineBasename = `config.broken-${timestamp}-${crypto.randomUUID()}.json`;
+            await assertNoConfigSymlink(allowedRoot, path.dirname(filePath));
+            await nodeFs.rename(filePath, path.join(path.dirname(filePath), quarantineBasename));
+            return {
+                pluginName: options.pluginName,
+                scope: options.scope,
+                storeKind: options.scope,
+                path: filePath,
+                existed: true,
+                deleted: true,
+                resetDisposition: 'quarantinedDirectory',
+                quarantineBasename,
+            };
+        }
+        throw new PluginConfigResetError('configResetTargetUnsupported', `${publicTarget} is a special filesystem node. Move it manually, then retry config reset.`);
+    }
+    catch (error) {
+        if (error instanceof PluginConfigResetError)
+            throw error;
+        const osCode = error.code;
+        throw new PluginConfigResetError('configResetFailed', `Cannot reset ${publicTarget}${osCode ? ` (${osCode})` : ''}. Fix filesystem access, then retry config reset.`, osCode);
+    }
+}
+export async function inspectPluginConfigResetTarget(options) {
+    const filePath = resolvePluginConfigStorePath({
+        ...options,
+        ...(options.scope === 'project' ? { access: 'write' } : {}),
     });
+    const allowedRoot = resolvePluginConfigAllowedRoot(options);
+    const publicTarget = `${options.scope}/plugin-config/${[
+        options.sourceId,
+        options.pluginName,
+        CONFIG_FILE,
+    ].filter(Boolean).join('/')}`;
+    const { root, candidate } = assertConfigPathBoundary(allowedRoot, filePath);
+    let current = root;
+    for (const segment of path.relative(root, path.dirname(candidate)).split(path.sep).filter(Boolean)) {
+        const stats = await lstatIfExists(current);
+        if (!stats)
+            return resetTargetInspection('absent');
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw new PluginConfigResetError('configResetTargetUnsupported', `${publicTarget} has an unsafe ancestor. Repair it manually, then retry config reset.`);
+        }
+        current = path.join(current, segment);
+    }
+    const parentStats = await lstatIfExists(current);
+    if (!parentStats)
+        return resetTargetInspection('absent');
+    if (parentStats.isSymbolicLink() || !parentStats.isDirectory()) {
+        throw new PluginConfigResetError('configResetTargetUnsupported', `${publicTarget} has an unsafe ancestor. Repair it manually, then retry config reset.`);
+    }
+    const target = await lstatIfExists(filePath);
+    if (!target)
+        return resetTargetInspection('absent');
+    const kind = target.isSymbolicLink() ? 'symbolicLink'
+        : target.isFile() ? 'regularFile'
+            : target.isDirectory() ? 'directory'
+                : 'special';
+    return resetTargetInspection(kind, target);
+}
+function resetTargetInspection(kind, stats) {
+    const fingerprint = `sha256:${crypto.createHash('sha256').update(JSON.stringify({
+        kind,
+        ...(stats ? {
+            dev: stats.dev,
+            ino: stats.ino,
+            mode: stats.mode,
+            size: stats.size,
+            mtimeMs: stats.mtimeMs,
+            ctimeMs: stats.ctimeMs,
+        } : {}),
+    })).digest('hex')}`;
     return {
-        pluginName: options.pluginName,
-        scope: options.scope,
-        storeKind: options.scope === 'user'
-            ? 'user'
-            : options.projectLayer === 'local'
-                ? 'projectLocal'
-                : 'projectShared',
-        path: filePath,
-        existed,
-        deleted: existed,
+        exists: kind !== 'absent',
+        kind,
+        resettable: kind !== 'special',
+        fingerprint,
     };
 }
 export async function resetPluginConfigStores(options) {
@@ -757,509 +987,303 @@ export async function resetPluginConfigStores(options) {
     });
     const allowedRoot = resolvePluginConfigAllowedRoot(options);
     const receipts = [];
-    await withUserPluginConfigRuntimeLease(options, async () => {
-        const withTargetLocks = async (index, action) => {
-            const target = targets[index];
-            if (!target)
-                return action();
-            return withConfigFileLock({
-                filePath: target.path,
-                allowedRoot,
-                action: () => withTargetLocks(index + 1, action),
-            });
-        };
-        await withTargetLocks(0, async () => {
-            const existing = [];
-            for (const target of targets) {
-                const stats = await lstatIfExists(target.path);
-                existing.push(stats !== null);
-                if (!stats)
-                    continue;
-                if (!stats.isFile() || stats.isSymbolicLink()) {
-                    throw new Error(`Config target must be a regular file: ${target.path}`);
-                }
-                if (options.sourceId) {
-                    if (!options.sourceIdentity) {
-                        throw new Error('sourceIdentity is required for namespaced plugin config.');
-                    }
-                    await readNamespacedStoreFile({
-                        filePath: target.path,
-                        sourceId: options.sourceId,
-                        sourceIdentity: options.sourceIdentity,
-                        pluginName: options.pluginName,
-                    });
-                }
-                else {
-                    await readStoreFile(target.path);
-                }
-            }
-            for (const [index, target] of targets.entries()) {
-                const deleted = await atomicRemoveConfigFile({
-                    filePath: target.path,
-                    allowedRoot,
-                });
-                receipts.push({
-                    pluginName: options.pluginName,
-                    scope: options.scope,
-                    storeKind: target.storeKind,
-                    path: target.path,
-                    existed: existing[index],
-                    deleted,
-                });
-            }
-        });
-    });
-    return receipts;
-}
-function coercePrimitiveValue(key, field, value) {
-    if (field.type === 'string') {
-        if (typeof value !== 'string') {
-            throw new Error(`Config "${key}" must be a string.`);
-        }
-        return value;
-    }
-    if (field.type === 'number') {
-        const numberValue = typeof value === 'number'
-            ? value
-            : typeof value === 'string' && value.trim() !== ''
-                ? Number(value)
-                : Number.NaN;
-        if (!Number.isFinite(numberValue)) {
-            throw new Error(`Config "${key}" must be a number.`);
-        }
-        if (field.min !== undefined && numberValue < field.min) {
-            throw new Error(`Config "${key}" must be greater than or equal to ${field.min}.`);
-        }
-        if (field.max !== undefined && numberValue > field.max) {
-            throw new Error(`Config "${key}" must be less than or equal to ${field.max}.`);
-        }
-        return numberValue;
-    }
-    if (field.type === 'boolean') {
-        if (typeof value === 'boolean') {
-            return value;
-        }
-        if (typeof value === 'string') {
-            const normalized = value.trim().toLowerCase();
-            if (['true', '1', 'yes', 'y'].includes(normalized)) {
-                return true;
-            }
-            if (['false', '0', 'no', 'n'].includes(normalized)) {
-                return false;
-            }
-        }
-        throw new Error(`Config "${key}" must be a boolean.`);
-    }
-    if (field.type === 'enum') {
-        if (typeof value !== 'string') {
-            throw new Error(`Config "${key}" must be an enum string.`);
-        }
-        if (!field.values?.includes(value)) {
-            throw new Error(`Config "${key}" must be one of: ${(field.values ?? []).join(', ')}.`);
+    const existing = [];
+    for (const target of targets) {
+        await prepareConfigFileParent(target.path, allowedRoot);
+        await assertNoConfigSymlink(allowedRoot, target.path);
+        const stats = await lstatIfExists(target.path);
+        existing.push(stats !== null);
+        if (!stats)
+            continue;
+        if (!stats.isFile() || stats.isSymbolicLink()) {
+            throw new Error(`Config target must be a regular file: ${target.path}`);
         }
-        return value;
     }
-    if (field.type === 'file' || field.type === 'directory') {
-        if (typeof value !== 'string' || value.trim() === '') {
-            throw new Error(`Config "${key}" must be a path string.`);
-        }
-        return value;
+    for (const [index, target] of targets.entries()) {
+        const deleted = await atomicRemoveConfigFile({
+            filePath: target.path,
+            allowedRoot,
+        });
+        receipts.push({
+            pluginName: options.pluginName,
+            scope: options.scope,
+            storeKind: target.storeKind,
+            path: target.path,
+            existed: existing[index],
+            deleted,
+            resetDisposition: deleted ? 'deletedFile' : 'absent',
+        });
     }
-    throw new Error(`Config "${key}" has unsupported type "${field.type}".`);
+    return receipts;
 }
-async function resolvePathConfigValue(options) {
-    if (options.field.type !== 'file' && options.field.type !== 'directory') {
-        return String(options.value);
+function coerceConfigValue(key, field, value) {
+    let coerced = value;
+    if (field.type === 'number' && typeof value === 'string' && value.trim() !== '') {
+        coerced = Number(value);
     }
-    const rawPath = String(options.value);
-    const resolvedPath = path.isAbsolute(rawPath)
-        ? rawPath
-        : path.resolve(options.projectRoot, rawPath);
-    const realPath = await fs.realpath(resolvedPath);
-    const stats = await fs.stat(realPath);
-    if (options.field.type === 'file' && !stats.isFile()) {
-        throw new Error(`Config "${options.key}" must point to an existing file.`);
+    else if (field.type === 'boolean' && typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (['true', '1', 'yes', 'y'].includes(normalized))
+            coerced = true;
+        if (['false', '0', 'no', 'n'].includes(normalized))
+            coerced = false;
     }
-    if (options.field.type === 'directory' && !stats.isDirectory()) {
-        throw new Error(`Config "${options.key}" must point to an existing directory.`);
+    const issues = validateCorePluginConfigValue(field, coerced, key);
+    if (issues.length > 0) {
+        throw new Error(formatPluginConfigIssue(issues[0]));
     }
-    return realPath;
+    return coerced;
 }
 export async function coercePluginConfigValue(options) {
-    const primitive = coercePrimitiveValue(options.key, options.field, options.value);
-    if (options.field.type === 'file' || options.field.type === 'directory') {
-        return resolvePathConfigValue({
-            key: options.key,
-            field: options.field,
-            value: primitive,
-            projectRoot: options.projectRoot,
-        });
+    return coerceConfigValue(options.key, options.field, options.value);
+}
+function validateConfigReadValue(key, field, value) {
+    const issues = validateCorePluginConfigValue(field, value, key);
+    if (issues.length > 0) {
+        throw new Error(formatPluginConfigIssue(issues[0]));
     }
-    return primitive;
+    return value;
 }
 function redactValue(field, value) {
-    return field.sensitive ? '[redacted]' : value;
+    return redactPluginConfigValue(field, value);
 }
-function sourceForStoreLayer(scope, projectLayer = 'shared') {
-    if (scope === 'user') {
-        return 'user';
-    }
-    return projectLayer === 'local' ? 'projectLocal' : 'project';
-}
-function isPathTypeField(field) {
-    return field.type === 'file' || field.type === 'directory';
+function sourceForStoreLayer(scope) {
+    return scope === 'user' ? 'user' : 'project';
 }
 async function applyConfigLayer(options) {
     for (const [key, field] of Object.entries(options.schema)) {
         if (!Object.hasOwn(options.entries, key)) {
             continue;
         }
-        try {
-            const coerced = await coercePluginConfigValue({
-                key,
-                field,
-                value: options.entries[key],
-                projectRoot: options.projectRoot,
-            });
-            options.values[key] = coerced;
-            options.redactedValues[key] = redactValue(field, coerced);
+        const value = options.entries[key];
+        const validationIssues = validateCorePluginConfigValue(field, value, key);
+        if (validationIssues.length === 0) {
+            const redactedValue = redactValue(field, value);
+            options.values[key] = value;
+            options.redactedValues[key] = redactedValue;
             options.sources[key] = options.source;
-            options.invalidIssues.delete(key);
+            options.fieldStates[key] = {
+                effective: { value, redactedValue, source: options.source },
+            };
         }
-        catch (error) {
+        else {
+            const fallback = options.fieldStates[key]?.effective;
             delete options.values[key];
             delete options.redactedValues[key];
             options.sources[key] = options.source;
-            options.invalidIssues.set(key, {
+            const issues = validationIssues.map((issue) => ({
                 type: 'invalid-config',
                 key,
                 source: options.source,
-                message: error instanceof Error ? error.message : String(error),
-            });
+                message: formatPluginConfigIssue(issue),
+            }));
+            options.fieldStates[key] = {
+                invalidOverride: { source: options.source, issues },
+                ...(fallback ? { fallback } : {}),
+            };
         }
     }
 }
 export async function resolveEffectivePluginConfig(options) {
     const pluginName = assertSafePluginConfigSegment(options.pluginName ?? options.manifest.name);
-    const schema = options.manifest.config?.schema;
+    const schema = options.manifest.config?.fields;
     if (!schema) {
         throw new Error(`Plugin "${pluginName}" does not declare an AW config schema.`);
     }
     const projectRoot = resolveAwProjectRoot(options.cwd);
-    const [userStore, projectStore, projectLocalStore] = await Promise.all([
-        readPluginConfigStore({
-            sourceId: options.sourceId,
-            sourceIdentity: options.sourceIdentity,
-            pluginName,
-            scope: 'user',
-            cwd: options.cwd,
-            env: options.env,
-        }),
-        readPluginConfigStore({
-            sourceId: options.sourceId,
-            sourceIdentity: options.sourceIdentity,
-            pluginName,
-            scope: 'project',
-            cwd: options.cwd,
-            env: options.env,
-        }),
-        readPluginConfigStore({
-            sourceId: options.sourceId,
-            sourceIdentity: options.sourceIdentity,
-            pluginName,
-            scope: 'project',
-            cwd: options.cwd,
-            env: options.env,
-            projectLayer: 'local',
-        }),
-    ]);
-    const values = {};
-    const redactedValues = {};
-    const sources = {};
-    const invalidIssues = new Map();
-    const ignoredUnknownKeys = [];
-    const schemaKeys = new Set(Object.keys(schema));
-    for (const key of schemaKeys) {
-        sources[key] = 'missing';
-    }
-    for (const [key, field] of Object.entries(schema)) {
-        if (field.default === undefined) {
-            continue;
-        }
-        await applyConfigLayer({
-            values,
-            redactedValues,
-            sources,
-            invalidIssues,
-            schema: { [key]: field },
-            entries: { [key]: field.default },
-            source: 'default',
-            projectRoot,
-        });
-    }
-    for (const [scope, store, projectLayer] of [
-        ['user', userStore, 'shared'],
-        ['project', projectStore, 'shared'],
-        ['project', projectLocalStore, 'local'],
-    ]) {
-        const plainEntries = getStoreEntries(store.values);
-        for (const key of Object.keys(plainEntries)) {
-            if (!schemaKeys.has(key)) {
-                ignoredUnknownKeys.push({
-                    scope,
-                    projectLayer,
-                    source: sourceForStoreLayer(scope, projectLayer),
-                    key,
-                });
-            }
-        }
-        await applyConfigLayer({
-            values,
-            redactedValues,
-            sources,
-            invalidIssues,
-            schema,
-            entries: plainEntries,
-            source: sourceForStoreLayer(scope, projectLayer),
-            projectRoot,
-        });
-    }
-    const issues = [...invalidIssues.values()];
-    for (const [key, field] of Object.entries(schema)) {
-        if (field.required && values[key] === undefined) {
-            issues.push({
-                type: 'missing-required',
-                key,
-                source: sources[key],
-                message: `Config "${key}" is required.`,
-            });
-        }
-    }
-    return {
+    const userStore = await readPluginConfigStore({
+        sourceId: options.sourceId,
+        sourceIdentity: options.sourceIdentity,
+        logicalIdentity: options.logicalIdentity,
         pluginName,
-        projectRoot,
-        values,
-        redactedValues,
-        sources,
-        issues,
-        ignoredUnknownKeys,
-        schema,
-        stores: {
-            user: userStore,
-            project: projectStore,
-            projectLocal: projectLocalStore,
-        },
-    };
-}
-export async function coercePluginConfigUpdates(options) {
-    const projectRoot = resolveAwProjectRoot(options.cwd);
-    const output = {};
-    for (const [key, value] of Object.entries(options.updates)) {
-        const field = options.schema[key];
-        if (!field) {
-            throw new Error(`Unknown config key "${key}".`);
-        }
-        output[key] = await coercePluginConfigValue({
-            key,
-            field,
-            value,
-            projectRoot,
-        });
-    }
-    return output;
-}
-function createProjectArtifactBoundaryIssue(options) {
-    if (options.reason === 'pathTypeDefault') {
-        return {
-            key: options.key,
-            source: options.source,
-            reason: options.reason,
-            message: `Config "${options.key}" uses file/directory default value, ` +
-                'which cannot participate in repo-visible project artifact truth.',
-        };
-    }
-    if (options.reason === 'pathTypeRequired') {
-        return {
-            key: options.key,
-            source: options.source,
-            reason: options.reason,
-            message: `Config "${options.key}" is a required file/directory key, ` +
-                'which is not portable enough for repo-visible project artifacts.',
-        };
-    }
-    if (options.reason === 'sharedPathValue') {
-        return {
-            key: options.key,
-            source: options.source,
-            reason: options.reason,
-            message: `Config "${options.key}" is stored in project shared config as a file/directory path. ` +
-                'Use user or project local config for machine-local paths.',
-        };
-    }
-    return {
-        key: options.key,
-        source: options.source,
-        reason: options.reason,
-        message: `Config "${options.key}" is declared as a refresh key for repo-visible project artifacts, ` +
-            'but file/directory config is machine-local and cannot drive shared artifact refresh.',
-    };
-}
-export function collectProjectArtifactConfigBoundaryIssues(options) {
-    const issues = [];
-    const refreshKeySet = new Set(options.refreshKeys ?? []);
-    for (const [key, field] of Object.entries(options.schema)) {
-        if (!isPathTypeField(field)) {
-            continue;
-        }
-        if (field.default !== undefined) {
-            issues.push(createProjectArtifactBoundaryIssue({
-                key,
-                source: 'default',
-                reason: 'pathTypeDefault',
-            }));
-        }
-        if (field.required) {
-            issues.push(createProjectArtifactBoundaryIssue({
-                key,
-                source: 'missing',
-                reason: 'pathTypeRequired',
-            }));
-        }
-        if (options.sharedEntries && Object.hasOwn(options.sharedEntries, key)) {
-            issues.push(createProjectArtifactBoundaryIssue({
-                key,
-                source: 'project',
-                reason: 'sharedPathValue',
-            }));
-        }
-        if (refreshKeySet.has(key)) {
-            issues.push(createProjectArtifactBoundaryIssue({
-                key,
-                source: 'project',
-                reason: 'pathTypeRefreshKey',
-            }));
-        }
-    }
-    return issues;
-}
-export async function resolveProjectArtifactRenderConfig(options) {
-    const pluginName = assertSafePluginConfigSegment(options.pluginName ?? options.manifest.name);
-    const schema = options.manifest.config?.schema;
-    const projectRoot = resolveAwProjectRoot(options.cwd);
-    const [userStore, projectStore, projectLocalStore] = await Promise.all([
-        readPluginConfigStore({
-            sourceId: options.sourceId,
-            sourceIdentity: options.sourceIdentity,
-            pluginName,
-            scope: 'user',
-            cwd: options.cwd,
-            env: options.env,
-        }),
-        readPluginConfigStore({
-            sourceId: options.sourceId,
-            sourceIdentity: options.sourceIdentity,
-            pluginName,
-            scope: 'project',
-            cwd: options.cwd,
-            env: options.env,
-        }),
-        readPluginConfigStore({
+        scope: 'user',
+        cwd: options.cwd,
+        env: options.env,
+    });
+    const projectStore = options.targetScope === 'user'
+        ? undefined
+        : await readPluginConfigStore({
             sourceId: options.sourceId,
             sourceIdentity: options.sourceIdentity,
+            logicalIdentity: options.logicalIdentity,
             pluginName,
             scope: 'project',
             cwd: options.cwd,
             env: options.env,
-            projectLayer: 'local',
-        }),
-    ]);
+        });
+    assertReadyPluginConfigStore(userStore);
+    if (projectStore)
+        assertReadyPluginConfigStore(projectStore);
+    return resolveEffectivePluginConfigFromStores({
+        pluginName,
+        manifest: options.manifest,
+        targetScope: options.targetScope,
+        projectRoot,
+        stores: {
+            user: userStore,
+            ...(projectStore ? { project: projectStore } : {}),
+        },
+    });
+}
+export async function resolveEffectivePluginConfigFromStores(options) {
+    const pluginName = assertSafePluginConfigSegment(options.pluginName ?? options.manifest.name);
+    const schema = options.manifest.config?.fields;
     if (!schema) {
-        return {
-            pluginName,
-            projectRoot,
-            values: {},
-            sources: {},
-            issues: [],
-            ignoredUnknownKeys: [],
-            boundaryIssues: [],
-            schema: {},
-            stores: {
-                user: userStore,
-                project: projectStore,
-                projectLocal: projectLocalStore,
-            },
-        };
+        throw new Error(`Plugin "${pluginName}" does not declare an AW config schema.`);
     }
+    const userStore = options.stores.user;
+    const projectStore = options.targetScope === 'user' ? undefined : options.stores.project;
+    assertReadyPluginConfigStore(userStore);
+    if (!projectStore && options.targetScope !== 'user') {
+        throw new Error(`Project plugin config store is required for ${pluginName}.`);
+    }
+    if (projectStore)
+        assertReadyPluginConfigStore(projectStore);
     const values = {};
+    const redactedValues = {};
     const sources = {};
-    const invalidIssues = new Map();
+    const fieldStates = {};
     const ignoredUnknownKeys = [];
+    const unsupportedLayerOverrides = [];
+    const dangerousKeyIssues = [];
     const schemaKeys = new Set(Object.keys(schema));
-    const boundaryIssues = collectProjectArtifactConfigBoundaryIssues({
-        schema,
-        sharedEntries: projectStore.values,
-        refreshKeys: options.refreshKeys,
-    });
-    for (const key of Object.keys(schema)) {
+    const userOnlyKeys = codexNativeRefreshKeys(options.manifest);
+    for (const key of schemaKeys) {
         sources[key] = 'missing';
     }
-    const projectPlainEntries = getStoreEntries(projectStore.values);
-    const userPlainEntries = getStoreEntries(userStore.values);
-    const projectLocalPlainEntries = getStoreEntries(projectLocalStore.values);
-    for (const key of Object.keys(projectPlainEntries)) {
-        if (!schemaKeys.has(key)) {
-            ignoredUnknownKeys.push({ scope: 'project', projectLayer: 'shared', source: 'project', key });
+    for (const [key, field] of Object.entries(schema)) {
+        if (field.default === undefined) {
+            continue;
         }
+        await applyConfigLayer({
+            values,
+            redactedValues,
+            sources,
+            fieldStates,
+            schema: { [key]: field },
+            entries: { [key]: field.default },
+            source: 'default',
+        });
     }
-    for (const key of Object.keys(userPlainEntries)) {
-        if (!schemaKeys.has(key)) {
-            ignoredUnknownKeys.push({ scope: 'user', projectLayer: 'shared', source: 'user', key });
+    const layers = options.targetScope === 'user'
+        ? [['user', userStore]]
+        : [
+            ['user', userStore],
+            ['project', projectStore],
+        ];
+    for (const [scope, store] of layers) {
+        const plainEntries = getStoreEntries(store.values);
+        const source = sourceForStoreLayer(scope);
+        const dangerousIssues = new Map(validatePluginConfigDocument(options.manifest.config, plainEntries).filter((issue) => issue.code === 'dangerousKey')
+            .map((issue) => [issue.path.field, issue]));
+        for (const key of Object.keys(plainEntries)) {
+            if (!schemaKeys.has(key)) {
+                const dangerousIssue = dangerousIssues.get(key);
+                if (dangerousIssue) {
+                    dangerousKeyIssues.push({
+                        type: 'invalid-config',
+                        code: dangerousIssue.code,
+                        key,
+                        source,
+                        message: formatPluginConfigIssue(dangerousIssue),
+                    });
+                }
+                else {
+                    ignoredUnknownKeys.push({ scope, source, key });
+                }
+            }
         }
+        const supportedEntries = scope === 'project'
+            ? Object.fromEntries(Object.entries(plainEntries).filter(([key]) => {
+                if (!schemaKeys.has(key) || !userOnlyKeys.has(key))
+                    return true;
+                unsupportedLayerOverrides.push({
+                    type: 'configLayerUnsupported',
+                    key,
+                    scope: 'project',
+                    source: 'project',
+                });
+                return false;
+            }))
+            : plainEntries;
+        await applyConfigLayer({
+            values,
+            redactedValues,
+            sources,
+            fieldStates,
+            schema,
+            entries: supportedEntries,
+            source,
+        });
     }
-    for (const key of Object.keys(projectLocalPlainEntries)) {
-        if (!schemaKeys.has(key)) {
-            ignoredUnknownKeys.push({ scope: 'project', projectLayer: 'local', source: 'projectLocal', key });
+    const candidateValues = {};
+    for (const [key, field] of Object.entries(schema)) {
+        const source = sources[key];
+        if (source === 'default')
+            candidateValues[key] = field.default;
+        if (source === 'user')
+            candidateValues[key] = ownStoreValue(userStore.values, key);
+        if (source === 'project' && projectStore)
+            candidateValues[key] = ownStoreValue(projectStore.values, key);
+    }
+    const referenceIssues = validatePluginConfigCandidate(options.manifest.config, candidateValues).filter((issue) => issue.code === 'valueRef' || issue.code === 'valueRefSource' || issue.code === 'valueRefReserved');
+    const missingReferenceIssues = [];
+    for (const issue of referenceIssues) {
+        const key = issue.path.field;
+        const source = sources[key];
+        const state = fieldStates[key];
+        const configIssue = {
+            type: 'invalid-config', code: issue.code, key, source,
+            message: formatPluginConfigIssue(issue),
+        };
+        if (source === 'missing') {
+            missingReferenceIssues.push(configIssue);
+            continue;
         }
+        delete values[key];
+        delete redactedValues[key];
+        fieldStates[key] = {
+            invalidOverride: { source, issues: [...(state?.invalidOverride?.issues ?? []), configIssue] },
+            ...(state?.fallback ? { fallback: state.fallback } : {}),
+        };
     }
-    for (const [key, field] of Object.entries(schema)) {
-        if (!isPathTypeField(field) && field.default !== undefined) {
-            await applyConfigLayer({
-                values,
-                redactedValues: {},
-                sources,
-                invalidIssues,
-                schema: { [key]: field },
-                entries: { [key]: field.default },
-                source: 'default',
-                projectRoot,
-            });
+    // Consumers must retain dependency failures after invalid source values are omitted.
+    const invalidKeys = new Set([
+        ...Object.entries(fieldStates).filter(([, state]) => state.invalidOverride !== undefined).map(([key]) => key),
+        ...missingReferenceIssues.map((issue) => issue.key),
+    ]);
+    for (const key of schemaKeys) {
+        if (invalidKeys.has(key))
+            continue;
+        const dependency = getPluginConfigDependencyKeys(options.manifest.config, [key])
+            .find((dependencyKey) => dependencyKey !== key && invalidKeys.has(dependencyKey));
+        if (dependency === undefined)
+            continue;
+        const source = sources[key];
+        const configIssue = {
+            type: 'invalid-config', code: 'valueRefSource', key, source,
+            message: `Config "${key}" depends on invalid config "${dependency}". Fix the dependency before using this field.`,
+        };
+        delete values[key];
+        delete redactedValues[key];
+        if (source === 'missing') {
+            missingReferenceIssues.push(configIssue);
+        }
+        else {
+            const state = fieldStates[key];
+            fieldStates[key] = {
+                invalidOverride: { source, issues: [configIssue] },
+                ...(state?.fallback ? { fallback: state.fallback } : {}),
+            };
         }
     }
-    const sharedSchema = Object.fromEntries(Object.entries(schema).filter(([, field]) => !isPathTypeField(field)));
-    await applyConfigLayer({
-        values,
-        redactedValues: {},
-        sources,
-        invalidIssues,
-        schema: sharedSchema,
-        entries: projectPlainEntries,
-        source: 'project',
-        projectRoot,
-    });
     const issues = [
-        ...invalidIssues.values(),
-        ...boundaryIssues.map((issue) => ({
-            type: 'invalid-config',
-            key: issue.key,
-            source: issue.source,
-            message: issue.message,
-        })),
+        ...Object.values(fieldStates).flatMap((state) => state.invalidOverride?.issues ?? []),
+        ...dangerousKeyIssues,
+        ...missingReferenceIssues,
     ];
     for (const [key, field] of Object.entries(schema)) {
-        if (isPathTypeField(field)) {
-            continue;
-        }
-        if (field.required && values[key] === undefined) {
+        if (field.required && values[key] === undefined && !fieldStates[key]?.invalidOverride) {
             issues.push({
                 type: 'missing-required',
                 key,
@@ -1270,81 +1294,135 @@ export async function resolveProjectArtifactRenderConfig(options) {
     }
     return {
         pluginName,
-        projectRoot,
+        projectRoot: options.projectRoot,
         values,
+        redactedValues,
         sources,
+        fieldStates,
         issues,
+        unsupportedLayerOverrides,
         ignoredUnknownKeys,
-        boundaryIssues,
         schema,
         stores: {
             user: userStore,
-            project: projectStore,
-            projectLocal: projectLocalStore,
+            ...(projectStore ? { project: projectStore } : {}),
         },
     };
 }
-export async function resolveProjectLocalPluginConfigView(options) {
-    const effective = await resolveEffectivePluginConfig(options);
-    const artifactConfig = await resolveProjectArtifactRenderConfig(options);
-    const values = {};
-    const redactedValues = {};
-    const sources = {};
-    const issues = [];
-    for (const [key, field] of Object.entries(effective.schema)) {
-        sources[key] = 'missing';
-        const localPlainEntries = getStoreEntries(effective.stores.projectLocal.values);
-        if (!Object.hasOwn(localPlainEntries, key)) {
-            continue;
-        }
-        sources[key] = 'projectLocal';
-        try {
-            const coerced = await coercePluginConfigValue({
-                key,
-                field,
-                value: localPlainEntries[key],
-                projectRoot: effective.projectRoot,
-            });
-            values[key] = coerced;
-            redactedValues[key] = redactValue(field, coerced);
-        }
-        catch (error) {
-            issues.push({
-                type: 'invalid-config',
-                key,
-                source: 'projectLocal',
-                message: error instanceof Error ? error.message : String(error),
-            });
+function ownStoreValue(values, key) {
+    return Object.hasOwn(values, key) ? values[key] : undefined;
+}
+/** Check cross-field relations before saving one complete layer candidate. */
+export async function assertPluginConfigMutationCandidate(options) {
+    const user = await readPluginConfigStore({ ...options, scope: 'user' });
+    const project = options.scope === 'project'
+        ? await readPluginConfigStore({ ...options, scope: 'project' })
+        : undefined;
+    assertReadyPluginConfigStore(user);
+    if (project)
+        assertReadyPluginConfigStore(project);
+    const edited = options.scope === 'user' ? user : project;
+    const values = { ...edited.values };
+    for (const key of options.removeKeys)
+        delete values[key];
+    for (const [key, value] of Object.entries(options.updates))
+        values[key] = value;
+    const candidateStore = { ...edited, values };
+    const effective = await resolveEffectivePluginConfigFromStores({
+        pluginName: options.pluginName,
+        manifest: options.manifest,
+        targetScope: options.scope,
+        projectRoot: resolveAwProjectRoot(options.cwd),
+        stores: {
+            user: options.scope === 'user' ? candidateStore : user,
+            ...(project ? { project: candidateStore } : {}),
+        },
+    });
+    const issues = effective.issues.filter((issue) => issue.code === 'valueRef'
+        || issue.code === 'valueRefSource' || issue.code === 'valueRefReserved');
+    if (issues.length > 0) {
+        throw Object.assign(new Error(`configReferenceInvalid: ${issues.map((issue) => issue.message).join(' ')}`), {
+            code: 'configReferenceInvalid',
+        });
+    }
+}
+export async function coercePluginConfigUpdates(options) {
+    const output = {};
+    for (const [key, value] of Object.entries(options.updates)) {
+        const field = options.schema[key];
+        if (!field) {
+            throw new Error(`Unknown config key "${key}".`);
         }
+        const coerced = await coercePluginConfigValue({
+            key,
+            field,
+            value,
+        });
+        output[key] = coerced;
+    }
+    return output;
+}
+export async function resolveProjectArtifactRenderConfig(options) {
+    if (!options.manifest.config?.fields) {
+        const pluginName = assertSafePluginConfigSegment(options.pluginName ?? options.manifest.name);
+        const [userStore, projectStore] = await Promise.all([
+            readPluginConfigStore({
+                sourceId: options.sourceId,
+                sourceIdentity: options.sourceIdentity,
+                logicalIdentity: options.logicalIdentity,
+                pluginName,
+                scope: 'user',
+                cwd: options.cwd,
+                env: options.env,
+            }),
+            readPluginConfigStore({
+                sourceId: options.sourceId,
+                sourceIdentity: options.sourceIdentity,
+                logicalIdentity: options.logicalIdentity,
+                pluginName,
+                scope: 'project',
+                cwd: options.cwd,
+                env: options.env,
+            }),
+        ]);
+        assertReadyPluginConfigStore(userStore);
+        assertReadyPluginConfigStore(projectStore);
+        return {
+            pluginName,
+            projectRoot: resolveAwProjectRoot(options.cwd),
+            values: {},
+            sources: {},
+            issues: [],
+            unsupportedLayerOverrides: [],
+            ignoredUnknownKeys: [],
+            schema: {},
+            stores: { user: userStore, project: projectStore },
+        };
     }
+    const effective = await resolveEffectivePluginConfig({
+        ...options,
+        targetScope: 'project',
+    });
     return {
         pluginName: effective.pluginName,
         projectRoot: effective.projectRoot,
+        values: effective.values,
+        sources: effective.sources,
+        issues: effective.issues,
+        unsupportedLayerOverrides: effective.unsupportedLayerOverrides,
+        ignoredUnknownKeys: effective.ignoredUnknownKeys,
         schema: effective.schema,
-        localStore: effective.stores.projectLocal,
-        values,
-        redactedValues,
-        sources,
-        issues,
-        ignoredUnknownKeys: effective.ignoredUnknownKeys.filter((entry) => entry.source === 'projectLocal'),
-        repoVisibleArtifactConfig: {
-            values: artifactConfig.values,
-            sources: artifactConfig.sources,
-            issues: artifactConfig.issues,
-            boundaryIssues: artifactConfig.boundaryIssues,
+        stores: {
+            user: effective.stores.user,
+            project: effective.stores.project,
         },
     };
 }
 async function resolveRedactedLayerValue(options) {
     try {
-        const coerced = await coercePluginConfigValue({
-            key: options.key,
-            field: options.field,
-            value: options.value,
-            projectRoot: options.projectRoot,
-        });
+        const value = validateConfigReadValue(options.key, options.field, options.value);
         return {
-            value: redactValue(options.field, coerced),
+            value: redactValue(options.field, value),
         };
     }
     catch (error) {
@@ -1360,24 +1438,17 @@ async function resolveRedactedLayerValue(options) {
 }
 export async function resolveProjectScopedPluginConfigView(options) {
     const effective = await resolveEffectivePluginConfig(options);
-    const artifactConfig = await resolveProjectArtifactRenderConfig(options);
     const entries = {};
     for (const [key, field] of Object.entries(effective.schema)) {
         const entry = {
             key,
             effectiveValue: effective.redactedValues[key],
             effectiveSource: effective.sources[key] ?? 'missing',
-            repoVisibleArtifactValue: artifactConfig.values[key] === undefined
-                ? undefined
-                : redactValue(field, artifactConfig.values[key]),
-            repoVisibleArtifactSource: artifactConfig.sources[key] ?? 'missing',
-            repoVisibleArtifactUsesSharedTruth: true,
         };
         if (field.default !== undefined) {
             const resolvedDefault = await resolveRedactedLayerValue({
                 key,
                 field,
-                projectRoot: effective.projectRoot,
                 source: 'default',
                 value: field.default,
             });
@@ -1390,7 +1461,6 @@ export async function resolveProjectScopedPluginConfigView(options) {
             const resolvedUser = await resolveRedactedLayerValue({
                 key,
                 field,
-                projectRoot: effective.projectRoot,
                 source: 'user',
                 value: userPlainEntries[key],
             });
@@ -1403,25 +1473,11 @@ export async function resolveProjectScopedPluginConfigView(options) {
             const resolvedProject = await resolveRedactedLayerValue({
                 key,
                 field,
-                projectRoot: effective.projectRoot,
                 source: 'project',
                 value: projectPlainEntries[key],
             });
             if (resolvedProject.value !== undefined) {
-                entry.projectSharedValue = resolvedProject.value;
-            }
-        }
-        const localPlainEntries = getStoreEntries(effective.stores.projectLocal.values);
-        if (Object.hasOwn(localPlainEntries, key)) {
-            const resolvedLocal = await resolveRedactedLayerValue({
-                key,
-                field,
-                projectRoot: effective.projectRoot,
-                source: 'projectLocal',
-                value: localPlainEntries[key],
-            });
-            if (resolvedLocal.value !== undefined) {
-                entry.projectLocalValue = resolvedLocal.value;
+                entry.projectValue = resolvedProject.value;
             }
         }
         entries[key] = entry;
@@ -1430,18 +1486,16 @@ export async function resolveProjectScopedPluginConfigView(options) {
         pluginName: effective.pluginName,
         projectRoot: effective.projectRoot,
         schema: effective.schema,
-        stores: effective.stores,
+        stores: {
+            user: effective.stores.user,
+            project: effective.stores.project,
+        },
         redactedValues: effective.redactedValues,
         sources: effective.sources,
         entries,
         issues: effective.issues,
+        unsupportedLayerOverrides: effective.unsupportedLayerOverrides,
         ignoredUnknownKeys: effective.ignoredUnknownKeys,
-        repoVisibleArtifactConfig: {
-            values: artifactConfig.values,
-            sources: artifactConfig.sources,
-            issues: artifactConfig.issues,
-            boundaryIssues: artifactConfig.boundaryIssues,
-        },
     };
 }
 function toConfigSourceLayer(source) {
@@ -1454,77 +1508,179 @@ function toConfigSourceLayer(source) {
     if (source === 'project') {
         return 'project';
     }
-    if (source === 'projectLocal') {
-        return 'local';
-    }
     return null;
 }
+function configFieldProjection(options) {
+    const source = options.source ?? 'missing';
+    const issues = options.issues ?? [];
+    const presetSensitive = options.field.sensitive === true
+        || (options.field.type === 'object'
+            && (Object.values(options.field.properties ?? {}).some((child) => child.sensitive === true)
+                || (options.field.additionalProperties !== false
+                    && options.field.additionalProperties?.sensitive === true)));
+    return {
+        value: options.value === undefined ? null : redactValue(options.field, options.value),
+        source,
+        matchedPreset: options.value === undefined || presetSensitive
+            ? null
+            : matchPluginConfigPreset(options.field, options.value)?.id ?? null,
+        valid: issues.length === 0,
+        issues,
+    };
+}
 async function buildManifestFieldEntries(options) {
-    const schema = options.plugin.manifest.config?.schema;
+    const schema = options.plugin.manifest.config?.fields;
     if (!schema) {
         return [];
     }
-    const projectRoot = resolveAwProjectRoot(options.cwd);
-    const [userStore, projectStore, projectLocalStore] = await Promise.all([
-        readPluginConfigStore({
-            sourceId: options.plugin.sourceId,
-            sourceIdentity: options.plugin.sourceIdentity,
-            pluginName: options.plugin.manifest.name,
-            scope: 'user',
-            cwd: options.cwd,
-            env: options.env,
-        }),
-        readPluginConfigStore({
-            sourceId: options.plugin.sourceId,
-            sourceIdentity: options.plugin.sourceIdentity,
-            pluginName: options.plugin.manifest.name,
-            scope: 'project',
-            projectLayer: 'shared',
-            cwd: options.cwd,
-            env: options.env,
-        }),
-        readPluginConfigStore({
+    const userStore = await readPluginConfigStore({
+        sourceId: options.plugin.sourceId,
+        sourceIdentity: options.plugin.sourceIdentity,
+        logicalIdentity: options.plugin.catalogLogicalIdentity,
+        pluginName: options.plugin.manifest.name,
+        scope: 'user',
+        cwd: options.cwd,
+        env: options.env,
+        schema,
+    });
+    const projectStore = options.scope === 'user'
+        ? undefined
+        : await readPluginConfigStore({
             sourceId: options.plugin.sourceId,
             sourceIdentity: options.plugin.sourceIdentity,
+            logicalIdentity: options.plugin.catalogLogicalIdentity,
             pluginName: options.plugin.manifest.name,
             scope: 'project',
-            projectLayer: 'local',
             cwd: options.cwd,
             env: options.env,
-        }),
-    ]);
+            schema,
+        });
+    assertReadyPluginConfigStore(userStore);
+    if (projectStore)
+        assertReadyPluginConfigStore(projectStore);
     const userPlainEntries = getStoreEntries(userStore.values);
-    const projectPlainEntries = getStoreEntries(projectStore.values);
-    const localPlainEntries = getStoreEntries(projectLocalStore.values);
+    const projectPlainEntries = projectStore ? getStoreEntries(projectStore.values) : {};
     const effective = await resolveEffectivePluginConfig({
         sourceId: options.plugin.sourceId,
         sourceIdentity: options.plugin.sourceIdentity,
+        logicalIdentity: options.plugin.catalogLogicalIdentity,
         pluginName: options.plugin.manifest.name,
         manifest: options.plugin.manifest,
+        targetScope: options.scope === 'user' ? 'user' : 'project',
         cwd: options.cwd,
         env: options.env,
     });
+    const userOnlyKeys = codexNativeRefreshKeys(options.plugin.manifest);
+    const projectRemovalFallback = (key) => {
+        const field = schema[key];
+        if (Object.hasOwn(userPlainEntries, key)) {
+            const value = userPlainEntries[key];
+            const validationIssues = validateCorePluginConfigValue(field, value, key);
+            if (validationIssues.length > 0) {
+                return {
+                    state: 'invalid',
+                    sourceLayer: 'user',
+                    issues: validationIssues.map((issue) => ({
+                        type: 'invalid-config',
+                        key,
+                        source: 'user',
+                        message: formatPluginConfigIssue(issue),
+                    })),
+                };
+            }
+            return {
+                state: 'valid',
+                effectiveValue: redactValue(field, value),
+                sourceLayer: 'user',
+            };
+        }
+        if (field.default === undefined)
+            return { state: 'missing' };
+        const validationIssues = validateCorePluginConfigValue(field, field.default, key);
+        if (validationIssues.length > 0) {
+            return {
+                state: 'invalid',
+                sourceLayer: 'default',
+                issues: validationIssues.map((issue) => ({
+                    type: 'invalid-config',
+                    key,
+                    source: 'default',
+                    message: formatPluginConfigIssue(issue),
+                })),
+            };
+        }
+        return {
+            state: 'valid',
+            effectiveValue: redactValue(field, field.default),
+            sourceLayer: 'default',
+        };
+    };
+    const effectiveFieldState = (key) => {
+        const source = effective.sources[key];
+        const sourceLayer = toConfigSourceLayer(source);
+        const field = schema[key];
+        const fieldIssues = effective.issues.filter((entry) => entry.key === key);
+        const fieldState = effective.fieldStates[key];
+        const fallback = options.scope === 'project'
+            ? projectRemovalFallback(key)
+            : fieldState?.fallback
+                ? {
+                    state: 'valid',
+                    effectiveValue: fieldState.fallback.redactedValue,
+                    sourceLayer: fieldState.fallback.source,
+                }
+                : undefined;
+        if (source === undefined || source === 'missing') {
+            return {
+                valueState: fieldIssues.length > 0 ? 'invalid' : 'default',
+                effectiveValue: null,
+                sourceLayer: null,
+                ...configFieldProjection({ field, source: 'missing', issues: fieldIssues }),
+            };
+        }
+        const issue = fieldIssues.find((entry) => entry.source === source);
+        return {
+            valueState: issue ? 'invalid' : source === 'default' ? 'default' : 'configured',
+            effectiveValue: issue ? null : effective.redactedValues[key] ?? null,
+            sourceLayer,
+            ...(fieldState?.invalidOverride ? {
+                invalidOverride: {
+                    sourceLayer: fieldState.invalidOverride.source,
+                    issues: fieldState.invalidOverride.issues,
+                },
+            } : {}),
+            ...(fallback ? { fallback } : {}),
+            ...configFieldProjection({
+                field,
+                value: issue ? undefined : effective.values[key],
+                source,
+                issues: fieldIssues,
+            }),
+        };
+    };
     const fields = [];
     for (const [key, field] of Object.entries(schema)) {
+        const canSet = options.scope !== 'project'
+            || (!userOnlyKeys.has(key) && field.sensitive !== true);
         const base = {
             key,
             title: field.title ?? key,
             kind: 'manifest',
             reserved: false,
-            writable: true,
+            writable: canSet,
+            canSet,
+            canUnset: options.scope === 'user'
+                ? Object.hasOwn(userPlainEntries, key)
+                : options.scope === 'project' && Object.hasOwn(projectPlainEntries, key),
             valueState: 'default',
             effectiveValue: null,
             sourceLayer: null,
+            ...configFieldProjection({ field }),
         };
         if (options.scope === 'user') {
             if (Object.hasOwn(userPlainEntries, key)) {
                 try {
-                    const value = await coercePluginConfigValue({
-                        key,
-                        field,
-                        value: userPlainEntries[key],
-                        projectRoot,
-                    });
+                    const value = validateConfigReadValue(key, field, userPlainEntries[key]);
                     fields.push({
                         ...base,
                         valueState: 'configured',
@@ -1532,6 +1688,7 @@ async function buildManifestFieldEntries(options) {
                         sourceLayer: 'user',
                         storedValue: redactValue(field, value),
                         storedSourceLayer: 'user',
+                        ...configFieldProjection({ field, value, source: 'user' }),
                     });
                 }
                 catch {
@@ -1539,22 +1696,22 @@ async function buildManifestFieldEntries(options) {
                         ...base,
                         valueState: 'invalid',
                         sourceLayer: 'user',
+                        source: 'user',
+                        storedSourceLayer: 'user',
+                        valid: false,
+                        issues: [{ type: 'invalid-config', key, source: 'user' }],
                     });
                 }
                 continue;
             }
             if (field.default !== undefined) {
                 try {
-                    const value = await coercePluginConfigValue({
-                        key,
-                        field,
-                        value: field.default,
-                        projectRoot,
-                    });
+                    const value = validateConfigReadValue(key, field, field.default);
                     fields.push({
                         ...base,
                         effectiveValue: redactValue(field, value),
                         sourceLayer: 'default',
+                        ...configFieldProjection({ field, value, source: 'default' }),
                     });
                 }
                 catch {
@@ -1562,6 +1719,9 @@ async function buildManifestFieldEntries(options) {
                         ...base,
                         valueState: 'invalid',
                         sourceLayer: 'default',
+                        source: 'default',
+                        valid: false,
+                        issues: [{ type: 'invalid-config', key, source: 'default' }],
                     });
                 }
                 continue;
@@ -1569,103 +1729,41 @@ async function buildManifestFieldEntries(options) {
             fields.push(base);
             continue;
         }
-        if (options.projectLayer === 'local') {
-            if (Object.hasOwn(localPlainEntries, key)) {
-                try {
-                    const value = await coercePluginConfigValue({
-                        key,
-                        field,
-                        value: localPlainEntries[key],
-                        projectRoot,
-                    });
-                    fields.push({
-                        ...base,
-                        valueState: 'configured',
-                        effectiveValue: redactValue(field, value),
-                        sourceLayer: 'local',
-                        storedValue: redactValue(field, value),
-                        storedSourceLayer: 'local',
-                    });
-                }
-                catch {
-                    fields.push({
-                        ...base,
-                        valueState: 'invalid',
-                        sourceLayer: 'local',
-                    });
-                }
-            }
-            else {
-                fields.push(base);
-            }
-            continue;
-        }
         let storedProjectValue;
         if (options.scope === 'project' && Object.hasOwn(projectPlainEntries, key)) {
             try {
-                const value = await coercePluginConfigValue({
-                    key,
-                    field,
-                    value: projectPlainEntries[key],
-                    projectRoot,
-                });
+                const value = validateConfigReadValue(key, field, projectPlainEntries[key]);
                 storedProjectValue = {
                     storedValue: redactValue(field, value),
                     storedSourceLayer: 'project',
                 };
             }
             catch {
-                storedProjectValue = undefined;
+                storedProjectValue = { storedSourceLayer: 'project' };
             }
         }
-        const source = effective.sources[key];
-        const layer = toConfigSourceLayer(source);
-        if (source === 'default') {
-            fields.push({
-                ...base,
-                effectiveValue: effective.redactedValues[key] ?? null,
-                sourceLayer: 'default',
-                ...storedProjectValue,
-            });
-            continue;
-        }
-        if (source === 'user' || source === 'project' || source === 'projectLocal') {
-            const issue = effective.issues.find((entry) => entry.key === key && entry.source === source);
-            fields.push({
-                ...base,
-                valueState: issue ? 'invalid' : 'configured',
-                effectiveValue: issue ? null : effective.redactedValues[key] ?? null,
-                sourceLayer: layer,
-                ...storedProjectValue,
-            });
-            continue;
-        }
-        fields.push({ ...base, ...storedProjectValue });
+        fields.push({ ...base, ...effectiveFieldState(key), ...storedProjectValue });
     }
     return fields;
 }
 async function buildLegacyStoreFieldEntries(options) {
     const locations = options.scope === 'effective'
         ? [
-            { scope: 'user', projectLayer: 'shared', sourceLayer: 'user' },
-            { scope: 'project', projectLayer: 'shared', sourceLayer: 'project' },
-            { scope: 'project', projectLayer: 'local', sourceLayer: 'local' },
+            { scope: 'user', sourceLayer: 'user' },
+            { scope: 'project', sourceLayer: 'project' },
         ]
         : [{
                 scope: options.scope,
-                projectLayer: options.projectLayer,
-                sourceLayer: options.scope === 'user'
-                    ? 'user'
-                    : options.projectLayer === 'local' ? 'local' : 'project',
+                sourceLayer: options.scope === 'user' ? 'user' : 'project',
             }];
     const fields = new Map();
     for (const location of locations) {
         const store = await readPluginConfigStore({
             sourceId: options.sourceId,
             sourceIdentity: options.sourceIdentity,
+            logicalIdentity: options.logicalIdentity,
             pluginName: options.pluginName,
             scope: location.scope,
-            ...(location.scope === 'project' ? { projectLayer: location.projectLayer } : {}),
             cwd: options.cwd,
             env: options.env,
         });
@@ -1676,9 +1774,16 @@ async function buildLegacyStoreFieldEntries(options) {
                 kind: 'manifest',
                 reserved: false,
                 writable: false,
+                canSet: false,
+                canUnset: false,
                 valueState: 'configured',
                 effectiveValue: '[redacted]',
                 sourceLayer: location.sourceLayer,
+                value: '[redacted]',
+                source: location.sourceLayer,
+                matchedPreset: null,
+                valid: true,
+                issues: [],
             });
         }
     }
@@ -1708,7 +1813,6 @@ export async function resolveConfigRead(options) {
         currentPlugin: options.plugin,
         currentPluginError: options.pluginError,
         scope: options.scope,
-        projectLayer: options.projectLayer,
         cwd: options.cwd,
         env: options.env,
     });
@@ -1716,24 +1820,25 @@ export async function resolveConfigRead(options) {
         ? await buildManifestFieldEntries({
             plugin: schemaAccess.plugin,
             scope: options.scope,
-            projectLayer: options.projectLayer,
             cwd: options.cwd,
             env: options.env,
         })
         : await buildLegacyStoreFieldEntries({
             sourceId: options.sourceId,
             sourceIdentity: options.sourceIdentity,
+            logicalIdentity: options.logicalIdentity,
             pluginName,
             scope: options.scope,
-            projectLayer: options.projectLayer,
             cwd: options.cwd,
             env: options.env,
         });
     return {
         pluginName,
         scope: options.scope,
-        projectLayer: options.projectLayer,
         ...(schemaAccess.schema ? { schema: schemaAccess.schema } : {}),
+        ...(schemaAccess.plugin?.manifest.config?.fields
+            ? { fieldDefinitions: schemaAccess.plugin.manifest.config.fields }
+            : {}),
         fields: manifestFields,
     };
 }
@@ -1747,6 +1852,15 @@ export function summarizeEffectivePluginConfig(config) {
     return {
         values: config.redactedValues,
         sources: config.sources,
+        fieldStates: Object.fromEntries(Object.entries(config.fieldStates).map(([key, state]) => [key, {
+                ...(state.effective ? {
+                    effective: { value: state.effective.redactedValue, source: state.effective.source },
+                } : {}),
+                ...(state.invalidOverride ? { invalidOverride: state.invalidOverride } : {}),
+                ...(state.fallback ? {
+                    fallback: { value: state.fallback.redactedValue, source: state.fallback.source },
+                } : {}),
+            }])),
         issues: config.issues,
         ignoredUnknownKeys: config.ignoredUnknownKeys,
     };
@@ -1762,52 +1876,75 @@ export function createPluginConfigSchemaIdentity(manifest) {
         .digest('hex');
     return `${manifest.name}:${hash}`;
 }
+function cliConfigPromptEnumValues(field) {
+    if (!field.choices)
+        return undefined;
+    const values = field.choices.presets
+        .map((preset) => preset.value);
+    if (field.type !== 'boolean') {
+        return field.choices.allowCustom ? undefined : values;
+    }
+    if (field.choices.allowCustom) {
+        for (const value of [true, false]) {
+            if (!values.includes(value))
+                values.push(value);
+        }
+    }
+    return values;
+}
 export function toCliConfigPromptSchema(schema) {
     const promptSchema = {};
     for (const [key, field] of Object.entries(schema)) {
+        if (field.type === 'object' || field.type === 'array')
+            continue;
         promptSchema[key] = {
-            type: field.type === 'enum' ? 'string' : field.type,
+            type: field.type,
             label: field.title ?? key,
             description: field.description,
             required: field.required,
             sensitive: field.sensitive,
             default: field.default,
-            enum: field.type === 'enum' ? field.values : undefined,
-            min: field.min,
-            max: field.max,
+            enum: cliConfigPromptEnumValues(field),
+            min: field.type === 'number' ? field.validation?.minimum : undefined,
+            max: field.type === 'number' ? field.validation?.maximum : undefined,
         };
     }
     return promptSchema;
 }
 export function createPluginConfigFormModel(options) {
-    const schema = options.manifest.config?.schema;
+    const schema = options.manifest.config?.fields;
     if (!schema) {
         throw new Error(`Plugin "${options.pluginName ?? options.manifest.name}" does not declare an AW config schema.`);
     }
     const requiredKeys = [...new Set(options.effective.issues
             .filter((issue) => issue.type === 'missing-required' || issue.type === 'invalid-config')
             .map((issue) => issue.key))];
+    const fields = Object.entries(schema).flatMap(([key, field]) => {
+        if (field.type === 'object' || field.type === 'array')
+            return [];
+        return [{
+                key,
+                type: field.type,
+                label: field.title ?? key,
+                description: field.description,
+                required: field.required === true,
+                sensitive: field.sensitive === true,
+                defaultValue: field.default,
+                enumValues: cliConfigPromptEnumValues(field),
+                min: field.type === 'number' ? field.validation?.minimum : undefined,
+                max: field.type === 'number' ? field.validation?.maximum : undefined,
+                configured: options.effective.values[key] !== undefined,
+                currentValue: field.sensitive
+                    ? undefined
+                    : options.effective.values[key],
+            }];
+    });
     return {
         pluginName: options.pluginName ?? options.manifest.name,
         allowedScopes: options.allowedScopes ?? ['user', 'project'],
         initialScope: options.initialScope,
         requiredKeys,
-        fields: Object.entries(schema).map(([key, field]) => ({
-            key,
-            type: field.type,
-            label: field.title ?? key,
-            description: field.description,
-            required: field.required === true,
-            sensitive: field.sensitive === true,
-            defaultValue: field.default,
-            enumValues: field.type === 'enum' ? field.values : undefined,
-            min: field.min,
-            max: field.max,
-            configured: options.effective.values[key] !== undefined,
-            currentValue: field.sensitive || isPathTypeField(field)
-                ? undefined
-                : options.effective.values[key],
-        })),
+        fields,
     };
 }
 export function toCliConfigPromptOptions(model) {
@@ -1826,7 +1963,7 @@ export function toCliConfigPromptOptions(model) {
         schema: Object.fromEntries(model.fields.map((field) => [
             field.key,
             {
-                type: field.type === 'enum' ? 'string' : field.type,
+                type: field.type,
                 label: field.label,
                 description: field.description,
                 required: field.required,
@@ -1844,13 +1981,21 @@ export function toCliConfigPromptOptions(model) {
         requiredKeys: [...model.requiredKeys],
     };
 }
-function formatRequiredConfigSetCommands(pluginName, issues, defaultScope) {
+export function formatPluginConfigSetRecoveryCommand(pluginName, key, field, scope) {
+    return field.sensitive === true
+        ? `aw config set ${pluginName} ${key} --scope user --value-stdin`
+        : `aw config set ${pluginName} ${key} --scope ${scope} --value-json '<json>'`;
+}
+function formatRequiredConfigSetCommands(pluginName, issues, defaultScope, schema) {
     const commands = new Set();
     for (const issue of issues) {
         const scope = issue.source === 'user' || issue.source === 'project'
             ? issue.source
             : defaultScope;
-        commands.add(`aw config set ${pluginName} ${issue.key} <value> -s ${scope}`);
+        const field = schema[issue.key];
+        if (!field)
+            continue;
+        commands.add(formatPluginConfigSetRecoveryCommand(pluginName, issue.key, field, scope));
     }
     return [...commands].map((command) => `\`${command}\``).join(' 或 ');
 }
@@ -1870,12 +2015,13 @@ export async function preflightRequiredPluginConfigs(options) {
         }
         visited.add(dedupeKey);
         result.checked += 1;
-        if (!target.manifest.config?.schema) {
+        if (!target.manifest.config?.fields) {
             continue;
         }
         let effective = await resolveEffectivePluginConfig({
             sourceId: target.sourceId,
             sourceIdentity: target.sourceIdentity,
+            logicalIdentity: target.logicalIdentity,
             pluginName,
             manifest: target.manifest,
             cwd: options.cwd,
@@ -1886,7 +2032,7 @@ export async function preflightRequiredPluginConfigs(options) {
             continue;
         }
         const details = blockingIssues.map((issue) => issue.key).join(', ');
-        const setCommands = formatRequiredConfigSetCommands(pluginName, blockingIssues, options.defaultScope);
+        const setCommands = formatRequiredConfigSetCommands(pluginName, blockingIssues, options.defaultScope, target.manifest.config.fields);
         throw new Error(`${pluginName} requires valid AW config before install/upgrade: ${details}. ` +
             `Run ${setCommands}, or open \`aw\` to complete setup.`);
     }