@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/workflow/schedules/settlement.ts

@@ -0,0 +1,144 @@
+import type { ExecutionJob } from '../../execution/jobs/types';
+import type { ScheduleDecisionType, ScheduleOccurrence } from './types';
+import {
+  getOccurrence,
+  getSchedule,
+  recordScheduleOccurrenceHandoff,
+  saveOccurrence,
+  saveSchedule,
+  type ScheduleOccurrenceHandoffInput,
+} from './store';
+
+const TERMINAL_OCCURRENCE_STATUSES = new Set<ScheduleOccurrence['status']>(['succeeded', 'failed', 'shadowed', 'skipped']);
+
+function computeScheduleFailureState(schedule: ReturnType<typeof getSchedule>, nextFailures: number): Pick<ReturnType<typeof getSchedule>, 'consecutiveFailures' | 'nextEligibleAt' | 'enabled' | 'pausedReason'> {
+  const shouldPause = nextFailures >= schedule.policy.maxFailures;
+  const backoffBase = Math.max(1, schedule.policy.backoffBaseMinutes ?? schedule.policy.cooldownMinutes ?? 1);
+  const backoffMax = Math.max(backoffBase, schedule.policy.backoffMaxMinutes ?? 24 * 60);
+  const backoffMinutes = Math.min(backoffMax, backoffBase * (2 ** Math.max(0, nextFailures - 1)));
+  return {
+    consecutiveFailures: nextFailures,
+    nextEligibleAt: new Date(Date.now() + backoffMinutes * 60_000).toISOString(),
+    enabled: shouldPause ? false : schedule.enabled,
+    pausedReason: shouldPause ? 'Maximum consecutive failures reached.' : undefined,
+  };
+}
+
+export function applyScheduleFailure(
+  controllerHome: string,
+  scheduleId: string,
+  repoId: string,
+  occurrenceId: string,
+  options: {
+    outcome: 'failed' | 'skipped';
+    decision?: ScheduleDecisionType;
+    reason: string;
+    countFailure?: boolean;
+    pauseReason?: string;
+    handoff?: ScheduleOccurrenceHandoffInput;
+  },
+): { schedule: ReturnType<typeof getSchedule>; occurrence?: ScheduleOccurrence } {
+  const schedule = getSchedule(controllerHome, repoId, scheduleId);
+  const occurrence = getOccurrence(controllerHome, repoId, occurrenceId);
+  let nextOccurrence = occurrence;
+  if (occurrence && !TERMINAL_OCCURRENCE_STATUSES.has(occurrence.status)) {
+    nextOccurrence = saveOccurrence(controllerHome, {
+      ...occurrence,
+      status: options.outcome,
+      decision: options.decision ?? occurrence.decision,
+      reason: options.reason,
+    });
+  }
+  if (nextOccurrence && options.handoff) {
+    nextOccurrence = recordScheduleOccurrenceHandoff(controllerHome, schedule, nextOccurrence, options.handoff);
+  }
+
+  const countFailure = options.countFailure !== false;
+  const nextSchedule = options.pauseReason
+    ? saveSchedule(controllerHome, {
+      ...schedule,
+      enabled: false,
+      pausedReason: options.pauseReason,
+      nextEligibleAt: undefined,
+      consecutiveFailures: countFailure ? schedule.consecutiveFailures + 1 : schedule.consecutiveFailures,
+    })
+    : countFailure
+      ? saveSchedule(controllerHome, { ...schedule, ...computeScheduleFailureState(schedule, schedule.consecutiveFailures + 1) })
+      : schedule;
+  return { schedule: nextSchedule, occurrence: nextOccurrence };
+}
+
+export function markScheduledExecutionRunning(controllerHome: string, job: ExecutionJob): void {
+  if (job.type !== 'scheduled-occurrence') return;
+  const occurrenceId = typeof job.payload.occurrenceId === 'string' ? job.payload.occurrenceId : undefined;
+  if (!occurrenceId) return;
+  try {
+    const occurrence = getOccurrence(controllerHome, job.repoId, occurrenceId);
+    if (occurrence && occurrence.status === 'queued') {
+      saveOccurrence(controllerHome, { ...occurrence, status: 'running', decision: 'execute', reason: 'Scheduled Worker started.' });
+    }
+  } catch {
+    // The durable Job remains authoritative if an old occurrence was removed.
+  }
+}
+
+/**
+ * Keep an occurrence and its owning schedule consistent with the terminal
+ * state of the durable ExecutionJob that implements it. This is deliberately
+ * idempotent so both the Worker and the Reconciler may call it safely.
+ */
+export function settleScheduledExecution(
+  controllerHome: string,
+  job: ExecutionJob,
+  outcome: 'succeeded' | 'failed',
+  reason: string,
+): void {
+  if (job.type !== 'scheduled-occurrence') return;
+  const scheduleId = typeof job.payload.scheduleId === 'string' ? job.payload.scheduleId : undefined;
+  const occurrenceId = typeof job.payload.occurrenceId === 'string' ? job.payload.occurrenceId : undefined;
+  if (!scheduleId || !occurrenceId) return;
+  try {
+    const schedule = getSchedule(controllerHome, job.repoId, scheduleId);
+    const occurrence = getOccurrence(controllerHome, job.repoId, occurrenceId);
+    if (occurrence && !['succeeded', 'failed', 'shadowed', 'skipped'].includes(occurrence.status)) {
+      saveOccurrence(controllerHome, {
+        ...occurrence,
+        status: outcome,
+        decision: 'execute',
+        reason,
+      });
+    }
+    if (outcome === 'failed') {
+      applyScheduleFailure(controllerHome, scheduleId, job.repoId, occurrenceId, {
+        outcome,
+        decision: 'execute',
+        reason,
+        handoff: {
+          title: `Scheduled maintenance occurrence ${occurrenceId} failed`,
+          summary: 'A bounded live maintenance occurrence failed and requires review before the schedule continues unattended.',
+          reason,
+          creationReason: 'repeated_infrastructure_failure',
+          blockingDecision: 'Review the failed maintenance occurrence and decide whether the schedule should continue automatically.',
+          recommendedDecision: 'Inspect the failed occurrence, fix the runtime blocker, then re-enable or retrigger the schedule intentionally.',
+          recommendedPrompt: `Review schedule occurrence ${occurrenceId} for ${scheduleId}, inspect the failed runtime maintenance action, and decide whether to resume automatic maintenance.`,
+          statusSummary: 'Scheduled maintenance execution failed.',
+          blockedBy: ['scheduled_execution_failed'],
+          attemptedActions: [
+            `job:${job.jobId}`,
+            `operation:${String(job.payload.operation ?? 'unknown')}`,
+          ],
+        },
+      });
+      return;
+    }
+    saveSchedule(controllerHome, {
+      ...schedule,
+      consecutiveFailures: 0,
+      nextEligibleAt: undefined,
+      pausedReason: undefined,
+    });
+  } catch {
+    // Job terminal state remains authoritative even if an old schedule record
+    // has already been removed. Reconciliation must not be blocked by it.
+  }
+}

