forge-openclaw-plugin 0.2.15 → 0.2.19

package/dist/server/repositories/rewards.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { getDatabase } from "../db.js";
 import { recordEventLog } from "./event-log.js";
-import { createManualRewardGrantSchema, rewardLedgerEventSchema, rewardRuleSchema, sessionEventSchema, updateRewardRuleSchema } from "../types.js";
+import { createManualRewardGrantSchema, workAdjustmentEntityTypeSchema, rewardLedgerEventSchema, rewardRuleSchema, sessionEventSchema, updateRewardRuleSchema } from "../types.js";
 const DEFAULT_RULES = [
     {
         id: "reward_rule_task_completion",
@@ -43,6 +43,22 @@ const DEFAULT_RULES = [
         description: "Reward a concrete decision to apply a useful insight.",
         config: { fixedXp: 15 }
     },
+    {
+        id: "reward_rule_habit_aligned",
+        family: "consistency",
+        code: "habit_aligned",
+        title: "Habit alignment",
+        description: "Award XP when a habit outcome matches the intended direction.",
+        config: { award: "habit.rewardXp" }
+    },
+    {
+        id: "reward_rule_habit_misaligned",
+        family: "recovery",
+        code: "habit_misaligned",
+        title: "Habit miss",
+        description: "Apply a small XP penalty when a habit outcome moves against the intended direction.",
+        config: { penalty: "habit.penaltyXp" }
+    },
     {
         id: "reward_rule_psyche_reflection_capture",
         family: "alignment",
@@ -91,6 +107,14 @@ const DEFAULT_RULES = [
         description: "Reward giving a recurring mode enough shape to recognize it later.",
         config: { fixedXp: 4 }
     },
+    {
+        id: "reward_rule_weekly_review_completed",
+        family: "alignment",
+        code: "weekly_review_completed",
+        title: "Weekly review completed",
+        description: "Reward closing the current weekly review cycle and turning it into explicit evidence.",
+        config: { fixedXp: 250 }
+    },
     {
         id: "reward_rule_session_dwell",
         family: "ambient",
@@ -178,6 +202,17 @@ export function getRewardRuleById(ruleId) {
 function getRuleByCode(code) {
     return listRewardRules().find((rule) => rule.code === code);
 }
+export function getTaskRunProgressRewardCadence() {
+    ensureDefaultRewardRules();
+    const rule = getRuleByCode("task_run_progress");
+    const intervalMinutes = Math.max(1, Number(rule?.config.intervalMinutes ?? 10));
+    return {
+        rule,
+        intervalMinutes,
+        intervalSeconds: intervalMinutes * 60,
+        fixedXp: Number(rule?.config.fixedXp ?? 4)
+    };
+}
 export function updateRewardRule(ruleId, input, activity) {
     ensureDefaultRewardRules();
     const current = getRewardRuleById(ruleId);
@@ -263,6 +298,17 @@ export function listRewardLedger(filters = {}) {
         .all(...params);
     return rows.map(mapLedger);
 }
+export function getRewardLedgerEventById(rewardId) {
+    ensureDefaultRewardRules();
+    const row = getDatabase()
+        .prepare(`SELECT
+         id, rule_id, event_log_id, entity_type, entity_id, actor, source, delta_xp, reason_title, reason_summary,
+         reversible_group, reversed_by_reward_id, metadata_json, created_at
+       FROM reward_ledger
+       WHERE id = ?`)
+        .get(rewardId);
+    return row ? mapLedger(row) : null;
+}
 export function getTotalXp() {
     ensureDefaultRewardRules();
     const row = getDatabase().prepare(`SELECT COALESCE(SUM(delta_xp), 0) AS total FROM reward_ledger`).get();
@@ -521,11 +567,7 @@ export function recordTaskRunStartReward(taskRunId, taskId, actor, source) {
     });
 }
 export function recordTaskRunProgressRewards(taskRunId, taskId, actor, source, creditedSeconds) {
-    ensureDefaultRewardRules();
-    const rule = getRuleByCode("task_run_progress");
-    const intervalMinutes = Math.max(1, Number(rule?.config.intervalMinutes ?? 10));
-    const intervalSeconds = intervalMinutes * 60;
-    const fixedXp = Number(rule?.config.fixedXp ?? 4);
+    const { rule, intervalMinutes, intervalSeconds, fixedXp } = getTaskRunProgressRewardCadence();
     const earnedBuckets = Math.floor(Math.max(0, creditedSeconds) / intervalSeconds);
     if (earnedBuckets <= 0) {
         return [];
@@ -577,6 +619,55 @@ export function recordTaskRunProgressRewards(taskRunId, taskId, actor, source, c
     }
     return rewards;
 }
+export function recordWorkAdjustmentReward(input) {
+    const { rule, intervalMinutes, intervalSeconds, fixedXp } = getTaskRunProgressRewardCadence();
+    const entityType = workAdjustmentEntityTypeSchema.parse(input.entityType);
+    const previousBuckets = Math.floor(Math.max(0, input.previousCreditedSeconds) / intervalSeconds);
+    const nextBuckets = Math.floor(Math.max(0, input.nextCreditedSeconds) / intervalSeconds);
+    const bucketDelta = nextBuckets - previousBuckets;
+    if (bucketDelta === 0) {
+        return null;
+    }
+    const deltaXp = bucketDelta * fixedXp;
+    const direction = bucketDelta > 0 ? "added" : "removed";
+    const appliedMinutes = Math.abs(input.appliedDeltaMinutes);
+    const eventLog = recordEventLog({
+        eventKind: "reward.work_adjustment",
+        entityType,
+        entityId: input.entityId,
+        actor: input.actor ?? null,
+        source: input.source,
+        metadata: {
+            adjustmentId: input.adjustmentId,
+            requestedDeltaMinutes: input.requestedDeltaMinutes,
+            appliedDeltaMinutes: input.appliedDeltaMinutes,
+            bucketDelta,
+            deltaXp
+        }
+    });
+    return insertLedgerEvent({
+        ruleId: rule?.id ?? null,
+        eventLogId: eventLog.id,
+        entityType,
+        entityId: input.entityId,
+        actor: input.actor ?? null,
+        source: input.source,
+        deltaXp,
+        reasonTitle: bucketDelta > 0 ? "Manual work minutes added" : "Manual work minutes removed",
+        reasonSummary: `${appliedMinutes} manual minute${appliedMinutes === 1 ? "" : "s"} ${direction}, shifting ${Math.abs(bucketDelta)} ${intervalMinutes}-minute reward bucket${Math.abs(bucketDelta) === 1 ? "" : "s"} for ${input.targetTitle}.`,
+        reversibleGroup: `work_adjustment:${entityType}:${input.entityId}:${input.adjustmentId}`,
+        metadata: {
+            adjustmentId: input.adjustmentId,
+            requestedDeltaMinutes: input.requestedDeltaMinutes,
+            appliedDeltaMinutes: input.appliedDeltaMinutes,
+            previousCreditedSeconds: input.previousCreditedSeconds,
+            nextCreditedSeconds: input.nextCreditedSeconds,
+            bucketDelta,
+            intervalMinutes,
+            rewardCategory: "manual_work_adjustment"
+        }
+    });
+}
 export function recordSessionEvent(input, activity, now = new Date()) {
     ensureDefaultRewardRules();
     const sessionEvent = sessionEventSchema.parse({
@@ -633,6 +724,85 @@ export function recordSessionEvent(input, activity, now = new Date()) {
     }, now);
     return { sessionEvent, rewardEvent };
 }
+export function recordHabitCheckInReward(habit, status, dateKey, activity) {
+    ensureDefaultRewardRules();
+    const aligned = (habit.polarity === "positive" && status === "done") ||
+        (habit.polarity === "negative" && status === "missed");
+    const rule = getRuleByCode(aligned ? "habit_aligned" : "habit_misaligned");
+    const deltaXp = aligned ? habit.rewardXp : -Math.abs(habit.penaltyXp);
+    const actionLabel = habit.polarity === "positive"
+        ? status === "done"
+            ? "completed"
+            : "missed"
+        : status === "done"
+            ? "performed"
+            : "resisted";
+    const eventLog = recordEventLog({
+        eventKind: aligned ? "reward.habit_aligned" : "reward.habit_misaligned",
+        entityType: "habit",
+        entityId: habit.id,
+        actor: activity.actor ?? null,
+        source: activity.source,
+        metadata: {
+            habitId: habit.id,
+            status,
+            polarity: habit.polarity,
+            dateKey,
+            deltaXp
+        }
+    });
+    return insertLedgerEvent({
+        ruleId: rule?.id ?? null,
+        eventLogId: eventLog.id,
+        entityType: "habit",
+        entityId: habit.id,
+        actor: activity.actor ?? null,
+        source: activity.source,
+        deltaXp,
+        reasonTitle: aligned ? `${habit.title} aligned` : `${habit.title} slipped`,
+        reasonSummary: `Habit ${actionLabel} on ${dateKey}.`,
+        reversibleGroup: `habit:${habit.id}:${dateKey}`,
+        metadata: {
+            habitId: habit.id,
+            status,
+            polarity: habit.polarity,
+            dateKey
+        }
+    });
+}
+export function recordWeeklyReviewCompletionReward(input, activity) {
+    ensureDefaultRewardRules();
+    const rule = getRuleByCode("weekly_review_completed");
+    const deltaXp = Math.max(0, Number(rule?.config.fixedXp ?? input.rewardXp));
+    const eventLog = recordEventLog({
+        eventKind: "reward.weekly_review_completed",
+        entityType: "system",
+        entityId: input.weekKey,
+        actor: activity.actor ?? null,
+        source: activity.source,
+        metadata: {
+            weekKey: input.weekKey,
+            windowLabel: input.windowLabel,
+            deltaXp
+        }
+    });
+    return insertLedgerEvent({
+        ruleId: rule?.id ?? null,
+        eventLogId: eventLog.id,
+        entityType: "system",
+        entityId: input.weekKey,
+        actor: activity.actor ?? null,
+        source: activity.source,
+        deltaXp,
+        reasonTitle: rule?.title ?? "Weekly review completed",
+        reasonSummary: `Closed the review for ${input.windowLabel}.`,
+        reversibleGroup: `weekly_review_completed:${input.weekKey}`,
+        metadata: {
+            weekKey: input.weekKey,
+            windowLabel: input.windowLabel
+        }
+    });
+}
 export function listSessionEvents(limit = 50) {
     const rows = getDatabase()
         .prepare(`SELECT id, session_id, event_type, actor, source, metrics_json, created_at

package/dist/server/repositories/settings.js

@@ -12,6 +12,18 @@ function toInt(value) {
 function hashToken(token) {
     return createHash("sha256").update(token).digest("hex");
 }
+function defaultMicrosoftRedirectUri() {
+    const port = process.env.PORT?.trim() || "4317";
+    return `http://127.0.0.1:${port}/api/v1/calendar/oauth/microsoft/callback`;
+}
+function normalizeMicrosoftTenantId(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : "common";
+}
+function normalizeMicrosoftRedirectUri(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : defaultMicrosoftRedirectUri();
+}
 function buildTokenSecret() {
     return `fg_live_${randomBytes(18).toString("hex")}`;
 }
@@ -108,7 +120,7 @@ function readSettingsRow() {
         .prepare(`SELECT
         operator_name, operator_email, operator_title, theme_preference, locale_preference,
         goal_drift_alerts, daily_quest_reminders, achievement_celebrations, max_active_tasks, time_accounting_mode,
-        integrity_score, last_audit_at, psyche_auth_required, created_at, updated_at
+        integrity_score, last_audit_at, psyche_auth_required, microsoft_client_id, microsoft_tenant_id, microsoft_redirect_uri, created_at, updated_at
        FROM app_settings
        WHERE id = 1`)
         .get();
@@ -166,6 +178,9 @@ export function isPsycheAuthRequired() {
 }
 export function getSettings() {
     const row = readSettingsRow();
+    const microsoftClientId = row.microsoft_client_id?.trim() ?? "";
+    const microsoftTenantId = normalizeMicrosoftTenantId(row.microsoft_tenant_id);
+    const microsoftRedirectUri = normalizeMicrosoftRedirectUri(row.microsoft_redirect_uri);
     return settingsPayloadSchema.parse({
         profile: {
             operatorName: row.operator_name,
@@ -191,6 +206,21 @@ export function getSettings() {
             tokenCount: listAgentTokens().filter((token) => token.status === "active").length,
             psycheAuthRequired: boolFromInt(row.psyche_auth_required)
         },
+        calendarProviders: {
+            microsoft: {
+                clientId: microsoftClientId,
+                tenantId: microsoftTenantId,
+                redirectUri: microsoftRedirectUri,
+                usesClientSecret: false,
+                readOnly: true,
+                authMode: "public_client_pkce",
+                isConfigured: microsoftClientId.length > 0,
+                isReadyForSignIn: microsoftClientId.length > 0,
+                setupMessage: microsoftClientId.length > 0
+                    ? "Microsoft local sign-in is configured. Test it if you want, then continue to the guided sign-in flow."
+                    : "Save the Microsoft client ID and the Forge callback redirect URI here before you try to sign in."
+            }
+        },
         agents: listAgentIdentities(),
         agentTokens: listAgentTokens()
     });
@@ -217,15 +247,25 @@ export function updateSettings(input, activity) {
             },
             themePreference: parsed.themePreference ?? current.themePreference,
             localePreference: parsed.localePreference ?? current.localePreference,
-            psycheAuthRequired: parsed.security?.psycheAuthRequired ?? current.security.psycheAuthRequired
+            psycheAuthRequired: parsed.security?.psycheAuthRequired ?? current.security.psycheAuthRequired,
+            calendarProviders: {
+                microsoft: {
+                    clientId: parsed.calendarProviders?.microsoft?.clientId?.trim() ??
+                        current.calendarProviders.microsoft.clientId,
+                    tenantId: normalizeMicrosoftTenantId(parsed.calendarProviders?.microsoft?.tenantId ??
+                        current.calendarProviders.microsoft.tenantId),
+                    redirectUri: normalizeMicrosoftRedirectUri(parsed.calendarProviders?.microsoft?.redirectUri ??
+                        current.calendarProviders.microsoft.redirectUri)
+                }
+            }
         };
         getDatabase()
             .prepare(`UPDATE app_settings
          SET operator_name = ?, operator_email = ?, operator_title = ?, theme_preference = ?, locale_preference = ?,
              goal_drift_alerts = ?, daily_quest_reminders = ?, achievement_celebrations = ?, max_active_tasks = ?, time_accounting_mode = ?,
-             psyche_auth_required = ?, updated_at = ?
+             psyche_auth_required = ?, microsoft_client_id = ?, microsoft_tenant_id = ?, microsoft_redirect_uri = ?, updated_at = ?
          WHERE id = 1`)
-            .run(next.profile.operatorName, next.profile.operatorEmail, next.profile.operatorTitle, next.themePreference, next.localePreference, toInt(next.notifications.goalDriftAlerts), toInt(next.notifications.dailyQuestReminders), toInt(next.notifications.achievementCelebrations), next.execution.maxActiveTasks, next.execution.timeAccountingMode, toInt(next.psycheAuthRequired), now);
+            .run(next.profile.operatorName, next.profile.operatorEmail, next.profile.operatorTitle, next.themePreference, next.localePreference, toInt(next.notifications.goalDriftAlerts), toInt(next.notifications.dailyQuestReminders), toInt(next.notifications.achievementCelebrations), next.execution.maxActiveTasks, next.execution.timeAccountingMode, toInt(next.psycheAuthRequired), next.calendarProviders.microsoft.clientId, next.calendarProviders.microsoft.tenantId, next.calendarProviders.microsoft.redirectUri, now);
         if (activity) {
             recordActivityEvent({
                 entityType: "system",
@@ -241,7 +281,9 @@ export function updateSettings(input, activity) {
                     goalDriftAlerts: next.notifications.goalDriftAlerts,
                     dailyQuestReminders: next.notifications.dailyQuestReminders,
                     maxActiveTasks: next.execution.maxActiveTasks,
-                    timeAccountingMode: next.execution.timeAccountingMode
+                    timeAccountingMode: next.execution.timeAccountingMode,
+                    microsoftConfigured: next.calendarProviders.microsoft.clientId.trim().length > 0,
+                    microsoftTenantId: next.calendarProviders.microsoft.tenantId
                 }
             });
         }

package/dist/server/repositories/task-runs.js

@@ -3,6 +3,7 @@ import { getDatabase, runInTransaction } from "../db.js";
 import { HttpError } from "../errors.js";
 import { computeWorkTime } from "../services/work-time.js";
 import { recordActivityEvent } from "./activity-events.js";
+import { bindTaskRunToTimebox, evaluateSchedulingForTask, finalizeTaskRunTimebox, heartbeatTaskRunTimebox } from "./calendar.js";
 import { createLinkedNotes } from "./notes.js";
 import { recordTaskRunCompletionReward, recordTaskRunProgressRewards, recordTaskRunStartReward } from "./rewards.js";
 import { getTaskById, updateTaskInTransaction } from "./tasks.js";
@@ -27,6 +28,7 @@ function selectClause() {
     task_runs.completed_at,
     task_runs.released_at,
     task_runs.timed_out_at,
+    task_runs.override_reason,
     task_runs.updated_at,
     tasks.title AS task_title
    FROM task_runs
@@ -74,6 +76,7 @@ function mapTaskRun(row, now = new Date(), cached = computeWorkTime(now)) {
         completedAt: row.completed_at,
         releasedAt: row.released_at,
         timedOutAt: row.timed_out_at,
+        overrideReason: row.override_reason ?? null,
         updatedAt: row.updated_at
     });
 }
@@ -289,6 +292,15 @@ export function claimTaskRun(taskId, input, now = new Date(), activity = { sourc
         const parsedInput = taskRunClaimSchema.parse(input);
         markExpiredRunsTimedOutInTransaction(now);
         requireKnownTask(taskId);
+        const task = getTaskById(taskId);
+        const scheduling = evaluateSchedulingForTask(task, now);
+        if (scheduling.blocked && (!parsedInput.overrideReason || parsedInput.overrideReason.trim().length === 0)) {
+            throw new HttpError(409, "task_run_calendar_blocked", `Calendar rules block starting ${task.title} right now. Add an override reason to proceed.`, {
+                taskId,
+                conflicts: scheduling.conflicts,
+                effectiveRules: scheduling.effectiveRules
+            });
+        }
         const existing = getActiveTaskRunRow(taskId, now);
         const nowIso = now.toISOString();
         if (existing) {
@@ -298,9 +310,9 @@ export function claimTaskRun(taskId, input, now = new Date(), activity = { sourc
             const nextExpiry = leaseExpiry(now, parsedInput.leaseTtlSeconds);
             getDatabase()
                 .prepare(`UPDATE task_runs
-           SET timer_mode = ?, planned_duration_seconds = ?, is_current = ?, heartbeat_at = ?, lease_expires_at = ?, lease_ttl_seconds = ?, note = ?, updated_at = ?
+           SET timer_mode = ?, planned_duration_seconds = ?, is_current = ?, heartbeat_at = ?, lease_expires_at = ?, lease_ttl_seconds = ?, note = ?, override_reason = ?, updated_at = ?
            WHERE id = ?`)
-                .run(parsedInput.timerMode, parsedInput.plannedDurationSeconds, existing.is_current, nowIso, nextExpiry, parsedInput.leaseTtlSeconds, parsedInput.note, nowIso, existing.id);
+                .run(parsedInput.timerMode, parsedInput.plannedDurationSeconds, existing.is_current, nowIso, nextExpiry, parsedInput.leaseTtlSeconds, parsedInput.note, parsedInput.overrideReason ?? null, nowIso, existing.id);
             maybeSetCurrentRun(parsedInput.actor, existing.id, parsedInput.isCurrent, now);
             touchTaskInProgress(taskId, parsedInput.actor, activity.source);
             recordActivityEvent({
@@ -315,9 +327,15 @@ export function claimTaskRun(taskId, input, now = new Date(), activity = { sourc
                     taskId,
                     leaseTtlSeconds: parsedInput.leaseTtlSeconds,
                     timerMode: parsedInput.timerMode,
-                    plannedDurationSeconds: parsedInput.plannedDurationSeconds
+                    plannedDurationSeconds: parsedInput.plannedDurationSeconds,
+                    overrideReason: parsedInput.overrideReason ?? null
                 }
             });
+            heartbeatTaskRunTimebox(existing.id, {
+                title: task.title,
+                endsAt: nextExpiry,
+                overrideReason: parsedInput.overrideReason ?? null
+            });
             const cached = computeWorkTime(now);
             return {
                 run: mapTaskRun(requireRun(existing.id), now, cached),
@@ -329,13 +347,22 @@ export function claimTaskRun(taskId, input, now = new Date(), activity = { sourc
         const expiry = leaseExpiry(now, parsedInput.leaseTtlSeconds);
         getDatabase()
             .prepare(`INSERT INTO task_runs (
-          id, task_id, actor, status, timer_mode, planned_duration_seconds, is_current, note, lease_ttl_seconds, claimed_at, heartbeat_at, lease_expires_at, updated_at
+          id, task_id, actor, status, timer_mode, planned_duration_seconds, is_current, note, lease_ttl_seconds, claimed_at, heartbeat_at, lease_expires_at, override_reason, updated_at
          )
-         VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(runId, taskId, parsedInput.actor, parsedInput.timerMode, parsedInput.plannedDurationSeconds, 0, parsedInput.note, parsedInput.leaseTtlSeconds, nowIso, nowIso, expiry, nowIso);
+         VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(runId, taskId, parsedInput.actor, parsedInput.timerMode, parsedInput.plannedDurationSeconds, 0, parsedInput.note, parsedInput.leaseTtlSeconds, nowIso, nowIso, expiry, parsedInput.overrideReason ?? null, nowIso);
         maybeSetCurrentRun(parsedInput.actor, runId, parsedInput.isCurrent, now);
         touchTaskInProgress(taskId, parsedInput.actor, activity.source);
         const run = mapTaskRun(requireRun(runId), now);
+        bindTaskRunToTimebox({
+            taskId,
+            taskRunId: run.id,
+            startedAt: now,
+            title: task.title,
+            projectId: task.projectId,
+            plannedDurationSeconds: parsedInput.plannedDurationSeconds,
+            overrideReason: parsedInput.overrideReason ?? null
+        });
         recordActivityEvent({
             entityType: "task_run",
             entityId: run.id,
@@ -350,7 +377,8 @@ export function claimTaskRun(taskId, input, now = new Date(), activity = { sourc
                 taskId: run.taskId,
                 leaseTtlSeconds: run.leaseTtlSeconds,
                 timerMode: run.timerMode,
-                plannedDurationSeconds: run.plannedDurationSeconds
+                plannedDurationSeconds: run.plannedDurationSeconds,
+                overrideReason: parsedInput.overrideReason ?? null
             }
         });
         recordTaskRunStartReward(run.id, run.taskId, run.actor, activity.source);
@@ -370,15 +398,16 @@ export function heartbeatTaskRun(taskRunId, input, now = new Date(), activity =
         const note = input.note ?? current.note;
         getDatabase()
             .prepare(`UPDATE task_runs
-         SET heartbeat_at = ?, lease_expires_at = ?, lease_ttl_seconds = ?, note = ?, updated_at = ?
+         SET heartbeat_at = ?, lease_expires_at = ?, lease_ttl_seconds = ?, note = ?, override_reason = ?, updated_at = ?
          WHERE id = ?`)
-            .run(nowIso, nextExpiry, input.leaseTtlSeconds, note, nowIso, taskRunId);
+            .run(nowIso, nextExpiry, input.leaseTtlSeconds, note, input.overrideReason ?? current.override_reason, nowIso, taskRunId);
         const run = mapTaskRun({
             ...current,
             heartbeat_at: nowIso,
             lease_expires_at: nextExpiry,
             lease_ttl_seconds: input.leaseTtlSeconds,
             note,
+            override_reason: input.overrideReason ?? current.override_reason,
             updated_at: nowIso
         }, now);
         recordActivityEvent({
@@ -391,9 +420,15 @@ export function heartbeatTaskRun(taskRunId, input, now = new Date(), activity =
             source: activity.source,
             metadata: {
                 taskId: run.taskId,
-                leaseTtlSeconds: run.leaseTtlSeconds
+                leaseTtlSeconds: run.leaseTtlSeconds,
+                overrideReason: input.overrideReason ?? null
             }
         });
+        heartbeatTaskRunTimebox(taskRunId, {
+            title: run.taskTitle,
+            endsAt: nextExpiry,
+            overrideReason: input.overrideReason ?? null
+        });
         recordTaskRunProgressRewards(run.id, run.taskId, input.actor ?? run.actor, activity.source, run.creditedSeconds);
         return run;
     });
@@ -451,6 +486,7 @@ function finishTaskRun(taskRunId, nextStatus, timestampColumn, input, now, activ
             [timestampColumn]: nowIso,
             updated_at: nowIso
         }, now);
+        finalizeTaskRunTimebox(taskRunId, nextStatus === "completed" ? "completed" : "cancelled", nowIso);
         recordActivityEvent({
             entityType: "task_run",
             entityId: run.id,

package/dist/server/repositories/tasks.js

@@ -11,7 +11,7 @@ import { pruneLinkedEntityReferences } from "./psyche.js";
 import { awardTaskCompletionReward, reverseLatestTaskCompletionReward } from "./rewards.js";
 import { assertTaskRelations } from "../services/relations.js";
 import { computeWorkTime, emptyTaskTimeSummary } from "../services/work-time.js";
-import { taskSchema } from "../types.js";
+import { calendarSchedulingRulesSchema, taskSchema } from "../types.js";
 function readTaskTagIds(taskId) {
     const rows = getDatabase()
         .prepare(`SELECT tag_id FROM task_tags WHERE task_id = ? ORDER BY tag_id`)
@@ -32,6 +32,10 @@ function mapTask(row, time = emptyTaskTimeSummary()) {
         effort: row.effort,
         energy: row.energy,
         points: row.points,
+        plannedDurationSeconds: row.planned_duration_seconds,
+        schedulingRules: row.scheduling_rules_json === null
+            ? null
+            : calendarSchedulingRulesSchema.parse(JSON.parse(row.scheduling_rules_json)),
         sortOrder: row.sort_order,
         completedAt: row.completed_at,
         createdAt: row.created_at,
@@ -129,9 +133,17 @@ function updateTaskRecord(current, input, activity) {
     getDatabase()
         .prepare(`UPDATE tasks
        SET title = ?, description = ?, status = ?, priority = ?, owner = ?, goal_id = ?, due_date = ?, effort = ?,
-           energy = ?, points = ?, sort_order = ?, completed_at = ?, updated_at = ?, project_id = ?
+           energy = ?, points = ?, planned_duration_seconds = ?, scheduling_rules_json = ?, sort_order = ?, completed_at = ?, updated_at = ?, project_id = ?
        WHERE id = ?`)
-        .run(input.title ?? current.title, input.description ?? current.description, nextStatus, input.priority ?? current.priority, input.owner ?? current.owner, nextGoalId, input.dueDate === undefined ? current.dueDate : input.dueDate, input.effort ?? current.effort, input.energy ?? current.energy, input.points ?? current.points, nextSort, completedAt, updatedAt, nextProjectId, current.id);
+        .run(input.title ?? current.title, input.description ?? current.description, nextStatus, input.priority ?? current.priority, input.owner ?? current.owner, nextGoalId, input.dueDate === undefined ? current.dueDate : input.dueDate, input.effort ?? current.effort, input.energy ?? current.energy, input.points ?? current.points, input.plannedDurationSeconds === undefined
+        ? current.plannedDurationSeconds
+        : input.plannedDurationSeconds, input.schedulingRules === undefined
+        ? current.schedulingRules === null
+            ? null
+            : JSON.stringify(current.schedulingRules)
+        : input.schedulingRules === null
+            ? null
+            : JSON.stringify(input.schedulingRules), nextSort, completedAt, updatedAt, nextProjectId, current.id);
     replaceTaskTags(current.id, nextTagIds);
     const updated = getTaskById(current.id);
     if (updated && activity) {
@@ -210,6 +222,8 @@ function fingerprintTaskCreate(input) {
         effort: input.effort,
         energy: input.energy,
         points: input.points,
+        plannedDurationSeconds: input.plannedDurationSeconds,
+        schedulingRules: input.schedulingRules,
         sortOrder: input.sortOrder ?? null,
         tagIds: input.tagIds,
         notes: input.notes.map((note) => ({
@@ -232,11 +246,11 @@ function insertTaskRecord(input, activity) {
     const completedAt = normalizeCompletedAt(input.status, null);
     getDatabase()
         .prepare(`INSERT INTO tasks (
-        id, title, description, status, priority, owner, goal_id, project_id, due_date, effort, energy, points, sort_order,
-        completed_at, created_at, updated_at
+        id, title, description, status, priority, owner, goal_id, project_id, due_date, effort, energy, points,
+        planned_duration_seconds, scheduling_rules_json, sort_order, completed_at, created_at, updated_at
       )
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(id, input.title, input.description, input.status, input.priority, input.owner, relationState.goalId, relationState.projectId, input.dueDate, input.effort, input.energy, input.points, sortOrder, completedAt, now, now);
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(id, input.title, input.description, input.status, input.priority, input.owner, relationState.goalId, relationState.projectId, input.dueDate, input.effort, input.energy, input.points, input.plannedDurationSeconds, input.schedulingRules === null ? null : JSON.stringify(input.schedulingRules), sortOrder, completedAt, now, now);
     replaceTaskTags(id, input.tagIds);
     const task = getTaskById(id);
     if (activity) {
@@ -306,7 +320,8 @@ export function listTasks(filters = {}) {
         params.push(filters.limit);
     }
     const rows = getDatabase()
-        .prepare(`SELECT id, title, description, status, priority, owner, goal_id, project_id, due_date, effort, energy, points, sort_order,
+        .prepare(`SELECT id, title, description, status, priority, owner, goal_id, project_id, due_date, effort, energy, points,
+              planned_duration_seconds, scheduling_rules_json, sort_order,
               completed_at, created_at, updated_at
        FROM tasks
        ${whereSql}
@@ -330,7 +345,8 @@ export function getTaskById(taskId) {
         return undefined;
     }
     const row = getDatabase()
-        .prepare(`SELECT id, title, description, status, priority, owner, goal_id, project_id, due_date, effort, energy, points, sort_order,
+        .prepare(`SELECT id, title, description, status, priority, owner, goal_id, project_id, due_date, effort, energy, points,
+              planned_duration_seconds, scheduling_rules_json, sort_order,
               completed_at, created_at, updated_at
        FROM tasks
        WHERE id = ?`)

package/dist/server/repositories/weekly-reviews.js

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto";
+import { getDatabase, runInTransaction } from "../db.js";
+import { recordActivityEvent } from "./activity-events.js";
+import { getRewardLedgerEventById, recordWeeklyReviewCompletionReward } from "./rewards.js";
+import { weeklyReviewClosureSchema } from "../types.js";
+function mapWeeklyReviewClosure(row) {
+    return weeklyReviewClosureSchema.parse({
+        id: row.id,
+        weekKey: row.week_key,
+        weekStartDate: row.week_start_date,
+        weekEndDate: row.week_end_date,
+        windowLabel: row.window_label,
+        actor: row.actor,
+        source: row.source,
+        rewardId: row.reward_id,
+        activityEventId: row.activity_event_id,
+        createdAt: row.created_at
+    });
+}
+export function getWeeklyReviewClosure(weekKey) {
+    const row = getDatabase()
+        .prepare(`SELECT
+         id,
+         week_key,
+         week_start_date,
+         week_end_date,
+         window_label,
+         actor,
+         source,
+         reward_id,
+         activity_event_id,
+         created_at
+       FROM weekly_review_closures
+       WHERE week_key = ?`)
+        .get(weekKey);
+    return row ? mapWeeklyReviewClosure(row) : null;
+}
+export function finalizeWeeklyReviewClosure(input) {
+    return runInTransaction(() => {
+        const existing = getWeeklyReviewClosure(input.weekKey);
+        if (existing) {
+            const existingReward = getRewardLedgerEventById(existing.rewardId);
+            if (!existingReward) {
+                throw new Error(`Weekly review closure ${existing.id} is missing reward ${existing.rewardId}.`);
+            }
+            return {
+                closure: existing,
+                reward: existingReward,
+                created: false
+            };
+        }
+        const reward = recordWeeklyReviewCompletionReward({
+            weekKey: input.weekKey,
+            windowLabel: input.windowLabel,
+            rewardXp: input.rewardXp
+        }, {
+            actor: input.actor ?? null,
+            source: input.source
+        });
+        const activity = recordActivityEvent({
+            entityType: "system",
+            entityId: input.weekKey,
+            eventType: "weekly_review_finalized",
+            title: `Weekly review finalized: ${input.windowLabel}`,
+            description: `Review completion locked this cycle and awarded ${reward.deltaXp} XP.`,
+            actor: input.actor ?? null,
+            source: input.source,
+            metadata: {
+                weekKey: input.weekKey,
+                weekStartDate: input.weekStartDate,
+                weekEndDate: input.weekEndDate,
+                rewardId: reward.id,
+                rewardXp: reward.deltaXp
+            }
+        });
+        const createdAt = new Date().toISOString();
+        const closure = weeklyReviewClosureSchema.parse({
+            id: `wrc_${randomUUID().replaceAll("-", "").slice(0, 10)}`,
+            weekKey: input.weekKey,
+            weekStartDate: input.weekStartDate,
+            weekEndDate: input.weekEndDate,
+            windowLabel: input.windowLabel,
+            actor: input.actor ?? null,
+            source: input.source,
+            rewardId: reward.id,
+            activityEventId: activity.id,
+            createdAt
+        });
+        getDatabase()
+            .prepare(`INSERT INTO weekly_review_closures (
+          id,
+          week_key,
+          week_start_date,
+          week_end_date,
+          window_label,
+          actor,
+          source,
+          reward_id,
+          activity_event_id,
+          created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(closure.id, closure.weekKey, closure.weekStartDate, closure.weekEndDate, closure.windowLabel, closure.actor, closure.source, closure.rewardId, closure.activityEventId, closure.createdAt);
+        return {
+            closure,
+            reward,
+            created: true
+        };
+    });
+}