@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/scheduler/infrastructure/schedule-store.ts

@@ -0,0 +1,805 @@
+import { createHash, randomUUID } from 'crypto';
+import { existsSync, readdirSync, rmSync, statSync } from 'fs';
+import { join } from 'path';
+import { controllerSystemRoot, repositoryControllerRoot } from '../../../../src/cli/repositories/controller-home';
+import { withControllerLock } from '../../../../src/cli/repositories/locks';
+import {
+  createHandoffItem,
+  getHandoffItem,
+  listHandoffItems,
+  resolveHandoffItem,
+} from '../../../../src/runtime/control-plane/facade/handoff-inbox-store';
+import { readJsonFile, writeJsonAtomic } from '../../../../src/runtime/shared/json-files';
+import { appendRuntimeEvent } from '../../../../src/runtime/evidence/event-ledger';
+import { type RepositorySchedule, type ScheduleDecision, type ScheduleOccurrence, type ScheduleDefinition, type ScheduleRuntimeState, extractScheduleDefinition, extractScheduleRuntimeState } from '../domain/schedule';
+
+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;
+}
+
+class ScheduleStoreError extends Error {
+  readonly code: 'SCHEDULE_REPOSITORY_PROVENANCE_MISMATCH';
+  readonly scheduleId: string;
+
+  constructor(scheduleId: string) {
+    super(`SCHEDULE_REPOSITORY_PROVENANCE_MISMATCH: ${scheduleId}`);
+    this.name = 'ScheduleStoreError';
+    this.code = 'SCHEDULE_REPOSITORY_PROVENANCE_MISMATCH';
+    this.scheduleId = scheduleId;
+  }
+}
+
+type CreateScheduleInput = Omit<RepositorySchedule, 'schemaVersion' | 'revision' | 'scheduleId' | 'createdAt' | 'updatedAt' | 'consecutiveFailures'>;
+type ScheduleMutableUpdate = Partial<Omit<RepositorySchedule, 'schemaVersion' | 'revision' | 'scheduleId' | 'repoId' | 'requestId' | 'createdAt' | 'updatedAt'>>;
+
+export interface ScheduleOccurrenceHandoffInput {
+  title: string;
+  summary: string;
+  reason: string;
+  creationReason: 'ambiguous_outcome' | 'missing_authorization';
+  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): string {
+  return join(controllerSystemRoot(controllerHome), 'schedules');
+}
+function legacySchedulesRoot(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'schedules');
+}
+function schedulePath(controllerHome: string, _repoId: string, scheduleId: string): string {
+  return join(schedulesRoot(controllerHome), 'records', `${scheduleId}.json`);
+}
+function legacySchedulePath(controllerHome: string, repoId: string, scheduleId: string): string {
+  return join(legacySchedulesRoot(controllerHome, repoId), 'records', `${scheduleId}.json`);
+}
+function occurrencePath(controllerHome: string, _repoId: string, occurrenceId: string): string {
+  return join(schedulesRoot(controllerHome), 'occurrences', `${occurrenceId}.json`);
+}
+function legacyOccurrencePath(controllerHome: string, repoId: string, occurrenceId: string): string {
+  return join(legacySchedulesRoot(controllerHome, repoId), 'occurrences', `${occurrenceId}.json`);
+}
+function decisionPath(controllerHome: string, _repoId: string, decisionId: string): string {
+  return join(schedulesRoot(controllerHome), 'decisions', `${decisionId}.json`);
+}
+function legacyDecisionPath(controllerHome: string, repoId: string, decisionId: string): string {
+  return join(legacySchedulesRoot(controllerHome, repoId), 'decisions', `${decisionId}.json`);
+}
+function occurrenceIndexPath(controllerHome: string, repoId: string): string {
+  const key = createHash('sha256').update(repoId).digest('hex').slice(0, 24);
+  return join(schedulesRoot(controllerHome), 'indexes', 'occurrences', `${key}.json`);
+}
+function requestTargetKey(input: Pick<RepositorySchedule, 'repoId' | 'scopeRef' | 'executionPlacement' | 'action'>): string {
+  return createHash('sha256').update(JSON.stringify(canonical({
+    scopeRef: input.scopeRef,
+    executionPlacement: input.executionPlacement,
+    repoId: input.repoId,
+    actionTarget: input.action.target,
+    operation: input.action.operation,
+  }))).digest('hex');
+}
+function requestPath(controllerHome: string, targetKey: string, requestId: string): string {
+  return join(schedulesRoot(controllerHome), 'indexes', 'requests', targetKey, `${createHash('sha256').update(requestId).digest('hex')}.json`);
+}
+
+export const SCHEDULE_OCCURRENCE_RECENT_LIMIT = 5_000;
+export const SCHEDULE_CREATED_OCCURRENCE_STALE_MS = 5 * 60 * 1_000;
+
+const EXTERNAL_CONTROLLER_WAKE_MAX_FAILURES = 3;
+const EXTERNAL_CONTROLLER_WAKE_DAILY_BUDGET_MINUTES = 60;
+const EXTERNAL_CONTROLLER_WAKE_MIN_COOLDOWN_MINUTES = 10;
+
+function boundedSchedulePolicy(schedule: RepositorySchedule): RepositorySchedule['policy'] {
+  const policy = {
+    ...schedule.policy,
+    backoffBaseMinutes: Math.max(1, schedule.policy.backoffBaseMinutes ?? schedule.policy.cooldownMinutes ?? 1),
+    backoffMaxMinutes: Math.max(1, schedule.policy.backoffMaxMinutes ?? 24 * 60),
+  };
+  if (schedule.action.operation !== 'external_controller_wake') return policy;
+  // A Work-bound controller wake is expensive and can affect the user's
+  // provider. No schedule payload may convert a transient tool outage into an
+  // all-day retry loop. Larger work needs an explicit future user action after
+  // the bounded lane records useful failure evidence.
+  return {
+    ...policy,
+    maxFailures: Math.max(1, Math.min(policy.maxFailures, EXTERNAL_CONTROLLER_WAKE_MAX_FAILURES)),
+    dailyBudgetMinutes: Math.max(1, Math.min(policy.dailyBudgetMinutes, EXTERNAL_CONTROLLER_WAKE_DAILY_BUDGET_MINUTES)),
+    cooldownMinutes: Math.max(policy.cooldownMinutes, EXTERNAL_CONTROLLER_WAKE_MIN_COOLDOWN_MINUTES),
+    backoffBaseMinutes: Math.max(policy.backoffBaseMinutes, EXTERNAL_CONTROLLER_WAKE_MIN_COOLDOWN_MINUTES),
+  };
+}
+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(-SCHEDULE_OCCURRENCE_RECENT_LIMIT);
+  index.recent = index.recent.slice(0, SCHEDULE_OCCURRENCE_RECENT_LIMIT);
+  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);
+  const targetKey = requestTargetKey(input);
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule-request:${targetKey}:${createHash('sha256').update(requestId).digest('hex').slice(0, 16)}` }, `create-schedule:${requestId}`, () => {
+    const requestRecordPath = requestPath(controllerHome, targetKey, 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 canonicalPath = schedulePath(controllerHome, repoId, scheduleId);
+  const legacyPath = legacySchedulePath(controllerHome, repoId, scheduleId);
+  const canonicalSchedule = existsSync(canonicalPath) ? readJsonFile<RepositorySchedule>(canonicalPath) : undefined;
+  const legacySchedule = existsSync(legacyPath) ? readJsonFile<RepositorySchedule>(legacyPath) : undefined;
+  if (canonicalSchedule && legacySchedule && JSON.stringify(canonicalSchedule) !== JSON.stringify(legacySchedule)) {
+    const canonicalRevision = Number.isFinite(canonicalSchedule.revision) ? canonicalSchedule.revision : 1;
+    const legacyRevision = Number.isFinite(legacySchedule.revision) ? legacySchedule.revision : 1;
+    if (canonicalRevision <= legacyRevision) throw new Error(`SCHEDULE_ID_COLLISION: ${scheduleId}`);
+  }
+  const schedule = canonicalSchedule ?? legacySchedule;
+  if (!schedule) throw new Error(`SCHEDULE_NOT_FOUND: ${scheduleId}`);
+  if (schedule.repoId !== repoId) throw new ScheduleStoreError(scheduleId);
+  return {
+    ...schedule,
+    revision: Number.isFinite(schedule.revision) ? schedule.revision : 1,
+    requestId: schedule.requestId || `legacy-schedule:${schedule.scheduleId}`,
+    policy: boundedSchedulePolicy(schedule),
+    consecutiveNoops: Math.max(0, schedule.consecutiveNoops ?? 0),
+  };
+}
+
+function persistScheduleRevision(
+  controllerHome: string,
+  current: RepositorySchedule,
+  candidate: RepositorySchedule,
+): RepositorySchedule {
+  const next: RepositorySchedule = {
+    ...candidate,
+    schemaVersion: current.schemaVersion,
+    revision: current.revision + 1,
+    scheduleId: current.scheduleId,
+    repoId: current.repoId,
+    requestId: current.requestId,
+    createdAt: current.createdAt,
+    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;
+}
+
+/**
+ * Persist a caller-owned Schedule snapshot only when its revision is still the
+ * current authority. User/configuration mutations use this path so stale
+ * writers fail closed instead of overwriting a newer decision.
+ */
+export function saveSchedule(controllerHome: string, schedule: RepositorySchedule): RepositorySchedule {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${schedule.scheduleId}` }, `save-schedule:${schedule.scheduleId}`, () => {
+    const current = getSchedule(controllerHome, schedule.repoId, schedule.scheduleId);
+    if (schedule.revision !== current.revision) {
+      throw new Error(`SCHEDULE_REVISION_CONFLICT: ${schedule.scheduleId}:expected=${schedule.revision}:actual=${current.revision}`);
+    }
+    return persistScheduleRevision(controllerHome, current, schedule);
+  }, 10_000);
+}
+
+/**
+ * Apply runtime-owned settlement/observation fields to the latest Schedule
+ * authority while holding the Schedule lock. Identity and revision fields are
+ * never writable through this path. Long-running occurrences use this instead
+ * of replaying a stale whole-record snapshot after user state may have changed.
+ */
+export function updateSchedule(
+  controllerHome: string,
+  repoId: string,
+  scheduleId: string,
+  update: (current: RepositorySchedule) => ScheduleMutableUpdate,
+): RepositorySchedule {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${scheduleId}` }, `update-schedule:${scheduleId}`, () => {
+    const current = getSchedule(controllerHome, repoId, scheduleId);
+    const changes = update(current);
+    return persistScheduleRevision(controllerHome, current, { ...current, ...changes });
+  }, 10_000);
+}
+
+export function listSchedules(controllerHome: string, repoId: string): RepositorySchedule[] {
+  const ids = new Set<string>();
+  for (const root of [join(schedulesRoot(controllerHome), 'records'), join(legacySchedulesRoot(controllerHome, repoId), 'records')]) {
+    try {
+      for (const name of readdirSync(root)) if (name.endsWith('.json')) ids.add(name.slice(0, -'.json'.length));
+    } catch { /* missing storage root is empty */ }
+  }
+  return [...ids]
+    .flatMap((scheduleId) => {
+      try {
+        const schedule = getSchedule(controllerHome, repoId, scheduleId);
+        return schedule.repoId === repoId ? [schedule] : [];
+      } catch (error) {
+        if (error instanceof ScheduleStoreError && error.code === 'SCHEDULE_REPOSITORY_PROVENANCE_MISMATCH') return [];
+        throw error;
+      }
+    })
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+export function deleteSchedule(controllerHome: string, repoId: string, scheduleId: string): RepositorySchedule {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${scheduleId}` }, `delete-schedule:${scheduleId}`, () => {
+    const current = getSchedule(controllerHome, repoId, scheduleId);
+    if (current.enabled) throw new Error(`SCHEDULE_DELETE_REQUIRES_PAUSED: ${scheduleId}`);
+    if (listActiveOccurrences(controllerHome, repoId, scheduleId).length > 0) {
+      throw new Error(`SCHEDULE_DELETE_ACTIVE_OCCURRENCE: ${scheduleId}`);
+    }
+    rmSync(schedulePath(controllerHome, repoId, scheduleId), { force: true });
+    const requestRecordPath = requestPath(controllerHome, requestTargetKey(current), current.requestId);
+    if (existsSync(requestRecordPath)) {
+      const record = readJsonFile<ScheduleRequestRecord>(requestRecordPath);
+      if (record.scheduleId === scheduleId) rmSync(requestRecordPath, { force: true });
+    }
+    appendRuntimeEvent(controllerHome, {
+      repoId,
+      entityType: 'schedule',
+      entityId: scheduleId,
+      eventType: 'schedule_deleted',
+      requestId: current.requestId,
+      revision: current.revision + 1,
+      data: { name: current.name },
+    });
+    return current;
+  }, 10_000);
+}
+
+export function saveOccurrence(controllerHome: string, occurrence: ScheduleOccurrence): ScheduleOccurrence {
+  const next = withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${occurrence.scheduleId}` }, `save-occurrence:${occurrence.occurrenceId}`, () => {
+    const existingPath = occurrencePath(controllerHome, occurrence.repoId, occurrence.occurrenceId);
+    const previous = existsSync(existingPath) ? readJsonFile<ScheduleOccurrence>(existingPath) : undefined;
+    const expectedRevision = previous?.revision ?? 0;
+    if (occurrence.revision !== expectedRevision) {
+      throw new Error(`SCHEDULE_OCCURRENCE_REVISION_CONFLICT: ${occurrence.occurrenceId}:expected=${occurrence.revision}:actual=${expectedRevision}`);
+    }
+    const saved = { ...occurrence, revision: expectedRevision + 1, updatedAt: new Date().toISOString() };
+    writeJsonAtomic(existingPath, saved);
+    upsertOccurrenceIndexUnlocked(controllerHome, saved);
+    const schedule = getSchedule(controllerHome, saved.repoId, saved.scheduleId);
+    appendRuntimeEvent(controllerHome, { repoId: saved.repoId, entityType: 'occurrence', entityId: saved.occurrenceId, eventType: `occurrence_${saved.status}`, requestId: `${schedule.requestId}:${saved.windowKey}`, revision: saved.revision, correlationId: saved.scheduleId, data: { decision: saved.decision, jobId: saved.jobId, reason: saved.reason } });
+    return saved;
+  }, 10_000);
+  return next;
+}
+
+export function getOccurrence(controllerHome: string, repoId: string, occurrenceId: string): ScheduleOccurrence | undefined {
+  const canonicalPath = occurrencePath(controllerHome, repoId, occurrenceId);
+  if (existsSync(canonicalPath)) {
+    const occurrence = readJsonFile<ScheduleOccurrence>(canonicalPath);
+    return occurrence.repoId === repoId ? occurrence : undefined;
+  }
+  const legacyPath = legacyOccurrencePath(controllerHome, repoId, occurrenceId);
+  return existsSync(legacyPath) ? readJsonFile<ScheduleOccurrence>(legacyPath) : 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] : [];
+    });
+}
+
+/**
+ * A created occurrence must be settled by the same evaluateSchedule call that
+ * creates it. If the process dies or an early Controller/Supervisor exception
+ * escapes before that settlement, leaving it active permanently blocks the
+ * schedule's maxActiveOccurrences admission. Reclaim only old `created`
+ * records; queued/running work remains owned by the normal worker recovery
+ * path.
+ */
+export function reclaimStaleCreatedOccurrences(
+  controllerHome: string,
+  repoId: string,
+  scheduleId: string,
+  nowMs = Date.now(),
+  staleAfterMs = SCHEDULE_CREATED_OCCURRENCE_STALE_MS,
+): ScheduleOccurrence[] {
+  const threshold = Math.max(1_000, staleAfterMs);
+  return listActiveOccurrences(controllerHome, repoId, scheduleId)
+    .filter((occurrence) => occurrence.status === 'created')
+    .filter((occurrence) => {
+      const createdAt = Date.parse(occurrence.createdAt);
+      return Number.isFinite(createdAt) && nowMs - createdAt >= threshold;
+    })
+    .map((occurrence) => saveOccurrence(controllerHome, {
+      ...occurrence,
+      status: 'skipped',
+      decision: 'operation_blocked',
+      reason: `Orphaned created occurrence reclaimed after ${threshold}ms without Scheduler settlement.`,
+    }));
+}
+
+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 roots = [join(schedulesRoot(controllerHome), 'occurrences'), join(legacySchedulesRoot(controllerHome, repoId), 'occurrences')];
+  try {
+    const legacy = roots.flatMap((root) => {
+      try { return readdirSync(root).filter((name) => name.endsWith('.json')).map((name) => readJsonFile<ScheduleOccurrence>(join(root, name))); }
+      catch { return []; }
+    })
+      .filter((entry) => !scheduleId || entry.scheduleId === scheduleId)
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .slice(0, bounded);
+    if (legacy.length > 0) {
+      withControllerLock(controllerHome, { scope: 'global', resource: `schedule-index:${repoId}` }, `schedule-index-backfill:${repoId}`, () => {
+        for (const occurrence of legacy) upsertOccurrenceIndexUnlocked(controllerHome, occurrence);
+      }, 10_000);
+    }
+    return legacy;
+  } catch { return []; }
+}
+
+
+export interface ScheduleHistoryCleanupResult {
+  removedOccurrencePaths: string[];
+  removedDecisionPaths: string[];
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  inspected: number;
+  eligible: number;
+  attempted: number;
+  retained: number;
+  budgetExhausted: boolean;
+  skippedByReason: Record<string, number>;
+  errors: string[];
+}
+
+function retainedOccurrenceIds(index: OccurrenceIndex): Set<string> {
+  return new Set([...index.active, ...index.recent].map((entry) => entry.occurrenceId));
+}
+
+function activeOccurrenceStatus(status: ScheduleOccurrence['status']): boolean {
+  return status === 'created' || status === 'queued' || status === 'running';
+}
+
+/**
+ * Reclaim Scheduler history that has already fallen outside the bounded recent
+ * index. Runtime maintenance decides when cleanup runs; Scheduler storage owns
+ * the mutation and re-checks the same per-schedule task lock used by
+ * saveOccurrence so a concurrent occurrence can never be deleted from a stale
+ * directory scan.
+ */
+export function cleanupScheduleOccurrenceHistory(
+  controllerHome: string,
+  repoId: string,
+  input: { maxEntries?: number; maxRemovals?: number } = {},
+): ScheduleHistoryCleanupResult {
+  const maxEntries = Math.max(1, Math.trunc(input.maxEntries ?? 2_000));
+  const maxRemovals = Math.max(0, Math.trunc(input.maxRemovals ?? 50));
+  const result: ScheduleHistoryCleanupResult = {
+    removedOccurrencePaths: [],
+    removedDecisionPaths: [],
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+    inspected: 0,
+    eligible: 0,
+    attempted: 0,
+    retained: 0,
+    budgetExhausted: false,
+    skippedByReason: {},
+    errors: [],
+  };
+  const skip = (reason: string) => {
+    result.retained += 1;
+    result.skippedByReason[reason] = (result.skippedByReason[reason] ?? 0) + 1;
+  };
+  const recordRemoval = (path: string, kind: 'occurrence' | 'decision') => {
+    try { result.reclaimedBytes += statSync(path).size; }
+    catch { result.unknownReclaimedByteCount += 1; }
+    rmSync(path, { force: true });
+    const relativePath = kind === 'occurrence'
+      ? `occurrences/${path.split('/').pop()}`
+      : `decisions/${path.split('/').pop()}`;
+    if (kind === 'occurrence') result.removedOccurrencePaths.push(relativePath);
+    else result.removedDecisionPaths.push(relativePath);
+  };
+  const canInspect = () => {
+    if (result.inspected >= maxEntries) {
+      result.budgetExhausted = true;
+      return false;
+    }
+    result.inspected += 1;
+    return true;
+  };
+  const canRemove = () => {
+    if (result.attempted >= maxRemovals) {
+      result.budgetExhausted = true;
+      return false;
+    }
+    result.attempted += 1;
+    return true;
+  };
+
+  const occurrenceRoot = join(schedulesRoot(controllerHome), 'occurrences');
+  let occurrenceNames: string[] = [];
+  try { occurrenceNames = readdirSync(occurrenceRoot).filter((name) => name.endsWith('.json')).sort(); }
+  catch { occurrenceNames = []; }
+  for (const name of occurrenceNames) {
+    if (!canInspect()) break;
+    const occurrenceId = name.slice(0, -'.json'.length);
+    if (retainedOccurrenceIds(readOccurrenceIndex(controllerHome, repoId)).has(occurrenceId)) {
+      skip('indexed_occurrence');
+      continue;
+    }
+    const path = join(occurrenceRoot, name);
+    let occurrence: ScheduleOccurrence;
+    try { occurrence = readJsonFile<ScheduleOccurrence>(path); }
+    catch (error) {
+      result.errors.push(`occurrence_unreadable:${name}:${error instanceof Error ? error.message : String(error)}`);
+      skip('occurrence_unreadable');
+      continue;
+    }
+    if (activeOccurrenceStatus(occurrence.status)) {
+      skip('active_occurrence_unindexed');
+      continue;
+    }
+    if (!canRemove()) break;
+    try {
+      withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${occurrence.scheduleId}` }, `cleanup-schedule-occurrence:${occurrence.occurrenceId}`, () => {
+        if (retainedOccurrenceIds(readOccurrenceIndex(controllerHome, repoId)).has(occurrence.occurrenceId)) {
+          skip('indexed_occurrence_recheck');
+          return;
+        }
+        const current = getOccurrence(controllerHome, repoId, occurrence.occurrenceId);
+        if (!current) return;
+        if (activeOccurrenceStatus(current.status)) {
+          skip('active_occurrence_recheck');
+          return;
+        }
+        result.eligible += 1;
+        recordRemoval(path, 'occurrence');
+      }, 10_000);
+    } catch (error) {
+      result.errors.push(`occurrence_cleanup_blocked:${name}:${error instanceof Error ? error.message : String(error)}`);
+      skip('schedule_lock_or_cleanup_error');
+    }
+  }
+
+  const decisionRoot = join(schedulesRoot(controllerHome), 'decisions');
+  let decisionNames: string[] = [];
+  try { decisionNames = readdirSync(decisionRoot).filter((name) => name.endsWith('.json')).sort(); }
+  catch { decisionNames = []; }
+  for (const name of decisionNames) {
+    if (!canInspect()) break;
+    const path = join(decisionRoot, name);
+    let decision: ScheduleDecision;
+    try { decision = readJsonFile<ScheduleDecision>(path); }
+    catch (error) {
+      result.errors.push(`decision_unreadable:${name}:${error instanceof Error ? error.message : String(error)}`);
+      skip('decision_unreadable');
+      continue;
+    }
+    if (retainedOccurrenceIds(readOccurrenceIndex(controllerHome, repoId)).has(decision.occurrenceId)) {
+      skip('indexed_decision_occurrence');
+      continue;
+    }
+    // Keep the decision paired with its occurrence until the occurrence itself
+    // is safely reclaimed. A failed/blocked occurrence cleanup therefore never
+    // leaves a partial history deletion.
+    if (getOccurrence(controllerHome, repoId, decision.occurrenceId)) {
+      skip('decision_occurrence_still_present');
+      continue;
+    }
+    if (!canRemove()) break;
+    try {
+      withControllerLock(controllerHome, { scope: 'global', resource: `schedule:${decision.scheduleId}` }, `cleanup-schedule-decision:${decision.decisionId}`, () => {
+        if (retainedOccurrenceIds(readOccurrenceIndex(controllerHome, repoId)).has(decision.occurrenceId)) {
+          skip('indexed_decision_recheck');
+          return;
+        }
+        if (getOccurrence(controllerHome, repoId, decision.occurrenceId)) {
+          skip('decision_occurrence_reappeared');
+          return;
+        }
+        if (!existsSync(path)) return;
+        result.eligible += 1;
+        recordRemoval(path, 'decision');
+      }, 10_000);
+    } catch (error) {
+      result.errors.push(`decision_cleanup_blocked:${name}:${error instanceof Error ? error.message : String(error)}`);
+      skip('schedule_lock_or_cleanup_error');
+    }
+  }
+  result.removedOccurrencePaths.sort();
+  result.removedDecisionPaths.sort();
+  return result;
+}
+
+
+export function saveScheduleDecision(controllerHome: string, decision: ScheduleDecision): ScheduleDecision {
+  return withControllerLock(controllerHome, { scope: 'global', resource: `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 canonicalPath = decisionPath(controllerHome, repoId, decisionId);
+  if (existsSync(canonicalPath)) {
+    const decision = readJsonFile<ScheduleDecision>(canonicalPath);
+    return decision.repoId === repoId ? decision : undefined;
+  }
+  const legacyPath = legacyDecisionPath(controllerHome, repoId, decisionId);
+  return existsSync(legacyPath) ? readJsonFile<ScheduleDecision>(legacyPath) : 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: 'global', resource: `schedule-dedupe:${repoId}` }, `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);
+}
+
+export function getScheduleDefinition(controllerHome: string, repoId: string, scheduleId: string): ScheduleDefinition {
+  const schedule = getSchedule(controllerHome, repoId, scheduleId);
+  return extractScheduleDefinition(schedule);
+}
+
+export function getScheduleRuntimeState(controllerHome: string, repoId: string, scheduleId: string): ScheduleRuntimeState {
+  const schedule = getSchedule(controllerHome, repoId, scheduleId);
+  return extractScheduleRuntimeState(schedule);
+}