@critical-path/core 0.19.1 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@critical-path/core",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Core headless domain engine, plugin architecture, and data stores for Critical Path",
   "author": "Jack James",
   "license": "MIT",

package/src/domain/calendar.test.ts

@@ -9,7 +9,8 @@ import {
   getWorkingHoursBetween,
   getWorkingDaysBetween,
   getWorkingDaysList,
-  getNetAvailableCapacity
+  getNetAvailableCapacity,
+  formatTaskDuration
 } from './calendar.js';
 import type { WorkSchedule } from '../types/index.js';
 
@@ -161,4 +162,55 @@ describe('Calendar and Work Schedule Domain', () => {
       expect(cap).toBe(16);
     });
   });
+
+  describe('formatTaskDuration', () => {
+    it('handles null, undefined, NaN, and negative values', () => {
+      expect(formatTaskDuration(null)).toBe('0s');
+      expect(formatTaskDuration(undefined)).toBe('0s');
+      expect(formatTaskDuration(NaN)).toBe('0s');
+      expect(formatTaskDuration(-5)).toBe('0s');
+      expect(formatTaskDuration(0)).toBe('0s');
+    });
+
+    it('formats short durations under 120s with seconds', () => {
+      expect(formatTaskDuration(45)).toBe('45s');
+      expect(formatTaskDuration(110.3)).toBe('110.3s');
+      expect(formatTaskDuration(119.9)).toBe('119.9s');
+      expect(formatTaskDuration(1.5)).toBe('1.5s');
+    });
+
+    it('formats sub-day durations with hours and minutes', () => {
+      // 44 minutes = 2640s
+      expect(formatTaskDuration(2640)).toBe('0h 44m');
+      // 2h 15m = 8100s
+      expect(formatTaskDuration(8100)).toBe('2h 15m');
+      // 7h 59m = 28740s (< 8h working day)
+      expect(formatTaskDuration(28740)).toBe('7h 59m');
+    });
+
+    it('formats multi-day durations using default 8h working days', () => {
+      // 8 hours = 28800s -> 1 day
+      expect(formatTaskDuration(28800)).toBe('1 day');
+      // 12 hours = 43200s -> 1.5 days
+      expect(formatTaskDuration(43200)).toBe('1.5 days');
+      // 25.6 hours = 92160s -> 3.2 days
+      expect(formatTaskDuration(92160)).toBe('3.2 days');
+    });
+
+    it('supports calendar_days basis (24h per day)', () => {
+      // 12 hours on calendar days basis -> 12h 0m (< 24h)
+      expect(formatTaskDuration(43200, { dayBasis: 'calendar_days' })).toBe('12h 0m');
+      // 36 hours on calendar days basis -> 1.5 days
+      expect(formatTaskDuration(129600, { dayBasis: 'calendar_days' })).toBe('1.5 days');
+    });
+
+    it('supports custom work schedules', () => {
+      const fourHourDaySchedule: WorkSchedule = {
+        ...DEFAULT_WORK_SCHEDULE,
+        defaultHoursPerDay: 4
+      };
+      // 6 hours with 4h/day schedule = 1.5 days
+      expect(formatTaskDuration(21600, { schedule: fourHourDaySchedule })).toBe('1.5 days');
+    });
+  });
 });

package/src/domain/calendar.ts

@@ -455,3 +455,48 @@ export function getNetAvailableCapacity(
 
   return Math.round(totalCapacity * 100) / 100;
 }
