fraim-hub 2.0.339 → 2.0.340

package/dist/src/local-mcp-server/artifact-retention-cleanup.js

@@ -28,9 +28,14 @@ exports.ARTIFACT_RETENTION_CATEGORIES = [
     'learning_usage',
     'hub_event_logs',
 ];
+function contentRoot(workspaceRoot) {
+    const packContent = node_path_1.default.join(workspaceRoot, 'personalized-employee');
+    return node_fs_1.default.existsSync(packContent) ? packContent : node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee');
+}
 function readWorkspaceConfig(workspaceRoot) {
     try {
-        const configPath = (0, project_fraim_paths_1.getWorkspaceConfigPath)(workspaceRoot);
+        const configPath = contentRoot(workspaceRoot) === node_path_1.default.join(workspaceRoot, 'personalized-employee')
+            ? node_path_1.default.join(workspaceRoot, 'config.json') : (0, project_fraim_paths_1.getWorkspaceConfigPath)(workspaceRoot);
         if (!node_fs_1.default.existsSync(configPath))
             return {};
         return JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf8'));
@@ -143,7 +148,7 @@ function loadGitLastChangeDates(workspaceRoot, relativeDir) {
     return dates;
 }
 function readFrontmatter(content) {
-    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const match = content.match(/^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/);
     if (!match)
         return {};
     const values = {};
@@ -167,8 +172,20 @@ function synthesizedDate(absolutePath) {
         return undefined;
     }
 }
-function userScoped(fileName, activeUserEmail) {
-    return fileName.startsWith(`${activeUserEmail}-`);
+function userScoped(filePath, activeUserEmail) {
+    try {
+        const body = node_fs_1.default.readFileSync(filePath, 'utf8');
+        const author = readFrontmatter(body).author;
+        if (author !== undefined) {
+            const value = author.replace(/^(?:"([^"]*)"|'([^']*)')$/, (_match, double, single) => double ?? single);
+            return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) && value === activeUserEmail;
+        }
+        // Older artifacts used the author in their filename.
+        return node_path_1.default.basename(filePath).startsWith(`${activeUserEmail}-`);
+    }
+    catch {
+        return false;
+    }
 }
 function evidenceEligibilityDate(workspaceRoot, absolutePath, gitDates) {
     const relativePath = normalizeRelative(workspaceRoot, absolutePath);
@@ -187,17 +204,22 @@ function collectCandidates(workspaceRoot, options) {
             eligibilityDate,
         });
     };
-    const archiveDir = node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings', 'archive');
+    const content = contentRoot(workspaceRoot);
+    const archiveDir = node_path_1.default.join(content, 'learnings', 'archive');
     for (const filePath of listFiles(archiveDir)) {
         const fileName = node_path_1.default.basename(filePath);
-        if (!fileName.endsWith('.md') || !userScoped(fileName, activeUserEmail))
+        if (!fileName.endsWith('.md') || !userScoped(filePath, activeUserEmail))
             continue;
         add('learning_archive', filePath, true, 'Archived learning source for active user.', fileMtime(filePath));
     }
-    const retrospectivesDir = node_path_1.default.join(workspaceRoot, 'docs', 'retrospectives');
-    for (const filePath of listFiles(retrospectivesDir)) {
+    const retrospectives = new Set([
+        node_path_1.default.join(workspaceRoot, 'docs', 'retrospectives'),
+        node_path_1.default.join(workspaceRoot, 'retrospectives'),
+        node_path_1.default.join(content, 'retrospectives'),
+    ].flatMap(listFiles));
+    for (const filePath of retrospectives) {
         const fileName = node_path_1.default.basename(filePath);
-        if (!fileName.endsWith('.md') || !userScoped(fileName, activeUserEmail))
+        if (!fileName.endsWith('.md') || !userScoped(filePath, activeUserEmail))
             continue;
         const date = synthesizedDate(filePath);
         if (date)
@@ -209,6 +231,11 @@ function collectCandidates(workspaceRoot, options) {
     const evidenceGitDates = loadGitLastChangeDates(workspaceRoot, 'docs/evidence');
     for (const filePath of listFiles(evidenceDir)) {
         const fileName = node_path_1.default.basename(filePath);
+        // A surviving run journal is unfinished recovery; completion removes it.
+        if (fileName.endsWith('.queue.jsonl')) {
+            add('evidence', filePath, false, 'Unfinished Sleep run journal; removed by run completion.');
+            continue;
+        }
         const isMarkdown = fileName.endsWith('.md');
         const isJson = fileName.endsWith('.json');
         const eligibilityDate = evidenceEligibilityDate(workspaceRoot, filePath, evidenceGitDates);

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -25,6 +25,7 @@ exports.resolveOrgBrandWriteDir = resolveOrgBrandWriteDir;
 exports.countPreservedLearnings = countPreservedLearnings;
 exports.collectBrainLearningDots = collectBrainLearningDots;
 exports.readPreservedLearnings = readPreservedLearnings;
+exports.normalizeLearningDomain = normalizeLearningDomain;
 exports.applyLearningEntryChange = applyLearningEntryChange;
 exports.isTruthyFlag = isTruthyFlag;
 const fs_1 = require("fs");
@@ -496,6 +497,15 @@ function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-pattern
  * behaviour instead of merely equivalent.
  */
 function resolveUsageClock(workspaceRoot) {
+    return resolveUsageViews(workspaceRoot).clock;
+}
+/**
+ * Issue #1755: one store read, two views of it: the clock the scorer needs and
+ * the counters a surface renders. They are resolved together because reading the
+ * store twice for the same pass would let the two disagree, and because the
+ * identity resolution that finds a record is the projection's, not each caller's.
+ */
+function resolveUsageViews(workspaceRoot) {
     try {
         // Required lazily: the store imports the retention config, which imports the
         // workspace path helpers, and a cycle through this module would be fragile.
@@ -503,14 +513,31 @@ function resolveUsageClock(workspaceRoot) {
         const projection = require('./learning-usage-projection');
         const loaded = store.readUsageStore();
         if (Object.keys(loaded.entries).length === 0)
-            return undefined;
+            return {};
         const lookup = projection.buildUsageLookup(loaded);
-        return (id, fileType, title) => projection.lookupUsage(lookup, id, fileType, title)?.lastFired ?? null;
+        return {
+            clock: (id, fileType, title) => projection.lookupUsage(lookup, id, fileType, title)?.lastFired ?? null,
+            stats: (id, fileType, title) => {
+                const found = projection.lookupUsage(lookup, id, fileType, title);
+                if (!found)
+                    return null;
+                return {
+                    offered: found.offered,
+                    offeredAboveThreshold: found.offeredAboveThreshold,
+                    applied: found.byOutcome.applied || 0,
+                    prevented: found.byOutcome.prevented || 0,
+                    ignored: found.byOutcome.ignored || 0,
+                    notApplicable: found.byOutcome['not-applicable'] || 0,
+                    lastOfferedAt: found.lastOffered,
+                    lastFiredAt: found.lastFired,
+                };
+            },
+        };
     }
     catch {
         // Usage data is derived and optional. A failure here must never change what
         // the agent is given.
-        return undefined;
+        return {};
     }
 }
 function readFrontmatter(content) {
@@ -1216,7 +1243,7 @@ function isTeamContextKey(value) {
  *   user-level `~/.fraim/…` path (where org onboarding writes).
  * - Project scope (projectContext/projectBrief/projectRules/projectQa): repo-local only.
  */
-function resolveTeamContextFile(workspaceRoot, key) {
+function resolveTeamContextFile(workspaceRoot, key, options = {}) {
     const { relativePath, scope } = TEAM_CONTEXT_FILE_MAP[key];
     const repoPath = (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(workspaceRoot), 'personalized-employee', relativePath);
     const repoDisplay = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`personalized-employee/${relativePath}`);
@@ -1245,7 +1272,7 @@ function resolveTeamContextFile(workspaceRoot, key) {
     // destination (R5.1), so writePath stays empty and the caller must route
     // edits through the org backend's propose-and-approve flow.
     if (key === 'org' || key === 'orgRules') {
-        const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, relativePath);
+        const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', options).contentRoot, relativePath);
         if ((0, fs_1.existsSync)(cachePath)) {
             const fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)();
             const orgDisplayPath = cachePath.startsWith(fraimDir)
@@ -1262,7 +1289,7 @@ function resolveTeamContextFile(workspaceRoot, key) {
         }
     }
     if (key === 'manager' || key === 'managerRules') {
-        const managerHome = (0, pack_home_1.resolvePackHome)('manager');
+        const managerHome = (0, pack_home_1.resolvePackHome)('manager', options);
         const managerCachePath = (0, path_1.join)(managerHome.contentRoot, relativePath);
         if ((0, fs_1.existsSync)(managerCachePath)) {
             const fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)();
@@ -1697,7 +1724,7 @@ function listDomainLearningFiles(dir, prefix, fileType) {
 // threshold: entries with score >= threshold (or in a non-gated category) are
 //   marked injected:true. Callers that don't need scoring pass Infinity so
 //   all entries are injected.
-function parseLearningEntries(filePath, displayPath, category, level, domain = 'global', tier, threshold = exports.DEFAULT_THRESHOLD, usageClock) {
+function parseLearningEntries(filePath, displayPath, category, level, domain = 'global', tier, threshold = exports.DEFAULT_THRESHOLD, usageClock, usageStats) {
     if (!(0, fs_1.existsSync)(filePath))
         return [];
     let content;
@@ -1719,6 +1746,10 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
     const flush = () => {
         if (current) {
             current.body = bodyLines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+            // Issue #1755: resolve usage once per entry, before scoring, so the
+            // counters a surface renders and the clock the score uses come from
+            // the same record rather than two independent lookups.
+            current.usage = usageStats ? usageStats(current.id, fileType, current.title) : null;
             if (isScoreGated) {
                 if (curLastSeen !== null) {
                     const lastFired = usageClock ? usageClock(current.id, fileType, current.title) : null;
@@ -1753,7 +1784,7 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
                 title: header[2].trim(),
                 id: null,
                 body: '', source: displayPath, category, level, domain,
-                score: null, injected: true,
+                score: null, injected: true, usage: null,
             };
             if (tier !== undefined)
                 entry.tier = tier;
@@ -1799,13 +1830,14 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
     const threshold = getScoreThreshold(workspaceRoot);
     // Issue #1103 R8: the Hub's injected flag must agree with the loader's, so both
     // read the same clock. One store read serves the whole call.
-    const usageClock = resolveUsageClock(workspaceRoot);
+    // Issue #1755: the same read also yields the counters the Hub renders.
+    const { clock: usageClock, stats: usageStats } = resolveUsageViews(workspaceRoot);
     const out = [];
     // Helper: parse + merge a list of tier paths for one file family.
     // ResolvedLearningTier uses 'manager' to mean machine-level personal; map it to 'machine'.
     const tierLevel = (t) => t.level === 'manager' ? 'machine' : t.level;
     const parseTiers = (tiers, cat, tierVal, domainVal) => mergeLearningEntriesAcrossTiers(tiers.map((t) => ({
-        entries: parseLearningEntries(t.path, t.displayPath, cat, tierLevel(t), domainVal ?? 'global', tierVal, threshold, usageClock),
+        entries: parseLearningEntries(t.path, t.displayPath, cat, tierLevel(t), domainVal ?? 'global', tierVal, threshold, usageClock, usageStats),
     })));
     if (scope === 'org') {
         for (const cat of ['avoid', 'preference', 'repeat', 'coaching']) {
@@ -1826,7 +1858,7 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
                 seenDomainFile.add(fileName);
                 const domainTiers = resolveOrgLearningFileTiers(roots.repoLearningsBase, fileName);
                 if (domainTiers.length === 0) {
-                    out.push(...parseLearningEntries((0, path_1.join)(base, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'org', domain, undefined, threshold));
+                    out.push(...parseLearningEntries((0, path_1.join)(base, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'org', domain, undefined, threshold, usageClock, usageStats));
                 }
                 else {
                     out.push(...parseTiers(domainTiers, cat, undefined, domain));
@@ -1843,13 +1875,13 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
         for (const cat of cats) {
             const fileType = exports.CATEGORY_TO_FILETYPE[cat];
             const f = `${resolvedUserId}-${fileType}.md`;
-            out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, f), `${REPO_LEARNINGS_REL}/${f}`, cat, 'project', 'global', 'hot', threshold));
+            out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, f), `${REPO_LEARNINGS_REL}/${f}`, cat, 'project', 'global', 'hot', threshold, usageClock, usageStats));
             const coldF = `${resolvedUserId}-${fileType}${COLD_FILE_SUFFIX}.md`;
             if ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, coldF))) {
-                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, coldF), `${REPO_LEARNINGS_REL}/${coldF}`, cat, 'project', 'global', 'cold', threshold));
+                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, coldF), `${REPO_LEARNINGS_REL}/${coldF}`, cat, 'project', 'global', 'cold', threshold, usageClock, usageStats));
             }
             for (const { fileName, domain } of listDomainLearningFiles(roots.repoLearningsBase, resolvedUserId, fileType)) {
-                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'project', domain, 'hot', threshold));
+                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'project', domain, 'hot', threshold, usageClock, usageStats));
             }
         }
         return out;
@@ -1880,6 +1912,25 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
     }
     return out;
 }
