@aiwg/cli 2026.9.7 → 2026.9.10

package/bin/aiwg.mjs

@@ -166,11 +166,12 @@ const FAST_HELP_TEXT = `
   PROMOTE
     promote <name>               Graduate project-local bundle to upstream (--to upstream|corpus, --dry-run, --cleanup)
 
-  RALPH LOOP
-    ralph "<task>"               Execute iterative task loop (--completion, --max-iterations)
-    ralph-status                 Check current loop status
-    ralph-abort                  Abort running loop
-    ralph-resume                 Resume interrupted loop
+  AGENT LOOP
+    agent-loop "<task>"          Execute iterative task loop (--completion, --max-iterations)
+    agent-loop-status            Check current loop status
+    agent-loop-abort             Abort running loop
+    agent-loop-resume            Resume interrupted loop
+                                 (legacy ralph* names remain accepted as aliases)
 
   MAINTENANCE
     doctor                       Check installation health
@@ -382,6 +383,29 @@ async function applyVerbosityFromArgs(args, routerPath) {
   return level;
 }
 
+/**
+ * Commands that only read state and therefore stay available while the
+ * recorded installation identity disagrees with the executing checkout
+ * (#2559). Everything else fails closed until the operator adopts or
+ * switches the identity. `index` is limited to its inspection subcommands;
+ * `index build` rewrites the capability index and is treated as a write.
+ */
+const RECOVERY_SAFE_COMMANDS = new Set([
+  'version', 'status', 'doctor', 'runtime-info', 'discover', 'show', 'help',
+]);
+const RECOVERY_SAFE_INDEX_SUBCOMMANDS = new Set(['query', 'deps', 'stats']);
+
+function isRecoverySafeCommand(args) {
+  const command = args.find((arg) => !arg.startsWith('-'));
+  if (!command) return false;
+  if (RECOVERY_SAFE_COMMANDS.has(command)) return true;
+  if (command === 'index') {
+    const sub = args.slice(args.indexOf(command) + 1).find((arg) => !arg.startsWith('-'));
+    return sub !== undefined && RECOVERY_SAFE_INDEX_SUBCOMMANDS.has(sub);
+  }
+  return false;
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -423,11 +447,32 @@ async function main() {
     }
     const { assertCanonicalInstallation } = await import(pathToFileURL(identityPath).href);
     const readOnlyPreview = args.includes('--dry-run');
-    assertCanonicalInstallation({
-      actualRoot: activePackageRoot,
-      createIfMissing: !readOnlyPreview,
-      allowUnrecorded: readOnlyPreview,
-    });
+    try {
+      assertCanonicalInstallation({
+        actualRoot: activePackageRoot,
+        createIfMissing: !readOnlyPreview,
+        allowUnrecorded: readOnlyPreview,
+      });
+    } catch (error) {
+      if (error?.code !== 'AIWG_INSTALLATION_DRIFT' || !isRecoverySafeCommand(args)) throw error;
+      // Read-only diagnostics stay reachable under drift so the documented
+      // recovery ladder (status → doctor → runtime-info → version → local
+      // discover) can run before the identity is repaired. Every mutating
+      // command still fails closed above (#2559).
+      const drift = Array.isArray(error.status?.drift) ? error.status.drift : [];
+      process.env['AIWG_INSTALLATION_DRIFT'] = JSON.stringify({
+        state: error.status?.state ?? 'mismatch',
+        drift,
+      });
+      process.stderr.write(
+        `aiwg: warning: installation identity drift detected; \`${args[0]}\` is read-only and continues, ` +
+        'but update, refresh, and deployment stay blocked until the identity is repaired.\n' +
+        drift.map((item) => `- ${item}\n`).join('') +
+        'Inspect: aiwg installation show\n' +
+        'Adopt this installation: aiwg installation adopt\n' +
+        'Switch deliberately: aiwg installation switch --root <path> --method <npm|web|source> [--manager <absolute-path>]\n',
+      );
+    }
   }
 
   // Wire up the logger level from -v/-vv/--quiet/AIWG_LOG_LEVEL before any

package/dist/src/artifacts/cli.js

@@ -1374,6 +1374,10 @@ async function handleSetQuery(args) {
         backend,
     });
 }