+
+export interface FormatDurationOptions {
+  /** Optional custom work schedule to determine working hours in a day */
+  schedule?: WorkSchedule;
+  /** 'working_days' uses schedule.defaultHoursPerDay (default 8h). 'calendar_days' uses 24h. Default: 'working_days' */
+  dayBasis?: 'working_days' | 'calendar_days';
+}
+
+/**
+ * Formats task execution duration dynamically based on magnitude:
+ * - < 120s: Seconds with 1 decimal place (e.g. '110.3s', '45s')
+ * - < 1 day (based on dayBasis): Hours and minutes (e.g. '0h 44m', '2h 15m')
+ * - >= 1 day: Days with 1 decimal place (e.g. '1.5 days', '3.2 days')
+ */
+export function formatTaskDuration(
+  durationSeconds: number | null | undefined,
+  options?: FormatDurationOptions
+): string {
+  if (durationSeconds === null || durationSeconds === undefined || isNaN(durationSeconds) || durationSeconds <= 0) {
+    return '0s';
+  }
+
+  // Under 120 seconds: return seconds with 1 decimal place (or whole if integer)
+  if (durationSeconds < 120) {
+    const formatted = durationSeconds.toFixed(1);
+    return `${formatted.endsWith('.0') ? formatted.slice(0, -2) : formatted}s`;
+  }
+
+  const hoursPerDay = options?.dayBasis === 'calendar_days'
+    ? 24
+    : (options?.schedule?.defaultHoursPerDay || DEFAULT_WORK_SCHEDULE.defaultHoursPerDay || 8);
+
+  const totalHours = durationSeconds / 3600;
+  if (totalHours >= hoursPerDay) {
+    const days = totalHours / hoursPerDay;
+    const formatted = days.toFixed(1);
+    const cleanDays = formatted.endsWith('.0') ? formatted.slice(0, -2) : formatted;
+    return `${cleanDays} ${cleanDays === '1' ? 'day' : 'days'}`;
+  }
+
+  const hours = Math.floor(totalHours);
+  const minutes = Math.floor((durationSeconds % 3600) / 60);
+  return `${hours}h ${minutes}m`;
+}
+

package/src/domain/entities.ts

