@aiwg/cli 2026.9.7 → 2026.9.9

package/dist/src/artifacts/index-builder.js

@@ -712,6 +712,33 @@ export function parseFlowDoc(content, filePath) {
         searchTerms: [...searchTerms],
     };
 }
+/**
+ * Best-effort absolute path to the AIWG install root, for error text that must
+ * name where the framework graph can actually be built (#2530).
+ */
+function resolveInstallRootHint() {
+    try {
+        // The running module lives under the install root; walk up to the package.
+        let dir = path.dirname(new URL(import.meta.url).pathname);
+        for (let i = 0; i < 10; i += 1) {
+            const pkg = path.join(dir, 'package.json');
+            if (fs.existsSync(pkg)) {
+                try {
+                    const content = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+                    if (content.name === 'aiwg' || content.name === '@aiwg/cli')
+                        return dir;
+                }
+                catch { /* keep walking */ }
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch { /* fall through */ }
+    return '<aiwg install root>';
+}
 export async function buildIndex(cwd, options = {}) {
     const { force = false, verbose = false, scope, outputDir, graph, explicit = true } = options;
     const startTime = Date.now();
@@ -748,7 +775,22 @@ export async function buildIndex(cwd, options = {}) {
             return;
         }
         console.error(`Error: No scan directories found: ${scanDirs.join(', ')}`);
-        console.log('Run this command from a project with the required directories.');
+        // The framework graph scans the AIWG corpus, which only exists at the install
+        // root — never in a consumer project. Saying "run from a project with the
+        // required directories" sends the operator looking in the wrong place (#2530).
+        if (graph === 'framework') {
+            const installRoot = resolveInstallRootHint();
+            console.log('The framework graph indexes the AIWG corpus and can only be built at the');
+            console.log('install root, not in a consumer project. Build it there, then sync here:');
+            console.log('');
+            console.log(`  cd ${installRoot} && aiwg index build --graph framework --force`);
+            console.log(`  cd ${cwd} && aiwg index sync --backend fortemi-core --graph framework`);
+            console.log('');
+            console.log("As an immediate workaround, discovery also works with '--backend local'.");
+        }
+        else {
+            console.log('Run this command from a project with the required directories.');
+        }
         process.exit(1);
     }
     // Determine output index directory

package/dist/src/artifacts/query-engine.js

@@ -59,6 +59,13 @@ function canonicalLocalityRank(entryPath) {
     const normalized = entryPath.replace(/\\/g, '/');
     if (normalized.startsWith('.aiwg/') || normalized.includes('/.aiwg/'))
         return 0;
+    // Top-level persona mirrors are the least canonical source for a name a bundle
+    // also owns. Without this they fell into the catch-all below and scored 1,
+    // beating the bundle copy at 2 — the opposite of #1643. It only ever looked
+    // correct because a populated user index supplied provenance and `scopeRank`
+    // never reached this fallback (#2544).
+    if (normalized.startsWith('agentic/code/agents/') || normalized.includes('/agentic/code/agents/'))
+        return 4;
     if (normalized.includes('/plugins/') || normalized.startsWith('agentic/code/plugins/'))
         return 3;
     if (normalized.includes('/frameworks/') ||

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

@@ -29,16 +29,84 @@ function display(status, json) {
         for (const item of status.drift)
             console.log(`  - ${item}`);
     }
+    const remedy = remediation(status);
+    if (remedy) {
+        console.log('');
+        console.log('Resolve:');
+        for (const line of remedy)
+            console.log(`  ${line}`);
+    }
     console.log('');
 }
+/**
+ * `switch` and `adopt` only write installation.json — they cannot change which
+ * binary is on PATH. So when the declaration and reality disagree, neither command
+ * resolves it and the operator needs a shell step this output never mentioned.
+ * Print it, tailored to the direction of the drift (#2534).
+ */
+export function remediation(status) {
+    if (status.state !== 'mismatch')
+        return null;
+    const canonicalMethod = status.identity?.method;
+    const canonicalRoot = status.identity?.root;
+    const actualMethod = status.actualMethod;
+    if (canonicalMethod === 'source' && canonicalRoot && actualMethod !== 'source') {
+        return [
+            `The declared source install is not what runs. Put it on PATH:`,
+            `  cd ${canonicalRoot} && npm link`,
+            `Then re-run 'aiwg installation show' to confirm State: aligned.`,
+            `('aiwg installation switch' would only rewrite the declaration, which already says source.)`,
+        ];
+    }
+    if (canonicalMethod === 'npm' && actualMethod === 'source') {
+        return [
+            `The declared npm package is not what runs. Restore it:`,
+            `  npm install -g aiwg`,
+            `If a source checkout was linked, unlink it first: npm unlink -g aiwg`,
+        ];
+    }
+    return [
+        `Declaration and reality disagree (${canonicalMethod ?? 'unrecorded'} vs ${actualMethod}).`,
+        `'switch' and 'adopt' are declaration-only and cannot change PATH.`,
+        `Install or link the intended root, then re-run 'aiwg installation show'.`,
+    ];
+}
+function usage() {
+    return `
+  aiwg installation — inspect, adopt, or switch the canonical global installation
+
+  Usage:
+    aiwg installation show [--json]
+    aiwg installation adopt --method <npm|web|source> [--run-mode <normal|development>] [--yes]
+    aiwg installation switch --root <path> --method <npm|web|source> [--manager <absolute-path>]
+
+  Options:
+    --json            Machine-readable output
+    --config-dir      Override the installation config directory
+    --manager         Absolute path to the package manager executable
+    --channel         Release channel (stable|edge)
+    --run-mode        normal|development (derived from --method when omitted)
+    --yes             Confirm an adopt that abandons the declared install
+
+  Notes:
+    These commands are declaration-only: they record which installation is
+    canonical, they do not change which binary is on PATH. When \`show\` reports
+    State: mismatch, it prints the concrete command that resolves it.
+`;
+}
 export const installationHandler = {
     id: 'installation',
     name: 'Installation',
     description: 'Inspect, adopt, or deliberately switch the canonical global installation',
     category: 'maintenance',
     aliases: [],
+    async help() {
+        return { exitCode: 0, message: usage(), rawOutput: true };
+    },
     async execute(ctx) {
         const [action = 'show'] = ctx.args;
+        if (action === 'help')
+            return { exitCode: 0, message: usage(), rawOutput: true };
         const json = ctx.args.includes('--json');
         const actualRoot = getPackageRoot();
         const common = {
@@ -54,11 +122,43 @@ export const installationHandler = {
         }
         if (action === 'adopt') {
             const method = valueAfter(ctx.args, '--method');
+            // adopt resolves a mismatch by rewriting canonical to match whatever is
+            // running — i.e. by abandoning the declared install. That is the opposite
+            // of what an operator standardizing on a source checkout wants, so make it
+            // a deliberate choice rather than a silent capitulation (#2534).
+            const before = inspectInstallation({
+                ...common,
+                identity: loadInstallationIdentity({ ...common, createIfMissing: true }),
+            });
+            const declaredMethod = before.identity?.method;
+            const abandoning = before.state === 'mismatch'
+                && declaredMethod
+                && declaredMethod !== before.actualMethod;
+            if (abandoning && !ctx.args.includes('--yes')) {
+                return {
+                    exitCode: 2,
+                    rawOutput: true,
+                    message: [
+                        `Refusing to adopt: this would abandon the declared ${declaredMethod} install.`,
+                        ``,
+                        `  declared: ${declaredMethod} at ${before.identity?.root ?? '(unrecorded)'}`,
+                        `  running:  ${before.actualMethod} at ${before.actualRoot}`,
+                        ``,
+                        `adopt rewrites the declaration to match what is running; it does not change`,
+                        `which binary is on PATH. If you meant to keep the declared install, run`,
+                        `'aiwg installation show' for the command that puts it back on PATH.`,
+                        `If you really mean to abandon it, re-run with --yes.`,
+                    ].join('\n'),
+                };
+            }
             const status = adoptInstallation({
                 ...common,
                 method,
                 runMode: valueAfter(ctx.args, '--run-mode'),
             });
+            if (abandoning) {
+                console.log(`Warning: adopted the running ${status.actualMethod} install; the previously declared ${declaredMethod} install is no longer canonical.`);
+            }
             display(status, json);
             return { exitCode: 0 };
         }
@@ -66,7 +166,7 @@ export const installationHandler = {
             const root = valueAfter(ctx.args, '--root');
             const method = valueAfter(ctx.args, '--method');
             if (!root || !method) {
-                return { exitCode: 2, message: 'Usage: aiwg installation switch --root <path> --method <npm|web|source> [--manager <absolute-path>]' };
+                return { exitCode: 2, message: `switch requires --root and --method\n${usage()}`, rawOutput: true };
             }
             const status = switchInstallation({
                 ...common,
@@ -77,7 +177,7 @@ export const installationHandler = {
             display(status, json);
             return { exitCode: 0 };
         }
-        return { exitCode: 2, message: 'Usage: aiwg installation <show|adopt|switch> [options]' };
+        return { exitCode: 2, message: `Unknown installation action: ${action}\n${usage()}`, rawOutput: true };
     },
 };
 //# sourceMappingURL=installation.js.map

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

@@ -228,7 +228,13 @@ Drain queued missions in a session by launching each as a ralph loop. Missions
 without --completion criteria are skipped with a warning.
 
   --accept-cost   Skip the cost-warning gate (required for non-TTY contexts
-                  when estimated cumulative cost exceeds $5). See #1450.`,
+                  when estimated cumulative cost exceeds $5). See #1450.
+
+The estimate is the cumulative iteration floor (missions x max-iterations x
+~$1.60 cache cost per headless iteration). A mission's --max-total-cost caps its
+share of that estimate only on a provider that reports spend; on a provider that
+reports none the ceiling is inert (#1766), so it is reported but not subtracted.
+See #2522.`,
     status: `Usage: aiwg mc status [<session-id>] [--json]
 
 Show mission status for a session. Auto-syncs from ralph loop state files.
@@ -479,6 +485,71 @@ async function mcDispatch(ctx) {
  *   detached process, so they DO run in parallel after launch — the loop here
  *   is just for orderly dispatch, not for parallel scheduling)
  */
+/**
+ * Per-iteration cache-creation floor for a headless claude session (sonnet
+ * baseline; opus is ~$3.90).
+ */
+export const SONNET_CACHE_USD = 1.60;
+/** Estimate at or above which `mc run` warns and refuses in non-TTY contexts. */
+export const COST_WARNING_THRESHOLD_USD = 5.0;
+/**
+ * Providers whose headless stream reports spend, so a declared `--max-total-cost`
+ * ceiling can actually fire mid-loop.
+ *
+ * Only `claude` emits cost on its stream-json events, which is what
+ * `SessionLauncher._extractUsageStats` reads. Adapters without stream-json
+ * (codex, factory, opencode, deepseek) emit no usage events at all — #1766
+ * recorded that a spend ceiling on those is inert and never fires. Adapters that
+ * do stream JSON but have not been observed carrying cost fields (omp, pi) stay
+ * out of this set deliberately: assuming an observability we have not seen would
+ * weaken the gate in exactly the case where the operator has least protection.
+ */
+export const COST_REPORTING_PROVIDERS = new Set(['claude']);
+/**
+ * Estimate cumulative spend for a set of queued missions (#2522).
+ *
+ * The floor for each mission is `maxIterations × SONNET_CACHE_USD`. A declared
+ * `maxTotalCost` bounds that floor **only** when the target provider reports
+ * spend — on a provider that reports none, the ceiling is inert (#1766), so
+ * subtracting it would make the warning weaker precisely where the operator has
+ * no enforced protection. Those ceilings are counted and surfaced instead.
+ */
+export function estimateMissionRunCost(missions, provider) {
+    const spendObservable = COST_REPORTING_PROVIDERS.has(provider);
+    let estimateUsd = 0;
+    let iterationFloorUsd = 0;
+    let declaredCeilingUsd = 0;
+    let cappedMissions = 0;
+    let inertCeilingMissions = 0;
+    for (const mission of missions) {
+        const floor = mission.maxIterations * SONNET_CACHE_USD;
+        iterationFloorUsd += floor;
+        const ceiling = typeof mission.maxTotalCost === 'number' && Number.isFinite(mission.maxTotalCost)
+            ? mission.maxTotalCost
+            : undefined;
+        if (ceiling === undefined) {
+            estimateUsd += floor;
+            continue;
+        }
+        declaredCeilingUsd += ceiling;
+        if (spendObservable) {
+            cappedMissions += 1;
+            estimateUsd += Math.min(floor, ceiling);
+        }
+        else {
+            inertCeilingMissions += 1;
+            estimateUsd += floor;
+        }
+    }
+    return {
+        estimateUsd,
+        iterationFloorUsd,
+        declaredCeilingUsd,
+        cappedMissions,
+        inertCeilingMissions,
+        spendObservable,
+    };
+}
 async function mcRun(ctx) {
     const positional = getPositionalArgs(ctx.args);
     const sessionId = positional[0];
@@ -493,24 +564,28 @@ async function mcRun(ctx) {
         ui.info(`No queued missions in session ${session.id}. Run \`aiwg mc dispatch ${session.id} "<objective>"\` to add one.`);
         return { exitCode: 0 };
     }
-    // #1450 P0: cost warning gate.
+    // #1450 P0: cost warning gate, with declared ceilings honored (#2522).
     //
     // Each headless claude session pays a ~$1.60 cache-creation cost on iteration
     // 1 before any user-meaningful work (sonnet baseline; opus is ~$3.90). Across
     // N missions × M iterations the floor compounds quickly. Warn before launch
     // and refuse in non-TTY contexts unless --accept-cost is set.
-    //
-    // Estimate is intentionally conservative: cumulative iteration floor =
-    // missions × max_iterations × sonnet_cache_cost. Real spend may be lower if
-    // missions complete in fewer iterations.
     const eligible = queued.filter(m => m.mode !== 'pty-orchestrator' && !!m.completion);
-    const SONNET_CACHE_USD = 1.60;
-    const iterFloor = eligible.reduce((sum, m) => sum + m.maxIterations, 0);
-    const estimateUsd = iterFloor * SONNET_CACHE_USD;
-    const COST_WARNING_THRESHOLD_USD = 5.0;
-    if (estimateUsd >= COST_WARNING_THRESHOLD_USD && !acceptCost) {
+    const projectRoot = ctx.cwd || process.cwd();
+    const frameworkRoot = ctx.frameworkRoot;
+    const { readAiwgConfig, resolveParallelism } = await import('../../config/aiwg-config.js');
+    const cfg = await readAiwgConfig(projectRoot).catch(() => null);
+    const provider = cfg?.providers[0] ?? 'unknown';
+    const estimate = estimateMissionRunCost(eligible, provider);
+    if (estimate.estimateUsd >= COST_WARNING_THRESHOLD_USD && !acceptCost) {
         ui.blank();
-        ui.warn(`Cost estimate: ~$${estimateUsd.toFixed(2)} (${eligible.length} missions × iteration floors × ~$${SONNET_CACHE_USD.toFixed(2)} cache cost per claude headless iter).`);
+        ui.warn(`Cost estimate: ~$${estimate.estimateUsd.toFixed(2)} (${eligible.length} missions × iteration floors × ~$${SONNET_CACHE_USD.toFixed(2)} cache cost per claude headless iter).`);
+        if (estimate.cappedMissions > 0) {
+            ui.warn(`Declared ceilings: $${estimate.declaredCeilingUsd.toFixed(2)} across ${estimate.cappedMissions} mission(s) — counted toward the estimate because ${provider} reports spend.`);
+        }
+        if (estimate.inertCeilingMissions > 0) {
+            ui.warn(`${estimate.inertCeilingMissions} mission(s) declare --max-total-cost totalling $${estimate.declaredCeilingUsd.toFixed(2)}, but ${provider} does not report spend — those ceilings cannot fire and are NOT subtracted from this estimate (#1766).`);
+        }
         ui.warn('Actual spend may be lower if missions complete early, higher if model is opus or context grows.');
         if (!process.stdout.isTTY) {
             ui.error('Refusing to launch in non-interactive context. Re-run with `--accept-cost` to proceed.');
@@ -531,12 +606,7 @@ async function mcRun(ctx) {
     let launched = 0;
     let skipped = 0;
     let failed = 0;
-    const projectRoot = ctx.cwd || process.cwd();
-    const frameworkRoot = ctx.frameworkRoot;
-    const { readAiwgConfig, resolveParallelism } = await import('../../config/aiwg-config.js');
     const { FileAdmissionStore, SharedHostScheduler } = await import('../../serve/shared-host-scheduler.js');
-    const cfg = await readAiwgConfig(projectRoot).catch(() => null);
-    const provider = cfg?.providers[0] ?? 'unknown';
     const maxConcurrent = resolveParallelism(cfg?.parallelism, provider).max_parallel_mc_missions;
     const scheduler = new SharedHostScheduler(new FileAdmissionStore(join(projectRoot, MC_ROOT, 'admission.json')), {
         maxConcurrent,

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

@@ -40,6 +40,48 @@ const PROVIDER_AGENT_DIRS = {
 export async function currentBundledAgentBasenames(frameworkRoot) {
     return new Set((await collectPackagedAgentInventory(frameworkRoot)).keys());
 }
+/**
+ * Basenames of every rule the current package can deploy.
+ *
+ * Symmetric to {@link currentBundledAgentBasenames}. A rule absent from this set
+ * is residue from a deploy model that no longer writes it (#2540).
+ *
+ * Every group that can ship a `rules/` directory must be listed here: the set is
+ * the prune's definition of "still shipped", so a missed group makes live rules
+ * look orphaned and deletes them. `extensions` ships 22 rules and was the group
+ * this nearly lost.
+ */
+export const BUNDLED_RULE_SOURCE_GROUPS = ['frameworks', 'addons', 'plugins', 'extensions'];
+export async function currentBundledRuleBasenames(frameworkRoot) {
+    const names = new Set();
+    const codeRoot = path.join(frameworkRoot, 'agentic', 'code');
+    for (const group of BUNDLED_RULE_SOURCE_GROUPS) {
+        let units;
+        try {
+            units = await fs.readdir(path.join(codeRoot, group), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const unit of units) {
+            if (!unit.isDirectory())
+                continue;
+            const rulesDir = path.join(codeRoot, group, unit.name, 'rules');
+            let entries;
+            try {
+                entries = await fs.readdir(rulesDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.isFile() && entry.name.endsWith('.md'))
+                    names.add(entry.name);
+            }
+        }
+    }
+    return names;
+}
 async function readFrameworkVersion(frameworkRoot) {
     try {
         const pkg = JSON.parse(await fs.readFile(path.join(frameworkRoot, 'package.json'), 'utf8'));
@@ -186,6 +228,7 @@ export async function partitionTrackedPaths(projectRoot, relativePaths) {
 }
 export async function pruneStaleManagedAgentFiles(options) {
     const desired = await currentBundledAgentBasenames(options.frameworkRoot);
+    const desiredRules = await currentBundledRuleBasenames(options.frameworkRoot);
     const currentVersion = options.currentVersion ?? await readFrameworkVersion(options.frameworkRoot);
     const crossProvider = options.crossProvider ?? 'skip';
     const removals = [];
@@ -204,7 +247,10 @@ export async function pruneStaleManagedAgentFiles(options) {
         // provider only drops agents whose source no longer ships them.
         if (!isTargetProvider && crossProvider === 'skip')
             continue;
-        const kinds = isTargetProvider ? ['agents'] : PRUNABLE_ARTIFACT_KINDS;
+        // Rules were excluded from the target-provider pass, so a project carried
+        // every rule any past version ever deployed. On long-lived projects that is
+        // the bulk of the startup-context budget (#2540).
+        const kinds = isTargetProvider ? ['agents', 'rules'] : PRUNABLE_ARTIFACT_KINDS;
         const hits = await collectManagedProviderArtifacts(options.projectRoot, provider, kinds);
         const eligible = hits.filter((hit) => {
             if (isTargetProvider) {
@@ -212,6 +258,8 @@ export async function pruneStaleManagedAgentFiles(options) {
                 // marker to the top-level package version makes a successful refresh
                 // delete freshly restored addon agents, so the active provider removes
                 // only artifacts absent from current sources.
+                if (hit.kind === 'rules')
+                    return !desiredRules.has(path.basename(hit.relativePath));
                 return !desired.has(hit.artifactName);
             }
             return currentVersion !== null && isOlderManagedVersion(hit.version, currentVersion);
@@ -583,7 +631,11 @@ export const refreshHandler = {
         }
         let staleAgentRemovals = [];
         let trackedSkipped = [];
-        if (!dryRun && deploymentFailures.length === 0) {
+        // A dry run still reports what a real run would remove. Skipping the pass
+        // entirely meant `refresh --dry-run` printed "Checking for stale deployments..."
+        // and nothing else, so orphaned artifacts were invisible until they had
+        // pushed the project over its context budget (#2540).
+        if (deploymentFailures.length === 0) {
             try {
                 const pruneResult = await pruneStaleManagedAgentFiles({
                     projectRoot: ctx.cwd,
@@ -591,6 +643,7 @@ export const refreshHandler = {
                     provider: detectedProvider,
                     crossProvider: pruneOtherProviders ? 'prune' : 'skip',
                     allowTrackedDeletes: pruneTracked,
+                    dryRun,
                 });
                 staleAgentRemovals = pruneResult.removals;
                 trackedSkipped = pruneResult.trackedSkipped;
@@ -607,19 +660,24 @@ export const refreshHandler = {
                 }
                 if (staleAgentRemovals.length > 0 && !quiet) {
                     const total = staleAgentRemovals.reduce((sum, item) => sum + item.paths.length, 0);
-                    ui.warn(`Removed ${total} stale AIWG-managed file${total === 1 ? '' : 's'} ` +
+                    ui.warn(`${dryRun ? 'Would remove' : 'Removed'} ${total} stale AIWG-managed file${total === 1 ? '' : 's'} ` +
                         `across ${staleAgentRemovals.length} provider${staleAgentRemovals.length === 1 ? '' : 's'}`);
                     for (const removal of staleAgentRemovals) {
                         const shown = removal.paths.slice(0, 3).join(', ');
                         const remainder = removal.paths.length - 3;
                         ui.dim(`    ${removal.provider}: ${removal.paths.length} (${shown}${remainder > 0 ? `, ...and ${remainder} more` : ''})`);
                     }
-                    ui.dim('    Review `git status` before committing — deployed artifacts may be tracked.');
+                    ui.dim(dryRun
+                        ? '    Re-run without --dry-run to remove them.'
+                        : '    Review `git status` before committing — deployed artifacts may be tracked.');
                 }
                 // #2506: keep the recorded deployment state consistent with what the
                 // prune actually left on disk, so a later run does not trust counts
-                // for artifacts that no longer exist.
-                await reconcileDeployedToAfterPrune(ctx.cwd, staleAgentRemovals, pruneOtherProviders ? detectedProvider : null);
+                // for artifacts that no longer exist. A dry run deleted nothing, so the
+                // recorded state is already accurate.
+                if (!dryRun) {
+                    await reconcileDeployedToAfterPrune(ctx.cwd, staleAgentRemovals, pruneOtherProviders ? detectedProvider : null);
+                }
             }
             catch {
                 if (!quiet)
@@ -685,7 +743,9 @@ export const refreshHandler = {
                         // #2506: a run that deleted artifacts is not an "up to date" run.
                         const removed = staleAgentRemovals.reduce((sum, item) => sum + item.paths.length, 0);
                         if (!quiet) {
-                            ui.warn(`Deployments current, but ${removed} stale artifact(s) were removed this run — review the list above`);
+                            ui.warn(dryRun
+                                ? `Deployments current, but ${removed} stale artifact(s) would be removed — review the list above`
+                                : `Deployments current, but ${removed} stale artifact(s) were removed this run — review the list above`);
                         }
                     }
                     else {