@aiwg/cli 2026.8.7 → 2026.8.10

package/dist/src/config/aiwg-config.js

@@ -10,11 +10,11 @@
  */
 import { readFile, writeFile, mkdir, access, readdir, rename, unlink } from 'fs/promises';
 import { createHash, randomBytes } from 'crypto';
-import { resolve, join, isAbsolute } from 'path';
+import { resolve, join, dirname, isAbsolute } from 'path';
 import { normalizeNamedCaptures } from '../artifacts/index-builder.js';
 import { getProviderDefinition, getProviderKernelSkillPath, PROVIDER_IDS, resolveProviderPathValue, } from '../providers/provider-definitions.js';
 import { validateAuthorization, } from '../policy/authorization.js';
-import { projectAiwgPath, resolveProjectAiwgDir } from './project-artifacts.js';
+import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from './project-artifacts.js';
 import { defaultThreatAssessmentConfig, validateThreatAssessmentConfig, } from '../security/threat-assessment-config.js';
 const CONFIG_FILENAME = 'aiwg.config';
 /**
@@ -658,11 +658,11 @@ export function emptyConfig(providers = ['claude']) {
 /**
  * Resolve path to the project-level AIWG config.
  *
- * Defaults to `<project>/.aiwg/aiwg.config`; honors `AIWG_ARTIFACTS_PATH` so
- * projects can rename or relocate the AIWG artifact directory.
+ * The config is part of the repository-local control plane. Relocating the
+ * artifact corpus does not relocate this path.
  */
 export function getConfigPath(projectDir) {
-    return projectAiwgPath(projectDir, CONFIG_FILENAME);
+    return projectControlPath(projectDir, CONFIG_FILENAME);
 }
 /**
  * Resolve the project directory for a handler invocation.
@@ -685,12 +685,22 @@ export function getProjectDir(ctx, args = []) {
  * Returns null if the file does not exist.
  */
 export async function readAiwgConfig(projectDir) {
-    const filePath = getConfigPath(projectDir);
+    const localPath = getConfigPath(projectDir);
+    const artifactPath = projectAiwgPath(projectDir, CONFIG_FILENAME);
+    let filePath = localPath;
     try {
-        await access(filePath);
+        await access(localPath);
     }
     catch {
-        return null;
+        if (artifactPath === localPath)
+            return null;
+        try {
+            await access(artifactPath);
+            filePath = artifactPath;
+        }
+        catch {
+            return null;
+        }
     }
     const content = await readFile(filePath, 'utf-8');
     const parsed = JSON.parse(content);
@@ -722,34 +732,51 @@ export async function readAiwgConfig(projectDir) {
     return parsed;
 }
 /**
- * Write aiwg.config, creating the resolved AIWG artifact directory if needed.
+ * Write aiwg.config to the repository-local control plane. When a reachable
+ * external corpus also carries the compatibility control copy, keep it in
+ * sync so split-root health remains deterministic.
  */
 export async function writeAiwgConfig(projectDir, config) {
     const threatAssessmentErrors = validateThreatAssessmentConfig(config.security?.threatAssessment);
     if (threatAssessmentErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${threatAssessmentErrors.join('\n')}`);
     }
-    const dir = resolveProjectAiwgDir(projectDir);
-    await mkdir(dir, { recursive: true });
-    const filePath = join(dir, CONFIG_FILENAME);
-    // Atomic write: emit to a temp sibling, fsync-ish via rename. Prevents a
-    // crash or kill mid-write from corrupting the config file. Rename is
-    // atomic on POSIX and on NTFS when both paths are on the same volume.
-    // The random suffix avoids collisions if two concurrent writers run.
-    const tmpPath = `${filePath}.${randomBytes(6).toString('hex')}.tmp`;
-    try {
-        await writeFile(tmpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-        await rename(tmpPath, filePath);
-    }
-    catch (err) {
-        // Best-effort cleanup of the temp file on failure, ignoring ENOENT.
+    const localPath = getConfigPath(projectDir);
+    const artifactDir = resolveProjectAiwgDir(projectDir);
+    const artifactPath = join(artifactDir, CONFIG_FILENAME);
+    const content = JSON.stringify(config, null, 2) + '\n';
+    const writeAtomic = async (filePath) => {
+        await mkdir(dirname(filePath), { recursive: true });
+        // Atomic write: emit to a temp sibling, fsync-ish via rename. Prevents a
+        // crash or kill mid-write from corrupting the config file. Rename is
+        // atomic on POSIX and on NTFS when both paths are on the same volume.
+        // The random suffix avoids collisions if two concurrent writers run.
+        const tmpPath = `${filePath}.${randomBytes(6).toString('hex')}.tmp`;
         try {
-            await unlink(tmpPath);
+            await writeFile(tmpPath, content, 'utf-8');
+            await rename(tmpPath, filePath);
         }
-        catch {
-            /* ignore */
+        catch (err) {
+            // Best-effort cleanup of the temp file on failure, ignoring ENOENT.
+            try {
+                await unlink(tmpPath);
+            }
+            catch {
+                /* ignore */
+            }
+            throw err;
+        }
+    };
+    await writeAtomic(localPath);
+    if (artifactPath !== localPath) {
+        try {
+            await access(artifactDir);
+            await writeAtomic(artifactPath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
         }
-        throw err;
     }
 }
 /**

package/dist/src/config/cli.js

@@ -21,7 +21,7 @@ import { fileURLToPath } from 'url';
 import path from 'path';
 import { UserConfig } from './user-config.js';
 import { AiwgError, EXIT_CODES } from '../cli/errors.js';
-import { projectAiwgPath, resolveProjectAiwgDir } from './project-artifacts.js';
+import { projectControlPath, resolveProjectAiwgDir } from './project-artifacts.js';
 const _scriptDir = path.dirname(fileURLToPath(import.meta.url));
 /**
  * Main CLI entry point for `aiwg config <subcommand> [args]`
@@ -417,7 +417,7 @@ async function handleProjectValidate(args) {
             ? validateIssueLabels(cfg.issues)
             : resolveIssueLabels(undefined, 'local').diagnostics;
     const diagnostics = [...indexErrors, ...externalLinkErrors, ...labelDiagnostics];
-    console.log(`Project config: ${projectAiwgPath(projectDir, 'aiwg.config')}`);
+    console.log(`Project config: ${projectControlPath(projectDir, 'aiwg.config')}`);
     console.log(`Artifact root:  ${resolveProjectAiwgDir(projectDir)}\n`);
     if (diagnostics.length === 0) {
         console.log('✓ Project config valid');
@@ -608,7 +608,7 @@ For project-level config: aiwg config show --project [--json]
         return;
     }
     // Human-readable view
-    console.log(`Project config: ${projectAiwgPath(projectDir, 'aiwg.config')}`);
+    console.log(`Project config: ${projectControlPath(projectDir, 'aiwg.config')}`);
     console.log(`Artifact root:  ${resolveProjectAiwgDir(projectDir)}\n`);
     console.log(`Schema version: ${cfg.version}`);
     console.log(`Providers:      ${cfg.providers.join(', ') || '(none)'}`);

package/dist/src/config/project-artifacts-health.js

@@ -0,0 +1,2 @@
+export { PROJECT_CONTROL_PLANE_FILES, auditProjectArtifactHealth, } from './project-artifacts-health.mjs';
+//# sourceMappingURL=project-artifacts-health.js.map

package/dist/src/config/project-artifacts-health.mjs

@@ -0,0 +1,123 @@
+/**
+ * Deterministic health audit for projects whose artifact corpus is external.
+ *
+ * The repository-local `.aiwg` directory is the control plane. The configured
+ * artifact root is the corpus. This audit deliberately does not mutate either.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import {
+  DEFAULT_PROJECT_AIWG_DIR,
+  PROJECT_AIWG_LOCATION_FILE,
+  readProjectArtifactLocation,
+  resolveProjectAiwgDir,
+} from './project-artifacts-runtime.mjs';
+
+export const PROJECT_CONTROL_PLANE_FILES = Object.freeze([
+  'AIWG.md',
+  'aiwg.config',
+  join('frameworks', 'registry.json'),
+]);
+
+const ARTIFACT_ENV_KEYS = [
+  'AIWG_ARTIFACTS_PATH',
+  'AIWG_PROJECT_ARTIFACTS_PATH',
+  'AIWG_PROJECT_AIWG_DIR',
+];
+
+function configuredSource(projectDir, env) {
+  for (const key of ARTIFACT_ENV_KEYS) {
+    if (typeof env[key] === 'string' && env[key].trim()) return { kind: 'environment', key };
+  }
+  if (readProjectArtifactLocation(projectDir)) return { kind: 'pointer', path: join(projectDir, PROJECT_AIWG_LOCATION_FILE) };
+  return { kind: 'default' };
+}
+
+function listFiles(root) {
+  if (!existsSync(root) || !statSync(root).isDirectory()) return [];
+  const files = [];
+  const visit = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const absolute = join(dir, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) files.push(relative(root, absolute));
+    }
+  };
+  visit(root);
+  return files.sort();
+}
+
+function sameFile(left, right) {
+  return existsSync(left) && existsSync(right) && readFileSync(left).equals(readFileSync(right));
+}
+
+export function auditProjectArtifactHealth(projectDir, env = process.env) {
+  const root = resolve(projectDir);
+  const localRoot = join(root, DEFAULT_PROJECT_AIWG_DIR);
+  const artifactRoot = resolveProjectAiwgDir(root, env);
+  const source = configuredSource(root, env);
+  const externalConfigured = resolve(localRoot) !== resolve(artifactRoot);
+  const externalReachable = existsSync(artifactRoot) && statSync(artifactRoot).isDirectory();
+
+  const controls = PROJECT_CONTROL_PLANE_FILES.map((file) => {
+    const localPath = join(localRoot, file);
+    const externalPath = join(artifactRoot, file);
+    const local = existsSync(localPath);
+    const external = externalReachable && existsSync(externalPath);
+    return { file: file.split(sep).join('/'), local, external, identical: local && external ? sameFile(localPath, externalPath) : null };
+  });
+  const missingLocal = controls.filter((item) => !item.local).map((item) => item.file);
+  const divergentControl = controls.filter((item) => item.identical === false).map((item) => item.file);
+  const localPayload = listFiles(localRoot).filter((file) => !PROJECT_CONTROL_PLANE_FILES.includes(file));
+  const divergentPayload = externalReachable
+    ? localPayload.filter((file) => !sameFile(join(localRoot, file), join(artifactRoot, file)))
+    : [];
+
+  let classification = 'local';
+  let severity = 'ok';
+  let repairable = false;
+  let action = null;
+
+  if (externalConfigured) {
+    if (!externalReachable) {
+      classification = 'degraded-offline';
+      severity = missingLocal.length ? 'error' : 'warning';
+      action = 'Reconnect or attach the external corpus, then run `aiwg artifacts repair --dry-run`.';
+    } else if (missingLocal.length) {
+      classification = 'legacy-missing-control-plane';
+      severity = 'error';
+      repairable = controls.filter((item) => !item.local).every((item) => item.external);
+      action = 'Run `aiwg artifacts repair --dry-run`, then `aiwg artifacts repair --apply` after reviewing the plan.';
+    } else if (divergentControl.length || divergentPayload.length) {
+      classification = 'duplicated-divergent';
+      severity = 'error';
+      action = 'Reconcile the reported local and external files manually; no automatic repair will overwrite divergent content.';
+    } else if (localPayload.length) {
+      classification = 'duplicated-identical';
+      severity = 'warning';
+      repairable = true;
+      action = 'Run `aiwg artifacts repair --dry-run`, then `aiwg artifacts repair --apply` to remove identical local corpus duplicates.';
+    } else {
+      classification = 'healthy-split-root';
+      severity = 'ok';
+    }
+  }
+
+  return {
+    classification,
+    severity,
+    external_configured: externalConfigured,
+    source,
+    local_control_root: localRoot,
+    artifact_root: artifactRoot,
+    external_reachable: externalReachable,
+    control_files: controls,
+    missing_local_control_files: missingLocal,
+    divergent_control_files: divergentControl,
+    duplicated_local_corpus_files: localPayload.map((file) => file.split(sep).join('/')),
+    divergent_local_corpus_files: divergentPayload.map((file) => file.split(sep).join('/')),
+    repairable,
+    action,
+  };
+}

package/dist/src/config/project-artifacts-runtime.mjs

@@ -63,6 +63,22 @@ export function resolveProjectAiwgDir(projectDir, env = process.env) {
   return resolve(projectDir, DEFAULT_PROJECT_AIWG_DIR);
 }
 
+/**
+ * Resolve the repository-local AIWG control plane.
+ *
+ * `.aiwg-location` and the artifact path environment variables relocate the
+ * potentially large artifact corpus. They do not relocate the small control
+ * plane required to open and operate the repository while that corpus is
+ * offline.
+ */
+export function resolveProjectControlDir(projectDir) {
+  return resolve(projectDir, DEFAULT_PROJECT_AIWG_DIR);
+}
+
 export function projectAiwgPath(projectDir, ...segments) {
   return join(resolveProjectAiwgDir(projectDir), ...segments);
 }
+
+export function projectControlPath(projectDir, ...segments) {
+  return join(resolveProjectControlDir(projectDir), ...segments);
+}

package/dist/src/config/project-artifacts.js

@@ -5,5 +5,6 @@
  * override for the project-local `.aiwg/` artifact root. Keep that contract
  * centralized so callers do not hardcode `<project>/.aiwg`.
  */
-export { AIWG_ARTIFACTS_PATH_ENV, DEFAULT_PROJECT_AIWG_DIR, PROJECT_AIWG_LOCATION_FILE, expandProjectArtifactPath, parseProjectArtifactLocation, projectAiwgPath, readProjectArtifactLocation, resolveProjectAiwgDir, } from './project-artifacts-runtime.mjs';
+export { AIWG_ARTIFACTS_PATH_ENV, DEFAULT_PROJECT_AIWG_DIR, PROJECT_AIWG_LOCATION_FILE, expandProjectArtifactPath, parseProjectArtifactLocation, projectAiwgPath, projectControlPath, readProjectArtifactLocation, resolveProjectAiwgDir, resolveProjectControlDir, } from './project-artifacts-runtime.mjs';
+export { PROJECT_CONTROL_PLANE_FILES, auditProjectArtifactHealth, } from './project-artifacts-health.mjs';
 //# sourceMappingURL=project-artifacts.js.map

package/dist/src/cost/fleet-report.js

@@ -0,0 +1,329 @@
+/**
+ * OpenRouter fleet spend observation and local activity correlation.
+ *
+ * Secrets are resolved only from the process environment or the user's
+ * ~/.config/aiwg/keys directory. Fleet configuration contains references,
+ * never credential values.
+ *
+ * @issue #1187
+ */
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { load as loadYaml } from 'js-yaml';
+const OPENROUTER_API = 'https://openrouter.ai/api/v1';
+const KEY_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SECRET_FIELD_PATTERN = /(?:api[_-]?key|token|secret|credential|authorization)/i;
+const GENERATION_ID_PATTERN = /(?:generation(?:_id|-id)?)[=:]\s*(gen-[A-Za-z0-9_-]+)/i;
+const TAG_PATTERN = (name) => new RegExp(`${name}[=:]\\s*([A-Za-z0-9._/-]+)`, 'i');
+export class FleetConfigMissingError extends Error {
+    configPath;
+    constructor(configPath) {
+        super(`No fleet config found at ${configPath}. Create it with a top-level fleet list; `
+            + 'store only key_ref values there, and place credentials in ~/.config/aiwg/keys/ or AIWG_OPENROUTER_KEY_* environment variables.');
+        this.configPath = configPath;
+        this.name = 'FleetConfigMissingError';
+    }
+}
+function hasEmbeddedSecret(value) {
+    if (typeof value === 'string')
+        return /^sk-or-/i.test(value.trim());
+    if (Array.isArray(value))
+        return value.some(hasEmbeddedSecret);
+    if (!value || typeof value !== 'object')
+        return false;
+    return Object.entries(value).some(([key, child]) => ((key !== 'key_ref' && SECRET_FIELD_PATTERN.test(key)) || hasEmbeddedSecret(child)));
+}
+function validateFleetConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Fleet config must be a YAML object.');
+    }
+    if (hasEmbeddedSecret(value)) {
+        throw new Error('Fleet config contains a credential-like field or value; store only key_ref values.');
+    }
+    const candidate = value;
+    if (candidate.provider && candidate.provider !== 'openrouter') {
+        throw new Error(`Unsupported fleet provider '${candidate.provider}'. Only openrouter is currently supported.`);
+    }
+    if (!Array.isArray(candidate.fleet) || candidate.fleet.length === 0) {
+        throw new Error('Fleet config must contain a non-empty fleet list.');
+    }
+    const seenBots = new Set();
+    const seenKeyRefs = new Set();
+    const fleet = candidate.fleet.map((raw, index) => {
+        if (!raw || typeof raw !== 'object')
+            throw new Error(`fleet[${index}] must be an object.`);
+        const entry = raw;
+        if (!entry.bot?.trim() || !entry.machine?.trim() || !entry.key_ref?.trim()) {
+            throw new Error(`fleet[${index}] requires bot, machine, and key_ref.`);
+        }
+        if (!KEY_REF_PATTERN.test(entry.key_ref)) {
+            throw new Error(`fleet[${index}].key_ref contains unsupported characters.`);
+        }
+        if (typeof entry.monthly_cap !== 'number' || !Number.isFinite(entry.monthly_cap) || entry.monthly_cap < 0) {
+            throw new Error(`fleet[${index}].monthly_cap must be a non-negative number.`);
+        }
+        if (seenBots.has(entry.bot))
+            throw new Error(`Duplicate fleet bot '${entry.bot}'.`);
+        if (seenKeyRefs.has(entry.key_ref))
+            throw new Error(`Duplicate fleet key_ref '${entry.key_ref}'.`);
+        seenBots.add(entry.bot);
+        seenKeyRefs.add(entry.key_ref);
+        return {
+            bot: entry.bot.trim(),
+            machine: entry.machine.trim(),
+            key_ref: entry.key_ref,
+            monthly_cap: entry.monthly_cap,
+        };
+    });
+    return {
+        provider: 'openrouter',
+        ...(typeof candidate.activity_log === 'string' ? { activity_log: candidate.activity_log } : {}),
+        fleet,
+    };
+}
+export async function loadFleetConfig(configPath) {
+    let raw;
+    try {
+        raw = await fs.readFile(configPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new FleetConfigMissingError(configPath);
+        throw error;
+    }
+    return validateFleetConfig(loadYaml(raw));
+}
+export function keyEnvironmentName(keyRef) {
+    return `AIWG_OPENROUTER_KEY_${keyRef.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+}
+export async function loadFleetKey(keyRef, options = {}) {
+    if (!KEY_REF_PATTERN.test(keyRef))
+        throw new Error('Invalid key_ref.');
+    const env = options.env ?? process.env;
+    const environmentName = keyEnvironmentName(keyRef);
+    const environmentValue = env[environmentName]?.trim();
+    if (environmentValue)
+        return environmentValue;
+    const homeDir = options.homeDir ?? os.homedir();
+    const keyDirectory = path.resolve(homeDir, '.config', 'aiwg', 'keys');
+    const keyPath = path.resolve(keyDirectory, keyRef);
+    if (path.dirname(keyPath) !== keyDirectory)
+        throw new Error(`Invalid key_ref '${keyRef}'.`);
+    let directoryStat;
+    try {
+        directoryStat = await fs.lstat(keyDirectory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`No secure credential directory exists for key_ref '${keyRef}'; use ${environmentName} or create ~/.config/aiwg/keys with mode 0700.`);
+        }
+        throw error;
+    }
+    if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+        throw new Error('The AIWG credential directory must be a regular directory, not a symlink.');
+    }
+    if ((directoryStat.mode & 0o077) !== 0) {
+        throw new Error('The AIWG credential directory must not be accessible by group or other users.');
+    }
+    if (typeof process.getuid === 'function' && directoryStat.uid !== process.getuid()) {
+        throw new Error('The AIWG credential directory must be owned by the current user.');
+    }
+    let stat;
+    try {
+        stat = await fs.lstat(keyPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`No credential found for key_ref '${keyRef}' in the secure key directory or ${environmentName}.`);
+        }
+        throw error;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error(`Credential for key_ref '${keyRef}' must be a regular file, not a symlink.`);
+    if ((stat.mode & 0o077) !== 0)
+        throw new Error(`Credential file for key_ref '${keyRef}' must not be accessible by group or other users.`);
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+        throw new Error(`Credential file for key_ref '${keyRef}' must be owned by the current user.`);
+    }
+    const value = (await fs.readFile(keyPath, 'utf8')).trim();
+    if (!value)
+        throw new Error(`Credential file for key_ref '${keyRef}' is empty.`);
+    return value;
+}
+function parseActivityLog(raw) {
+    const entries = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const generationId = line.match(GENERATION_ID_PATTERN)?.[1];
+        if (!generationId)
+            continue;
+        const bot = line.match(TAG_PATTERN('bot'))?.[1];
+        const session = line.match(TAG_PATTERN('session'))?.[1] ?? generationId;
+        entries.push({ id: generationId, ...(bot ? { bot } : {}), session });
+    }
+    return entries;
+}
+async function readActivityLog(file) {
+    try {
+        return parseActivityLog(await fs.readFile(file, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+function requestSignal(parent) {
+    const timeout = AbortSignal.timeout(15_000);
+    return parent ? AbortSignal.any([parent, timeout]) : timeout;
+}
+async function openRouterGet(endpoint, key, options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${options.apiBaseUrl ?? OPENROUTER_API}${endpoint}`, {
+        headers: { Authorization: `Bearer ${key}` },
+        signal: requestSignal(options.signal),
+    });
+    if (!response.ok)
+        throw new Error(`OpenRouter request failed with status ${response.status}.`);
+    const payload = await response.json();
+    if (!payload || typeof payload !== 'object' || !payload.data)
+        throw new Error('OpenRouter returned an invalid response.');
+    return payload.data;
+}
+function correlateGenerations(records) {
+    const sessions = new Map();
+    const breakdown = {};
+    for (const { activity, data } of records) {
+        const cost = Number(data.total_cost ?? data.usage ?? 0);
+        const current = sessions.get(activity.session) ?? { session: activity.session, cost: 0, generations: 0 };
+        current.cost += Number.isFinite(cost) ? cost : 0;
+        current.generations += 1;
+        sessions.set(activity.session, current);
+        const tier = data.service_tier || data.model || 'unknown';
+        breakdown[tier] = (breakdown[tier] ?? 0) + (Number.isFinite(cost) ? cost : 0);
+    }
+    return {
+        top_sessions: [...sessions.values()].sort((a, b) => b.cost - a.cost || a.session.localeCompare(b.session)).slice(0, 3),
+        model_tier_breakdown: Object.fromEntries(Object.entries(breakdown).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))),
+    };
+}
+async function reportBot(entry, activity, options) {
+    try {
+        const key = await loadFleetKey(entry.key_ref, options);
+        const keyData = await openRouterGet('/key', key, options);
+        const spend = Number(keyData.usage_monthly ?? keyData.usage ?? 0);
+        if (!Number.isFinite(spend) || spend < 0)
+            throw new Error('OpenRouter returned invalid monthly usage.');
+        const matching = activity.filter(item => item.bot === entry.bot || (!item.bot && options.fleet?.length === 1));
+        const unique = [...new Map(matching.map(item => [item.id, item])).values()].slice(0, 100);
+        const generationResults = await Promise.allSettled(unique.map(async (item) => ({
+            activity: item,
+            data: await openRouterGet(`/generation?id=${encodeURIComponent(item.id)}`, key, options),
+        })));
+        const now = options.now ?? new Date();
+        const monthStart = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1);
+        const monthEnd = Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1);
+        const generations = generationResults
+            .filter((result) => result.status === 'fulfilled')
+            .map(result => result.value)
+            .filter(({ data }) => {
+            if (!data.created_at)
+                return true;
+            const created = Date.parse(data.created_at);
+            return Number.isFinite(created) && created >= monthStart && created < monthEnd;
+        });
+        const correlated = correlateGenerations(generations);
+        const apiMonthlyCap = keyData.limit_reset === 'monthly' && typeof keyData.limit === 'number' ? keyData.limit : 0;
+        const cap = entry.monthly_cap > 0 ? entry.monthly_cap : apiMonthlyCap;
+        const percent = cap > 0 ? (spend / cap) * 100 : null;
+        const anomalies = [];
+        if (generationResults.some(result => result.status === 'rejected'))
+            anomalies.push('generation-correlation-partial');
+        if (percent !== null && percent >= 100)
+            anomalies.push('cap-exceeded');
+        else if (percent !== null && percent >= 80)
+            anomalies.push('cap-near-limit');
+        if (correlated.top_sessions[0] && spend > 0 && correlated.top_sessions[0].cost / spend >= 0.5) {
+            anomalies.push('single-session-spike');
+        }
+        return {
+            bot: entry.bot,
+            machine: entry.machine,
+            spend_mtd: spend,
+            cap,
+            percent_used: percent,
+            ...correlated,
+            anomalies,
+        };
+    }
+    catch (error) {
+        return {
+            bot: entry.bot,
+            machine: entry.machine,
+            spend_mtd: null,
+            cap: entry.monthly_cap,
+            percent_used: null,
+            top_sessions: [],
+            model_tier_breakdown: {},
+            anomalies: ['observation-error'],
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function generateFleetSpendReport(options) {
+    const homeDir = options.homeDir ?? os.homedir();
+    let fleet = options.fleet;
+    let configuredActivityLog;
+    if (!fleet) {
+        const configPath = options.configPath ?? path.join(homeDir, '.config', 'aiwg', 'fleet.yaml');
+        const config = await loadFleetConfig(configPath);
+        fleet = config.fleet;
+        configuredActivityLog = config.activity_log;
+    }
+    const activityLog = path.resolve(options.cwd, options.activityLog ?? configuredActivityLog ?? '.aiwg/activity.log');
+    const activity = await readActivityLog(activityLog);
+    const bots = await Promise.all(fleet.map(entry => reportBot(entry, activity, { ...options, homeDir })));
+    return {
+        source: 'openrouter',
+        observed_at: (options.now ?? new Date()).toISOString(),
+        enforcement: 'openrouter',
+        activity_log: activityLog,
+        bots,
+    };
+}
+function money(value) {
+    return value === null ? 'n/a' : `$${value.toFixed(2)}`;
+}
+export function formatFleetSpendReport(report) {
+    const headers = ['bot', 'machine', 'spend MTD', 'cap', '% used', 'top-3 expensive sessions'];
+    const rows = report.bots.map(bot => [
+        bot.bot,
+        bot.machine,
+        money(bot.spend_mtd),
+        money(bot.cap),
+        bot.percent_used === null ? 'n/a' : `${bot.percent_used.toFixed(1)}%`,
+        bot.top_sessions.length
+            ? bot.top_sessions.map(session => `${session.session} (${money(session.cost)})`).join(', ')
+            : '—',
+    ]);
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map(row => row[index].length)));
+    const line = (cells) => cells.map((cell, index) => cell.padEnd(widths[index])).join(' | ');
+    const output = [
+        'OpenRouter Fleet Cost Report',
+        `Observed: ${report.observed_at}`,
+        'AIWG observes and correlates spend; OpenRouter enforces all key limits and caps.',
+        '',
+        line(headers),
+        widths.map(width => '-'.repeat(width)).join('-|-'),
+        ...rows.map(line),
+    ];
+    for (const bot of report.bots) {
+        if (bot.anomalies.length)
+            output.push(`! ${bot.bot}: ${bot.anomalies.join(', ')}${bot.error ? ` (${bot.error})` : ''}`);
+        const breakdown = Object.entries(bot.model_tier_breakdown);
+        if (breakdown.length)
+            output.push(`  ${bot.bot} model/tier: ${breakdown.map(([name, cost]) => `${name} ${money(cost)}`).join(', ')}`);
+    }
+    return output.join('\n');
+}
+//# sourceMappingURL=fleet-report.js.map