@geraldmaron/construct 1.0.2 → 1.0.4

package/lib/parity.mjs

@@ -2,7 +2,7 @@
  * lib/parity.mjs — Cross-surface parity verifier.
  *
  * After `construct sync` writes adapters to multiple surfaces (Claude Code,
- * OpenCode, Codex), the module diffs each surface's actual state against the
+ * OpenCode, Codex, Copilot, VS Code, Cursor), the module diffs each surface's actual state against the
  * canonical `agents/registry.json`. Backs `construct doctor` for surfacing
  * silent divergence — for instance, an agent added to the registry that
  * never made it to OpenCode because of a sync regression.
@@ -14,9 +14,12 @@
  * the field are mirrored everywhere.
  *
  * Surfaces checked:
- *   claude   ~/.claude/agents/*.md
- *   opencode ~/.config/opencode/opencode.json (agent table)
- *   codex    ~/.codex/agents/*.toml
+ *   claude    ~/.claude/agents/*.md
+ *   opencode  ~/.config/opencode/opencode.json (agent table)
+ *   codex     ~/.codex/agents/*.toml
+ *   copilot   ~/.github/prompts/*.prompt.md
+ *   vscode    VS Code user settings (github.copilot.mcpServers)
+ *   cursor    ~/.cursor/mcp.json
  */
 
 import fs from 'node:fs';
@@ -59,16 +62,15 @@ function diffSets(expected, actual) {
   return { missing, extra };
 }
 
