@lesliechan721/aw 0.1.0-beta.3 → 0.1.0-beta.30

package/dist/src/index.js

@@ -3,37 +3,50 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { Command, CommanderError, Option } from 'commander';
+import { Command, CommanderError, InvalidArgumentError, Option } from 'commander';
+import { doctorEvalProviders } from '@lesliechan721/agent-skill-eval';
 import { initCommand } from './commands/init.js';
-import { addCatalogSourceCommand, explicitRefPolicy, listCatalogSources, removeCatalogSourceCommand, setPrimaryCatalogSourceCommand, updateCatalogSourceCommand, } from './commands/catalog-source.js';
-import { cleanupWriteCommand as cleanupCommand, installWriteCommand as installCommand, reinstallWriteCommand as reinstallCommand, uninstallWriteCommand as uninstallCommand, upgradeWriteCommand as upgradeCommand, } from './commands/write-commands.js';
+import { resolveCatalogWorkspaceRoot } from './commands/catalog-workspace-resolution.js';
+import { addCatalogSourceCommand, preflightCatalogSourceMutation, explicitRefPolicy, listCatalogSources, removeCatalogSourceCommand, setPrimaryCatalogSourceCommand, updateCatalogSourceCommand, } from './commands/catalog-source.js';
+import { catalogSourceStatusCommand, syncCatalogSourceCommand, } from './commands/catalog-generation.js';
+import { catalogStoreErrorCode, catalogStorePrune, catalogStoreStatus, } from './commands/catalog-store.js';
+import { cleanupWriteCommand as cleanupCommand, installWriteCommand as installCommand, reinstallWriteCommand as reinstallCommand, uninstallWriteCommand as uninstallCommand, } from './commands/write-commands.js';
+import { syncCommand } from './commands/sync-command.js';
 import { formatInteractiveConsoleUnavailableMessage, runConsoleController, } from './commands/console.js';
 import { runCommandWizard, toWizardCandidates, WizardExecutionError, } from './commands/wizard.js';
 import { createCliExecutionContext, emitCommandEvent, } from './commands/runtime.js';
-import { loadConsoleItemsResult } from './commands/status.js';
-import { statusCommandV4 } from './commands/status-v4.js';
-import { normalizeUninstallCommandOptions, normalizeCleanupCommandOptions, resolveConfigReadResolution, resolveConfigProjectLayer, resolveConfigWriteScope, normalizeInstallCommandOptions, normalizeReinstallCommandOptions, normalizeUpgradeCommandOptions, } from './commands/options.js';
+import { loadConsoleItemsResult, statusCommandV8 } from './commands/status-v6.js';
+import { normalizeUninstallCommandOptions, normalizeCleanupCommandOptions, resolveConfigReadResolution, resolveConfigWriteScope, normalizeInstallCommandOptions, normalizeReinstallCommandOptions, resolveScriptTimeoutMs, } from './commands/options.js';
 import { isCommandWarningError, } from './types.js';
 import { formatWarnings } from './output/reporter.js';
 import { redactString, redactValue } from './output/redact.js';
 import { renderShellCommand, } from './output/equivalent-command.js';
 import { buildRebuildReceiptJson, buildInitReceiptJson, renderRebuildReceipt, renderInitReceipt, } from './output/command-receipt.js';
 import { resolveCliPackageRoot } from './utils/paths.js';
-import { coercePluginConfigUpdates, findConfigFieldEntry, listNamespacedPluginConfigStores, listPluginConfigStorePluginNames, readPluginConfigStore, renderPluginConfigValueForDisplay, resolveConfigRead, } from './utils/plugin-config.js';
-import { applyPluginConfigWrite, describeResetAffectedFields, resetPluginConfigWithHelper, } from './utils/plugin-config-write.js';
+import { findConfigFieldEntry, formatPluginConfigSetRecoveryCommand, listNamespacedPluginConfigStores, listPluginConfigStorePluginNames, readPluginConfigStore, renderPluginConfigValueForDisplay, resolveConfigRead, } from './utils/plugin-config.js';
+import { applyPluginConfigWrite, buildConfigMutationReceipt, configWriteStateForError, describeResetAffectedFields, resetPluginConfigWithHelper, } from './utils/plugin-config-write.js';
 import { assertStrictSemVer } from './utils/manifest.js';
 import { writeCandidateEligibility } from './utils/target-eligibility.js';
 import { assertCatalogSourceReferencesSupported, inventoryLegacyConfigReferences, } from './utils/catalog-source-references.js';
 import { parsePluginId, withResolvedCatalogPlugin, withResolvedMultiSourceCatalog, } from './utils/multi-source-catalog.js';
-import { sanitizeCatalogSourceError } from './utils/catalog-public-error.js';
-import { formatConfigCommandValue, parseConfigValue, } from './utils/config-value.js';
+import { sanitizeCatalogSourceError, sanitizeCatalogSourceErrorMessage, } from './utils/catalog-public-error.js';
+import { catalogGenerationErrorCode } from './utils/catalog-generation-error.js';
+import { resolveCatalogOperationContext, } from './utils/catalog-operation-context.js';
 import { withAwHomeMutationLock, } from './utils/aw-home-mutation-lock.js';
 import { installPortableSkills, materializePortableSkillsToDirectory, PortableCommandError, renderPortableReview, } from './portable/commands.js';
 import { SkillsCliError } from './portable/skills-cli.js';
 import { computeReviewComponentDigest, listReviewRecords, parseReviewAttachment, publishReviewRecord, showReviewRecord, verifyReviewRecord, } from './commands/review-publication.js';
+import { createReviewInspectionFailure, getReviewInspectionExitCode, inspectReviewTarget, } from './commands/review-inspection.js';
+import { prepareReviewTarget, } from './commands/review-preparation.js';
 import { resolveRepoRoot } from './utils/state-paths.js';
 import { runCatalogBuildCommand, runCatalogInitCommand, runCatalogValidateCommand, runCatalogVersionCommand, runPluginBuildCommand, runPluginTestCommand, } from './authoring/workspace-commands.js';
