@lesliechan721/aw 0.1.0-beta.7 → 0.1.0-beta.8

package/dist/src/index.js

@@ -4,14 +4,15 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { Command, CommanderError, Option } from 'commander';
+import { resolveCatalogWorkspaceRoot } from '@lesliechan721/aw-plugin-core';
 import { initCommand } from './commands/init.js';
 import { addCatalogSourceCommand, explicitRefPolicy, listCatalogSources, removeCatalogSourceCommand, setPrimaryCatalogSourceCommand, updateCatalogSourceCommand, } from './commands/catalog-source.js';
+import { activateCatalogSourceCandidateCommand, catalogGenerationStatusCommand, refreshCatalogSourceGenerationCommand, setCatalogSourceRefreshPolicyCommand, } from './commands/catalog-generation.js';
 import { cleanupWriteCommand as cleanupCommand, installWriteCommand as installCommand, reinstallWriteCommand as reinstallCommand, uninstallWriteCommand as uninstallCommand, upgradeWriteCommand as upgradeCommand, } from './commands/write-commands.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 { loadConsoleItemsResult, statusCommandV5 } from './commands/status-v5.js';
 import { normalizeUninstallCommandOptions, normalizeCleanupCommandOptions, resolveConfigReadResolution, resolveConfigProjectLayer, resolveConfigWriteScope, normalizeInstallCommandOptions, normalizeReinstallCommandOptions, normalizeUpgradeCommandOptions, } from './commands/options.js';
 import { isCommandWarningError, } from './types.js';
 import { formatWarnings } from './output/reporter.js';
@@ -26,6 +27,8 @@ 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 { catalogGenerationErrorCode } from './utils/catalog-generation-error.js';
+import { bootstrapCatalogOperationSources, resolveCatalogOperationContext, } from './utils/catalog-operation-context.js';
 import { formatConfigCommandValue, parseConfigValue, } from './utils/config-value.js';
 import { withAwHomeMutationLock, } from './utils/aw-home-mutation-lock.js';
 import { installPortableSkills, materializePortableSkillsToDirectory, PortableCommandError, renderPortableReview, } from './portable/commands.js';
@@ -35,7 +38,10 @@ 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 { getCatalogStatus, renderCatalogStatus } from './commands/catalog-status.js';
+import { getCatalogContext } from './commands/catalog-context.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, IMPLEMENTED_AW_CAPABILITIES, } from './commands/aw-capabilities.js';
 function createDefaultIo() {
     return {
         stdout: (text) => process.stdout.write(text),
@@ -141,6 +147,9 @@ export function buildEquivalentWriteCommandTokens(command, selection, rawOptions
         selection.platform ?? 'both',
         '--scope',
         selection.scope ?? 'user',
+        ...(rawOptions.allowManagedCodexInstall === true
+            ? ['--allow-managed-codex-install']
+            : []),
         ...(command === 'cleanup' ? [] : optionTokens('--script-timeout', rawOptions.scriptTimeout)),
         ...(!all && selection.plugins.length > 0 ? ['--', ...selection.plugins] : []),
     ];
@@ -209,7 +218,6 @@ async function loadWizardCandidates(context, rawOptions) {
         cwd: context.cwd,
         scope: rawOptions.scope,
         platform: rawOptions.platform,
-        includeCatalogOnly: true,
     }, context);
     return toWizardCandidates(loaded.items);
 }
@@ -389,6 +397,20 @@ async function resolveMultiSourceConfigRead(options) {
         return { ...stored, result };
     });
 }
+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) {
     const raw = { cwd: context.cwd, ...rawOptions };
     const commandOptions = command === 'install'
@@ -404,12 +426,17 @@ async function executeWriteCommand(command, pluginNames, rawOptions, context) {
         type: 'options:normalized',
         data: { plugins: pluginNames, options: commandOptions },
     });
