@aiwg/cli 2026.8.7 → 2026.8.10

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

@@ -149,7 +149,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) {
@@ -241,13 +241,24 @@ 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) {
+            if (frameworks.length === 0 && !quiet) {
+                ui.dim('  No installed frameworks or addons to re-deploy');
+            }
+            for (const fw of frameworks) {
                 const providerArgs = ['--provider', detectedProvider, ...modelDeployArgs];
                 const useResult = await runner.run('tools/cli/deploy.mjs', [fw, ...providerArgs], { capture: quiet });
                 if (useResult.exitCode === 0) {
@@ -261,9 +272,10 @@ export const refreshHandler = {
             }
         }
         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}`);
                 }
             }
@@ -419,7 +431,7 @@ export const refreshHandler = {
             const output = JSON.stringify({
                 status: dryRun ? 'dry-run' : 'refreshed',
                 provider: detectedProvider,
-                frameworks: frameworks || ['all'],
+                frameworks,
                 skipUpdate,
                 channel: channel || undefined,
                 staleAgentRemovals,

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

@@ -25,7 +25,8 @@ 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')) {
         console.log(`
@@ -40,7 +41,8 @@ async function handleRegenerate(args, cwd) {
     or commands — use 'aiwg refresh' for that.
 
   Options:
-    --workspace             Canonical WORKSPACE.md → AIWG.md graph (default)
+    (no branch flag)        Intelligently select workspace refresh or adoption preview
+    --workspace             Explicit canonical WORKSPACE.md → AIWG.md graph
     --existing-project      Transactionally extract an established project into WORKSPACE.md
     --legacy, --full-inject Legacy inline compatibility branch
     --apply                 Apply --existing-project after its mandatory preflight
@@ -57,6 +59,7 @@ async function handleRegenerate(args, cwd) {
     aiwg regenerate --workspace
     aiwg regenerate --existing-project --dry-run
     aiwg regenerate --existing-project --apply
+    aiwg regenerate --apply
     aiwg regenerate --full-inject
     aiwg regenerate --dry-run
     aiwg regenerate --provider codex
@@ -69,9 +72,9 @@ async function handleRegenerate(args, cwd) {
     const skipAiwgMd = args.includes('--no-aiwg-md');
     const skipAgentsMd = args.includes('--no-agents-md');
     const skipWorkspaceMd = args.includes('--no-workspace-md');
-    const legacy = args.includes('--legacy') || args.includes('--full-inject');
-    const workspace = args.includes('--workspace');
-    const existingProject = args.includes('--existing-project');
+    const requestedLegacy = args.includes('--legacy') || args.includes('--full-inject');
+    const requestedWorkspace = args.includes('--workspace');
+    const requestedExistingProject = args.includes('--existing-project');
     const apply = args.includes('--apply');
     const valueFlags = new Set(['--provider']);
     const booleanFlags = new Set([
@@ -95,23 +98,27 @@ async function handleRegenerate(args, cwd) {
             });
         }
     }
-    const selectedBranches = Number(legacy) + Number(workspace) + Number(existingProject);
+    const selectedBranches = Number(requestedLegacy) + Number(requestedWorkspace) + Number(requestedExistingProject);
     if (selectedBranches > 1)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
             message: 'Choose exactly one regenerate branch: --workspace, --existing-project, or --full-inject.',
             exitCode: EXIT_CODES.USAGE,
         });
-    if (apply && !existingProject)
+    if (dryRun && apply)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
-            message: '--apply is only valid with --existing-project.',
+            message: 'Choose either --dry-run or --apply.',
             exitCode: EXIT_CODES.USAGE,
         });
-    if (existingProject && dryRun && apply)
+    const selection = await selectRegenerateBranch(cwd, args);
+    const legacy = selection.branch === 'legacy';
+    const existingProject = selection.branch === 'existing-project';
+    if (apply && !existingProject)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
-            message: 'Choose either --dry-run or --apply for --existing-project.',
+            message: '--apply is only valid when the existing-project branch is selected.',
+            hint: 'Use `aiwg regenerate --existing-project --apply`, or run without --apply to inspect the selected branch.',
             exitCode: EXIT_CODES.USAGE,
         });
     if (existingProject && (force || skipAiwgMd || skipAgentsMd || skipWorkspaceMd))
@@ -140,6 +147,9 @@ async function handleRegenerate(args, cwd) {
     console.log(`  Provider: ${provider}`);
     console.log(`  Target:   ${target}`);
     console.log(`  Branch:   ${legacy ? 'legacy full injection' : existingProject ? 'canonical existing-project extraction' : 'canonical workspace graph'}`);
+    console.log(`  Selected: ${selection.explicit ? 'explicit' : 'inferred'} — ${selection.reason}`);
+    if (selection.evidence.length > 0)
+        console.log(`  Evidence: ${selection.evidence.join(', ')}`);
     if (existingProject) {
         const preflight = await migrateWorkspaceContext(target, {
             dryRun: true,
@@ -188,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');
@@ -236,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);
             }

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

@@ -1203,15 +1203,16 @@ function projectRootCandidate(start) {
     catch {
         current = resolve(start);
     }
-    let gitRoot = null;
     while (true) {
         if (existsSync(resolve(current, '.aiwg', 'aiwg.config')))
             return current;
-        if (!gitRoot && existsSync(resolve(current, '.git')))
-            gitRoot = current;
+        // A repository root is the project boundary. Do not let an unrelated
+        // ancestor workspace configuration capture session catalog reads.
+        if (existsSync(resolve(current, '.git')))
+            return current;
         const parent = dirname(current);
         if (parent === current)
-            return gitRoot;
+            return null;
         current = parent;
     }
 }