@aiwg/cli 2026.8.8 → 2026.8.11

package/dist/src/cli/command-log.js

@@ -4,7 +4,7 @@ import { createHash } from 'crypto';
 import path from 'path';
 import os from 'os';
 import { readAiwgConfig } from '../config/aiwg-config.js';
-import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath } from '../config/project-artifacts.js';
+import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath, projectControlPath, } from '../config/project-artifacts.js';
 const DEFAULT_MAX_BYTES = 1_048_576;
 const DEFAULT_REPORT_LIMIT = 20;
 export async function maybeAppendCommandLog(input) {
@@ -157,7 +157,7 @@ async function findProjectRoot(startDir) {
     while (current !== path.dirname(current)) {
         if (existsSync(path.join(current, '.aiwg')) ||
             existsSync(path.join(current, PROJECT_AIWG_LOCATION_FILE)) ||
-            existsSync(projectAiwgPath(current, 'aiwg.config'))) {
+            existsSync(projectControlPath(current, 'aiwg.config'))) {
             return current;
         }
         current = path.dirname(current);

package/dist/src/cli/handlers/artifacts.js

@@ -1,12 +1,17 @@
 import { getProjectDir } from '../../config/aiwg-config.js';
 import { moveProjectArtifacts } from '../../artifacts/move.js';
+import { repairProjectArtifacts } from '../../artifacts/repair.js';
+import { resolveProjectAiwgDir } from '../../config/project-artifacts.js';
 function usage() {
     return [
         'aiwg artifacts — Manage the project AIWG artifact root',
         '',
         'Usage:',
+        '  aiwg artifacts path [--json]',
         '  aiwg artifacts move --to <path> [--from <path>] [--dry-run] [--no-reindex] [--no-sync]',
         '  aiwg artifacts attach --to <existing-path> [--dry-run] [--no-reindex] [--no-sync]',
+        '  aiwg artifacts repair --dry-run',
+        '  aiwg artifacts repair --apply',
         '',
         'Notes:',
         '  move relocates a local artifact root; attach adopts an existing populated root.',
@@ -32,9 +37,53 @@ export const artifactsHandler = {
         if (action === 'help' || ctx.args.includes('--help') || ctx.args.includes('-h')) {
             return { exitCode: 0, message: usage() };
         }
-        if (action !== 'move' && action !== 'attach') {
+        if (action !== 'path' && action !== 'move' && action !== 'attach' && action !== 'repair') {
             return { exitCode: 1, message: `Unknown artifacts action: ${action}\n\n${usage()}` };
         }
+        if (action === 'path') {
+            const projectDir = getProjectDir(ctx, ctx.args);
+            const artifactRoot = resolveProjectAiwgDir(projectDir);
+            if (ctx.args.includes('--json')) {
+                return {
+                    exitCode: 0,
+                    message: JSON.stringify({
+                        schema: 'aiwg.artifacts.path.v1',
+                        project_root: projectDir,
+                        artifact_root: artifactRoot,
+                    }, null, 2),
+                    rawOutput: true,
+                };
+            }
+            return { exitCode: 0, message: artifactRoot, rawOutput: true };
+        }
+        if (action === 'repair') {
+            try {
+                const applied = ctx.args.includes('--apply');
+                const result = await repairProjectArtifacts({
+                    projectDir: getProjectDir(ctx, ctx.args),
+                    apply: applied,
+                });
+                return {
+                    exitCode: 0,
+                    message: [
+                        `${applied ? 'Repaired' : 'Artifact repair dry run for'} ${result.before.classification}`,
+                        `  Local control plane: ${result.before.local_control_root}`,
+                        `  External corpus:    ${result.before.artifact_root}`,
+                        `  Copy locally: ${result.copied.length ? result.copied.join(', ') : 'none'}`,
+                        `  Remove local identical corpus copies: ${result.removed.length ? result.removed.join(', ') : 'none'}`,
+                        `  Result: ${result.after.classification}`,
+                        applied ? '' : 'No files changed. Re-run with --apply after reviewing this plan.',
+                    ].filter(Boolean).join('\n'),
+                };
+            }
+            catch (error) {
+                return {
+                    exitCode: 1,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    message: `Artifact repair failed: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
         const to = valueAfter(ctx.args, '--to');
         if (!to) {
             return { exitCode: 1, message: `Error: --to <path> is required.\n\n${usage()}` };

package/dist/src/cli/handlers/cost-report.js

@@ -0,0 +1,71 @@
+/** OpenRouter fleet cost-report CLI handler. @issue #1187 */
+import os from 'node:os';
+import path from 'node:path';
+import { FleetConfigMissingError, formatFleetSpendReport, generateFleetSpendReport, } from '../../cost/fleet-report.js';
+function option(args, name) {
+    const index = args.indexOf(name);
+    const value = index >= 0 ? args[index + 1] : undefined;
+    return value && !value.startsWith('-') ? value : undefined;
+}
+function usage() {
+    return [
+        'Usage: aiwg cost-report (--fleet | --key <key_ref>) [--source openrouter] [--config <fleet.yaml>] [--json]',
+        '',
+        'Reads bot-to-key references from ~/.config/aiwg/fleet.yaml and credentials from',
+        '~/.config/aiwg/keys/<key_ref> or AIWG_OPENROUTER_KEY_<KEY_REF>.',
+        '',
+        'AIWG observes and correlates spend; OpenRouter enforces all key limits and caps.',
+    ].join('\n');
+}
+export const costReportHandler = {
+    id: 'cost-report',
+    name: 'Cost Report',
+    description: 'Observe OpenRouter fleet spend and correlate it with local AIWG activity',
+    category: 'utility',
+    aliases: [],
+    async execute(ctx) {
+        if (ctx.args.includes('--help') || ctx.args.includes('-h'))
+            return { exitCode: 0, message: usage() };
+        const keyRef = option(ctx.args, '--key');
+        if (ctx.args.includes('--fleet') && keyRef)
+            return { exitCode: 2, message: 'Choose either --fleet or --key, not both.' };
+        if (!ctx.args.includes('--fleet') && !keyRef) {
+            return { exitCode: 2, message: `Select --fleet or --key <key_ref>.\n\n${usage()}` };
+        }
+        const source = option(ctx.args, '--source') ?? 'openrouter';
+        if (source !== 'openrouter')
+            return { exitCode: 2, message: `Unsupported source '${source}'. Only openrouter is supported.` };
+        const configuredPath = option(ctx.args, '--config');
+        const configPath = configuredPath
+            ? path.resolve(ctx.cwd, configuredPath)
+            : path.join(os.homedir(), '.config', 'aiwg', 'fleet.yaml');
+        try {
+            const capValue = option(ctx.args, '--monthly-cap');
+            const cap = capValue === undefined ? 0 : Number(capValue);
+            if (!Number.isFinite(cap) || cap < 0)
+                return { exitCode: 2, message: '--monthly-cap must be a non-negative number.' };
+            const report = await generateFleetSpendReport({
+                cwd: ctx.cwd,
+                configPath,
+                signal: ctx.signal,
+                ...(keyRef ? {
+                    fleet: [{
+                            bot: option(ctx.args, '--bot') ?? keyRef,
+                            machine: option(ctx.args, '--machine') ?? os.hostname(),
+                            key_ref: keyRef,
+                            monthly_cap: cap,
+                        }],
+                } : {}),
+            });
+            return {
+                exitCode: report.bots.some(bot => bot.error) ? 1 : 0,
+                message: ctx.args.includes('--json') ? JSON.stringify(report, null, 2) : formatFleetSpendReport(report),
+            };
+        }
+        catch (error) {
+            const message = error instanceof FleetConfigMissingError ? error.message : `Fleet cost report failed: ${error instanceof Error ? error.message : String(error)}`;
+            return { exitCode: 1, message };
+        }
+    },
+};
+//# sourceMappingURL=cost-report.js.map

package/dist/src/cli/handlers/evidence.js

@@ -0,0 +1,78 @@
+/** Evidence bundle export and verification CLI. @issue #2039 */
+import path from 'node:path';
+import { createEvidenceBundle, verifyEvidenceBundle } from '../../evidence/bundle.js';
+function values(args, flag) {
+    const result = [];
+    for (let index = 0; index < args.length; index++)
+        if (args[index] === flag && args[index + 1])
+            result.push(args[++index]);
+    return result;
+}
+function value(args, flag) { return values(args, flag)[0]; }
+function versions(items) {
+    return Object.fromEntries(items.map(item => {
+        const index = item.indexOf('=');
+        if (index < 1 || index === item.length - 1)
+            throw new Error(`version '${item}' must use name=value`);
+        return [item.slice(0, index), item.slice(index + 1)];
+    }));
+}
+function usage() {
+    return [
+        'Usage:',
+        '  aiwg evidence export --output <dir> [--activity-export <json>] [--report <file>] [--source <file>]',
+        '    [--eval-config <file>] [--provenance <file>] [--model-version name=value] [--tool-version name=value]',
+        '    [--check-only --not-run <reason>] [--json]',
+        '  aiwg evidence verify <bundle> [--expected-root <sha256>] [--json]',
+    ].join('\n');
+}
+export const evidenceHandler = {
+    id: 'evidence', name: 'Evidence', description: 'Export and verify portable evaluation evidence bundles', category: 'utility', aliases: [],
+    async execute(ctx) {
+        const [subcommand] = ctx.args;
+        if (!subcommand || subcommand === '--help' || subcommand === '-h')
+            return { exitCode: 0, message: usage() };
+        try {
+            if (subcommand === 'verify') {
+                const bundle = ctx.args[1];
+                if (!bundle || bundle.startsWith('-'))
+                    return { exitCode: 2, message: usage() };
+                const expectedRoot = value(ctx.args, '--expected-root');
+                if (expectedRoot && !/^[0-9a-f]{64}$/i.test(expectedRoot))
+                    return { exitCode: 2, message: '--expected-root must be a SHA-256 hex digest' };
+                const result = await verifyEvidenceBundle(path.resolve(ctx.cwd, bundle), expectedRoot?.toLowerCase());
+                return { exitCode: result.valid ? 0 : 1, message: ctx.args.includes('--json') ? JSON.stringify(result, null, 2) : [
+                        `Evidence bundle: ${result.valid ? 'VALID' : 'INVALID'} (${result.status})`,
+                        ...result.errors.map(error => `ERROR: ${error}`), ...result.warnings.map(warning => `WARN: ${warning}`),
+                    ].join('\n') };
+            }
+            if (subcommand !== 'export')
+                return { exitCode: 2, message: usage() };
+            const output = value(ctx.args, '--output');
+            if (!output)
+                return { exitCode: 2, message: '--output is required.\n\n' + usage() };
+            const checkOnly = ctx.args.includes('--check-only');
+            const notRunReason = value(ctx.args, '--not-run');
+            if (checkOnly !== Boolean(notRunReason))
+                return { exitCode: 2, message: '--check-only and --not-run <reason> must be used together' };
+            const inputs = [
+                ...values(ctx.args, '--activity-export').map(file => ({ file: path.resolve(ctx.cwd, file), role: 'activity-export' })),
+                ...values(ctx.args, '--report').map(file => ({ file: path.resolve(ctx.cwd, file), role: 'report' })),
+                ...values(ctx.args, '--source').map(file => ({ file: path.resolve(ctx.cwd, file), role: 'source' })),
+                ...values(ctx.args, '--eval-config').map(file => ({ file: path.resolve(ctx.cwd, file), role: 'eval-config' })),
+                ...values(ctx.args, '--provenance').map(file => ({ file: path.resolve(ctx.cwd, file), role: 'provenance' })),
+            ];
+            const manifest = await createEvidenceBundle({
+                output: path.resolve(ctx.cwd, output), inputs,
+                modelVersions: versions(values(ctx.args, '--model-version')),
+                toolVersions: { aiwg: process.env.npm_package_version ?? 'unknown', node: process.version, ...versions(values(ctx.args, '--tool-version')) },
+                checkOnly, notRunReason,
+            });
+            return { exitCode: 0, message: ctx.args.includes('--json') ? JSON.stringify(manifest, null, 2) : `Evidence bundle ${manifest.status}: ${path.resolve(ctx.cwd, output)}\nVerifier root: ${manifest.verifier.root}` };
+        }
+        catch (error) {
+            return { exitCode: 1, message: `Evidence command failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    },
+};
+//# sourceMappingURL=evidence.js.map

package/dist/src/cli/handlers/help.js

@@ -95,6 +95,15 @@ function displayHelp() {
     ]);
     helpGroup('VALIDATION', [
         ['validate-metadata [path]', 'Validate AIWG component metadata (defaults to agentic/code)'],
+        ['context-firewall [scan]', 'Audit provider context, trust, drift, poisoning signals, and budget'],
+        ['context-firewall baseline', 'Plan or explicitly write the reviewed context baseline'],
+    ]);
+    helpGroup('METRICS', [
+        ['cost-report --fleet', 'Observe OpenRouter per-bot MTD spend and correlate local activity'],
+    ]);
+    helpGroup('EVIDENCE', [
+        ['evidence export --output <dir>', 'Package portable activity, report, source, eval, and provenance evidence'],
+        ['evidence verify <bundle>', 'Verify every member hash and the bundle checkpoint'],
     ]);
     helpGroup('SCAFFOLDING', [
         ['new-bundle <name>', 'Create project-local bundle (--type extension|addon|framework|plugin|provider, --starter skill|rule|agent|minimal, --dry-run)'],

package/dist/src/cli/handlers/index.js

@@ -16,7 +16,7 @@ import { versionHandler } from './version.js';
 import { authHandler } from './auth.js';
 import { useHandler } from './use.js';
 import { statusHandler, wizardHandler, migrateWorkspaceHandler, rollbackWorkspaceHandler, workspaceHandlers, } from './workspace.js';
-import { prefillCardsHandler, contributeStartHandler, validateMetadataHandler, doctorHandler, updateHandler, utilityHandlers, } from './utilities.js';
+import { prefillCardsHandler, contributeStartHandler, validateMetadataHandler, doctorHandler, contextFirewallHandler, updateHandler, utilityHandlers, } from './utilities.js';
 import { skillLintHandler } from './skill-lint.js';
 import { addAgentHandler, addCommandHandler, addSkillHandler, addBehaviorHandler, addTemplateHandler, scaffoldAddonHandler, scaffoldExtensionHandler, scaffoldFrameworkHandler, scaffoldingHandlers, } from './scaffolding.js';
 import { behaviorHandler, daemonInitHandler, daemonHandlers, } from './daemon.js';
@@ -59,12 +59,14 @@ import { skillUsageHandler } from './skill-usage.js';
 import { modelsHandler } from './models.js';
 import { versionsHandler } from './resource-versions.js';
 import { jobHandler } from './job.js';
+import { costReportHandler } from './cost-report.js';
+import { evidenceHandler } from './evidence.js';
 // Re-export individual handlers
 export { 
 // Maintenance
-helpHandler, versionHandler, authHandler, doctorHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
+helpHandler, versionHandler, authHandler, doctorHandler, contextFirewallHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
 // Framework management
-useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, 
+useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, 
 // Project
 newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
@@ -118,6 +120,7 @@ export const allHandlers = [
     versionHandler,
     authHandler,
     doctorHandler,
+    contextFirewallHandler,
     updateHandler,
     refreshHandler,
     regenerateHandler,
@@ -143,6 +146,8 @@ export const allHandlers = [
     issueAuditHandler,
     runHandler,
     jobHandler,
+    costReportHandler,
+    evidenceHandler,
     // Workspace management
     ...workspaceHandlers,
     // Subcommand handlers (MCP, catalog, index, skills)

package/dist/src/cli/handlers/local-executor.js

@@ -19,6 +19,7 @@
 import path from 'path';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { randomUUID } from 'crypto';
+import { pathToFileURL } from 'node:url';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
 const DEFAULT_PORT = 8200;
 const DEFAULT_BIND = '127.0.0.1';
@@ -131,7 +132,7 @@ export const localExecutorServeHandler = {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let DaemonSupervisor;
         try {
-            const shimMod = await (new Function('m', 'return import(m)'))(path.join(ctx.frameworkRoot, 'tools', 'ralph-external', 'executor-shim.mjs'));
+            const shimMod = await import(pathToFileURL(path.join(ctx.frameworkRoot, 'tools', 'ralph-external', 'executor-shim.mjs')).href);
             ExecutorShim = shimMod.ExecutorShim;
             startExecutorServer = shimMod.startExecutorServer;
         }
@@ -142,7 +143,7 @@ export const localExecutorServeHandler = {
             };
         }
         try {
-            const dsMod = await (new Function('m', 'return import(m)'))(path.join(ctx.frameworkRoot, 'tools', 'ralph-external', 'daemon-supervisor.mjs'));
+            const dsMod = await import(pathToFileURL(path.join(ctx.frameworkRoot, 'tools', 'ralph-external', 'daemon-supervisor.mjs')).href);
             DaemonSupervisor = dsMod.DaemonSupervisor;
         }
         catch (err) {
@@ -155,7 +156,7 @@ export const localExecutorServeHandler = {
         // requires it. Try loading from ralph-external/orchestrator.mjs.
         let agentSupervisorInstance = null;
         try {
-            const orchMod = await (new Function('m', 'return import(m)'))(path.join(ctx.frameworkRoot, 'tools', 'ralph-external', 'orchestrator.mjs'));
+            const orchMod = await import(pathToFileURL(path.join(ctx.frameworkRoot, 'tools', 'ralph-external', 'orchestrator.mjs')).href);
             const OrchClass = orchMod.Orchestrator ?? orchMod.default;
             if (OrchClass) {
                 const orch = new OrchClass({ maxConcurrent: opts.maxConcurrency });

package/dist/src/cli/handlers/refresh.js

@@ -15,6 +15,7 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { createScriptRunner } from './script-runner.js';
+import { createUseHandler } from './use.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
 import { refreshAllPackages } from '../../packages/registry.js';
 import { resolveActiveProvider } from '../provider-resolution.js';
@@ -97,7 +98,14 @@ export async function pruneStaleManagedAgentFiles(options) {
                 continue;
             const artifactName = normalizeAgentArtifactName(entry.name);
             const missingFromCurrentPackage = !desired.has(artifactName);
-            const fromOlderPackage = currentVersion !== null && isOlderManagedVersion(marker.version, currentVersion);
+            // Addons have independent manifest versions. Comparing their managed
+            // marker to the top-level package version makes a successful refresh
+            // delete freshly restored addon agents. Version-based cleanup remains
+            // valid for other provider trees that were not refreshed, while the
+            // active provider removes only artifacts absent from current sources.
+            const fromOlderPackage = provider !== options.provider
+                && currentVersion !== null
+                && isOlderManagedVersion(marker.version, currentVersion);
             if (!missingFromCurrentPackage && !fromOlderPackage)
                 continue;
             const relFile = path.relative(options.projectRoot, file);
@@ -149,7 +157,7 @@ export function collectModelDeployArgs(args) {
 export const refreshHandler = {
     id: 'refresh',
     name: 'Refresh',
-    description: 'Refresh AIWG to latest version and re-deploy all frameworks',
+    description: 'Refresh AIWG to latest version and re-deploy installed frameworks',
     category: 'maintenance',
     aliases: ['--refresh', 'sync', '--sync'],
     async execute(ctx) {
@@ -163,6 +171,7 @@ export const refreshHandler = {
         const modelDeployArgs = collectModelDeployArgs(ctx.args);
         const frameworkRoot = await getFrameworkRoot();
         const runner = createScriptRunner(frameworkRoot);
+        const activeUseHandler = createUseHandler();
         if (!quiet) {
             ui.blank();
             // Deprecation notice when invoked as 'sync'
@@ -195,6 +204,7 @@ export const refreshHandler = {
         // Step 2.5: Refresh remote packages (always, unless --packages-only skips npm)
         if (!quiet)
             ui.info(dryRun ? 'Would refresh remote packages...' : 'Refreshing remote packages...');
+        const deploymentFailures = [];
         if (!dryRun) {
             try {
                 const refreshed = await refreshAllPackages();
@@ -241,39 +251,67 @@ export const refreshHandler = {
             if (!quiet)
                 ui.dim('  Skipping package update (--skip-update)');
         }
-        // Step 4: Re-deploy frameworks
-        const frameworks = frameworksArg ? frameworksArg.split(',') : undefined;
+        // Step 4: Re-deploy frameworks. Both the default form and --all mean
+        // "all installed", never the `aiwg use all` expansion meta-target. This
+        // preserves the operator's selected footprint and removal symmetry.
+        const refreshConfig = await readAiwgConfig(ctx.cwd);
+        const installedFrameworks = Object.keys(refreshConfig?.installed ?? {});
+        const requestedFrameworks = frameworksArg
+            ? frameworksArg.split(',').map(item => item.trim()).filter(Boolean)
+            : [];
+        const frameworks = !frameworksArg || requestedFrameworks.includes('all')
+            ? installedFrameworks
+            : requestedFrameworks;
         if (!quiet)
             ui.info(dryRun ? 'Would re-deploy frameworks...' : 'Re-deploying frameworks...');
         if (!dryRun) {
-            const deployTarget = frameworks || ['all'];
-            for (const fw of deployTarget) {
-                const providerArgs = ['--provider', detectedProvider, ...modelDeployArgs];
-                const useResult = await runner.run('tools/cli/deploy.mjs', [fw, ...providerArgs], { capture: quiet });
+            if (frameworks.length === 0 && !quiet) {
+                ui.dim('  No installed frameworks or addons to re-deploy');
+            }
+            for (const fw of frameworks) {
+                // Invoke the active installation's handler directly. The historical
+                // deploy.mjs bridge shells out to the first `aiwg` on PATH, which can
+                // be a different version/root and therefore cannot safely refresh
+                // addons installed by this package (#143/#2102).
+                const useResult = await activeUseHandler.execute({
+                    ...ctx,
+                    cwd: ctx.cwd,
+                    frameworkRoot,
+                    args: [
+                        fw,
+                        '--provider', detectedProvider,
+                        '--target', ctx.cwd,
+                        '--yes',
+                        '--json',
+                        ...modelDeployArgs,
+                    ],
+                    rawArgs: ['use', fw],
+                });
                 if (useResult.exitCode === 0) {
                     if (!quiet)
                         ui.success(`Deployed: ${fw}`);
                 }
                 else {
+                    deploymentFailures.push(fw);
                     if (!quiet)
                         ui.warn(`Deploy issue: ${fw} (exit ${useResult.exitCode})`);
                 }
             }
         }
         else {
-            const targets = frameworks || ['all installed frameworks'];
             if (!quiet) {
-                for (const fw of targets) {
+                if (frameworks.length === 0)
+                    ui.dim('    No installed frameworks or addons');
+                for (const fw of frameworks) {
                     ui.dim(`    Would re-deploy: ${fw}`);
                 }
             }
         }
         // Step 4.25: Report planned project-local deploys (#1035).
-        // The actual deploy is performed by `aiwg use` underneath via deploy.mjs;
-        // this block surfaces what *would* happen during dry-run and what was
-        // covered during a real refresh.
+        // The active use handler performs the actual project-local deploy during
+        // framework refresh; this block surfaces dry-run and completion details.
         try {
-            const plDiscovery = await discoverProjectLocalBundles(process.cwd());
+            const plDiscovery = await discoverProjectLocalBundles(ctx.cwd);
             const plCount = plDiscovery.bundles.length;
             if (plCount > 0) {
                 if (dryRun) {
@@ -300,11 +338,12 @@ export const refreshHandler = {
         if (!quiet)
             ui.info('Checking for stale deployments...');
         let staleAgentRemovals = [];
-        if (!dryRun) {
+        if (!dryRun && deploymentFailures.length === 0) {
             try {
                 staleAgentRemovals = await pruneStaleManagedAgentFiles({
                     projectRoot: ctx.cwd,
                     frameworkRoot,
+                    provider: detectedProvider,
                 });
                 if (staleAgentRemovals.length > 0 && !quiet) {
                     const total = staleAgentRemovals.reduce((sum, item) => sum + item.paths.length, 0);
@@ -419,14 +458,21 @@ export const refreshHandler = {
             const output = JSON.stringify({
                 status: dryRun ? 'dry-run' : 'refreshed',
                 provider: detectedProvider,
-                frameworks: frameworks || ['all'],
+                frameworks,
                 skipUpdate,
                 channel: channel || undefined,
                 staleAgentRemovals,
+                deploymentFailures,
             });
             console.log(output);
         }
-        return { exitCode: dryRun ? 0 : 0 };
+        if (deploymentFailures.length > 0) {
+            return {
+                exitCode: 1,
+                message: `Failed to re-deploy installed bundle(s): ${deploymentFailures.join(', ')}`,
+            };
+        }
+        return { exitCode: 0 };
     },
 };
 //# sourceMappingURL=refresh.js.map

package/dist/src/cli/handlers/regenerate.js

@@ -25,7 +25,7 @@ import * as ui from '../ui.js';
 import { generate as generateContextFiles, discoverDeployedArtifacts, shouldEmitContextFiles, buildNormalizedAiwgMd, writeNormalizedAiwgMd, injectLegacyContext, migrateWorkspaceContext, extractExistingProjectContext, } from '../../smiths/context-pipeline/index.js';
 import { resolveActiveProvider } from '../provider-resolution.js';
 import { getProviderContextDiscoveryPathStrings } from '../../providers/provider-definitions.js';
-import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { projectControlPath } from '../../config/project-artifacts.js';
 import { selectRegenerateBranch } from '../regenerate-selector.js';
 async function handleRegenerate(args, cwd) {
     if (args.includes('--help') || args.includes('-h')) {
@@ -198,7 +198,7 @@ async function handleRegenerate(args, cwd) {
     if (legacy) {
         if (skipWorkspaceMd)
             console.log('  Note: --no-workspace-md is implicit in legacy mode.');
-        const normalizedPath = projectAiwgPath(target, 'AIWG.md');
+        const normalizedPath = projectControlPath(target, 'AIWG.md');
         let existing = '';
         try {
             existing = await fs.readFile(normalizedPath, 'utf8');
@@ -246,7 +246,7 @@ async function handleRegenerate(args, cwd) {
         console.log(`  Would regenerate:`);
         if (!skipWorkspaceMd)
             console.log(`    - ${path.join(target, 'WORKSPACE.md')} (managed graph; operator section preserved)`);
-        console.log(`    - ${projectAiwgPath(target, 'AIWG.md')}`);
+        console.log(`    - ${projectControlPath(target, 'AIWG.md')}`);
         if (!skipAiwgMd)
             console.log(`    - ${aiwgMd}`);
         if (provider === 'claude') {

package/dist/src/cli/handlers/serve.js

@@ -10,7 +10,6 @@
  */
 import path from 'path';
 import { existsSync, readFileSync } from 'fs';
-import { spawnSync } from 'child_process';
 import { createPtyWsHandler, registry as ptyRegistry } from '../../serve/pty-bridge.js';
 import { telemetryStore, createEvent } from '../../serve/telemetry.js';
 import { sandboxRegistry, normalizeSandboxEvent, } from '../../serve/sandbox-registry.js';
@@ -21,6 +20,7 @@ import { executorRegistry, validateRegisterPayload, validateDispatchPayload, val
 import { handleWebhook, IdempotencyCache, PushSecretRegistry, } from '../../a2a/webhook.js';
 import { AiwgError, EXIT_CODES } from '../errors.js';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { loadFeaturePackage } from '../../features/runtime.js';
 // A2A push-notification state — module-scoped so the test harness can
 // monkey-patch them in if needed. One process serves one set of secrets.
 const pushSecretRegistry = new PushSecretRegistry();
@@ -190,11 +190,10 @@ async function setupWebSockets(httpServer, readOnly) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let wsMod;
     try {
-        // @ts-expect-error — ws lacks bundled types; we use the runtime constructor only
-        wsMod = await import('ws');
+        wsMod = await loadFeaturePackage('ws');
     }
     catch {
-        console.warn('[serve] ws package not available — WebSocket routes disabled. Install with: npm install ws');
+        console.warn('[serve] WebSocket routes disabled — run `aiwg features install webserver` to enable them.');
         return;
     }
     // ws ships as CJS; ESM import may wrap in .default
@@ -510,40 +509,19 @@ export async function startServer(opts) {
         // import path raises ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING (#1277).
         // hono is an optionalDependency; tsc may not find its types under
         // `npm ci --omit=optional` (e.g. metadata-validation workflow). The
-        // try/catch + auto-install fallback below handles that at runtime.
+        // try/catch below emits the managed feature-install route at runtime.
         // @ts-ignore — optional dep; may not be installed at typecheck time
-        honoMod = await import('hono');
+        honoMod = await loadFeaturePackage('hono');
         // @ts-ignore — optional dep; may not be installed at typecheck time
-        nodeMod = await import('@hono/node-server');
+        nodeMod = await loadFeaturePackage('@hono/node-server');
     }
     catch {
-        // Auto-install optional serve dependencies on first use
-        console.log('Installing serve dependencies (hono, @hono/node-server, ws)...');
-        const result = spawnSync('npm', ['install', '--save-optional', 'hono', '@hono/node-server', 'ws'], { stdio: 'inherit' });
-        if (result.status !== 0) {
-            throw new AiwgError({
-                code: 'ERR_SERVE_DEPS_INSTALL_FAILED',
-                message: 'Failed to install serve dependencies (hono, @hono/node-server, ws)',
-                hint: 'Install manually: npm install hono @hono/node-server ws',
-                exitCode: EXIT_CODES.GENERAL,
-            });
-        }
-        // Retry imports after install
-        try {
-            // @ts-ignore — optional dep; may not be installed at typecheck time
-            honoMod = await import('hono');
-            // @ts-ignore — optional dep; may not be installed at typecheck time
-            nodeMod = await import('@hono/node-server');
-        }
-        catch (err) {
-            throw new AiwgError({
-                code: 'ERR_SERVE_DEPS_LOAD_FAILED',
-                message: 'Serve dependencies installed but could not be loaded',
-                hint: 'Try: npm install hono @hono/node-server ws',
-                exitCode: EXIT_CODES.GENERAL,
-                cause: err,
-            });
-        }
+        throw new AiwgError({
+            code: 'ERR_SERVE_DEPS_MISSING',
+            message: 'The optional webserver feature is not available',
+            hint: 'Run `aiwg features install webserver`, then retry `aiwg serve`.',
+            exitCode: EXIT_CODES.GENERAL,
+        });
     }
     const { Hono } = honoMod;
     const { serve } = nodeMod;
@@ -1692,7 +1670,8 @@ export async function startServer(opts) {
     const webDistDir = path.join(opts.frameworkRoot, 'apps', 'web', 'dist');
     if (existsSync(webDistDir)) {
         try {
-            const { serveStatic } = await (new Function('m', 'return import(m)'))('@hono/node-server/serve-static');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const { serveStatic } = await loadFeaturePackage('@hono/node-server/serve-static');
             app.use('/*', serveStatic({ root: webDistDir }));
         }
         catch {
@@ -1788,7 +1767,7 @@ export const serveHandler = {
         if (open) {
             try {
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const openMod = await (new Function('m', 'return import(m)'))('open');
+                const openMod = await loadFeaturePackage('open');
                 const openBrowser = openMod.default ?? openMod;
                 await openBrowser(url);
             }