@rigour-labs/core 6.4.2 → 6.4.4

package/dist/deep/code-pass.d.ts

@@ -21,5 +21,9 @@ export interface CodePassConfig extends PassConfig {
 }
 export interface CodePassResult extends PassResult {
     contexts: CodeContext[];
+    /** Findings the model proposed, before the self-check (the max and cloud tiers). */
+    proposed: number;
+    /** Of those, withdrawn by the self-check. */
+    withdrawn: number;
 }
 export declare function runCodePass(provider: InferenceProvider, facts: FileFacts[], config: CodePassConfig): Promise<CodePassResult>;

package/dist/deep/code-pass.js

@@ -11,7 +11,7 @@ import { buildReferencePack } from './reference-pack.js';
 import { selfCheck } from './self-check.js';
 import { Logger } from '../utils/logger.js';
 export async function runCodePass(provider, facts, config) {
-    const result = { findings: [], chunksTotal: facts.length, chunksFailed: 0, contexts: [] };
+    const result = { findings: [], chunksTotal: facts.length, chunksFailed: 0, contexts: [], proposed: 0, withdrawn: 0 };
     for (let i = 0; i < facts.length; i++) {
         const file = facts[i];
         config.onProgress?.(`  Reviewing ${file.path} (${i + 1}/${facts.length})...`);
@@ -32,7 +32,17 @@ export async function runCodePass(provider, facts, config) {
             context = { ...context, source: `${context.source}\n${pack.source}` };
         result.contexts.push(context);
         try {
-            result.findings.push(...(pack ? await reviewTwiceAndCheck(provider, context, pack, config) : await reviewOnce(provider, context, '', config)));
+            if (pack) {
+                const checked = await reviewTwiceAndCheck(provider, context, pack, config);
+                result.findings.push(...checked.kept);
+                result.proposed += checked.proposed;
+                result.withdrawn += checked.withdrawn;
+            }
+            else {
+                const found = await reviewOnce(provider, context, '', config);
+                result.findings.push(...found);
+                result.proposed += found.length;
+            }
         }
         catch (error) {
             recordFailure(result, `${file.path}: ${error.message}`, config);
@@ -48,11 +58,11 @@ async function reviewTwiceAndCheck(provider, context, pack, config) {
     const second = pack.sections.length > 1 ? await reviewOnce(provider, context, [...pack.sections].reverse().join('\n\n'), config) : [];
     const union = dedupe([...first, ...second]);
     if (union.length === 0)
-        return union;
+        return { kept: union, proposed: 0, withdrawn: 0 };
     const checked = await selfCheck(provider, context, pack.text, union, config.inference);
     if (checked.withdrawn > 0)
         config.onProgress?.(`  Self-check withdrew ${checked.withdrawn} of ${union.length} finding(s) in ${context.file}.`);
-    return checked.kept;
+    return { kept: checked.kept, proposed: union.length, withdrawn: checked.withdrawn };
 }
 function packFor(file, config) {
     const reference = config.reference;

package/dist/deep/code-pass.test.js

@@ -39,6 +39,7 @@ describe('runCodePass', () => {
         const result = await run(provider);
         expect(prompts).toHaveLength(1);
         expect(result.findings.map(f => f.line)).toEqual([3]);
+        expect([result.proposed, result.withdrawn]).toEqual([1, 0]);
     });
     it('does not repeat an identical pass when there is only one reference section', async () => {
         const { provider, prompts } = fakeProvider([[]], []);
@@ -60,6 +61,7 @@ describe('runCodePass', () => {
         expect(reviews[1].indexOf('REMOVED by this change')).toBeLessThan(reviews[1].indexOf('PR DESCRIPTION'));
         expect(prompts.filter(p => p.startsWith('You reported a defect'))).toHaveLength(2);
         expect(result.findings.map(f => [f.line, f.category])).toEqual([[3, 'correctness']]);
+        expect([result.proposed, result.withdrawn]).toEqual([2, 1]); // two distinct findings, one withdrawn
     });
     it('reads a self-check reply only when it is a verdict', () => {
         expect(parseVerdict('{"real": false, "reason": "handled"}')).toBe(false);

package/dist/gates/deep-analysis.d.ts

@@ -31,6 +31,9 @@ export interface DeepRunOutcome {
     filesAnalyzed: number;
     chunksTotal: number;
     chunksFailed: number;
+    /** Code mode: findings the model proposed, and how many the self-check withdrew. */
+    findingsProposed?: number;
+    findingsWithdrawn?: number;
     /** Model actually used (the stock fallback is named as such). */
     model?: string;
     modelFallback?: boolean;

package/dist/gates/deep-analysis.js

@@ -111,6 +111,8 @@ export class DeepAnalysisGate extends Gate {
             onProgress: this.config.onProgress,
         });
         this.recordPass(result);
+        this.outcome.findingsProposed = result.proposed;
+        this.outcome.findingsWithdrawn = result.withdrawn;
         return verifyCodeFindings(result.findings, result.contexts);
     }
     /** The max and cloud tiers read reference material and review twice; the small models do not. */

package/dist/gates/deep-runner.js

@@ -46,6 +46,8 @@ export async function runDeepAnalysis(config, context, deepOptions) {
         chunks_total: outcome.chunksTotal,
         chunks_failed: outcome.chunksFailed,
         error: outcome.error,
+        findings_proposed: outcome.findingsProposed,
+        findings_withdrawn: outcome.findingsWithdrawn,
         findings_count: findings.length,
         findings_verified: findings.filter(f => f.verified).length,
     };

package/dist/index.d.ts

@@ -52,6 +52,7 @@ export * from './context/index-bridge.js';
 export * from './context/automatic-index.js';
 export * from './context/dependency-graph.js';
 export * from './services/context-telemetry-service.js';
+export * from './services/observed-savings.js';
 export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';

package/dist/index.js

@@ -51,6 +51,7 @@ export * from './context/index-bridge.js';
 export * from './context/automatic-index.js';
 export * from './context/dependency-graph.js';
 export * from './services/context-telemetry-service.js';
+export * from './services/observed-savings.js';
 export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';

package/dist/services/context-telemetry-service.d.ts

@@ -3,6 +3,7 @@
  * Calculates exact observed usage, avoided tokens, cache performance, and cost breakdowns.
  * Supports CSV/JSON Cursor usage imports.
  */
+import { type ObservedSavings } from './observed-savings.js';
 import { type CursorUsageSyncOptions } from './cursor-usage-client.js';
 /** Heuristic token counter (~4 chars per token for code/text) */
 export declare function estimateTokenCount(text: string): number;
@@ -57,6 +58,14 @@ export interface TaskCostStats {
         pricingSource: string;
         pricingEffectiveDate: string;
     };
+    /**
+     * Measured, not modelled: scoped files the agent's hook saw it never read,
+     * less the summaries it read instead. Only scopes followed by observed agent
+     * activity count (trackedScopes); the estimate above is an upper bound.
+     */
+    observed: ObservedSavings & {
+        avoidedCostUsd: number;
+    };
 }
 export interface CachePerformanceStats {
     exactCacheHits: number;

package/dist/services/context-telemetry-service.js

@@ -4,6 +4,7 @@
  * Supports CSV/JSON Cursor usage imports.
  */
 import { createHash } from 'crypto';
+import { observedSavings } from './observed-savings.js';
 import fs from 'fs-extra';
 import path from 'path';
 import { getContextEvents, getModelUsages, getCheckpointMetrics, recordModelUsage, } from '../storage/index.js';
@@ -110,6 +111,8 @@ export async function getTaskCostStats(taskId, cwd) {
         actualPricingBasis = 'observed-cursor-charged-cents';
     }
     const retrievalPricing = estimateAvoidedContextCostUsd(stats.potentialAvoidedTokens, usages);
+    const observed = observedSavings(cwd ?? process.cwd());
+    const observedPricing = estimateAvoidedContextCostUsd(observed.avoidedTokens, usages);
     const checkpointPricing = estimateAvoidedContextCostUsd(stats.checkpointReplayAvoided, usages);
     const unknownPricing = retrievalPricing.pricing.pricingBasis.includes('fallback');
     const range = (tokens) => ({
@@ -150,6 +153,7 @@ export async function getTaskCostStats(taskId, cwd) {
             pricingSource: MODEL_PRICING_SOURCE,
             pricingEffectiveDate: MODEL_PRICING_EFFECTIVE_DATE,
         },
+        observed: { ...observed, avoidedCostUsd: observedPricing.costUsd },
     };
 }
 /**

package/dist/services/observed-savings.d.ts

@@ -0,0 +1,36 @@
+export declare const OBSERVATION_WINDOW_MS: number;
+export interface ScopeOffer {
+    ts: number;
+    files: Array<{
+        path: string;
+        tokens: number;
+    }>;
+    summaryTokens: number;
+}
+export interface AgentActivity {
+    ts: number;
+    tool: string;
+    path?: string;
+}
+export interface ObservedSavings {
+    scopes: number;
+    /** Scopes followed by agent activity the hook saw: the only ones measured. */
+    trackedScopes: number;
+    offeredTokens: number;
+    /** Tokens of scoped files the agent read anyway. */
+    readBackTokens: number;
+    /** Tokens of scoped files never read, less the summaries, over tracked scopes. */
+    avoidedTokens: number;
+}
+export declare function recordScopeOffer(cwd: string, files: Array<{
+    path: string;
+    tokens: number;
+}>, summaryTokens: number, ts?: number): void;
+/** One tool call an agent hook saw. Read-like tools carry the file they read. */
+export declare function recordAgentActivity(cwd: string, tool: string, filePath?: string, ts?: number): void;
+/**
+ * A hook payload for one agent tool call (Claude Code PreToolUse sends tool_name,
+ * tool_input and cwd); anything else is ignored.
+ */
+export declare function recordHookPayload(payload: unknown, fallbackCwd: string, ts?: number): void;
+export declare function observedSavings(cwd: string, windowMs?: number): ObservedSavings;

package/dist/services/observed-savings.js

@@ -0,0 +1,94 @@
+/**
+ * Observed context savings: tokens an agent did not read because Rigour scoped its context.
+ *
+ * The estimate in context telemetry assumes the agent would otherwise read every
+ * scoped file whole, and does not read them afterwards anyway. Neither is
+ * measured. Here both sides are observed:
+ *
+ *   .rigour/context-scopes.jsonl   files rigour_context_scope summarised, with their tokens
+ *   .rigour/agent-activity.jsonl   every tool call the agent's hook saw (and the file it read)
+ *
+ * A scope is tracked when the hook recorded any agent activity after it, so
+ * "the agent read nothing" is told apart from "no hook is installed". For a
+ * tracked scope, the saving is the tokens of scoped files the agent did not
+ * read within the window, less the summary it read instead.
+ */
+import fs from 'fs';
+import path from 'path';
+const SCOPES = 'context-scopes.jsonl';
+const ACTIVITY = 'agent-activity.jsonl';
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+export const OBSERVATION_WINDOW_MS = 30 * 60 * 1000;
+const READ_TOOLS = /^(?:read|read_file|readfile|view|open_file|cat)$/i;
+export function recordScopeOffer(cwd, files, summaryTokens, ts = Date.now()) {
+    append(cwd, SCOPES, { ts, files: files.map(f => ({ path: normalize(cwd, f.path), tokens: f.tokens })), summaryTokens });
+}
+/** One tool call an agent hook saw. Read-like tools carry the file they read. */
+export function recordAgentActivity(cwd, tool, filePath, ts = Date.now()) {
+    const entry = { ts, tool };
+    if (filePath && READ_TOOLS.test(tool))
+        entry.path = normalize(cwd, filePath);
+    append(cwd, ACTIVITY, entry);
+}
+/**
+ * A hook payload for one agent tool call (Claude Code PreToolUse sends tool_name,
+ * tool_input and cwd); anything else is ignored.
+ */
+export function recordHookPayload(payload, fallbackCwd, ts = Date.now()) {
+    const event = payload;
+    if (!event || typeof event.tool_name !== 'string')
+        return;
+    const input = event.tool_input ?? {};
+    const file = [input.file_path, input.path, input.target_file].find((v) => typeof v === 'string');
+    recordAgentActivity(typeof event.cwd === 'string' ? event.cwd : fallbackCwd, event.tool_name, file, ts);
+}
+export function observedSavings(cwd, windowMs = OBSERVATION_WINDOW_MS) {
+    const scopes = readLog(cwd, SCOPES);
+    const activity = readLog(cwd, ACTIVITY).sort((a, b) => a.ts - b.ts);
+    const result = { scopes: scopes.length, trackedScopes: 0, offeredTokens: 0, readBackTokens: 0, avoidedTokens: 0 };
+    for (const scope of scopes) {
+        const after = activity.filter(a => a.ts >= scope.ts && a.ts <= scope.ts + windowMs);
+        if (after.length === 0)
+            continue;
+        result.trackedScopes++;
+        const read = new Set(after.filter(a => a.path).map(a => a.path));
+        const offered = scope.files.reduce((sum, f) => sum + f.tokens, 0);
+        const readBack = scope.files.filter(f => read.has(f.path)).reduce((sum, f) => sum + f.tokens, 0);
+        result.offeredTokens += offered;
+        result.readBackTokens += readBack;
+        result.avoidedTokens += Math.max(0, offered - readBack - scope.summaryTokens);
+    }
+    return result;
+}
+function normalize(cwd, file) {
+    return path.relative(cwd, path.resolve(cwd, file)).split(path.sep).join('/');
+}
+function append(cwd, name, entry) {
+    try {
+        const dir = path.join(cwd, '.rigour');
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, name);
+        fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+        if (fs.statSync(file).size > MAX_LOG_BYTES) {
+            const lines = fs.readFileSync(file, 'utf8').trimEnd().split('\n');
+            fs.writeFileSync(file, lines.slice(Math.floor(lines.length / 2)).join('\n') + '\n');
+        }
+    }
+    catch {
+        // Measurement must never break the agent's tool call.
+    }
+}
+function readLog(cwd, name) {
+    try {
+        return fs.readFileSync(path.join(cwd, '.rigour', name), 'utf8').split('\n').filter(Boolean)
+            .flatMap(line => { try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        } });
+    }
+    catch {
+        return [];
+    }
+}

package/dist/services/observed-savings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/observed-savings.test.js

@@ -0,0 +1,37 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { observedSavings, recordAgentActivity, recordHookPayload, recordScopeOffer } from './observed-savings.js';
+let cwd;
+beforeEach(() => { cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'observed-savings-')); });
+afterEach(() => { fs.rmSync(cwd, { recursive: true, force: true }); });
+const T = 1_000_000;
+describe('observedSavings', () => {
+    it('counts only scoped files the agent did not read afterwards, less the summary', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 3000 }, { path: 'src/b.ts', tokens: 2000 }], 400, T);
+        recordAgentActivity(cwd, 'Read', path.join(cwd, 'src/a.ts'), T + 60_000); // read anyway
+        recordAgentActivity(cwd, 'Edit', path.join(cwd, 'src/b.ts'), T + 90_000); // an edit is not a read
+        expect(observedSavings(cwd)).toEqual({ scopes: 1, trackedScopes: 1, offeredTokens: 5000, readBackTokens: 3000, avoidedTokens: 1600 });
+    });
+    it('claims nothing for a scope no hook observed, so a missing hook never reads as a saving', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 3000 }], 400, T);
+        expect(observedSavings(cwd)).toMatchObject({ scopes: 1, trackedScopes: 0, avoidedTokens: 0 });
+    });
+    it('ignores activity outside the observation window', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 3000 }], 400, T);
+        recordAgentActivity(cwd, 'Read', 'src/a.ts', T + 2 * 60 * 60 * 1000);
+        expect(observedSavings(cwd).trackedScopes).toBe(0);
+    });
+    it('never claims more than was offered when the summary outweighs unread files', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 100 }], 400, T);
+        recordAgentActivity(cwd, 'Grep', undefined, T + 1000);
+        expect(observedSavings(cwd).avoidedTokens).toBe(0);
+    });
+    it('reads a Claude Code PreToolUse payload: the tool, the file it reads, and its working directory', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 3000 }], 400, T);
+        recordHookPayload({ tool_name: 'Read', tool_input: { file_path: path.join(cwd, 'src/a.ts') }, cwd }, '/elsewhere', T + 1000);
+        recordHookPayload({ hello: 'not a tool call' }, cwd, T + 2000);
+        expect(observedSavings(cwd)).toMatchObject({ trackedScopes: 1, readBackTokens: 3000, avoidedTokens: 0 });
+    });
+});