+/** True for a domain value that means "the undecorated global file". */
+function isGlobalDomain(domain) {
+    return !domain || domain === 'global';
+}
+/** Normalize a caller-supplied domain to one of the known domains, or 'global'. */
+function normalizeLearningDomain(domain) {
+    if (isGlobalDomain(domain))
+        return 'global';
+    const found = learning_domains_1.LEARNING_DOMAINS.find((d) => d === domain);
+    return found ?? 'global';
+}
+function learningFileName(userId, fileType, domain) {
+    // Issue #1755 / #754: normalize here rather than trusting the caller. The HTTP
+    // layer already allowlists the domain, but this function builds a path and a
+    // direct caller passing `../../escape` would otherwise write outside the
+    // learnings root. Anything not in the known set resolves to the global file.
+    const safe = normalizeLearningDomain(domain);
+    return safe === 'global' ? `${userId}-${fileType}.md` : `${userId}-${safe}-${fileType}.md`;
+}
 function resolveLearningFilePath(workspaceRoot, userId, ref) {
     const roots = getLearningRoots(workspaceRoot);
     const fileType = exports.CATEGORY_TO_FILETYPE[ref.category];
@@ -1887,12 +1938,12 @@ function resolveLearningFilePath(workspaceRoot, userId, ref) {
         // Write org entries to the org pack home — same location share-with-others uses.
         // The Hub read path already merges pack home + repo-local, so edits land where
         // the agent reads them without needing a repo commit.
-        return (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings', `org-${fileType}.md`);
+        return (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings', learningFileName('org', fileType, ref.domain));
     }
     const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
     // Issue #1070: for the 'machine' level use the configured manager home.
     const base = ref.level === 'project' ? roots.repoLearningsBase : roots.managerHomeBase;
-    return (0, path_1.join)(base, `${resolvedUserId}-${fileType}.md`);
+    return (0, path_1.join)(base, learningFileName(resolvedUserId, fileType, ref.domain));
 }
 function titleCaseFromFileType(fileType) {
     return fileType.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
@@ -1916,9 +1967,10 @@ function applyLearningEntryChange(workspaceRoot, userId, ref, action, payload) {
         const body = String(payload.body || '').trim();
         const block = [`#### [${sev}] ${title}`, '', body, '', '---'].join(nl);
         const fileType = exports.CATEGORY_TO_FILETYPE[ref.category];
+        const addDomain = normalizeLearningDomain(ref.domain);
         const preamble = existing.trim()
             ? existing.replace(/\s*$/, '')
-            : `# ${ref.scope === 'org' ? 'Org ' : ''}${titleCaseFromFileType(fileType)}`;
+            : `# ${ref.scope === 'org' ? 'Org ' : ''}${titleCaseFromFileType(fileType)}${addDomain === 'global' ? '' : ` (${addDomain})`}`;
         write(preamble + nl + nl + block);
         return { ok: true, path: filePath };
     }
@@ -1935,8 +1987,12 @@ function applyLearningEntryChange(workspaceRoot, userId, ref, action, payload) {
         write(next.join(nl).replace(/\n{3,}/g, '\n\n'));
         return { ok: true, path: filePath };
     }
-    // edit: keep the entry's metadata lines (Score/Last seen/Recurrences/...) intact,
+    // edit: keep the entry's metadata lines (Id/Score/Last seen/Recurrences/...) intact,
     // replace only the heading (priority + title) and the prose body.
+    //
+    // Issue #1755: `Id` is in this list. It used not to be, so every Hub edit dropped
+    // the entry's stable identifier and the usage record keyed to it (#1752) was
+    // orphaned: silently, and permanently once the title also changed.
     const headerMatch = lines[start].match(headingRe);
     const sev = (payload.severity || headerMatch[1]);
     const title = (payload.title !== undefined ? payload.title : headerMatch[2]).trim();
@@ -1945,11 +2001,32 @@ function applyLearningEntryChange(workspaceRoot, userId, ref, action, payload) {
         const t = l.trim();
         if (t === '---')
             continue;
-        if (/^\*\*(Score|Last seen|Recurrences|Technical trace|Users|First synthesized)\*\*:/i.test(t) || /^(First|Last) synthesized:/i.test(t))
+        if (/^\*\*(Id|Score|Last seen|Recurrences|Technical trace|Users|First synthesized)\*\*:/i.test(t) || /^(First|Last) synthesized:/i.test(t))
             meta.push(l);
     }
     const body = String(payload.body !== undefined ? payload.body : '').trim();
     const rebuilt = [`#### [${sev}] ${title}`, '', ...meta, ...(meta.length ? [''] : []), body, '', '---'];
+    // Issue #1755 R2/R4: a domain change is a move between files, because the domain
+    // IS the filename. Cut the rebuilt block from the source file and append it to the
+    // destination, so the entry keeps its id, score and history rather than being
+    // re-created as a new entry with no past.
+    const targetDomain = payload.targetDomain === undefined ? undefined : normalizeLearningDomain(payload.targetDomain);
+    if (targetDomain !== undefined && targetDomain !== normalizeLearningDomain(ref.domain)) {
+        const destPath = resolveLearningFilePath(workspaceRoot, userId, { ...ref, domain: targetDomain });
+        const destExisting = (0, fs_1.existsSync)(destPath) ? (0, fs_1.readFileSync)(destPath, 'utf8') : '';
+        const destNl = destExisting.includes('\r\n') ? '\r\n' : nl;
+        const fileTypeForHeader = exports.CATEGORY_TO_FILETYPE[ref.category];
+        const destPreamble = destExisting.trim()
+            ? destExisting.replace(/\s*$/, '')
+            : `# ${ref.scope === 'org' ? 'Org ' : ''}${titleCaseFromFileType(fileTypeForHeader)}${targetDomain === 'global' ? '' : ` (${targetDomain})`}`;
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(destPath), { recursive: true });
+        (0, fs_1.writeFileSync)(destPath, (destPreamble + destNl + destNl + rebuilt.join(destNl)).replace(/\s*$/, '') + destNl, 'utf8');
+        // Remove from the source only after the destination write succeeded, so a
+        // failure mid-move duplicates rather than loses the entry.
+        const without = [...lines.slice(0, start), ...lines.slice(end)];
+        write(without.join(nl).replace(/\n{3,}/g, '\n\n'));
+        return { ok: true, path: destPath };
+    }
     const next = [...lines.slice(0, start), ...rebuilt, ...lines.slice(end)];
     write(next.join(nl).replace(/\n{3,}/g, '\n\n'));
     return { ok: true, path: filePath };

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

@@ -7,43 +7,17 @@ exports.listEventLogs = listEventLogs;
 exports.readEventsSince = readEventsSince;
 exports.compactEventLogs = compactEventLogs;
 /**
- * Issue #1752 — the durable half of the usage record.
+ * Per-machine usage journals: job runs append complete JSON lines; sleep folds
+ * them into a recoverable snapshot and removes processed records.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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");
@@ -51,6 +25,7 @@ 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);
@@ -136,10 +111,25 @@ function listEventLogs(eventDir) {
             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);
@@ -148,14 +138,20 @@ function listEventLogs(eventDir) {
         catch {
             continue;
         }
-        logs.push({ machineId: name.slice(0, -LOG_SUFFIX.length), path, size });
+        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 restarted = from > log.size;
+    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 length = log.size - start;
+    const physicalStart = start - log.baseOffset + log.headerBytes;
+    const length = log.size - physicalStart;
     if (length <= 0) {
         return { ...log, records: [], skippedLines: 0, through: start, restarted };
     }
@@ -164,7 +160,7 @@ function readTail(log, from) {
         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);
+            const read = (0, fs_1.readSync)(fd, buffer, 0, length, physicalStart);
             text = buffer.subarray(0, read).toString('utf8');
         }
         finally {
@@ -202,7 +198,7 @@ function readTail(log, from) {
             skippedLines += 1;
         }
     }
-    return { ...log, records, skippedLines, through: log.size - partialBytes, restarted };
+    return { ...log, records, skippedLines, through: end - partialBytes, restarted };
 }
 /**
  * Read every log's tail past its checkpoint.
@@ -220,32 +216,42 @@ function readEventsSince(eventDir, checkpoints) {
     };
 }
 /**
- * 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.
+ * 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) {
-    const result = { scanned: 0, kept: 0, dropped: 0, skippedLines: 0, logs: [] };
+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, 0);
+        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);
-        result.kept += retained.length;
-        result.dropped += read.records.length - retained.length;
-        if (retained.length === read.records.length && read.skippedLines === 0)
+        // 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 {
-            (0, fs_1.writeFileSync)(temp, retained.length ? `${retained.map((r) => JSON.stringify(r)).join('\n')}\n` : '', 'utf8');
+            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