package/src/runtime/workflow/schedules/store.ts

@@ -0,0 +1,417 @@
+import { createHash, randomUUID } from 'crypto';
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { withControllerLock } from '../../../cli/repositories/locks';
+import { createHandoffItem, getHandoffItem } from '../../control-plane/facade/handoff-inbox-store';
+import { readJsonFile, writeJsonAtomic } from '../../shared/json-files';
+import { appendRuntimeEvent } from '../../evidence/event-ledger';
+import type { RepositorySchedule, ScheduleDecision, ScheduleOccurrence } from './types';
+
+interface OccurrenceIndex {
+  schemaVersion: 1;
+  updatedAt: string;
+  active: Array<{ occurrenceId: string; scheduleId: string; status: ScheduleOccurrence['status']; updatedAt: string }>;
+  recent: Array<{ occurrenceId: string; scheduleId: string; status: ScheduleOccurrence['status']; createdAt: string; updatedAt: string }>;
+}
+interface ScheduleRequestRecord {
+  schemaVersion: 1;
+  requestId: string;
+  semanticKey: string;
+  scheduleId: string;
+  repoId: string;
+  createdAt: string;
+}
+type CreateScheduleInput = Omit<RepositorySchedule, 'schemaVersion' | 'revision' | 'scheduleId' | 'createdAt' | 'updatedAt' | 'consecutiveFailures'>;
+
+export interface ScheduleOccurrenceHandoffInput {
+  title: string;
+  summary: string;
+  reason: string;
+  creationReason: 'ambiguous_outcome' | 'missing_authorization' | 'repeated_infrastructure_failure';
+  blockingDecision: string;
+  recommendedDecision: string;
+  recommendedPrompt: string;
+  statusSummary: string;
+  blockedBy?: string[];
+  attemptedActions?: string[];
+  evidenceRefs?: Array<{ title: string; summary?: string; detailLevel?: 'summary' | 'detail' | 'raw' }>;
+}
+
+function schedulesRoot(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'schedules');
+}
+function schedulePath(controllerHome: string, repoId: string, scheduleId: string): string {
+  return join(schedulesRoot(controllerHome, repoId), 'records', `${scheduleId}.json`);
+}
+function occurrencePath(controllerHome: string, repoId: string, occurrenceId: string): string {
+  return join(schedulesRoot(controllerHome, repoId), 'occurrences', `${occurrenceId}.json`);
+}
+
+function decisionPath(controllerHome: string, repoId: string, decisionId: string): string {
+  return join(schedulesRoot(controllerHome, repoId), 'decisions', `${decisionId}.json`);
+}
+function occurrenceIndexPath(controllerHome: string, repoId: string): string {
+  return join(schedulesRoot(controllerHome, repoId), 'indexes', 'occurrences.json');
+}
+function requestPath(controllerHome: string, repoId: string, requestId: string): string {
+  return join(schedulesRoot(controllerHome, repoId), 'indexes', 'requests', `${createHash('sha256').update(requestId).digest('hex')}.json`);
+}
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+    .sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, canonical(entry)]));
+  return value;
+}
+function scheduleSemanticKey(input: CreateScheduleInput): string {
+  return createHash('sha256').update(JSON.stringify(canonical({
+    repoId: input.repoId,
+    name: input.name,
+    trigger: input.trigger,
+    policy: input.policy,
+    action: input.action,
+    stopConditions: input.stopConditions,
+  }))).digest('hex');
+}
+function emptyIndex(): OccurrenceIndex {
+  return { schemaVersion: 1, updatedAt: new Date().toISOString(), active: [], recent: [] };
+}
+function readOccurrenceIndex(controllerHome: string, repoId: string): OccurrenceIndex {
+  return readJsonFile<OccurrenceIndex>(occurrenceIndexPath(controllerHome, repoId), emptyIndex());
+}
+function upsertOccurrenceIndexUnlocked(controllerHome: string, occurrence: ScheduleOccurrence): void {
+  const index = readOccurrenceIndex(controllerHome, occurrence.repoId);
+  index.active = index.active.filter((entry) => entry.occurrenceId !== occurrence.occurrenceId);
+  index.recent = index.recent.filter((entry) => entry.occurrenceId !== occurrence.occurrenceId);
+  if (['created', 'queued', 'running'].includes(occurrence.status)) {
+    index.active.push({ occurrenceId: occurrence.occurrenceId, scheduleId: occurrence.scheduleId, status: occurrence.status, updatedAt: occurrence.updatedAt });
+  }
+  index.recent.push({ occurrenceId: occurrence.occurrenceId, scheduleId: occurrence.scheduleId, status: occurrence.status, createdAt: occurrence.createdAt, updatedAt: occurrence.updatedAt });
+  index.updatedAt = new Date().toISOString();
+  index.active.sort((a, b) => a.updatedAt.localeCompare(b.updatedAt));
+  index.recent.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  index.active = index.active.slice(-5000);
+  index.recent = index.recent.slice(0, 5000);
+  writeJsonAtomic(occurrenceIndexPath(controllerHome, occurrence.repoId), index);
+}
+
+export function createSchedule(controllerHome: string, input: CreateScheduleInput): RepositorySchedule {
+  const requestId = input.requestId.trim();
+  if (!requestId) throw new Error('SCHEDULE_REQUEST_ID_REQUIRED');
+  const semanticKey = scheduleSemanticKey(input);
+  return withControllerLock(controllerHome, { scope: 'task', repoId: input.repoId, taskId: `schedule-request-${createHash('sha256').update(requestId).digest('hex').slice(0, 16)}` }, `create-schedule:${requestId}`, () => {
+    const requestRecordPath = requestPath(controllerHome, input.repoId, requestId);
+    if (existsSync(requestRecordPath)) {
+      const record = readJsonFile<ScheduleRequestRecord>(requestRecordPath);
+      if (record.semanticKey !== semanticKey) throw new Error(`SCHEDULE_REQUEST_ID_CONFLICT: ${requestId}`);
+      return getSchedule(controllerHome, input.repoId, record.scheduleId);
+    }
+    const timestamp = new Date().toISOString();
+    const schedule: RepositorySchedule = {
+      ...input,
+      requestId,
+      schemaVersion: 1,
+      revision: 1,
+      scheduleId: `SCH-${Date.now()}-${randomUUID().slice(0, 8)}`,
+      createdAt: timestamp,
+      updatedAt: timestamp,
+      consecutiveFailures: 0,
+    };
+    writeJsonAtomic(schedulePath(controllerHome, schedule.repoId, schedule.scheduleId), schedule);
+    writeJsonAtomic(requestRecordPath, { schemaVersion: 1, requestId, semanticKey, scheduleId: schedule.scheduleId, repoId: schedule.repoId, createdAt: timestamp } satisfies ScheduleRequestRecord);
+    appendRuntimeEvent(controllerHome, { repoId: schedule.repoId, entityType: 'schedule', entityId: schedule.scheduleId, eventType: 'schedule_created', requestId, revision: schedule.revision, data: { name: schedule.name, shadowMode: schedule.policy.shadowMode } });
+    return schedule;
+  }, 10_000);
+}
+
+export function getSchedule(controllerHome: string, repoId: string, scheduleId: string): RepositorySchedule {
+  const schedule = readJsonFile<RepositorySchedule>(schedulePath(controllerHome, repoId, scheduleId));
+  // Hydrate schedules written before requestId/revision became mandatory.
+  return {
+    ...schedule,
+    revision: Number.isFinite(schedule.revision) ? schedule.revision : 1,
+    requestId: schedule.requestId || `legacy-schedule:${schedule.scheduleId}`,
+    policy: {
+      ...schedule.policy,
+      backoffBaseMinutes: Math.max(1, schedule.policy.backoffBaseMinutes ?? schedule.policy.cooldownMinutes ?? 1),
+      backoffMaxMinutes: Math.max(1, schedule.policy.backoffMaxMinutes ?? 24 * 60),
+    },
+    consecutiveNoops: Math.max(0, schedule.consecutiveNoops ?? 0),
+  };
+}
+
+export function saveSchedule(controllerHome: string, schedule: RepositorySchedule): RepositorySchedule {
+  return withControllerLock(controllerHome, { scope: 'task', repoId: schedule.repoId, taskId: `schedule-${schedule.scheduleId}` }, `save-schedule:${schedule.scheduleId}`, () => {
+    const current = getSchedule(controllerHome, schedule.repoId, schedule.scheduleId);
+    const next = { ...schedule, revision: current.revision + 1, updatedAt: new Date().toISOString() };
+    writeJsonAtomic(schedulePath(controllerHome, next.repoId, next.scheduleId), next);
+    appendRuntimeEvent(controllerHome, { repoId: next.repoId, entityType: 'schedule', entityId: next.scheduleId, eventType: 'schedule_updated', requestId: next.requestId, revision: next.revision, data: { enabled: next.enabled, pausedReason: next.pausedReason } });
+    return next;
+  }, 10_000);
+}
+
+export function listSchedules(controllerHome: string, repoId: string): RepositorySchedule[] {
+  const root = join(schedulesRoot(controllerHome, repoId), 'records');
+  try {
+    return readdirSync(root).filter((name) => name.endsWith('.json'))
+      .map((name) => getSchedule(controllerHome, repoId, name.slice(0, -'.json'.length)))
+      .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  } catch { return []; }
+}
+
+export function saveOccurrence(controllerHome: string, occurrence: ScheduleOccurrence): ScheduleOccurrence {
+  return withControllerLock(controllerHome, { scope: 'task', repoId: occurrence.repoId, taskId: `schedule-${occurrence.scheduleId}` }, `save-occurrence:${occurrence.occurrenceId}`, () => {
+    const existingPath = occurrencePath(controllerHome, occurrence.repoId, occurrence.occurrenceId);
+    const previous = existsSync(existingPath) ? readJsonFile<ScheduleOccurrence>(existingPath) : undefined;
+    const next = { ...occurrence, revision: (previous?.revision ?? occurrence.revision ?? 0) + 1, updatedAt: new Date().toISOString() };
+    writeJsonAtomic(existingPath, next);
+    upsertOccurrenceIndexUnlocked(controllerHome, next);
+    const schedule = getSchedule(controllerHome, next.repoId, next.scheduleId);
+    appendRuntimeEvent(controllerHome, { repoId: next.repoId, entityType: 'occurrence', entityId: next.occurrenceId, eventType: `occurrence_${next.status}`, requestId: `${schedule.requestId}:${next.windowKey}`, revision: next.revision, correlationId: next.scheduleId, data: { decision: next.decision, jobId: next.jobId, reason: next.reason } });
+    return next;
+  }, 10_000);
+}
+
+export function getOccurrence(controllerHome: string, repoId: string, occurrenceId: string): ScheduleOccurrence | undefined {
+  const path = occurrencePath(controllerHome, repoId, occurrenceId);
+  return existsSync(path) ? readJsonFile<ScheduleOccurrence>(path) : undefined;
+}
+
+export function recordScheduleOccurrenceHandoff(
+  controllerHome: string,
+  schedule: RepositorySchedule,
+  occurrence: ScheduleOccurrence,
+  input: ScheduleOccurrenceHandoffInput,
+): ScheduleOccurrence {
+  if (occurrence.handoffId) return occurrence;
+  const handoffId = `schedule-${occurrence.occurrenceId}`;
+  const evidenceRefs: NonNullable<ScheduleOccurrenceHandoffInput['evidenceRefs']> = [
+    { title: `Occurrence ${occurrence.occurrenceId}`, summary: occurrence.reason ?? input.reason, detailLevel: 'summary' as const },
+  ];
+  for (const ref of input.evidenceRefs ?? []) {
+    evidenceRefs.push(ref);
+    if (evidenceRefs.length >= 20) break;
+  }
+  const existing = getHandoffItem({ controllerHome, repoId: occurrence.repoId }, handoffId);
+  const item = existing ?? createHandoffItem(
+    { controllerHome, repoId: occurrence.repoId },
+    {
+      id: handoffId,
+      repoId: occurrence.repoId,
+      title: input.title,
+      severity: 'blocked',
+      reason: input.reason,
+      creationReason: input.creationReason,
+      summary: input.summary,
+      currentState: {
+        repoId: occurrence.repoId,
+        taskId: schedule.scheduleId,
+        statusSummary: input.statusSummary,
+        blockedBy: input.blockedBy,
+      },
+      attemptedActions: [
+        `schedule:${schedule.scheduleId}`,
+        `occurrence:${occurrence.occurrenceId}`,
+        ...(input.attemptedActions ?? []),
+      ].slice(0, 20),
+      evidenceRefs,
+      blockingDecision: input.blockingDecision,
+      recommendedDecision: input.recommendedDecision,
+      recommendedPrompt: input.recommendedPrompt,
+      suggestedNextActions: [{
+        label: 'Review handoff',
+        tool: 'rh_inbox',
+        operation: 'get',
+        payload: { handoff_id: handoffId },
+        risk: 'readonly',
+        confidence: 'high',
+        reason: 'Review the bounded occurrence handoff before resuming automatic maintenance.',
+      }],
+    },
+  );
+  return saveOccurrence(controllerHome, { ...occurrence, handoffId: item.id });
+}
+
+export function listActiveOccurrences(controllerHome: string, repoId: string, scheduleId?: string): ScheduleOccurrence[] {
+  const index = readOccurrenceIndex(controllerHome, repoId);
+  return index.active
+    .filter((entry) => !scheduleId || entry.scheduleId === scheduleId)
+    .flatMap((entry) => {
+      const occurrence = getOccurrence(controllerHome, repoId, entry.occurrenceId);
+      return occurrence ? [occurrence] : [];
+    });
+}
+
+export function listOccurrences(controllerHome: string, repoId: string, scheduleId?: string, limit = 100): ScheduleOccurrence[] {
+  const bounded = Math.max(1, Math.min(limit, 1000));
+  const index = readOccurrenceIndex(controllerHome, repoId);
+  const indexed = index.recent
+    .filter((entry) => !scheduleId || entry.scheduleId === scheduleId)
+    .slice(0, bounded)
+    .flatMap((entry) => {
+      const occurrence = getOccurrence(controllerHome, repoId, entry.occurrenceId);
+      return occurrence ? [occurrence] : [];
+    });
+  if (indexed.length > 0) return indexed;
+
+  const root = join(schedulesRoot(controllerHome, repoId), 'occurrences');
+  try {
+    const legacy = readdirSync(root).filter((name) => name.endsWith('.json'))
+      .map((name) => readJsonFile<ScheduleOccurrence>(join(root, name)))
+      .filter((entry) => !scheduleId || entry.scheduleId === scheduleId)
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .slice(0, bounded);
+    if (legacy.length > 0) {
+      withControllerLock(controllerHome, { scope: 'repository', repoId }, `schedule-index-backfill:${repoId}`, () => {
+        for (const occurrence of legacy) upsertOccurrenceIndexUnlocked(controllerHome, occurrence);
+      }, 10_000);
+    }
+    return legacy;
+  } catch { return []; }
+}
+
+
+export function saveScheduleDecision(controllerHome: string, decision: ScheduleDecision): ScheduleDecision {
+  return withControllerLock(controllerHome, { scope: 'task', repoId: decision.repoId, taskId: `schedule-${decision.scheduleId}` }, `save-schedule-decision:${decision.decisionId}`, () => {
+    const path = decisionPath(controllerHome, decision.repoId, decision.decisionId);
+    if (existsSync(path)) return readJsonFile<ScheduleDecision>(path);
+    writeJsonAtomic(path, decision);
+    appendRuntimeEvent(controllerHome, {
+      repoId: decision.repoId,
+      entityType: 'schedule-decision',
+      entityId: decision.decisionId,
+      eventType: `schedule_decision_${decision.decision}`,
+      requestId: decision.requestId,
+      revision: decision.revision,
+      correlationId: decision.occurrenceId,
+      data: { scheduleId: decision.scheduleId, reason: decision.reason, evidence: decision.evidence },
+    });
+    return decision;
+  }, 10_000);
+}
+
+export function getScheduleDecision(controllerHome: string, repoId: string, decisionId: string): ScheduleDecision | undefined {
+  const path = decisionPath(controllerHome, repoId, decisionId);
+  return existsSync(path) ? readJsonFile<ScheduleDecision>(path) : undefined;
+}
+
+
+export interface ScheduleDuplicateMember {
+  scheduleId: string;
+  name: string;
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+  keep: boolean;
+  reason: string;
+}
+
+export interface ScheduleDuplicateGroup {
+  semanticKey: string;
+  scheduleIds: string[];
+  names: string[];
+  enabledCount: number;
+  keepScheduleId: string;
+  members: ScheduleDuplicateMember[];
+  recommendation: string;
+}
+
+export interface ScheduleDedupeReport {
+  repoId: string;
+  generatedAt: string;
+  totalSchedules: number;
+  duplicateGroups: ScheduleDuplicateGroup[];
+  proposedDisableCount: number;
+}
+
+export interface ScheduleDedupeApplyResult {
+  repoId: string;
+  appliedAt: string;
+  dryRun: boolean;
+  report: ScheduleDedupeReport;
+  disabled: Array<{ scheduleId: string; previousEnabled: boolean; pausedReason?: string }>;
+}
+
+function scheduleDedupeKey(schedule: RepositorySchedule): string {
+  return createHash('sha256').update(JSON.stringify(canonical({
+    repoId: schedule.repoId,
+    name: schedule.name.trim().toLowerCase(),
+    trigger: schedule.trigger,
+    policy: schedule.policy,
+    action: schedule.action,
+    stopConditions: schedule.stopConditions,
+  }))).digest('hex');
+}
+
+function chooseScheduleToKeep(entries: RepositorySchedule[]): RepositorySchedule {
+  const enabled = entries.filter((entry) => entry.enabled);
+  const pool = enabled.length > 0 ? enabled : entries;
+  return [...pool].sort((left, right) => {
+    const triggered = String(right.lastTriggeredAt ?? '').localeCompare(String(left.lastTriggeredAt ?? ''));
+    if (triggered !== 0) return triggered;
+    return right.updatedAt.localeCompare(left.updatedAt) || right.createdAt.localeCompare(left.createdAt);
+  })[0]!;
+}
+
+function duplicateGroup(semanticKey: string, entries: RepositorySchedule[]): ScheduleDuplicateGroup {
+  const keep = chooseScheduleToKeep(entries);
+  const members = [...entries]
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+    .map((entry) => ({
+      scheduleId: entry.scheduleId,
+      name: entry.name,
+      enabled: entry.enabled,
+      createdAt: entry.createdAt,
+      updatedAt: entry.updatedAt,
+      keep: entry.scheduleId === keep.scheduleId,
+      reason: entry.scheduleId === keep.scheduleId
+        ? 'newest enabled duplicate selected as canonical schedule'
+        : entry.enabled ? 'enabled duplicate should be paused to prevent repeated execution' : 'already disabled duplicate',
+    }));
+  return {
+    semanticKey,
+    scheduleIds: entries.map((entry) => entry.scheduleId),
+    names: [...new Set(entries.map((entry) => entry.name))],
+    enabledCount: entries.filter((entry) => entry.enabled).length,
+    keepScheduleId: keep.scheduleId,
+    members,
+    recommendation: 'Keep one canonical schedule enabled and pause older enabled duplicates with a dedupe reason.',
+  };
+}
+
+export function buildScheduleDedupeReport(controllerHome: string, repoId: string): ScheduleDedupeReport {
+  const schedules = listSchedules(controllerHome, repoId);
+  const groups = new Map<string, RepositorySchedule[]>();
+  for (const schedule of schedules) {
+    const key = scheduleDedupeKey(schedule);
+    groups.set(key, [...(groups.get(key) ?? []), schedule]);
+  }
+  const duplicateGroups = [...groups.entries()]
+    .filter(([, entries]) => entries.length > 1)
+    .map(([semanticKey, entries]) => duplicateGroup(semanticKey, entries))
+    .sort((left, right) => right.scheduleIds.length - left.scheduleIds.length);
+  const proposedDisableCount = duplicateGroups.reduce((sum, group) => sum + group.members.filter((member) => member.enabled && !member.keep).length, 0);
+  return { repoId, generatedAt: new Date().toISOString(), totalSchedules: schedules.length, duplicateGroups, proposedDisableCount };
+}
+
+export function applyScheduleDedupe(controllerHome: string, repoId: string, input: { dryRun?: unknown; confirmAuthorization?: unknown } = {}): ScheduleDedupeApplyResult {
+  const dryRun = input.dryRun === true;
+  if (!dryRun && input.confirmAuthorization !== true) throw new Error('SCHEDULE_DEDUPE_AUTHORIZATION_REQUIRED: confirm_authorization must be true to pause duplicate schedules');
+  return withControllerLock(controllerHome, { scope: 'task', repoId, taskId: 'schedule-dedupe' }, `schedule-dedupe:${repoId}`, () => {
+    const report = buildScheduleDedupeReport(controllerHome, repoId);
+    const disabled: ScheduleDedupeApplyResult['disabled'] = [];
+    if (!dryRun) {
+      for (const group of report.duplicateGroups) {
+        for (const member of group.members) {
+          if (member.keep || !member.enabled) continue;
+          const current = getSchedule(controllerHome, repoId, member.scheduleId);
+          const previousEnabled = current.enabled;
+          const pausedReason = `duplicate schedule paused by schedule_dedupe_apply; kept ${group.keepScheduleId}`;
+          saveSchedule(controllerHome, { ...current, enabled: false, pausedReason });
+          disabled.push({ scheduleId: current.scheduleId, previousEnabled, pausedReason });
+        }
+      }
+    }
+    return { repoId, appliedAt: new Date().toISOString(), dryRun, report, disabled };
+  }, 10_000);
+}