package/dist/types/index.d.ts

@@ -3023,6 +3023,8 @@ export declare const ReportSchema: z.ZodObject<{
             chunks_total: z.ZodOptional<z.ZodNumber>;
             chunks_failed: z.ZodOptional<z.ZodNumber>;
             error: z.ZodOptional<z.ZodString>;
+            findings_proposed: z.ZodOptional<z.ZodNumber>;
+            findings_withdrawn: z.ZodOptional<z.ZodNumber>;
             findings_count: z.ZodOptional<z.ZodNumber>;
             findings_verified: z.ZodOptional<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
@@ -3037,6 +3039,8 @@ export declare const ReportSchema: z.ZodObject<{
             files_analyzed?: number | undefined;
             chunks_total?: number | undefined;
             chunks_failed?: number | undefined;
+            findings_proposed?: number | undefined;
+            findings_withdrawn?: number | undefined;
             findings_count?: number | undefined;
             findings_verified?: number | undefined;
         }, {
@@ -3051,6 +3055,8 @@ export declare const ReportSchema: z.ZodObject<{
             files_analyzed?: number | undefined;
             chunks_total?: number | undefined;
             chunks_failed?: number | undefined;
+            findings_proposed?: number | undefined;
+            findings_withdrawn?: number | undefined;
             findings_count?: number | undefined;
             findings_verified?: number | undefined;
         }>>;
@@ -3068,6 +3074,8 @@ export declare const ReportSchema: z.ZodObject<{
             files_analyzed?: number | undefined;
             chunks_total?: number | undefined;
             chunks_failed?: number | undefined;
+            findings_proposed?: number | undefined;
+            findings_withdrawn?: number | undefined;
             findings_count?: number | undefined;
             findings_verified?: number | undefined;
         } | undefined;
@@ -3097,6 +3105,8 @@ export declare const ReportSchema: z.ZodObject<{
             files_analyzed?: number | undefined;
             chunks_total?: number | undefined;
             chunks_failed?: number | undefined;
+            findings_proposed?: number | undefined;
+            findings_withdrawn?: number | undefined;
             findings_count?: number | undefined;
             findings_verified?: number | undefined;
         } | undefined;
@@ -3128,6 +3138,8 @@ export declare const ReportSchema: z.ZodObject<{
             files_analyzed?: number | undefined;
             chunks_total?: number | undefined;
             chunks_failed?: number | undefined;
+            findings_proposed?: number | undefined;
+            findings_withdrawn?: number | undefined;
             findings_count?: number | undefined;
             findings_verified?: number | undefined;
         } | undefined;
@@ -3176,6 +3188,8 @@ export declare const ReportSchema: z.ZodObject<{
             files_analyzed?: number | undefined;
             chunks_total?: number | undefined;
             chunks_failed?: number | undefined;
+            findings_proposed?: number | undefined;
+            findings_withdrawn?: number | undefined;
             findings_count?: number | undefined;
             findings_verified?: number | undefined;
         } | undefined;

package/dist/types/index.js

@@ -422,6 +422,8 @@ export const ReportSchema = z.object({
             chunks_total: z.number().optional(),
             chunks_failed: z.number().optional(),
             error: z.string().optional(),
+            findings_proposed: z.number().optional(), // code mode, before the self-check
+            findings_withdrawn: z.number().optional(), // by the self-check
             findings_count: z.number().optional(),
             findings_verified: z.number().optional(),
         }).optional(),

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.4.2",
+  "version": "6.4.4",
   "description": "AI-native quality gate engine with local Bayesian learning. AST analysis, drift detection, Fix Packet generation, and agent self-healing across TypeScript, JavaScript, Python, Go, Ruby, and C#.",
+  "engines": {
+    "node": ">=22"
+  },
   "license": "MIT",
   "homepage": "https://rigour.run",
   "keywords": [
@@ -67,11 +70,11 @@
     "pg": "^8.16.3",
     "sqlite3": "^5.1.7",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-arm64": "6.4.2",
-    "@rigour-labs/brain-darwin-x64": "6.4.2",
-    "@rigour-labs/brain-linux-arm64": "6.4.2",
-    "@rigour-labs/brain-win-x64": "6.4.2",
-    "@rigour-labs/brain-linux-x64": "6.4.2"
+    "@rigour-labs/brain-darwin-arm64": "6.4.4",
+    "@rigour-labs/brain-linux-arm64": "6.4.4",
+    "@rigour-labs/brain-win-x64": "6.4.4",
+    "@rigour-labs/brain-linux-x64": "6.4.4",
+    "@rigour-labs/brain-darwin-x64": "6.4.4"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",