@@ -87,6 +87,8 @@ export class TaskEntity extends BaseEntity {
   public estimatedDurationMinutes?: number;
   public actualDurationMinutes?: number;
   public billableDurationMinutes?: number;
+  public actualDurationSeconds?: number;
+  public inProgressSince?: string | null;
   public progress?: number;
   public tags?: string[];
   public todos?: TaskTodoItem[];
@@ -121,6 +123,8 @@ export class TaskEntity extends BaseEntity {
     this.estimatedDurationMinutes = data.estimatedDurationMinutes;
     this.actualDurationMinutes = data.actualDurationMinutes;
     this.billableDurationMinutes = data.billableDurationMinutes;
+    this.actualDurationSeconds = data.actualDurationSeconds;
+    this.inProgressSince = data.inProgressSince;
     this.progress = data.progress ?? 0;
     this.tags = data.tags ? [...data.tags] : [];
     this.todos = data.todos ? data.todos.map((t) => ({ ...t })) : [];
@@ -141,6 +145,10 @@ export class TaskEntity extends BaseEntity {
 
     const status = input.status || options?.workflow?.defaultStatusKey || 'todo';
     const statusDef = resolveStatusDefinition(status, options?.workflow?.statuses);
+    const semanticStatus = input.semanticStatus || statusDef.category;
+    const actualStartDate = input.actualStartDate ?? (semanticStatus === 'in_progress' ? now : undefined);
+    const inProgressSince = input.inProgressSince ?? (semanticStatus === 'in_progress' ? now : undefined);
+    const actualEndDate = input.actualEndDate ?? ((semanticStatus === 'completed' || semanticStatus === 'canceled') ? now : undefined);
 
     const task = new TaskEntity({
       ...input,
@@ -148,7 +156,11 @@ export class TaskEntity extends BaseEntity {
       createdAt: now,
       updatedAt: now,
       status,
-      semanticStatus: input.semanticStatus || statusDef.category,
+      semanticStatus,
+      actualStartDate,
+      inProgressSince,
+      actualEndDate,
+      actualDurationSeconds: input.actualDurationSeconds,
       priority: input.priority || 'medium',
       loggedHours: input.loggedHours ?? 0,
       progress: input.progress ?? 0,
@@ -190,16 +202,45 @@ export class TaskEntity extends BaseEntity {
     this.semanticStatus = statusDef.category;
 
     const prevStatusDef = resolveStatusDefinition(previousStatus, options?.statusDefs || workflow?.statuses);
-    if ((prevStatusDef.category === 'completed' || prevStatusDef.category === 'canceled') &&
-        (statusDef.category === 'in_progress' || statusDef.category === 'not_started')) {
-      this.actualEndDate = undefined;
+
+    // 1. Leaving in_progress: finalize current session duration
+    if (prevStatusDef.category === 'in_progress' && statusDef.category !== 'in_progress') {
+      if (this.inProgressSince) {
+        const startMs = new Date(this.inProgressSince).getTime();
+        const endMs = new Date(now).getTime();
+        if (!isNaN(startMs) && !isNaN(endMs) && endMs >= startMs) {
+          const sessionSeconds = Math.max(0, (endMs - startMs) / 1000);
+          this.actualDurationSeconds = (this.actualDurationSeconds || 0) + sessionSeconds;
+          this.actualHours = Math.round(((this.actualDurationSeconds || 0) / 3600) * 100) / 100;
+          this.actualDurationMinutes = Math.round((this.actualDurationSeconds || 0) / 60);
+        }
+        this.inProgressSince = null;
+      }
     }
 
-    if (statusDef.category === 'in_progress' && !this.actualStartDate) {
-      this.actualStartDate = now;
+    // 2. Entering in_progress: retain earliest start date & start session timer
+    if (statusDef.category === 'in_progress') {
+      if (!this.actualStartDate) {
+        this.actualStartDate = now;
+      }
+      if (!this.inProgressSince) {
+        this.inProgressSince = now;
+      }
+      if (prevStatusDef.category === 'completed' || prevStatusDef.category === 'canceled') {
+        this.actualEndDate = undefined;
+      }
+    } else if (
+      (prevStatusDef.category === 'completed' || prevStatusDef.category === 'canceled') &&
+      statusDef.category === 'not_started'
+    ) {
+      this.actualEndDate = undefined;
     }
+
+    // 3. Entering completed or canceled
     if (statusDef.category === 'completed' || statusDef.category === 'canceled') {
-      this.actualEndDate = now;
+      if (!this.actualEndDate) {
+        this.actualEndDate = now;
+      }
       if (statusDef.category === 'completed' && this.progress !== undefined && this.progress < 100) {
         this.progress = 100;
       }
@@ -354,6 +395,13 @@ export class TaskEntity extends BaseEntity {
     }
 
     Object.assign(this, updates);
+    if (updates.actualDurationSeconds !== undefined && updates.actualHours === undefined) {
+      this.actualHours = Math.round((updates.actualDurationSeconds / 3600) * 100) / 100;
+      this.actualDurationMinutes = updates.actualDurationMinutes ?? Math.round(updates.actualDurationSeconds / 60);
+    } else if (updates.actualHours !== undefined && updates.actualDurationSeconds === undefined) {
+      this.actualDurationSeconds = Math.round(updates.actualHours * 3600);
+      this.actualDurationMinutes = updates.actualDurationMinutes ?? Math.round(updates.actualHours * 60);
+    }
     this.markUpdated();
 
     const event: TaskUpdatedEvent = {
@@ -401,6 +449,8 @@ export class TaskEntity extends BaseEntity {
       estimatedDurationMinutes: this.estimatedDurationMinutes,
       actualDurationMinutes: this.actualDurationMinutes,
       billableDurationMinutes: this.billableDurationMinutes,
+      actualDurationSeconds: this.actualDurationSeconds,
+      inProgressSince: this.inProgressSince,
       progress: this.progress,
       tags: this.tags ? [...this.tags] : [],
       todos: this.todos ? this.todos.map((t) => ({ ...t })) : [],

package/src/domain/metrics.ts

@@ -453,20 +453,32 @@ export function calculateTaskMetrics(
 
   // Compute Inferred Actuals
   let activeWorkingHours: number | undefined;
+  let calendarDurationHours: number | undefined;
+
   if (task.actualStartDate && task.actualEndDate) {
     const startMs = new Date(task.actualStartDate).getTime();
     const endMs = new Date(task.actualEndDate).getTime();
     if (!isNaN(startMs) && !isNaN(endMs) && endMs >= startMs) {
-      activeWorkingHours = Math.round(((endMs - startMs) / (1000 * 60 * 60)) * 100) / 100;
+      calendarDurationHours = Math.round(((endMs - startMs) / (1000 * 60 * 60)) * 100) / 100;
     }
   }
 
+  if (task.actualDurationSeconds !== undefined) {
+    activeWorkingHours = Math.round((task.actualDurationSeconds / 3600) * 100) / 100;
+  } else if (task.actualHours !== undefined) {
+    activeWorkingHours = task.actualHours;
+  } else {
+    activeWorkingHours = calendarDurationHours;
+  }
+
   const inferredActuals: TaskInferredActuals = {
     actualStartDate: task.actualStartDate,
     actualEndDate: task.actualEndDate,
     isStartDateInferred: Boolean(task.actualStartDate && !task.plannedStartDate),
     isEndDateInferred: Boolean(task.actualEndDate && task.semanticStatus === 'completed'),
-    activeWorkingHours
+    activeWorkingHours,
+    calendarDurationHours,
+    actualDurationSeconds: task.actualDurationSeconds
   };
 
   const progress = inferTaskProgress(task, options);

package/src/domain/task-duration.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect, vi } from 'vitest';
+import { TaskEntity } from './entities.js';
+import { CriticalPathEngine } from '../engine/index.js';
+import { InMemoryStore } from '../store/index.js';
+import { DEFAULT_SOFTWARE_WORKFLOW } from '../utils/workflow.js';
+
+describe('Task Execution Timestamps & Cumulative In-Progress Duration', () => {
+  it('stamps actualStartDate and inProgressSince when moving to in_progress', () => {
+    const task = TaskEntity.create({
+      projectId: 'proj_1',
+      title: 'Implement Task Timestamps',
+      status: 'todo'
+    });
+
+    expect(task.actualStartDate).toBeUndefined();
+    expect(task.actualEndDate).toBeUndefined();
+    expect(task.inProgressSince).toBeUndefined();
+    expect(task.actualDurationSeconds).toBeUndefined();
+
+    task.transitionTo('in_progress', DEFAULT_SOFTWARE_WORKFLOW);
+
+    expect(task.actualStartDate).toBeDefined();
+    expect(task.inProgressSince).toBeDefined();
+    expect(task.actualEndDate).toBeUndefined();
+  });
+
+  it('accumulates in-progress duration across pause/resume cycles and retains earliest actualStartDate', async () => {
+    vi.useFakeTimers();
+    try {
+      const now = new Date('2026-09-23T10:00:00Z');
+      vi.setSystemTime(now);
+
+      const task = TaskEntity.create({
+        projectId: 'proj_1',
+        title: 'Work Tracking',
+        status: 'todo'
+      });
+
+      // 1. Start working at 10:00
+      task.transitionTo('in_progress', DEFAULT_SOFTWARE_WORKFLOW);
+      const initialStartDate = task.actualStartDate;
+      expect(initialStartDate).toBe(now.toISOString());
+      expect(task.inProgressSince).toBe(now.toISOString());
+
+      // Fast-forward 30 minutes (1800s)
+      vi.setSystemTime(new Date('2026-09-23T10:30:00Z'));
+
+      // 2. Pause: move to todo
+      task.transitionTo('todo', DEFAULT_SOFTWARE_WORKFLOW);
+      expect(task.inProgressSince).toBeNull();
+      expect(task.actualDurationSeconds).toBe(1800);
+      expect(task.actualHours).toBe(0.5);
+      expect(task.actualDurationMinutes).toBe(30);
+      expect(task.actualStartDate).toBe(initialStartDate); // Retains earliest
+
+      // Paused for 1 hour
+      vi.setSystemTime(new Date('2026-09-23T11:30:00Z'));
+
+      // 3. Resume: move back to in_progress
+      task.transitionTo('in_progress', DEFAULT_SOFTWARE_WORKFLOW);
+      expect(task.actualStartDate).toBe(initialStartDate); // Still retains earliest
+      expect(task.inProgressSince).toBe(new Date('2026-09-23T11:30:00Z').toISOString());
+      expect(task.actualDurationSeconds).toBe(1800); // Unchanged until leaving
+
+      // Fast-forward another 45 minutes (2700s)
+      vi.setSystemTime(new Date('2026-09-23T12:15:00Z'));
+
+      // 4. Complete: move to done
+      task.transitionTo('done', DEFAULT_SOFTWARE_WORKFLOW);
+      expect(task.inProgressSince).toBeNull();
+      // Total duration = 1800s + 2700s = 4500s = 1.25h
+      expect(task.actualDurationSeconds).toBe(4500);
+      expect(task.actualHours).toBe(1.25);
+      expect(task.actualDurationMinutes).toBe(75);
+      expect(task.actualStartDate).toBe(initialStartDate);
+      expect(task.actualEndDate).toBe(new Date('2026-09-23T12:15:00Z').toISOString());
+      expect(task.progress).toBe(100);
+
+      // 5. Reopen: move from done to todo, then to in_progress
+      vi.setSystemTime(new Date('2026-09-23T14:00:00Z'));
+      task.transitionTo('todo', DEFAULT_SOFTWARE_WORKFLOW);
+      expect(task.actualEndDate).toBeUndefined(); // Reset upon reopen
+      expect(task.actualStartDate).toBe(initialStartDate); // Retains earliest
+
+      vi.setSystemTime(new Date('2026-09-23T14:15:00Z'));
+      task.transitionTo('in_progress', DEFAULT_SOFTWARE_WORKFLOW);
+      expect(task.actualEndDate).toBeUndefined();
+      expect(task.actualStartDate).toBe(initialStartDate); // Retains earliest
+      expect(task.inProgressSince).toBe(new Date('2026-09-23T14:15:00Z').toISOString());
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('keeps actualDurationSeconds and actualHours synchronized on manual updates', () => {
+    const task = TaskEntity.create({
+      projectId: 'proj_1',
+      title: 'Manual Adjustments',
+      status: 'todo'
+    });
+
+    // Update actualDurationSeconds directly
+    task.update({ actualDurationSeconds: 7200 });
+    expect(task.actualHours).toBe(2);
+    expect(task.actualDurationMinutes).toBe(120);
+
+    // Update actualHours directly
+    task.update({ actualHours: 1.5 });
+    expect(task.actualDurationSeconds).toBe(5400);
+    expect(task.actualDurationMinutes).toBe(90);
+  });
+
+  it('integrates with CriticalPathEngine updateTask and metrics calculation', async () => {
+    vi.useFakeTimers();
+    try {
+      const store = new InMemoryStore();
+      const engine = new CriticalPathEngine({ store });
+
+      const project = await engine.createProject({ name: 'Engine Duration Test' });
+
+      vi.setSystemTime(new Date('2026-09-23T09:00:00Z'));
+      const task = await engine.createTask({
+        projectId: project.id,
+        title: 'Build Feature',
+        estimatedHours: 8
+      });
+
+      // 1. Move to in_progress
+      const started = await engine.updateTask(task.id, { status: 'in_progress' });
+      expect(started?.actualStartDate).toBe('2026-09-23T09:00:00.000Z');
+      expect(started?.inProgressSince).toBe('2026-09-23T09:00:00.000Z');
+      expect(started?.actualEndDate).toBeUndefined();
+
+      // 2. Work for 2 hours (7200s), then move to todo (pause)
+      vi.setSystemTime(new Date('2026-09-23T11:00:00Z'));
+      const paused = await engine.updateTask(task.id, { status: 'todo' });
+      expect(paused?.inProgressSince).toBeNull();
+      expect(paused?.actualDurationSeconds).toBe(7200);
+      expect(paused?.actualHours).toBe(2);
+
+      // 3. Complete task at 14:00 (move from todo to done)
+      vi.setSystemTime(new Date('2026-09-23T14:00:00Z'));
+      const completed = await engine.updateTask(task.id, { status: 'done' });
+      expect(completed?.actualEndDate).toBe('2026-09-23T14:00:00.000Z');
+      // in-progress duration should still be 7200s (since time in todo was paused)
+      expect(completed?.actualDurationSeconds).toBe(7200);
+
+      // 4. Verify metrics calculation
+      const metrics = await engine.getTaskMetrics(task.id);
+      expect(metrics?.inferredActuals.actualDurationSeconds).toBe(7200);
+      expect(metrics?.inferredActuals.activeWorkingHours).toBe(2);
+      // Calendar duration: 09:00 to 14:00 = 5.0 hours
+      expect(metrics?.inferredActuals.calendarDurationHours).toBe(5);
+
+      // 5. Reopen task (done -> todo -> in_progress): actualEndDate must be cleared (undefined)
+      vi.setSystemTime(new Date('2026-09-23T15:00:00Z'));
+      const reopenedTodo = await engine.updateTask(task.id, { status: 'todo' });
+      expect(reopenedTodo?.actualEndDate).toBeUndefined();
+
+      vi.setSystemTime(new Date('2026-09-23T15:30:00Z'));
+      const reopenedProgress = await engine.updateTask(task.id, { status: 'in_progress' });
+      expect(reopenedProgress?.actualEndDate).toBeUndefined();
+      expect(reopenedProgress?.actualStartDate).toBe('2026-09-23T09:00:00.000Z'); // Earliest preserved
+      expect(reopenedProgress?.inProgressSince).toBe('2026-09-23T15:30:00.000Z');
+      expect(reopenedProgress?.actualDurationSeconds).toBe(7200);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/engine/index.ts

@@ -371,6 +371,7 @@ export class CriticalPathEngine {
     const statusDef = resolveStatusDefinition(initialStatus, project?.statusDefinitions || workflow?.statuses);
     const semanticStatus = processedInput.semanticStatus ?? taskInput.semanticStatus ?? statusDef.category;
     const actualStartDate = processedInput.actualStartDate ?? taskInput.actualStartDate ?? (statusDef.category === 'in_progress' ? now : undefined);
+    const inProgressSince = processedInput.inProgressSince ?? taskInput.inProgressSince ?? (statusDef.category === 'in_progress' ? now : undefined);
     const actualEndDate = processedInput.actualEndDate ?? taskInput.actualEndDate ?? ((statusDef.category === 'completed' || statusDef.category === 'canceled') ? now : undefined);
 
     const created = await this.store.createTask({
@@ -400,6 +401,8 @@ export class CriticalPathEngine {
       estimatedDurationMinutes: processedInput.estimatedDurationMinutes ?? taskInput.estimatedDurationMinutes,
       actualDurationMinutes: processedInput.actualDurationMinutes ?? taskInput.actualDurationMinutes,
       billableDurationMinutes: processedInput.billableDurationMinutes ?? taskInput.billableDurationMinutes,
+      actualDurationSeconds: processedInput.actualDurationSeconds ?? taskInput.actualDurationSeconds,
+      inProgressSince,
       progress: processedInput.progress ?? taskInput.progress ?? (statusDef.category === 'completed' ? 100 : 0),
       tags: processedInput.tags ?? taskInput.tags ?? [],
       customFields: processedInput.customFields ?? taskInput.customFields ?? {},
@@ -515,17 +518,51 @@ export class CriticalPathEngine {
         existing.status,
         project?.statusDefinitions || workflow?.statuses
       );
-      if (
+
+      // 1. Leaving in_progress: finalize active session duration
+      if (existingStatusDef.category === 'in_progress' && statusDef.category !== 'in_progress') {
+        const inProgressSince = existing.inProgressSince;
+        if (inProgressSince) {
+          const startMs = new Date(inProgressSince).getTime();
+          const endMs = new Date(now).getTime();
+          if (!isNaN(startMs) && !isNaN(endMs) && endMs >= startMs) {
+            const sessionSeconds = Math.max(0, (endMs - startMs) / 1000);
+            processedUpdates.actualDurationSeconds =
+              (processedUpdates.actualDurationSeconds ?? existing.actualDurationSeconds ?? 0) + sessionSeconds;
+            if (processedUpdates.actualHours === undefined) {
+              processedUpdates.actualHours = Math.round((processedUpdates.actualDurationSeconds / 3600) * 100) / 100;
+            }
+            if (processedUpdates.actualDurationMinutes === undefined) {
+              processedUpdates.actualDurationMinutes = Math.round(processedUpdates.actualDurationSeconds / 60);
+            }
+          }
+          processedUpdates.inProgressSince = null;
+        }
+      }
+
+      // 2. Entering in_progress: retain earliest start date & start session timer
+      if (statusDef.category === 'in_progress') {
+        if (!existing.actualStartDate && !processedUpdates.actualStartDate) {
+          processedUpdates.actualStartDate = now;
+        }
+        if (!processedUpdates.inProgressSince) {
+          processedUpdates.inProgressSince = now;
+        }
+        if (
+          (existingStatusDef.category === 'completed' || existingStatusDef.category === 'canceled') &&
+          processedUpdates.actualEndDate === undefined
+        ) {
+          processedUpdates.actualEndDate = undefined;
+        }
+      } else if (
         (existingStatusDef.category === 'completed' || existingStatusDef.category === 'canceled') &&
-        (statusDef.category === 'in_progress' || statusDef.category === 'not_started') &&
+        statusDef.category === 'not_started' &&
         processedUpdates.actualEndDate === undefined
       ) {
         processedUpdates.actualEndDate = undefined;
       }
 
-      if (statusDef.category === 'in_progress' && !existing.actualStartDate && !processedUpdates.actualStartDate) {
-        processedUpdates.actualStartDate = now;
-      }
+      // 3. Entering completed or canceled
       if ((statusDef.category === 'completed' || statusDef.category === 'canceled') && !processedUpdates.actualEndDate) {
         processedUpdates.actualEndDate = now;
         if (statusDef.category === 'completed' && processedUpdates.progress === undefined && (existing.progress || 0) < 100) {
@@ -534,6 +571,19 @@ export class CriticalPathEngine {
       }
     }
 
+    // Mutual sync for manual duration/effort edits
+    if (processedUpdates.actualDurationSeconds !== undefined && processedUpdates.actualHours === undefined) {
+      processedUpdates.actualHours = Math.round((processedUpdates.actualDurationSeconds / 3600) * 100) / 100;
+      if (processedUpdates.actualDurationMinutes === undefined) {
+        processedUpdates.actualDurationMinutes = Math.round(processedUpdates.actualDurationSeconds / 60);
+      }
+    } else if (processedUpdates.actualHours !== undefined && processedUpdates.actualDurationSeconds === undefined) {
+      processedUpdates.actualDurationSeconds = Math.round(processedUpdates.actualHours * 3600);
+      if (processedUpdates.actualDurationMinutes === undefined) {
+        processedUpdates.actualDurationMinutes = Math.round(processedUpdates.actualHours * 60);
+      }
+    }
+
     const updated = await this.store.updateTask(id, processedUpdates);
     if (!updated) return null;
 

package/src/store/sqlite.ts

@@ -131,6 +131,8 @@ export class SQLiteStore implements StorageAdapter {
         estimatedDurationMinutes REAL,
         actualDurationMinutes REAL,
         billableDurationMinutes REAL,
+        actualDurationSeconds REAL,
+        inProgressSince TEXT,
         progress REAL,
         isBlocked INTEGER,
         blockedReason TEXT,
@@ -660,10 +662,11 @@ export class SQLiteStore implements StorageAdapter {
         id, projectId, title, description, status, priority, taskType, assigneeId, assignees, reporterId,
         reviewerId, iterationId, teamId, containerId, deliverableId, plannedStartDate, actualStartDate, actualEndDate,
         dueDate, estimatedHours, loggedHours, actualHours, billableHours,
-        estimatedDurationMinutes, actualDurationMinutes, billableDurationMinutes, progress,
+        estimatedDurationMinutes, actualDurationMinutes, billableDurationMinutes,
+        actualDurationSeconds, inProgressSince, progress,
         isBlocked, blockedReason,
         tags, customFields, parentId, createdAt, updatedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newTask.id,
@@ -692,6 +695,8 @@ export class SQLiteStore implements StorageAdapter {
       newTask.estimatedDurationMinutes ?? null,
       newTask.actualDurationMinutes ?? null,
       newTask.billableDurationMinutes ?? null,
+      newTask.actualDurationSeconds ?? null,
+      newTask.inProgressSince ?? null,
       newTask.progress ?? null,
       newTask.isBlocked !== undefined ? (newTask.isBlocked ? 1 : 0) : null,
       newTask.blockedReason ?? null,
@@ -720,7 +725,8 @@ export class SQLiteStore implements StorageAdapter {
         assigneeId = ?, assignees = ?, reporterId = ?, reviewerId = ?, iterationId = ?, teamId = ?, containerId = ?, deliverableId = ?,
         plannedStartDate = ?, actualStartDate = ?, actualEndDate = ?, dueDate = ?,
         estimatedHours = ?, loggedHours = ?, actualHours = ?, billableHours = ?,
-        estimatedDurationMinutes = ?, actualDurationMinutes = ?, billableDurationMinutes = ?, progress = ?,
+        estimatedDurationMinutes = ?, actualDurationMinutes = ?, billableDurationMinutes = ?,
+        actualDurationSeconds = ?, inProgressSince = ?, progress = ?,
         isBlocked = ?, blockedReason = ?,
         tags = ?, customFields = ?, parentId = ?, updatedAt = ?
       WHERE id = ?
@@ -751,6 +757,8 @@ export class SQLiteStore implements StorageAdapter {
       updated.estimatedDurationMinutes ?? null,
       updated.actualDurationMinutes ?? null,
       updated.billableDurationMinutes ?? null,
+      updated.actualDurationSeconds ?? null,
+      updated.inProgressSince ?? null,
       updated.progress ?? null,
       updated.isBlocked !== undefined ? (updated.isBlocked ? 1 : 0) : null,
       updated.blockedReason ?? null,

package/src/types/index.ts

@@ -214,6 +214,10 @@ export interface Task {
   estimatedDurationMinutes?: number;
   actualDurationMinutes?: number;
   billableDurationMinutes?: number;
+  /** Cumulative active execution time spent in 'in_progress' status (in seconds) */
+  actualDurationSeconds?: number;
+  /** Transient ISO timestamp marking the start of current 'in_progress' session (null when not in_progress) */
+  inProgressSince?: string | null;
   // Progress (0 to 100 percentage)
   progress?: number;
   isBlocked?: boolean;
@@ -626,6 +630,10 @@ export interface TaskInferredActuals {
   isStartDateInferred: boolean;
   isEndDateInferred: boolean;
   activeWorkingHours?: number;
+  /** Calendar elapsed hours between actualStartDate and actualEndDate */
+  calendarDurationHours?: number;
+  /** Cumulative active execution duration in seconds */
+  actualDurationSeconds?: number;
 }
 
 export interface TaskMetrics {

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}
+{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}