fraim 2.0.338 → 2.0.340

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

@@ -18,6 +18,13 @@ 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");
+/**
+ * Preserve checkpointed history and distinguish backup recovery from attestation backfill.
+ * Backfill supplements older firings; it cannot reconstruct missing offers.
+ */
+const REBUILD_NOTE = "Keep `learning-usage.json`, its `.checkpoint` backup, `events/` and any conflict copies. After consolidation, the snapshot and checkpoint backup preserve lifetime counters and already-counted source markers; the remaining journal cannot rebuild that history. A missing or torn snapshot is read from its checkpoint backup automatically. Restore matching checkpoint and journal files from backup if both copies are damaged. Inspect split identities and conflict copies before repairing them; do not delete the snapshot to clear a warning. Separately, `learning-usage backfill` can recover older firings from retrospectives; raw learnings and retrospectives cannot restore runtime offers.";
 function resolveWorkspaceRoot(options) {
     return node_path_1.default.resolve(options.workspaceRoot || options.root || process.cwd());
 }
@@ -38,6 +45,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 +76,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 +126,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 +143,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 +177,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 +203,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 +217,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 +235,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 +263,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 +289,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 +382,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 +408,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 +437,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 +452,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. Preserve them and the checkpoint backup for inspection; do not delete snapshots to clear this warning.');
+        }
+        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 consolidate processed events into the snapshot and checkpoint backup, then clear them independently of retention.`
+            : `  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 +509,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,267 @@
+"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;
+/**
+ * Per-machine usage journals: job runs append complete JSON lines; sleep folds
+ * them into a recoverable snapshot and removes processed records.
+ *
+ * A cleared journal contains only {_usageJournalThroughBytes:N}. This framing
+ * marker preserves its logical position across atomic replacement, so a crash
+ * between checkpoint publication and journal cleanup cannot reset offsets or
+ * count an event twice. It contains no activity details. New appends continue
+ * from N; an older/missing snapshot cannot silently cold-fold compacted history.
+ *
+ * Maintenance requires no concurrent writers or sync activity. Ordinary writers
+ * append one payload; different machines use different filenames.
+ */
+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';
+const CHECKPOINT_MARKER = '_usageJournalThroughBytes';
+/** 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;
+        let baseOffset = 0;
+        let headerBytes = 0;
+        try {
+            const fd = (0, fs_1.openSync)(path, 'r');
+            try {
+                size = (0, fs_1.fstatSync)(fd).size;
+                const prefix = Buffer.alloc(Math.min(size, 128));
+                (0, fs_1.readSync)(fd, prefix, 0, prefix.length, 0);
+                const newline = prefix.indexOf(0x0a);
+                if (newline >= 0) {
+                    try {
+                        const header = JSON.parse(prefix.subarray(0, newline).toString('utf8'));
+                        if (Object.keys(header).length === 1 && Number.isSafeInteger(header[CHECKPOINT_MARKER]) && header[CHECKPOINT_MARKER] >= 0) {
+                            baseOffset = header[CHECKPOINT_MARKER];
+                            headerBytes = newline + 1;
+                        }
+                    }
+                    catch { /* An ordinary first event, not a checkpoint marker. */ }
+                }
+            }
+            finally {
+                (0, fs_1.closeSync)(fd);
+            }
+        }
+        catch {
+            continue;
+        }
+        logs.push({ machineId: name.slice(0, -LOG_SUFFIX.length), path, size, baseOffset, headerBytes });
+    }
+    return logs.sort((a, b) => a.machineId.localeCompare(b.machineId));
+}
+function readTail(log, from) {
+    const end = log.baseOffset + log.size - log.headerBytes;
+    if (from < log.baseOffset)
+        throw new Error('Usage checkpoint is missing or older than the consolidated journal. Restore learning-usage.json or its .checkpoint backup; raw retrospectives cannot restore runtime offers.');
+    const restarted = from > end;
+    if (restarted && log.baseOffset > 0)
+        throw new Error('Usage journal is behind its checkpoint; restore matching files before continuing.');
+    const start = restarted ? 0 : Math.max(0, from);
+    const physicalStart = start - log.baseOffset + log.headerBytes;
+    const length = log.size - physicalStart;
+    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, physicalStart);
+            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: end - 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),
+    };
+}
+/**
+ * Clear fully checkpointed logs whose records are all understood by this reader.
+ * Preserve unknown, malformed, partial or newly appended logs byte-for-byte.
+ * Flush then atomically replace each log with its logical-position header; the
+ * checkpoint saved before this call remains correct on either side of a crash.
+ */
+function compactEventLogs(eventDir, keep, checkpoints) {
+    const result = { scanned: 0, kept: 0, dropped: 0, skippedLines: 0, logs: [], checkpoints: { ...checkpoints } };
+    for (const log of listEventLogs(eventDir)) {
+        const read = readTail(log, log.baseOffset);
+        result.scanned += read.records.length;
+        result.skippedLines += read.skippedLines;
+        result.kept += read.records.length;
+        // The snapshot knows nothing about a later append or torn
+        // tail. Leave that log and its old checkpoint alone for the next fold.
+        if (read.through !== log.baseOffset + log.size - log.headerBytes
+            || read.through !== (checkpoints[log.machineId] ?? 0) || read.skippedLines > 0)
+            continue;
+        const retained = read.records.filter(keep);
+        // Unknown records may belong to a newer reader. Leave their whole log
+        // intact so their original positions remain meaningful.
+        if (retained.length > 0 || read.records.length === 0)
+            continue;
+        const temp = `${log.path}.compacting`;
+        try {
+            const payload = `${JSON.stringify({ [CHECKPOINT_MARKER]: read.through })}\n`;
+            (0, fs_1.writeFileSync)(temp, payload, { encoding: 'utf8', flush: true });
+            if ((0, fs_1.statSync)(log.path).size !== log.size) {
+                (0, fs_1.rmSync)(temp, { force: true });
+                continue;
+            }
+            (0, fs_1.renameSync)(temp, log.path);
+            const dropped = read.records.length - retained.length;
+            result.kept -= dropped;
+            result.dropped += dropped;
+            // The logical checkpoint remains unchanged across the atomic replacement.
+            result.checkpoints[log.machineId] = read.through;
+        }
+        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);
 }