-import { runCatalogPublishCommand } from './commands/catalog-publish.js';
+import { runCatalogPublishApplyCommand, runCatalogPublishPlanCommand, } from './commands/catalog-publish.js';
+import { catalogPublicationFailure, CatalogPublicationInspectionError, } from './commands/catalog-publication-inspection.js';
+import { getCatalogStatus, renderCatalogStatus } from './commands/catalog-status.js';
+import { activateCatalogDevSource, catalogDevSourceError, createCatalogDevFailureReceipt, deactivateCatalogDevSource, getCatalogDevSourceStatus, } from './commands/catalog-dev-source.js';
+import { getPluginCapabilitiesResult, parsePluginCapabilitySurface, renderPluginCapabilities, } from './commands/plugin-capabilities.js';
+import { AwCapabilityUnsupportedError, checkCurrentAw, describeCurrentAw, inspectPluginRequirements, } from './commands/aw-capabilities.js';
+import { prepareSkillEval } from './commands/skill-eval.js';
 function createDefaultIo() {
     return {
         stdout: (text) => process.stdout.write(text),
@@ -43,6 +56,62 @@ function createDefaultIo() {
 function writeLine(write, line) {
     write(`${line}\n`);
 }
+function strictValueOption(flags, description, choices) {
+    let seen = false;
+    const option = new Option(flags, description);
+    return option.argParser((value) => {
+        if (seen)
+            throw new InvalidArgumentError(`${option.long} can be specified only once.`);
+        if (choices && !choices.includes(value)) {
+            throw new InvalidArgumentError(`${option.long} must be one of: ${choices.join(', ')}.`);
+        }
+        seen = true;
+        return value;
+    });
+}
+function collectUniqueOption(value, previous) {
+    return previous.includes(value) ? previous : [...previous, value];
+}
+function renderReviewSkills(write, skills, issues) {
+    for (const skill of skills) {
+        writeLine(write, `${skill.skill}\t${skill.profile.platform}/${skill.profile.scope}\t${skill.state}\t${skill.finalPath ?? '-'}`);
+    }
+    for (const issue of issues)
+        writeLine(write, `${issue.code}: ${issue.message}`);
+}
+function renderReviewInspection(write, receipt) {
+    writeLine(write, `Review inspection (${receipt.view}): ${receipt.ok ? 'ok' : 'failed'}`);
+    if (receipt.view === 'review') {
+        renderReviewSkills(write, receipt.skills, receipt.issues);
+        return;
+    }
+    for (const issue of receipt.issues)
+        writeLine(write, `${issue.code}: ${issue.message}`);
+}
+function renderReviewPreparation(write, receipt) {
+    writeLine(write, `Review preparation: ${receipt.ok ? 'complete' : 'failed'}`);
+    if (receipt.sourceBindingPath)
+        writeLine(write, `Source binding: ${receipt.sourceBindingPath}`);
+    renderReviewSkills(write, receipt.skills, receipt.issues);
+}
+function requestedReviewView(argv) {
+    const inline = argv.find((token) => token.startsWith('--view='));
+    if (inline === '--view=release')
+        return 'release';
+    const index = argv.indexOf('--view');
+    return index >= 0 && argv[index + 1] === 'release' ? 'release' : 'review';
+}
+function createReviewPreparationFailure(message, code = 'invalidArguments') {
+    return {
+        schemaVersion: 1,
+        command: 'review:prepare',
+        ok: false,
+        target: null,
+        sourceBindingPath: null,
+        skills: [],
+        issues: [{ code, path: null, message }],
+    };
+}
 function writeWarnings(write, warnings, options = {}) {
     for (const warning of formatWarnings(warnings, options)) {
         writeLine(write, warning);
@@ -54,10 +123,266 @@ function resolveCliVersion() {
     return assertStrictSemVer(packageJson.version, 'packages/cli/package.json version');
 }
 function resolveCommandReceiptExitCode(result) {
-    if (result.overallState === 'failed') {
-        return 1;
+    return result.overallState === 'succeeded' ? 0 : 1;
+}
+class WriteCommandRequestError extends Error {
+    code = 'invalidArguments';
+}
+function normalizeWriteRequest(normalize) {
+    try {
+        return normalize();
+    }
+    catch (error) {
+        throw new WriteCommandRequestError(error instanceof Error ? error.message : String(error));
+    }
+}
+function writeCommandFailure(error) {
+    const message = redactString(error instanceof Error ? error.message : String(error));
+    if (error instanceof CommanderError || error instanceof WriteCommandRequestError) {
+        return { code: 'invalidArguments', message };
+    }
+    const explicitCode = error?.code;
+    if (typeof explicitCode === 'string' && /^[A-Za-z][A-Za-z0-9]*$/u.test(explicitCode)) {
+        return { code: explicitCode, message };
+    }
+    const separator = message.indexOf(':');
+    const prefix = separator > 0 ? message.slice(0, separator) : '';
+    return {
+        code: /^[A-Za-z][A-Za-z0-9]*$/u.test(prefix) ? prefix : 'writeCommandFailed',
+        message,
+    };
+}
+function preparseWriteReceiptRequest(argv) {
+    const request = { json: false, plugins: [] };
+    let positionalOnly = false;
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (positionalOnly) {
+            request.plugins.push(token);
+            continue;
+        }
+        if (token === '--') {
+            positionalOnly = true;
+            continue;
+        }
+        if (token === '--json') {
+            request.json = true;
+            continue;
+        }
+        if (token === '--platform' || token === '--scope') {
+            const value = argv[index + 1];
+            if (token === '--platform')
+                request.platform = value;
+            else
+                request.scope = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith('--platform=')) {
+            request.platform = token.slice('--platform='.length);
+            continue;
+        }
+        if (token.startsWith('--scope=')) {
+            request.scope = token.slice('--scope='.length);
+            continue;
+        }
+        if (token === '--dependency-scope' || token === '--script-timeout' || token === '--log-file') {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith('--'))
+            continue;
+        if (token.startsWith('-') && token !== '-') {
+            const shortOptions = token.slice(1);
+            for (let offset = 0; offset < shortOptions.length; offset += 1) {
+                const option = shortOptions[offset];
+                if (option === 'j') {
+                    request.json = true;
+                    continue;
+                }
+                if (option === 'p' || option === 's') {
+                    const value = shortOptions.slice(offset + 1) || argv[index + 1];
+                    if (option === 'p')
+                        request.platform = value;
+                    else
+                        request.scope = value;
+                    if (shortOptions.length === offset + 1)
+                        index += 1;
+                    break;
+                }
+            }
+            continue;
+        }
+        request.plugins.push(token);
+    }
+    return request;
+}
+function jsonWriteCommandRequest(argv) {
+    const command = argv[0];
+    if (!['install', 'reinstall', 'uninstall', 'cleanup', 'sync'].includes(command ?? '')) {
+        return null;
+    }
+    const request = preparseWriteReceiptRequest(argv);
+    if (!request.json)
+        return null;
+    const rawPlatform = request.platform;
+    const platform = rawPlatform === 'codex' || rawPlatform === 'claude' || rawPlatform === 'both'
+        ? rawPlatform
+        : 'codex';
+    return {
+        command: command,
+        plugins: request.plugins,
+        platform,
+        scope: request.scope === 'project' ? 'project' : 'user',
+    };
+}
+function writeCommandFailureReceipt(write, request, error) {
+    const platforms = request.platform === 'both'
+        ? ['codex', 'claude']
+        : [request.platform];
+    writeJsonReceipt(write, buildRebuildReceiptJson(request.command, {
+        platforms,
+        plugins: request.plugins,
+        warnings: [],
+        overallState: 'failed',
+        errors: [writeCommandFailure(error)],
+        receiptTargets: request.plugins.flatMap((selector) => platforms.map((platform) => {
+            let pluginName = selector;
+            let sourceId;
+            try {
+                const parsed = parsePluginId(selector);
+                pluginName = parsed.pluginName;
+                sourceId = parsed.sourceId;
+            }
+            catch {
+                // Keep the raw selector in the failed receipt.
+            }
+            return {
+                pluginName,
+                pluginId: selector,
+                ...(sourceId ? { sourceId } : {}),
+                platform,
+                scope: request.scope,
+            };
+        })),
+    }));
+}
+function scanConfigMutationShortOptions(token, command) {
+    if (!/^-[^-].*/u.test(token))
+        return { json: false, consumesNextValue: false };
+    let json = false;
+    for (let index = 1; index < token.length; index += 1) {
+        const option = token[index];
+        if (option === 's') {
+            return {
+                json,
+                consumesNextValue: index === token.length - 1,
+            };
+        }
+        if (option === 'j') {
+            json = true;
+            continue;
+        }
+        if (option === 'v' || option === 'D' || (option === 'y' && command === 'config:reset')) {
+            continue;
+        }
+        break;
+    }
+    return { json, consumesNextValue: false };
+}
+function jsonConfigMutationRequest(argv) {
+    if (argv[0] !== 'config' || !['set', 'unset', 'reset'].includes(argv[1] ?? '')) {
+        return null;
+    }
+    const command = `config:${argv[1]}`;
+    let json = false;
+    let plugin;
+    const valueOptions = new Set(['--scope', '--value-json', '--preset', '--log-file']);
+    for (let index = 2; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--')
+            break;
+        if (valueOptions.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (token === '--json') {
+            json = true;
+            continue;
+        }
+        const shortOptions = scanConfigMutationShortOptions(token, command);
+        if (shortOptions.json)
+            json = true;
+        if (shortOptions.consumesNextValue)
+            index += 1;
+        if (token.startsWith('-'))
+            continue;
+        plugin ??= token;
+    }
+    if (!json)
+        return null;
+    return {
+        command,
+        ...(plugin ? { plugin } : {}),
+    };
+}
+function configMutationFailure(error, env, cwd) {
+    const configWrite = configWriteStateForError(error);
+    if (error instanceof CommanderError) {
+        return {
+            code: 'invalidArguments',
+            message: 'error: invalid config mutation arguments',
+            configWrite,
+        };
+    }
+    const message = catalogPublicationFailure({
+        error,
+        env,
+        sensitiveRoots: [cwd],
+    }).message;
+    if (message.includes('Usage:'))
+        return { code: 'invalidArguments', message, configWrite };
+    const generationCode = catalogGenerationErrorCode(error);
+    if (generationCode === 'catalogGenerationUnavailable'
+        || generationCode === 'catalogGenerationSourceMissing') {
+        return { code: 'catalogSourceUnavailable', message, configWrite };
+    }
+    if (generationCode !== 'catalogGenerationFailed')
+        return { code: generationCode, message, configWrite };
+    const explicitCode = error?.code;
+    if (typeof explicitCode === 'string' && /^[A-Za-z][A-Za-z0-9]*$/u.test(explicitCode)) {
+        return { code: explicitCode, message, configWrite };
+    }
+    if (message.includes('legacyStateUnsupported'))
+        return { code: 'legacyStateUnsupported', message, configWrite };
+    if (message.includes('sourceChanged'))
+        return { code: 'sourceChanged', message, configWrite };
+    if (message.includes('sourceMissing'))
+        return { code: 'sourceMissing', message, configWrite };
+    if (message.startsWith('Cannot resolve required catalog sources:')) {
+        return { code: 'catalogSourceUnavailable', message, configWrite };
+    }
+    const prefix = message.match(/^([A-Za-z][A-Za-z0-9]*):/u)?.[1];
+    return { code: prefix ?? 'configMutationFailed', message, configWrite };
+}
+function writeConfigMutationFailureReceipt(write, request, failure) {
+    let plugin;
+    try {
+        if (request.plugin) {
+            parsePluginId(request.plugin);
+            plugin = request.plugin;
+        }
     }
-    return 0;
+    catch {
+        // Do not echo an invalid selector from raw argv in an early failure receipt.
+    }
+    writeJsonReceipt(write, buildConfigMutationReceipt(request.command, {
+        ok: false,
+        overallState: 'failed',
+        configWrite: failure.configWrite,
+        ...(plugin ? { plugin } : {}),
+        errors: [failure],
+    }));
 }
 async function runAuthoringScript(options) {
     const scriptPath = path.join(resolveCliPackageRoot(), 'dist', 'authoring', 'scripts', options.scriptName);
@@ -100,47 +425,54 @@ function optionTokens(flag, value) {
 function writeCommandUsage(command) {
     const cardinality = command === 'reinstall' || command === 'cleanup' ? '<plugin>' : '<plugin...>';
     const scope = command === 'cleanup' ? ' --scope <project|user>' : ' [--scope <project|user>]';
-    const all = command === 'upgrade' ? ' 或 aw upgrade --all --platform both --scope user' : '';
     return [
         `${command} 命令缺少必要参数。`,
         `Usage: aw ${command} ${cardinality} --platform <codex|claude|both>${scope}`,
-        `Example: aw ${command} example-plugin --platform codex --scope user${all}`,
+        `Example: aw ${command} example-plugin --platform codex --scope user`,
     ].join('\n');
 }
 function configCommandUsage(command) {
     const argumentsByCommand = {
         list: '<plugin>',
         get: '<plugin> [key]',
-        set: '<plugin> <key> <value>',
+        set: '<plugin> <field> --scope <project|user> (--value-json <json> | --value-stdin | --preset <id>)',
         unset: '<plugin> <key>',
         reset: '<plugin> --scope <project|user> --yes',
     };
     return [
         `config ${command} 命令缺少必要参数。`,
         `Usage: aw config ${command} ${argumentsByCommand[command]}`,
-        `Example: aw config ${command} example-plugin${command === 'set' ? ' key value' : command === 'unset' ? ' key' : command === 'reset' ? ' --scope user --yes' : ''}`,
+        `Example: aw config ${command} example-plugin${command === 'set' ? ' mode --scope user --value-json \'"safe"\'' : command === 'unset' ? ' key' : command === 'reset' ? ' --scope user --yes' : ''}`,
     ].join('\n');
 }
-function assertUpgradeAllConflict(pluginNames, all) {
-    if (all && pluginNames.length > 0) {
-        throw new Error('upgrade 命令不能同时使用插件名和 `--all`。');
+async function readUtf8Stdin(stdin) {
+    const chunks = [];
+    for await (const chunk of stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : Buffer.from(chunk));
     }
+    return Buffer.concat(chunks).toString('utf8');
 }
 function equivalentWriteCommand(command, selection, rawOptions) {
     return shellCommand(buildEquivalentWriteCommandTokens(command, selection, rawOptions));
 }
 export function buildEquivalentWriteCommandTokens(command, selection, rawOptions) {
-    const all = command === 'upgrade' && rawOptions.all === true;
     return [
         'aw',
         command,
-        ...(all ? ['--all'] : []),
         '--platform',
         selection.platform ?? 'both',
         '--scope',
         selection.scope ?? 'user',
-        ...(command === 'cleanup' ? [] : optionTokens('--script-timeout', rawOptions.scriptTimeout)),
-        ...(!all && selection.plugins.length > 0 ? ['--', ...selection.plugins] : []),
+        ...(rawOptions.allowManagedCodexInstall === true
+            ? ['--allow-managed-codex-install']
+            : []),
+        ...(command === 'install'
+            ? (rawOptions.dependencyScope ?? []).flatMap((value) => ['--dependency-scope', value])
+            : []),
+        ...((command === 'install' || command === 'reinstall')
+            ? optionTokens('--script-timeout', rawOptions.scriptTimeout)
+            : []),
+        ...(selection.plugins.length > 0 ? ['--', ...selection.plugins] : []),
     ];
 }
 function equivalentConfigCommand(options) {
@@ -152,39 +484,14 @@ function equivalentConfigCommandProjection(resolve) {
         equivalentCommandTokens: (selection) => buildEquivalentConfigCommandTokens(resolve(selection)),
     };
 }
-function configSetEquivalentOptions(selection, candidates, rawOptions) {
-    const field = candidates.find((entry) => entry.pluginName === selection.plugins[0])
-        ?.configSchema?.[selection.key ?? ''];
-    const placeholder = configFieldPlaceholder(field);
-    return {
-        command: 'set',
-        plugin: selection.plugins[0],
-        key: selection.key,
-        value: placeholder
-            ? rawOptions.valueJson ? JSON.stringify(placeholder) : placeholder
-            : formatConfigCommandValue(selection.value, rawOptions.valueJson === true),
-        scope: selection.scope ?? 'user',
-        projectLayer: selection.projectLayer,
-        valueJson: rawOptions.valueJson,
-    };
-}
-function configFieldPlaceholder(field) {
-    if (field?.sensitive)
-        return '<sensitive-value>';
-    if (field?.type === 'file')
-        return '<file-path>';
-    if (field?.type === 'directory')
-        return '<directory-path>';
-    return undefined;
-}
 export function buildEquivalentConfigCommandTokens(options) {
     return [
         'aw',
         'config',
         options.command,
         ...optionTokens('--scope', options.scope),
-        ...(options.projectLayer === 'local' ? ['--local'] : []),
-        ...(options.valueJson ? ['--value-json'] : []),
+        ...optionTokens('--value-json', options.valueJson),
+        ...optionTokens('--preset', options.preset),
         ...(options.confirmed ? ['--yes'] : []),
         '--',
         options.plugin,
@@ -207,7 +514,6 @@ async function loadWizardCandidates(context, rawOptions) {
         cwd: context.cwd,
         scope: rawOptions.scope,
         platform: rawOptions.platform,
-        includeCatalogOnly: true,
     }, context);
     return toWizardCandidates(loaded.items);
 }
@@ -235,7 +541,6 @@ async function loadStoredConfigWizardCandidates(context, locations, options = {}
             cwd: context.cwd,
             env: context.env,
             scope: location.scope,
-            ...(location.scope === 'project' ? { projectLayer: location.projectLayer } : {}),
         });
         for (const store of stores) {
             const keys = Object.keys(store.values);
@@ -243,12 +548,11 @@ async function loadStoredConfigWizardCandidates(context, locations, options = {}
                 continue;
             const existing = storesByPlugin.get(store.pluginId) ?? {
                 sourceId: store.sourceId,
-                sourceIdentity: store.sourceIdentity,
+                ...(store.binding.kind === 'source'
+                    ? { sourceIdentity: store.binding.sourceIdentity }
+                    : {}),
                 keys: new Set(),
             };
-            if (existing.sourceIdentity !== store.sourceIdentity) {
-                throw new Error(`sourceChanged: ${store.pluginId} config stores have different source identities.`);
-            }
             for (const key of keys)
                 existing.keys.add(key);
             storesByPlugin.set(store.pluginId, existing);
@@ -260,26 +564,53 @@ async function loadStoredConfigWizardCandidates(context, locations, options = {}
         pluginName: pluginId,
         pluginId,
         sourceId: store.sourceId,
-        sourceIdentity: store.sourceIdentity,
+        ...(store.sourceIdentity ? { sourceIdentity: store.sourceIdentity } : {}),
         targets: [],
         configKeys: [...store.keys].sort((left, right) => left.localeCompare(right)),
     }));
 }
 function configReadStoreLocations(rawOptions) {
-    if (rawOptions.local)
-        return [{ scope: 'project', projectLayer: 'local' }];
     if (rawOptions.scope === 'user')
-        return [{ scope: 'user', projectLayer: 'shared' }];
+        return [{ scope: 'user' }];
     if (rawOptions.scope === 'project')
-        return [{ scope: 'project', projectLayer: 'shared' }];
+        return [{ scope: 'project' }];
     return [
-        { scope: 'user', projectLayer: 'shared' },
-        { scope: 'project', projectLayer: 'shared' },
-        { scope: 'project', projectLayer: 'local' },
+        { scope: 'user' },
+        { scope: 'project' },
     ];
 }
 function overallResultState(value) {
-    return value.overallState;
+    return value.overallState === 'succeeded' ? 'succeeded' : 'failed';
+}
+async function resolveStoredConfigResetIdentity(options) {
+    const parsed = parsePluginId(options.selector);
+    if (parsed.sourceId) {
+        return {
+            pluginName: parsed.pluginName,
+            pluginId: options.selector,
+            sourceId: parsed.sourceId,
+        };
+    }
+    const matches = (await listNamespacedPluginConfigStores({
+        cwd: options.context.cwd,
+        env: options.context.env,
+        scope: options.scope,
+    })).filter((store) => store.pluginName === parsed.pluginName);
+    if (matches.length === 0) {
+        throw new Error(`configStoreMissing: ${options.selector} has no config in the selected store.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`configTargetAmbiguous: ${options.selector} exists in multiple source namespaces: ${matches.map((store) => store.pluginId).join(', ')}. Use a full pluginId.`);
+    }
+    const [match] = matches;
+    return {
+        pluginName: match.pluginName,
+        pluginId: match.pluginId,
+        sourceId: match.sourceId,
+        ...(match.binding.kind === 'source'
+            ? { sourceIdentity: match.binding.sourceIdentity }
+            : { logicalIdentity: match.binding.logicalIdentity }),
+    };
 }
 async function resolveStoredOnlyConfigIdentity(options) {
     const parsed = parsePluginId(options.selector);
@@ -289,33 +620,43 @@ async function resolveStoredOnlyConfigIdentity(options) {
         cwd: options.context.cwd,
         env: options.context.env,
         scope: location.scope,
-        ...(location.scope === 'project' ? { projectLayer: location.projectLayer } : {}),
     })))).flat().filter((store) => store.pluginId === options.selector);
     if (stores.length === 0)
         throw new Error(`Plugin "${options.selector}" does not have a namespaced config store.`);
-    const identities = new Set(stores.map((store) => store.sourceIdentity));
-    if (identities.size !== 1)
-        throw new Error(`sourceChanged: ${options.selector} config stores have different source identities.`);
-    const sourceIdentity = [...identities][0];
-    await withResolvedMultiSourceCatalog({
+    const sourceBindings = stores.flatMap((store) => store.binding.kind === 'source'
+        ? [store.binding.sourceIdentity] : []);
+    const catalogBindings = stores.flatMap((store) => store.binding.kind === 'catalog'
+        ? [store.binding.logicalIdentity] : []);
+    if (new Set(sourceBindings).size > 1 || new Set(catalogBindings).size > 1) {
+        throw new Error(`identityMismatch: ${options.selector} config stores have different bindings.`);
+    }
+    const currentSource = await withResolvedMultiSourceCatalog({
         cliVersion: resolveCliVersion(),
-        freshnessPolicy: 'cacheFirst',
         sourceIds: [parsed.sourceId],
         env: options.context.env,
         consume: async (catalog) => {
             const source = catalog.sources.find((entry) => entry.sourceId === parsed.sourceId);
-            if (!source?.resolution)
+            if (!source?.resolution) {
                 throw source?.error ?? new Error(`Catalog source "${parsed.sourceId}" is unavailable.`);
-            if (source.resolution.sourceIdentity !== sourceIdentity) {
-                throw new Error(`sourceChanged: ${options.selector} config source identity does not match the current source.`);
             }
+            return {
+                sourceIdentity: source.resolution.sourceIdentity,
+                logicalIdentity: source.resolution.logicalIdentity,
+            };
         },
     });
+    if (sourceBindings[0] && sourceBindings[0] !== currentSource.sourceIdentity) {
+        throw new Error(`identityMismatch: ${options.selector} user config does not match the current source identity.`);
+    }
+    if (catalogBindings[0] && catalogBindings[0] !== currentSource.logicalIdentity) {
+        throw new Error(`identityMismatch: ${options.selector} project config does not match the current Catalog logical identity.`);
+    }
     return {
         pluginName: parsed.pluginName,
         pluginId: options.selector,
         sourceId: parsed.sourceId,
-        sourceIdentity,
+        sourceIdentity: currentSource.sourceIdentity,
+        logicalIdentity: currentSource.logicalIdentity,
     };
 }
 async function resolveMultiSourceConfigRead(options) {
@@ -324,26 +665,21 @@ async function resolveMultiSourceConfigRead(options) {
         env: options.context.env,
     });
     assertCatalogSourceReferencesSupported(inventory);
-    const projectLayer = resolveConfigProjectLayer(options.rawOptions);
     return withResolvedCatalogPlugin({
         selector: options.selector,
         cliVersion: resolveCliVersion(),
-        freshnessPolicy: 'cacheFirst',
         env: options.context.env,
         consume: async ({ pluginId, source, plugin }) => {
             const result = await resolveConfigRead({
                 pluginName: plugin.manifest.name,
                 plugin,
-                scope: options.rawOptions.local
-                    ? 'project'
-                    : resolveConfigReadResolution(options.rawOptions.scope),
-                projectLayer,
+                scope: resolveConfigReadResolution(options.rawOptions.scope),
                 cwd: options.context.cwd,
                 env: options.context.env,
             });
             if (options.key !== undefined) {
                 const field = findConfigFieldEntry(result.fields, options.key);
-                if (!field && plugin.manifest.config?.schema?.[options.key] === undefined) {
+                if (!field && plugin.manifest.config?.fields?.[options.key] === undefined) {
                     throw new Error(`Unknown config key "${options.key}".`);
                 }
                 if (field)
@@ -369,12 +705,10 @@ async function resolveMultiSourceConfigRead(options) {
         const result = await resolveConfigRead({
             sourceId: stored.sourceId,
             sourceIdentity: stored.sourceIdentity,
+            logicalIdentity: stored.logicalIdentity,
             pluginName: stored.pluginName,
             plugin: null,
-            scope: options.rawOptions.local
-                ? 'project'
-                : resolveConfigReadResolution(options.rawOptions.scope),
-            projectLayer,
+            scope: resolveConfigReadResolution(options.rawOptions.scope),
             cwd: options.context.cwd,
             env: options.context.env,
         });
@@ -387,36 +721,52 @@ async function resolveMultiSourceConfigRead(options) {
         return { ...stored, result };
     });
 }
-async function executeWriteCommand(command, pluginNames, rawOptions, context) {
+export function createManagedCodexAuthorizer(rawOptions, context) {
+    if (rawOptions.allowManagedCodexInstall === true)
+        return async () => true;
+    if (!(context.interactive && context.isTty && !context.isCi && rawOptions.json !== true)
+        || !context.prompt.confirm)
+        return undefined;
+    return async () => {
+        const response = await context.prompt.confirm({
+            message: '系统中没有可用的 Codex CLI。是否获取本次操作所需的 AW-managed Codex runtime？',
+            defaultValue: false,
+        });
+        return !response.cancelled && response.value === true;
+    };
+}
+async function executeWriteCommand(command, pluginNames, rawOptions, context, directCli = false) {
     const raw = { cwd: context.cwd, ...rawOptions };
-    const commandOptions = command === 'install'
+    const commandOptions = normalizeWriteRequest(() => command === 'install'
         ? normalizeInstallCommandOptions(raw)
-        : command === 'upgrade'
-            ? normalizeUpgradeCommandOptions(raw)
-            : command === 'uninstall'
-                ? normalizeUninstallCommandOptions(raw)
-                : command === 'cleanup'
-                    ? normalizeCleanupCommandOptions(raw)
-                    : normalizeReinstallCommandOptions(raw);
+        : command === 'uninstall'
+            ? normalizeUninstallCommandOptions(raw)
+            : command === 'cleanup'
+                ? normalizeCleanupCommandOptions(raw)
+                : normalizeReinstallCommandOptions(raw));
     await emitCommandEvent(context, {
         type: 'options:normalized',
         data: { plugins: pluginNames, options: commandOptions },
     });
+    const managedCodexAuthorizer = createManagedCodexAuthorizer(rawOptions, context);
+    const runtime = {
+        ...context,
+        directCli,
+        preApplyConfirmed: rawOptions.yes === true,
+        ...(managedCodexAuthorizer ? { managedCodexAuthorizer } : {}),
+    };
     switch (command) {
-        case 'install': return installCommand(pluginNames, commandOptions, context);
-        case 'upgrade': return upgradeCommand(pluginNames, commandOptions, context);
-        case 'uninstall': return uninstallCommand(pluginNames, commandOptions, context);
-        case 'cleanup': return cleanupCommand(pluginNames, commandOptions, context);
-        case 'reinstall': return reinstallCommand(pluginNames, commandOptions, context);
+        case 'install': return installCommand(pluginNames, commandOptions, runtime);
+        case 'uninstall': return uninstallCommand(pluginNames, commandOptions, runtime);
+        case 'cleanup': return cleanupCommand(pluginNames, commandOptions, runtime);
+        case 'reinstall': return reinstallCommand(pluginNames, commandOptions, runtime);
     }
 }
 async function runWriteCommandAction(command, pluginNames, rawOptions, context) {
     if ((command === 'cleanup' || command === 'reinstall') && pluginNames.length > 1) {
-        throw new Error(`${command} 命令当前只支持单个插件目标。`);
+        throw new WriteCommandRequestError(`${command} 命令当前只支持单个插件目标。`);
     }
-    if (command === 'upgrade')
-        assertUpgradeAllConflict(pluginNames, rawOptions.all === true);
-    const missingPlugin = pluginNames.length === 0 && !(command === 'upgrade' && rawOptions.all === true);
+    const missingPlugin = pluginNames.length === 0;
     const missingPlatform = rawOptions.platform === undefined;
     const missingScope = command === 'cleanup' && rawOptions.scope === undefined;
     const missing = missingPlugin || missingPlatform || missingScope;
@@ -431,17 +781,16 @@ async function runWriteCommandAction(command, pluginNames, rawOptions, context)
     if (!missing) {
         return {
             cancelled: false,
-            result: await executeWriteCommand(command, pluginNames, rawOptions, context),
+            result: await executeWriteCommand(command, pluginNames, rawOptions, context, true),
         };
     }
     if (!isWizardAvailable(context, rawOptions)) {
-        throw new Error(writeCommandUsage(command));
+        throw new WriteCommandRequestError(writeCommandUsage(command));
     }
     const loaded = await loadConsoleItemsResult({
         cwd: context.cwd,
         scope: rawOptions.scope,
         platform: rawOptions.platform,
-        includeCatalogOnly: true,
     }, context);
     if (loaded.catalogUnavailable) {
         throw new Error('插件目录不可用。请运行 `aw init` 或 `aw init --force`，或使用完整参数重试。');
@@ -587,34 +936,77 @@ async function runActionWithContext(context, action) {
 function writeJsonReceipt(write, payload) {
     writeLine(write, JSON.stringify(payload, null, 2));
 }
-function configLayerLabel(scope, projectLayer = 'shared') {
+function configLayerLabel(scope) {
     if (scope === 'user') {
         return '个人';
     }
-    return projectLayer === 'local' ? '当前项目（本机私有覆盖）' : '当前项目';
+    return '当前项目';
 }
 function writeConfigApplyNotice(write, receipt) {
-    if (receipt.targetResults.length === 0) {
-        const message = receipt.applySkippedReason === 'noConfigChange'
+    const sanitizeMessage = (message) => redactString(message)
+        .replace(/https?:\/\/\S+/giu, '[REDACTED URL]')
+        .replace(/(?:file:\/\/)?(?:\/[\w.@+-]+){2,}/gu, '[REDACTED PATH]')
+        .replace(/[A-Za-z]:\\(?:[^\s\\]+\\)+[^\s\\]*/gu, '[REDACTED PATH]');
+    const writeTargetFailures = () => {
+        for (const entry of receipt.apply.targetResults.filter((target) => target.state === 'failed' || target.state === 'skipped')) {
+            const reason = entry.message
+                ? `${entry.errorCode ? `[${entry.errorCode}] ` : ''}${sanitizeMessage(entry.message)}`
+                : entry.errorCode
+                    ? `失败原因：${entry.errorCode}。`
+                    : '未提供安全失败原因。';
+            const command = `aw reinstall ${receipt.plugin} -p ${entry.target.platform} -s ${entry.target.scope}`;
+            const recovery = entry.errorCode === 'invalidConfig'
+                ? ' 请修复无效配置后运行 aw sync。'
+                : entry.errorCode === 'preApplyAuthorizationRequired'
+                    || entry.errorCode === 'sharedNativeConfigApplyConfirmationRequired'
+                    || entry.errorCode === 'sharedNativeImpactAuthorizationRequired'
+                    ? ` 请运行 ${command} --yes 重试。`
+                    : entry.state === 'failed'
+                        ? ` 请在解决失败原因后运行 ${command}。`
+                        : '';
+            writeLine(write, `${entry.target.platform}/${entry.target.scope}：${reason}${recovery}`);
+        }
+    };
+    const targetResults = receipt.apply.targetResults;
+    if (receipt.apply.state === 'skipped') {
+        const message = receipt.apply.reason === 'noConfigChange'
             ? '配置内容没有变化，因此没有运行 reinstall。'
-            : '配置已保存。当前没有可见的 AW 安装目标，因此没有应用配置。';
+            : receipt.apply.reason === 'noEffectiveConfigChange'
+                ? '配置存储已更新，但有效配置没有变化，因此没有运行 reinstall。'
+                : receipt.apply.reason === 'notRequested'
+                    ? '配置已保存，但未请求应用配置。'
+                    : '配置已保存。当前没有可见的 AW 安装目标，因此没有应用配置。';
         writeLine(write, message);
     }
-    else {
-        const completed = receipt.targetResults.filter((entry) => entry.state === 'completed').length;
-        const failed = receipt.targetResults.filter((entry) => entry.state === 'failed');
-        writeLine(write, `配置已保存。已重装 ${completed} 个当前可见目标；失败 ${failed.length} 个。`);
-        for (const entry of failed) {
-            writeLine(write, `${entry.target.platform}/${entry.target.scope}：${entry.message ?? 'reinstall 失败。'} `
-                + `请重试 aw reinstall ${receipt.plugin} -p ${entry.target.platform} -s ${entry.target.scope}。`);
-        }
+    else if (receipt.apply.state === 'unavailable') {
+        const fallbackMessages = {
+            invalidConfig: '可见目标的有效配置无效。',
+            schemaUnavailable: '配置 schema 不可用。',
+            sourceUnavailable: '插件来源不可用。',
+            effectiveConfigUnavailable: '无法读取有效配置。',
+            targetDiscoveryFailed: '无法发现可应用配置的目标。',
+        };
+        const detail = receipt.apply.error
+            ? `${receipt.apply.error.code}：${sanitizeMessage(receipt.apply.error.message)}`
+            : `${receipt.apply.reason}：${fallbackMessages[receipt.apply.reason]}`;
+        const recovery = receipt.apply.reason === 'invalidConfig'
+            ? '请修复无效配置后运行 aw sync。'
+            : receipt.apply.reason === 'effectiveConfigUnavailable'
+                ? '请修复配置后运行 aw sync。'
+                : receipt.apply.reason === 'schemaUnavailable' || receipt.apply.reason === 'sourceUnavailable'
+                    ? '请修复插件来源或配置后运行 aw sync。'
+                    : '请修复来源或配置后运行 aw sync。';
+        writeLine(write, `配置已保存，但当前无法应用配置。${detail} ${recovery}`);
+        writeTargetFailures();
     }
-    if (receipt.otherProjectsRequireReinstall) {
-        writeLine(write, '其它项目没有被扫描。请进入每个项目目录并运行对应的 aw reinstall 命令。');
+    else {
+        const completed = targetResults.filter((entry) => entry.state === 'completed').length;
+        const failed = targetResults.filter((entry) => entry.state === 'failed').length;
+        const skipped = targetResults.filter((entry) => entry.state === 'skipped').length;
+        writeLine(write, `配置已保存。已重装 ${completed} 个当前可见目标；失败 ${failed} 个；跳过 ${skipped} 个。`);
+        writeTargetFailures();
     }
-}
-function writeProjectLocalConfigNotice(write) {
-    writeLine(write, '当前显示的是当前项目的本机私有覆盖层，不作为 repo-visible artifact 渲染输入。');
+    writeWarnings(write, receipt.warnings);
 }
 function renderConfigFieldState(field) {
     if (field.valueState === 'invalid') {
@@ -634,13 +1026,15 @@ function writeConfigReadHuman(write, resolved, pluginName) {
         }
         if (field.kind === 'manifest' && field.valueState === 'invalid') {
             const sourceScope = field.sourceLayer === 'project'
-                ? ' -s project'
-                : field.sourceLayer === 'local'
-                    ? ' -s project --local'
-                    : ' -s user';
-            writeLine(write, `  aw config set ${pluginName} ${field.key} <value>${sourceScope}`);
-            writeLine(write, `  aw config unset ${pluginName} ${field.key}${sourceScope}`);
-            writeLine(write, `  aw config reset ${pluginName}${sourceScope}`);
+                ? 'project'
+                : 'user';
+            const definition = resolved.fieldDefinitions?.[field.key];
+            if (definition) {
+                writeLine(write, `  ${formatPluginConfigSetRecoveryCommand(pluginName, field.key, definition, sourceScope)}`);
+            }
+            const scopeOption = ` -s ${sourceScope}`;
+            writeLine(write, `  aw config unset ${pluginName} ${field.key}${scopeOption}`);
+            writeLine(write, `  aw config reset ${pluginName}${scopeOption}`);
         }
     }
 }
@@ -674,9 +1068,176 @@ export function buildProgram(options = {}) {
     const plugin = program
         .command('plugin')
         .description('Create and validate AW plugin source');
+    const self = program
+        .command('self')
+        .description('Describe and check this AW executable');
+    self
+        .command('describe')
+        .description('Describe implemented AW capabilities')
+        .requiredOption('--json', 'emit one machine-readable JSON object')
+        .action(() => {
+        writeJsonReceipt(io.stdout, describeCurrentAw(resolveCliVersion()));
+    });
+    self
+        .command('check')
+        .description('Check nearby plugin requirements against this AW executable')
+        .option('--from <path>', 'start discovery from this file or directory')
+        .requiredOption('--json', 'emit one machine-readable JSON object')
+        .action(async (rawOptions) => {
+        const result = await checkCurrentAw({
+            awVersion: resolveCliVersion(),
+            from: path.resolve(cwd, rawOptions.from ?? '.'),
+        });
+        writeJsonReceipt(io.stdout, result);
+        commandExitState.exitCode = result.ok ? 0 : 1;
+    });
+    plugin
+        .command('capabilities')
+        .description('Show the current plugin manifest authoring surface')
+        .option('--surface <surface>', 'manifest | build-config | extensions | slash-commands | mcp-apps | config | pre-apply | artifacts')
+        .option('--json', 'emit one machine-readable JSON object', false)
+        .action((rawOptions) => {
+        try {
+            const surface = rawOptions.surface === undefined
+                ? undefined
+                : parsePluginCapabilitySurface(rawOptions.surface);
+            const result = getPluginCapabilitiesResult({
+                awVersion: resolveCliVersion(),
+                ...(surface ? { surface } : {}),
+            });
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, result);
+            else
+                for (const line of renderPluginCapabilities(result))
+                    writeLine(io.stdout, line);
+        }
+        catch (error) {
+            writeLine(io.stderr, error instanceof Error ? error.message : String(error));
+            commandExitState.exitCode = 1;
+        }
+    });
+    plugin
+        .command('requirements')
+        .description('Inspect or update effective AW capabilities required by a plugin')
+        .argument('<plugin-directory>', 'plugin source directory')
+        .option('--workspace-root <root>', 'Catalog Workspace root (default: nearest ancestor from plugin directory)')
+        .option('--add <capability>', 'add one declared AW capability')
+        .option('--remove <capability>', 'remove one declared AW capability')
+        .requiredOption('--json', 'emit one machine-readable JSON object')
+        .action(async (pluginDirectory, rawOptions) => {
+        try {
+            const result = await inspectPluginRequirements({
+                pluginDirectory,
+                ...(rawOptions.workspaceRoot ? { workspaceRoot: rawOptions.workspaceRoot } : {}),
+                ...(rawOptions.add ? { add: rawOptions.add } : {}),
+                ...(rawOptions.remove ? { remove: rawOptions.remove } : {}),
+                cwd,
+            });
+            writeJsonReceipt(io.stdout, result);
+            if (result.observations.some((observation) => observation.blocking)) {
+                commandExitState.exitCode = 1;
+            }
+        }
+        catch (error) {
+            writeJsonReceipt(io.stdout, {
+                schemaVersion: 1,
+                command: 'plugin:requirements',
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            commandExitState.exitCode = 1;
+        }
+    });
     const skill = program
         .command('skill')
         .description('Install, materialize, or validate Agent Skills');
+    const skillEval = skill
+        .command('eval')
+        .description('Prepare or diagnose deterministic Agent Skill Eval inputs');
+    skillEval
+        .command('doctor')
+        .description('Inspect Agent Skill Eval provider readiness without model execution')
+        .requiredOption('--json', 'emit one provider doctor JSON object')
+        .action(async () => {
+        try {
+            writeJsonReceipt(io.stdout, await doctorEvalProviders({ sourceEnv: env }));
+        }
+        catch (error) {
+            writeJsonReceipt(io.stdout, {
+                ok: false,
+                error: redactString(error instanceof Error ? error.message : String(error)),
+            });
+            commandExitState.exitCode = 1;
+        }
+    });
+    skillEval
+        .command('prepare')
+        .description('Prepare one complete Agent Skill Eval input directory')
+        .argument('<plugin>', 'canonical Workspace plugin name')
+        .argument('<skill>', 'owner Skill name')
+        .option('--suite <suite>', 'Eval suite ID')
+        .option('--profile <profile>', 'Eval profile ID')
+        .option('--workspace-root <root>', 'Catalog Workspace root')
+        .option('--split <split>', 'case split filter')
+        .option('--case <id>', 'case ID filter')
+        .option('--runs <count>', 'runs per selected case')
+        .option('--timeout-ms <milliseconds>', 'timeout for each provider attempt')
+        .option('--baseline <mode>', 'append without-skill comparison')
+        .option('--previous-version <runtime-skill-root>', 'append a previous-version comparison')
+        .option('--keep-workspace', 'retain the preparation materialization workspace', false)
+        .requiredOption('--output <spec-directory>', 'new EvalSpec directory')
+        .requiredOption('--json', 'emit one preparation receipt JSON object')
+        .action(async (pluginName, skillName, rawOptions) => {
+        try {
+            const workspace = await resolveCatalogWorkspaceRoot({
+                cwd,
+                ...(rawOptions.workspaceRoot === undefined ? {} : { explicitRoot: rawOptions.workspaceRoot }),
+                mode: 'existing',
+                env,
+            });
+            const runs = rawOptions.runs === undefined
+                ? undefined
+                : (/^[1-9][0-9]*$/u.test(rawOptions.runs) ? Number(rawOptions.runs) : Number.NaN);
+            const timeoutMs = rawOptions.timeoutMs === undefined
+                ? undefined
+                : (/^[1-9][0-9]*$/u.test(rawOptions.timeoutMs) ? Number(rawOptions.timeoutMs) : Number.NaN);
+            const receipt = await prepareSkillEval({
+                workspaceRoot: workspace.workspaceRoot,
+                workspaceRootResolvedFrom: workspace.workspaceRootResolvedFrom,
+                pluginName,
+                skillName,
+                ...(rawOptions.suite === undefined ? {} : { suiteId: rawOptions.suite }),
+                ...(rawOptions.profile === undefined ? {} : { profileId: rawOptions.profile }),
+                output: rawOptions.output,
+                cwd,
+                env,
+                ...(rawOptions.split === undefined ? {} : { split: rawOptions.split }),
+                ...(rawOptions.case === undefined ? {} : { caseId: rawOptions.case }),
+                ...(runs === undefined ? {} : { runs }),
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                ...(rawOptions.baseline === undefined ? {} : {
+                    baseline: rawOptions.baseline,
+                }),
+                ...(rawOptions.previousVersion === undefined ? {} : {
+                    previousVersion: rawOptions.previousVersion,
+                }),
+                ...(rawOptions.keepWorkspace === true ? { keepWorkspace: true } : {}),
+            });
+            writeJsonReceipt(io.stdout, receipt);
+        }
+        catch (error) {
+            writeJsonReceipt(io.stdout, {
+                schemaVersion: 1,
+                command: 'skill:eval:prepare',
+                ok: false,
+                errors: [{
+                        code: 'evalPreparationFailed',
+                        message: redactString(error instanceof Error ? error.message : String(error)),
+                    }],
+            });
+            commandExitState.exitCode = 1;
+        }
+    });
     const review = program
         .command('review')
         .description('Publish and inspect immutable review records');
@@ -685,6 +1246,81 @@ export function buildProgram(options = {}) {
         recordDir: reviewRecordDir(repoRoot, record),
         manifest: record.manifest,
     });
+    review
+        .command('inspect')
+        .description('Inspect current AW Review source and materialization facts')
+        .argument('<target>', 'Catalog Workspace, Plugin, or source Skill path')
+        .addOption(strictValueOption('--workspace-root <root>', 'explicit Catalog Workspace root'))
+        .option('--skill <name>', 'select one declared Skill', collectUniqueOption, [])
+        .addOption(strictValueOption('--platform <platform>', 'select codex, claude, or agent-skills', ['codex', 'claude', 'agent-skills']))
+        .addOption(strictValueOption('--scope <scope>', 'select user or project scope', ['user', 'project']))
+        .addOption(strictValueOption('--config <file>', 'review config JSON file'))
+        .option('--materialization <receipt>', 'validate one aw-source-binding receipt', collectUniqueOption, [])
+        .addOption(strictValueOption('--view <view>', 'select review or release view', ['review', 'release']).default('review'))
+        .option('--json', 'emit one Review inspection JSON object', false)
+        .action(async (target, rawOptions) => {
+        try {
+            const receipt = await inspectReviewTarget({
+                cwd,
+                target,
+                ...(rawOptions.workspaceRoot === undefined
+                    ? {}
+                    : { workspaceRoot: rawOptions.workspaceRoot }),
+                skills: rawOptions.skill,
+                ...(rawOptions.platform === undefined ? {} : { platform: rawOptions.platform }),
+                ...(rawOptions.scope === undefined ? {} : { scope: rawOptions.scope }),
+                ...(rawOptions.config === undefined ? {} : { configFile: rawOptions.config }),
+                materializations: [...new Set(rawOptions.materialization
+                        .map((entry) => path.resolve(cwd, entry)))],
+                view: rawOptions.view,
+                env,
+            });
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, receipt);
+            else
+                renderReviewInspection(io.stdout, receipt);
+            commandExitState.exitCode = 0;
+        }
+        catch (error) {
+            const receipt = createReviewInspectionFailure(error, rawOptions.view);
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, receipt);
+            else
+                renderReviewInspection(io.stdout, receipt);
+            commandExitState.exitCode = getReviewInspectionExitCode(error);
+        }
+    });
+    review
+        .command('prepare')
+        .description('Prepare deterministic Skill finals for AW Review')
+        .argument('<target>', 'Plugin or source Skill path')
+        .addOption(strictValueOption('--workspace-root <root>', 'explicit Catalog Workspace root'))
+        .option('--skill <name>', 'select one declared Skill', collectUniqueOption, [])
+        .addOption(strictValueOption('--platform <platform>', 'select codex, claude, or agent-skills', ['codex', 'claude', 'agent-skills']).makeOptionMandatory())
+        .addOption(strictValueOption('--scope <scope>', 'select user or project scope', ['user', 'project']).makeOptionMandatory())
+        .addOption(strictValueOption('--config <file>', 'review config JSON file'))
+        .addOption(strictValueOption('--out <new-dir>', 'new output directory').makeOptionMandatory())
+        .option('--json', 'emit one Review preparation JSON object', false)
+        .action(async (target, rawOptions) => {
+        const result = await prepareReviewTarget({
+            cwd,
+            target,
+            ...(rawOptions.workspaceRoot === undefined
+                ? {}
+                : { workspaceRoot: rawOptions.workspaceRoot }),
+            skills: rawOptions.skill,
+            platform: rawOptions.platform,
+            scope: rawOptions.scope,
+            ...(rawOptions.config === undefined ? {} : { configFile: rawOptions.config }),
+            out: rawOptions.out,
+            env,
+        });
+        if (rawOptions.json)
+            writeJsonReceipt(io.stdout, result.receipt);
+        else
+            renderReviewPreparation(io.stdout, result.receipt);
+        commandExitState.exitCode = result.exitCode;
+    });
     review
         .command('digest')
         .description('Compute one canonical workflow component digest')
@@ -837,15 +1473,17 @@ export function buildProgram(options = {}) {
         .option('--skill <name...>', 'install only selected Skill names')
         .option('--agent <id...>', 'install to explicit Agent IDs')
         .option('-y, --yes', 'confirm the reviewed install', false)
-        .option('-j, --json', 'emit one receipt v4 JSON object', false)
+        .option('-j, --json', 'emit one receipt v5 JSON object', false)
         .action(async (selector, rawOptions) => {
         const context = createActionContext('skill:install', {});
         const writeFailure = (error) => {
-            const code = error instanceof PortableCommandError || error instanceof SkillsCliError
-                ? error.code
-                : 'portableInstallFailed';
+            const capabilityError = error instanceof AwCapabilityUnsupportedError ? error : undefined;
+            const code = capabilityError?.code
+                ?? (error instanceof PortableCommandError || error instanceof SkillsCliError
+                    ? error.code
+                    : 'portableInstallFailed');
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 4,
+                receiptSchemaVersion: 5,
                 command: 'skill:install',
                 ok: false,
                 status: 'failed',
@@ -861,7 +1499,15 @@ export function buildProgram(options = {}) {
                 materializationDigest: null,
                 verification: { records: [], missing: [] },
                 warnings: [],
-                failures: [{ code, message: `${code}: portable Skill 安装未执行。` }],
+                failures: [{
+                        code,
+                        message: capabilityError?.message ?? `${code}: portable Skill 安装未执行。`,
+                        ...(capabilityError ? {
+                            plugin: capabilityError.plugin,
+                            missingCapabilities: capabilityError.missingCapabilities,
+                            availableCapabilities: capabilityError.availableCapabilities,
+                        } : {}),
+                    }],
             });
         };
         if (rawOptions.json && !rawOptions.yes) {
@@ -931,7 +1577,7 @@ export function buildProgram(options = {}) {
         .requiredOption('-s, --scope <scope>', 'project or user')
         .requiredOption('--out <dir>', 'output directory')
         .option('--skill <name...>', 'write only selected Skill names')
-        .option('-j, --json', 'emit one receipt v4 JSON object', false)
+        .option('-j, --json', 'emit one receipt v5 JSON object', false)
         .action(async (selector, rawOptions) => {
         const context = createActionContext('skill:materialize', {});
         try {
@@ -952,11 +1598,13 @@ export function buildProgram(options = {}) {
         catch (error) {
             if (!rawOptions.json)
                 throw error;
-            const code = error instanceof PortableCommandError || error instanceof SkillsCliError
-                ? error.code
-                : 'portableMaterializeFailed';
+            const capabilityError = error instanceof AwCapabilityUnsupportedError ? error : undefined;
+            const code = capabilityError?.code
+                ?? (error instanceof PortableCommandError || error instanceof SkillsCliError
+                    ? error.code
+                    : 'portableMaterializeFailed');
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 4,
+                receiptSchemaVersion: 5,
                 command: 'skill:materialize',
                 ok: false,
                 plugin: { id: selector },
@@ -968,7 +1616,15 @@ export function buildProgram(options = {}) {
                 configDigest: null,
                 materializationDigest: null,
                 outputDigest: null,
-                errors: [{ code, message: `${code}: portable Skill 导出未执行。` }],
+                errors: [{
+                        code,
+                        message: capabilityError?.message ?? `${code}: portable Skill 导出未执行。`,
+                        ...(capabilityError ? {
+                            plugin: capabilityError.plugin,
+                            missingCapabilities: capabilityError.missingCapabilities,
+                            availableCapabilities: capabilityError.availableCapabilities,
+                        } : {}),
+                    }],
             });
             commandExitState.exitCode = 1;
         }
@@ -980,7 +1636,7 @@ export function buildProgram(options = {}) {
         '',
         'During development, keep the current stable target when production content changes.',
         'Next, run `aw plugin validate`, `aw plugin test`, `aw plugin build`, and `aw catalog build`.',
-        'Publish only as an explicit later step; inspect `aw catalog publish --help` first.',
+        'Publish only as an explicit later step; inspect `aw catalog publish plan --help` first.',
         '',
     ].join('\n'))
         .argument('<plugin-name>', 'lowercase hyphen-case plugin name')
@@ -992,14 +1648,12 @@ export function buildProgram(options = {}) {
         .option('--skill-short-description <text>', 'initial Skill UI summary (25-64 characters)')
         .option('--skill-invocation <mode>', 'model | manual | claude-model-only (default: model)')
         .option('--version <semver>', 'initial stable plugin version (default: 0.1.0)')
-        .option('--min-version <semver>', 'compatibility.aw.minVersion')
-        .option('--catalog-min-version <semver>', 'target catalog compatibility minimum')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
         .option('--no-skills', 'create the plugin without a skills directory')
         .option('--with-mcp', 'add a minimal .mcp.json', false)
         .option('--with-apps', 'add a minimal .app.json', false)
         .option('--with-config-api', 'add AW config schema and helper', false)
-        .option('--with-lifecycle', 'add a lifecycle script sample', false);
+        .option('--with-pre-apply', 'add an idempotent Node preApply environment check', false);
     plugin
         .command('add-skill')
         .description('Add one static Skill scaffold to an existing plugin')
@@ -1007,7 +1661,7 @@ export function buildProgram(options = {}) {
         '',
         'During development, keep the current stable target when production content changes.',
         'Next, run `aw plugin validate`, `aw plugin test`, `aw plugin build`, and `aw catalog build`.',
-        'Publish only as an explicit later step; inspect `aw catalog publish --help` first.',
+        'Publish only as an explicit later step; inspect `aw catalog publish plan --help` first.',
         '',
     ].join('\n'))
         .argument('<plugin-name>', 'existing lowercase hyphen-case plugin name')
@@ -1015,28 +1669,39 @@ export function buildProgram(options = {}) {
         .option('--skill-description <text>', 'Skill goal and discovery description (required)')
         .option('--skill-short-description <text>', 'Skill UI summary (25-64 characters)')
         .option('--skill-invocation <mode>', 'model | manual | claude-model-only (default: model)')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)');
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)');
+    plugin
+        .command('remove')
+        .description('Remove one committed and unchanged canonical plugin source tree')
+        .argument('<plugin-name>', 'existing lowercase hyphen-case plugin name')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
+        .option('--yes', 'confirm plugin source deletion', false)
+        .option('--json', 'emit one schema 1 JSON object', false);
     plugin
         .command('validate')
         .description('Validate one source plugin directory')
         .argument('<plugin-directory>', 'source plugin directory')
-        .option('--catalog-min-version <semver>', 'validate compatibility against a target catalog')
         .option('--strict-agent-skills', 'allow only Agent Skills portable core frontmatter', false)
         .option('--claude-skill-profile <profile>', 'minimum | current (default: minimum)')
         .option('--version-base <git-ref>', 'production bundle comparison base (default: HEAD)')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from plugin directory)')
         .option('--json', 'emit one machine-readable JSON result', false);
     plugin
         .command('test')
         .description('Run deterministic Node tests declared by one source plugin')
         .argument('<plugin-directory>', 'source plugin directory')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from plugin directory)')
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (pluginDirectory, rawOptions) => {
         try {
+            const workspace = await resolveCatalogWorkspaceRoot({
+                cwd: path.resolve(cwd, pluginDirectory),
+                ...(rawOptions.workspaceRoot === undefined ? {} : { explicitRoot: path.resolve(cwd, rawOptions.workspaceRoot) }),
+                mode: 'existing',
+            });
             commandExitState.exitCode = await runPluginTestCommand({
-                workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
-                pluginDirectory,
+                ...workspace,
+                pluginDirectory: path.resolve(cwd, pluginDirectory),
                 json: rawOptions.json,
                 io,
             });
@@ -1053,15 +1718,20 @@ export function buildProgram(options = {}) {
         .command('build')
         .description('Build and inspect one source plugin bundle')
         .argument('<plugin-directory>', 'source plugin directory')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)')
-        .option('--out <path>', 'output path inside the workspace')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from plugin directory)')
+        .option('--out <path>', 'output path inside the Catalog Workspace')
         .option('--force', 'replace an existing generated output', false)
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (pluginDirectory, rawOptions) => {
         try {
+            const workspace = await resolveCatalogWorkspaceRoot({
+                cwd: path.resolve(cwd, pluginDirectory),
+                ...(rawOptions.workspaceRoot === undefined ? {} : { explicitRoot: path.resolve(cwd, rawOptions.workspaceRoot) }),
+                mode: 'existing',
+            });
             await runPluginBuildCommand({
-                workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
-                pluginDirectory,
+                ...workspace,
+                pluginDirectory: path.resolve(cwd, pluginDirectory),
                 out: rawOptions.out,
                 force: rawOptions.force,
                 json: rawOptions.json,
@@ -1080,18 +1750,10 @@ export function buildProgram(options = {}) {
         .command('status')
         .description('Show current plugin status or compare against an explicit Git base')
         .argument('[plugin-name]', 'one explicit plugin name')
-        .option('--all', 'check every current workspace plugin', false)
-        .option('--base <git-ref>', 'explicit Git comparison base')
-        .option('--json', 'emit one schema v3 JSON document', false)
-        .option('--workspace-root <path>', 'workspace root (default: current directory)');
-    plugin
-        .command('check-versions')
-        .description('Deprecated alias for plugin status')
-        .argument('[plugin-name]', 'one explicit plugin name')
-        .option('--all', 'check every plugin changed relative to the Git base', false)
+        .option('--all', 'check every current Catalog Workspace plugin', false)
         .option('--base <git-ref>', 'explicit Git comparison base')
         .option('--json', 'emit one schema v3 JSON document', false)
-        .option('--workspace-root <path>', 'workspace root (default: current directory)');
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)');
     skill
         .command('validate')
         .description('Validate one Agent Skill directory')
@@ -1104,19 +1766,25 @@ export function buildProgram(options = {}) {
         .description('Build and manage catalogs');
     catalog
         .command('init')
-        .description('Initialize a local AW plugin workspace')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)')
+        .description('Initialize a local AW Catalog Workspace')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor, then Git worktree root, then current directory)')
         .option('--owner-name <name>', 'catalog owner name')
         .option('--owner-url <url>', 'catalog owner URL')
         .option('--display-name <name>', 'catalog display name')
         .option('--catalog-version <version>', 'initial stable or x.y.z-beta.N catalog version (default: 0.1.0)')
-        .option('--force', 'repair a matching managed workspace scaffold', false)
+        .option('--force', 'repair a matching managed Catalog Workspace scaffold', false)
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (rawOptions) => {
         try {
+            const workspace = await resolveCatalogWorkspaceRoot({
+                cwd,
+                ...(rawOptions.workspaceRoot === undefined ? {} : { explicitRoot: rawOptions.workspaceRoot }),
+                mode: 'initialize',
+                env,
+            });
             await runCatalogInitCommand({
                 ...rawOptions,
-                workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
+                ...workspace,
                 io,
             });
         }
@@ -1130,15 +1798,22 @@ export function buildProgram(options = {}) {
     });
     catalog
         .command('version')
-        .description('Read or set the workspace catalog version')
+        .description('Read or set the Catalog version')
         .argument('[version]', 'stable or x.y.z-beta.N catalog version')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)')
+        .option('--bump <level>', 'bump the stable SemVer base: patch, minor, or major')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (version, rawOptions) => {
         try {
+            const workspace = await resolveCatalogWorkspaceRoot({
+                cwd,
+                ...(rawOptions.workspaceRoot === undefined ? {} : { explicitRoot: rawOptions.workspaceRoot }),
+                mode: 'existing',
+            });
             await runCatalogVersionCommand({
-                workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
+                ...workspace,
                 version,
+                bump: rawOptions.bump,
                 json: rawOptions.json,
                 io,
             });
@@ -1154,14 +1829,19 @@ export function buildProgram(options = {}) {
     catalog
         .command('build')
         .description('Build a deterministic development Catalog snapshot')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)')
-        .option('--out <path>', 'output path inside the workspace')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
+        .option('--out <path>', 'output path inside the Catalog Workspace')
         .option('--force', 'replace an existing generated output', false)
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (rawOptions) => {
         try {
+            const workspace = await resolveCatalogWorkspaceRoot({
+                cwd,
+                ...(rawOptions.workspaceRoot === undefined ? {} : { explicitRoot: rawOptions.workspaceRoot }),
+                mode: 'existing',
+            });
             await runCatalogBuildCommand({
-                workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
+                ...workspace,
                 out: rawOptions.out,
                 force: rawOptions.force,
                 json: rawOptions.json,
@@ -1178,7 +1858,7 @@ export function buildProgram(options = {}) {
     });
     catalog
         .command('validate')
-        .description('Validate a schema 4 Catalog snapshot')
+        .description('Validate a schema 7 Catalog snapshot')
         .argument('<snapshot-directory>', 'Catalog snapshot directory')
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (snapshotDirectory, rawOptions) => {
@@ -1198,53 +1878,204 @@ export function buildProgram(options = {}) {
         }
     });
     catalog
+        .command('status')
+        .description('Inspect static Catalog Workspace, snapshot, and Git facts')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
+        .option('--json', 'emit one machine-readable JSON status object', false)
+        .action(async (rawOptions) => {
+        const receipt = await getCatalogStatus({
+            cwd,
+            workspaceRoot: rawOptions.workspaceRoot,
+            env,
+        });
+        if (rawOptions.json)
+            writeJsonReceipt(io.stdout, receipt);
+        else
+            io.stdout(renderCatalogStatus(receipt));
+        commandExitState.exitCode = receipt.ok ? 0 : 1;
+    });
+    const catalogPublish = catalog
         .command('publish')
-        .description('Publish a versioned Catalog snapshot to a configured Git remote')
-        .option('--workspace-root <path>', 'workspace root (default: current directory)')
-        .option('--remote <name>', 'configured Git remote name (default: origin)')
+        .description('Plan or apply a versioned Catalog publication');
+    catalogPublish
+        .command('plan')
+        .description('Prepare and inspect the exact Catalog publication plan')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
+        .option('--remote <name>', 'Git remote (default: origin, otherwise sole remote; explicit if ambiguous)')
         .option('--branch <name>', 'dedicated Catalog branch (default: catalog)')
-        .option('-y, --yes', 'confirm publication without a prompt', false)
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (rawOptions) => {
         try {
-            const context = createActionContext('catalog:publish', {});
-            const result = await runCatalogPublishCommand({
-                workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
+            const result = await runCatalogPublishPlanCommand({
+                cwd,
+                workspaceRoot: rawOptions.workspaceRoot,
                 remote: rawOptions.remote,
                 branch: rawOptions.branch,
-                yes: rawOptions.yes,
-                json: rawOptions.json,
                 env,
-                interactive: context.interactive,
-                ...(context.prompt.confirm ? {
-                    confirm: async (message) => {
-                        const response = await context.prompt.confirm({ message, defaultValue: false });
-                        return !response.cancelled && response.value === true;
-                    },
-                } : {}),
                 io,
             });
-            if (!result)
-                return;
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, result);
             else {
-                writeLine(io.stdout, `Published Catalog ${result.catalogVersion} to ${result.remote} (${result.pushUrl}).`);
+                writeLine(io.stdout, `Workspace identity: ${result.workspaceIdentity}`);
+                writeLine(io.stdout, `Source HEAD: ${result.sourceHead}`);
+                writeLine(io.stdout, `Remote identity: ${result.descriptor.remote.identityDigest}`);
+                writeLine(io.stdout, `Remote: ${result.remote} (${result.remoteUrl})`);
                 writeLine(io.stdout, `Branch: refs/heads/${result.branch}`);
+                writeLine(io.stdout, `Parent: ${result.parent ?? '<root>'}`);
                 writeLine(io.stdout, `Tag: refs/tags/${result.tag}`);
-                writeLine(io.stdout, `Commit: ${result.commit}`);
-                writeLine(io.stdout, `Add it as a source: aw catalog source add <id> --git ${result.fetchUrl} --ref refs/heads/${result.branch}`);
+                writeLine(io.stdout, `Snapshot digest: ${result.snapshotDigest}`);
+                writeLine(io.stdout, `Expected commit: ${result.expectedCommit}`);
+                writeLine(io.stdout, `Plan digest: ${result.planDigest}`);
             }
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (rawOptions.json)
-                writeJsonReceipt(io.stdout, {
-                    command: 'catalog:publish',
-                    ok: false,
-                    errors: [{ message }],
-                });
-            writeLine(io.stderr, message);
+            const failure = catalogPublicationFailure({
+                error,
+                env,
+                sensitiveRoots: [
+                    cwd,
+                    ...(rawOptions.workspaceRoot ? [path.resolve(cwd, rawOptions.workspaceRoot)] : []),
+                ],
+            });
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, failure);
+            writeLine(io.stderr, failure.message);
+            commandExitState.exitCode = 1;
+        }
+    });
+    catalogPublish
+        .command('apply')
+        .description('Apply an authorized Catalog publication plan')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
+        .option('--remote <name>', 'Git remote (default: origin, otherwise sole remote; explicit if ambiguous)')
+        .option('--branch <name>', 'dedicated Catalog branch (default: catalog)')
+        .requiredOption('--expected-plan-digest <sha256>', 'exact plan digest returned by catalog publish plan')
+        .option('-y, --yes', 'confirm publication without a prompt', false)
+        .option('--json', 'emit one machine-readable JSON result', false)
+        .action(async (rawOptions) => {
+        try {
+            const context = createActionContext('catalog:publish:apply', {});
+            const result = await runCatalogPublishApplyCommand({
+                cwd,
+                workspaceRoot: rawOptions.workspaceRoot,
+                remote: rawOptions.remote,
+                branch: rawOptions.branch,
+                expectedPlanDigest: rawOptions.expectedPlanDigest,
+                yes: rawOptions.yes,
+                json: rawOptions.json,
+                env,
+                interactive: context.interactive,
+                ...(context.prompt.confirm ? {
+                    confirm: async (message) => {
+                        const response = await context.prompt.confirm({ message, defaultValue: false });
+                        return !response.cancelled && response.value === true;
+                    },
+                } : {}),
+                io,
+            });
+            if (!result)
+                return;
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, result);
+            else {
+                writeLine(io.stdout, `Published Catalog ${result.catalogVersion} to ${result.remote} (${result.pushUrl}).`);
+                writeLine(io.stdout, `Branch: refs/heads/${result.branch}`);
+                writeLine(io.stdout, `Tag: refs/tags/${result.tag}`);
+                writeLine(io.stdout, `Commit: ${result.commit}`);
+                writeLine(io.stdout, `Add it as a source: aw catalog source add <id> --git ${result.fetchUrl} --ref refs/heads/${result.branch}`);
+            }
+        }
+        catch (error) {
+            const failure = catalogPublicationFailure({
+                error,
+                env,
+                sensitiveRoots: [
+                    cwd,
+                    ...(rawOptions.workspaceRoot ? [path.resolve(cwd, rawOptions.workspaceRoot)] : []),
+                ],
+            });
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, failure);
+            writeLine(io.stderr, failure.message);
+            commandExitState.exitCode = 1;
+        }
+    });
+    const catalogDev = catalog
+        .command('dev')
+        .description('Manage the current Catalog Workspace development source');
+    catalogDev
+        .command('activate')
+        .option('--workspace-root <path>', 'explicit Catalog Workspace root')
+        .option('--source-id <id>', 'explicit managed source ID')
+        .option('--primary', 'make the development source primary', false)
+        .option('--force-build', 'rebuild a current snapshot', false)
+        .option('-y, --yes', 'confirm affected or unknown source references', false)
+        .requiredOption('--json', 'emit one schema 2 JSON receipt')
+        .action(async (rawOptions) => {
+        try {
+            const receipt = await activateCatalogDevSource({
+                cwd,
+                workspaceRoot: rawOptions.workspaceRoot,
+                sourceId: rawOptions.sourceId,
+                primary: rawOptions.primary,
+                forceBuild: rawOptions.forceBuild,
+                yes: rawOptions.yes,
+                cliVersion: resolveCliVersion(),
+                env,
+            });
+            writeJsonReceipt(io.stdout, receipt);
+            commandExitState.exitCode = receipt.ok ? 0 : 1;
+        }
+        catch (error) {
+            const failure = catalogDevSourceError(error);
+            writeJsonReceipt(io.stdout, createCatalogDevFailureReceipt({
+                command: 'activate', cwd, workspaceRoot: rawOptions.workspaceRoot,
+                sourceId: rawOptions.sourceId, ...failure,
+            }));
+            commandExitState.exitCode = 1;
+        }
+    });
+    catalogDev
+        .command('status')
+        .option('--workspace-root <path>', 'explicit Catalog Workspace root')
+        .requiredOption('--json', 'emit one schema 4 JSON receipt')
+        .action(async (rawOptions) => {
+        const receipt = await getCatalogDevSourceStatus({
+            cwd,
+            workspaceRoot: rawOptions.workspaceRoot,
+            cliVersion: resolveCliVersion(),
+            env,
+        });
+        writeJsonReceipt(io.stdout, receipt);
+        commandExitState.exitCode = receipt.ok ? 0 : 1;
+    });
+    catalogDev
+        .command('deactivate')
+        .option('--workspace-root <path>', 'explicit Catalog Workspace root')
+        .option('--source-id <id>', 'recover one managed source by exact ID')
+        .option('--replacement-primary <id>', 'replacement when the target source is primary')
+        .option('-y, --yes', 'confirm source impact or recovery by source ID', false)
+        .requiredOption('--json', 'emit one schema 4 JSON receipt')
+        .action(async (rawOptions) => {
+        try {
+            const receipt = await deactivateCatalogDevSource({
+                cwd,
+                workspaceRoot: rawOptions.workspaceRoot,
+                sourceId: rawOptions.sourceId,
+                replacementPrimary: rawOptions.replacementPrimary,
+                yes: rawOptions.yes,
+                env,
+            });
+            writeJsonReceipt(io.stdout, receipt);
+            commandExitState.exitCode = receipt.ok ? 0 : 1;
+        }
+        catch (error) {
+            const failure = catalogDevSourceError(error);
+            writeJsonReceipt(io.stdout, createCatalogDevFailureReceipt({
+                command: 'deactivate', cwd, workspaceRoot: rawOptions.workspaceRoot,
+                sourceId: rawOptions.sourceId, ...failure,
+            }));
             commandExitState.exitCode = 1;
         }
     });
@@ -1256,52 +2087,70 @@ export function buildProgram(options = {}) {
         const message = failure instanceof Error ? failure.message : String(error);
         if (json) {
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 4,
+                receiptSchemaVersion: 6,
                 command,
                 ok: false,
                 changed: false,
                 sourceId,
-                references: failure.inventory?.references ?? [],
+                primaryChange: failure.impact?.primaryChange ?? null,
+                references: failure.impact?.references ?? failure.inventory?.references ?? [],
                 errors: [{ code: failure.code ?? failure.name ?? 'catalogSourceMutationFailed', message }],
             });
         }
         writeLine(io.stderr, message);
         commandExitState.exitCode = 1;
     };
-    const writeConfigMutationFailure = (command, plugin, json, error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        const code = message.includes('legacyStateUnsupported')
-            ? 'legacyStateUnsupported'
-            : message.includes('sourceChanged')
-                ? 'sourceChanged'
-                : message.includes('sourceMissing')
-                    ? 'sourceMissing'
-                    : message.startsWith('Cannot resolve required catalog sources:')
-                        ? 'catalogSourceUnavailable'
-                        : message.split(':', 1)[0] || 'configMutationFailed';
-        if (json && !message.includes('Usage:')) {
+    const writeCatalogGenerationFailure = (command, sourceId, json, error) => {
+        const failure = sanitizeCatalogSourceError(error, env);
+        const message = redactString(failure.message);
+        if (json) {
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 4,
+                ...(command === 'catalog:source:sync'
+                    ? { catalogGenerationSchemaVersion: 1 }
+                    : { catalogGenerationStatusSchemaVersion: 2 }),
                 command,
                 ok: false,
-                overallState: 'failed',
-                ...(plugin ? { plugin } : {}),
-                errors: [{ code, message }],
+                ...(sourceId ? { sourceId } : {}),
+                ...(failure.impact ? { impact: failure.impact } : {}),
+                errors: [{ code: catalogGenerationErrorCode(error), message }],
             });
         }
         writeLine(io.stderr, message);
         commandExitState.exitCode = 1;
     };
-    const withResolvedConfigMutationPlugin = (context, selector, consume) => withAwHomeMutationLock({
-        env: context.env,
-        action: (awHomeMutationToken) => withResolvedCatalogPlugin({
-            selector,
-            cliVersion: resolveCliVersion(),
-            freshnessPolicy: 'requireRemote',
+    const writeConfigMutationFailure = (command, plugin, json, error) => {
+        const failure = configMutationFailure(error, env, cwd);
+        if (json) {
+            writeConfigMutationFailureReceipt(io.stdout, {
+                command,
+                ...(plugin ? { plugin } : {}),
+            }, failure);
+        }
+        const message = json
+            ? failure.message
+            : redactString(sanitizeCatalogSourceErrorMessage(error instanceof Error ? error.message : String(error), env, [cwd]));
+        writeLine(io.stderr, message);
+        commandExitState.exitCode = 1;
+    };
+    const withResolvedConfigMutationPlugin = (context, selector, consume) => (async () => {
+        const parsed = parsePluginId(selector);
+        return withAwHomeMutationLock({
             env: context.env,
-            consume: (resolution) => consume(resolution, awHomeMutationToken),
-        }),
-    });
+            action: async (awHomeMutationToken) => {
+                const catalogOperationContext = await resolveCatalogOperationContext({
+                    ...(parsed.sourceId ? { sourceIds: [parsed.sourceId] } : {}),
+                    env: context.env,
+                });
+                return withResolvedCatalogPlugin({
+                    selector,
+                    cliVersion: resolveCliVersion(),
+                    operationContext: catalogOperationContext,
+                    env: context.env,
+                    consume: (resolution) => consume(resolution, awHomeMutationToken, catalogOperationContext),
+                });
+            },
+        });
+    })();
     catalogSource
         .command('list')
         .option('-j, --json', 'print catalog sources as JSON', false)
@@ -1316,6 +2165,70 @@ export function buildProgram(options = {}) {
             writeLine(io.stdout, `${source.primary ? '*' : '-'} ${source.id} ${source.type} ${source.sourceIdentity}`);
         }
     });
+    catalogSource
+        .command('sync')
+        .argument('<id>')
+        .option('--check', 'fetch and validate without changing the Catalog store or Active state', false)
+        .option('--replace-damaged', 'replace a damaged Active entry with the current candidate', false)
+        .option('-y, --yes', 'confirm affected, unknown, or damaged Active replacement impact', false)
+        .option('-j, --json', 'print the source sync result as JSON', false)
+        .action(async (id, rawOptions) => {
+        try {
+            if (rawOptions.check && rawOptions.replaceDamaged) {
+                throw new Error('catalog source sync --check cannot use --replace-damaged.');
+            }
+            const result = await syncCatalogSourceCommand({
+                sourceId: id,
+                cliVersion: resolveCliVersion(),
+                cwd,
+                check: rawOptions.check === true,
+                impactConfirmed: rawOptions.yes === true,
+                replaceDamaged: rawOptions.replaceDamaged === true,
+                env,
+            });
+            if (rawOptions.json) {
+                writeJsonReceipt(io.stdout, {
+                    ...result,
+                    command: 'catalog:source:sync',
+                    ok: true,
+                });
+            }
+            else {
+                writeLine(io.stdout, rawOptions.check
+                    ? `Catalog source ${id} is valid.`
+                    : `Catalog source ${id}: ${result.outcome}.`);
+            }
+        }
+        catch (error) {
+            writeCatalogGenerationFailure('catalog:source:sync', id, rawOptions.json === true, error);
+        }
+    });
+    catalogSource
+        .command('status')
+        .argument('[id]')
+        .option('-j, --json', 'print offline Catalog source status schema 2 as JSON', false)
+        .action(async (id, rawOptions) => {
+        try {
+            const result = await catalogSourceStatusCommand({ sourceId: id, env });
+            if (rawOptions.json) {
+                writeJsonReceipt(io.stdout, result);
+            }
+            else {
+                for (const source of result.sources) {
+                    const active = source.active
+                        ? `Active ${source.active.snapshotDigest}`
+                        : 'no Active';
+                    const readiness = source.compatibility?.state === 'unsupported'
+                        ? `incompatible (required: ${source.compatibility.requiredCapabilities.join(', ')}; missing: ${source.compatibility.missingCapabilities.join(', ')})`
+                        : source.activeReady ? 'ready' : 'not ready';
+                    writeLine(io.stdout, `${source.sourceId}: ${active}, ${readiness}`);
+                }
+            }
+        }
+        catch (error) {
+            writeCatalogGenerationFailure('catalog:source:status', id, rawOptions.json === true, error);
+        }
+    });
     catalogSource
         .command('add')
         .argument('<id>')
@@ -1324,7 +2237,9 @@ export function buildProgram(options = {}) {
         .addOption(new Option('--ref <ref>', 'use an explicit Git ref'))
         .addOption(new Option('--default-ref', 'select the Git ref from the CLI release channel'))
         .option('--subdir <path>', 'use a catalog snapshot below the Git repository root')
+        .option('--no-auto-check', 'disable automatic update checks for this source')
         .option('--primary', 'make this source primary', false)
+        .option('-y, --yes', 'confirm affected or unknown primary source references', false)
         .option('-j, --json', 'print mutation receipt as JSON', false)
         .action(async (id, rawOptions) => {
         try {
@@ -1335,7 +2250,7 @@ export function buildProgram(options = {}) {
                 throw new Error('Git catalog source add requires exactly one of `--ref` or `--default-ref`.');
             }
             if (rawOptions.path !== undefined && (rawOptions.ref !== undefined || rawOptions.defaultRef === true || rawOptions.subdir !== undefined)) {
-                throw new Error('Path catalog source add only accepts `--path` and `--primary`.');
+                throw new Error('Path catalog source add only accepts `--path`, `--primary`, `--no-auto-check`, and `--yes`.');
             }
             const source = rawOptions.git !== undefined
                 ? {
@@ -1345,18 +2260,32 @@ export function buildProgram(options = {}) {
                     url: rawOptions.git,
                     refPolicy: explicitRefPolicy(rawOptions.ref, rawOptions.defaultRef === true),
                     ...(rawOptions.subdir ? { subdir: rawOptions.subdir } : {}),
+                    ...(rawOptions.autoCheck === false ? { autoCheck: false } : {}),
                 }
                 : {
                     id,
                     type: 'path',
                     primary: rawOptions.primary === true,
                     path: rawOptions.path,
+                    ...(rawOptions.autoCheck === false ? { autoCheck: false } : {}),
                 };
+            const preview = source.primary
+                ? await preflightCatalogSourceMutation({
+                    request: { action: 'add', source }, cwd, env,
+                })
+                : undefined;
             const receipt = await addCatalogSourceCommand({
                 source,
                 cliVersion: resolveCliVersion(),
                 cwd,
                 env,
+                ...(preview ? {
+                    expectedConfigDigest: preview.configDigest,
+                    expectedProposedConfigDigest: preview.proposedConfigDigest,
+                    expectedImpactDigest: preview.impactDigest,
+                } : {}),
+                requireImpactConfirmation: true,
+                confirmImpact: rawOptions.yes === true,
             });
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, receipt);
@@ -1378,6 +2307,9 @@ export function buildProgram(options = {}) {
         .addOption(new Option('--default-ref', 'select the Git ref from the CLI release channel'))
         .addOption(new Option('--subdir <path>', 'update the Git catalog subdirectory'))
         .addOption(new Option('--no-subdir', 'remove the Git catalog subdirectory'))
+        .addOption(new Option('--auto-check', 'enable automatic update checks for this source'))
+        .addOption(new Option('--no-auto-check', 'disable automatic update checks for this source'))
+        .option('-y, --yes', 'confirm a source identity change', false)
         .option('-j, --json', 'print mutation receipt as JSON', false)
         .action(async (id, rawOptions) => {
         try {
@@ -1391,15 +2323,25 @@ export function buildProgram(options = {}) {
                 || rawOptions.path !== undefined
                 || rawOptions.ref !== undefined
                 || rawOptions.defaultRef === true
-                || rawOptions.subdir !== undefined;
+                || rawOptions.subdir !== undefined
+                || rawOptions.autoCheck !== undefined;
             if (!hasUpdate)
                 throw new Error('catalog source update requires at least one update option.');
             if (rawOptions.path !== undefined && (rawOptions.ref !== undefined || rawOptions.defaultRef === true || rawOptions.subdir !== undefined))
-                throw new Error('Path catalog source update only accepts `--path`.');
+                throw new Error('Path catalog source update only accepts `--path` and auto-check options.');
+            const hasGitUpdate = rawOptions.git !== undefined
+                || rawOptions.ref !== undefined
+                || rawOptions.defaultRef === true
+                || rawOptions.subdir !== undefined;
             const update = rawOptions.path !== undefined
-                ? { type: 'path', path: rawOptions.path }
-                : {
+                ? {
+                    type: 'path',
+                    path: rawOptions.path,
+                    ...(rawOptions.autoCheck !== undefined ? { autoCheck: rawOptions.autoCheck } : {}),
+                }
+                : hasGitUpdate ? {
                     type: 'git',
+                    ...(rawOptions.autoCheck !== undefined ? { autoCheck: rawOptions.autoCheck } : {}),
                     ...(rawOptions.git !== undefined ? { url: rawOptions.git } : {}),
                     ...(rawOptions.ref !== undefined || rawOptions.defaultRef === true
                         ? { refPolicy: explicitRefPolicy(rawOptions.ref, rawOptions.defaultRef === true) }
@@ -1407,13 +2349,22 @@ export function buildProgram(options = {}) {
                     ...(rawOptions.subdir !== undefined
                         ? { subdir: rawOptions.subdir === false ? null : rawOptions.subdir }
                         : {}),
-                };
+                }
+                    : { autoCheck: rawOptions.autoCheck };
+            const preview = await preflightCatalogSourceMutation({
+                request: { action: 'update', sourceId: id, update }, cwd, env,
+            });
             const receipt = await updateCatalogSourceCommand({
                 sourceId: id,
                 update,
                 cliVersion: resolveCliVersion(),
                 cwd,
                 env,
+                expectedConfigDigest: preview.configDigest,
+                expectedProposedConfigDigest: preview.proposedConfigDigest,
+                expectedImpactDigest: preview.impactDigest,
+                requireIdentityChangeConfirmation: true,
+                confirmIdentityChange: rawOptions.yes === true,
             });
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, receipt);
@@ -1429,10 +2380,17 @@ export function buildProgram(options = {}) {
     catalogSource
         .command('set-primary')
         .argument('<id>')
+        .option('-y, --yes', 'confirm affected or unknown primary source references', false)
         .option('-j, --json', 'print mutation receipt as JSON', false)
         .action(async (id, rawOptions) => {
         try {
-            const receipt = await setPrimaryCatalogSourceCommand({ sourceId: id, cwd, env });
+            const receipt = await setPrimaryCatalogSourceCommand({
+                sourceId: id,
+                cwd,
+                env,
+                requireImpactConfirmation: true,
+                confirmImpact: rawOptions.yes === true,
+            });
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, receipt);
             else
@@ -1445,10 +2403,17 @@ export function buildProgram(options = {}) {
     catalogSource
         .command('remove')
         .argument('<id>')
+        .option('-y, --yes', 'confirm affected or unknown source references', false)
         .option('-j, --json', 'print mutation receipt as JSON', false)
         .action(async (id, rawOptions) => {
         try {
-            const receipt = await removeCatalogSourceCommand({ sourceId: id, cwd, env });
+            const receipt = await removeCatalogSourceCommand({
+                sourceId: id,
+                cwd,
+                env,
+                requireImpactConfirmation: true,
+                confirmImpact: rawOptions.yes === true,
+            });
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, receipt);
             else
@@ -1458,9 +2423,102 @@ export function buildProgram(options = {}) {
             await writeCatalogSourceFailure('catalog:source:remove', id, rawOptions.json === true, error);
         }
     });
+    const catalogStore = catalog
+        .command('store')
+        .description('Inspect or prune the immutable Catalog store');
+    catalogStore
+        .command('status')
+        .option('-j, --json', 'print Catalog store status as JSON', false)
+        .action(async (rawOptions) => {
+        try {
+            const result = await catalogStoreStatus({ env });
+            if (rawOptions.json) {
+                writeJsonReceipt(io.stdout, result);
+            }
+            else if (result.entries.length === 0) {
+                writeLine(io.stdout, 'Catalog store is empty.');
+            }
+            else {
+                for (const entry of result.entries) {
+                    const bytes = entry.reclaimableBytes === null ? 'unknown bytes' : `${entry.reclaimableBytes} bytes`;
+                    writeLine(io.stdout, `${entry.storeKey}: ${entry.category}, ${entry.status}, ${entry.reason}, ${bytes}`);
+                }
+                writeLine(io.stdout, `Reclaimable: ${result.totals.reclaimableEntries} item(s).`);
+                if (result.errors.length > 0) {
+                    writeLine(io.stderr, `${result.errors.length} item(s) could not be fully inspected and were retained.`);
+                }
+            }
+            commandExitState.exitCode = result.ok ? 0 : 1;
+        }
+        catch (error) {
+            const failure = sanitizeCatalogSourceError(error, env);
+            const message = redactString(failure.message);
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, {
+                    catalogStoreSchemaVersion: 2,
+                    command: 'catalog:store:status',
+                    ok: false,
+                    entries: [],
+                    errors: [{ code: catalogStoreErrorCode(error), message }],
+                });
+            writeLine(io.stderr, message);
+            commandExitState.exitCode = 1;
+        }
+    });
+    catalogStore
+        .command('prune')
+        .option('--dry-run', 'inspect reclaimable items without deleting them', false)
+        .option('-y, --yes', 'delete items classified as safely reclaimable', false)
+        .option('-j, --json', 'print the prune receipt as JSON', false)
+        .action(async (rawOptions) => {
+        const dryRun = rawOptions.yes !== true;
+        try {
+            if (rawOptions.dryRun === true && rawOptions.yes === true) {
+                throw Object.assign(new Error('catalog store prune cannot combine `--dry-run` and `--yes`.'), {
+                    code: 'invalidArguments',
+                });
+            }
+            const result = await catalogStorePrune({ dryRun, env });
+            if (rawOptions.json) {
+                writeJsonReceipt(io.stdout, result);
+            }
+            else if (dryRun) {
+                writeLine(io.stdout, `Dry run: ${result.entries.filter((entry) => entry.status === 'reclaimable').length} item(s) are reclaimable.`);
+                writeLine(io.stdout, 'Run `aw catalog store prune --yes` to delete them.');
+                if (result.errors.length > 0)
+                    writeLine(io.stderr, `${result.errors.length} item(s) could not be fully inspected and were retained.`);
+            }
+            else {
+                writeLine(io.stdout, `Deleted ${result.deleted.length} Catalog store item(s) (${result.deletedBytes} bytes).`);
+                if (result.errors.length > 0)
+                    writeLine(io.stderr, `${result.errors.length} item(s) could not be fully inspected or deleted and were retained.`);
+            }
+            commandExitState.exitCode = result.ok ? 0 : 1;
+        }
+        catch (error) {
+            const failure = sanitizeCatalogSourceError(error, env);
+            const message = redactString(failure.message);
+            const code = catalogStoreErrorCode(error);
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, {
+                    catalogStoreSchemaVersion: 2,
+                    command: 'catalog:store:prune',
+                    ok: false,
+                    overallState: 'failed',
+                    dryRun,
+                    entries: [],
+                    deleted: [],
+                    retained: [],
+                    errors: [{ code, message }],
+                    reclaimableBytes: null,
+                    deletedBytes: 0,
+                });
+            writeLine(io.stderr, message);
+            commandExitState.exitCode = 1;
+        }
+    });
     program
         .command('init')
-        .option('-f, --force', 're-fetch and rebuild the current catalog cache entry', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -1468,8 +2526,6 @@ export function buildProgram(options = {}) {
         .action(async (rawOptions) => {
         const context = createActionContext('init', rawOptions);
         const result = await runActionWithContext(context, () => initCommand({
-            force: rawOptions.force,
-            cliVersion: resolveCliVersion(),
             env: context.env,
         }));
         if (rawOptions.json) {
@@ -1480,7 +2536,6 @@ export function buildProgram(options = {}) {
                 writeLine(io.stdout, line);
             }
         }
-        writeWarnings(io.stderr, result.warnings, { actionableOnly: true });
         for (const source of result.sources) {
             if (!source.ok && source.error)
                 writeLine(io.stderr, `${source.id}: ${source.error}`);
@@ -1488,53 +2543,79 @@ export function buildProgram(options = {}) {
         commandExitState.exitCode = result.ok ? 0 : 1;
     });
     program
-        .command('install')
+        .command('sync')
+        .description('Reconcile actual state from existing desired intent')
         .argument('[plugins...]')
-        .option('-s, --scope <scope>', 'project or user')
-        .option('-p, --platform <platform>', 'codex | claude | both')
-        .option('--script-timeout <ms>', 'override plugin lifecycle script timeout in milliseconds')
-        .option('-j, --json', 'print receipt as JSON', false)
+        .requiredOption('-s, --scope <scope>', 'project or user')
+        .requiredOption('-p, --platform <platform>', 'codex, claude, or both')
+        .option('-a, --all', 'reconcile every desired plugin in the selected scope', false)
+        .option('--refresh', 'refresh only Catalog sources required by selected intent roots', false)
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('-y, --yes', 'authorize preApply and shared native replacement or forced repair', false)
+        .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
+        .option('-j, --json', 'print sync receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
         .option('--log-file <path>', 'write debug diagnostics to the specified file')
         .action(async (plugins, rawOptions) => {
-        const context = createActionContext('install', rawOptions);
-        const outcome = await runActionWithContext(context, () => runWriteCommandAction('install', plugins ?? [], rawOptions, context));
-        if (outcome.cancelled)
-            return;
-        const receipt = outcome.result;
+        const context = createActionContext('sync', rawOptions);
+        const normalized = normalizeWriteRequest(() => normalizeInstallCommandOptions({
+            cwd: context.cwd,
+            scope: rawOptions.scope,
+            platform: rawOptions.platform,
+            scriptTimeout: rawOptions.scriptTimeout,
+            allowManagedCodexInstall: rawOptions.allowManagedCodexInstall,
+        }));
+        const syncPlatform = normalized.platform;
+        const result = await runActionWithContext(context, () => syncCommand(plugins ?? [], {
+            cwd: context.cwd,
+            env: context.env,
+            platform: syncPlatform,
+            scope: normalized.scope,
+            all: rawOptions.all,
+            refresh: rawOptions.refresh,
+            cliVersion: resolveCliVersion(),
+            yes: rawOptions.yes,
+            json: rawOptions.json,
+            interactive: context.interactive && context.isTty && !context.isCi,
+            prompt: context.prompt,
+            allowManagedCodexInstall: rawOptions.allowManagedCodexInstall,
+            scriptTimeoutMs: normalized.scriptTimeoutMs,
+        }, context));
         if (rawOptions.json) {
-            writeJsonReceipt(io.stdout, buildRebuildReceiptJson('install', receipt));
+            writeJsonReceipt(io.stdout, buildRebuildReceiptJson('sync', result));
         }
         else {
-            for (const line of renderRebuildReceipt('install', receipt)) {
+            for (const line of renderRebuildReceipt('sync', result))
                 writeLine(io.stdout, line);
-            }
         }
-        writeWarnings(io.stderr, receipt.warnings, { actionableOnly: true });
-        commandExitState.exitCode = resolveCommandReceiptExitCode(receipt);
+        writeWarnings(io.stderr, result.warnings, { actionableOnly: true });
+        commandExitState.exitCode = resolveCommandReceiptExitCode(result);
     });
     program
-        .command('uninstall')
+        .command('install')
         .argument('[plugins...]')
         .option('-s, --scope <scope>', 'project or user')
         .option('-p, --platform <platform>', 'codex | claude | both')
-        .option('--script-timeout <ms>', 'override plugin lifecycle script timeout in milliseconds')
+        .option('--dependency-scope <pluginId[#platform]=scope>', 'place one dependency at project or user scope; repeat for more dependencies', (value, previous) => [...previous, value], [])
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
+        .option('-y, --yes', 'authorize preApply and shared Codex native replacement', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
         .option('--log-file <path>', 'write debug diagnostics to the specified file')
         .action(async (plugins, rawOptions) => {
-        const context = createActionContext('uninstall', rawOptions);
-        const outcome = await runActionWithContext(context, () => runWriteCommandAction('uninstall', plugins ?? [], rawOptions, context));
+        const context = createActionContext('install', rawOptions);
+        const outcome = await runActionWithContext(context, () => runWriteCommandAction('install', plugins ?? [], rawOptions, context));
         if (outcome.cancelled)
             return;
         const receipt = outcome.result;
         if (rawOptions.json) {
-            writeJsonReceipt(io.stdout, buildRebuildReceiptJson('uninstall', receipt));
+            writeJsonReceipt(io.stdout, buildRebuildReceiptJson('install', receipt));
         }
         else {
-            for (const line of renderRebuildReceipt('uninstall', receipt)) {
+            for (const line of renderRebuildReceipt('install', receipt)) {
                 writeLine(io.stdout, line);
             }
         }
@@ -1542,27 +2623,26 @@ export function buildProgram(options = {}) {
         commandExitState.exitCode = resolveCommandReceiptExitCode(receipt);
     });
     program
-        .command('upgrade')
+        .command('uninstall')
         .argument('[plugins...]')
-        .option('-a, --all', 'upgrade all plugins', false)
         .option('-s, --scope <scope>', 'project or user')
         .option('-p, --platform <platform>', 'codex | claude | both')
-        .option('--script-timeout <ms>', 'override plugin lifecycle script timeout in milliseconds')
+        .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
         .option('--log-file <path>', 'write debug diagnostics to the specified file')
         .action(async (plugins, rawOptions) => {
-        const context = createActionContext('upgrade', rawOptions);
-        const outcome = await runActionWithContext(context, () => runWriteCommandAction('upgrade', plugins ?? [], rawOptions, context));
+        const context = createActionContext('uninstall', rawOptions);
+        const outcome = await runActionWithContext(context, () => runWriteCommandAction('uninstall', plugins ?? [], rawOptions, context));
         if (outcome.cancelled)
             return;
         const receipt = outcome.result;
         if (rawOptions.json) {
-            writeJsonReceipt(io.stdout, buildRebuildReceiptJson('upgrade', receipt));
+            writeJsonReceipt(io.stdout, buildRebuildReceiptJson('uninstall', receipt));
         }
         else {
-            for (const line of renderRebuildReceipt('upgrade', receipt)) {
+            for (const line of renderRebuildReceipt('uninstall', receipt)) {
                 writeLine(io.stdout, line);
             }
         }
@@ -1575,7 +2655,8 @@ export function buildProgram(options = {}) {
         .option('-s, --scope <scope>', 'project or user')
         .option('-p, --platform <platform>', 'codex | claude | both')
         .option('-j, --json', 'print cleanup result as JSON', false)
-        .option('--force', 'remove exclusively owned plugin output without dependency protection', false)
+        .option('--force', 'use exact shallow evidence for exclusively owned damaged output; preserve foreign and shared content', false)
+        .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
         .option('--log-file <path>', 'write debug diagnostics to the specified file')
@@ -1594,14 +2675,16 @@ export function buildProgram(options = {}) {
             }
         }
         writeWarnings(io.stderr, result.warnings, { actionableOnly: true });
-        commandExitState.exitCode = result.overallState === 'failed' ? 1 : 0;
+        commandExitState.exitCode = resolveCommandReceiptExitCode(result);
     });
     program
         .command('reinstall')
         .argument('[plugins...]')
         .option('-s, --scope <scope>', 'project or user')
         .option('-p, --platform <platform>', 'codex | claude | both')
-        .option('--script-timeout <ms>', 'override plugin lifecycle script timeout in milliseconds')
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
+        .option('-y, --yes', 'authorize preApply and shared Codex native replacement or forced reinstall', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -1631,7 +2714,6 @@ export function buildProgram(options = {}) {
         .command('list')
         .argument('[plugin]')
         .option('-s, --scope <scope>', 'read only project or user config')
-        .option('--local', 'read only the current project local override layer', false)
         .option('-j, --json', 'print config as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -1639,9 +2721,7 @@ export function buildProgram(options = {}) {
         .action(async (pluginName, rawOptions) => {
         const context = createActionContext('config:list', rawOptions);
         const outcome = await runActionWithContext(context, async () => {
-            resolveConfigProjectLayer(rawOptions);
-            if (!rawOptions.local)
-                resolveConfigReadResolution(rawOptions.scope);
+            resolveConfigReadResolution(rawOptions.scope);
             const execute = async (selectedPlugin) => resolveMultiSourceConfigRead({
                 selector: selectedPlugin,
                 rawOptions,
@@ -1666,7 +2746,6 @@ export function buildProgram(options = {}) {
                     command: 'list',
                     plugin: selection.plugins[0],
                     scope: rawOptions.scope,
-                    projectLayer: rawOptions.local ? 'local' : 'shared',
                 })),
                 execute: (selection) => execute(selection.plugins[0]),
             });
@@ -1688,8 +2767,7 @@ export function buildProgram(options = {}) {
                 pluginId: resolved.pluginId,
                 sourceId: resolved.sourceId,
                 sourceIdentity: resolved.sourceIdentity,
-                scope: rawOptions.local ? 'project' : rawOptions.scope ?? 'effective',
-                projectLayer: rawOptions.local ? 'local' : 'shared',
+                scope: rawOptions.scope ?? 'effective',
                 ...(resolved.result.schema ? { schema: resolved.result.schema } : {}),
                 fields: resolved.result.fields,
             });
@@ -1703,7 +2781,6 @@ export function buildProgram(options = {}) {
         .argument('[plugin]')
         .argument('[key]')
         .option('-s, --scope <scope>', 'read only project or user config')
-        .option('--local', 'read only the current project local override layer', false)
         .option('-j, --json', 'print config as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -1711,9 +2788,7 @@ export function buildProgram(options = {}) {
         .action(async (pluginName, key, rawOptions) => {
         const context = createActionContext('config:get', rawOptions);
         const outcome = await runActionWithContext(context, async () => {
-            resolveConfigProjectLayer(rawOptions);
-            if (!rawOptions.local)
-                resolveConfigReadResolution(rawOptions.scope);
+            resolveConfigReadResolution(rawOptions.scope);
             const execute = async (selectedPlugin) => resolveMultiSourceConfigRead({
                 selector: selectedPlugin,
                 ...(key === undefined ? {} : { key }),
@@ -1740,7 +2815,6 @@ export function buildProgram(options = {}) {
                     plugin: selection.plugins[0],
                     key,
                     scope: rawOptions.scope,
-                    projectLayer: rawOptions.local ? 'local' : 'shared',
                 })),
                 execute: (selection) => execute(selection.plugins[0]),
             });
@@ -1763,8 +2837,7 @@ export function buildProgram(options = {}) {
                 sourceId: resolved.sourceId,
                 sourceIdentity: resolved.sourceIdentity,
                 key,
-                scope: rawOptions.local ? 'project' : rawOptions.scope ?? 'effective',
-                projectLayer: rawOptions.local ? 'local' : 'shared',
+                scope: rawOptions.scope ?? 'effective',
                 ...(resolved.result.schema ? { schema: resolved.result.schema } : {}),
                 fields: resolved.result.fields,
             });
@@ -1776,47 +2849,119 @@ export function buildProgram(options = {}) {
     config
         .command('set')
         .argument('[plugin]')
-        .argument('[key]')
-        .argument('[value]')
+        .argument('[field]')
         .option('-s, --scope <scope>', 'project or user')
-        .option('--local', 'write only the current project local override layer', false)
-        .option('--value-json', 'parse value as a JSON literal', false)
+        .option('--value-json <json>', 'set the field to an exact JSON value')
+        .option('--value-stdin', 'read the exact string value from stdin until EOF', false)
+        .option('--preset <id>', 'set the field to the current manifest preset value')
+        .option('--apply', 'apply the saved config to visible desired placements', false)
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('-y, --yes', 'confirm preApply and shared Codex native config apply', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
         .option('--log-file <path>', 'write debug diagnostics to the specified file')
-        .action(async (pluginName, key, rawValue, rawOptions) => {
+        .action(async (pluginName, key, rawOptions) => {
+        if (!pluginName || !key)
+            throw new Error(configCommandUsage('set'));
         const context = createActionContext('config:set', rawOptions);
         let outcome;
         try {
             outcome = await runActionWithContext(context, async () => {
                 const scope = resolveConfigWriteScope(rawOptions.scope);
-                const projectLayer = resolveConfigProjectLayer(rawOptions);
-                const execute = async (selectedPlugin, selectedKey, inputValue) => withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken) => {
-                    if (!plugin.manifest.config?.schema) {
-                        throw new Error(`configSchemaUnavailable: Plugin "${selectedPlugin}" does not declare an AW config schema.`);
+                const scriptTimeoutMs = resolveScriptTimeoutMs(rawOptions);
+                const explicitValueCount = [
+                    rawOptions.valueJson !== undefined,
+                    rawOptions.valueStdin === true,
+                    rawOptions.preset !== undefined,
+                ].filter(Boolean).length;
+                if (explicitValueCount > 1
+                    || (explicitValueCount === 0
+                        && !(context.interactive && context.isTty && !context.isCi && rawOptions.json !== true))) {
+                    throw new Error('Use exactly one of --value-json <json>, --value-stdin, or --preset <id>.');
+                }
+                return withResolvedConfigMutationPlugin(context, pluginName, async ({ pluginId, source, plugin }, awHomeMutationToken, catalogOperationContext) => {
+                    if (!plugin.manifest.config?.fields) {
+                        throw new Error(`configSchemaUnavailable: Plugin "${pluginName}" does not declare an AW config schema.`);
                     }
-                    if (!plugin.manifest.config.schema[selectedKey]) {
-                        throw new Error(`Unknown config key "${selectedKey}".`);
+                    const field = plugin.manifest.config.fields[key];
+                    if (!field) {
+                        throw new Error(`Unknown config key "${key}".`);
+                    }
+                    const sensitive = field.sensitive === true;
+                    if (sensitive && scope !== 'user') {
+                        const error = new Error('sensitiveProjectConfigUnsupported: Sensitive config can only be set in user scope.');
+                        error.code = 'sensitiveProjectConfigUnsupported';
+                        throw error;
+                    }
+                    if (sensitive && (rawOptions.valueJson !== undefined || rawOptions.preset !== undefined)) {
+                        const error = new Error('sensitiveConfigInputUnsupported: Sensitive config cannot use --value-json or --preset.');
+                        error.code = 'sensitiveConfigInputUnsupported';
+                        throw error;
+                    }
+                    if (!sensitive && explicitValueCount !== 1) {
+                        throw new Error('Use exactly one of --value-json <json>, --value-stdin, or --preset <id>.');
+                    }
+                    let inputValue;
+                    if (rawOptions.valueStdin === true) {
+                        inputValue = await readUtf8Stdin(context.stdin);
+                    }
+                    else if (sensitive) {
+                        if (!(context.interactive && context.isTty && !context.isCi && rawOptions.json !== true)
+                            || !context.prompt.password) {
+                            const error = new Error('sensitiveConfigStdinRequired: Use --value-stdin for sensitive config outside an interactive terminal.');
+                            error.code = 'sensitiveConfigStdinRequired';
+                            throw error;
+                        }
+                        const response = await context.prompt.password({
+                            message: `输入 ${field.title ?? key}`,
+                            mask: true,
+                        });
+                        if (response.cancelled || response.action !== 'select' || response.value === undefined) {
+                            const error = new Error('sensitiveConfigInputCancelled: Sensitive config input was cancelled.');
+                            error.code = 'sensitiveConfigInputCancelled';
+                            throw error;
+                        }
+                        inputValue = response.value;
+                    }
+                    else if (rawOptions.valueJson !== undefined) {
+                        try {
+                            inputValue = JSON.parse(rawOptions.valueJson);
+                        }
+                        catch {
+                            throw new Error('--value-json must contain valid JSON.');
+                        }
+                    }
+                    else {
+                        const preset = field.choices?.presets.find((entry) => entry.id === rawOptions.preset);
+                        if (!preset)
+                            throw new Error(`Unknown preset "${rawOptions.preset}" for config key "${key}".`);
+                        inputValue = structuredClone(preset.value);
                     }
                     const writeReceipt = await applyPluginConfigWrite({
                         plugin,
                         pluginName: plugin.manifest.name,
                         scope,
-                        projectLayer,
                         cwd: context.cwd,
                         env: context.env,
                         nativeCliRunner: context.nativeCliRunner,
-                        rebuildRuntime: { ...context, awHomeMutationToken },
+                        rebuildRuntime: {
+                            ...context,
+                            awHomeMutationToken,
+                            catalogOperationContext,
+                            expectedGenerationSetDigest: catalogOperationContext.generationSetDigest,
+                            ...(scriptTimeoutMs === undefined ? {} : { scriptTimeoutMs }),
+                        },
                         awHomeMutationToken,
                         request: {
-                            updates: { [selectedKey]: inputValue },
+                            updates: { [key]: inputValue },
                         },
+                        apply: rawOptions.apply === true,
+                        sharedNativeApplyConfirmed: rawOptions.yes === true,
+                        preApplyConfirmed: rawOptions.yes === true,
                     });
-                    return {
+                    return buildConfigMutationReceipt('config:set', {
                         ok: writeReceipt.overallState === 'succeeded',
-                        receiptSchemaVersion: 4,
-                        command: 'config:set',
                         ...writeReceipt,
                         plugin: plugin.manifest.name,
                         pluginName: plugin.manifest.name,
@@ -1824,104 +2969,39 @@ export function buildProgram(options = {}) {
                         sourceId: source.sourceId,
                         sourceIdentity: source.sourceIdentity,
                         affectedFields: [{
-                                key: selectedKey,
-                                title: plugin?.manifest.config?.schema?.[selectedKey]?.title ?? selectedKey,
+                                key,
+                                title: field.title ?? key,
                                 kind: 'manifest',
                                 reserved: false,
                                 action: 'set',
                                 scope,
-                                ...(scope === 'project' ? { projectLayer } : {}),
                             }],
-                    };
-                });
-                if (pluginName && key && rawValue !== undefined) {
-                    const inputValue = parseConfigValue(rawValue, rawOptions.valueJson === true);
-                    return {
-                        cancelled: false,
-                        key,
-                        value: await execute(pluginName, key, inputValue),
-                    };
-                }
-                if (!isWizardAvailable(context, rawOptions))
-                    throw new Error(configCommandUsage('set'));
-                const candidates = await loadWizardCandidates(context, {});
-                if (pluginName) {
-                    const candidate = candidates.find((entry) => entry.pluginName === pluginName);
-                    if (!candidate)
-                        throw new Error(`Unknown plugin "${pluginName}".`);
-                    if (!hasConfigSchemaKeys(candidate)) {
-                        throw new Error(`configSchemaUnavailable: Plugin "${pluginName}" does not declare an AW config schema.`);
-                    }
-                    if (key && !candidate.configSchema?.[key])
-                        throw new Error(`Unknown config key "${key}".`);
-                }
-                const configurableCandidates = candidates.filter(hasConfigSchemaKeys);
-                if (configurableCandidates.length === 0) {
-                    throw new Error('configSchemaUnavailable: No current plugin declares an AW config schema.');
-                }
-                const result = await runCommandWizard(context, {
-                    command: 'config:set',
-                    candidates: configurableCandidates,
-                    initial: {
-                        plugins: pluginName ? [pluginName] : [],
-                        key,
-                        ...(rawValue !== undefined ? { value: rawValue } : {}),
-                        scope,
-                        projectLayer,
-                    },
-                    pluginMode: pluginName ? 'none' : 'single',
-                    valueJson: rawOptions.valueJson === true,
-                    promptForKey: key === undefined,
-                    promptForValue: rawValue === undefined,
-                    ...equivalentConfigCommandProjection((selection) => configSetEquivalentOptions(selection, candidates, rawOptions)),
-                    commandIsTemplate: (selection) => candidates.find((entry) => entry.pluginName === selection.plugins[0])?.configSchema?.[selection.key ?? ''] !== undefined
-                        && configFieldPlaceholder(candidates.find((entry) => entry.pluginName === selection.plugins[0])?.configSchema?.[selection.key ?? '']) !== undefined,
-                    resultState: overallResultState,
-                    execute: async (selection) => {
-                        const selectedPlugin = selection.plugins[0];
-                        const selectedKey = selection.key;
-                        const schema = candidates.find((entry) => entry.pluginName === selectedPlugin).configSchema;
-                        const updates = await coercePluginConfigUpdates({
-                            schema,
-                            updates: {
-                                [selectedKey]: parseConfigValue(selection.value, rawOptions.valueJson === true),
-                            },
-                            cwd: context.cwd,
-                        });
-                        return execute(selectedPlugin, selectedKey, updates[selectedKey]);
-                    },
+                    });
                 });
-                return result.cancelled
-                    ? { cancelled: true }
-                    : { cancelled: false, key: result.selection.key, value: result.value };
             });
         }
         catch (error) {
             writeConfigMutationFailure('config:set', pluginName, rawOptions.json === true, error);
             return;
         }
-        if (outcome.cancelled)
-            return;
-        const receipt = outcome.value;
-        const selectedKey = outcome.key;
+        const receipt = outcome;
         if (rawOptions.json) {
             writeJsonReceipt(io.stdout, receipt);
         }
         else {
-            writeLine(io.stdout, `已写入 ${receipt.plugin}.${selectedKey}（${configLayerLabel(receipt.scope, receipt.projectLayer)}配置）。`);
-            if (receipt.projectLayer === 'local') {
-                writeProjectLocalConfigNotice(io.stdout);
-            }
+            writeLine(io.stdout, `已写入 ${receipt.plugin}.${key}（${configLayerLabel(receipt.scope)}配置）。`);
             writeConfigApplyNotice(io.stderr, receipt);
         }
-        commandExitState.exitCode = receipt.overallState === 'failed' ? 1 : 0;
+        commandExitState.exitCode = receipt.overallState === 'succeeded' ? 0 : 1;
     });
     config
         .command('unset')
         .argument('[plugin]')
         .argument('[key]')
         .option('-s, --scope <scope>', 'project or user')
-        .option('--local', 'write only the current project local override layer', false)
+        .option('--apply', 'apply the saved config to visible desired placements', false)
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('-y, --yes', 'confirm preApply and shared Codex native config apply', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -1932,19 +3012,17 @@ export function buildProgram(options = {}) {
         try {
             outcome = await runActionWithContext(context, async () => {
                 const scope = resolveConfigWriteScope(rawOptions.scope);
-                const projectLayer = resolveConfigProjectLayer(rawOptions);
-                const execute = async (selectedPlugin, selectedKey) => withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken) => {
-                    if (plugin.manifest.config?.schema && !plugin.manifest.config.schema[selectedKey]) {
-                        throw new Error(`Unknown config key "${selectedKey}".`);
-                    }
+                const scriptTimeoutMs = resolveScriptTimeoutMs(rawOptions);
+                const execute = async (selectedPlugin, selectedKey, confirmed) => withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken, catalogOperationContext) => {
                     const store = await readPluginConfigStore({
                         sourceId: source.sourceId,
                         sourceIdentity: source.sourceIdentity,
+                        logicalIdentity: source.logicalIdentity,
                         pluginName: plugin.manifest.name,
                         scope,
-                        ...(scope === 'project' ? { projectLayer } : {}),
                         cwd: context.cwd,
                         env: context.env,
+                        schema: plugin.manifest.config?.fields,
                     });
                     const existed = Object.hasOwn(store.values, selectedKey);
                     if (!existed)
@@ -1953,20 +3031,26 @@ export function buildProgram(options = {}) {
                         plugin,
                         pluginName: plugin.manifest.name,
                         scope,
-                        projectLayer,
                         cwd: context.cwd,
                         env: context.env,
                         nativeCliRunner: context.nativeCliRunner,
-                        rebuildRuntime: { ...context, awHomeMutationToken },
+                        rebuildRuntime: {
+                            ...context,
+                            awHomeMutationToken,
+                            catalogOperationContext,
+                            expectedGenerationSetDigest: catalogOperationContext.generationSetDigest,
+                            ...(scriptTimeoutMs === undefined ? {} : { scriptTimeoutMs }),
+                        },
                         awHomeMutationToken,
                         request: {
                             removeKeys: [selectedKey],
                         },
+                        apply: rawOptions.apply === true,
+                        sharedNativeApplyConfirmed: confirmed,
+                        preApplyConfirmed: rawOptions.yes === true,
                     });
-                    return {
+                    return buildConfigMutationReceipt('config:unset', {
                         ok: writeReceipt.overallState === 'succeeded',
-                        receiptSchemaVersion: 4,
-                        command: 'config:unset',
                         ...writeReceipt,
                         plugin: plugin.manifest.name,
                         pluginName: plugin.manifest.name,
@@ -1977,17 +3061,20 @@ export function buildProgram(options = {}) {
                         existed,
                         affectedFields: [{
                                 key: selectedKey,
-                                title: plugin?.manifest.config?.schema?.[selectedKey]?.title ?? selectedKey,
+                                title: plugin?.manifest.config?.fields?.[selectedKey]?.title ?? selectedKey,
                                 kind: 'manifest',
                                 reserved: false,
                                 action: 'unset',
                                 scope,
-                                ...(scope === 'project' ? { projectLayer } : {}),
+                                ...(!plugin.manifest.config?.fields?.[selectedKey] ? { stale: true } : {}),
                             }],
-                    };
+                    });
                 });
                 if (pluginName && key) {
-                    return { cancelled: false, value: await execute(pluginName, key) };
+                    return {
+                        cancelled: false,
+                        value: await execute(pluginName, key, rawOptions.yes === true),
+                    };
                 }
                 if (!isWizardAvailable(context, rawOptions))
                     throw new Error(configCommandUsage('unset'));
@@ -2003,7 +3090,7 @@ export function buildProgram(options = {}) {
                 const result = await runCommandWizard(context, {
                     command: 'config:unset',
                     candidates,
-                    initial: { plugins: pluginName ? [pluginName] : [], key, scope, projectLayer },
+                    initial: { plugins: pluginName ? [pluginName] : [], key, scope },
                     pluginMode: pluginName ? 'none' : 'single',
                     promptForKey: key === undefined,
                     destructive: true,
@@ -2012,10 +3099,9 @@ export function buildProgram(options = {}) {
                         plugin: selection.plugins[0],
                         key: selection.key,
                         scope: selection.scope ?? 'user',
-                        projectLayer: selection.projectLayer,
                     })),
                     resultState: overallResultState,
-                    execute: (selection) => execute(selection.plugins[0], selection.key),
+                    execute: (selection) => execute(selection.plugins[0], selection.key, true),
                 });
                 return result.cancelled
                     ? { cancelled: true }
@@ -2034,21 +3120,19 @@ export function buildProgram(options = {}) {
         }
         else {
             writeLine(io.stdout, receipt.existed
-                ? `已删除 ${receipt.plugin}.${receipt.removedKey}（${configLayerLabel(receipt.scope, receipt.projectLayer)}配置）。`
-                : `${receipt.plugin}.${receipt.removedKey}（${configLayerLabel(receipt.scope, receipt.projectLayer)}配置）原本不存在。`);
-            if (receipt.projectLayer === 'local') {
-                writeProjectLocalConfigNotice(io.stdout);
-            }
+                ? `已删除 ${receipt.plugin}.${receipt.removedKey}（${configLayerLabel(receipt.scope)}配置）。`
+                : `${receipt.plugin}.${receipt.removedKey}（${configLayerLabel(receipt.scope)}配置）原本不存在。`);
             writeConfigApplyNotice(io.stderr, receipt);
         }
-        commandExitState.exitCode = receipt.overallState === 'failed' ? 1 : 0;
+        commandExitState.exitCode = receipt.overallState === 'succeeded' ? 0 : 1;
     });
     config
         .command('reset')
         .argument('[plugin]')
         .option('-s, --scope <scope>', 'project or user')
-        .option('--local', 'reset only the current project local override layer', false)
-        .option('-y, --yes', 'confirm destructive reset', false)
+        .option('--apply', 'apply the saved config to visible desired placements', false)
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('-y, --yes', 'confirm destructive reset and preApply/shared Codex native config apply', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -2058,61 +3142,79 @@ export function buildProgram(options = {}) {
         let outcome;
         try {
             outcome = await runActionWithContext(context, async () => {
-                const execute = async (selectedPlugin, selectedScope, projectLayer, confirmed) => {
+                const execute = async (selectedPlugin, selectedScope, confirmed) => {
+                    const scriptTimeoutMs = resolveScriptTimeoutMs(rawOptions);
                     if (!confirmed) {
-                        throw new Error(`Reset requires confirmation. Re-run \`aw config reset ${selectedPlugin} -s ${selectedScope}${projectLayer === 'local' ? ' --local' : ''} --yes\` to delete this store.`);
+                        throw new Error(`Reset requires confirmation. Re-run \`aw config reset ${selectedPlugin} -s ${selectedScope} --yes\` to delete this store.`);
                     }
-                    return withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken) => {
+                    const located = await resolveStoredConfigResetIdentity({
+                        selector: selectedPlugin,
+                        context,
+                        scope: selectedScope,
+                    });
+                    const resetLocatedStore = async (plugin, pluginError) => {
                         const affectedFields = await describeResetAffectedFields({
-                            pluginName: plugin.manifest.name,
+                            sourceId: located.sourceId,
+                            sourceIdentity: located.sourceIdentity,
+                            logicalIdentity: located.logicalIdentity,
+                            pluginName: located.pluginName,
                             plugin,
+                            pluginError,
                             scope: selectedScope,
-                            projectLayer,
                             cwd: context.cwd,
                             env: context.env,
-                        });
+                        }).catch(() => []);
                         const resetReceipt = await resetPluginConfigWithHelper({
-                            pluginName: plugin.manifest.name,
+                            sourceId: located.sourceId,
+                            sourceIdentity: located.sourceIdentity,
+                            logicalIdentity: located.logicalIdentity,
+                            pluginName: located.pluginName,
                             scope: selectedScope,
-                            projectLayer,
                             cwd: context.cwd,
                             env: context.env,
                             nativeCliRunner: context.nativeCliRunner,
-                            rebuildRuntime: { ...context, awHomeMutationToken },
-                            awHomeMutationToken,
                             plugin,
+                            pluginError,
+                            apply: rawOptions.apply === true,
+                            rebuildRuntime: scriptTimeoutMs === undefined ? undefined : { scriptTimeoutMs },
+                            sharedNativeApplyConfirmed: confirmed,
+                            preApplyConfirmed: rawOptions.yes === true,
                         });
-                        return {
+                        return buildConfigMutationReceipt('config:reset', {
                             ok: resetReceipt.overallState === 'succeeded',
-                            receiptSchemaVersion: 4,
-                            command: 'config:reset',
                             ...resetReceipt,
-                            plugin: plugin.manifest.name,
-                            pluginName: plugin.manifest.name,
-                            pluginId,
-                            sourceId: source.sourceId,
-                            sourceIdentity: source.sourceIdentity,
+                            plugin: located.pluginName,
+                            pluginName: located.pluginName,
+                            pluginId: located.pluginId,
+                            sourceId: located.sourceId,
+                            ...(located.sourceIdentity ? { sourceIdentity: located.sourceIdentity } : {}),
                             affectedFields,
-                        };
-                    }).catch((error) => {
-                        const message = error instanceof Error ? error.message : String(error);
-                        if (message.includes('Catalog source')
-                            || message.startsWith('Cannot resolve required catalog sources:')) {
-                            throw new Error(`sourceMissing: ${selectedPlugin} source is unavailable; config store was not changed.`);
-                        }
-                        if (message.includes('does not exist in the required catalog source set')) {
-                            throw new Error(`configSchemaUnavailable: Plugin "${selectedPlugin}" is unavailable; config store was not changed.`);
-                        }
-                        throw error;
-                    });
+                        });
+                    };
+                    let resetStarted = false;
+                    try {
+                        return await withResolvedCatalogPlugin({
+                            selector: located.pluginId,
+                            cliVersion: resolveCliVersion(),
+                            env: context.env,
+                            consume: async ({ plugin }) => {
+                                resetStarted = true;
+                                return resetLocatedStore(plugin, null);
+                            },
+                        });
+                    }
+                    catch (error) {
+                        if (resetStarted)
+                            throw error;
+                        return resetLocatedStore(null, error instanceof Error ? error : new Error(String(error)));
+                    }
                 };
                 const scope = resolveConfigWriteScope(rawOptions.scope);
-                const projectLayer = resolveConfigProjectLayer(rawOptions);
                 const needsWizard = pluginName === undefined || rawOptions.yes !== true;
                 if (!needsWizard) {
                     return {
                         cancelled: false,
-                        value: await execute(pluginName, scope, projectLayer, true),
+                        value: await execute(pluginName, scope, true),
                     };
                 }
                 if (!isWizardAvailable(context, rawOptions)) {
@@ -2120,16 +3222,16 @@ export function buildProgram(options = {}) {
                         throw new Error(configCommandUsage('reset'));
                     return {
                         cancelled: false,
-                        value: await execute(pluginName, scope, projectLayer, false),
+                        value: await execute(pluginName, scope, false),
                     };
                 }
                 const currentCandidates = pluginName ? [] : await loadWizardCandidates(context, {});
                 const candidatesByScope = new Map();
                 if (!pluginName && (rawOptions.scope === undefined || scope === 'user')) {
-                    candidatesByScope.set('user', mergeWizardCandidates(currentCandidates, await loadStoredConfigWizardCandidates(context, [{ scope: 'user', projectLayer: 'shared' }], { includeEmptyStores: true })));
+                    candidatesByScope.set('user', mergeWizardCandidates(currentCandidates, await loadStoredConfigWizardCandidates(context, [{ scope: 'user' }], { includeEmptyStores: true })));
                 }
                 if (!pluginName && (rawOptions.scope === undefined || scope === 'project')) {
-                    candidatesByScope.set('project', mergeWizardCandidates(currentCandidates, await loadStoredConfigWizardCandidates(context, [{ scope: 'project', projectLayer }], { includeEmptyStores: true })));
+                    candidatesByScope.set('project', mergeWizardCandidates(currentCandidates, await loadStoredConfigWizardCandidates(context, [{ scope: 'project' }], { includeEmptyStores: true })));
                 }
                 const candidates = mergeWizardCandidates(candidatesByScope.get('user') ?? [], candidatesByScope.get('project') ?? []);
                 if (!pluginName && candidates.length === 0) {
@@ -2138,7 +3240,7 @@ export function buildProgram(options = {}) {
                 const result = await runCommandWizard(context, {
                     command: 'config:reset',
                     candidates,
-                    initial: { plugins: pluginName ? [pluginName] : [], scope, projectLayer },
+                    initial: { plugins: pluginName ? [pluginName] : [], scope },
                     pluginMode: pluginName ? 'none' : 'single',
                     promptForScope: rawOptions.scope === undefined,
                     destructive: true,
@@ -2149,11 +3251,10 @@ export function buildProgram(options = {}) {
                         command: 'reset',
                         plugin: selection.plugins[0],
                         scope: selection.scope ?? 'user',
-                        projectLayer: selection.projectLayer,
                         confirmed: true,
                     })),
                     resultState: overallResultState,
-                    execute: (selection) => execute(selection.plugins[0], selection.scope ?? 'user', selection.projectLayer ?? 'shared', true),
+                    execute: (selection) => execute(selection.plugins[0], selection.scope ?? 'user', true),
                 });
                 return result.cancelled
                     ? { cancelled: true }
@@ -2172,14 +3273,11 @@ export function buildProgram(options = {}) {
         }
         else {
             writeLine(io.stdout, receipt.deleted
-                ? `已重置 ${receipt.plugin} 的${configLayerLabel(receipt.scope, receipt.projectLayer)}配置。`
-                : `${receipt.plugin} 没有可重置的${configLayerLabel(receipt.scope, receipt.projectLayer)}配置。`);
-            if (receipt.projectLayer === 'local') {
-                writeProjectLocalConfigNotice(io.stdout);
-            }
+                ? `已重置 ${receipt.plugin} 的${configLayerLabel(receipt.scope)}配置。`
+                : `${receipt.plugin} 没有可重置的${configLayerLabel(receipt.scope)}配置。`);
             writeConfigApplyNotice(io.stderr, receipt);
         }
-        commandExitState.exitCode = receipt.overallState === 'failed' ? 1 : 0;
+        commandExitState.exitCode = receipt.overallState === 'succeeded' ? 0 : 1;
     });
     program
         .command('status')
@@ -2192,7 +3290,7 @@ export function buildProgram(options = {}) {
         .option('-j, --json', 'print status as JSON', false)
         .action(async (plugins, rawOptions) => {
         const context = createActionContext('status', rawOptions);
-        const result = await runActionWithContext(context, () => statusCommandV4({
+        const result = await runActionWithContext(context, () => statusCommandV8({
             plugins: plugins ?? [],
             cwd,
             env: context.env,
@@ -2205,11 +3303,11 @@ export function buildProgram(options = {}) {
         commandExitState.exitCode = result.hasErrors ? 1 : 0;
         writeLine(io.stdout, result.output);
         for (const source of result.payload.catalog.sources) {
-            if (source.error)
+            if (rawOptions.json && source.error)
                 writeLine(io.stderr, `${source.id}: ${source.error}`);
         }
         for (const error of result.payload.errors) {
-            if (error.code !== 'nativeStateUnreadable' && error.code !== 'stateInventoryFailed') {
+            if (rawOptions.json && error.code !== 'nativeStateUnreadable' && error.code !== 'stateInventoryFailed') {
                 writeLine(io.stderr, error.message);
             }
         }
@@ -2234,18 +3332,31 @@ export async function runCli(argv, options = {}) {
         ...createDefaultIo(),
         ...options.io,
     };
+    const reviewCommand = argv[0] === 'review' && ['inspect', 'prepare'].includes(argv[1] ?? '')
+        ? argv[1]
+        : null;
+    const jsonReviewCommand = reviewCommand !== null && argv.includes('--json');
     const jsonAuthoringCommand = argv.includes('--json')
-        && ((argv[0] === 'catalog' && ['init', 'version', 'build', 'validate', 'publish'].includes(argv[1] ?? ''))
-            || (argv[0] === 'plugin' && ['build', 'test'].includes(argv[1] ?? '')))
+        && ((argv[0] === 'catalog' && ['init', 'context', 'version', 'build', 'validate', 'status', 'publish'].includes(argv[1] ?? ''))
+            || (argv[0] === 'plugin' && ['build', 'test', 'validate', 'status', 'remove'].includes(argv[1] ?? ''))
+            || reviewCommand !== null)
         ? `${argv[0]}:${argv[1]}`
         : null;
+    const jsonCatalogDevCommand = argv.includes('--json')
+        && argv[0] === 'catalog'
+        && argv[1] === 'dev'
+        && ['activate', 'status', 'deactivate'].includes(argv[2] ?? '')
+        ? argv[2]
+        : null;
+    const jsonWriteRequest = jsonWriteCommandRequest(argv);
+    const jsonConfigMutation = jsonConfigMutationRequest(argv);
     try {
         const authoringScriptByCommand = {
             init: 'init-plugin.mjs',
             'add-skill': 'add-skill.mjs',
+            remove: 'remove-plugin.mjs',
             validate: 'validate-plugin.mjs',
             status: 'plugin-status.mjs',
-            'check-versions': 'check-plugin-versions.mjs',
         };
         const authoringScript = argv[0] === 'plugin'
             ? authoringScriptByCommand[argv[1] ?? '']
@@ -2254,29 +3365,85 @@ export async function runCli(argv, options = {}) {
                 : undefined;
         if (authoringScript && !argv.includes('--help') && !argv.includes('-h')) {
             const authoringArgs = argv.slice(2);
+            let authoringEnv = options.env ?? process.env;
             if (argv[0] === 'plugin'
-                && argv[1] === 'validate'
-                && !authoringArgs.some((token) => token === '--workspace-root' || token.startsWith('--workspace-root='))) {
-                authoringArgs.push('--workspace-root', options.cwd ?? process.cwd());
+                && !authoringArgs.some((token) => token === '--plugin-root' || token.startsWith('--plugin-root='))) {
+                let explicitRoot;
+                for (let index = 0; index < authoringArgs.length; index += 1) {
+                    const token = authoringArgs[index];
+                    if (token.startsWith('--workspace-root='))
+                        explicitRoot = token.slice('--workspace-root='.length);
+                    if (token === '--workspace-root')
+                        explicitRoot = authoringArgs[index + 1];
+                }
+                const originalCwd = options.cwd ?? process.cwd();
+                let discoveryCwd = originalCwd;
+                if (argv[1] === 'validate') {
+                    const valueOptions = new Set(['--workspace-root', '--claude-skill-profile', '--version-base']);
+                    for (let index = 0; index < authoringArgs.length; index += 1) {
+                        const token = authoringArgs[index];
+                        if (valueOptions.has(token)) {
+                            index += 1;
+                            continue;
+                        }
+                        if (!token.startsWith('-')) {
+                            discoveryCwd = path.resolve(originalCwd, token);
+                            authoringArgs[index] = discoveryCwd;
+                            break;
+                        }
+                    }
+                }
+                const workspace = await resolveCatalogWorkspaceRoot({
+                    cwd: discoveryCwd,
+                    ...(explicitRoot === undefined ? {} : { explicitRoot: path.resolve(options.cwd ?? process.cwd(), explicitRoot) }),
+                    mode: 'existing',
+                });
+                authoringEnv = {
+                    ...authoringEnv,
+                    AW_AUTHORING_WORKSPACE_ROOT: workspace.workspaceRoot,
+                    AW_AUTHORING_WORKSPACE_ROOT_RESOLVED_FROM: workspace.workspaceRootResolvedFrom,
+                };
+                if (explicitRoot === undefined)
+                    authoringArgs.push('--workspace-root', workspace.workspaceRoot);
             }
             return runAuthoringScript({
                 scriptName: authoringScript,
                 args: authoringArgs,
                 cwd: options.cwd ?? process.cwd(),
-                env: options.env ?? process.env,
+                env: authoringEnv,
                 io,
             });
         }
-        if (argv.some((token) => token === '--subdir' || token.startsWith('--subdir='))
+        if (!jsonConfigMutation
+            && argv.some((token) => token === '--subdir' || token.startsWith('--subdir='))
             && argv.includes('--no-subdir')) {
             const message = 'option --subdir cannot be used with option --no-subdir';
             if (argv.includes('--json') && argv[0] === 'catalog' && argv[1] === 'source' && argv[2] === 'update') {
                 writeJsonReceipt(io.stdout, {
-                    receiptSchemaVersion: 4,
+                    receiptSchemaVersion: 6,
+                    command: 'catalog:source:update',
+                    ok: false,
+                    changed: false,
+                    sourceId: argv[3] ?? '',
+                    primaryChange: null,
+                    references: [],
+                    errors: [{ code: 'catalogSourceOptionConflict', message }],
+                });
+            }
+            writeLine(io.stderr, `error: ${message}`);
+            return 1;
+        }
+        if (argv[0] === 'catalog' && argv[1] === 'source' && argv[2] === 'update'
+            && argv.includes('--auto-check') && argv.includes('--no-auto-check')) {
+            const message = 'option --auto-check cannot be used with option --no-auto-check';
+            if (argv.includes('--json') || argv.includes('-j')) {
+                writeJsonReceipt(io.stdout, {
+                    receiptSchemaVersion: 6,
                     command: 'catalog:source:update',
                     ok: false,
                     changed: false,
                     sourceId: argv[3] ?? '',
+                    primaryChange: null,
                     references: [],
                     errors: [{ code: 'catalogSourceOptionConflict', message }],
                 });
@@ -2304,9 +3471,30 @@ export async function runCli(argv, options = {}) {
             }
             return await runActionWithContext(context, () => runConsoleController(context));
         }
+        let catalogPublicationActionStarted = false;
+        let configMutationActionStarted = false;
+        const programIo = jsonCatalogDevCommand || jsonWriteRequest || jsonReviewCommand
+            ? { ...io, stderr: () => undefined }
+            : jsonConfigMutation
+                ? {
+                    ...io,
+                    stderr: (text) => {
+                        if (configMutationActionStarted)
+                            io.stderr(text);
+                    },
+                }
+                : jsonAuthoringCommand === 'catalog:publish'
+                    ? {
+                        ...io,
+                        stderr: (text) => {
+                            if (catalogPublicationActionStarted)
+                                io.stderr(text);
+                        },
+                    }
+                    : io;
         const program = buildProgram({
             ...options,
-            io,
+            io: programIo,
             diagnostics: {
                 ...options.diagnostics,
                 metadata: {
@@ -2315,16 +3503,139 @@ export async function runCli(argv, options = {}) {
                 },
             },
         });
+        if (jsonAuthoringCommand === 'catalog:publish') {
+            program.hook('preAction', () => {
+                catalogPublicationActionStarted = true;
+            });
+        }
+        if (jsonConfigMutation) {
+            program.hook('preAction', () => {
+                configMutationActionStarted = true;
+            });
+        }
         await program.parseAsync(['node', 'aw', ...argv]);
         return program.__awCommandExitState?.exitCode ?? 0;
     }
     catch (error) {
-        if (jsonAuthoringCommand && error instanceof CommanderError) {
-            writeJsonReceipt(io.stdout, {
-                command: jsonAuthoringCommand,
-                ok: false,
-                errors: [{ code: 'invalidArguments', message: error.message }],
+        if (reviewCommand && error instanceof CommanderError) {
+            if (error.exitCode === 0)
+                return 0;
+            if (jsonReviewCommand) {
+                const receipt = reviewCommand === 'inspect'
+                    ? createReviewInspectionFailure(new Error(error.message), requestedReviewView(argv), 'invalidArguments')
+                    : createReviewPreparationFailure(error.message);
+                writeJsonReceipt(io.stdout, receipt);
+            }
+            return 2;
+        }
+        if (jsonCatalogDevCommand) {
+            const workspaceRootIndex = argv.findIndex((token) => token === '--workspace-root');
+            const workspaceRootOption = argv.find((token) => token.startsWith('--workspace-root='));
+            const workspaceRoot = workspaceRootOption?.slice('--workspace-root='.length)
+                ?? (workspaceRootIndex >= 0 ? argv[workspaceRootIndex + 1] : undefined);
+            const sourceIdIndex = argv.findIndex((token) => token === '--source-id');
+            const sourceIdOption = argv.find((token) => token.startsWith('--source-id='));
+            const sourceId = sourceIdOption?.slice('--source-id='.length)
+                ?? (sourceIdIndex >= 0 ? argv[sourceIdIndex + 1] : undefined);
+            const failure = error instanceof CommanderError
+                ? { code: 'invalidArguments', message: error.message }
+                : catalogDevSourceError(error);
+            writeJsonReceipt(io.stdout, createCatalogDevFailureReceipt({
+                command: jsonCatalogDevCommand,
+                cwd: options.cwd ?? process.cwd(),
+                workspaceRoot,
+                sourceId,
+                ...failure,
+            }));
+            return 1;
+        }
+        if (jsonWriteRequest) {
+            writeCommandFailureReceipt(io.stdout, jsonWriteRequest, error);
+            return 1;
+        }
+        if (jsonConfigMutation) {
+            if (error instanceof CommanderError && error.exitCode === 0)
+                return 0;
+            const failure = configMutationFailure(error, options.env ?? process.env, options.cwd ?? process.cwd());
+            writeConfigMutationFailureReceipt(io.stdout, error instanceof CommanderError
+                ? { command: jsonConfigMutation.command }
+                : jsonConfigMutation, failure);
+            writeLine(io.stderr, failure.message);
+            return 1;
+        }
+        if (jsonAuthoringCommand === 'catalog:publish' && error instanceof CommanderError) {
+            const failure = catalogPublicationFailure({
+                error: new CatalogPublicationInspectionError('invalidArguments', error.message),
+                env: options.env,
+                sensitiveRoots: [options.cwd ?? process.cwd()],
             });
+            writeJsonReceipt(io.stdout, failure);
+            writeLine(io.stderr, failure.message);
+            return 1;
+        }
+        if (jsonAuthoringCommand && !(error instanceof CommanderError)) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (jsonAuthoringCommand === 'plugin:validate') {
+                writeJsonReceipt(io.stdout, {
+                    ok: false,
+                    profile: 'unknown',
+                    warnings: [],
+                    errors: [message],
+                });
+            }
+            else if (jsonAuthoringCommand === 'plugin:status') {
+                writeJsonReceipt(io.stdout, {
+                    schemaVersion: 3,
+                    policy: 'development',
+                    ok: false,
+                    base: null,
+                    requestedBase: null,
+                    baseCommit: null,
+                    checkedPlugins: 0,
+                    checks: [],
+                    workspaceRoot: null,
+                    workspaceRootResolvedFrom: null,
+                    errors: [{ code: 'workspaceResolutionFailed', message }],
+                });
+            }
+            else if (jsonAuthoringCommand === 'plugin:remove') {
+                writeJsonReceipt(io.stdout, {
+                    schemaVersion: 1,
+                    command: 'plugin:remove',
+                    ok: false,
+                    workspaceRoot: null,
+                    workspaceRootResolvedFrom: null,
+                    baseCommit: null,
+                    plugin: null,
+                    removed: false,
+                    errors: [{ code: 'workspaceResolutionFailed', message }],
+                });
+            }
+            else if (jsonAuthoringCommand === 'review:inspect') {
+                writeJsonReceipt(io.stdout, createReviewInspectionFailure(error, requestedReviewView(argv)));
+            }
+            else if (jsonAuthoringCommand === 'review:prepare') {
+                writeJsonReceipt(io.stdout, createReviewPreparationFailure(message, 'reviewPreparationFailed'));
+            }
+            else {
+                writeJsonReceipt(io.stdout, {
+                    command: jsonAuthoringCommand,
+                    ok: false,
+                    errors: [{ code: 'workspaceResolutionFailed', message }],
+                });
+            }
+            return 1;
+        }
+        if (jsonAuthoringCommand && error instanceof CommanderError) {
+            writeJsonReceipt(io.stdout, jsonAuthoringCommand === 'review:inspect'
+                ? createReviewInspectionFailure(new Error(error.message), requestedReviewView(argv), 'invalidArguments')
+                : jsonAuthoringCommand === 'review:prepare'
+                    ? createReviewPreparationFailure(error.message)
+                    : {
+                        command: jsonAuthoringCommand,
+                        ok: false,
+                        errors: [{ code: 'invalidArguments', message: error.message }],
+                    });
         }
         return handleCliError(error, io.stderr);
     }