+/** `index discover` flags that consume the following argument as a value. */
+const DISCOVER_VALUE_FLAGS = new Set([
+    '--type', '--limit', '--format', '--graph', '--backend', '--resource-source', '--aiwg-version',
+]);
 /**
  * Handle 'index discover' command — capability-search for AIWG operational
  * assets.
@@ -1391,17 +1395,25 @@ async function handleSetQuery(args) {
 async function handleDiscover(args) {
     const { discoverCapability } = await import('./query-engine.js');
     const cwd = process.cwd();
-    // Parse positional phrase (everything before flags)
+    // Parse the positional phrase. Flags may appear before or after it — the
+    // documented local-backend fallback is written flag-first
+    // (`aiwg discover --backend local "<phrase>"`, #2530), so a phrase after a
+    // value flag must not be swallowed as that flag's argument (#2559).
     const textParts = [];
     const flags = [];
-    let inFlags = false;
-    for (const arg of args) {
-        if (arg.startsWith('--'))
-            inFlags = true;
-        if (inFlags)
-            flags.push(arg);
-        else
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith('--')) {
             textParts.push(arg);
+            continue;
+        }
+        flags.push(arg);
+        const bare = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+        const next = args[index + 1];
+        if (DISCOVER_VALUE_FLAGS.has(bare) && !arg.includes('=') && next !== undefined && !next.startsWith('--')) {
+            flags.push(next);
+            index += 1;
+        }
     }
     const phrase = textParts.join(' ').trim();
     if (!phrase) {

package/dist/src/artifacts/corpus-views/taxonomies.js

@@ -110,7 +110,7 @@ export const PIPELINE_STAGES = [
     ['4. Mixture-of-Experts & Sparse Architectures', 'Sparsely activated models as a parallel pretraining strategy.', ['REF-007']],
     ['5. Instruction Tuning & SFT', 'Supervised fine-tuning on instructions to convert base models into assistants.', ['REF-055', 'REF-435', 'REF-470']],
     ['6. RLHF, DPO, and Preference Optimization', 'Aligning models with human and AI feedback.', ['REF-025', 'REF-055', 'REF-449']],
-    ['7. RLVR & Reasoning RL', 'Verifiable-reward RL for reasoning, math, and code.', ['REF-819', 'REF-957', 'REF-457']],
+    ['7. RLVR & Reasoning RL', 'Verifiable-reward RL for reasoning, math, and code.', ['REF-394', 'REF-957', 'REF-457']],
     ['8. PEFT / LoRA / Adapter-Based Adaptation', 'Parameter-efficient fine-tuning when full SFT is impractical.', ['REF-049']],
     ['9. Quantization, Pruning & Compression', 'Shrinking trained models for inference deployment.', ['REF-051']],
     ['10. Inference Serving & Optimization', 'Productionizing trained models: batching, KV cache, throughput.', ['REF-101', 'REF-102', 'REF-312', 'REF-313']],

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

@@ -134,11 +134,12 @@ function displayHelp() {
     helpGroup('PROMOTE', [
         ['promote <name>', 'Graduate project-local bundle to upstream (--to upstream|corpus, --dry-run, --cleanup)'],
     ]);
-    helpGroup('RALPH LOOP', [
-        ['ralph "<task>"', 'Execute iterative task loop (--completion, --max-iterations)'],
-        ['ralph-status', 'Check current loop status'],
-        ['ralph-abort', 'Abort running loop'],
-        ['ralph-resume', 'Resume interrupted loop'],
+    helpGroup('AGENT LOOP', [
+        ['agent-loop "<task>"', 'Execute iterative task loop (--completion, --max-iterations)'],
+        ['agent-loop-status', 'Check current loop status'],
+        ['agent-loop-abort', 'Abort running loop'],
+        ['agent-loop-resume', 'Resume interrupted loop'],
+        ['', 'Legacy ralph* names remain accepted as aliases'],
     ]);
     helpGroup('MAINTENANCE', [
         ['doctor', 'Check installation health'],

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

@@ -17,6 +17,7 @@ import readline from 'readline';
 import { readAiwgConfig, writeAiwgConfig, emptyConfig, populateDeployedTo, VALID_PROVIDERS, getConfigPath, } from '../../config/aiwg-config.js';
 import * as ui from '../ui.js';
 import { askString as sharedAskString, askYesNo as sharedAskYesNo } from '../prompt-utils.js';
+import { normalizeProviderDefinitionId } from '../../providers/provider-definitions.js';
 import { writeNormalizedAiwgMd } from '../../smiths/context-pipeline/finalization.js';
 import { ensureWorkspaceContext } from '../../smiths/context-pipeline/workspace-context.js';
 const PROVIDER_LABELS = {
@@ -61,9 +62,13 @@ async function askProviders(rl, signal) {
         const num = parseInt(part, 10);
         if (!isNaN(num) && num >= 1 && num <= VALID_PROVIDERS.length) {
             selected.push(VALID_PROVIDERS[num - 1]);
+            continue;
         }
-        else if (VALID_PROVIDERS.includes(part)) {
-            selected.push(part);
+        // Accept canonical ids and registered aliases (e.g. `dsh` for
+        // `deepseek-harness`) so the picker honours the same names as `--provider`.
+        const canonical = normalizeProviderDefinitionId(part);
+        if (canonical && VALID_PROVIDERS.includes(canonical)) {
+            selected.push(canonical);
         }
         else {
             ui.warn(`  Unknown provider '${part}' — skipped`);

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/ralph.js

@@ -156,7 +156,7 @@ export class RalphHandler {
     name = 'Agent Loop';
     description = 'Execute iterative task loop with automatic completion detection';
     category = 'ralph';
-    aliases = ['ralph', '-ralph', '--ralph'];
+    aliases = ['agent-loop', '--agent-loop', 'ralph', '-ralph', '--ralph'];
     async execute(ctx) {
         const parsed = parseRalphArgs(ctx.args);
         // Show help
@@ -334,7 +334,7 @@ export class RalphStatusHandler {
     name = 'Ralph Status';
     description = 'Show Agent loop status and iteration history';
     category = 'ralph';
-    aliases = ['ralph-status'];
+    aliases = ['agent-loop-status', 'ralph-status'];
     async execute(ctx) {
         const showAll = ctx.args.includes('--all') || ctx.args.includes('-a');
         const statuses = getLoopStatuses(process.cwd());
@@ -402,7 +402,7 @@ export class RalphAbortHandler {
     name = 'Ralph Abort';
     description = 'Abort currently running Agent loop';
     category = 'ralph';
-    aliases = ['ralph-abort'];
+    aliases = ['agent-loop-abort', 'ralph-abort'];
     async execute(ctx) {
         // Parse --loop-id if provided
         let loopId;
@@ -428,7 +428,7 @@ export class RalphResumeHandler {
     name = 'Ralph Resume';
     description = 'Resume previously aborted Agent loop';
     category = 'ralph';
-    aliases = ['ralph-resume'];
+    aliases = ['agent-loop-resume', 'ralph-resume'];
     async execute(ctx) {
         // Parse arguments
         let loopId;
@@ -493,7 +493,7 @@ export const ralphExternalHandler = {
     name: 'Agent Loop External',
     description: 'Crash-resilient external loop with state persistence and CI/CD integration',
     category: 'ralph',
-    aliases: ['ralph-external', '--ralph-external', '--agent-loop-ext'],
+    aliases: ['agent-loop-ext', '--agent-loop-ext', 'ralph-external', '--ralph-external'],
     async execute(ctx) {
         const runner = createScriptRunner(ctx.frameworkRoot);
         // Delegate to the external Ralph supervisor script
@@ -510,7 +510,7 @@ export const ralphMemoryHandler = {
     name: 'Ralph Memory',
     description: 'Manage Ralph semantic memory entries (list, query, clear)',
     category: 'ralph',
-    aliases: ['--ralph-memory'],
+    aliases: ['--agent-loop-memory', '--ralph-memory'],
     async execute(ctx) {
         const runner = createScriptRunner(ctx.frameworkRoot);
         return runner.run('tools/ralph-external/memory-manager.mjs', ['--cli', ...ctx.args]);
@@ -526,7 +526,7 @@ export const ralphConfigHandler = {
     name: 'Ralph Config',
     description: 'View and configure Agent loop settings (show, set, reset, preset)',
     category: 'ralph',
-    aliases: ['--ralph-config'],
+    aliases: ['--agent-loop-config', '--ralph-config'],
     async execute(ctx) {
         const runner = createScriptRunner(ctx.frameworkRoot);
         return runner.run('tools/ralph-external/orchestrator.mjs', ['--config', ...ctx.args]);
@@ -543,7 +543,7 @@ export class RalphAttachHandler {
     name = 'Ralph Attach';
     description = 'Attach to a running Agent loop\'s live output stream';
     category = 'ralph';
-    aliases = ['ralph-attach'];
+    aliases = ['agent-loop-attach', 'ralph-attach'];
     async execute(ctx) {
         let loopId;
         const loopIdIndex = ctx.args.indexOf('--loop-id');