fraim 2.0.339 → 2.0.340

package/dist/registry/scripts/learning/completion-state.js

@@ -0,0 +1,153 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPLETION_END = exports.COMPLETION_START = void 0;
+exports.validateProcessedSources = validateProcessedSources;
+exports.decodeCompletion = decodeCompletion;
+const node_path_1 = __importDefault(require("node:path"));
+function validateProcessedSources(sources) {
+    if (!Array.isArray(sources) || new Set(sources.map(item => item.path)).size !== sources.length || sources.some(item => !item || !node_path_1.default.isAbsolute(item.path) || !node_path_1.default.isAbsolute(item.destination) || !['raw', 'retrospective'].includes(item.kind)
+        || !/^[a-f0-9]{64}$/.test(item.sha256) || !/^[a-f0-9]{64}$/.test(item.resultHash) || !/^\d{4}-\d{2}-\d{2}$/.test(item.synthesizedAt)))
+        throw new Error('invalid-processed-sources');
+}
+exports.COMPLETION_START = '<!-- fraim-sleep-decisions:v1 -->';
+exports.COMPLETION_END = '<!-- /fraim-sleep-decisions -->';
+const text = (value) => typeof value === 'string' && !!value.trim();
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const keys = (value, allowed) => object(value) && Object.keys(value).every(key => allowed.includes(key));
+const ownerValid = (value) => object(value) && ['Project', 'Manager', 'Org'].includes(value.level)
+    && keys(value, ['level', 'path']) && text(value.path) && node_path_1.default.isAbsolute(value.path)
+    && !/[\x00-\x1f]/.test(value.path) && value.path === (process.platform === 'win32' ? node_path_1.default.resolve(value.path).replace(/\\/g, '/').toLowerCase() : node_path_1.default.resolve(value.path));
+const sameOwner = (a, b) => a.level === b.level && a.path === b.path;
+function decodeCompletion(markdown, expected = {}) {
+    const fail = () => { throw new Error('invalid-completion-decisions'); };
+    if ((markdown.match(/<!--\s*fraim-sleep-decisions:/g) || []).length !== 1 || markdown.split(exports.COMPLETION_START).length !== 2 || markdown.split(exports.COMPLETION_END).length !== 2)
+        fail();
+    const start = markdown.indexOf(exports.COMPLETION_START) + exports.COMPLETION_START.length;
+    const end = markdown.indexOf(exports.COMPLETION_END);
+    if (end < start)
+        fail();
+    const block = markdown.slice(start, end).match(/^\s*```json\r?\n([\s\S]*?)\r?\n```\s*$/);
+    if (!block)
+        fail();
+    let state;
+    try {
+        state = JSON.parse(block[1]);
+    }
+    catch {
+        fail();
+    }
+    if (!keys(state, ['schemaVersion', 'runId', 'owner', 'finalizationState', 'decisions', 'sourceDispositions', 'cleanup', 'reconciliations', 'retrospective', 'processedSources']) || state.schemaVersion !== 1 || !text(state.runId) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(state.runId) || !ownerValid(state.owner)
+        || !['pending', 'complete'].includes(state.finalizationState) || !Array.isArray(state.decisions) || !Array.isArray(state.sourceDispositions) || !Array.isArray(state.cleanup))
+        fail();
+    if ((expected.runId && expected.runId !== state.runId) || (expected.owner && !sameOwner(expected.owner, state.owner)))
+        fail();
+    if (state.retrospective !== undefined && (!keys(state.retrospective, ['relativePath', 'sha256'])
+        || state.retrospective.relativePath !== `retrospectives/${state.runId}-sleep-postmortem.md` || !hash(state.retrospective.sha256)))
+        fail();
+    if (state.processedSources !== undefined)
+        validateProcessedSources(state.processedSources);
+    const ids = new Set();
+    for (const item of state.decisions) {
+        if (!keys(item, ['actionId', 'revision', 'digest', 'owner', 'claimKey', 'evidenceFingerprint', 'sourceRefs', 'decision', 'publicationRef', 'target', 'dependencies']) || !text(item.actionId) || ids.has(item.actionId) || !Number.isInteger(item.revision) || item.revision < 1 || !hash(item.digest) || !ownerValid(item.owner)
+            || !text(item.claimKey) || !text(item.evidenceFingerprint) || !Array.isArray(item.sourceRefs) || !item.sourceRefs.every(text) || (item.publicationRef !== undefined && !text(item.publicationRef)))
+            fail();
+        ids.add(item.actionId);
+        const decision = item.decision;
+        if (!keys(decision, ['action', 'revision', 'digest', 'reviewer', 'reason', 'revisitCondition', 'at']) || !['approve', 'reject'].includes(decision.action) || decision.revision !== item.revision || decision.digest !== item.digest
+            || !text(decision.reviewer) || !text(decision.reason) || !text(decision.at) || !Number.isFinite(Date.parse(decision.at))
+            || (decision.revisitCondition !== undefined && (decision.action !== 'reject' || !text(decision.revisitCondition))))
+            fail();
+        if ('content' in item || 'specification' in item || 'application' in item || 'preimage' in item)
+            fail();
+        if (item.target && (!keys(item.target, ['owner', 'relativePath', 'entryId', 'learningSubject']) || !ownerValid(item.target.owner) || !text(item.target.relativePath) || /^[\\/]|^[a-zA-Z]:/.test(item.target.relativePath) || item.target.relativePath.split('/').includes('..')))
+            fail();
+        if (item.dependencies && (!Array.isArray(item.dependencies) || item.dependencies.some((dependency) => !keys(dependency, ['actionId', 'outcome']) || !text(dependency.actionId) || !['applied', 'rejected'].includes(dependency.outcome))))
+            fail();
+    }
+    for (const source of state.sourceDispositions) {
+        if (!keys(source, ['sourceRef', 'sourceHash', 'outcome', 'actionId']) || !text(source.sourceRef) || !hash(source.sourceHash) || !['applied', 'rejected'].includes(source.outcome) || !ids.has(source.actionId))
+            fail();
+    }
+    const decisions = new Map(state.decisions.map((item) => [item.actionId, item]));
+    const outcome = (item) => item.decision.action === 'approve' ? 'applied' : 'rejected';
+    const dispositions = new Set();
+    for (const source of state.sourceDispositions) {
+        const action = decisions.get(source.actionId);
+        const key = JSON.stringify([source.actionId, source.sourceRef]);
+        if (dispositions.has(key) || !action.sourceRefs.includes(source.sourceRef) || source.outcome !== outcome(action))
+            fail();
+        dispositions.add(key);
+    }
+    for (const action of decisions.values()) {
+        if (action.target && !sameOwner(action.owner, action.target.owner))
+            fail();
+        if (new Set(action.sourceRefs).size !== action.sourceRefs.length || action.sourceRefs.some(ref => !dispositions.has(JSON.stringify([action.actionId, ref]))))
+            fail();
+        const dependencies = action.dependencies || [];
+        if (new Set(dependencies.map(dependency => dependency.actionId)).size !== dependencies.length)
+            fail();
+        for (const dependency of dependencies) {
+            const target = decisions.get(dependency.actionId);
+            if (!target || target.actionId === action.actionId || dependency.outcome !== outcome(target)
+                || (action.decision.action === 'approve' && dependency.outcome !== 'applied'))
+                fail();
+        }
+    }
+    const checked = new Set();
+    const visiting = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            fail();
+        if (checked.has(id))
+            return;
+        visiting.add(id);
+        for (const dependency of decisions.get(id).dependencies || [])
+            visit(dependency.actionId);
+        visiting.delete(id);
+        checked.add(id);
+    };
+    for (const id of decisions.keys())
+        visit(id);
+    for (const item of state.cleanup) {
+        if (!keys(item, ['path', 'outcome', 'reason', 'sha256', 'location']) || !text(item.path) || !['pending', 'deleted', 'absent', 'retained'].includes(item.outcome) || (item.reason !== undefined && typeof item.reason !== 'string') || (item.sha256 !== undefined && !hash(item.sha256)))
+            fail();
+        if (item.location !== undefined) {
+            const location = item.location;
+            if (!keys(location, ['owner', 'relativePath']) || !ownerValid(location.owner)
+                || !text(location.relativePath) || !/^learnings\/(?:review-queue|review-archive|review-evidence|archive)\//.test(location.relativePath)
+                || /[\\:]/.test(location.relativePath) || location.relativePath.split('/').some((part) => !part || part === '.' || part === '..'))
+                fail();
+        }
+        if (state.finalizationState === 'complete' && item.outcome === 'pending')
+            fail();
+    }
+    if (state.reconciliations !== undefined) {
+        if (!Array.isArray(state.reconciliations))
+            fail();
+        const sources = new Set();
+        for (const item of state.reconciliations) {
+            if (!keys(item, ['sourceRef', 'sourceHash', 'owner', 'relativePath', 'actionIds', 'actionBindings', 'disposition', 'rationale', 'preservedDecisions', 'reviewer'])
+                || !text(item.sourceRef) || sources.has(item.sourceRef) || !hash(item.sourceHash) || !ownerValid(item.owner)
+                || !text(item.relativePath) || !/^learnings\/(?:review-queue|review-archive|review-evidence|archive)\//.test(item.relativePath)
+                || /[\\:]/.test(item.relativePath) || item.relativePath.split('/').some((part) => !part || part === '.' || part === '..')
+                || !['accounted', 'unrelated', 'raw-source'].includes(item.disposition) || !text(item.rationale) || !text(item.reviewer)
+                || !Array.isArray(item.preservedDecisions) || !item.preservedDecisions.every(text)
+                || !Array.isArray(item.actionIds) || new Set(item.actionIds).size !== item.actionIds.length
+                || !Array.isArray(item.actionBindings) || item.actionBindings.length !== item.actionIds.length)
+                fail();
+            sources.add(item.sourceRef);
+            for (const [index, id] of item.actionIds.entries()) {
+                const decision = decisions.get(id);
+                const binding = item.actionBindings[index];
+                if (!decision || !keys(binding, ['actionId', 'revision', 'digest']) || binding.actionId !== id || binding.revision !== decision.revision || binding.digest !== decision.digest
+                    || !state.sourceDispositions.some((source) => source.actionId === id && source.sourceRef.replace(/\\/g, '/') === item.sourceRef.replace(/\\/g, '/') && source.sourceHash === item.sourceHash))
+                    fail();
+            }
+        }
+    }
+    return state;
+}

