@moretea-labs/forge 1.5.0-rc.1

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

@@ -0,0 +1,620 @@
+import { createHash, randomUUID } from 'crypto';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { getRepository } from '../../../cli/repositories/registry';
+import { findExecutionJob, listActiveExecutionJobs, listExecutionJobs } from '../../execution/jobs/store';
+import { readRepositoryProjection } from '../../projections/materialized-view';
+import {
+  applyRuntimeMaintenance,
+  previewAutomaticRuntimeMaintenance,
+  type RuntimeMaintenanceActionId,
+} from '../../recovery/maintenance-executor';
+import { listCandidateFindings } from '../findings/store';
+import {
+  getOccurrence,
+  getSchedule,
+  listActiveOccurrences,
+  listOccurrences,
+  recordScheduleOccurrenceHandoff,
+  listSchedules,
+  saveOccurrence,
+  saveSchedule,
+  saveScheduleDecision,
+} from './store';
+import { applyScheduleFailure } from './settlement';
+import type {
+  RepositorySchedule,
+  ScheduleDecisionType,
+  ScheduleOccurrence,
+  ScheduleTriggerContext,
+} from './types';
+
+const execFileAsync = promisify(execFile);
+const LIVE_MAINTENANCE_OPERATION = 'runtime_maintenance_apply';
+
+function isDeterministicSchedule(schedule: RepositorySchedule): boolean {
+  // Kernel may execute only fully deterministic, allowlisted schedule operations.
+  // Semantic / model-backed schedules remain external-controller handoffs.
+  return schedule.action.operation === LIVE_MAINTENANCE_OPERATION;
+}
+
+function normalizedWindow(minutes: number, at = Date.now()): string {
+  return String(Math.floor(at / (Math.max(1, minutes) * 60_000)));
+}
+
+interface ZonedDateParts {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  weekday: number;
+}
+
+function zonedDateParts(at: number, timezone = 'UTC'): ZonedDateParts {
+  let formatter: Intl.DateTimeFormat;
+  try {
+    formatter = new Intl.DateTimeFormat('en-US-u-ca-iso8601', {
+      timeZone: timezone,
+      year: 'numeric', month: '2-digit', day: '2-digit',
+      hour: '2-digit', minute: '2-digit', weekday: 'short',
+      hourCycle: 'h23',
+    });
+  } catch {
+    throw new Error(`SCHEDULE_TIMEZONE_INVALID: ${timezone}`);
+  }
+  const values = Object.fromEntries(formatter.formatToParts(new Date(at)).map((entry) => [entry.type, entry.value]));
+  const weekdays: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  return {
+    year: Number(values.year),
+    month: Number(values.month),
+    day: Number(values.day),
+    hour: Number(values.hour),
+    minute: Number(values.minute),
+    weekday: weekdays[String(values.weekday)] ?? 0,
+  };
+}
+
+function fixedCronTime(expression: string | undefined): { minute: number; hour: number; day: string; month: string; weekday: string } | undefined {
+  if (!expression) return undefined;
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5 || !/^\d+$/.test(fields[0]) || !/^\d+$/.test(fields[1])) return undefined;
+  const minute = Number(fields[0]);
+  const hour = Number(fields[1]);
+  if (minute < 0 || minute > 59 || hour < 0 || hour > 23) return undefined;
+  return { minute, hour, day: fields[2], month: fields[3], weekday: fields[4] };
+}
+
+function cronWindowKey(schedule: RepositorySchedule, at = Date.now()): string {
+  const timezone = schedule.trigger.timezone ?? 'UTC';
+  const parts = zonedDateParts(at, timezone);
+  const fixed = fixedCronTime(schedule.trigger.cronExpression);
+  if (fixed) {
+    return `${parts.year}-${String(parts.month).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}@${String(fixed.hour).padStart(2, '0')}:${String(fixed.minute).padStart(2, '0')}[${timezone}]`;
+  }
+  return `${parts.year}-${String(parts.month).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}T${String(parts.hour).padStart(2, '0')}:${String(parts.minute).padStart(2, '0')}[${timezone}]`;
+}
+
+function triggerWindowKey(schedule: RepositorySchedule, context: ScheduleTriggerContext | undefined, at = Date.now()): string {
+  switch (schedule.trigger.type) {
+    case 'cron':
+      return cronWindowKey(schedule, at);
+    case 'calendar':
+      return schedule.trigger.calendarAt ?? new Date(at).toISOString().slice(0, 16);
+    case 'repository-event':
+      return context?.eventId?.trim() || `${context?.eventName ?? schedule.trigger.eventName ?? 'event'}:${normalizedWindow(1, at)}`;
+    case 'dependency-checkpoint':
+      return createHash('sha256').update(JSON.stringify(schedule.trigger.dependencyJobIds ?? [])).digest('hex').slice(0, 20);
+    case 'manual':
+      return context?.eventId?.trim() || normalizedWindow(1, at);
+    case 'condition':
+    case 'interval':
+    default:
+      return normalizedWindow(schedule.trigger.everyMinutes ?? 60, at);
+  }
+}
+
+function cronFieldMatches(value: number, field: string, min: number, max: number): boolean {
+  return field.split(',').some((part) => {
+    const trimmed = part.trim();
+    if (trimmed === '*') return true;
+    const stepMatch = trimmed.match(/^\*\/(\d+)$/);
+    if (stepMatch) return value % Math.max(1, Number(stepMatch[1])) === 0;
+    const rangeMatch = trimmed.match(/^(\d+)-(\d+)(?:\/(\d+))?$/);
+    if (rangeMatch) {
+      const start = Math.max(min, Number(rangeMatch[1]));
+      const end = Math.min(max, Number(rangeMatch[2]));
+      const step = Math.max(1, Number(rangeMatch[3] ?? 1));
+      return value >= start && value <= end && (value - start) % step === 0;
+    }
+    const exact = Number(trimmed);
+    return Number.isInteger(exact) && exact >= min && exact <= max && value === exact;
+  });
+}
+
+export function cronDue(
+  expression: string | undefined,
+  at = Date.now(),
+  timezone = 'UTC',
+  catchUpMinutes = 0,
+): boolean {
+  if (!expression) return false;
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) throw new Error(`SCHEDULE_CRON_INVALID: expected five fields, received ${fields.length}`);
+  const parts = zonedDateParts(at, timezone);
+  const calendarMatches = cronFieldMatches(parts.day, fields[2], 1, 31)
+    && cronFieldMatches(parts.month, fields[3], 1, 12)
+    && cronFieldMatches(parts.weekday, fields[4], 0, 6);
+  if (!calendarMatches) return false;
+  if (cronFieldMatches(parts.minute, fields[0], 0, 59) && cronFieldMatches(parts.hour, fields[1], 0, 23)) return true;
+  const fixed = fixedCronTime(expression);
+  if (!fixed || catchUpMinutes <= 0) return false;
+  const scheduledMinute = fixed.hour * 60 + fixed.minute;
+  const currentMinute = parts.hour * 60 + parts.minute;
+  return currentMinute >= scheduledMinute && currentMinute - scheduledMinute <= Math.min(24 * 60, catchUpMinutes);
+}
+
+async function workspaceDirty(controllerHome: string, repoId: string): Promise<boolean> {
+  try {
+    const repository = getRepository(repoId, controllerHome, { includeRemoved: true });
+    const result = await execFileAsync('git', ['-C', repository.canonicalRoot, 'status', '--porcelain=v1'], {
+      encoding: 'utf8', timeout: 1_500, maxBuffer: 256 * 1024,
+    });
+    return Boolean(result.stdout.trim());
+  } catch {
+    return true;
+  }
+}
+
+async function triggerDue(
+  controllerHome: string,
+  schedule: RepositorySchedule,
+  force: boolean,
+  context?: ScheduleTriggerContext,
+): Promise<{ due: boolean; reason?: string; evidence?: Record<string, unknown> }> {
+  if (force && schedule.trigger.type !== 'repository-event') return { due: true };
+  switch (schedule.trigger.type) {
+    case 'manual':
+      return { due: force, reason: force ? undefined : 'Manual Schedule requires an explicit trigger.' };
+    case 'interval':
+      return { due: true };
+    case 'cron':
+      return {
+        due: cronDue(schedule.trigger.cronExpression, Date.now(), schedule.trigger.timezone ?? 'UTC', schedule.trigger.catchUpMinutes ?? 0),
+        reason: `Cron expression is not due in the current ${schedule.trigger.timezone ?? 'UTC'} minute or catch-up window.`,
+      };
+    case 'calendar': {
+      const at = Date.parse(schedule.trigger.calendarAt ?? '');
+      if (!Number.isFinite(at)) throw new Error('SCHEDULE_CALENDAR_INVALID: calendarAt must be an ISO-8601 timestamp');
+      return { due: Date.now() >= at, reason: 'Calendar trigger is not due yet.', evidence: { calendarAt: schedule.trigger.calendarAt } };
+    }
+    case 'repository-event': {
+      const expected = schedule.trigger.eventName?.trim();
+      const actual = context?.eventName?.trim();
+      const due = context?.source === 'repository-event' && Boolean(actual) && (!expected || expected === actual);
+      return { due, reason: due ? undefined : 'Repository event did not match this Schedule.', evidence: { expected, actual, eventId: context?.eventId } };
+    }
+    case 'dependency-checkpoint': {
+      const dependencyJobIds = schedule.trigger.dependencyJobIds ?? [];
+      if (dependencyJobIds.length === 0) throw new Error('SCHEDULE_DEPENDENCY_REQUIRED: dependency checkpoint has no Job ids');
+      const jobs = dependencyJobIds.map((jobId) => findExecutionJob(controllerHome, jobId));
+      const due = jobs.every((job) => job?.status === 'succeeded');
+      return {
+        due,
+        reason: due ? undefined : 'Dependency checkpoint is not ready.',
+        evidence: { dependencies: dependencyJobIds.map((jobId, index) => ({ jobId, status: jobs[index]?.status ?? 'missing' })) },
+      };
+    }
+    case 'condition': {
+      const condition = schedule.trigger.condition;
+      if (!condition) throw new Error('SCHEDULE_CONDITION_REQUIRED');
+      if (condition.kind === 'repository_clean') {
+        const clean = !(await workspaceDirty(controllerHome, schedule.repoId));
+        return { due: clean, reason: clean ? undefined : 'Repository is not clean.', evidence: { clean } };
+      }
+      if (condition.kind === 'job_succeeded' || condition.kind === 'job_terminal') {
+        const job = condition.jobId ? findExecutionJob(controllerHome, condition.jobId) : undefined;
+        const terminal = Boolean(job && ['succeeded', 'failed', 'timed_out', 'cancelled', 'orphaned', 'stale', 'human_attention_required'].includes(job.status));
+        const due = condition.kind === 'job_succeeded' ? job?.status === 'succeeded' : terminal;
+        return { due, reason: due ? undefined : `Condition ${condition.kind} is not met.`, evidence: { jobId: condition.jobId, status: job?.status ?? 'missing' } };
+      }
+      const threshold = Math.max(1, condition.observationThreshold ?? 2);
+      const finding = listCandidateFindings(controllerHome, schedule.repoId, { includeTerminal: true, limit: 1000 })
+        .find((entry) => entry.semanticKey === condition.semanticKey);
+      const due = Boolean(finding && finding.observationCount >= threshold);
+      return { due, reason: due ? undefined : 'Candidate observation threshold is not met.', evidence: { semanticKey: condition.semanticKey, observations: finding?.observationCount ?? 0, threshold } };
+    }
+    default:
+      return { due: false, reason: 'Unsupported Schedule trigger.' };
+  }
+}
+
+async function stopReason(controllerHome: string, schedule: RepositorySchedule): Promise<string | undefined> {
+  const projection = readRepositoryProjection(controllerHome, schedule.repoId);
+  if (schedule.stopConditions.includes('human_review_required') && projection.currentAttention.length > 0) return 'Repository has jobs requiring human attention.';
+  if (schedule.stopConditions.includes('release_ready') && projection.releaseFrozen) return 'Repository is in release freeze.';
+  if (schedule.stopConditions.includes('external_blocker')) {
+    try {
+      const repository = getRepository(schedule.repoId, controllerHome, { includeRemoved: true });
+      if (!repository.enabled || repository.removedAt) return 'Repository is disabled or removed.';
+    } catch {
+      return 'Repository registry is unavailable.';
+    }
+    const recentInfrastructureFailure = listExecutionJobs(controllerHome, schedule.repoId, 20).find((job) => {
+      if (!['failed', 'timed_out', 'orphaned'].includes(job.status) || !job.error) return false;
+      if (job.error.retryable) return true;
+      return /(?:network|connection|upstream|external|remote|github|tunnel|502|503|timeout)/i.test(`${job.error.code} ${job.error.message}`);
+    });
+    if (recentInfrastructureFailure) return `External or infrastructure blocker detected from Job ${recentInfrastructureFailure.jobId}.`;
+  }
+  if (projection.activeJobs.some((job) => job.status === 'waiting_for_release_barrier')) return 'Repository is waiting on a release barrier.';
+  if (schedule.action.operation !== LIVE_MAINTENANCE_OPERATION
+    && schedule.action.resourceClaims?.some((claim) => claim.mode !== 'read')
+    && await workspaceDirty(controllerHome, schedule.repoId)) {
+    return 'Workspace is dirty; automatic write occurrence was suppressed.';
+  }
+  return undefined;
+}
+
+function dailyRuntimeMinutes(controllerHome: string, occurrences: ScheduleOccurrence[]): number {
+  const today = new Date().toISOString().slice(0, 10);
+  return occurrences
+    .filter((entry) => entry.createdAt.startsWith(today) && ['succeeded', 'failed', 'queued', 'running'].includes(entry.status))
+    .reduce((total, entry) => {
+      if (entry.jobId) {
+        const job = findExecutionJob(controllerHome, entry.jobId);
+        if (job) {
+          const started = Date.parse(job.startedAt ?? job.createdAt);
+          const finished = Date.parse(job.finishedAt ?? new Date().toISOString());
+          return total + Math.max(1, Math.ceil(Math.max(0, finished - started) / 60_000));
+        }
+      }
+      const started = Date.parse(entry.createdAt);
+      const finished = Date.parse(entry.updatedAt ?? entry.createdAt);
+      return total + Math.max(1, Math.ceil(Math.max(0, finished - started) / 60_000));
+    }, 0);
+}
+
+function occurrenceDecisionEvidence(extra: Record<string, unknown> = {}): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(extra).filter(([, value]) => value !== undefined));
+}
+
+function isLiveMaintenanceSchedule(schedule: RepositorySchedule): boolean {
+  return schedule.action.operation === LIVE_MAINTENANCE_OPERATION;
+}
+
+function decideOccurrence(
+  controllerHome: string,
+  schedule: RepositorySchedule,
+  occurrence: ScheduleOccurrence,
+  decision: ScheduleDecisionType,
+  status: ScheduleOccurrence['status'],
+  reason?: string,
+  evidence?: Record<string, unknown>,
+): ScheduleOccurrence {
+  const decisionId = `DEC-${occurrence.occurrenceId}`;
+  saveScheduleDecision(controllerHome, {
+    schemaVersion: 1,
+    revision: 1,
+    decisionId,
+    occurrenceId: occurrence.occurrenceId,
+    scheduleId: occurrence.scheduleId,
+    repoId: occurrence.repoId,
+    requestId: `${schedule.requestId}:${occurrence.windowKey}`,
+    decision,
+    reason,
+    triggerContext: occurrence.triggerContext,
+    evidence,
+    createdAt: new Date().toISOString(),
+  });
+  return saveOccurrence(controllerHome, { ...occurrence, decision, decisionId, status, reason });
+}
+
+export async function evaluateSchedule(
+  controllerHome: string,
+  schedule: RepositorySchedule,
+  force = false,
+  triggerContext?: ScheduleTriggerContext,
+): Promise<ScheduleOccurrence | undefined> {
+  if (!schedule.enabled && !force) return undefined;
+  const due = await triggerDue(controllerHome, schedule, force, triggerContext);
+  if (!due.due) return undefined;
+
+  const key = triggerWindowKey(schedule, triggerContext);
+  const occurrenceId = `OCC-${schedule.scheduleId}-${createHash('sha256').update(key).digest('hex').slice(0, 20)}`;
+  const existing = getOccurrence(controllerHome, schedule.repoId, occurrenceId);
+  if (existing) return existing;
+  const timestamp = new Date().toISOString();
+  const occurrence: ScheduleOccurrence = saveOccurrence(controllerHome, {
+    schemaVersion: 1,
+    revision: 0,
+    occurrenceId,
+    scheduleId: schedule.scheduleId,
+    repoId: schedule.repoId,
+    windowKey: key,
+    status: 'created',
+    decision: 'nothing_to_do',
+    triggerContext: triggerContext ?? { source: force ? 'manual' : 'timer' },
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  });
+
+  // Semantic / model-backed schedules only record a trigger + Handoff.
+  // Deterministic allowlisted operations continue into the local engine path.
+  if (!isDeterministicSchedule(schedule)) {
+    const externalControllerHandoff = recordScheduleOccurrenceHandoff(
+      controllerHome,
+      schedule,
+      decideOccurrence(
+        controllerHome,
+        schedule,
+        occurrence,
+        'operation_blocked',
+        'skipped',
+        'Schedule execution is external-controller-owned; no ExecutionJob was created.',
+        occurrenceDecisionEvidence({ operation: schedule.action.operation, trigger: occurrence.triggerContext?.source }),
+      ),
+      {
+        title: `Schedule ${schedule.name} requires an external Controller`,
+        summary: 'The scheduled trigger was recorded without dispatching a Kernel Job.',
+        reason: 'Schedule execution is external-controller-owned.',
+        creationReason: 'ambiguous_outcome',
+        blockingDecision: 'Claim or create the related Work before executing the scheduled operation.',
+        recommendedDecision: 'Review the trigger evidence and continue it through an explicitly claimed external Controller session.',
+        recommendedPrompt: `Review schedule ${schedule.scheduleId} occurrence ${occurrence.occurrenceId}; create or claim Work for ${schedule.action.operation} and continue through Process Runtime or Thin Launcher.`,
+        statusSummary: 'Schedule trigger is waiting for external Controller ownership.',
+        blockedBy: ['external_controller_required'],
+        attemptedActions: [`operation:${schedule.action.operation}`],
+      },
+    );
+    saveSchedule(controllerHome, { ...schedule, lastTriggeredAt: timestamp, lastOccurrenceId: occurrenceId });
+    return externalControllerHandoff;
+  }
+
+  const recent = listOccurrences(controllerHome, schedule.repoId, schedule.scheduleId, 1000);
+  const stop = await stopReason(controllerHome, schedule);
+  if (stop) {
+    const stopped = decideOccurrence(controllerHome, schedule, occurrence, 'stopped', 'skipped', stop);
+    if (!isLiveMaintenanceSchedule(schedule)) return stopped;
+    const failed = applyScheduleFailure(controllerHome, schedule.scheduleId, schedule.repoId, occurrence.occurrenceId, {
+      outcome: 'skipped',
+      decision: 'stopped',
+      reason: stop,
+      countFailure: false,
+      pauseReason: stop,
+      handoff: {
+        title: `Scheduled maintenance occurrence ${occurrence.occurrenceId} stopped`,
+        summary: 'A live maintenance occurrence was blocked by an explicit schedule stop condition and requires review before automation resumes.',
+        reason: stop,
+        creationReason: 'ambiguous_outcome',
+        blockingDecision: 'Review the stop condition and decide whether automatic maintenance should stay paused.',
+        recommendedDecision: 'Resolve the stop condition, then explicitly re-enable or retrigger the maintenance schedule.',
+        recommendedPrompt: `Review maintenance schedule ${schedule.scheduleId} for repo ${schedule.repoId}, inspect stop condition ${stop}, and decide whether to resume the schedule.`,
+        statusSummary: 'Scheduled maintenance occurrence stopped before dispatch.',
+        blockedBy: ['schedule_stop_condition'],
+        attemptedActions: [`schedule:${schedule.scheduleId}`, `operation:${schedule.action.operation}`],
+      },
+    });
+    return failed.occurrence ?? stopped;
+  }
+
+  const active = listActiveOccurrences(controllerHome, schedule.repoId, schedule.scheduleId)
+    .filter((entry) => entry.occurrenceId !== occurrence.occurrenceId);
+  if (active.length >= schedule.policy.maxActiveOccurrences) {
+    return decideOccurrence(controllerHome, schedule, occurrence, 'active_occurrence', 'skipped', 'Maximum active occurrences reached.');
+  }
+  if (schedule.consecutiveFailures >= schedule.policy.maxFailures) {
+    saveSchedule(controllerHome, { ...schedule, enabled: false, pausedReason: 'Maximum consecutive failures reached.' });
+    return decideOccurrence(controllerHome, schedule, occurrence, 'stopped', 'skipped', 'Schedule paused after repeated failures.');
+  }
+  if (schedule.nextEligibleAt && Date.parse(schedule.nextEligibleAt) > Date.now() && !force) {
+    return decideOccurrence(controllerHome, schedule, occurrence, 'cooldown', 'skipped', `Schedule backoff remains active until ${schedule.nextEligibleAt}.`);
+  }
+  if (schedule.lastTriggeredAt && Date.now() - Date.parse(schedule.lastTriggeredAt) < schedule.policy.cooldownMinutes * 60_000 && !force) {
+    return decideOccurrence(controllerHome, schedule, occurrence, 'cooldown', 'skipped', 'Schedule is cooling down.');
+  }
+  if (dailyRuntimeMinutes(controllerHome, recent) >= schedule.policy.dailyBudgetMinutes) {
+    return decideOccurrence(controllerHome, schedule, occurrence, 'budget_exhausted', 'skipped', 'Daily schedule budget exhausted.');
+  }
+  if (schedule.policy.shadowMode) {
+    if (isLiveMaintenanceSchedule(schedule)) {
+      const repository = getRepository(schedule.repoId, controllerHome, { includeRemoved: true });
+      const preview = previewAutomaticRuntimeMaintenance(repository, controllerHome, schedule.action.arguments);
+      if (!preview.allowed) {
+        const decision = preview.blockedPermanently ? 'operation_blocked' : 'maintenance_not_ready';
+        const blocked = decideOccurrence(controllerHome, schedule, occurrence, decision, 'skipped', preview.blockedReason, occurrenceDecisionEvidence({
+          actionId: preview.actionId,
+          safeCandidates: preview.selectedCandidateIds.length,
+          typedSafeCandidates: preview.selectedTypedCandidateIds.length,
+        }));
+        const failed = applyScheduleFailure(controllerHome, schedule.scheduleId, schedule.repoId, occurrence.occurrenceId, {
+          outcome: 'skipped',
+          decision,
+          reason: preview.blockedReason ?? 'Automatic maintenance preview blocked the occurrence.',
+          countFailure: !preview.blockedPermanently,
+          pauseReason: preview.blockedPermanently ? preview.blockedReason : undefined,
+          handoff: {
+            title: `Scheduled maintenance occurrence ${occurrence.occurrenceId} blocked`,
+            summary: 'A bounded live maintenance occurrence was blocked before dispatch and requires a human decision.',
+            reason: preview.blockedReason ?? 'Automatic maintenance preview blocked the occurrence.',
+            creationReason: preview.blockedPermanently ? 'missing_authorization' : 'ambiguous_outcome',
+            blockingDecision: preview.blockedPermanently
+              ? 'Fix the schedule operation or authorization before automatic maintenance can resume.'
+              : 'Inspect runtime maintenance readiness before allowing another unattended attempt.',
+            recommendedDecision: preview.blockedPermanently
+              ? 'Correct the automatic maintenance configuration and re-enable the schedule deliberately.'
+              : 'Review the maintenance preview, resolve the blocker, and then retrigger the schedule intentionally.',
+            recommendedPrompt: `Review blocked maintenance occurrence ${occurrence.occurrenceId} for schedule ${schedule.scheduleId}. Determine whether the schedule configuration or runtime maintenance readiness should be corrected before retrying.`,
+            statusSummary: 'Scheduled maintenance occurrence blocked before dispatch.',
+            blockedBy: [decision],
+            attemptedActions: [`schedule:${schedule.scheduleId}`, `operation:${schedule.action.operation}`],
+          },
+        });
+        return failed.occurrence ?? blocked;
+      }
+      if (preview.noOp) {
+        return decideOccurrence(controllerHome, schedule, occurrence, 'nothing_to_do', 'skipped', 'Automatic maintenance preview found nothing safe to repair.', occurrenceDecisionEvidence({
+          actionId: preview.actionId,
+          readyForExecution: preview.status.readyForExecution,
+        }));
+      }
+      saveSchedule(controllerHome, { ...schedule, lastTriggeredAt: timestamp, lastOccurrenceId: occurrenceId });
+      return decideOccurrence(controllerHome, schedule, occurrence, 'would_execute', 'shadowed', 'Shadow mode records the live maintenance decision without applying it.', occurrenceDecisionEvidence({
+        actionId: preview.actionId,
+        safeCandidates: preview.selectedCandidateIds.length,
+        typedSafeCandidates: preview.selectedTypedCandidateIds.length,
+      }));
+    }
+    saveSchedule(controllerHome, { ...schedule, lastTriggeredAt: timestamp, lastOccurrenceId: occurrenceId });
+    return decideOccurrence(controllerHome, schedule, occurrence, 'would_execute', 'shadowed', 'Shadow mode records the decision without modifying the repository.', due.evidence);
+  }
+
+  if (isLiveMaintenanceSchedule(schedule)) {
+    const repository = getRepository(schedule.repoId, controllerHome, { includeRemoved: true });
+    const preview = previewAutomaticRuntimeMaintenance(repository, controllerHome, schedule.action.arguments);
+    if (!preview.allowed) {
+      const decision = preview.blockedPermanently ? 'operation_blocked' : 'maintenance_not_ready';
+      const blocked = decideOccurrence(controllerHome, schedule, occurrence, decision, 'skipped', preview.blockedReason, occurrenceDecisionEvidence({
+        actionId: preview.actionId,
+        safeCandidates: preview.selectedCandidateIds.length,
+        typedSafeCandidates: preview.selectedTypedCandidateIds.length,
+      }));
+      const failed = applyScheduleFailure(controllerHome, schedule.scheduleId, schedule.repoId, occurrence.occurrenceId, {
+        outcome: 'skipped',
+        decision,
+        reason: preview.blockedReason ?? 'Automatic maintenance preview blocked the occurrence.',
+        countFailure: !preview.blockedPermanently,
+        pauseReason: preview.blockedPermanently ? preview.blockedReason : undefined,
+        handoff: {
+          title: `Scheduled maintenance occurrence ${occurrence.occurrenceId} blocked`,
+          summary: 'A bounded live maintenance occurrence was blocked before dispatch and requires a human decision.',
+          reason: preview.blockedReason ?? 'Automatic maintenance preview blocked the occurrence.',
+          creationReason: preview.blockedPermanently ? 'missing_authorization' : 'ambiguous_outcome',
+          blockingDecision: preview.blockedPermanently
+            ? 'Fix the schedule operation or authorization before automatic maintenance can resume.'
+            : 'Inspect runtime maintenance readiness before allowing another unattended attempt.',
+          recommendedDecision: preview.blockedPermanently
+            ? 'Correct the automatic maintenance configuration and re-enable the schedule deliberately.'
+            : 'Review the maintenance preview, resolve the blocker, and then retrigger the schedule intentionally.',
+          recommendedPrompt: `Review blocked maintenance occurrence ${occurrence.occurrenceId} for schedule ${schedule.scheduleId}. Determine whether the schedule configuration or runtime maintenance readiness should be corrected before retrying.`,
+          statusSummary: 'Scheduled maintenance occurrence blocked before dispatch.',
+          blockedBy: [decision],
+          attemptedActions: [`schedule:${schedule.scheduleId}`, `operation:${schedule.action.operation}`],
+        },
+      });
+      return failed.occurrence ?? blocked;
+    }
+    if (preview.noOp) {
+      return decideOccurrence(controllerHome, schedule, occurrence, 'nothing_to_do', 'skipped', 'Automatic maintenance preview found nothing safe to repair.', occurrenceDecisionEvidence({
+        actionId: preview.actionId,
+        readyForExecution: preview.status.readyForExecution,
+      }));
+    }
+  }
+
+  const args = schedule.action.arguments ?? {};
+  const actionIdRaw = typeof args.action_id === 'string'
+    ? args.action_id
+    : typeof args.actionId === 'string'
+      ? args.actionId
+      : undefined;
+  const decision = decideOccurrence(
+    controllerHome,
+    schedule,
+    occurrence,
+    'execute',
+    'running',
+    'Deterministic schedule occurrence executing inline without an ExecutionJob.',
+    occurrenceDecisionEvidence({
+      ...due.evidence,
+      operation: schedule.action.operation,
+      actionId: actionIdRaw,
+    }),
+  );
+
+  try {
+    if (!actionIdRaw) {
+      throw new Error('SCHEDULE_ACTION_ID_REQUIRED: deterministic maintenance schedules require action_id.');
+    }
+    const repository = getRepository(schedule.repoId, controllerHome, { includeRemoved: true });
+    const result = applyRuntimeMaintenance(repository, controllerHome, {
+      confirmMaintenance: true,
+      actionId: actionIdRaw as RuntimeMaintenanceActionId,
+      minAgeMinutes: typeof args.min_age_minutes === 'number'
+        ? args.min_age_minutes
+        : typeof args.minAgeMinutes === 'number'
+          ? args.minAgeMinutes
+          : undefined,
+      maxCandidates: typeof args.max_candidates === 'number'
+        ? args.max_candidates
+        : typeof args.maxCandidates === 'number'
+          ? args.maxCandidates
+          : undefined,
+      cancelPendingApprovals: false,
+    });
+    const appliedCount = result.applied.filter((candidate) => candidate.applied).length;
+    const latest = getSchedule(controllerHome, schedule.repoId, schedule.scheduleId);
+    saveSchedule(controllerHome, {
+      ...latest,
+      lastTriggeredAt: timestamp,
+      lastOccurrenceId: occurrenceId,
+      consecutiveFailures: 0,
+      nextEligibleAt: undefined,
+      pausedReason: undefined,
+    });
+    return saveOccurrence(controllerHome, {
+      ...decision,
+      status: 'succeeded',
+      reason: `Deterministic maintenance applied ${appliedCount} candidate(s) for ${actionIdRaw}.`,
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const failed = applyScheduleFailure(controllerHome, schedule.scheduleId, schedule.repoId, occurrence.occurrenceId, {
+      outcome: 'failed',
+      decision: 'execute',
+      reason,
+      handoff: {
+        title: `Scheduled maintenance occurrence ${occurrence.occurrenceId} failed`,
+        summary: 'A bounded live maintenance occurrence failed during deterministic apply 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 ${occurrence.occurrenceId} for ${schedule.scheduleId}, inspect the failed runtime maintenance action, and decide whether to resume automatic maintenance.`,
+        statusSummary: 'Scheduled maintenance execution failed.',
+        blockedBy: ['scheduled_execution_failed'],
+        attemptedActions: [
+          `schedule:${schedule.scheduleId}`,
+          `operation:${schedule.action.operation}`,
+          actionIdRaw ? `action:${actionIdRaw}` : 'action:unknown',
+        ],
+      },
+    });
+    const latest = getSchedule(controllerHome, schedule.repoId, schedule.scheduleId);
+    saveSchedule(controllerHome, {
+      ...latest,
+      lastTriggeredAt: timestamp,
+      lastOccurrenceId: occurrenceId,
+    });
+    return failed.occurrence ?? saveOccurrence(controllerHome, {
+      ...decision,
+      status: 'failed',
+      reason,
+    });
+  }
+}
+
+export async function tickSchedules(controllerHome: string, repoIds: string[]): Promise<ScheduleOccurrence[]> {
+  const occurrences: ScheduleOccurrence[] = [];
+  for (const repoId of repoIds) {
+    for (const schedule of listSchedules(controllerHome, repoId)) {
+      const occurrence = await evaluateSchedule(controllerHome, schedule, false, { source: 'timer' });
+      if (occurrence) occurrences.push(occurrence);
+    }
+  }
+  return occurrences;
+}
+
+export function hasScheduledWriter(controllerHome: string, repoId: string): boolean {
+  return listActiveExecutionJobs(controllerHome, repoId).some((job) => job.origin.surface === 'schedule' && job.resourceClaims.some((claim) => claim.mode !== 'read'));
+}