+    const managedCodexAuthorizer = createManagedCodexAuthorizer(rawOptions, context);
+    const runtime = {
+        ...context,
+        ...(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 'upgrade': return upgradeCommand(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) {
@@ -443,7 +470,6 @@ async function runWriteCommandAction(command, pluginNames, rawOptions, context)
         cwd: context.cwd,
         scope: rawOptions.scope,
         platform: rawOptions.platform,
-        includeCatalogOnly: true,
     }, context);
     if (loaded.catalogUnavailable) {
         throw new Error('插件目录不可用。请运行 `aw init` 或 `aw init --force`，或使用完整参数重试。');
@@ -676,9 +702,32 @@ 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 authoring capability contract')
+        .description('Show the current plugin manifest authoring surface')
         .option('--surface <surface>', 'manifest | build-config | extensions | slash-commands | mcp-apps | config | lifecycle | artifacts')
         .option('--json', 'emit one machine-readable JSON object', false)
         .action((rawOptions) => {
@@ -701,6 +750,38 @@ export function buildProgram(options = {}) {
             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');
@@ -868,9 +949,11 @@ export function buildProgram(options = {}) {
         .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,
                 command: 'skill:install',
@@ -888,7 +971,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) {
@@ -979,9 +1070,11 @@ 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,
                 command: 'skill:materialize',
@@ -995,7 +1088,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;
         }
@@ -1019,9 +1120,7 @@ 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>', 'Catalog 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)
@@ -1042,35 +1141,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>', 'Catalog 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')
-        .requiredOption('--workspace-root <path>', 'Catalog Workspace root')
+        .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>', 'Catalog 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>', 'Catalog 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,
             });
@@ -1087,15 +1190,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>', 'Catalog Workspace root (default: current directory)')
+        .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,
@@ -1117,15 +1225,7 @@ export function buildProgram(options = {}) {
         .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>', 'Catalog 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('--base <git-ref>', 'explicit Git comparison base')
-        .option('--json', 'emit one schema v3 JSON document', false)
-        .option('--workspace-root <path>', 'Catalog 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')
@@ -1139,7 +1239,7 @@ export function buildProgram(options = {}) {
     catalog
         .command('init')
         .description('Initialize a local AW Catalog Workspace')
-        .option('--workspace-root <path>', 'Catalog Workspace root (default: current directory)')
+        .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')
@@ -1148,9 +1248,14 @@ export function buildProgram(options = {}) {
         .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',
+            });
             await runCatalogInitCommand({
                 ...rawOptions,
-                workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
+                ...workspace,
                 io,
             });
         }
@@ -1162,17 +1267,43 @@ export function buildProgram(options = {}) {
             commandExitState.exitCode = 1;
         }
     });
+    catalog
+        .command('context')
+        .description('Inspect resolved Catalog Workspace and publication context without network access')
+        .option('--workspace-root <path>', 'explicit Catalog Workspace root')
+        .option('--remote <name>', 'Git remote (default: origin, otherwise sole remote; explicit if ambiguous)')
+        .option('--branch <name>', 'explicit Catalog publication branch')
+        .requiredOption('--json', 'emit one schema 1 JSON object')
+        .action(async (rawOptions) => {
+        const receipt = await getCatalogContext({
+            cwd,
+            workspaceRoot: rawOptions.workspaceRoot,
+            remote: rawOptions.remote,
+            branch: rawOptions.branch,
+            env,
+            awVersion: resolveCliVersion(),
+            capabilities: IMPLEMENTED_AW_CAPABILITIES,
+        });
+        writeJsonReceipt(io.stdout, receipt);
+        if (receipt.issues.some((issue) => issue.blocking))
+            commandExitState.exitCode = 1;
+    });
     catalog
         .command('version')
         .description('Read or set the Catalog version')
         .argument('[version]', 'stable or x.y.z-beta.N catalog version')
         .option('--bump <level>', 'bump the stable SemVer base: patch, minor, or major')