package/dist/src/cli/commands/cleanup-artifacts.js

@@ -22,10 +22,10 @@ function runCleanupArtifactsCommand(options) {
 }
 exports.cleanupArtifactsCommand = new commander_1.Command('cleanup-artifacts')
     .alias('cleanup-artifact')
-    .description('Evaluate and optionally apply artifact retention cleanup for the current FRAIM workspace')
+    .description('Evaluate and optionally apply artifact retention cleanup for a FRAIM workspace or pack root')
     .option('--user <email>', 'Active user email used only for user-scoped cleanup categories')
     .option('--workspace-root <path>', 'Workspace root containing fraim/config.json')
-    .option('--root <path>', 'Alias for --workspace-root')
+    .option('--root <path>', 'Workspace root or explicit Manager/Org pack root; uses that root\'s retention policy')
     .option('--apply', 'Delete eligible files. Without this flag the command performs a dry run.')
     .action((options) => {
     try {

package/dist/src/core/ai-mentor.js

@@ -348,4 +348,4 @@ class AIMentor {
     }
 }
 exports.AIMentor = AIMentor;
-AIMentor.COMPACT_PHASE_AUTHORITY = '**Use only the phases defined in this workflow.**';
+AIMentor.COMPACT_PHASE_AUTHORITY = '**Use only the phases defined in this workflow.** Before phase work, read `get_fraim_file({ path: "orchestration/phase-authority.md" })` for phase closure, approval gates, and resumption.';

package/dist/src/core/handoff-contracts.js

@@ -27,6 +27,7 @@ exports.validateReviewActionCompleteness = validateReviewActionCompleteness;
 exports.hasPhaseStarted = hasPhaseStarted;
 exports.upsertPhaseStarted = upsertPhaseStarted;
 exports.buildPhaseStartWarning = buildPhaseStartWarning;
+exports.reviewHandoffNormalizationError = reviewHandoffNormalizationError;
 exports.validateReviewHandoff = validateReviewHandoff;
 exports.validateNextJobRecommendations = validateNextJobRecommendations;
 exports.validateDelegationLedger = validateDelegationLedger;
@@ -255,23 +256,49 @@ function validateReviewArtifactEntry(artifact, index) {
     return errors;
 }
 /**
- * Validates evidence.reviewHandoff. Returns null if valid, or an array of
- * human-readable error strings describing what is wrong.
- *
- * Required minimum shape:
- * {
- *   reviewRequired: boolean,
- *   artifacts: array,
- *   // when reviewRequired is true:
- *   reviewTarget: { type: "pull_request", label: string, url: string } | { type: "artifact_set", label: string },
- *   reviewActions: [{ kind: "approve", ... }, { kind: "request_changes", ... }],
- * }
- *
- * Hub normalizers (server.ts + script.js) both read reviewTarget.type, not .kind.
- * Using reviewTarget.kind produces a payload that passes validation but is silently
- * un-renderable. This validator enforces the renderable contract so malformed payloads
- * are rejected before phase advancement.
+ * Reports payloads the Hub cannot normalize, including artifact_set entries it
+ * would silently drop. This deliberately preserves the Hub's legacy defaults;
+ * it does not impose the stronger, phase-dependent submission contract.
  */
+function reviewHandoffNormalizationError(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return 'reviewHandoff must be an object';
+    }
+    const handoff = value;
+    if (typeof handoff.reviewRequired !== 'boolean') {
+        return 'reviewHandoff.reviewRequired must be a boolean';
+    }
+    // This is renderability, not the stronger submission-phase contract below.
+    // In particular legacy handoffs need not supply actions or an artifacts array.
+    if (!handoff.reviewRequired)
+        return null;
+    const target = handoff.reviewTarget;
+    const targetType = typeof target?.type === 'string' ? target.type.trim() : '';
+    if (targetType !== 'pull_request' && targetType !== 'artifact_set') {
+        return 'reviewHandoff.reviewTarget.type must be pull_request or artifact_set';
+    }
+    if (targetType === 'pull_request' && !isAbsoluteHttpUrl(target?.url)) {
+        return 'reviewHandoff.reviewTarget.url must be an absolute http or https URL';
+    }
+    // Match the host parser's object-artifact selection and Hub's path/URL
+    // normalization. A missing label/type is filled in by the Hub, not rejected.
+    const artifacts = Array.isArray(handoff.artifacts)
+        ? handoff.artifacts.filter((artifact) => artifact && typeof artifact === 'object')
+        : [];
+    for (const [index, artifact] of artifacts.entries()) {
+        const hasPath = typeof artifact.path === 'string' && artifact.path.trim().length > 0;
+        const hasUrl = isAbsoluteHttpUrl(artifact.url);
+        if (targetType === 'pull_request') {
+            if (hasPath || hasUrl)
+                return 'reviewHandoff.artifacts must be empty for a pull_request target';
+        }
+        else if (!hasPath || hasUrl) {
+            return `reviewHandoff.artifacts[${index}] cannot be applied: an artifact_set requires a file path without an http or https URL`;
+        }
+    }
+    return null;
+}
+/** Validate the complete submission contract, including required actions. */
 function validateReviewHandoff(value) {
     if (value === undefined || value === null) {
         return ['evidence.reviewHandoff is missing'];

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-command.js

@@ -21,15 +21,10 @@ 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.
+ * Preserve checkpointed history and distinguish backup recovery from attestation backfill.
+ * Backfill supplements older firings; it cannot reconstruct missing offers.
  */
-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.';
+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());
 }
@@ -488,14 +483,14 @@ const verifyCommand = addModelOption(addCommonOptions(new commander_1.Command('v
             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('    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 compact it to the configured retention window.`
+            ? `  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);

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

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

@@ -10,6 +10,7 @@ exports.ruleUsageKey = ruleUsageKey;
 exports.resolveEntryIdentity = resolveEntryIdentity;
 exports.normalizeModelName = normalizeModelName;
 exports.readUsageSnapshot = readUsageSnapshot;
+exports.resolveUsageCheckpointPath = resolveUsageCheckpointPath;
 exports.writeUsageSnapshot = writeUsageSnapshot;
 exports.foldUsageEvents = foldUsageEvents;
 exports.readUsageStore = readUsageStore;
@@ -46,18 +47,10 @@ exports.compactUsageEvents = compactUsageEvents;
  * (`src/ai-hub/server.ts`). That placement is what satisfies R18; there is no
  * second guardrail here.
  *
- * It is derived data (R17): deleting it loses no lesson, because every firing is
- * still written in the retrospective that attested it and every offer is
- * re-recorded the next time the entry is delivered.
- *
- * ## Issue #1752 — what changed and why
- *
- * The durable artifact is now the append-only event log in
- * `learning-usage-events.ts`; `usage/learning-usage.json` is a derived snapshot
- * carrying a `foldedThroughBytes` checkpoint into it. The old read-modify-write
- * lost 1589 of 1600 writes from eight concurrent processes on a plain local disk
- * (spike S1b), which is the real cause of both the impossible `fired > offered`
- * counts and the four OneDrive conflict copies.
+ * Sleep consolidates the append-only journal into learning-usage.json and its
+ * recoverable .checkpoint copy before clearing processed events. Those snapshots
+ * preserve lifetime aggregates and source bookmarks after journal cleanup.
+ * Raw retrospectives preserve lessons and attestations, not every runtime offer.
  *
  * Four smaller corrections ride with it, each removing a place where the record
  * gave a confident answer it could not prove:
@@ -306,32 +299,45 @@ function readCheckpoints(value) {
     }
     return out;
 }
-/**
- * Parse the snapshot alone, with no event folding. A missing or corrupt snapshot
- * reads as empty: it is derived data, so losing it is recoverable and must never
- * break the loader that reads it.
- */
+/** Read the normal snapshot, recovering a missing or torn copy from its checkpoint. */
 function readUsageSnapshot(storePath = resolveUsageStorePath()) {
+    for (const candidate of [storePath, resolveUsageCheckpointPath(storePath)]) {
+        const snapshot = parseUsageSnapshot(candidate);
+        if (snapshot)
+            return snapshot;
+    }
+    if ((0, fs_1.existsSync)(resolveUsageCheckpointPath(storePath))) {
+        throw new Error('Usage snapshot and checkpoint backup are unreadable. Restore a matching backup; do not delete the usage directory.');
+    }
+    return emptyStore();
+}
+function resolveUsageCheckpointPath(storePath) {
+    return storePath + '.checkpoint';
+}
+function parseUsageSnapshot(storePath) {
     try {
         if (!(0, fs_1.existsSync)(storePath))
-            return emptyStore();
+            return null;
         const parsed = JSON.parse((0, fs_1.readFileSync)(storePath, 'utf8'));
         // `typeof [] === 'object'`, so an array has to be rejected explicitly: otherwise
         // Object.values yields whatever the array held and every consumer that reads
         // `entry.offered` throws on it.
         if (!parsed || typeof parsed !== 'object' || !parsed.entries
             || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
-            return emptyStore();
+            return null;
         }
         // Drop any value that is not a usable record rather than handing a caller
         // something it will crash on. A partially corrupt store degrades to the records
-        // that are still readable, which is the right behaviour for derived data.
+        // that are still readable before consolidation. Consolidated snapshots must be complete.
         const entries = {};
         for (const [key, value] of Object.entries(parsed.entries)) {
             if (isUsableRecord(value))
                 entries[key] = value;
+            else if (parsed.consolidated)
+                return null;
         }
         return {
+            consolidated: parsed.consolidated === true,
             version: parsed.version ?? STORE_VERSION,
             updatedAt: parsed.updatedAt ?? emptyStore().updatedAt,
             entries,
@@ -342,28 +348,18 @@ function readUsageSnapshot(storePath = resolveUsageStorePath()) {
         };
     }
     catch {
-        return emptyStore();
+        return null;
     }
 }
 /**
- * Publish the derived snapshot.
- *
- * In place, with a plain `writeFileSync`, and never by rename. S3 measured a
- * rename over a target any process holds open failing EPERM 100 times in 100, on
- * both a synced and a local path, because that is Windows file-sharing semantics
- * rather than a OneDrive artefact. The usage store is read by concurrent MCP
- * processes by design, so a rename-published snapshot would fail essentially
- * always in production. This is safe precisely because the snapshot is derived: a
- * torn one is rejected by `readUsageSnapshot` and rebuilt from the log.
- *
- * Returns whether it landed. A failure is never thrown: the log is authoritative
- * and the next reader either uses the older snapshot with a longer tail, or folds
- * cold.
+ * Refresh the normal snapshot in place (Windows readers can prevent rename).
+ * Sleep alone publishes the separate flushed checkpoint backup before clearing
+ * journals, so a torn ordinary refresh can recover without replaying old history.
  */
 function writeUsageSnapshot(store, storePath = resolveUsageStorePath()) {
     try {
         (0, fs_1.mkdirSync)((0, path_1.dirname)(storePath), { recursive: true });
-        (0, fs_1.writeFileSync)(storePath, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+        (0, fs_1.writeFileSync)(storePath, `${JSON.stringify(store, null, 2)}\n`, { encoding: 'utf8', flush: true });
         return true;
     }
     catch {
@@ -385,6 +381,8 @@ function foldUsageEvents(options) {
     // A checkpoint past the end of its log means the log was compacted or replaced
     // under this snapshot, so the snapshot may already count events the log no
     // longer holds. Re-folding onto it would double count. Discard and fold cold.
+    if (tail.restarted && base.consolidated)
+        throw new Error('Usage journal no longer matches its consolidated snapshot. Restore matching checkpoint files before continuing.');
     if (tail.restarted) {
         const cold = (0, learning_usage_events_1.readEventsSince)(options.eventDir, {});
         return applyTail(emptyStore(), cold, limits, now, true);
@@ -393,6 +391,7 @@ function foldUsageEvents(options) {
 }
 function applyTail(base, tail, limits, now, restarted) {
     const store = {
+        consolidated: base.consolidated,
         version: base.version,
         updatedAt: base.updatedAt,
         entries: base.entries,
@@ -430,13 +429,23 @@ function readUsageStore(storePath = resolveUsageStorePath(), options = {}) {
     const eventDir = options.eventDir ?? (0, learning_usage_events_1.resolveEventDir)(storePath);
     if ((0, learning_usage_events_1.listEventLogs)(eventDir).length === 0)
         return snapshot;
-    const folded = foldUsageEvents({
+    const fold = (base) => foldUsageEvents({
         eventDir,
         limits: options.limits,
         now: options.now,
-        base: snapshot,
-        checkpoints: snapshot.foldedThroughBytes ?? {},
+        base,
+        checkpoints: base.foldedThroughBytes ?? {},
     });
+    let folded;
+    try {
+        folded = fold(snapshot);
+    }
+    catch (error) {
+        const backup = parseUsageSnapshot(resolveUsageCheckpointPath(storePath));
+        if (!backup)
+            throw error;
+        folded = fold(backup);
+    }
     const mode = options.refreshSnapshot ?? 'auto';
     const shouldRefresh = mode === 'always'
         || (mode === 'auto' && (folded.tailBytes >= SNAPSHOT_REFRESH_BYTES || !(0, fs_1.existsSync)(storePath) || folded.restarted));
@@ -747,7 +756,7 @@ function flagIntegrity(store) {
 /**
  * Materialize the snapshot when there is none.
  *
- * The snapshot is derived and normally published by readers, but a workspace that
+ * Before the first consolidation, readers publish snapshots, but a workspace that
  * has only ever been written to would have no snapshot at all, so every reader
  * would pay a cold fold and anything inspecting the store as a file would find
  * nothing there. Bounded: it only runs when the file is absent, and at that point
@@ -761,7 +770,7 @@ function ensureSnapshotExists(storePath, eventDir, limits, now) {
         readUsageStore(storePath, { limits, now, eventDir, refreshSnapshot: 'always' });
     }
     catch {
-        // The log is authoritative. A missing snapshot costs a cold fold, nothing else.
+        // Initial cache publication can retry; consolidated history has a separate backup.
     }
 }
 /**
@@ -899,26 +908,48 @@ function pruneUsageStore(limits, options = {}) {
     const compaction = compactUsageEvents({ eventDir, snapshotPath: storePath, limits, now, store });
     return { prunedOfferRecords, prunedFiringRecords, entries: Object.keys(store.entries).length, compaction };
 }
-/**
- * Rewrite the event logs to the configured retention window and re-base the
- * snapshot's checkpoint onto the rewritten logs.
- *
- * Re-basing is not optional: leaving a checkpoint pointing into the old log would
- * make the next reader either re-count events the snapshot already holds, or skip
- * ones it does not.
+/** Save totals and source bookmarks in both copies, then clear processed journals.
+ * Requires an interval without concurrent writers or sync activity.
  */
 function compactUsageEvents(options) {
     const now = options.now ?? new Date();
     const store = options.store
         ?? readUsageStore(options.snapshotPath, { limits: options.limits, now, eventDir: options.eventDir });
-    const result = (0, learning_usage_events_1.compactEventLogs)(options.eventDir, (event) => {
+    for (const log of (0, learning_usage_events_1.listEventLogs)(options.eventDir)) {
+        if ((store.foldedThroughBytes?.[log.machineId] ?? 0) < log.baseOffset) {
+            throw new Error('Cannot consolidate from a snapshot older than the journal checkpoint.');
+        }
+    }
+    for (const entry of Object.values(store.entries))
+        trimLogs(entry, options.limits, now);
+    store.consolidated = true;
+    store.updatedAt = now.toISOString();
+    // Publish the recoverable checkpoint first, then the normal snapshot. No
+    // journal is cleared unless both writes succeed. The backup is never written
+    // by ordinary readers, so a torn cache refresh cannot destroy both copies.
+    const checkpoint = resolveUsageCheckpointPath(options.snapshotPath);
+    const temp = checkpoint + '.tmp';
+    try {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(checkpoint), { recursive: true });
+        (0, fs_1.writeFileSync)(temp, JSON.stringify(store, null, 2) + '\n', { encoding: 'utf8', flush: true });
+        (0, fs_1.renameSync)(temp, checkpoint);
+    }
+    catch {
+        try {
+            (0, fs_1.rmSync)(temp, { force: true });
+        }
+        catch { /* Best effort. */ }
+        throw new Error('Cannot consolidate usage events: checkpoint backup could not be saved.');
+    }
+    if (!writeUsageSnapshot(store, options.snapshotPath)) {
+        throw new Error('Cannot consolidate usage events: aggregate snapshot could not be saved.');
+    }
+    return (0, learning_usage_events_1.compactEventLogs)(options.eventDir, (event) => {
+        if (event.kind !== 'offer' && event.kind !== 'firing')
+            return true;
         const date = typeof event.date === 'string' ? event.date : '';
-        if (!isValidDate(date))
+        if (typeof event.key !== 'string' || !event.key || !isValidDate(date))
             return true;
-        return withinRetention(date, options.limits.retentionDays, now);
-    });
-    store.foldedThroughBytes = Object.fromEntries(result.logs.map((log) => [log.machineId, log.size]));
-    store.updatedAt = now.toISOString();
-    writeUsageSnapshot(store, options.snapshotPath);
-    return result;
+        return event.kind === 'firing' && !exports.FIRING_OUTCOMES.includes(event.outcome);
+    }, store.foldedThroughBytes ?? {});
 }

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

@@ -16,31 +16,16 @@ exports.buildVerifyReport = buildVerifyReport;
  * It reports and never blocks. Nothing here treats a finding as a gate: it states
  * what it found, and the manager decides.
  *
- * ## Why there is no repair command here
+ * ## Recovery boundary
  *
- * The usage record is derived data (#1103 R17): every firing is also written in
- * the retrospective that attested it, and every offer is re-recorded the next
- * time the entry is delivered. So the repair for a store that has gone wrong is
- * to delete it and rebuild, not to reconcile it in place.
- *
- * That is not a preference, it is what the numbers say. Measured on a 733-file
- * retrospective corpus with four unmerged store copies beside the canonical one:
- *
- *   delete `usage/` then `learning-usage backfill`  ->  149 entries, 2874 firings,
- *                                                       0 split identities,
- *                                                       1 clean model bucket
- *
- * A rebuild lands with zero split identities and one model bucket for free,
- * because the identity resolution and the model normalization fix the causes and
- * a rebuilt store carries no legacy shape. The only thing an in-place
- * reconciliation recovers beyond that is old firings whose retrospectives
- * retention has already deleted, and a decay clock reads the most recent firing
- * rather than the count. What a rebuild does cost is the offer history, which
- * rebuilds itself from live traffic and degrades toward `undetermined` and
- * hold-back in the meantime, which is this module's posture anyway.
- *
- * So `verify` names the rebuild when it finds a stale shape, and the destructive
- * step stays the manager's.
+ * Rebuild only the snapshot, keeping the event directory intact. The retained
+ * events recover the offers and firings they cover; retrospective backfill can
+ * supplement older firings but cannot recreate offers. Normal compaction keeps
+ * lifetime aggregate totals in the snapshot, so a backup is required before
+ * discarding it if history already pruned from events must remain inspectable.
+ * Rebuilding cannot invent missing history or fix identities still present in
+ * the authoritative events. Verify reports those limitations rather than
+ * claiming that deleting the usage directory is a lossless repair.
  */
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -212,7 +197,7 @@ function buildVerifyReport(options) {
         // The one number that makes a stale read visible: a snapshot that stops
         // advancing while the log grows is a failing snapshot write, which S3 showed
         // will happen intermittently on a synced folder and is otherwise silent.
-        checkpointLag: Object.fromEntries(logs.map((log) => [log.machineId, Math.max(0, log.size - (checkpoints[log.machineId] ?? 0))])),
+        checkpointLag: Object.fromEntries(logs.map((log) => [log.machineId, Math.max(0, log.baseOffset + log.size - log.headerBytes - (checkpoints[log.machineId] ?? 0))])),
         skippedLines: 0,
         totalLogBytes,
         compactionAdvisoryBytes: exports.COMPACTION_ADVISORY_BYTES,

package/dist/src/local-mcp-server/stdio-server.js

@@ -2428,6 +2428,35 @@ class FraimLocalMCPServer {
         if (request.method === 'tools/call' && typeof toolName === 'string') {
             // 🔍 SMART DISPATCHER: Intercept mentoring and job/workflow tools for local overrides
             if (toolName === 'seekMentoring') {
+                // #1766: report an unrenderable supplied handoff before any mentoring
+                // success response, including when phase-policy enforcement is disabled.
+                // Match the host's direct/evidence/findings precedence and JSON support.
+                const suppliedHandoffs = [args.reviewHandoff, args.evidence?.reviewHandoff, args.findings?.reviewHandoff]
+                    .filter((value) => value !== undefined && value !== null)
+                    .map((value) => {
+                    if (typeof value !== 'string')
+                        return value;
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch {
+                        return value;
+                    }
+                });
+                const suppliedHandoff = suppliedHandoffs.find((value) => value && typeof value === 'object' && !Array.isArray(value) && typeof value.reviewRequired === 'boolean') ?? suppliedHandoffs[0];
+                if (suppliedHandoffs.length > 0) {
+                    const normalizationError = (0, handoff_contracts_1.reviewHandoffNormalizationError)(suppliedHandoff);
+                    if (normalizationError) {
+                        return {
+                            jsonrpc: '2.0',
+                            id: request.id,
+                            result: {
+                                isError: true,
+                                content: [{ type: 'text', text: `Review handoff was not applied: ${normalizationError}. This response does not confirm delivery.` }],
+                            },
+                        };
+                    }
+                }
                 try {
                     const mentor = this.getMentor(requestSessionId);
                     const tutoringResponse = await mentor.handleMentoringRequest(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.339",
+  "version": "2.0.340",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist/registry/scripts/learning/learning-domains.json",
     "dist/registry/scripts/learning/entry-format.js",
+    "dist/registry/scripts/learning/completion-state.js",
     "dist/src/local-mcp-server/",
     "dist/src/cli/",
     "!dist/src/cli/fraim-hub.js",