@aiwg/cli 2026.9.6 → 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/help.js

@@ -10,6 +10,7 @@
 import * as ui from '../ui.js';
 import { maybePrintCommunityFooter } from '../../community/footer.js';
 import { listProviderDefinitions } from '../../providers/provider-definitions.js';
+import { getCommandIds } from '../../extensions/commands/definitions.js';
 /**
  * Help command handler
  */
@@ -19,7 +20,12 @@ export const helpHandler = {
     description: 'Show CLI help message',
     category: 'maintenance',
     aliases: ['-h', '-help', '--help'],
-    async execute(_ctx) {
+    async execute(ctx) {
+        if (ctx.args.includes('--json')) {
+            // Canonical IDs only: aliases and example prose are not registry entries.
+            console.log(JSON.stringify({ schema: 'aiwg.command-registry.v1', commandIds: getCommandIds() }));
+            return { exitCode: 0 };
+        }
         displayHelp();
         return { exitCode: 0 };
     },

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

@@ -20,21 +20,93 @@ function display(status, json) {
     console.log(`Release channel:   ${status.identity?.channel ?? '(unrecorded)'}`);
     console.log(`Actual method:     ${status.actualMethod}`);
     console.log(`Actual root:       ${status.actualRoot}`);
+    console.log(`Framework root:    ${status.frameworkRoot}`);
+    if (status.launcher) {
+        console.log(`Launcher:          ${status.launcher.method} at ${status.launcher.root} (edge redirect — expected)`);
+    }
     if (status.drift.length > 0) {
         console.log('Drift:');
         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 = {
@@ -50,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 };
         }
@@ -62,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,
@@ -73,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

@@ -169,12 +169,15 @@ function hasFlag(args, flag) {
  * dispatch missions with no ceiling while the operator believed one applied
  * (#1770).
  */
-function parseNumberFlag(args, flag, invalidSink) {
-    const raw = parseFlag(args, flag);
-    if (raw === undefined)
+function parseNumberFlag(args, flag, invalidSink, integer = false) {
+    if (!args.some(arg => arg === flag || arg.startsWith(`${flag}=`)))
         return undefined;
-    const value = Number(raw);
-    if (!Number.isFinite(value) || value <= 0) {
+    const raw = parseFlag(args, flag);
+    // Presence and validity are distinct: a trailing flag must not silently
+    // disappear, and counter limits must not accept fractional/unsafe values.
+    const decimal = typeof raw === 'string' && /^[+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(raw);
+    const value = decimal ? Number(raw) : NaN;
+    if (!Number.isFinite(value) || value <= 0 || (integer && !Number.isSafeInteger(value))) {
         invalidSink?.push(`${flag} (got '${raw}')`);
         return undefined;
     }
@@ -225,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.
@@ -330,23 +339,13 @@ async function mcDispatch(ctx) {
     const completion = parseFlag(ctx.args, '--completion');
     const priority = parseFlag(ctx.args, '--priority') || 'normal';
     const invalidFlags = [];
-    const maxIterationsRaw = parseFlag(ctx.args, '--max-iterations');
-    let maxIterations = 10;
-    if (maxIterationsRaw !== undefined) {
-        const parsedIterations = parseInt(maxIterationsRaw, 10);
-        if (!Number.isFinite(parsedIterations) || parsedIterations <= 0) {
-            invalidFlags.push(`--max-iterations (got '${maxIterationsRaw}')`);
-        }
-        else {
-            maxIterations = parsedIterations;
-        }
-    }
-    const maxTotalTokens = parseNumberFlag(ctx.args, '--max-total-tokens', invalidFlags);
-    const maxOutputTokens = parseNumberFlag(ctx.args, '--max-output-tokens', invalidFlags);
-    const maxToolCalls = parseNumberFlag(ctx.args, '--max-tool-calls', invalidFlags);
+    const maxIterations = parseNumberFlag(ctx.args, '--max-iterations', invalidFlags, true) ?? 10;
+    const maxTotalTokens = parseNumberFlag(ctx.args, '--max-total-tokens', invalidFlags, true);
+    const maxOutputTokens = parseNumberFlag(ctx.args, '--max-output-tokens', invalidFlags, true);
+    const maxToolCalls = parseNumberFlag(ctx.args, '--max-tool-calls', invalidFlags, true);
     const maxTotalCost = parseNumberFlag(ctx.args, '--max-total-cost', invalidFlags);
     const maxWallClockMinutes = parseNumberFlag(ctx.args, '--max-wall-clock-minutes', invalidFlags);
-    const explorationQuota = parseNumberFlag(ctx.args, '--exploration-quota', invalidFlags);
+    const explorationQuota = parseNumberFlag(ctx.args, '--exploration-quota', invalidFlags, true);
     const budgetStopPolicyRaw = parseFlag(ctx.args, '--budget-stop-policy');
     let budgetStopPolicy;
     if (budgetStopPolicyRaw !== undefined) {
@@ -486,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];
@@ -500,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.');
@@ -538,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/ralph.js

@@ -13,6 +13,13 @@
 import { createScriptRunner } from './script-runner.js';
 import { launchExternalRalph, getLoopStatuses, abortLoop, resumeLoop, attachToLoopOutput, } from './ralph-launcher.js';
 import { handlerResultFromError } from '../errors.js';
+/** Parse a complete positive decimal value without truncating counter limits. */
+function parsePositiveLimit(raw, integer = false) {
+    if (typeof raw !== 'string' || !/^[+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(raw))
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 && (!integer || Number.isSafeInteger(value)) ? value : undefined;
+}
 /**
  * Parse Ralph command arguments
  */
@@ -22,8 +29,8 @@ function parseRalphArgs(args) {
     // Present-but-invalid numeric values are a hard usage error: an operator who
     // typed --max-total-cost expects a ceiling to exist (#1770).
     const positiveNumber = (flag, raw, integer = false) => {
-        const value = integer ? parseInt(raw ?? '', 10) : parseFloat(raw ?? '');
-        if (!Number.isFinite(value) || value <= 0) {
+        const value = parsePositiveLimit(raw, integer);
+        if (value === undefined) {
             result.invalidFlags.push(`${flag} (got '${raw ?? ''}')`);
             return undefined;
         }
@@ -431,8 +438,11 @@ export class RalphResumeHandler {
             if (arg === '--loop-id' && ctx.args[i + 1]) {
                 loopId = ctx.args[++i];
             }
-            else if (arg === '--max-iterations' && ctx.args[i + 1]) {
-                maxIterations = parseInt(ctx.args[++i], 10);
+            else if (arg === '--max-iterations') {
+                maxIterations = parsePositiveLimit(ctx.args[++i], true);
+                if (maxIterations === undefined) {
+                    return { exitCode: 1, message: 'Error: --max-iterations requires a positive safe integer. Loop not resumed.' };
+                }
             }
         }
         try {