fraim 2.0.337 → 2.0.339

package/dist/src/local-mcp-server/learning-usage-command.js

@@ -18,6 +18,18 @@ const learning_context_builder_1 = require("./learning-context-builder");
 const learning_usage_analysis_1 = require("./learning-usage-analysis");
 const learning_usage_store_1 = require("./learning-usage-store");
 const learning_usage_attestation_1 = require("./learning-usage-attestation");
+const learning_usage_verify_1 = require("./learning-usage-verify");
+const pack_home_1 = require("../cli/utils/pack-home");
+/**
+ * The repair for a usage record that has gone wrong.
+ *
+ * The record is derived (#1103 R17), so the fix is to rebuild it rather than to
+ * reconcile it in place. Measured on a 733-file retrospective corpus: a rebuild
+ * lands with zero split identities and one model bucket, because the identity
+ * resolution and the model normalization fix the causes and a rebuilt store
+ * carries no legacy shape.
+ */
+const REBUILD_NOTE = 'Delete the `usage/` directory and run `learning-usage backfill` to rebuild the record from the retrospectives. The record is derived: every firing is also written in the retrospective that attested it, so a rebuild restores one identity per lesson and one bucket per model. It costs the offer history, which rebuilds itself from live traffic.';
 function resolveWorkspaceRoot(options) {
     return node_path_1.default.resolve(options.workspaceRoot || options.root || process.cwd());
 }
@@ -38,6 +50,23 @@ function addCommonOptions(command) {
         .option('--user <email>', 'Active user email')
         .option('--json', 'Print JSON');
 }
+/**
+ * Issue #1752 C1: every command that draws a per-model conclusion takes the model
+ * from its caller. It is never inferred from the record, because the record is
+ * shared by concurrent sessions from more than one agent on more than one
+ * machine, so inference reports whichever wrote last.
+ */
+function addModelOption(command) {
+    return command.option('--model <model>', 'The model you are running under. Falls back to FRAIM_ACTIVE_MODEL, then reports unknown');
+}
+/**
+ * Issue #1752 B: the offer and firing log bounds are applied when the event log is
+ * folded, so a read states the bounds it wants rather than inheriting whatever the
+ * last writer used.
+ */
+function readStore(workspaceRoot) {
+    return (0, learning_usage_store_1.readUsageStore)(undefined, { limits: (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot) });
+}
 // ── offers ───────────────────────────────────────────────────────────────────
 const offersCommand = addCommonOptions(new commander_1.Command('offers'))
     .description('List the learning entries and rule files the runtime delivered, so an attestation is written against the record rather than memory')
@@ -52,7 +81,7 @@ const offersCommand = addCommonOptions(new commander_1.Command('offers'))
     // actually delivered. Re-deriving from the files on disk answers a subtly
     // different question — what would be delivered now — and the two diverge if a
     // learning file changed during the job.
