fraim 2.0.342 → 2.0.344

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

@@ -32,7 +32,7 @@ class AIMentor {
             }
         }
         if (args.status === 'starting') {
-            return await this.generateStartingMessage(workflow, args.currentPhase, args.skipIncludes);
+            return await this.generateStartingMessage(workflow, args.currentPhase, args.skipIncludes, args.requestInstructions);
         }
         else if (args.status === 'complete') {
             return await this.generateCompletionMessage(workflow, args.currentPhase, args.findings, args.evidence, args.skipIncludes);
@@ -65,6 +65,9 @@ class AIMentor {
         const unique = Array.from(new Set(matches));
         throw new Error(`Unresolved include directives in ${context}: ${unique.join(', ')}`);
     }
+    buildPhaseArrivalInstruction(jobName, phaseId) {
+        return `## On Arrival\nBefore starting any work in this phase, call \`seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "starting" })\`.\n\n`;
+    }
     buildReportBackFooter(jobName, phaseId, phaseFlow) {
         if (!phaseFlow)
             return '';
@@ -99,6 +102,9 @@ class AIMentor {
     getCompactPhaseAuthority() {
         return AIMentor.COMPACT_PHASE_AUTHORITY;
     }
+    getEvidenceInitialization() {
+        return '## Initialize the Work Record\nAfter resolving the workspace and owning home, before substantive work, read and follow `get_fraim_file({ path: "delivery/initialize-evidence.md" })`. Resume the existing run record when continuing work.';
+    }
     buildPhasedJobOverview(workflow) {
         const metadataPhases = Object.keys(workflow.metadata.phases || {});
         const initialPhase = workflow.metadata.initialPhase || metadataPhases[0] || Array.from(workflow.phases.keys())[0] || 'starting';
@@ -120,9 +126,10 @@ class AIMentor {
                 + ' `get_fraim_file({ path: "skills/engineering/set-up-workspace.md" })`'
                 + ' to work on the issue\'s branch when a repository is configured, or in place otherwise.');
         }
+        lines.push('', this.getEvidenceInitialization());
         return lines.join('\n');
     }
-    async generateStartingMessage(workflow, phaseId, skipIncludes) {
+    async generateStartingMessage(workflow, phaseId, skipIncludes, requestInstructions) {
         const entityType = 'Job';
         if (workflow.isSimple) {
             const message = `Starting ${entityType}: ${workflow.metadata.name}\n\n${workflow.overview}`;
@@ -134,26 +141,42 @@ class AIMentor {
             };
         }
         const isVeryFirstCall = phaseId === 'starting';
-        let targetPhase = isVeryFirstCall ? (workflow.metadata.initialPhase || 'starting') : phaseId;
+        const initialPhase = workflow.metadata.initialPhase || Object.keys(workflow.metadata.phases || {})[0] || Array.from(workflow.phases.keys())[0] || 'starting';
+        let targetPhase = isVeryFirstCall ? initialPhase : phaseId;
         const targetDefinition = workflow.metadata.phases?.[targetPhase];
+        // Named initial phases and scheduled recurrence entry have no preceding
+        // completion response supplying their instructions.
+        const deliverInstructions = isVeryFirstCall || phaseId === initialPhase
+            || (0, resolve_phase_edge_1.isRecurrencePhase)(targetDefinition)
+            || (0, resolve_phase_edge_1.findRecurrenceForMember)(workflow.metadata.phases, phaseId)?.role === 'recur'
+            || requestInstructions === true;
         if ((0, resolve_phase_edge_1.isRecurrencePhase)(targetDefinition)) {
             targetPhase = isVeryFirstCall ? targetDefinition.setup.phase : targetDefinition.recur.phase;
         }
         let message = `### Current Phase: ${targetPhase}\n\n`;
-        let instructions = workflow.phases.get(targetPhase);
-        if (instructions) {
-            instructions = skipIncludes ? instructions : await this.resolveIncludes(instructions, workflow.path);
-            message += instructions;
+        if (isVeryFirstCall) {
+            message += this.buildPhaseArrivalInstruction(workflow.metadata.name, targetPhase);
         }
-        else {
-            message += `No specific instructions found for phase: ${targetPhase}`;
+        if (deliverInstructions) {
+            let instructions = workflow.phases.get(targetPhase);
+            if (instructions) {
+                // The proxy survives compaction with a warmed skill cache. An
+                // explicit recovery must restore nested skill bodies as well.
+                instructions = skipIncludes ? instructions : requestInstructions === true
+                    ? await (0, include_resolver_1.resolveIncludes)(instructions, this.resolver, workflow.path)
+                    : await this.resolveIncludes(instructions, workflow.path);
+                message += instructions;
+            }
+            else {
+                message += `No specific instructions found for phase: ${targetPhase}`;
+            }
         }
         const recurrenceMember = (0, resolve_phase_edge_1.findRecurrenceForMember)(workflow.metadata.phases, targetPhase);
         const phaseFlow = recurrenceMember
             ? { onSuccess: undefined, onFailure: recurrenceMember.node[recurrenceMember.role].onFailure }
             : ((0, resolve_phase_edge_1.isRecurrencePhase)(workflow.metadata.phases?.[targetPhase]) ? undefined : workflow.metadata.phases?.[targetPhase]);
         message += this.buildReportBackFooter(workflow.metadata.name, targetPhase, phaseFlow);
-        if (!skipIncludes) {
+        if (deliverInstructions && !skipIncludes) {
             this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name}:${targetPhase} (starting)`);
         }
         return {
@@ -229,6 +252,7 @@ class AIMentor {
         }
         else if (nextPhaseId) {
             message += `Moving to the next phase: **${nextPhaseId}**.\n\n`;
+            message += this.buildPhaseArrivalInstruction(workflow.metadata.name, nextPhaseId);
             let nextInstructions = workflow.phases.get(nextPhaseId);
             if (nextInstructions) {
                 nextInstructions = skipIncludes ? nextInstructions : await this.resolveIncludes(nextInstructions, workflow.path);
@@ -275,6 +299,13 @@ class AIMentor {
                 ?? (!(0, resolve_phase_edge_1.isRecurrencePhase)(phaseMeta) ? phaseMeta?.onFailure : undefined), (0, resolve_phase_edge_1.resolveDiscriminant)(findings, evidence)) || phaseId)
             : phaseId;
         let message = `### Current Phase: ${targetPhaseId}\n\n`;
+        // Issue #1935: a `failure` commits a completion for the phase being left, so
+        // the phase resolved above is entered with no open instance and needs its own
+        // `status: "starting"` call, for a back-edge and for the self-retry alike.
+        // `incomplete` commits nothing and never leaves the phase, so it gets none.
+        if (status === 'failure') {
+            message += this.buildPhaseArrivalInstruction(workflow.metadata.name, targetPhaseId);
+        }
         let instructions = workflow.phases.get(targetPhaseId);
         if (instructions) {
             instructions = skipIncludes ? instructions : await this.resolveIncludes(instructions, workflow.path);
@@ -329,7 +360,7 @@ class AIMentor {
         if (!job)
             return null;
         if (job.isSimple) {
-            return { overview: job.overview, isSimple: true };
+            return { overview: `${job.overview}\n\n${this.getEvidenceInitialization()}`, isSimple: true };
         }
         return {
             overview: this.buildPhasedJobOverview(job),

package/dist/src/core/config-loader.js

@@ -169,6 +169,10 @@ function normalizeFraimConfig(config, options = {}) {
     if (config.learning) {
         mergedConfig.learning = config.learning;
     }
+    if (config.artifactPaths !== undefined) {
+        // Preserve configuration; the shared artifact resolver owns validation and defaults.
+        mergedConfig.artifactPaths = config.artifactPaths;
+    }
     if (config.competitors && typeof config.competitors === 'object') {
         mergedConfig.competitors = config.competitors;
     }

package/dist/src/core/fraim-config-schema.generated.js

@@ -230,6 +230,23 @@ exports.FRAIM_CONFIG_SCHEMA = {
                 }
             }
         },
+        "artifactPaths": {
+            "kind": "object",
+            "properties": {
+                "evidence": {
+                    "kind": "string"
+                },
+                "rawLearnings": {
+                    "kind": "string"
+                },
+                "learningRetrospectives": {
+                    "kind": "string"
+                },
+                "learningArchive": {
+                    "kind": "string"
+                }
+            }
+        },
         "customer-communication": {
             "kind": "object",
             "properties": {
@@ -693,6 +710,11 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "learning.usage.firingLogLimit",
     "learning.usage.offerLogLimit",
     "learning.usage.retirementOfferThreshold",
+    "artifactPaths",
+    "artifactPaths.evidence",
+    "artifactPaths.rawLearnings",
+    "artifactPaths.learningRetrospectives",
+    "artifactPaths.learningArchive",
     "customer-communication",
     "customer-communication.productName",
     "customer-communication.productUrl",

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

@@ -297,11 +297,16 @@ function upsertPhaseStarted(marker, phaseId, timestamp) {
     startedPhases[phaseId] = timestamp;
     return { startedPhases };
 }
-/** Builds the warn-only notice for any phase completed without an on-arrival start. */
-function buildPhaseStartWarning(phaseId) {
-    return (`⚠️ **Phase-start notice**: phase \`${phaseId}\` completed without an on-arrival ` +
+/** Builds the warn-only notice for any phase completed without an on-arrival start.
+ * When nextPhase is supplied, a forward-looking instruction is appended so the agent
+ * knows to call seekMentoring({status:"starting"}) before beginning the next phase. */
+function buildPhaseStartWarning(phaseId, nextPhase) {
+    const base = (`⚠️ **Phase-start notice**: phase \`${phaseId}\` completed without an on-arrival ` +
         `\`seekMentoring({ currentPhase: "${phaseId}", status: "starting" })\` call in this session. ` +
         `The missing call was flagged, but this completion remains accepted.\n\n`);
+    if (!nextPhase)
+        return base;
+    return base + `Before starting any work in **${nextPhase}**, call \`seekMentoring({ currentPhase: "${nextPhase}", status: "starting" })\` immediately.\n\n`;
 }
 function isAbsoluteHttpUrl(url) {
     if (typeof url !== 'string' || !url)

package/dist/src/core/utils/local-registry-resolver.js

@@ -72,6 +72,17 @@ class LocalRegistryResolver {
         }
         return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, ...parts);
     }
+    /**
+     * Machine catalogs own synced content. Legacy project catalogs are a fallback
+     * only when that machine catalog is absent, so removed entries cannot revive
+     * from an old project copy. Explicit user-level roots remain self-contained.
+     */
+    getSyncedCatalogRoot(role, type) {
+        if (this.effectiveFraimDir)
+            return (0, path_1.join)(this.effectiveFraimDir, role, type);
+        const machineRoot = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), role, type);
+        return (0, fs_1.existsSync)(machineRoot) ? machineRoot : this.getFraimPath(role, type);
+    }
     /**
      * Check if a local override exists for the given path
      */
@@ -102,16 +113,16 @@ class LocalRegistryResolver {
                 (0, path_1.join)(this.managerCacheRoot, dir),
                 (0, path_1.join)(this.orgCacheRoot, dir),
                 (0, path_1.join)(this.workspaceRoot, 'registry', dir),
-                // Installed projects have categorized job stubs in the synced roles,
-                // without a source registry checkout. Keep authored overrides first.
-                ...(type === 'jobs' ? [this.getFraimPath('ai-employee', dir), this.getFraimPath('ai-manager', dir)] : []),
+                // Installed projects discover categorized capabilities in machine catalogs.
+                this.getSyncedCatalogRoot('ai-employee', dir),
+                ...(type !== 'skills' ? [this.getSyncedCatalogRoot('ai-manager', dir)] : []),
             ];
             for (const root of searchRoots) {
                 const found = this.searchFileRecursively(root, baseName);
                 if (!found)
                     continue;
-                const syncedRole = ['ai-employee', 'ai-manager'].find(role => root === this.getFraimPath(role, dir));
-                if (syncedRole)
+                const syncedRole = ['ai-employee', 'ai-manager'].find(role => root === this.getSyncedCatalogRoot(role, dir));
+                if (syncedRole && type !== 'skills')
                     return `${dir}/${syncedRole}/${found.slice(root.length + 1).replace(/\\/g, '/')}`;
                 // Convert absolute back to a registry-relative path.
                 const rel = found.replace(/\\/g, '/');
@@ -157,67 +168,32 @@ class LocalRegistryResolver {
         return this.getFraimPath('personalized-employee', normalized);
     }
     /**
-     * Get the full path to a locally synced FRAIM file when available.
-     * Skills and rules are synced under role-based folders:
-     * - skills/* -> fraim/ai-employee/skills/*
-     * - rules/*  -> fraim/ai-employee/rules/*
+     * Resolve synced content from machine catalogs, retaining legacy project
+     * catalogs only when the corresponding machine catalog is unavailable.
      */
     getSyncedFilePath(path) {
         const normalizedPath = path.replace(/\\/g, '/').replace(/^\/+/, '');
-        // 1. Workflows: workflows/[role]/path -> fraim/[role]/workflows/path
-        if (normalizedPath.startsWith('workflows/')) {
-            const parts = normalizedPath.split('/');
+        const parts = normalizedPath.split('/');
+        const type = parts[0];
+        if (type === 'jobs' || type === 'workflows') {
             if (parts.length >= 3 && (parts[1] === 'ai-employee' || parts[1] === 'ai-manager')) {
-                const role = parts[1];
-                const subPath = parts.slice(2).join('/');
-                return this.getFraimPath(role, 'workflows', subPath);
+                return (0, path_1.join)(this.getSyncedCatalogRoot(parts[1], type), ...parts.slice(2));
             }
-            // Fallback: Try ai-employee and ai-manager if no role prefix
-            const subPath = normalizedPath.substring('workflows/'.length);
-            const employeePath = this.getFraimPath('ai-employee', 'workflows', subPath);
-            if (fs.existsSync(employeePath))
-                return employeePath;
-            const managerPath = this.getFraimPath('ai-manager', 'workflows', subPath);
-            if (fs.existsSync(managerPath))
-                return managerPath;
-            // Fallback for non-role-prefixed direct workspace paths
-            return this.getFraimPath(normalizedPath);
-        }
-        // 2. Jobs: jobs/[role]/path -> fraim/[role]/jobs/path
-        if (normalizedPath.startsWith('jobs/')) {
-            const parts = normalizedPath.split('/');
-            if (parts.length >= 3 && (parts[1] === 'ai-employee' || parts[1] === 'ai-manager')) {
-                const role = parts[1];
-                const subPath = parts.slice(2).join('/');
-                return this.getFraimPath(role, 'jobs', subPath);
+            for (const role of ['ai-employee', 'ai-manager']) {
+                const candidate = (0, path_1.join)(this.getSyncedCatalogRoot(role, type), ...parts.slice(1));
+                if ((0, fs_1.existsSync)(candidate))
+                    return candidate;
             }
-            // Fallback: Try ai-employee and ai-manager if no role prefix
-            const subPath = normalizedPath.substring('jobs/'.length);
-            const employeePath = this.getFraimPath('ai-employee', 'jobs', subPath);
-            if (fs.existsSync(employeePath))
-                return employeePath;
-            const managerPath = this.getFraimPath('ai-manager', 'jobs', subPath);
-            if (fs.existsSync(managerPath))
-                return managerPath;
-            // Fallback
+            // Retain direct workspace job/workflow files authored outside the catalogs.
             return this.getFraimPath(normalizedPath);
         }
-        // 3. Rules: [role]/rules/path -> fraim/[role]/rules/path
         if (normalizedPath.includes('/rules/')) {
-            const role = normalizedPath.includes('/ai-manager/') ? 'ai-manager' : 'ai-employee';
-            // Extract the part after "rules/"
-            const rulesIdx = normalizedPath.indexOf('rules/');
-            const subPath = normalizedPath.substring(rulesIdx + 'rules/'.length);
-            return this.getFraimPath(role, 'rules', subPath);
-        }
-        // 4. Skills: skills/path -> fraim/ai-employee/skills/path (default to ai-employee)
-        if (normalizedPath.startsWith('skills/')) {
-            const subPath = normalizedPath.substring('skills/'.length);
-            return this.getFraimPath('ai-employee', 'skills', subPath);
+            const role = parts.includes('ai-manager') ? 'ai-manager' : 'ai-employee';
+            const subPath = normalizedPath.substring(normalizedPath.indexOf('rules/') + 'rules/'.length);
+            return (0, path_1.join)(this.getSyncedCatalogRoot(role, 'rules'), subPath);
         }
-        // 5. Rules: rules/path -> fraim/ai-employee/rules/path (default to ai-employee)
-        if (normalizedPath.startsWith('rules/')) {
-            return this.getFraimPath('ai-employee', normalizedPath);
+        if (type === 'skills' || type === 'rules') {
+            return (0, path_1.join)(this.getSyncedCatalogRoot('ai-employee', type), ...parts.slice(1));
         }
         return null;
     }
@@ -579,7 +555,7 @@ class LocalRegistryResolver {
             }
             const syncedLocalContent = this.readSyncedLocalFile(path);
             if (syncedLocalContent !== null) {
-                // Synced baseline (fraim/ai-employee), not personalized.
+                // Synced machine baseline, not personalized.
                 return {
                     content: syncedLocalContent,
                     source: 'local',

package/dist/src/fraim/db-service.js

@@ -1090,6 +1090,22 @@ class FraimDbService {
         });
         return latest?.createdAt ?? null;
     }
+    /** Keep the earliest observed start per execution before grouping into time buckets. */
+    distinctJobStartStages() {
+        return [
+            { $sort: { createdAt: 1, _id: 1 } },
+            { $group: {
+                    _id: { $cond: [
+                            { $and: [{ $eq: ['$type', 'job'] }, { $ne: [{ $ifNull: ['$jobId', ''] }, ''] }] },
+                            { userId: '$userId', name: '$name', jobId: '$jobId' },
+                            // Preserve legacy event counts when no execution ID is available.
+                            '$_id',
+                        ] },
+                    event: { $first: '$$ROOT' },
+                } },
+            { $replaceRoot: { newRoot: '$event' } },
+        ];
+    }
     /**
      * Get top components by usage count
      */
@@ -1106,18 +1122,19 @@ class FraimDbService {
         if (types && types.length > 0) {
             matchStage.type = { $in: types };
         }
-        // When counting job events, exclude explicit complete events so each run is
-        // counted once. A completed run emits both start and complete; without this
-        // filter the dashboard would show double the runs count vs the runs list.
-        // Old-path events (no args.action field) pass through because $ne includes
-        // documents where the field is absent.
+        // Job instruction reloads are continuation events, not new executions.
+        // Preserve other component usage and legacy job loads without action metadata.
         if (!types || types.includes('job')) {
-            matchStage['args.action'] = { $ne: 'complete' };
+            matchStage.$or = [
+                { type: { $ne: 'job' } },
+                { 'args.action': { $ne: 'complete' }, 'args.isReload': { $ne: true } },
+            ];
         }
         const pipeline = [
             {
                 $match: matchStage
             },
+            ...this.distinctJobStartStages(),
             {
                 $group: {
                     _id: { name: '$name', type: '$type' },
@@ -1250,6 +1267,7 @@ class FraimDbService {
             // Exclude explicit complete events so each run is counted once (at start).
             // Old-path events have no args.action and are included by $ne.
             'args.action': { $ne: 'complete' },
+            'args.isReload': { $ne: true },
             createdAt: this.buildCreatedAtMatch(timeWindow)
         };
         if (userId) {
@@ -1277,6 +1295,7 @@ class FraimDbService {
         }
         const pipeline = [
             { $match: matchStage },
+            ...this.distinctJobStartStages(),
             {
                 $group: {
                     _id: {
@@ -1837,133 +1856,123 @@ class FraimDbService {
         const collection = this.db.collection(this.usageEventsCollectionName);
         const sanitizedRepo = repoIdentifier ? (0, git_utils_1.sanitizeRepoIdentifier)(repoIdentifier) : undefined;
         const createdAtMatch = { $gte: startDate, ...(endDate ? { $lte: endDate } : {}) };
-        // Check if we have explicit job lifecycle events
-        const explicitMatch = { type: 'job', 'args.action': 'start', createdAt: createdAtMatch };
-        if (jobName)
-            explicitMatch.name = jobName;
-        if (userId)
-            explicitMatch.userId = userId;
-        if (sanitizedRepo)
-            explicitMatch.repoIdentifier = sanitizedRepo;
-        const hasExplicit = await collection.countDocuments(explicitMatch) > 0;
-        // Use explicit events if available, fall back to mentoring events for legacy data
-        const matchStage = hasExplicit
-            ? { type: 'job', 'args.action': { $in: ['start', 'complete'] }, createdAt: createdAtMatch }
-            : { type: 'mentoring', createdAt: createdAtMatch };
+        // Mentoring carries issue context that is not known when instructions load.
+        const matchStage = { type: { $in: ['job', 'mentoring'] }, createdAt: createdAtMatch };
         if (jobName)
             matchStage.name = jobName;
         if (userId)
             matchStage.userId = userId;
         if (sanitizedRepo)
             matchStage.repoIdentifier = sanitizedRepo;
-        const pipeline = [
+        const isStart = { $and: [
+                { $eq: ['$type', 'job'] }, { $eq: ['$args.action', 'start'] },
+                { $ne: [{ $ifNull: ['$args.isReload', false] }, true] },
+            ] };
+        const isLegacyLoad = { $and: [
+                { $eq: ['$type', 'job'] }, { $eq: [{ $ifNull: ['$args.action', null] }, null] },
+                { $ne: [{ $ifNull: ['$args.isReload', false] }, true] },
+            ] };
+        const isExplicitComplete = { $and: [{ $eq: ['$type', 'job'] }, { $eq: ['$args.action', 'complete'] }] };
+        const isLegacyComplete = { $and: [
+                { $eq: ['$type', 'mentoring'] }, { $eq: ['$args.status', 'complete'] },
+                { $eq: ['$args.nextPhase', null] },
+            ] };
+        const executions = await collection.aggregate([
             { $match: matchStage },
-            { $sort: { createdAt: 1 } },
-            {
-                $group: {
-                    _id: { jobName: '$name', jobId: '$jobId' },
-                    startTime: { $min: '$createdAt' },
-                    completeTime: {
-                        $max: {
-                            $cond: [
-                                { $or: [
-                                        { $eq: ['$args.action', 'complete'] },
-                                        { $eq: ['$args.nextPhase', null] }
-                                    ] },
-                                '$createdAt', null
-                            ]
-                        }
-                    },
-                    hasStart: { $first: { $cond: [true, true, false] } },
-                    hasComplete: {
-                        $max: {
-                            $cond: [
-                                { $or: [
-                                        { $eq: ['$args.action', 'complete'] },
-                                        { $eq: ['$args.nextPhase', null] }
-                                    ] },
-                                true, false
-                            ]
-                        }
-                    },
-                    eventCount: { $sum: 1 }
-                }
-            },
             {
                 $group: {
-                    _id: '$_id.jobName',
-                    totalStarted: { $sum: { $cond: ['$hasStart', 1, 0] } },
-                    totalCompleted: { $sum: { $cond: ['$hasComplete', 1, 0] } },
-                    completionDurations: {
-                        $push: {
-                            $cond: [
-                                { $and: ['$hasStart', '$hasComplete', { $ne: ['$startTime', null] }, { $ne: ['$completeTime', null] }] },
-                                { $subtract: ['$completeTime', '$startTime'] },
-                                null
-                            ]
-                        }
-                    },
-                    // Track last phase for abandoned jobs (started but not completed)
-                    abandonedPhases: {
-                        $push: {
-                            $cond: [
-                                { $and: ['$hasStart', { $not: '$hasComplete' }] },
-                                '$finalPhase',
-                                null
-                            ]
-                        }
-                    }
-                }
-            },
-            {
-                $project: {
-                    jobName: '$_id',
-                    totalStarted: 1,
-                    totalCompleted: 1,
-                    totalAbandoned: { $subtract: ['$totalStarted', '$totalCompleted'] },
-                    completionRate: {
-                        $cond: [
-                            { $gt: ['$totalStarted', 0] },
-                            { $divide: ['$totalCompleted', '$totalStarted'] },
-                            0
-                        ]
-                    },
-                    avgCompletionMs: {
-                        $cond: [
-                            { $gt: [{ $size: '$completionDurations' }, 0] },
-                            { $avg: '$completionDurations' },
-                            null
-                        ]
-                    },
-                    medianIdx: {
-                        $cond: [
-                            { $gt: [{ $size: '$completionDurations' }, 0] },
-                            { $floor: { $divide: [{ $size: '$completionDurations' }, 2] } },
-                            null
-                        ]
+                    _id: {
+                        jobName: '$name', userId: '$userId',
+                        execution: { $ifNull: ['$jobId', { $concat: ['sess_', { $ifNull: ['$sessionId', { $toString: '$_id' }] }] }] },
                     },
-                    completionDurations: 1
+                    firstEventTime: { $min: '$createdAt' },
+                    startTime: { $min: { $cond: [isStart, '$createdAt', null] } },
+                    completeTime: { $max: { $cond: [isExplicitComplete, '$createdAt', null] } },
+                    legacyCompleteTime: { $max: { $cond: [isLegacyComplete, '$createdAt', null] } },
+                    hasStart: { $max: { $cond: [isStart, true, false] } },
+                    hasLegacyLoad: { $max: { $cond: [isLegacyLoad, true, false] } },
+                    hasJobLifecycle: { $max: { $cond: [
+                                { $and: [{ $eq: ['$type', 'job'] }, { $in: ['$args.action', ['start', 'complete']] }] }, true, false,
+                            ] } },
+                    hasMentoring: { $max: { $cond: [{ $eq: ['$type', 'mentoring'] }, true, false] } },
+                    legacyAmbiguous: { $max: { $cond: [
+                                { $and: [isStart, { $or: [
+                                                { $ne: [{ $ifNull: ['$args.isReload', null] }, false] },
+                                                { $eq: [{ $ifNull: ['$jobId', ''] }, ''] },
+                                            ] }] }, true, false,
+                            ] } },
+                    repositories: { $addToSet: '$repoIdentifier' },
+                    issues: { $addToSet: '$args.issueNumber' },
                 }
             }
-        ];
-        const results = await collection.aggregate(pipeline).toArray();
-        return results.map(result => {
-            // Calculate median from sorted durations
-            const durations = (result.completionDurations || []).filter((d) => typeof d === 'number').sort((a, b) => a - b);
-            const medianMs = durations.length > 0 ? durations[Math.floor(durations.length / 2)] : undefined;
+        ]).toArray();
+        const grouped = new Map();
+        for (const execution of executions) {
+            // A reload or completion alone does not establish a start in this window.
+            // Keep old load/mentoring estimates, clearly labeled, without rewriting history.
+            const estimated = !execution.hasStart && (execution.hasLegacyLoad || (!execution.hasJobLifecycle && execution.hasMentoring));
+            if (!execution.hasStart && !estimated)
+                continue;
+            const name = execution._id.jobName;
+            const result = grouped.get(name) || { count: 0, completed: 0, known: 0, legacy: 0, conflicts: 0, workItems: new Set(), durations: [] };
+            grouped.set(name, result);
+            result.count++;
+            if (estimated || execution.legacyAmbiguous)
+                result.legacy++;
+            const repositories = new Set((execution.repositories || [])
+                .filter((value) => typeof value === 'string' && value.trim().length > 0)
+                .map((value) => (0, git_utils_1.sanitizeRepoIdentifier)(value)));
+            const issues = new Set((execution.issues || [])
+                .filter((value) => (typeof value === 'string' && value.trim().length > 0)
+                || (typeof value === 'number' && Number.isFinite(value)))
+                .map((value) => String(value).trim()));
+            if (repositories.size === 1 && issues.size === 1) {
+                result.known++;
+                result.workItems.add(JSON.stringify([[...repositories][0], [...issues][0], name]));
+            }
+            else if (repositories.size > 1 || issues.size > 1) {
+                result.conflicts++;
+            }
+            // Modern executions require explicit completion; legacy mentoring fallback
+            // requires a complete status and an explicitly terminal nextPhase.
+            const completedAt = execution.completeTime || (estimated ? execution.legacyCompleteTime : null);
+            if (completedAt) {
+                result.completed++;
+                const startedAt = execution.startTime || execution.firstEventTime;
+                const duration = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+                if (duration >= 0)
+                    result.durations.push(duration);
+            }
+        }
+        return [...grouped].map(([name, result]) => {
+            const durations = result.durations.sort((a, b) => a - b);
+            const notes = [];
+            if (result.legacy)
+                notes.push(`${result.legacy} legacy execution identities are estimates; historical reloads cannot be distinguished reliably.`);
+            if (result.count > result.known)
+                notes.push(`${result.count - result.known} executions have unknown work-item identity; unique work items count only known identities.`);
+            if (result.conflicts)
+                notes.push(`${result.conflicts} executions have conflicting work-item metadata and are counted as unknown.`);
+            const completionRate = result.completed / result.count;
             return {
-                jobName: result.jobName,
-                totalRequested: result.totalStarted,
-                totalStarted: result.totalStarted,
-                totalCompleted: result.totalCompleted,
-                totalAbandoned: result.totalStarted - result.totalCompleted,
+                jobName: name,
+                executionCount: result.count,
+                uniqueWorkItemCount: result.workItems.size,
+                executionsWithKnownWorkItem: result.known,
+                executionsWithUnknownWorkItem: result.count - result.known,
+                legacyAmbiguousExecutionCount: result.legacy,
+                identityNote: notes.length ? notes.join(' ') : null,
+                totalRequested: result.count,
+                totalStarted: result.count,
+                totalCompleted: result.completed,
+                totalAbandoned: result.count - result.completed,
                 startRate: 1.0,
-                completionRate: result.completionRate,
-                overallRate: result.completionRate,
-                averageCompletionTime: result.avgCompletionMs ?? undefined,
-                medianCompletionTime: medianMs,
+                completionRate,
+                overallRate: completionRate,
+                averageCompletionTime: durations.length ? durations.reduce((sum, duration) => sum + duration, 0) / durations.length : undefined,
+                medianCompletionTime: durations.length ? durations[Math.floor(durations.length / 2)] : undefined,
                 commonAbandonmentPhases: [],
-                timeRange: { start: startDate, end: new Date() }
+                timeRange: { start: startDate, end: endDate || new Date() }
             };
         });
     }