-        .option('--workspace-root <path>', 'Catalog Workspace root (default: current directory)')
+        .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,
@@ -1190,14 +1321,19 @@ export function buildProgram(options = {}) {
     catalog
         .command('build')
         .description('Build a deterministic development Catalog snapshot')
-        .option('--workspace-root <path>', 'Catalog Workspace root (default: current directory)')
+        .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,
@@ -1214,7 +1350,7 @@ export function buildProgram(options = {}) {
     });
     catalog
         .command('validate')
-        .description('Validate a schema 4 Catalog snapshot')
+        .description('Validate a schema 5 Catalog snapshot')
         .argument('<snapshot-directory>', 'Catalog snapshot directory')
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (snapshotDirectory, rawOptions) => {
@@ -1236,14 +1372,15 @@ export function buildProgram(options = {}) {
     catalog
         .command('status')
         .description('Inspect a Catalog Workspace; --preflight executes plugin validation and build code')
-        .option('--workspace-root <path>', 'Catalog Workspace root (default: current directory)')
-        .option('--remote <name>', 'configured Git remote name for preflight (default: origin)')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
+        .option('--remote <name>', 'Git remote for preflight (default: origin, otherwise sole remote; explicit if ambiguous)')
         .option('--branch <name>', 'dedicated Catalog branch for preflight (default: catalog)')
         .option('--preflight', 'run publication validation and temporary plugin builds (executes plugin code)', false)
         .option('--json', 'emit one machine-readable JSON status object', false)
         .action(async (rawOptions) => {
         const receipt = await getCatalogStatus({
-            workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
+            cwd,
+            workspaceRoot: rawOptions.workspaceRoot,
             remote: rawOptions.remote,
             branch: rawOptions.branch,
             preflight: rawOptions.preflight,
@@ -1258,8 +1395,8 @@ export function buildProgram(options = {}) {
     catalog
         .command('publish')
         .description('Publish a versioned Catalog snapshot to a configured Git remote')
-        .option('--workspace-root <path>', 'Catalog Workspace root (default: current directory)')
-        .option('--remote <name>', 'configured Git remote name (default: origin)')
+        .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('--expected-descriptor-digest <digest>', 'required exact descriptor returned by publication preflight')
         .option('-y, --yes', 'confirm publication without a prompt', false)
@@ -1268,7 +1405,8 @@ export function buildProgram(options = {}) {
         try {
             const context = createActionContext('catalog:publish', {});
             const result = await runCatalogPublishCommand({
-                workspaceRoot: path.resolve(cwd, rawOptions.workspaceRoot ?? '.'),
+                cwd,
+                workspaceRoot: rawOptions.workspaceRoot,
                 remote: rawOptions.remote,
                 branch: rawOptions.branch,
                 expectedDescriptorDigest: rawOptions.expectedDescriptorDigest,
@@ -1308,6 +1446,75 @@ export function buildProgram(options = {}) {
             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)
+        .requiredOption('--json', 'emit one schema 1 JSON receipt')
+        .action(async (rawOptions) => {
+        try {
+            const receipt = await activateCatalogDevSource({
+                cwd,
+                workspaceRoot: rawOptions.workspaceRoot,
+                sourceId: rawOptions.sourceId,
+                primary: rawOptions.primary,
+                forceBuild: rawOptions.forceBuild,
+                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 1 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')
+        .requiredOption('--json', 'emit one schema 1 JSON receipt')
+        .action(async (rawOptions) => {
+        try {
+            const receipt = await deactivateCatalogDevSource({
+                cwd,
+                workspaceRoot: rawOptions.workspaceRoot,
+                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, ...failure,
+            }));
+            commandExitState.exitCode = 1;
+        }
+    });
     const catalogSource = catalog
         .command('source')
         .description('Manage catalog sources');
@@ -1328,17 +1535,38 @@ export function buildProgram(options = {}) {
         writeLine(io.stderr, message);
         commandExitState.exitCode = 1;
     };
+    const writeCatalogGenerationFailure = (command, sourceId, json, error) => {
+        const failure = sanitizeCatalogSourceError(error, env);
+        const message = redactString(failure.message);
+        if (json) {
+            writeJsonReceipt(io.stdout, {
+                catalogGenerationSchemaVersion: 1,
+                command,
+                ok: false,
+                ...(sourceId ? { sourceId } : {}),
+                errors: [{ code: catalogGenerationErrorCode(error), 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';
+        const generationCode = catalogGenerationErrorCode(error);
+        const code = generationCode === 'catalogGenerationUnavailable'
+            || generationCode === 'catalogGenerationSourceMissing'
+            ? 'catalogSourceUnavailable'
+            : generationCode !== 'catalogGenerationFailed'
+                ? generationCode
+                : 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:')) {
             writeJsonReceipt(io.stdout, {
                 receiptSchemaVersion: 4,
@@ -1352,16 +1580,33 @@ export function buildProgram(options = {}) {
         writeLine(io.stderr, message);
         commandExitState.exitCode = 1;
     };
-    const withResolvedConfigMutationPlugin = (context, selector, consume) => withAwHomeMutationLock({
-        env: context.env,
-        action: (awHomeMutationToken) => withResolvedCatalogPlugin({
-            selector,
+    const withResolvedConfigMutationPlugin = (context, selector, consume) => (async () => {
+        const parsed = parsePluginId(selector);
+        await bootstrapCatalogOperationSources({
             cliVersion: resolveCliVersion(),
-            freshnessPolicy: 'requireRemote',
+            ...(parsed.sourceId ? { sourceIds: [parsed.sourceId] } : {}),
             env: context.env,
-            consume: (resolution) => consume(resolution, awHomeMutationToken),
-        }),
-    });
+        });
+        return withAwHomeMutationLock({
+            env: context.env,
+            action: async (awHomeMutationToken) => {
+                const catalogOperationContext = await resolveCatalogOperationContext({
+                    cliVersion: resolveCliVersion(),
+                    ...(parsed.sourceId ? { sourceIds: [parsed.sourceId] } : {}),
+                    env: context.env,
+                    bootstrapMissingActive: false,
+                });
+                return withResolvedCatalogPlugin({
+                    selector,
+                    cliVersion: resolveCliVersion(),
+                    freshnessPolicy: 'cacheFirst',
+                    operationContext: catalogOperationContext,
+                    env: context.env,
+                    consume: (resolution) => consume(resolution, awHomeMutationToken, catalogOperationContext),
+                });
+            },
+        });
+    })();
     catalogSource
         .command('list')
         .option('-j, --json', 'print catalog sources as JSON', false)
@@ -1376,6 +1621,109 @@ export function buildProgram(options = {}) {
             writeLine(io.stdout, `${source.primary ? '*' : '-'} ${source.id} ${source.type} ${source.sourceIdentity}`);
         }
     });
+    catalogSource
+        .command('refresh')
+        .argument('<id>')
+        .option('-j, --json', 'print the generation refresh result as JSON', false)
+        .action(async (id, rawOptions) => {
+        try {
+            const result = await refreshCatalogSourceGenerationCommand({
+                sourceId: id,
+                cliVersion: resolveCliVersion(),
+                env,
+            });
+            if (rawOptions.json) {
+                writeJsonReceipt(io.stdout, {
+                    ...result,
+                    command: 'catalog:source:refresh',
+                    ok: true,
+                });
+            }
+            else {
+                writeLine(io.stdout, `Catalog source ${id}: ${result.outcome}.`);
+            }
+        }
+        catch (error) {
+            writeCatalogGenerationFailure('catalog:source:refresh', id, rawOptions.json === true, error);
+        }
+    });
+    catalogSource
+        .command('activate-candidate')
+        .argument('<id>')
+        .option('-j, --json', 'print the generation activation result as JSON', false)
+        .action(async (id, rawOptions) => {
+        try {
+            const result = await activateCatalogSourceCandidateCommand({ sourceId: id, env });
+            if (rawOptions.json) {
+                writeJsonReceipt(io.stdout, {
+                    ...result,
+                    command: 'catalog:source:activate-candidate',
+                    ok: true,
+                });
+            }
+            else {
+                writeLine(io.stdout, `Catalog source ${id} Candidate activated.`);
+            }
+        }
+        catch (error) {
+            writeCatalogGenerationFailure('catalog:source:activate-candidate', id, rawOptions.json === true, error);
+        }
+    });
+    catalogSource
+        .command('generation-status')
+        .argument('[id]')
+        .option('-j, --json', 'print Catalog generation status as JSON', false)
+        .action(async (id, rawOptions) => {
+        try {
+            const result = await catalogGenerationStatusCommand({ sourceId: id, env });
+            if (rawOptions.json) {
+                writeJsonReceipt(io.stdout, result);
+            }
+            else {
+                for (const source of result.sources) {
+                    const active = source.active ? `Active ${source.active.catalogVersion}` : 'no Active';
+                    const candidate = source.candidate
+                        ? `, Candidate ${source.candidate.catalogVersion}`
+                        : '';
+                    writeLine(io.stdout, `${source.sourceId}: ${active}${candidate} (${source.refreshPolicy})`);
+                }
+            }
+        }
+        catch (error) {
+            writeCatalogGenerationFailure('catalog:source:generation-status', id, rawOptions.json === true, error);
+        }
+    });
+    catalogSource
+        .command('refresh-policy')
+        .argument('<id>')
+        .argument('<policy>', 'startup or manual')
+        .option('-j, --json', 'print Catalog refresh policy result as JSON', false)
+        .action(async (id, policy, rawOptions) => {
+        try {
+            if (policy !== 'startup' && policy !== 'manual') {
+                throw new Error('Catalog refresh policy must be startup or manual.');
+            }
+            const result = await setCatalogSourceRefreshPolicyCommand({
+                sourceId: id,
+                refreshPolicy: policy,
+                env,
+            });
+            if (rawOptions.json) {
+                writeJsonReceipt(io.stdout, {
+                    catalogGenerationSchemaVersion: 1,
+                    command: 'catalog:source:refresh-policy',
+                    ok: true,
+                    ...result,
+                });
+            }
+            else {
+                writeLine(io.stdout, `Catalog source ${id} refresh policy: ${result.refreshPolicy}.`);
+            }
+        }
+        catch (error) {
+            writeCatalogGenerationFailure('catalog:source:refresh-policy', id, rawOptions.json === true, error);
+        }
+    });
     catalogSource
         .command('add')
         .argument('<id>')
@@ -1553,6 +1901,7 @@ export function buildProgram(options = {}) {
         .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)
@@ -1580,6 +1929,7 @@ export function buildProgram(options = {}) {
         .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)
@@ -1608,6 +1958,7 @@ export function buildProgram(options = {}) {
         .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)
@@ -1636,6 +1987,7 @@ export function buildProgram(options = {}) {
         .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('--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')
@@ -1662,6 +2014,7 @@ export function buildProgram(options = {}) {
         .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)
@@ -1852,7 +2205,7 @@ export function buildProgram(options = {}) {
             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) => {
+                const execute = async (selectedPlugin, selectedKey, inputValue) => withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken, catalogOperationContext) => {
                     if (!plugin.manifest.config?.schema) {
                         throw new Error(`configSchemaUnavailable: Plugin "${selectedPlugin}" does not declare an AW config schema.`);
                     }
@@ -1867,7 +2220,12 @@ export function buildProgram(options = {}) {
                         cwd: context.cwd,
                         env: context.env,
                         nativeCliRunner: context.nativeCliRunner,
-                        rebuildRuntime: { ...context, awHomeMutationToken },
+                        rebuildRuntime: {
+                            ...context,
+                            awHomeMutationToken,
+                            catalogOperationContext,
+                            expectedGenerationSetDigest: catalogOperationContext.generationSetDigest,
+                        },
                         awHomeMutationToken,
                         request: {
                             updates: { [selectedKey]: inputValue },
@@ -1993,7 +2351,7 @@ export function buildProgram(options = {}) {
             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) => {
+                const execute = async (selectedPlugin, selectedKey) => withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken, catalogOperationContext) => {
                     if (plugin.manifest.config?.schema && !plugin.manifest.config.schema[selectedKey]) {
                         throw new Error(`Unknown config key "${selectedKey}".`);
                     }
@@ -2017,7 +2375,12 @@ export function buildProgram(options = {}) {
                         cwd: context.cwd,
                         env: context.env,
                         nativeCliRunner: context.nativeCliRunner,
-                        rebuildRuntime: { ...context, awHomeMutationToken },
+                        rebuildRuntime: {
+                            ...context,
+                            awHomeMutationToken,
+                            catalogOperationContext,
+                            expectedGenerationSetDigest: catalogOperationContext.generationSetDigest,
+                        },
                         awHomeMutationToken,
                         request: {
                             removeKeys: [selectedKey],
@@ -2122,7 +2485,7 @@ export function buildProgram(options = {}) {
                     if (!confirmed) {
                         throw new Error(`Reset requires confirmation. Re-run \`aw config reset ${selectedPlugin} -s ${selectedScope}${projectLayer === 'local' ? ' --local' : ''} --yes\` to delete this store.`);
                     }
-                    return withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken) => {
+                    return withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken, catalogOperationContext) => {
                         const affectedFields = await describeResetAffectedFields({
                             pluginName: plugin.manifest.name,
                             plugin,
@@ -2138,7 +2501,12 @@ export function buildProgram(options = {}) {
                             cwd: context.cwd,
                             env: context.env,
                             nativeCliRunner: context.nativeCliRunner,
-                            rebuildRuntime: { ...context, awHomeMutationToken },
+                            rebuildRuntime: {
+                                ...context,
+                                awHomeMutationToken,
+                                catalogOperationContext,
+                                expectedGenerationSetDigest: catalogOperationContext.generationSetDigest,
+                            },
                             awHomeMutationToken,
                             plugin,
                         });
@@ -2252,7 +2620,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, () => statusCommandV5({
             plugins: plugins ?? [],
             cwd,
             env: context.env,
@@ -2295,10 +2663,16 @@ export async function runCli(argv, options = {}) {
         ...options.io,
     };
     const jsonAuthoringCommand = argv.includes('--json')
-        && ((argv[0] === 'catalog' && ['init', 'version', 'build', 'validate', 'status', '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] ?? '')))
         ? `${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;
     try {
         const authoringScriptByCommand = {
             init: 'init-plugin.mjs',
@@ -2306,7 +2680,6 @@ export async function runCli(argv, options = {}) {
             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] ?? '']
@@ -2315,16 +2688,52 @@ 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,
             });
         }
@@ -2367,7 +2776,7 @@ export async function runCli(argv, options = {}) {
         }
         const program = buildProgram({
             ...options,
-            io,
+            io: jsonCatalogDevCommand ? { ...io, stderr: () => undefined } : io,
             diagnostics: {
                 ...options.diagnostics,
                 metadata: {
@@ -2380,6 +2789,74 @@ export async function runCli(argv, options = {}) {
         return program.__awCommandExitState?.exitCode ?? 0;
     }
     catch (error) {
+        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 (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 {
+                writeJsonReceipt(io.stdout, {
+                    command: jsonAuthoringCommand,
+                    ok: false,
+                    errors: [{ code: 'workspaceResolutionFailed', message }],
+                });
+            }
+            return 1;
+        }
         if (jsonAuthoringCommand && error instanceof CommanderError) {
             writeJsonReceipt(io.stdout, {
                 command: jsonAuthoringCommand,