-    const store = (0, learning_usage_store_1.readUsageStore)();
+    const store = readStore(workspaceRoot);
     const recorded = Object.values(store.entries)
         .filter((entry) => entry.offered.log.some((offer) => offer.job === options.job))
         .map((entry) => {
@@ -102,6 +131,7 @@ const recordFiringsCommand = addCommonOptions(new commander_1.Command('record-fi
     .option('--agent <name>', 'Agent that attested')
     .option('--model <model>', 'Model that attested')
     .option('--legacy', 'Also accept the pre-#1103 prose form')
+    .option('--force', 'Record the firings even when they violate the scoped integrity invariant, flagging the entry instead of refusing. Use when the offers are known to be stranded in an unmerged store copy or an unsynced machine log')
     .action((options) => {
     const workspaceRoot = resolveWorkspaceRoot(options);
     const user = resolveUser(options);
@@ -118,6 +148,7 @@ const recordFiringsCommand = addCommonOptions(new commander_1.Command('record-fi
         agent: options.agent ?? null,
         model: options.model ?? null,
         legacy: Boolean(options.legacy),
+        integrityMode: options.force ? 'flag' : 'throw',
     });
     emit(result, options.json, () => {
         const lines = [
@@ -151,17 +182,17 @@ const classifyCommand = addCommonOptions(new commander_1.Command('classify'))
     // character, so an agent assembling `T:<family>:<title>` into a shell command
     // would be interpolating untrusted text into a command line. Passing the title
     // as its own argument keeps it a single argv entry.
-    let key;
-    if (options.entry) {
-        key = String(options.entry);
-    }
-    else if (options.title && options.family) {
-        key = (0, learning_usage_store_1.titleUsageKey)(String(options.family), String(options.title));
-    }
-    else {
+    if (!options.entry && !(options.title && options.family)) {
         throw new Error('Pass --entry <id>, or --title <title> together with --family <family>.');
     }
-    const store = (0, learning_usage_store_1.readUsageStore)();
+    // #1752 A1: the same identity function the offer and firing paths use, so
+    // the CLI cannot ask about a key neither of them would have written.
+    const key = (0, learning_usage_store_1.resolveEntryIdentity)({
+        id: options.entry ? String(options.entry) : null,
+        fileType: options.family ? String(options.family) : null,
+        title: options.title ? String(options.title) : null,
+    }).key;
+    const store = readStore(workspaceRoot);
     const diagnosis = (0, learning_usage_analysis_1.classifyRecurrence)(store, {
         key,
         job: options.job,
@@ -177,14 +208,13 @@ const classifyCommand = addCommonOptions(new commander_1.Command('classify'))
     ].join('\n'));
 });
 // ── candidates ───────────────────────────────────────────────────────────────
-const candidatesCommand = addCommonOptions(new commander_1.Command('candidates'))
+const candidatesCommand = addModelOption(addCommonOptions(new commander_1.Command('candidates')))
     .description('List retirement candidates: offered often under the current model with no firing under it, paired with a structural signal')
-    .option('--model <model>', 'Override the current model (defaults to the most recently offered-to model)')
     .option('--detector <path>', 'Path to the corpus hygiene detector that provides the structural signal')
     .action((options) => {
     const workspaceRoot = resolveWorkspaceRoot(options);
     const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const result = (0, learning_usage_analysis_1.findRetirementCandidates)((0, learning_usage_store_1.readUsageStore)(), {
+    const result = (0, learning_usage_analysis_1.findRetirementCandidates)(readStore(workspaceRoot), {
         workspaceRoot,
         limits,
         currentModel: options.model ?? undefined,
@@ -192,7 +222,14 @@ const candidatesCommand = addCommonOptions(new commander_1.Command('candidates')
     });
     emit(result, options.json, () => {
         if (result.candidates.length === 0) {
-            return `No retirement candidates. Current model: ${result.currentModel ?? 'unknown'}; threshold ${result.offerThreshold} offers.`;
+            const lines = [`No retirement candidates. Current model: ${result.currentModel ?? 'unknown'}; threshold ${result.offerThreshold} offers.`];
+            if (result.reason)
+                lines.push('', result.reason);
+            const unknownAttribution = result.notCandidates.filter((c) => /attribution is unknown/i.test(c.reason));
+            if (unknownAttribution.length > 0) {
+                lines.push('', `${unknownAttribution.length} entr${unknownAttribution.length === 1 ? 'y was' : 'ies were'} held back because their firings carry no model, so how hard they are working under this model cannot be measured.`);
+            }
+            return lines.join('\n');
         }
         const lines = [`Current model: ${result.currentModel ?? 'unknown'}. Threshold: ${result.offerThreshold} offers.`, ''];
         for (const c of result.candidates) {
@@ -203,13 +240,13 @@ const candidatesCommand = addCommonOptions(new commander_1.Command('candidates')
     });
 });
 // ── standing ─────────────────────────────────────────────────────────────────
-const standingCommand = addCommonOptions(new commander_1.Command('standing'))
+const standingCommand = addModelOption(addCommonOptions(new commander_1.Command('standing')))
     .description('Assess each entry as promoted, standard or demoted from its usage record, and list the ones whose standing should change')
     .option('--changes-only', 'Print only the entries whose standing should change')
     .action((options) => {
     const workspaceRoot = resolveWorkspaceRoot(options);
     const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const report = (0, learning_usage_analysis_1.assessStanding)((0, learning_usage_store_1.readUsageStore)(), { limits });
+    const report = (0, learning_usage_analysis_1.assessStanding)(readStore(workspaceRoot), { limits });
     const payload = options.changesOnly ? { ...report, assessments: report.changes } : report;
     emit(payload, options.json, () => {
         const rows = (options.changesOnly ? report.changes : report.assessments);
@@ -231,16 +268,17 @@ const standingCommand = addCommonOptions(new commander_1.Command('standing'))
     });
 });
 // ── report ───────────────────────────────────────────────────────────────────
-const reportCommand = addCommonOptions(new commander_1.Command('report'))
+const reportCommand = addModelOption(addCommonOptions(new commander_1.Command('report')))
     .description('Answer which learnings are still earning their place, from the record rather than from memory')
     .option('--window <days>', 'Reporting window', '90')
     .action((options) => {
     const workspaceRoot = resolveWorkspaceRoot(options);
     const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const report = (0, learning_usage_analysis_1.buildUsageReport)((0, learning_usage_store_1.readUsageStore)(), {
+    const report = (0, learning_usage_analysis_1.buildUsageReport)(readStore(workspaceRoot), {
         workspaceRoot,
         limits,
         windowDays: Number.parseInt(options.window, 10) || 90,
+        currentModel: options.model ?? undefined,
     });
     emit(report, options.json, () => {
         const lines = [
@@ -256,7 +294,13 @@ const reportCommand = addCommonOptions(new commander_1.Command('report'))
         }
         if (report.ignoredWhileInContext.length) {
             lines.push('', 'Ignored while in context');
-            report.ignoredWhileInContext.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. In context and the work went against it, so the entry needs work rather than another recurrence.`));
+            // #1752 defect 8: this section selects on the `ignored` count, so it
+            // prints that count. Printing only the clock-advancing one made the
+            // section contradict its own evidence column.
+            report.ignoredWhileInContext.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Attested ignored ${e.ignored} time${e.ignored === 1 ? '' : 's'} (fired ${e.fired}). In context and the work went against it, so the entry needs work rather than another recurrence.`));
+        }
+        if (report.integrityFlagged > 0) {
+            lines.push('', `${report.integrityFlagged} entr${report.integrityFlagged === 1 ? 'y has' : 'ies have'} an integrity flag: more attested firings than recorded offers. Run \`learning-usage verify\` before acting on anything below.`);
         }
         lines.push('', 'Nothing is retired from this view. Run sleep-on-learnings to decide.');
         return lines.join('\n');
@@ -343,6 +387,19 @@ function stampFile(filePath, fileType, apply) {
     return { file: filePath, entriesStamped: stamped, entriesAlreadyStamped: alreadyStamped };
 }
 const FILE_TYPES = ['mistake-patterns', 'preferences', 'validated-patterns', 'manager-coaching'];
+function defaultStampDirs(workspaceRoot) {
+    const dirs = [node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings')];
+    for (const level of ['org', 'manager']) {
+        try {
+            dirs.push(node_path_1.default.join((0, pack_home_1.resolvePackHome)(level).contentRoot, 'learnings'));
+        }
+        catch {
+            // A pack home that does not resolve is simply not stamped. Reported by the
+            // filesScanned count rather than failing the command.
+        }
+    }
+    return [...new Set(dirs)];
+}
 function fileTypeFromName(fileName) {
     for (const type of FILE_TYPES) {
         if (fileName.includes(type))
@@ -356,9 +413,14 @@ const stampIdsCommand = addCommonOptions(new commander_1.Command('stamp-ids'))
     .option('--apply', 'Write the changes. Without this flag the command reports what it would do')
     .action((options) => {
     const workspaceRoot = resolveWorkspaceRoot(options);
+    // #1752 A3: the default set is every tier the context reader merges, not
+    // the repo alone. `stamp-ids` never reaching the org and manager pack homes
+    // is half of defect 4: one lesson stamped in one tier and unstamped in the
+    // other resolved to two usage keys. Still opt-in behind --apply, and still a
+    // format migration that inserts one identifier line and touches no lesson text.
     const dirs = options.dir.length
         ? options.dir.map((d) => node_path_1.default.resolve(d))
-        : [node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings')];
+        : defaultStampDirs(workspaceRoot);
     const results = [];
     for (const dir of dirs) {
         if (!node_fs_1.default.existsSync(dir))
@@ -380,7 +442,8 @@ const stampIdsCommand = addCommonOptions(new commander_1.Command('stamp-ids'))
         files: results,
     };
     emit(payload, options.json, () => [
-        `${payload.apply ? 'Stamped' : 'Would stamp'} ${payload.entriesStamped} entries across ${payload.filesScanned} files.`,
+        `${payload.apply ? 'Stamped' : 'Would stamp'} ${payload.entriesStamped} entries across ${payload.filesScanned} files in ${dirs.length} director${dirs.length === 1 ? 'y' : 'ies'}:`,
+        ...dirs.map((d) => `  ${d}`),
         `${payload.entriesAlreadyStamped} entries already carry an id.`,
         payload.apply ? '' : 'Re-run with --apply to write the changes.',
     ].filter(Boolean).join('\n'));
@@ -394,6 +457,52 @@ const pruneCommand = addCommonOptions(new commander_1.Command('prune'))
     const result = (0, learning_usage_store_1.pruneUsageStore)(limits);
     emit({ ...result, storePath: (0, learning_usage_store_1.resolveUsageStorePath)(), limits }, options.json, () => `Pruned ${result.prunedOfferRecords} offer records and ${result.prunedFiringRecords} firing records across ${result.entries} entries. Aggregates unchanged.`);
 });
+function mb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+// ── verify ───────────────────────────────────────────────────────────────────
+const verifyCommand = addModelOption(addCommonOptions(new commander_1.Command('verify')))
+    .description('Report the integrity of the usage record in one output: split identities, impossible counters, split model buckets, unmerged store copies, and how far each snapshot checkpoint is behind its log')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const report = (0, learning_usage_verify_1.buildVerifyReport)({
+        snapshotPath: (0, learning_usage_store_1.resolveUsageStorePath)(),
+        limits: (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot),
+        currentModel: options.model ?? undefined,
+    });
+    emit(report, options.json, () => {
+        const lines = [
+            `Usage record: ${report.entries} entries at ${report.snapshotPath}`,
+            `Current model: ${report.currentModel ?? 'unknown'}`,
+            '',
+        ];
+        const finding = (count, singular, plural, remedy) => count === 0 ? `  none: ${singular}` : `  ${count} ${count === 1 ? singular : plural}. ${remedy}`;
+        lines.push('Identity', finding(report.twinPairs.length, 'lesson tracked under two keys', 'lessons tracked under two keys', 'Its offers and its firings are on different records, so every count about it is partial.'), report.unmatchedTitleKeys.length
+            ? `  ${report.unmatchedTitleKeys.length} title-keyed record${report.unmatchedTitleKeys.length === 1 ? ' has' : 's have'} no id twin. Expected for entries no tier has stamped; run \`stamp-ids\` to reduce it.`
+            : '  every title-keyed record has been matched or has no twin', '', 'Counters', finding(report.invariantViolations.length, 'entry holds more attested firings than recorded offers', 'entries hold more attested firings than recorded offers', 'An entry cannot fire without being offered, so one of the two counters is wrong. History stranded in a store copy nothing reads is the usual cause.'), finding(report.caseVariantModelBuckets.length, 'model bucket differs only by case', 'model buckets differ only by case', 'One model spelled two ways splits its own denominator, so every per-model conclusion about it is computed on a fraction of its traffic.'), finding(report.unknownModelAttribution.length, 'entry fired with no model recorded', 'entries fired with no model recorded', 'Per-model retirement cannot be answered for these, and they are held back rather than counted as zero. These were attested before record-firings carried --agent and --model, so the model was never recorded against them and a rebuild cannot invent it; attestations recorded from now on carry both.'), '', 'Storage');
+        if (report.storeCopies.length === 0) {
+            lines.push('  one store file, no unmerged copies');
+        }
+        else {
+            lines.push(`  ${report.storeCopies.length} unmerged store cop${report.storeCopies.length === 1 ? 'y' : 'ies'} beside the canonical snapshot:`);
+            for (const copy of report.storeCopies) {
+                lines.push(`    ${copy.path}: ${copy.readable ? `${copy.entries} entries, ${copy.offers} offers, ${copy.firings} firings` : `unreadable (${copy.error ?? 'unknown error'})`}`);
+            }
+            lines.push('    Nothing reads these. Their history is recoverable only through a rebuild.');
+        }
+        lines.push(`  event logs folded: ${report.eventLogs.length === 0 ? 'none' : report.eventLogs.map((l) => `${l.machineId} (${l.bytes} bytes)`).join(', ')}`);
+        for (const [machineId, lag] of Object.entries(report.checkpointLag)) {
+            lines.push(`  checkpoint lag for ${machineId}: ${lag} bytes${lag > 0 ? ' behind the log head' : ''}`);
+        }
+        lines.push(report.compactionAdvised
+            ? `  log size ${mb(report.totalLogBytes)} is past the ${mb(report.compactionAdvisoryBytes)} point where a cold fold stops fitting the context-injection budget. Run \`learning-usage prune\` to compact it to the configured retention window.`
+            : `  log size ${mb(report.totalLogBytes)} of ${mb(report.compactionAdvisoryBytes)} before compaction is worth running.`);
+        if (report.rebuildAdvised)
+            lines.push('', REBUILD_NOTE);
+        lines.push('', 'Nothing here blocks anything. This is what the record can and cannot currently prove.');
+        return lines.join('\n');
+    });
+});
 // ── root ─────────────────────────────────────────────────────────────────────
 exports.learningUsageCommand = new commander_1.Command('learning-usage')
     .description('Read and analyse the learning and rule usage record (issue #1103)')
@@ -405,4 +514,5 @@ exports.learningUsageCommand = new commander_1.Command('learning-usage')
     .addCommand(reportCommand)
     .addCommand(backfillCommand)
     .addCommand(stampIdsCommand)
-    .addCommand(pruneCommand);
+    .addCommand(pruneCommand)
+    .addCommand(verifyCommand);

package/dist/src/local-mcp-server/learning-usage-events.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEventDir = resolveEventDir;
+exports.resolveMachineId = resolveMachineId;
+exports.appendEvents = appendEvents;
+exports.listEventLogs = listEventLogs;
+exports.readEventsSince = readEventsSince;
+exports.compactEventLogs = compactEventLogs;
+/**
+ * Issue #1752 — the durable half of the usage record.
+ *
+ * The store used to be one mutable JSON document rewritten by every writer with a
+ * plain `writeFileSync`. Measured (spike S1b): eight concurrent processes doing
+ * that on a *plain local disk*, no sync folder involved, lost 1589 of 1600
+ * writes. The four OneDrive conflict copies in issue #1752 are a symptom of the
+ * same defect, not its cause.
+ *
+ * So the durable artifact is an append-only log, one file per machine:
+ *
+ *   OFFER/FIRING event  →  appendFileSync of one whole JSON line
+ *   usage/learning-usage.json  →  a derived snapshot with a byte checkpoint
+ *
+ * Three measurements decided the shape, and each closed off an alternative:
+ *
+ *   S2   16 processes x 1000 lines on the real OneDrive-synced path produced
+ *        16000/16000 complete parseable lines, 0 interleaved, 0 conflict copies.
+ *        That is what removes the need for a same-machine lock. The per-machine
+ *        filename is what removes the cross-machine question, because two
+ *        machines then never write one file.
+ *   S3   `renameSync` over a target any process holds open fails EPERM 100 times
+ *        in 100 on Windows, on a synced path *and* a local one, because Node's
+ *        `openSync(path,'r')` does not request FILE_SHARE_DELETE. The usage store
+ *        is read by concurrent MCP processes by design, so rename-publish is not
+ *        available here. Recorded so it is not re-proposed. See also #820.
+ *   S4b  A full fold is linear: 84 ms at today's volume, 794 ms at ten times it.
+ *        A snapshot plus a tail fold is 2.6 ms at both 9.9 MB and 79 MB. Flat.
+ *
+ * This module owns the log files and nothing else: framing, appending, reading a
+ * tail from a byte offset, and compaction. It knows a line is a JSON object and
+ * knows nothing about what a usage record looks like. That is deliberate — the
+ * record shape lives in `learning-usage-store.ts`, which imports this, so there
+ * is no cycle between them.
+ *
+ * The same primitive is already used by `src/ai-hub/raw-event-log-store.ts`
+ * (append one JSON line, track byte offsets); this is the learning-usage
+ * equivalent rather than a second general mechanism.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/** Subdirectory of the usage folder holding the per-machine logs. */
+const EVENT_DIR_NAME = 'events';
+const LOG_SUFFIX = '.jsonl';
+/** The log directory that belongs to a snapshot: `<usage>/events/`. */
+function resolveEventDir(snapshotPath) {
+    return (0, path_1.join)((0, path_1.dirname)(snapshotPath), EVENT_DIR_NAME);
+}
+/**
+ * The filename component identifying this machine. Two machines must never write
+ * one file, which is the entire cross-machine safety argument, so anything that
+ * is not a safe filename character is replaced rather than dropped (dropping can
+ * collide two different hostnames onto one name).
+ */
+function resolveMachineId() {
+    const raw = (() => { try {
+        return (0, os_1.hostname)();
+    }
+    catch {
+        return '';
+    } })();
+    const safe = String(raw || 'unknown-machine').trim().replace(/[^A-Za-z0-9._-]/g, '_');
+    return safe || 'unknown-machine';
+}
+function logPathFor(eventDir, machineId) {
+    return (0, path_1.join)(eventDir, `${machineId}${LOG_SUFFIX}`);
+}
+/**
+ * Append one JSON line per record. No read, so there is no lost-update window to
+ * narrow: the window is gone rather than smaller.
+ */
+function appendEvents(eventDir, records, machineId = resolveMachineId()) {
+    if (records.length === 0)
+        return 0;
+    (0, fs_1.mkdirSync)(eventDir, { recursive: true });
+    const logPath = logPathFor(eventDir, machineId);
+    const separator = endsOnARecordBoundary(logPath) ? '' : '\n';
+    const payload = `${separator}${records.map((record) => JSON.stringify(record)).join('\n')}\n`;
+    (0, fs_1.appendFileSync)(logPath, payload, 'utf8');
+    return records.length;
+}
+/**
+ * Does the log already end where a record ends?
+ *
+ * A process killed part-way through an append leaves a line with no terminator.
+ * Appending straight onto it concatenates the torn record and the new one into a
+ * single unparseable line, so one interrupted write costs two events rather than
+ * one. Found in the #1752 bug bash. Closing the boundary first means a torn write
+ * loses only itself.
+ *
+ * One byte read per append, and only when the log already exists.
+ */
+function endsOnARecordBoundary(logPath) {
+    try {
+        const fd = (0, fs_1.openSync)(logPath, 'r');
+        try {
+            const size = (0, fs_1.fstatSync)(fd).size;
+            if (size === 0)
+                return true;
+            const last = Buffer.alloc(1);
+            (0, fs_1.readSync)(fd, last, 0, 1, size - 1);
+            return last[0] === 0x0a;
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        // No log yet, or it cannot be read. A fresh file starts on a boundary, and an
+        // unreadable one is the fold's problem rather than the append's.
+        return true;
+    }
+}
+function listEventLogs(eventDir) {
+    if (!(0, fs_1.existsSync)(eventDir))
+        return [];
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)(eventDir);
+    }
+    catch {
+        return [];
+    }
+    const logs = [];
+    for (const name of names) {
+        if (!name.endsWith(LOG_SUFFIX))
+            continue;
+        const path = (0, path_1.join)(eventDir, name);
+        let size = 0;
+        try {
+            const fd = (0, fs_1.openSync)(path, 'r');
+            try {
+                size = (0, fs_1.fstatSync)(fd).size;
+            }
+            finally {
+                (0, fs_1.closeSync)(fd);
+            }
+        }
+        catch {
+            continue;
+        }
+        logs.push({ machineId: name.slice(0, -LOG_SUFFIX.length), path, size });
+    }
+    return logs.sort((a, b) => a.machineId.localeCompare(b.machineId));
+}
+function readTail(log, from) {
+    const restarted = from > log.size;
+    const start = restarted ? 0 : Math.max(0, from);
+    const length = log.size - start;
+    if (length <= 0) {
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    let text;
+    try {
+        const fd = (0, fs_1.openSync)(log.path, 'r');
+        try {
+            const buffer = Buffer.alloc(length);
+            const read = (0, fs_1.readSync)(fd, buffer, 0, length, start);
+            text = buffer.subarray(0, read).toString('utf8');
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        // Unreadable right now (locked, mid-sync). The checkpoint does not advance,
+        // so the next reader picks it up. Degrading to what is readable is the
+        // existing contract for this derived data.
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    // Only complete lines are consumed. A trailing partial is what an interrupted
+    // append leaves behind, and advancing past it would lose the record for good.
+    const lastNewline = text.lastIndexOf('\n');
+    if (lastNewline === -1) {
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    const complete = text.slice(0, lastNewline);
+    const partialBytes = Buffer.byteLength(text.slice(lastNewline + 1), 'utf8');
+    const records = [];
+    let skippedLines = 0;
+    for (const line of complete.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                records.push(parsed);
+            else
+                skippedLines += 1;
+        }
+        catch {
+            skippedLines += 1;
+        }
+    }
+    return { ...log, records, skippedLines, through: log.size - partialBytes, restarted };
+}
+/**
+ * Read every log's tail past its checkpoint.
+ *
+ * A checkpoint past the end of its log means the log was compacted or replaced
+ * underneath the snapshot. `restarted` says so, and the caller discards the whole
+ * snapshot rather than returning a short count that looks like real data.
+ */
+function readEventsSince(eventDir, checkpoints) {
+    const reads = listEventLogs(eventDir).map((log) => readTail(log, checkpoints[log.machineId] ?? 0));
+    return {
+        reads,
+        skippedLines: reads.reduce((sum, r) => sum + r.skippedLines, 0),
+        restarted: reads.some((r) => r.restarted),
+    };
+}
+/**
+ * Rewrite every log keeping only the records `keep` accepts.
+ *
+ * Required rather than an optimization: S4 measured a cold full fold growing
+ * linearly to 794 ms at ten times today's volume, and the checkpoint only makes a
+ * cold fold rare, not bounded.
+ *
+ * Published by writing a temp file and renaming it. That is safe here and not on
+ * the snapshot (S3), because nothing holds a compacted log open for reading in
+ * the way concurrent MCP processes hold the snapshot: this runs from the CLI, and
+ * a failed rename leaves the original log untouched.
+ */
+function compactEventLogs(eventDir, keep) {
+    const result = { scanned: 0, kept: 0, dropped: 0, skippedLines: 0, logs: [] };
+    for (const log of listEventLogs(eventDir)) {
+        const read = readTail(log, 0);
+        result.scanned += read.records.length;
+        result.skippedLines += read.skippedLines;
+        const retained = read.records.filter(keep);
+        result.kept += retained.length;
+        result.dropped += read.records.length - retained.length;
+        if (retained.length === read.records.length && read.skippedLines === 0)
+            continue;
+        const temp = `${log.path}.compacting`;
+        try {
+            (0, fs_1.writeFileSync)(temp, retained.length ? `${retained.map((r) => JSON.stringify(r)).join('\n')}\n` : '', 'utf8');
+            (0, fs_1.renameSync)(temp, log.path);
+        }
+        catch {
+            // The log is authoritative and the original is still intact, so a failed
+            // compaction costs a slower cold fold and nothing else.
+            try {
+                (0, fs_1.rmSync)(temp, { force: true });
+            }
+            catch { /* best effort */ }
+        }
+    }
+    result.logs = listEventLogs(eventDir);
+    return result;
+}

package/dist/src/local-mcp-server/learning-usage-projection.js

@@ -50,30 +50,34 @@ function buildUsageLookup(store) {
 /**
  * Resolve the usage for one entry from whichever handles it has. Prefers the id,
  * because a title is only a fallback for entries the id migration has not reached.
+ *
+ * Issue #1752 A1: the preference order is `resolveEntryIdentity`'s, not a second
+ * copy of it. The title key is still tried afterwards, because a record written
+ * before the entry was stamped is reachable only by title.
  */
 function lookupUsage(lookup, id, fileType, title) {
-    if (id) {
-        const byId = lookup.get(id);
-        if (byId)
-            return byId;
-    }
-    return lookup.get((0, learning_usage_store_1.titleUsageKey)(fileType, title));
+    const identity = (0, learning_usage_store_1.resolveEntryIdentity)({ id, fileType, title });
+    const resolved = lookup.get(identity.key);
+    if (resolved)
+        return resolved;
+    return identity.source === 'id' ? lookup.get((0, learning_usage_store_1.titleUsageKey)(fileType, title)) : undefined;
 }
 /**
- * The model with the most recent offer. Used as "the current model" for the
- * per-model retirement question, so it follows the agent in use rather than
- * needing to be configured.
+ * Issue #1752 C1 — "the current model" comes from the caller, never from the store.
+ *
+ * This used to return the model of the globally most-recent offer. The store is
+ * shared by concurrent sessions from two machines and two agents, so that reports
+ * whichever agent wrote last. On the sleep-on-learnings run of 2026-09-18 it
+ * answered `gpt-5` while the session was Claude Opus 5, and since retirement
+ * candidacy is computed per model, every per-model conclusion in that run was
+ * computed against a model that was not running.
+ *
+ * Resolution order is the explicit flag, then `FRAIM_ACTIVE_MODEL`, then null.
+ * That follows the existing `FRAIM_ACTIVE_USER_EMAIL` convention, which is
+ * read-only and operator-set, so it introduces no new configuration mechanism.
+ * Null is reported as `unknown` and suppresses every per-model conclusion rather
+ * than being computed against a null bucket.
  */
-function resolveCurrentModel(store) {
-    let bestDate = '';
-    let bestModel = null;
-    for (const record of Object.values(store.entries)) {
-        for (const entry of record.offered.log) {
-            if (entry.model && entry.date >= bestDate) {
-                bestDate = entry.date;
-                bestModel = entry.model;
-            }
-        }
-    }
-    return bestModel;
+function resolveCurrentModel(explicit) {
+    return (0, learning_usage_store_1.normalizeModelName)(explicit) ?? (0, learning_usage_store_1.normalizeModelName)(process.env.FRAIM_ACTIVE_MODEL);
 }