package/src/runtime/workflow/schedules/types.ts

@@ -0,0 +1,124 @@
+import type { ExecutionJobPriority, ResourceClaimSpec } from '../../execution/jobs/types';
+
+export type ScheduleTriggerType =
+  | 'interval'
+  | 'cron'
+  | 'calendar'
+  | 'condition'
+  | 'repository-event'
+  | 'dependency-checkpoint'
+  | 'manual';
+
+export interface ScheduleCondition {
+  kind: 'repository_clean' | 'job_succeeded' | 'job_terminal' | 'candidate_observation_threshold';
+  jobId?: string;
+  semanticKey?: string;
+  observationThreshold?: number;
+}
+
+export interface ScheduleTrigger {
+  type: ScheduleTriggerType;
+  everyMinutes?: number;
+  cronExpression?: string;
+  timezone?: string;
+  catchUpMinutes?: number;
+  calendarAt?: string;
+  condition?: ScheduleCondition;
+  eventName?: string;
+  dependencyJobIds?: string[];
+}
+
+export interface ScheduleTriggerContext {
+  source?: 'timer' | 'manual' | 'repository-event' | 'dependency-checkpoint' | 'condition';
+  eventName?: string;
+  eventId?: string;
+  data?: Record<string, unknown>;
+}
+
+export interface SchedulePolicy {
+  maxActiveOccurrences: number;
+  maxFailures: number;
+  cooldownMinutes: number;
+  dailyBudgetMinutes: number;
+  shadowMode: boolean;
+  backoffBaseMinutes?: number;
+  backoffMaxMinutes?: number;
+}
+
+export interface ScheduleAction {
+  operation: string;
+  target?: 'repository-tool' | 'mcp-tool' | 'runtime' | 'workspace-agent';
+  arguments?: Record<string, unknown>;
+  priority?: ExecutionJobPriority;
+  resourceClaims?: ResourceClaimSpec[];
+}
+
+export interface RepositorySchedule {
+  schemaVersion: 1;
+  revision: number;
+  scheduleId: string;
+  requestId: string;
+  repoId: string;
+  name: string;
+  enabled: boolean;
+  trigger: ScheduleTrigger;
+  policy: SchedulePolicy;
+  action: ScheduleAction;
+  stopConditions: string[];
+  createdAt: string;
+  updatedAt: string;
+  lastTriggeredAt?: string;
+  lastOccurrenceId?: string;
+  consecutiveFailures: number;
+  consecutiveNoops?: number;
+  nextEligibleAt?: string;
+  pausedReason?: string;
+}
+
+export type ScheduleDecisionType =
+  | 'nothing_to_do'
+  | 'would_execute'
+  | 'execute'
+  | 'cooldown'
+  | 'budget_exhausted'
+  | 'active_occurrence'
+  | 'stopped'
+  | 'operation_blocked'
+  | 'maintenance_not_ready'
+  | 'trigger_not_due'
+  | 'condition_not_met'
+  | 'dependency_not_ready'
+  | 'event_not_matched';
+
+export interface ScheduleDecision {
+  schemaVersion: 1;
+  revision: number;
+  decisionId: string;
+  occurrenceId: string;
+  scheduleId: string;
+  repoId: string;
+  requestId: string;
+  decision: ScheduleDecisionType;
+  reason?: string;
+  triggerContext?: ScheduleTriggerContext;
+  evidence?: Record<string, unknown>;
+  createdAt: string;
+}
+
+export interface ScheduleOccurrence {
+  schemaVersion: 1;
+  revision: number;
+  occurrenceId: string;
+  scheduleId: string;
+  repoId: string;
+  windowKey: string;
+  status: 'created' | 'shadowed' | 'queued' | 'running' | 'succeeded' | 'failed' | 'skipped';
+  decision: ScheduleDecisionType;
+  decisionId?: string;
+  triggerContext?: ScheduleTriggerContext;
+  createdAt: string;
+  updatedAt: string;
+  jobId?: string;
+  handoffId?: string;
+  reason?: string;
+}