-function checkClaude(registry, { homeDir = os.homedir() } = {}) {
-  const dir = path.join(homeDir, '.claude', 'agents');
-  if (!fs.existsSync(dir)) return { surface: 'claude', status: 'absent', dir };
-  const expected = entriesForSurface(registry, 'claude');
+function checkFileSurface({ surface, kind, dir, extension, expected }) {
+  if (!fs.existsSync(dir)) return { surface, kind, status: 'absent', dir };
   const actual = fs.readdirSync(dir)
-    .filter((name) => name.endsWith('.md'))
-    .map((name) => name.replace(/\.md$/, ''));
+    .filter((name) => name.endsWith(extension))
+    .map((name) => name.slice(0, -extension.length));
   const { missing, extra } = diffSets(expected, actual);
   return {
-    surface: 'claude',
+    surface,
+    kind,
     status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
     dir,
     expectedCount: expected.length,
@@ -78,20 +80,56 @@ function checkClaude(registry, { homeDir = os.homedir() } = {}) {
   };
 }
 
+function getVSCodeSettingsPaths(homeDir) {
+  const platform = os.platform();
+  if (platform === 'darwin') {
+    return [
+      path.join(homeDir, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
+      path.join(homeDir, 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json'),
+    ];
+  }
+  if (platform === 'linux') {
+    return [
+      path.join(homeDir, '.config', 'Code', 'User', 'settings.json'),
+      path.join(homeDir, '.config', 'Code - Insiders', 'User', 'settings.json'),
+    ];
+  }
+  if (platform === 'win32') {
+    const appData = process.env.APPDATA ?? path.join(homeDir, 'AppData', 'Roaming');
+    return [
+      path.join(appData, 'Code', 'User', 'settings.json'),
+      path.join(appData, 'Code - Insiders', 'User', 'settings.json'),
+    ];
+  }
+  return [];
+}
+
+function checkClaude(registry, { homeDir = os.homedir() } = {}) {
+  const expected = entriesForSurface(registry, 'claude');
+  return checkFileSurface({
+    surface: 'claude',
+    kind: 'agents',
+    dir: path.join(homeDir, '.claude', 'agents'),
+    extension: '.md',
+    expected,
+  });
+}
+
 function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
   const file = path.join(homeDir, '.config', 'opencode', 'opencode.json');
-  if (!fs.existsSync(file)) return { surface: 'opencode', status: 'absent', file };
+  if (!fs.existsSync(file)) return { surface: 'opencode', kind: 'agents', status: 'absent', file };
   let config;
   try {
     config = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch (err) {
-    return { surface: 'opencode', status: 'unreadable', file, error: err.message };
+    return { surface: 'opencode', kind: 'agents', status: 'unreadable', file, error: err.message };
   }
   const expected = entriesForSurface(registry, 'opencode');
   const actual = Object.keys(config.agent || config.agents || {});
   const { missing, extra } = diffSets(expected, actual);
   return {
     surface: 'opencode',
+    kind: 'agents',
     status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
     file,
     expectedCount: expected.length,
@@ -102,17 +140,79 @@ function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
 }
 
 function checkCodex(registry, { homeDir = os.homedir() } = {}) {
-  const dir = path.join(homeDir, '.codex', 'agents');
-  if (!fs.existsSync(dir)) return { surface: 'codex', status: 'absent', dir };
   const expected = entriesForSurface(registry, 'codex');
-  const actual = fs.readdirSync(dir)
-    .filter((name) => name.endsWith('.toml'))
-    .map((name) => name.replace(/\.toml$/, ''));
+  return checkFileSurface({
+    surface: 'codex',
+    kind: 'agents',
+    dir: path.join(homeDir, '.codex', 'agents'),
+    extension: '.toml',
+    expected,
+  });
+}
+
+function checkCopilot(registry, { homeDir = os.homedir() } = {}) {
+  const prefix = registry.prefix || 'cx';
+  const entries = [
+    ...(registry.personas || []).map((p) => ({ ...p, isPersona: true })),
+    ...(registry.agents || []).map((a) => ({ ...a, isPersona: false })),
+  ];
+  const expected = entries
+    .filter((entry) => !entry.internal)
+    .filter((entry) => !Array.isArray(entry.platforms) || entry.platforms.includes('copilot'))
+    .map((entry) => adapterName(entry, prefix));
+  return checkFileSurface({
+    surface: 'copilot',
+    kind: 'prompts',
+    dir: path.join(homeDir, '.github', 'prompts'),
+    extension: '.prompt.md',
+    expected,
+  });
+}
+
+function checkVSCode(registry, { homeDir = os.homedir() } = {}) {
+  const paths = getVSCodeSettingsPaths(homeDir).filter((settingsPath) => fs.existsSync(settingsPath));
+  if (paths.length === 0) return { surface: 'vscode', kind: 'mcps', status: 'absent', paths };
+  const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
+  const actualSet = new Set();
+  for (const settingsPath of paths) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      for (const id of Object.keys(settings['github.copilot.mcpServers'] ?? {})) actualSet.add(id);
+    } catch (err) {
+      return { surface: 'vscode', kind: 'mcps', status: 'unreadable', file: settingsPath, error: err.message };
+    }
+  }
+  const actual = [...actualSet].sort();
   const { missing, extra } = diffSets(expected, actual);
   return {
-    surface: 'codex',
+    surface: 'vscode',
+    kind: 'mcps',
     status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
-    dir,
+    paths,
+    expectedCount: expected.length,
+    actualCount: actual.length,
+    missing,
+    extra,
+  };
+}
+
+function checkCursor(registry, { homeDir = os.homedir() } = {}) {
+  const file = path.join(homeDir, '.cursor', 'mcp.json');
+  if (!fs.existsSync(file)) return { surface: 'cursor', kind: 'mcps', status: 'absent', file };
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return { surface: 'cursor', kind: 'mcps', status: 'unreadable', file, error: err.message };
+  }
+  const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
+  const actual = Object.keys(config.mcpServers ?? {});
+  const { missing, extra } = diffSets(expected, actual);
+  return {
+    surface: 'cursor',
+    kind: 'mcps',
+    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    file,
     expectedCount: expected.length,
     actualCount: actual.length,
     missing,
@@ -130,13 +230,16 @@ export function checkParity({ rootDir = ROOT_DIR, homeDir = os.homedir() } = {})
     checkClaude(registry, { homeDir }),
     checkOpenCode(registry, { homeDir }),
     checkCodex(registry, { homeDir }),
+    checkCopilot(registry, { homeDir }),
+    checkVSCode(registry, { homeDir }),
+    checkCursor(registry, { homeDir }),
   ];
 
   const ok = surfaces.every((s) => s.status === 'ok' || s.status === 'absent');
   const summary = surfaces.map((s) => {
     if (s.status === 'absent') return `${s.surface}: not installed`;
     if (s.status === 'unreadable') return `${s.surface}: unreadable (${s.error})`;
-    if (s.status === 'ok') return `${s.surface}: ok (${s.actualCount}/${s.expectedCount})`;
+    if (s.status === 'ok') return `${s.surface}: ok (${s.actualCount}/${s.expectedCount} ${s.kind})`;
     const parts = [];
     if (s.missing.length) parts.push(`missing: ${s.missing.join(', ')}`);
     if (s.extra.length) parts.push(`extra: ${s.extra.join(', ')}`);

package/lib/project-profile.mjs

@@ -8,7 +8,7 @@
  *
  * The profile is written to `<cwd>/.cx/project-profile.json` and consumed by:
  *   - `construct skills scope` — reports relevant vs irrelevant skills
- *   - `construct setup` — runs detection on bootstrap
+ *   - `construct init` — runs detection on bootstrap
  *   - future per-host filter generators (.claude/settings.json filter,
  *     .opencode/construct-skills.json sidecars, etc.)
  */

package/lib/prompt-composer.js

@@ -8,8 +8,12 @@
  * NEW contract (no backward compat):
  *   { metadata, fragments, system, messages, staticEndIndex, totalTokens }
  *
- * Fragment order: core → role-flavor → task-context → learned-patterns → task-packet → context-digest → host-constraints
- * learned-patterns is inserted before the task packet so agents see what has been learned before reading the specific task.
+ * Fragment order: core → role-flavor → model-profile → task-context → learned-patterns → task-packet → context-digest → strategy → host-constraints
+ * strategy is injected after context-digest so agents have strategic grounding before learned-patterns affect framing.
+ *
+ * Workspace-type overlay auto-selection: when workspaceType is passed, the matching role overlay
+ * is selected automatically (e.g. workspaceType='platform' → product-manager.platform overlay)
+ * unless roleFlavors explicitly overrides it.
  */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
@@ -17,29 +21,45 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 
 import { buildContextDigest, readContextState } from './context-state.mjs';
-import { resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from './model-router.mjs';
+import {
+  MODEL_OPERATING_PROFILES,
+  resolveExecutionContractModelMetadata,
+  resolveModelOperatingProfile,
+  selectModelTierForWorkCategory,
+} from './model-router.mjs';
 import { searchObservations } from './observation-store.mjs';
 import { routeRequest } from './orchestration-policy.mjs';
 import { resolvePromptEntry, resolvePromptMetadata } from './prompt-metadata.mjs';
 import { readRoleFile } from './role-preload.mjs';
 import { estimateTokens, estimatePromptTokens, estimateTokensSync } from './token-engine.js';
+import { cxDir } from './paths.mjs';
+import { getStrategyDigestSync } from './strategy-store.mjs';
 
-// Token limits (replacing char limits)
-const LEARNED_PATTERNS_TOKEN_LIMIT = 200;
-const MAX_OBSERVATIONS = 3; // matched to token budget
-const MAX_CONTEXT_TOKENS = 3000; // total prompt token budget
+const MAX_OBSERVATIONS = 3;
 
 // Priority tiers (1 = never drop, 5 = drop first)
 const PRIORITY = {
   'core': 1,
   'task-packet': 1,
   'role-flavor': 2,
+  'model-profile': 2,
   'context-digest': 3,
+  'strategy': 3,
   'learned-patterns': 4,
   'host-constraints': 5,
 };
 
+// workspaceType → roleFlavors auto-selection when caller doesn't override
+const WORKSPACE_FLAVOR_MAP = {
+  platform: { productManager: 'platform', architect: 'platform', engineer: 'platform' },
+  enterprise: { productManager: 'enterprise', architect: 'enterprise' },
+  'ai-product': { productManager: 'ai-product', architect: 'ai-systems' },
+  growth: { productManager: 'growth' },
+  product: {},
+};
+
 const AGENT_FLAVOR_MAP = {
+  engineer: { classifierKey: 'engineer', rolePrefix: 'engineer' },
   architect: { classifierKey: 'architect', rolePrefix: 'architect' },
   'product-manager': { classifierKey: 'productManager', rolePrefix: 'product-manager' },
   qa: { classifierKey: 'qa', rolePrefix: 'qa' },
@@ -48,6 +68,18 @@ const AGENT_FLAVOR_MAP = {
   'data-engineer': { classifierKey: 'dataEngineer', rolePrefix: 'data-engineer' },
 };
 
+// Merge workspaceType-derived overlays with explicit roleFlavors. Explicit always wins.
+function resolveRoleFlavors(roleFlavors, workspaceType, shortName) {
+  const workspaceDefaults = workspaceType ? (WORKSPACE_FLAVOR_MAP[workspaceType] ?? {}) : {};
+  if (!roleFlavors && !workspaceType) return null;
+  return { ...workspaceDefaults, ...(roleFlavors || {}) };
+}
+
+// Synchronous strategy digest for prompt injection — reads all scope files from the strategy directory.
+function buildStrategyBlock({ tokenLimit = 400 } = {}) {
+  return getStrategyDigestSync();
+}
+
 function compactTokens(text, tokenLimit = 300, { modelId = 'default' } = {}) {
   if (!text) return '';
   const normalized = String(text).trim();
@@ -65,7 +97,13 @@ function readPromptBody(promptFile, rootDir) {
   return fs.readFileSync(filePath, 'utf8').trim();
 }
 
-function buildLearnedPatternsBlock(agentName, { intent = null, workCategory = null, project = null, modelId = 'default' } = {}) {
+function buildLearnedPatternsBlock(agentName, {
+  intent = null,
+  workCategory = null,
+  project = null,
+  modelId = 'default',
+  tokenLimit = MODEL_OPERATING_PROFILES.balanced.learnedPatternsTokens,
+} = {}) {
   try {
     const rootDir = homedir();
     const query = [agentName, intent, workCategory].filter(Boolean).join(' ');
@@ -93,7 +131,7 @@ function buildLearnedPatternsBlock(agentName, { intent = null, workCategory = nu
       const prefix = obs.category === 'anti-pattern' ? '⚠ ' : obs.category === 'decision' ? '✓ ' : '• ';
       const line = `${prefix}${obs.summary}`;
       const lineTokens = estimateTokensSync(line + '\n', { modelId });
-      if (tokens + lineTokens > LEARNED_PATTERNS_TOKEN_LIMIT) break;
+      if (tokens + lineTokens > tokenLimit) break;
       lines.push(line);
       tokens += lineTokens + 1;
     }
@@ -144,42 +182,68 @@ export function composePrompt(agentName, {
   intent = null,
   workCategory = null,
   roleFlavors = null,
+  workspaceType = null,
   project = null,
   injectLearnedPatterns = true,
   modelId = 'default',
+  executionContractModel = null,
 } = {}) {
   const entry = resolvePromptEntry(agentName, { rootDir, registry });
   if (!entry?.promptFile) return { metadata: {}, fragments: [], system: '', messages: [], staticEndIndex: -1, totalTokens: 0 };
 
   const metadata = resolvePromptMetadata(agentName, { rootDir, registry });
   const fragments = [];
+  const selectedProfile = resolveModelOperatingProfile({
+    envValues: executionContractModel?.profile ? { CONSTRUCT_MODEL_PROFILE: executionContractModel.profile.id } : {},
+    selectedModel: executionContractModel?.selectedModel ?? modelId,
+  });
 
-  // 1. Core (priority 1 — never dropped)
   fragments.push({ type: 'core', priority: PRIORITY['core'], label: entry.name, content: readPromptBody(entry.promptFile, rootDir), tokenBudget: null });
 
-  // 2. Role flavor overlay (priority 2)
   const shortName = String(agentName).replace(/^cx-/, '');
   const flavorMapping = AGENT_FLAVOR_MAP[shortName];
-  if (flavorMapping && roleFlavors) {
-    const flavor = roleFlavors[flavorMapping.classifierKey];
+
+  // When workspaceType is provided and roleFlavors doesn't already specify this agent's flavor,
+  // auto-select the matching overlay so agents get domain guidance without requiring explicit caller config.
+  const effectiveRoleFlavors = resolveRoleFlavors(roleFlavors, workspaceType, shortName);
+
+  if (flavorMapping && effectiveRoleFlavors) {
+    const flavor = effectiveRoleFlavors[flavorMapping.classifierKey];
     if (flavor) {
       const overlayBody = readRoleFile(rootDir, `${flavorMapping.rolePrefix}.${flavor}`, {
         source: 'prompt-composer',
         callerContext: agentName,
       });
       if (overlayBody) {
+        const overlayContent = selectedProfile.preferCompressedRoleGuidance
+          ? compactTokens(overlayBody, selectedProfile.roleFlavorTokens, { modelId })
+          : overlayBody;
         fragments.push({
           type: 'role-flavor',
           priority: PRIORITY['role-flavor'],
           label: `${flavorMapping.rolePrefix}.${flavor}`,
-          content: `### ${flavor} domain guidance\n\n${overlayBody}`,
-          tokenBudget: null,
+          content: `### ${flavor} domain guidance\n\n${overlayContent}`,
+          tokenBudget: selectedProfile.roleFlavorTokens,
         });
       }
     }
   }
 
-  // 3. Task context (priority varies, part of static if present)
+  if (selectedProfile.retrievalFirst) {
+    fragments.push({
+      type: 'model-profile',
+      priority: PRIORITY['model-profile'],
+      label: `model-profile.${selectedProfile.id}`,
+      content: [
+        `## ${selectedProfile.label} operating mode`,
+        '',
+        'Prefer retrieval-first execution: gather focused evidence before broad edits.',
+        'Keep plans and summaries compact, stage work in verified steps, and avoid whole-file rewrites unless the task requires them.',
+      ].join('\n'),
+      tokenBudget: 90,
+    });
+  }
+
   if (intent || workCategory) {
     const text = `Intent: ${intent || 'unknown'}\nWork category: ${workCategory || 'unknown'}`;
     fragments.push({
@@ -191,10 +255,13 @@ export function composePrompt(agentName, {
     });
   }
 
-  // 4. Learned patterns (priority 4)
   if (injectLearnedPatterns) {
     const { text: learnedBlock, tokens: learnedTokens } = buildLearnedPatternsBlock(agentName, {
-      intent, workCategory, project, modelId,
+      intent,
+      workCategory,
+      project,
+      modelId,
+      tokenLimit: selectedProfile.learnedPatternsTokens,
     });
     if (learnedBlock) {
       fragments.push({
@@ -202,13 +269,12 @@ export function composePrompt(agentName, {
         priority: PRIORITY['learned-patterns'],
         label: 'observations',
         content: learnedBlock,
-        tokenBudget: LEARNED_PATTERNS_TOKEN_LIMIT,
+        tokenBudget: selectedProfile.learnedPatternsTokens,
         estimatedTokens: learnedTokens,
       });
     }
   }
 
-  // 5. Task packet (priority 1 — never dropped)
   if (task) {
     const taskBlock = [
       task.title ? `Task: ${task.title}` : null,
@@ -229,13 +295,12 @@ export function composePrompt(agentName, {
         type: 'task-packet',
         priority: PRIORITY['task-packet'],
         label: 'workflow-task',
-        content: compactTokens(taskBlock, 150, { modelId }),
-        tokenBudget: 150,
+        content: compactTokens(taskBlock, selectedProfile.taskPacketTokens, { modelId }),
+        tokenBudget: selectedProfile.taskPacketTokens,
       });
     }
   }
 
-  // 6. Context digest (priority 3)
   const digest = buildContextDigest(contextState);
   if (digest) {
     const digestStr = JSON.stringify(digest);
@@ -243,24 +308,34 @@ export function composePrompt(agentName, {
       type: 'context-digest',
       priority: PRIORITY['context-digest'],
       label: 'context',
-      content: compactTokens(digestStr, 200, { modelId }),
-      tokenBudget: 200,
+      content: compactTokens(digestStr, selectedProfile.contextDigestTokens, { modelId }),
+      tokenBudget: selectedProfile.contextDigestTokens,
+    });
+  }
+
+  const strategyText = buildStrategyBlock({ modelId, tokenLimit: selectedProfile.strategyTokens ?? 400 });
+  if (strategyText) {
+    fragments.push({
+      type: 'strategy',
+      priority: PRIORITY['strategy'],
+      label: 'active-strategy',
+      content: strategyText,
+      tokenBudget: selectedProfile.strategyTokens ?? 400,
     });
   }
 
-  // 7. Host constraints (priority 5 — dropped first)
   if (hostConstraints) {
     fragments.push({
       type: 'host-constraints',
       priority: PRIORITY['host-constraints'],
       label: 'host',
-      content: compactTokens(JSON.stringify(hostConstraints), 75, { modelId }),
-      tokenBudget: 75,
+      content: compactTokens(JSON.stringify(hostConstraints), selectedProfile.hostConstraintsTokens, { modelId }),
+      tokenBudget: selectedProfile.hostConstraintsTokens,
     });
   }
 
   // Priority-based pruning
-  const pruned = pruneFragments(fragments, MAX_CONTEXT_TOKENS, modelId);
+  const pruned = pruneFragments(fragments, selectedProfile.maxPromptTokens, modelId);
   const staticEndIndex = findStaticEndIndex(pruned);
 
   // Assemble outputs
@@ -366,6 +441,7 @@ export function summarizePromptComposition(agentName, options = {}) {
     roleFlavors: options.roleFlavors || route?.roleFlavors || null,
   });
   const fragmentTypes = composed.fragments.map((fragment) => fragment.type);
+  const flavorFragment = composed.fragments.find((fragment) => fragment.type === 'role-flavor');
   const composedPromptHash = composed.system
     ? crypto.createHash('sha256').update(composed.system).digest('hex')
     : null;
@@ -393,6 +469,7 @@ export function summarizePromptComposition(agentName, options = {}) {
       routeDispatchPlan: route.dispatchPlan,
       ...(route.roleFlavors ? { routeRoleFlavors: route.roleFlavors } : {}),
     } : {}),
+    ...(flavorFragment ? { promptRoleFlavor: flavorFragment.label } : {}),
     promptHasRoleFlavor: fragmentTypes.includes('role-flavor'),
     promptHasLearnedPatterns: fragmentTypes.includes('learned-patterns'),
     executionContractModel,

package/lib/read-tracker-store.mjs

@@ -0,0 +1,149 @@
+/**
+ * lib/hooks/read-tracker-store.mjs — batched persistence for read-efficiency tracking.
+ *
+ * The Read hook runs in a fresh process for every file read. Persisting the
+ * full session-efficiency store on every invocation is correct but noisy and
+ * expensive. This module appends compact JSONL deltas per read, then folds
+ * them into the durable session summary when the delta log is flushed.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const SESSION_IDLE_RESET_MS = 2 * 60 * 60 * 1000;
+const REPEATED_READ_WARNING_THRESHOLD = 5;
+const REPEATED_READ_TIER2_THRESHOLD = 8;
+const LARGE_READ_WARNING_THRESHOLD = 3;
+const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
+const FILES_LRU_CAP = 200;
+const EFFICIENCY_LARGE_READ_LIMIT = 400;
+
+export function readTrackerPaths(env = process.env) {
+  const home = env.CX_HOME_OVERRIDE || env.HOME || homedir();
+  const cxDir = join(home, '.cx');
+  return {
+    cxDir,
+    efficiencyStore: join(cxDir, 'session-efficiency.json'),
+    deltaLog: join(cxDir, 'session-efficiency.reads.jsonl'),
+    warnFlags: join(cxDir, 'warn-flags.txt'),
+  };
+}
+
+export function freshEfficiencyStats(nowIso) {
+  return {
+    sessionStartedAt: nowIso,
+    lastUpdatedAt: nowIso,
+    readCount: 0,
+    uniqueFileCount: 0,
+    repeatedReadCount: 0,
+    largeReadCount: 0,
+    totalBytesRead: 0,
+    warnings: {},
+    files: {},
+  };
+}
+
+export function loadEfficiencyStats(nowIso, env = process.env) {
+  const { efficiencyStore } = readTrackerPaths(env);
+  const fresh = freshEfficiencyStats(nowIso);
+  try {
+    const existing = JSON.parse(readFileSync(efficiencyStore, 'utf8'));
+    const lastUpdated = new Date(existing.lastUpdatedAt || 0).getTime();
+    if (!lastUpdated || Date.now() - lastUpdated > SESSION_IDLE_RESET_MS) return fresh;
+    return { ...fresh, ...existing, warnings: existing.warnings || {}, files: existing.files || {} };
+  } catch {
+    return fresh;
+  }
+}
+
+function appendWarning(message, env = process.env) {
+  try {
+    const { warnFlags } = readTrackerPaths(env);
+    appendFileSync(warnFlags, `${message}\n`);
+  } catch { /* best effort */ }
+}
+
+function topRepeatedPath(files) {
+  return Object.entries(files || {})
+    .map(([filePath, value]) => ({ filePath, count: Number(value?.count || 0) }))
+    .filter((entry) => entry.count > 1)
+    .sort((a, b) => b.count - a.count || a.filePath.localeCompare(b.filePath))[0];
+}
+
+export function applyReadDelta(stats, delta, env = process.env) {
+  const existingFile = stats.files[delta.path];
+  const isLargeRead = Number(delta.limit || 0) > EFFICIENCY_LARGE_READ_LIMIT;
+
+  stats.readCount += 1;
+  stats.totalBytesRead += Number(delta.size || 0);
+  if (isLargeRead) stats.largeReadCount += 1;
+  if (existingFile) stats.repeatedReadCount += 1;
+  else stats.uniqueFileCount += 1;
+
+  stats.files[delta.path] = {
+    count: Number(existingFile?.count || 0) + 1,
+    size: Number(delta.size || 0),
+    lastReadAt: delta.ts,
+    lastRequestedLimit: Number(delta.limit || 0),
+  };
+
+  const fileEntries = Object.entries(stats.files);
+  if (fileEntries.length > FILES_LRU_CAP) {
+    fileEntries.sort((a, b) => (a[1]?.lastReadAt || '').localeCompare(b[1]?.lastReadAt || ''));
+    const drop = fileEntries.length - FILES_LRU_CAP;
+    for (let i = 0; i < drop; i++) delete stats.files[fileEntries[i][0]];
+  }
+
+  if (stats.repeatedReadCount >= REPEATED_READ_WARNING_THRESHOLD && !stats.warnings.repeatedReads) {
+    const top = topRepeatedPath(stats.files);
+    const topNote = top ? ` Top repeat: ${top.filePath} (${top.count}x).` : '';
+    appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session.${topNote} Use rg or construct distill before re-reading more files.`, env);
+    stats.warnings.repeatedReads = delta.ts;
+    if (stats.repeatedReadCount >= REPEATED_READ_TIER2_THRESHOLD && !stats.warnings.repeatedReadsTier2) {
+      appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session — consider using construct distill or rg before re-reading entire files.`, env);
+      stats.warnings.repeatedReadsTier2 = delta.ts;
+    }
+  }
+
+  if (stats.largeReadCount >= LARGE_READ_WARNING_THRESHOLD && !stats.warnings.largeReads) {
+    appendWarning(`Efficiency: ${stats.largeReadCount} large reads this session — prefer rg/glob plus targeted reads under 400 lines.`, env);
+    stats.warnings.largeReads = delta.ts;
+  }
+
+  if (stats.totalBytesRead >= TOTAL_BYTES_WARNING_THRESHOLD && !stats.warnings.totalBytes) {
+    appendWarning(`Efficiency: ${Math.round(stats.totalBytesRead / 1024)} KB read this session — consider distill/query-focused retrieval or compact context before continuing.`, env);
+    stats.warnings.totalBytes = delta.ts;
+  }
+
+  stats.lastUpdatedAt = delta.ts;
+  return stats;
+}
+
+export function recordReadDelta(delta, env = process.env) {
+  const { cxDir, deltaLog } = readTrackerPaths(env);
+  mkdirSync(cxDir, { recursive: true });
+  appendFileSync(deltaLog, `${JSON.stringify(delta)}\n`, 'utf8');
+}
+
+export function flushReadTrackerDeltas({ nowIso = new Date().toISOString(), env = process.env } = {}) {
+  const { cxDir, deltaLog, efficiencyStore } = readTrackerPaths(env);
+  mkdirSync(cxDir, { recursive: true });
+  const stats = loadEfficiencyStats(nowIso, env);
+  if (!existsSync(deltaLog)) return stats;
+
+  const lines = readFileSync(deltaLog, 'utf8')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  for (const line of lines) {
+    try {
+      const delta = JSON.parse(line);
+      applyReadDelta(stats, delta, env);
+    } catch { /* best effort */ }
+  }
+
+  writeFileSync(efficiencyStore, `${JSON.stringify(stats, null, 2)}\n`);
+  rmSync(deltaLog, { force: true });
+  return stats;
+}