@bouncesecurity/aghast 0.4.4 → 0.6.0

package/dist/discovery.js.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA6D5D,6BAA6B;AAE7B,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA2B,CAAC;AAE7D;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAA0B;IAC1D,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,SAAS,GAAG,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,WAAW,CAAC,WAAW,CAAC,KAAK,EAAE,4BAA4B,IAAI,iBAAiB,SAAS,IAAI,mBAAmB,EAAE,CAAC,CACpH,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA6D5D,6BAA6B;AAE7B,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA2B,CAAC;AAE7D;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAA0B;IAC1D,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,SAAS,GAAG,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,WAAW,CAAC,WAAW,CAAC,KAAK,EAAE,4BAA4B,IAAI,iBAAiB,SAAS,IAAI,mBAAmB,EAAE,CAAC,CACpH,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC"}

package/dist/error-codes.d.ts

@@ -4,7 +4,7 @@
  * Numbering scheme:
  *   E1xxx — CLI parsing (argument/flag/command errors)
  *   E2xxx — Configuration (config dir, checks, runtime config)
- *   E3xxx — AI provider
+ *   E3xxx — Agent provider
  *   E4xxx — Repository/target validation
  *   E5xxx — Semgrep
  *   E6xxx — OpenAnt
@@ -26,10 +26,12 @@ export declare const ERROR_CODES: {
     readonly E3001: ErrorCode;
     readonly E3002: ErrorCode;
     readonly E3003: ErrorCode;
+    readonly E3004: ErrorCode;
     readonly E4001: ErrorCode;
     readonly E5001: ErrorCode;
     readonly E6001: ErrorCode;
     readonly E6002: ErrorCode;
+    readonly E7001: ErrorCode;
     readonly E9001: ErrorCode;
 };
 /**

package/dist/error-codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;CA8Bd,CAAC;AAEX;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWzE"}
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;CAsCd,CAAC;AAEX;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWzE"}

package/dist/error-codes.js

@@ -4,7 +4,7 @@
  * Numbering scheme:
  *   E1xxx — CLI parsing (argument/flag/command errors)
  *   E2xxx — Configuration (config dir, checks, runtime config)
- *   E3xxx — AI provider
+ *   E3xxx — Agent provider
  *   E4xxx — Repository/target validation
  *   E5xxx — Semgrep
  *   E6xxx — OpenAnt
@@ -24,10 +24,15 @@ export const ERROR_CODES = {
     E2003: ec('E2003', 'No checks found'),
     E2004: ec('E2004', 'Invalid check definition'),
     E2005: ec('E2005', 'Configuration error'),
-    // E3xxx — AI provider
+    // E3xxx — Agent provider
     E3001: ec('E3001', 'API key missing'),
-    E3002: ec('E3002', 'Unknown AI provider'),
+    E3002: ec('E3002', 'Unknown agent provider'),
+    // E3003 retains "AI" intentionally: it refers to the file containing the
+    // mocked AI/LLM response body, not the agent harness. Same rationale as
+    // AGHAST_MOCK_AI / AGHAST_AI_MODEL — the model and its output are AI
+    // concerns; only the provider/harness layer was renamed to "agent".
     E3003: ec('E3003', 'Mock AI response file not found'),
+    E3004: ec('E3004', 'OpenCode not installed'),
     // E4xxx — Repository/target validation
     E4001: ec('E4001', 'Repository path not found'),
     // E5xxx — Semgrep
@@ -35,6 +40,8 @@ export const ERROR_CODES = {
     // E6xxx — OpenAnt
     E6001: ec('E6001', 'OpenAnt not installed'),
     E6002: ec('E6002', 'OpenAnt execution failed'),
+    // E7xxx — Budget / cost controls
+    E7001: ec('E7001', 'Budget limit exceeded'),
     // E9xxx — Internal
     E9001: ec('E9001', 'Fatal internal error'),
 };

package/dist/error-codes.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,SAAS,EAAE,CAAC,IAAY,EAAE,KAAa;IACrC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,sBAAsB;IACtB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,gCAAgC,CAAC;IACpD,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACrC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAE5C,wBAAwB;IACxB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,gCAAgC,CAAC;IACpD,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,oCAAoC,CAAC;IACxD,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACrC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAC9C,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,qBAAqB,CAAC;IAEzC,sBAAsB;IACtB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACrC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACzC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,iCAAiC,CAAC;IAErD,uCAAuC;IACvC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAE/C,kBAAkB;IAClB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAE3C,kBAAkB;IAClB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC3C,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAE9C,mBAAmB;IACnB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC;CAClC,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAoB,EAAE,OAAe;IAC/D,OAAO,UAAU,SAAS,CAAC,IAAI,MAAM,OAAO,EAAE,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,OAAe;IAC/D,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,kBAAkB,CAAC,gBAAgB,OAAO,mBAAmB,OAAO,EAAE,CAAC,CAAC;IACrF,MAAM,GAAG,GAAG,6DAA6D,KAAK,SAAS,IAAI,aAAa,CAAC;IACzG,OAAO;QACL,uBAAuB,WAAW,CAAC,KAAK,CAAC,IAAI,MAAM,OAAO,EAAE;QAC5D,YAAY,OAAO,EAAE;QACrB,EAAE;QACF,0CAA0C;QAC1C,KAAK,GAAG,EAAE;KACX,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,SAAS,EAAE,CAAC,IAAY,EAAE,KAAa;IACrC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,sBAAsB;IACtB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,gCAAgC,CAAC;IACpD,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACrC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAE5C,wBAAwB;IACxB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,gCAAgC,CAAC;IACpD,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,oCAAoC,CAAC;IACxD,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACrC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAC9C,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,qBAAqB,CAAC;IAEzC,yBAAyB;IACzB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACrC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC5C,yEAAyE;IACzE,wEAAwE;IACxE,qEAAqE;IACrE,oEAAoE;IACpE,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,iCAAiC,CAAC;IACrD,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAE5C,uCAAuC;IACvC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAE/C,kBAAkB;IAClB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAE3C,kBAAkB;IAClB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC3C,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAE9C,iCAAiC;IACjC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAE3C,mBAAmB;IACnB,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC;CAClC,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAoB,EAAE,OAAe;IAC/D,OAAO,UAAU,SAAS,CAAC,IAAI,MAAM,OAAO,EAAE,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,OAAe;IAC/D,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,kBAAkB,CAAC,gBAAgB,OAAO,mBAAmB,OAAO,EAAE,CAAC,CAAC;IACrF,MAAM,GAAG,GAAG,6DAA6D,KAAK,SAAS,IAAI,aAAa,CAAC;IACzG,OAAO;QACL,uBAAuB,WAAW,CAAC,KAAK,CAAC,IAAI,MAAM,OAAO,EAAE;QAC5D,YAAY,OAAO,EAAE;QACrB,EAAE;QACF,0CAA0C;QAC1C,KAAK,GAAG,EAAE;KACX,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/formatters/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Output formatter interface for scan results.
- * Follows the AIProvider interface pattern from src/types.ts.
+ * Follows the AgentProvider interface pattern from src/types.ts.
  */
 import type { ScanResults } from '../types.js';
 export interface OutputFormatter {

package/dist/formatters/types.js

@@ -1,6 +1,6 @@
 /**
  * Output formatter interface for scan results.
- * Follows the AIProvider interface pattern from src/types.ts.
+ * Follows the AgentProvider interface pattern from src/types.ts.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,eAAe,CAAC;AAmSvB,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+Q3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,eAAe,CAAC;AA4WvB,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuX3D"}

package/dist/index.js

@@ -5,18 +5,21 @@
 import 'dotenv/config';
 import { readFile, writeFile, stat, mkdir, readdir } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
-import { runMultiScan } from './scan-runner.js';
+import { runMultiScanWithCost } from './scan-runner.js';
+import { loadDefaultPricing, mergePricing, formatCostSourceLabel } from './cost-calculator.js';
+import { saveScanRecord, queryScanHistory } from './scan-history.js';
 import { createProviderByName, getProviderNames, DEFAULT_PROVIDER_NAME } from './provider-registry.js';
 import { loadCheckRegistry, discoverCheckFolders, resolveChecks, filterChecksForRepository, validateCheck, loadCheckDetails, } from './check-library.js';
 import { analyzeRepository } from './repository-analyzer.js';
 import { loadRuntimeConfig } from './runtime-config.js';
 import { logProgress, logDebug, setLogLevel, createTimer, isValidLogLevel, initFileHandler, closeAllHandlers, getAvailableLogTypes } from './logging.js';
-import { MOCK_MODEL_NAME, DEFAULT_AI_MODEL } from './types.js';
+import { MOCK_MODEL_NAME, DEFAULT_MODEL } from './types.js';
 import { getFormatter } from './formatters/index.js';
 import { verifySemgrepInstalled } from './semgrep-runner.js';
 import { verifyOpenAntInstalled } from './openant-runner.js';
-import { MockAIProvider } from './mock-ai-provider.js';
+import { MockAgentProvider } from './mock-agent-provider.js';
 import { ERROR_CODES, formatError, formatFatalError } from './error-codes.js';
+import { DEFAULT_OUTPUT_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_LOG_TYPE } from './defaults.js';
 import { colorStatus } from './colors.js';
 import { getCheckType } from './check-types.js';
 import { createRequire } from 'node:module';
@@ -33,7 +36,31 @@ async function createMockProvider() {
             throw new Error(`Failed to read AGHAST_MOCK_AI response file: ${mockAiValue}`, { cause: err });
         }
     }
-    const provider = new MockAIProvider({ rawResponse });
+    // Optional mock token usage for testing cost/budget pipelines.
+    // Format: AGHAST_MOCK_TOKENS="<input>,<output>" (e.g. "1000,500")
+    // When AGHAST_LOCAL_CLAUDE=true, inject a mock reportedCost so that the
+    // coveredBySubscription path (banner "equivalent", label) is exercisable in tests.
+    let tokenUsage;
+    const mockTokensRaw = process.env.AGHAST_MOCK_TOKENS;
+    if (mockTokensRaw) {
+        const parts = mockTokensRaw.split(',').map((s) => Number(s.trim()));
+        if (parts.length === 2 && parts.every((n) => Number.isFinite(n) && n >= 0)) {
+            const useLocalClaude = process.env.AGHAST_LOCAL_CLAUDE === 'true';
+            tokenUsage = {
+                inputTokens: parts[0],
+                outputTokens: parts[1],
+                totalTokens: parts[0] + parts[1],
+                ...(useLocalClaude ? {
+                    reportedCost: {
+                        amountUsd: (parts[0] + parts[1]) / 1_000_000,
+                        source: 'claude-agent-sdk',
+                        coveredBySubscription: true,
+                    },
+                } : {}),
+            };
+        }
+    }
+    const provider = new MockAgentProvider({ rawResponse, tokenUsage });
     await provider.initialize({});
     return provider;
 }
@@ -60,8 +87,12 @@ General options:
   --log-type <type>          Log file handler type (default: file).
                              Available types: file
   --model <model>            AI model override (e.g. claude-sonnet-4-20250514)
-  --ai-provider <name>       AI provider name (default: claude-code)
+  --agent-provider <name>    Agent provider name (default: claude-code)
   --generic-prompt <file>    Generic prompt template filename in prompts/ dir
+  --budget-limit-cost <usd>  Abort the scan when accumulated cost exceeds this
+                             USD value. Warns at 80%, aborts at 100%
+  --budget-limit-tokens <n>  Abort the scan when accumulated tokens exceed n.
+                             Warns at 80%, aborts at 100%
 
 Environment variables:
   ANTHROPIC_API_KEY           API key for Claude (required for AI-based checks)
@@ -98,8 +129,10 @@ function parseArgs(args) {
     let logType;
     let runtimeConfigPath;
     let model;
-    let aiProvider;
+    let agentProvider;
     let genericPrompt;
+    let budgetLimitCost;
+    let budgetLimitTokens;
     for (let i = startIdx; i < args.length; i++) {
         switch (args[i]) {
             case '--config-dir': {
@@ -150,10 +183,10 @@ function parseArgs(args) {
                 i++;
                 break;
             }
-            case '--ai-provider': {
-                aiProvider = args[i + 1];
-                if (!aiProvider) {
-                    console.error(formatError(ERROR_CODES.E1001, '--ai-provider requires a provider name argument'));
+            case '--agent-provider': {
+                agentProvider = args[i + 1];
+                if (!agentProvider) {
+                    console.error(formatError(ERROR_CODES.E1001, '--agent-provider requires a provider name argument'));
                     process.exit(1);
                 }
                 i++;
@@ -196,26 +229,62 @@ function parseArgs(args) {
                 i++;
                 break;
             }
+            case '--budget-limit-cost': {
+                const raw = args[i + 1];
+                if (!raw) {
+                    console.error(formatError(ERROR_CODES.E1001, '--budget-limit-cost requires a number argument (USD)'));
+                    process.exit(1);
+                }
+                const n = Number(raw);
+                if (!Number.isFinite(n) || n <= 0) {
+                    console.error(formatError(ERROR_CODES.E1001, `--budget-limit-cost must be a positive number (got "${raw}")`));
+                    process.exit(1);
+                }
+                budgetLimitCost = n;
+                i++;
+                break;
+            }
+            case '--budget-limit-tokens': {
+                const raw = args[i + 1];
+                if (!raw) {
+                    console.error(formatError(ERROR_CODES.E1001, '--budget-limit-tokens requires a number argument'));
+                    process.exit(1);
+                }
+                const n = Number(raw);
+                if (!Number.isFinite(n) || n <= 0 || !Number.isInteger(n)) {
+                    console.error(formatError(ERROR_CODES.E1001, `--budget-limit-tokens must be a positive integer (got "${raw}")`));
+                    process.exit(1);
+                }
+                budgetLimitTokens = n;
+                i++;
+                break;
+            }
             // --fail-on-check-failure and --debug are handled above via includes()
         }
     }
     return {
         repositoryPath, configDir, outputPath, outputFormat,
         failOnCheckFailure, debug, logLevel, logFile, logType,
-        runtimeConfigPath, model, aiProvider, genericPrompt,
+        runtimeConfigPath, model, agentProvider, genericPrompt,
+        budgetLimitCost, budgetLimitTokens,
     };
 }
-async function createProvider(useMock, aiProviderName, modelOverride) {
+async function createProvider(useMock, agentProviderName, modelOverride) {
     if (useMock) {
-        logProgress(TAG, `MOCK AI provider enabled via AGHAST_MOCK_AI=${process.env.AGHAST_MOCK_AI}`);
-        return { provider: await createMockProvider(), modelName: MOCK_MODEL_NAME };
+        logProgress(TAG, `Mock provider enabled via AGHAST_MOCK_AI=${process.env.AGHAST_MOCK_AI}`);
+        const provider = await createMockProvider();
+        // Honour --model in mock mode so cost-calculation tests can target a known
+        // pricing entry. Defaults to MOCK_MODEL_NAME.
+        const effectiveModel = modelOverride ?? MOCK_MODEL_NAME;
+        provider.setModel?.(effectiveModel);
+        return { provider, modelName: effectiveModel };
     }
-    const provider = createProviderByName(aiProviderName);
+    const provider = createProviderByName(agentProviderName);
     await provider.initialize({
         apiKey: process.env.ANTHROPIC_API_KEY,
         model: modelOverride,
     });
-    const modelName = provider.getModelName?.() ?? DEFAULT_AI_MODEL;
+    const modelName = provider.getModelName?.() ?? DEFAULT_MODEL;
     return { provider, modelName };
 }
 /**
@@ -278,7 +347,7 @@ export async function runScan(args) {
     }
     // Resolve log level: --log-level > AGHAST_LOG_LEVEL > runtime config > --debug/AGHAST_DEBUG > default
     const debug = parsed.debug || process.env.AGHAST_DEBUG === 'true';
-    const resolvedLogLevel = parsed.logLevel ?? (process.env.AGHAST_LOG_LEVEL || undefined) ?? runtimeConfig.logging?.level ?? (debug ? 'debug' : 'info');
+    const resolvedLogLevel = parsed.logLevel ?? (process.env.AGHAST_LOG_LEVEL || undefined) ?? runtimeConfig.logging?.level ?? (debug ? 'debug' : DEFAULT_LOG_LEVEL);
     if (resolvedLogLevel !== 'silent' && !isValidLogLevel(resolvedLogLevel)) {
         console.error(formatError(ERROR_CODES.E1001, `Invalid log level "${resolvedLogLevel}". Valid levels: error, warn, info, debug, trace`));
         process.exit(1);
@@ -287,7 +356,7 @@ export async function runScan(args) {
     // Resolve log file: --log-file > AGHAST_LOG_FILE > runtime config
     const resolvedLogFile = parsed.logFile ?? (process.env.AGHAST_LOG_FILE || undefined) ?? (runtimeConfig.logging?.logFile ? resolve(runtimeConfig.logging.logFile) : undefined);
     if (resolvedLogFile) {
-        const resolvedLogType = parsed.logType ?? (process.env.AGHAST_LOG_TYPE || undefined) ?? runtimeConfig.logging?.logType ?? 'file';
+        const resolvedLogType = parsed.logType ?? (process.env.AGHAST_LOG_TYPE || undefined) ?? runtimeConfig.logging?.logType ?? DEFAULT_LOG_TYPE;
         const availableTypes = getAvailableLogTypes();
         if (!availableTypes.includes(resolvedLogType)) {
             console.error(formatError(ERROR_CODES.E1001, `Unknown log type "${resolvedLogType}". Available types: ${availableTypes.join(', ')}`));
@@ -316,7 +385,7 @@ export async function runScan(args) {
         throw err;
     }
     // Resolve output format: CLI > runtime config > default
-    const resolvedOutputFormat = parsed.outputFormat ?? runtimeConfig.reporting?.outputFormat ?? 'json';
+    const resolvedOutputFormat = parsed.outputFormat ?? runtimeConfig.reporting?.outputFormat ?? DEFAULT_OUTPUT_FORMAT;
     // Resolve formatter early — fail fast on unknown format
     const formatter = getFormatter(resolvedOutputFormat);
     // Treat AGHAST_MOCK_AI=false (or empty) as disabled; any other truthy value enables mock mode
@@ -390,29 +459,30 @@ export async function runScan(args) {
     const needsAI = checksWithDetails.some(c => getCheckType(c.check.checkTarget?.type).needsAI);
     const needsSemgrep = checksWithDetails.some(c => c.check.checkTarget?.discovery === 'semgrep');
     const needsOpenant = checksWithDetails.some(c => c.check.checkTarget?.discovery === 'openant');
-    // ─── Conditional AI provider setup ───
-    const aiProviderName = parsed.aiProvider ?? runtimeConfig.aiProvider?.name ?? DEFAULT_PROVIDER_NAME;
+    // ─── Conditional agent provider setup ───
+    const agentProviderName = parsed.agentProvider ?? runtimeConfig.agentProvider?.name ?? DEFAULT_PROVIDER_NAME;
     if (needsAI && !useMock) {
-        // Validate AI provider name before checking credentials (config errors before auth errors)
-        if (!getProviderNames().includes(aiProviderName)) {
-            console.error(formatError(ERROR_CODES.E3002, `Unknown AI provider "${aiProviderName}". Supported providers: ${getProviderNames().join(', ')}`));
+        // Validate agent provider name before checking credentials (config errors before auth errors)
+        if (!getProviderNames().includes(agentProviderName)) {
+            console.error(formatError(ERROR_CODES.E3002, `Unknown agent provider "${agentProviderName}". Supported providers: ${getProviderNames().join(', ')}`));
             process.exit(1);
         }
-        // Validate ANTHROPIC_API_KEY (not needed when using mock or local Claude)
-        if (!process.env.ANTHROPIC_API_KEY && process.env.AGHAST_LOCAL_CLAUDE !== 'true') {
-            console.error(formatError(ERROR_CODES.E3001, 'ANTHROPIC_API_KEY environment variable is required'));
+        // Validate provider-specific prerequisites (API keys, binaries, etc.)
+        try {
+            const tempProvider = createProviderByName(agentProviderName);
+            tempProvider.checkPrerequisites?.();
+        }
+        catch (err) {
+            console.error(formatError(ERROR_CODES.E3001, err instanceof Error ? err.message : String(err)));
             process.exit(1);
         }
     }
     // Resolve model precedence: CLI --model > env AGHAST_AI_MODEL > runtime config > default
-    const modelOverride = parsed.model ?? process.env.AGHAST_AI_MODEL ?? runtimeConfig.aiProvider?.model;
+    const modelOverride = parsed.model ?? process.env.AGHAST_AI_MODEL ?? runtimeConfig.agentProvider?.model;
     let provider;
     let modelName;
     if (needsAI) {
-        ({ provider, modelName } = await createProvider(useMock, aiProviderName, modelOverride));
-        if (resolvedLogLevel === 'debug' || resolvedLogLevel === 'trace') {
-            provider.enableDebug?.();
-        }
+        ({ provider, modelName } = await createProvider(useMock, agentProviderName, modelOverride));
         logProgress(TAG, `Using model: ${modelName}`);
     }
     // ─── Conditional Semgrep verification ───
@@ -435,59 +505,164 @@ export async function runScan(args) {
             process.exit(1);
         }
     }
-    const results = await runMultiScan({
-        repositoryPath: effectiveRepoPath,
-        checks: checksWithDetails,
-        aiProvider: provider,
-        aiModelName: needsAI ? modelName : undefined,
-        repositoryInfo: repoAnalysis?.repository,
-        aiProviderName: needsAI ? (useMock ? 'mock' : aiProviderName) : undefined,
-        configDir,
-        genericPrompt,
-    });
-    // Resolve output path: --output flag > runtime config dir > default
-    let resolvedOutputPath;
-    if (parsed.outputPath) {
-        resolvedOutputPath = parsed.outputPath;
-    }
-    else if (runtimeConfig.reporting?.outputDirectory) {
-        const dir = resolve(runtimeConfig.reporting.outputDirectory);
-        resolvedOutputPath = resolve(dir, 'security_checks_results' + formatter.fileExtension);
+    // ─── Pricing + budget setup ───
+    const defaultPricing = await loadDefaultPricing();
+    const pricing = mergePricing(defaultPricing, runtimeConfig.pricing);
+    const budgetLimits = (() => {
+        const cliCost = parsed.budgetLimitCost;
+        const cliTokens = parsed.budgetLimitTokens;
+        const cfg = runtimeConfig.budget;
+        if (cliCost === undefined && cliTokens === undefined && !cfg)
+            return undefined;
+        const out = {};
+        const perScan = { ...(cfg?.perScan ?? {}) };
+        if (cliCost !== undefined)
+            perScan.maxCostUsd = cliCost;
+        if (cliTokens !== undefined)
+            perScan.maxTokens = cliTokens;
+        if (perScan.maxCostUsd !== undefined || perScan.maxTokens !== undefined) {
+            out.perScan = perScan;
+        }
+        if (cfg?.perPeriod && cfg.perPeriod.window && cfg.perPeriod.maxCostUsd !== undefined) {
+            out.perPeriod = { window: cfg.perPeriod.window, maxCostUsd: cfg.perPeriod.maxCostUsd };
+        }
+        if (cfg?.thresholds)
+            out.thresholds = cfg.thresholds;
+        return Object.keys(out).length > 0 ? out : undefined;
+    })();
+    // Pre-load history for period budget checks (skip when no period limit set)
+    let scanHistoryForBudget;
+    if (budgetLimits?.perPeriod) {
+        try {
+            scanHistoryForBudget = await queryScanHistory();
+        }
+        catch (err) {
+            logDebug(TAG, `Could not load scan history for budget check: ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
-    else {
-        resolvedOutputPath = resolve(effectiveRepoPath, 'security_checks_results' + formatter.fileExtension);
+    try {
+        const outcome = await runMultiScanWithCost({
+            repositoryPath: effectiveRepoPath,
+            checks: checksWithDetails,
+            agentProvider: provider,
+            modelName: needsAI ? modelName : undefined,
+            repositoryInfo: repoAnalysis?.repository,
+            agentProviderName: needsAI ? (useMock ? 'mock' : agentProviderName) : undefined,
+            configDir,
+            genericPrompt,
+            pricing,
+            budgetLimits,
+            scanHistory: scanHistoryForBudget,
+            isLocalClaude: process.env.AGHAST_LOCAL_CLAUDE === 'true',
+        });
+        const results = outcome.results;
+        // Resolve output path: --output flag > runtime config dir > default
+        let resolvedOutputPath;
+        if (parsed.outputPath) {
+            resolvedOutputPath = parsed.outputPath;
+        }
+        else if (runtimeConfig.reporting?.outputDirectory) {
+            const dir = resolve(runtimeConfig.reporting.outputDirectory);
+            resolvedOutputPath = resolve(dir, 'security_checks_results' + formatter.fileExtension);
+        }
+        else {
+            resolvedOutputPath = resolve(effectiveRepoPath, 'security_checks_results' + formatter.fileExtension);
+        }
+        await mkdir(dirname(resolvedOutputPath), { recursive: true });
+        await writeFile(resolvedOutputPath, formatter.format(results), 'utf-8');
+        // Summary output
+        const statusIcon = results.summary.failedChecks > 0
+            ? 'ISSUES DETECTED'
+            : results.summary.flaggedChecks > 0
+                ? 'REVIEW REQUIRED'
+                : results.summary.errorChecks > 0
+                    ? 'SCAN ERROR'
+                    : 'NO ISSUES DETECTED';
+        console.log('');
+        console.log('='.repeat(60));
+        console.log(`AGHAST Scan Complete: ${colorStatus(statusIcon)}`);
+        console.log('='.repeat(60));
+        console.log(`  Total checks:  ${results.summary.totalChecks}`);
+        console.log(`  Passed:        ${results.summary.passedChecks}`);
+        console.log(`  Failed:        ${results.summary.failedChecks}`);
+        console.log(`  Flagged:       ${results.summary.flaggedChecks}`);
+        console.log(`  Errors:        ${results.summary.errorChecks}`);
+        console.log(`  Total issues:  ${results.summary.totalIssues}`);
+        if (results.tokenUsage) {
+            const tu = results.tokenUsage;
+            const cacheSegments = [
+                tu.cacheReadInputTokens !== undefined ? ` cache-read: ${tu.cacheReadInputTokens.toLocaleString()}` : '',
+                tu.cacheCreationInputTokens !== undefined ? ` cache-write: ${tu.cacheCreationInputTokens.toLocaleString()}` : '',
+                tu.reasoningTokens !== undefined ? ` reasoning: ${tu.reasoningTokens.toLocaleString()}` : '',
+            ].filter(Boolean).join(',');
+            const tokenDetail = `(in: ${tu.inputTokens.toLocaleString()}, out: ${tu.outputTokens.toLocaleString()}${cacheSegments ? ',' + cacheSegments : ''})`;
+            console.log(`  Tokens:        ${tu.totalTokens.toLocaleString()} ${tokenDetail}`);
+        }
+        if (outcome.totalCostUsd > 0 || outcome.costSource === 'estimated-unpriced') {
+            const label = formatCostSourceLabel(outcome.costSource, outcome.costReportedBy, outcome.costCoveredBySubscription);
+            const equiv = outcome.costCoveredBySubscription ? ' equivalent' : '';
+            console.log(`  Cost:          $${outcome.totalCostUsd.toFixed(4)}${equiv}  ${label}`);
+        }
+        console.log(`  Duration:      ${globalTimer.elapsedStr()}`);
+        console.log(`  Results:       ${resolvedOutputPath}`);
+        console.log('='.repeat(60));
+        // Persist the scan record to history (best-effort — never blocks exit).
+        // We DO save the record even when the scan was aborted by budget: per-period
+        // budgets aggregate over historical scans, so the partial cost incurred
+        // before the abort must be recorded — otherwise a user could repeatedly
+        // hit the budget abort and still consume more total spend than the period
+        // limit allows.
+        try {
+            const record = {
+                scanId: results.scanId,
+                startedAt: results.startTime,
+                endedAt: results.endTime,
+                durationMs: results.executionTime,
+                repository: effectiveRepoPath,
+                repositoryUrl: repoAnalysis?.repository.remoteUrl,
+                models: outcome.models.length > 0 ? outcome.models : (modelName ? [modelName] : []),
+                tokenUsage: results.tokenUsage,
+                totalCost: outcome.totalCostUsd,
+                currency: outcome.currency,
+                costSource: outcome.costSource,
+                costReportedBy: outcome.costReportedBy,
+                costCoveredBySubscription: outcome.costCoveredBySubscription,
+                checks: results.summary.totalChecks,
+                issues: results.summary.totalIssues,
+            };
+            await saveScanRecord(record);
+        }
+        catch (err) {
+            logDebug(TAG, `Failed to save scan history: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // A budget abort is a deliberate failure mode the user opted into via
+        // --budget-limit-* / runtime config — it must always exit non-zero (and
+        // surface E7001 to stderr) regardless of --fail-on-check-failure. Doing
+        // otherwise would silently drop the abort signal in CI pipelines that
+        // rely on the exit code as a guardrail.
+        //
+        // Emit through both stderr (for terminal users / CI logs) AND the logging
+        // system (so --log-file captures the abort reason — console.error bypasses
+        // registered log handlers).
+        if (outcome.budgetAborted) {
+            const reason = outcome.budgetAbortReason ?? 'Budget limit exceeded';
+            console.error(formatError(ERROR_CODES.E7001, reason));
+            logProgress(TAG, `Scan aborted by budget: ${reason}`);
+        }
+        // Exit code based on --fail-on-check-failure flag or runtime config (spec Section 9.3),
+        // OR a budget abort.
+        const failOnCheckFailure = parsed.failOnCheckFailure || runtimeConfig.failOnCheckFailure === true;
+        const shouldFail = outcome.budgetAborted ||
+            (failOnCheckFailure && (results.summary.failedChecks > 0 || results.summary.errorChecks > 0));
+        await closeAllHandlers();
+        process.exit(shouldFail ? 1 : 0);
     }
-    await mkdir(dirname(resolvedOutputPath), { recursive: true });
-    await writeFile(resolvedOutputPath, formatter.format(results), 'utf-8');
-    // Summary output
-    const statusIcon = results.summary.failedChecks > 0
-        ? 'FAIL'
-        : results.summary.flaggedChecks > 0
-            ? 'FLAG'
-            : results.summary.errorChecks > 0
-                ? 'ERROR'
-                : 'PASS';
-    console.log('');
-    console.log('='.repeat(60));
-    console.log(`AGHAST Scan Complete: ${colorStatus(statusIcon)}`);
-    console.log('='.repeat(60));
-    console.log(`  Total checks:  ${results.summary.totalChecks}`);
-    console.log(`  Passed:        ${results.summary.passedChecks}`);
-    console.log(`  Failed:        ${results.summary.failedChecks}`);
-    console.log(`  Flagged:       ${results.summary.flaggedChecks}`);
-    console.log(`  Errors:        ${results.summary.errorChecks}`);
-    console.log(`  Total issues:  ${results.summary.totalIssues}`);
-    if (results.tokenUsage) {
-        console.log(`  Tokens:        ${results.tokenUsage.totalTokens.toLocaleString()} (in: ${results.tokenUsage.inputTokens.toLocaleString()}, out: ${results.tokenUsage.outputTokens.toLocaleString()})`);
+    finally {
+        // Clean up provider resources (e.g. OpenCode server process)
+        if (provider && 'cleanup' in provider && typeof provider.cleanup === 'function') {
+            await provider.cleanup();
+        }
     }
-    console.log(`  Duration:      ${globalTimer.elapsedStr()}`);
-    console.log(`  Results:       ${resolvedOutputPath}`);
-    console.log('='.repeat(60));
-    // Exit code based on --fail-on-check-failure flag or runtime config (spec Section 9.3)
-    const failOnCheckFailure = parsed.failOnCheckFailure || runtimeConfig.failOnCheckFailure === true;
-    const shouldFail = failOnCheckFailure && (results.summary.failedChecks > 0 || results.summary.errorChecks > 0);
-    await closeAllHandlers();
-    process.exit(shouldFail ? 1 : 0);
 }
 // Auto-run when executed directly (npm run scan / tsx src/index.ts), but not when imported by cli.ts.
 if (!process.env._AGHAST_CLI) {