Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

106 KB
Raw Blame
/**
 * Task Schedule Service (v2 - Unified)
 *
 * Manages configurable intervals for improvement tasks across all apps (including PortOS).
 * All task types live in a single `tasks` object — no more selfImprovement/appImprovement split.
 *
 * Cadence model (two variants + one orthogonal flag):
 * - type 'on-demand': never auto-queued; only a manual trigger runs it.
 * - type 'cron': clock-scheduled from `cronExpression` (5-field), without replaying missed slots.
 * - `perpetual: true` (independent of type): drain actionable work back-to-back
 *   (re-queue on completion) until a programmatic work-detector reports nothing
 *   actionable, then PARK on a recheck cadence. An on-demand+perpetual task
 *   rechecks on `recheckCron` / `recheckIntervalMs` (default daily); a
 *   cron+perpetual task's cron slot INITIATES the drain and the same expression
 *   gates the next attempt once it parks. With `autoStart: false`, on-demand
 *   drains start only on explicit dispatch and never wake on a recheck timer.
 *   Omitted autoStart preserves legacy automatic on-demand drains.
 *   See server/services/perpetualWork.js for the detector registry and the
 *   perpetual gate in cosTaskGenerator.prepareManagedAppImprovementTask.
 */

import { scheduleExecutionFieldsSchema } from '../lib/scheduleExecutionFieldsValidation.js';
import { unresolvedRetirements, retainRetirementObligations, sameRetirementCheckout, sameRetirementObservation, matchingRetirementReceipts, hasRetirementReceipt } from '../lib/reconcileRetirementEvidence.js';
import { applyLegacyRetirementResolutions } from '../lib/legacyRetirementTransition.js';
import { readCheckoutPathPresence, readLocalBranchPresence } from './repoCleanupObservation.js';
import { isCurrentRetirementCheckout } from '../lib/retirementCheckoutObservation.js';
import { findGoneInventoryRows, isObligationRow } from './branchReconcileInventoryPrune.js';
import { createHash, randomUUID } from 'node:crypto';
import { ServerError } from '../lib/errorHandler.js';
import { taskExecutionKey as executionKey } from '../lib/scheduledTaskTypes.js';
import { TASK_READINESS_REASON } from '../lib/taskReadinessReasons.js';
import { cosEvents, emitLog } from './cosEvents.js';
import { formatSkipCauses } from '../lib/perpetualSkipCauses.js';
import { DAY, safeDate } from '../lib/fileUtils.js';
import { mapWithConcurrency } from '../lib/mapWithConcurrency.js';
import { getAdaptiveCooldownMultiplier } from './taskLearning.js';
import { getAppById, isTaskTypeEnabledForApp, getAppTaskTypeInterval, getAppTaskTypeIntervalMs, getActiveApps, getAppTaskTypeOverrides, clearAllPrWatcherState, clearAllIssueWatcherState } from './apps.js';
import { loadState, isImprovementEnabled } from './cosState.js';
import { getLocalParts } from '../lib/timezone.js';
import { getUserTimezone } from './userTimezone.js';
import { parseCronToNextRun } from './eventScheduler.js';
import { isAuditTaskType, defaultFileIssuesFor, auditDoWorkRequiresWorktree, getAuditScheduleMetadata, AUDIT_RUN_GUIDANCE, AUDIT_SUGGESTED_AFTER } from '../lib/auditCatalog.js';
import { DEFAULT_TASK_PROMPTS, stampPromptWrite } from './taskPromptDefaults.js';
import {
  DEFAULT_PERPETUAL_RECHECK_MS,
  INTERVAL_TYPES,
  ON_DEMAND_ORIGINS,
  isCronExpression,
  isUserOriginRequest,
  resolveAppOverrideCadence
} from './taskScheduleConstants.js';
import {
  DEFAULT_TASK_INTERVALS,
  TASK_INPUT_PATHS,
  INSTALL_WIDE_TASK_TYPES,
  MANAGED_APP_TARGET_TASK_TYPES,
  MANAGED_AGENT_OPTIONS,
  getTaskTypeDescription,
  getTaskTypeInvocation,
  getTaskTypePromptInfo,
  requiresInstallWideTarget,
  isProgrammaticScheduledTaskType,
  enforceBranchReconcileBatch,
  enforceManagedAgentOptions
} from './taskScheduleRegistry.js';
import { loadSchedule, updateSchedule } from './taskScheduleStore.js';
import { inputsUnchangedSince } from './taskInputGate.js';
import { isInstanceFeatureEnabled } from './instanceFeatures.js';
import { recordUserAction } from './userActions.js';
import { getTaskDataInputCatalog } from '../lib/taskDataInputCatalog.js';
import { normalizeSuggestedAfter } from '../lib/scheduleRunOrder.js';
import { isManualOnDemandRequest, normalizeQuotaBurnProvenance } from '../lib/quotaBurnOrigin.js';
import { enabledAppIdsByTaskType, evaluateOnDemandEligibility } from '../lib/quotaBurnTaskRef.js';
import {
  clearFailureLedgerFields,
  clearTaskTypeFailurePark,
  clearTaskTypeFailureParkNotification,
  computeFailureBackoffMs
} from './taskScheduleBackoff.js';

export { PROMPT_VERSIONS, REFERENCE_WATCH_AUDITED_VERSION } from './taskPromptDefaults.js';
export {
  INTERVAL_TYPES, ON_DEMAND_ORIGINS, isRefillRequest, isUserOriginRequest
} from './taskScheduleConstants.js';
export {
  DEFAULT_BRANCHES_PER_AGENT, DEFAULT_TASK_INTERVALS, INSTALL_WIDE_TASK_TYPES,
  MANAGED_APP_TARGET_TASK_TYPES,
  MANAGED_AGENT_OPTIONS, PERPETUAL_DRAIN_DISPATCH_CAP, SELF_IMPROVEMENT_TASK_TYPES,
  TASK_TYPE_DESCRIPTIONS, TASK_TYPE_INVOCATION, TASK_TYPE_PROMPT_INFO,
  getTaskTypeInvocation, getTaskTypePromptInfo, requiresManagedAppTarget, requiresInstallWideTarget,
  isProgrammaticScheduledTaskType, PROGRAMMATIC_SCHEDULED_TASK_TYPES,
  stripManagedAgentOptionsFromOverride
} from './taskScheduleRegistry.js';
export { loadSchedule } from './taskScheduleStore.js';
export {
  FAILURE_BACKOFF_BASE_MS, FAILURE_BACKOFF_CAP_MS, FAILURE_PARK_THRESHOLD,
  clearTaskTypeFailurePark, computeFailureBackoffMs, recordTaskTypeFailure,
  recordTaskTypeSuccess
} from './taskScheduleBackoff.js';
export { addTemplateTask, deleteTemplateTask, getTemplateTasks } from './taskScheduleTemplates.js';

// Settings whose edit is not an "I've addressed the cause" signal, so saving
// one leaves a failure-parked task parked (see the unpark block below).
const PRESENTATION_ONLY_SETTINGS = new Set(['labels', 'suggestedAfter']);

export const createFeatureGate = () => {
  const enabledByFeature = new Map();
  return async (interval) => {
    const featureId = interval?.feature;
    if (!featureId) return true;
    if (!enabledByFeature.has(featureId)) {
      enabledByFeature.set(featureId, isInstanceFeatureEnabled(featureId));
    }
    return enabledByFeature.get(featureId);
  };
};

/**
 * Get learning-adjusted interval for a task type
 */
async function getPerformanceAdjustedInterval(taskType, baseIntervalMs) {
  const taskTypeKey = `task:${taskType}`;

  const cooldownInfo = await getAdaptiveCooldownMultiplier(taskTypeKey).catch(() => ({
    multiplier: 1.0,
    reason: 'error-fallback',
    skip: false,
    successRate: null,
    completed: 0
  }));

  if (cooldownInfo.reason === 'insufficient-data' || cooldownInfo.reason === 'error-fallback') {
    // Also check legacy keys for migration period
    const legacyKeys = [`self-improve:${taskType}`, `app-improve:${taskType}`];
    for (const key of legacyKeys) {
      const legacyInfo = await getAdaptiveCooldownMultiplier(key).catch(() => null);
      if (legacyInfo && legacyInfo.reason !== 'insufficient-data' && legacyInfo.reason !== 'error-fallback') {
        const adjustedIntervalMs = Math.round(baseIntervalMs * legacyInfo.multiplier);
        return {
          adjustedIntervalMs,
          multiplier: legacyInfo.multiplier,
          reason: legacyInfo.reason,
          successRate: legacyInfo.successRate,
          dataPoints: legacyInfo.completed,
          skip: legacyInfo.skip,
          adjusted: legacyInfo.multiplier !== 1.0,
          recommendation: legacyInfo.recommendation
        };
      }
    }

    return {
      adjustedIntervalMs: baseIntervalMs,
      multiplier: 1.0,
      reason: cooldownInfo.reason,
      successRate: null,
      dataPoints: cooldownInfo.completed || 0,
      adjusted: false
    };
  }

  const adjustedIntervalMs = Math.round(baseIntervalMs * cooldownInfo.multiplier);

  if (cooldownInfo.multiplier !== 1.0) {
    const direction = cooldownInfo.multiplier < 1 ? 'decreased' : 'increased';
    const percentage = Math.abs(Math.round((1 - cooldownInfo.multiplier) * 100));
    emitLog('debug', `Learning: ${taskType} interval ${direction} by ${percentage}% (${cooldownInfo.successRate}% success rate)`, {
      taskType,
      multiplier: cooldownInfo.multiplier,
      successRate: cooldownInfo.successRate,
      dataPoints: cooldownInfo.completed
    }, '📊 TaskSchedule');
  }

  return {
    adjustedIntervalMs,
    multiplier: cooldownInfo.multiplier,
    reason: cooldownInfo.reason,
    successRate: cooldownInfo.successRate,
    dataPoints: cooldownInfo.completed,
    skip: cooldownInfo.skip,
    adjusted: cooldownInfo.multiplier !== 1.0,
    recommendation: cooldownInfo.recommendation
  };
}

// ============================================================
// Unified getters/setters (replace split self/app functions)
// ============================================================
export async function getTaskInterval(taskType) {
  const schedule = await loadSchedule();
  return schedule.tasks[taskType] || {
    type: INTERVAL_TYPES.ON_DEMAND,
    perpetual: false,
    enabled: false,
    providerId: null,
    model: null,
    description: getTaskTypeDescription(taskType),
  };
}

export async function updateTaskInterval(taskType, settings) {
  const executionFields = scheduleExecutionFieldsSchema.safeParse(settings);
  if (!executionFields.success) {
    throw new ServerError('Invalid schedule execution fields', { status: 400, code: 'VALIDATION_ERROR' });
  }
  settings = { ...settings, ...executionFields.data };
  const { task, unparkedScopes } = await updateSchedule(async (schedule) => {
    if (!schedule.tasks[taskType]) {
      schedule.tasks[taskType] = { type: INTERVAL_TYPES.ON_DEMAND, perpetual: false, enabled: false, providerId: null, model: null, createdAt: new Date().toISOString() };
    }

    // The description is display-only schedule metadata. Keep it separate from
    // the prompt so custom card copy never becomes agent instructions.
    if ('description' in settings) {
      settings.description = typeof settings.description === 'string'
        ? settings.description.trim().slice(0, 240) || null
        : null;
    }
    if ('prompt' in settings) {
      Object.assign(settings, stampPromptWrite(settings.prompt, taskType));
    }

    schedule.tasks[taskType] = {
      ...schedule.tasks[taskType],
      ...settings
    };

    // Re-assert agent-managed taskMetadata fields after the merge so a PUT that
    // tries to flip them (UI bypass, hand-edited TASKS.md, direct API call)
    // gets the locked value back in its response.
    enforceManagedAgentOptions(taskType, schedule.tasks[taskType]);
    enforceBranchReconcileBatch(taskType, schedule.tasks[taskType]);

    // Config change unparks a failure-parked type (#2616): editing a type's
    // settings is an explicit "I've addressed the cause" signal, so clear the
    // consecutive-failure ledger + auto-park (global + every per-app record) so
    // the type gets a fresh start on its next tick. Track the scopes that were
    // actually parked so their stale notifications can be pruned after the save.
    const topExec = schedule.executions[`task:${taskType}`];
    const unparkedScopes = [];
    // Page-organizing edits do not signal that a failed task is repaired:
    // labels group the cards and `suggestedAfter` orders them, neither touching
    // what the task does when it runs.
    const presentationOnly = Object.keys(settings).every(key => PRESENTATION_ONLY_SETTINGS.has(key));
    if (topExec && !presentationOnly) {
      if (topExec.failureParkedAt) unparkedScopes.push(null);
      clearFailureLedgerFields(topExec);
      for (const [id, rec] of Object.entries(topExec.perApp || {})) {
        if (rec.failureParkedAt) unparkedScopes.push(id);
        clearFailureLedgerFields(rec);
      }
    }

    // Globally disabling pr-watcher also drops its execution cooldown so a later
    // re-enable baselines on the very next tick rather than waiting out the prior
    // 30-min interval — otherwise PRs opened in that delayed window slip past the
    // firstRun baseline and are never dispatched. Paired with clearAllPrWatcherState
    // below (the per-app disable paths in apps.js do the same via resetExecutionHistory).
    if (['pr-watcher', 'issue-watcher'].includes(taskType) && settings.enabled === false) {
      delete schedule.executions[`task:${taskType}`];
    }

    // When the recheck cadence of a perpetual task changes, re-derive the
    // `parkedUntil` of any CURRENTLY-parked execution records (global + per-app)
    // from the new cadence — otherwise an already-parked task keeps waiting out
    // its old timestamp and the cadence control appears to do nothing until then.
    // Only recompute existing parks (never create one), and compute from now so a
    // shortened cadence takes effect on the next slot. A park whose timestamp has
    // ALREADY elapsed is left alone (#3590): an elapsed park is not cleared when it
    // expires — shouldRunTask reports `perpetual-recheck` and the dispatch gate
    // clears it — so it is a record that is DUE RIGHT NOW. Restamping it from a
    // lengthened cadence would silently push already-due work back into the future.
    const merged = schedule.tasks[taskType];
    if (merged.perpetual && ('recheckCron' in settings || 'recheckIntervalMs' in settings || 'cronExpression' in settings)) {
      const exec = schedule.executions[`task:${taskType}`];
      if (exec) {
        const nowMs = Date.now();
        const records = [exec, ...Object.values(exec.perApp || {})];
        for (const rec of records) {
          if (parkedUntilMs(rec) > nowMs) {
            rec.parkedUntil = boundParkedUntil(await computePerpetualRecheckAt(merged), rec.parkNotLaterThan);
          }
        }
      }
    }

    return {
      result: { task: schedule.tasks[taskType], unparkedScopes },
      changed: true
    };
  });

  // Globally disabling pr-watcher clears every app's high-water mark, mirroring
  // the per-app disable clears in apps.js — so a later global re-enable
  // baselines silently instead of dispatching the backlog of PRs opened while
  // it was paused. (`enabled` arrives as a real boolean from the schedule route.)
  if (taskType === 'pr-watcher' && settings.enabled === false) {
    await clearAllPrWatcherState().catch((err) => {
      emitLog('warn', `pr-watcher global-disable state clear failed: ${err.message}`, {}, '📅 TaskSchedule');
    });
  }
  if (taskType === 'issue-watcher' && settings.enabled === false) {
    await clearAllIssueWatcherState().catch((err) => {
      emitLog('warn', `issue-watcher global-disable state clear failed: ${err.message}`, {}, '📅 TaskSchedule');
    });
  }

  for (const scope of unparkedScopes) {
    await clearTaskTypeFailureParkNotification(taskType, scope);
  }

  emitLog('info', `Updated task interval for ${taskType}`, { taskType, settings }, '📅 TaskSchedule');
  cosEvents.emit('schedule:changed', { taskType, settings });

  return task;
}

/**
 * Record a task execution
 */
export async function recordExecution(taskType, appId = null) {
  return updateSchedule(async (schedule) => {
    const key = taskType.startsWith('task:') ? taskType : `task:${taskType}`;

    if (!schedule.executions[key]) {
      schedule.executions[key] = {
        lastRun: null,
        count: 0,
        perApp: {}
      };
    }

    schedule.executions[key].lastRun = new Date().toISOString();
    schedule.executions[key].count = (schedule.executions[key].count || 0) + 1;

    if (appId) {
      if (!schedule.executions[key].perApp[appId]) {
        schedule.executions[key].perApp[appId] = {
          lastRun: null,
          count: 0
        };
      }
      schedule.executions[key].perApp[appId].lastRun = new Date().toISOString();
      schedule.executions[key].perApp[appId].count++;
    }

    return { result: schedule.executions[key], changed: true };
  });
}

export async function getExecutionHistory(taskType) {
  const schedule = await loadSchedule();
  const key = taskType.startsWith('task:') ? taskType : `task:${taskType}`;
  return schedule.executions[key] || { lastRun: null, count: 0, perApp: {} };
}

/**
 * Keep the latest triage output of an audit beside its execution record so the
 * Schedule card can show it (#12085). Machine-local: the execution store never
 * federates. An empty list clears nothing — a run that produced no
 * recommendation leaves the previous one visible rather than erasing it.
 */
export async function recordRecommendedAudits(taskType, appId, items) {
  if (!Array.isArray(items) || items.length === 0) return null;
  return updateSchedule(async (schedule) => {
    const key = taskType.startsWith('task:') ? taskType : `task:${taskType}`;
    schedule.executions[key] ||= { lastRun: null, count: 0, perApp: {} };
    schedule.executions[key].recommendedAudits = {
      at: new Date().toISOString(),
      appId: appId || null,
      items: items.slice(0, 3).map(item => String(item).slice(0, 300)),
    };
    return { result: schedule.executions[key].recommendedAudits, changed: true };
  });
}

/**
 * Baseline for the `inputs-unchanged` gate: the repo HEAD of the last clean run
 * of an input-gated task. A failed or finding-producing run passes `null`, which
 * drops the baseline so the next automatic launch runs.
 */
export async function recordCleanInputBaseline(taskType, appId, head) {
  if (!TASK_INPUT_PATHS[taskType] || !appId) return false;
  return updateSchedule(async (schedule) => {
    const record = ensureExecutionRecord(schedule, taskType, appId);
    if ((record.lastCleanHead ?? null) === (head ?? null)) return { result: false, changed: false };
    if (head) record.lastCleanHead = head;
    else delete record.lastCleanHead;
    return { result: true, changed: true };
  });
}

// True when the task declares input paths and none changed since its last clean run.
async function inputsUnchangedForTask(taskType, appId, schedule) {
  const inputPaths = TASK_INPUT_PATHS[taskType];
  const lastCleanHead = inputPaths && appId ? resolveExecutionRecord(schedule, taskType, appId)?.lastCleanHead : null;
  if (!lastCleanHead) return false;
  const app = await getAppById(appId).catch(() => null);
  return inputsUnchangedSince({ repoPath: app?.repoPath, lastCleanHead, inputPaths });
}

// ============================================================
// Perpetual (drain-until-done) park state
// ============================================================

/**
 * Compute when a parked perpetual task should next re-probe its work-detector.
 * A cron-scheduled perpetual task rechecks on its own `cronExpression`;
 * otherwise this prefers `recheckCron` (a 5-field cron string, evaluated in the
 * user's timezone) over `recheckIntervalMs`, falling back to
 * DEFAULT_PERPETUAL_RECHECK_MS.
 * Returns an ISO timestamp string.
 */
export async function computePerpetualRecheckAt(interval, fromMs = Date.now()) {
  // A cron+perpetual task needs no separate recheck cadence: its own schedule
  // both initiates the drain and gates the next attempt after it parks.
  const cron = (interval?.type === INTERVAL_TYPES.CRON && isCronExpression(interval?.cronExpression))
    ? interval.cronExpression
    : interval?.recheckCron;
  if (isCronExpression(cron)) {
    const timezone = await getUserTimezone();
    const next = parseCronToNextRun(cron, new Date(fromMs), timezone);
    if (next) return next.toISOString();
  }
  const ms = Number(interval?.recheckIntervalMs) > 0
    ? Number(interval.recheckIntervalMs)
    : DEFAULT_PERPETUAL_RECHECK_MS;
  return new Date(fromMs + ms).toISOString();
}

/**
 * Shorten a computed park so it cannot sleep past a moment the caller already
 * KNOWS the situation changes on its own.
 *
 * The recheck cadence is a poll interval — the right default when nothing is
 * known about *when* new work appears. But some parks wait on a deadline the
 * detector can name: branch-reconcile holds a merged branch whose claim worktree
 * is still inside its grace window, and that hold lifts at a computable instant.
 * Parking past it compounds two waits (the grace window, then the next cron
 * fire) into a stall several times longer than either — on a weekly recheck a
 * 7-day hold becomes up to 14 days of a task that looks idle.
 *
 * Only ever SHORTENS: a bound that is unparseable, already elapsed, or later
 * than the recheck is ignored, so a bad bound can never extend a park (nor spin
 * one into a hot retry loop).
 *
 * @param {string} recheckAt - ISO timestamp from computePerpetualRecheckAt
 * @param {string|null|undefined} notLaterThan - ISO instant the hold self-lifts
 * @param {number} [nowMs]
 * @returns {string} ISO timestamp
 */
export function boundParkedUntil(recheckAt, notLaterThan, nowMs = Date.now()) {
  const bound = Date.parse(notLaterThan);
  const recheck = Date.parse(recheckAt);
  if (!Number.isFinite(bound) || !Number.isFinite(recheck)) return recheckAt;
  if (bound <= nowMs || bound >= recheck) return recheckAt;
  return new Date(bound).toISOString();
}

/**
 * Numeric ms of a record's perpetual park, or 0 when it carries none (or an
 * unparseable timestamp). The single reader of `parkedUntil` — every park
 * comparison in this file goes through it so "parked" can't mean two things.
 */
function parkedUntilMs(record) {
  if (!record?.parkedUntil) return 0;
  const ms = new Date(record.parkedUntil).getTime();
  return Number.isFinite(ms) ? ms : 0;
}

/**
 * Roll a perpetual task's park records up into ONE aggregate that every
 * per-app-park consumer projects from (getUpcomingTasks eligibility and the
 * getScheduleStatus UI block).
 *
 * GLOBAL-RECORD INCLUSION RULE (documented once, here, so the callers can't
 * diverge): every `perApp` record is a tracked scope; the top-level execution
 * record is a tracked scope ONLY when it carries its OWN `parkedUntil`.
 * Rationale — perpetual parks are recorded PER-APP (parkPerpetual is always
 * called with an appId for the shipped app-scoped drains: claim-issue,
 * claim-work, branch-/issue-reconcile), so for those the top-level record is
 * just a container and must not be mistaken for a scope that is "due now".
 * A future global-park perpetual (none ship today) stamps its own `parkedUntil`
 * and is then folded in like any other scope.
 *
 * Returns:
 *   trackedAppCount  per-app records (the UI's "N app(s)" denominator)
 *   trackedCount     tracked scopes total (per-app + an own-parked global)
 *   parkedAppCount   per-app records still parked in the future
 *   globalParked     the top-level record carries a park that hasn't elapsed
 *   soonestParkAt    ms of the earliest un-elapsed park, or null when none
 *   anyDueNow        some tracked scope is unparked or its park has elapsed
 *   parkReason       first parked app's reason, else the parked global's
 *   parkCounts       first parked app's counts, else the parked global's
 *   parkSkipCauses   first parked app's skip breakdown, else the parked global's
 */
function aggregatePerpetualParks(execution, now) {
  const appRecords = Object.values(execution?.perApp || {});
  const globalUntil = parkedUntilMs(execution);
  const globalTracked = globalUntil > 0;
  const globalParked = globalUntil > now;

  let parkedAppCount = 0;
  let anyDueNow = false;
  let soonestParkAt = null;
  // The FIRST parked app in iteration order, not the first one that happens to
  // carry a reason — the UI names the app it counted first, so a reasonless park
  // must read as "no reason" rather than borrowing the next app's.
  let firstParkedApp = null;

  for (const rec of appRecords) {
    const until = parkedUntilMs(rec);
    // Unparked (mid-drain) or park already elapsed → this scope is due now.
    if (until <= now) {
      anyDueNow = true;
      continue;
    }
    parkedAppCount++;
    if (firstParkedApp === null) firstParkedApp = rec;
    if (soonestParkAt === null || until < soonestParkAt) soonestParkAt = until;
  }

  if (globalTracked) {
    if (globalParked) {
      if (soonestParkAt === null || globalUntil < soonestParkAt) soonestParkAt = globalUntil;
    } else {
      anyDueNow = true;
    }
  }

  const parkedRecord = firstParkedApp || (globalParked ? execution : null);

  return {
    trackedAppCount: appRecords.length,
    trackedCount: appRecords.length + (globalTracked ? 1 : 0),
    parkedAppCount,
    globalParked,
    soonestParkAt,
    anyDueNow,
    parkReason: firstParkedApp?.parkReason || (globalParked ? execution.parkReason : null) || null,
    parkCounts: parkedRecord?.parkCounts ?? null,
    parkSkipCauses: parkedRecord?.parkSkipCauses ?? null
  };
}

/**
 * The park record lives ALONGSIDE the execution record (global or per-app), so a
 * perpetual task's "parked until" survives restarts the same way `lastRun` does.
 * Returns the execution sub-record that holds the park fields, creating the
 * skeleton if absent.
 */
function ensureExecutionRecord(schedule, taskType, appId) {
  const key = executionKey(taskType);
  if (!schedule.executions[key]) {
    schedule.executions[key] = { lastRun: null, count: 0, perApp: {} };
  }
  const top = schedule.executions[key];
  if (appId) {
    if (!top.perApp) top.perApp = {};
    if (!top.perApp[appId]) top.perApp[appId] = { lastRun: null, count: 0 };
    return top.perApp[appId];
  }
  return top;
}

/**
 * Resolve the EXISTING execution sub-record (global or per-app) without creating
 * it — the read-only counterpart to ensureExecutionRecord. Returns null when the
 * task (or that app) has no record yet.
 */
function resolveExecutionRecord(schedule, taskType, appId = null) {
  const top = schedule.executions[executionKey(taskType)];
  if (!top) return null;
  return (appId ? top.perApp?.[appId] : top) || null;
}

// Every field parkPerpetual stamps for a park. Kept as one list so the clear /
// reset paths can't drift from what park writes (adding a park field here is the
// single edit that keeps all three in sync).
const PARK_FIELDS = ['parkedUntil', 'parkReason', 'parkActionableCount', 'parkCounts', 'parkSkipCauses', 'parkNotLaterThan', 'parkedAt'];

/**
 * Park a perpetual task: its work-detector reported nothing actionable, so stop
 * draining and wait until `parkedUntil` before re-probing. Stamps the park
 * fields on the (per-app or global) execution record.
 *
 * `signature` and `dispatchCount` are the drain's two convergence brakes, both
 * settable HERE rather than by a follow-up call, because every terminal park has
 * to land them in the same write it lands the park. A second await after this one
 * is a step a future park path can forget — and a stale non-zero dispatch count
 * makes the NEXT fresh drain cap out early, which looks exactly like the task
 * silently doing nothing.
 *
 * `notLaterThan` is an optional ISO instant at which the caller knows the hold
 * lifts on its own; the park is shortened to it when that is sooner than the
 * recheck cadence, and ignored otherwise.
 *
 * `dispatchCount` therefore DEFAULTS to 0: a park ends the drain window by
 * definition, so zeroing the budget is the invariant, not an opt-in every caller
 * has to remember. The churn detector's park in agentChurn.js relies on this
 * default so a local signal ends the current drain window cleanly. Note
 * `dispatchCount` is still deliberately NOT in `PARK_FIELDS`:
 * `recordPerpetualDispatch` clears those fields mid-drain on every dispatch, and
 * zeroing the counter there would reset the budget before every dispatch, so the
 * cap could never fire.
 */
export async function parkPerpetual(taskType, appId = null, { reason = null, actionableCount = 0, counts = null, skipCauses = null, signature, dispatchCount = 0, notLaterThan = null, branchAttempts } = {}) {
  const { record, parkedUntil } = await updateSchedule(async (schedule) => {
    const interval = schedule.tasks[taskType] || {};
    // Bound HERE, not at the assignment: `parkedUntil` is also what the log line and
    // the schedule:perpetual-parked event publish, and a change whose whole point is
    // an honest "when will this actually run" must not report the un-shortened time.
    const parkedUntil = boundParkedUntil(await computePerpetualRecheckAt(interval), notLaterThan);
    const record = ensureExecutionRecord(schedule, taskType, appId);
    record.parkedUntil = parkedUntil;
    record.parkReason = reason;
    if (taskType === 'branch-reconcile') {
      const remaining = record.branchReconcileOutcome?.remaining ?? null;
      const drained = reason === 'no-in-flight-branches' && remaining?.length === 0;
      record.branchReconcileOutcome = {
        ...record.branchReconcileOutcome,
        status: drained ? 'drained' : 'incomplete', reason, remaining,
        observedAt: record.branchReconcileOutcome?.observedAt ?? null,
        updatedAt: new Date().toISOString(),
        nextAction: drained ? null : 'Resolve the listed holds or dispatch limit, then run branch reconciliation again.',
      };
    }
    if (branchAttempts === null) delete record.branchReconcileAttempts;
    else if (branchAttempts !== undefined) record.branchReconcileAttempts = branchAttempts;
    record.parkActionableCount = actionableCount;
    // The detector's candidate breakdown ({ open, inFlight, filtered }). Lets the
    // UI explain WHY a non-empty queue yields zero claimable work — "0 of N, M
    // in-flight" — instead of a bare "no work". `null` = the detector reported no
    // breakdown (e.g. the reconcile scans), so the field is left off the record.
    if (counts != null) record.parkCounts = counts;
    else delete record.parkCounts;
    // Per-cause skip attribution ({ 'needs-input': 49, blocked: 17, … }) for the
    // same purpose: "78 filtered" alone can't tell a user their work is waiting
    // on `needs-input` decisions rather than the task being broken. Same null
    // contract as parkCounts — absent when the detector reported no attribution.
    if (skipCauses != null) record.parkSkipCauses = skipCauses;
    else delete record.parkSkipCauses;
    // The self-expiry has to OUTLIVE this call: updateTaskInterval restamps every
    // un-elapsed park from the new cadence, and without a remembered bound it would
    // stretch a correctly-shortened park back out — reintroducing the stacking this
    // option exists to remove, via an unrelated settings edit.
    if (notLaterThan) record.parkNotLaterThan = notLaterThan;
    else delete record.parkNotLaterThan;
    record.parkedAt = new Date().toISOString();
    // A drain that parks because a full cycle made NO progress (branch-reconcile's
    // 'no-progress' park) records the actionable signature it was stuck on, so the
    // next recheck can tell "same stuck set" (park again) from "the set changed"
    // (resume). `null` clears it (an idle park with nothing actionable); `undefined`
    // (the default) leaves any prior signature untouched.
    //
    // `signatureRepeatCount` is the harvested "same finding again" metric the
    // CoS churn detector reports: increment when this park restates the same
    // signature, reset when the set changes, clear when idle.
    if (signature !== undefined) {
      if (signature === null) {
        delete record.lastActionableSignature;
        delete record.signatureRepeatCount;
      } else if (signature === record.lastActionableSignature) {
        record.signatureRepeatCount = (Number(record.signatureRepeatCount) || 1) + 1;
      } else {
        record.lastActionableSignature = signature;
        record.signatureRepeatCount = 1;
      }
    }
    // Same option shape for the consecutive-dispatch budget: `0` (or null) clears it
    // because this park ended the drain window; `undefined` leaves it alone.
    if (dispatchCount !== undefined) {
      if (!dispatchCount) delete record.perpetualDispatchCount;
      else record.perpetualDispatchCount = dispatchCount;
    }

    return { result: { record, parkedUntil }, changed: true };
  });
  // A park on a non-empty queue needs its WHY in the log line itself — the
  // operator reads PM2 output, where a bare `no-actionable-issues` next to "88
  // open issues" reads as the task being broken. Render the top skip causes
  // inline ("49 needs-input, 17 blocked") so the one line they see answers the
  // question the toast exists for.
  const causes = formatSkipCauses(skipCauses);
  const causeSummary = causes ? ` — ${causes}` : '';
  emitLog('info', `Perpetual ${taskType} parked until ${parkedUntil} (${reason || 'idle'}${causeSummary})`, { taskType, appId, parkedUntil }, '📅 TaskSchedule');
  cosEvents.emit('schedule:perpetual-parked', { taskType, appId, parkedUntil, reason, actionableCount, counts, skipCauses });
  return record;
}

/**
 * Read the current park record for a perpetual task (or null when not parked).
 * Used by the on-demand handler to explain to the user WHY an explicit "Run"
 * produced no task — the park fields are freshly stamped by the same dispatch,
 * so this reflects the just-completed detection, not stale cadence state.
 */
export async function getPerpetualParkInfo(taskType, appId = null) {
  const schedule = await loadSchedule();
  const record = resolveExecutionRecord(schedule, taskType, appId);
  if (!record || record.parkedUntil == null) return null;
  return {
    parkedUntil: record.parkedUntil,
    parkReason: record.parkReason ?? null,
    parkActionableCount: record.parkActionableCount ?? null,
    parkCounts: record.parkCounts ?? null,
    parkSkipCauses: record.parkSkipCauses ?? null,
    parkedAt: record.parkedAt ?? null,
    signatureRepeatCount: Number.isFinite(record.signatureRepeatCount) ? record.signatureRepeatCount : null
  };
}

/**
 * Stamp (or clear) the perpetual work gate's escalated probe-failure diagnostic
 * onto the task's schedule record — ALONGSIDE the park fields, never instead of
 * them, because a stall means the gate is skipping WITHOUT parking (the drain
 * keeps ticking; there is no park record to hang the reason on otherwise). This
 * is what lets the Schedule tab render "probe failing — gh: <reason>" instead of
 * an apparently-healthy armed schedule while a broken forge CLI silently skips
 * every evaluation (#7551). Survives a process restart the same way a park does.
 *
 * `stall: null` clears it — a probe that stops being transient (recovers,
 * dispatches, or reaches a definitive park) means whatever was stuck has
 * cleared, so applyPerpetualWorkGate clears this on every non-escalated path.
 */
export async function recordPerpetualStall(taskType, appId = null, stall = null) {
  return updateSchedule(async (schedule) => {
    const record = ensureExecutionRecord(schedule, taskType, appId);
    if (!stall) {
      if (!('stall' in record)) return { result: null, changed: false };
      delete record.stall;
      return { result: null, changed: true };
    }
    record.stall = {
      cli: stall.cli || null,
      reason: stall.reason || null,
      detail: stall.detail || null,
      consecutive: Number.isFinite(stall.consecutive) ? stall.consecutive : 0,
      at: new Date().toISOString()
    };
    return { result: null, changed: true };
  });
}

/**
 * First still-relevant stall diagnostic across a perpetual task's per-app (and
 * global) execution records. Unlike a park, a stall can coexist with a
 * currently-draining task (the gate skips without parking), so the UI needs its
 * own signal independent of aggregatePerpetualParks — mirrors that function's
 * per-app-then-global scan order.
 */
function aggregatePerpetualStall(execution) {
  const appRecords = Object.values(execution?.perApp || {});
  const stalledApp = appRecords.find((rec) => rec?.stall);
  return stalledApp?.stall || execution?.stall || null;
}

/**
 * Is this type+app parked with an UNEXPIRED `parkedUntil`?
 *
 * `getPerpetualParkInfo` reports the park record whether or not it has elapsed —
 * an elapsed park is deliberately left on disk (it reads as "due right now"), so
 * its mere presence is not a stop signal. This is the elapse-aware question, and
 * it is what the completion refill asks before re-issuing a drain: a park means
 * "stop draining until the recheck cadence", and until #3848 the refill lane
 * never asked, so a park could not stop a refill hop.
 */
export async function isPerpetualParkActive(taskType, appId = null) {
  const schedule = await loadSchedule();
  const record = resolveExecutionRecord(schedule, taskType, appId);
  return parkedUntilMs(record) > Date.now();
}

/** Persist the latest deterministic sweep evidence independently of agent success. */
export async function recordBranchReconcileOutcome(appId, { status, reason, remaining, nextAction, remoteInventory, retirementObligations: additionalObligations = [] }) {
  const outcome = await updateSchedule(async (schedule) => {
    const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
    const now = new Date().toISOString();
    const previous = record.branchReconcileOutcome;
    const transition = schedule.retirementPolicyVersion === 2 && !previous?.legacyRetirementTransition
      ? { version: 1, observations: [], resolutions: [] } : previous?.legacyRetirementTransition;
    const existing = unresolvedRetirements(previous);
    const admitted = [];
    const rejected = [];
    for (const row of [...(remaining || []), ...additionalObligations]) {
      if (!isObligationRow(row)) continue;
      if (existing.some(entry => sameRetirementObservation(entry, row))) continue;
      const resolved = previous?.legacyRetirementTransition?.resolutions?.some(entry => sameRetirementObservation(entry.observation, row)
        && (!row.createdAt || row.createdAt === entry.observation.createdAt));
      if (resolved) {
        const app = await getAppById(appId);
        if (app?.repoPath && (!row.path || await readCheckoutPathPresence(row.path) === false)
          && row.branch && await readLocalBranchPresence(app.repoPath, row.branch) === false) {
          rejected.push(row);
          continue;
        }
      }
      const previousIncarnation = existing.some(entry => sameRetirementCheckout(entry, row));
      const receipts = matchingRetirementReceipts(previous, row);
      // Legacy rows without observation identity cannot claim to be recreations.
      if (hasRetirementReceipt(previous, row)
        || ((receipts.length || previousIncarnation) && !Number.isFinite(Date.parse(row.createdAt))
          && (!row.checkoutIdentity || !await isCurrentRetirementCheckout(row).catch(() => false)))) {
        rejected.push(row);
      } else admitted.push(row);
    }
    // A fresh empty scan must not erase the last observation of vanished source.
    const omitted = remaining === undefined ? [] : (previous?.remaining || [])
      .filter(row => !remaining.some(current => sameRetirementCheckout(current, row))
        && !hasRetirementReceipt(previous, row)
        && !rejected.some(entry => sameRetirementObservation(entry, row)));
    const missing = await missingInventoryRows(appId, omitted);
    const retirementObligations = retainRetirementObligations(previous,
      [...admitted, ...missing.map(missingPreservationObligation)], now);
    const inventory = (remaining === undefined ? previous?.remaining ?? null : remaining)
      ?.filter(row => !rejected.some(entry => sameRetirementObservation(entry, row))) ?? null;
    const current = inventory?.map(row => {
      const obligation = retirementObligations.find(entry => sameRetirementObservation(entry, row));
      return obligation ? { ...row, createdAt: obligation.createdAt,
        ...(obligation.checkoutIdentity && { checkoutIdentity: obligation.checkoutIdentity }),
        ...(obligation.observedAt && { observedAt: obligation.observedAt }) } : row;
    }) ?? null;
    const retained = retirementObligations.filter(obligation => !current?.some(row => sameRetirementObservation(row, obligation)));
    record.branchReconcileOutcome = {
      ...previous, status, reason, nextAction, updatedAt: now, retirementObligations,
      ...(transition && { legacyRetirementTransition: transition }),
      ...(remoteInventory !== undefined && { remoteInventory }),
      remaining: retained.length ? [...(current || []), ...retained] : current,
      observedAt: remaining === undefined ? record.branchReconcileOutcome?.observedAt ?? null : now,
      ...(retirementObligations.some(row => row.reason === 'retirement-provenance-unverified') && missingPreservationStatus),
    };
    return { result: record.branchReconcileOutcome, changed: true };
  });
  if (!appId || !unresolvedRetirements(outcome).length) return outcome;
  const app = await getAppById(appId).catch(() => null);
  if (!app?.repoPath) return outcome;
  // Compatibility for stores that have not yet run migration 443. Upgraded and
  // fresh stores always have the transition marker and never require archives.
  if (!outcome.legacyRetirementTransition) {
    const missing = await findGoneInventoryRows(app.repoPath, unresolvedRetirements(outcome), { includeObligations: true }).catch(() => []);
    if (!missing.length) return outcome;
    const { recoverMissingCheckoutPreservations } = await import('./heldCheckoutRecovery.js');
    return recoverMissingCheckoutPreservations({ appId, repoPath: app.repoPath, outcome });
  }
  // Writers are also called while a checkout retirement owns the claim lock.
  // The scan entry points run historical proof work after that lock is released.
  return outcome;
}

export async function recordLegacyRetirementResolutions(appId, expected, resolutions, stillAbsent) {
  return updateSchedule(async schedule => {
    const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
    if (JSON.stringify(record.branchReconcileOutcome) !== JSON.stringify(expected) || !await stillAbsent()) {
      return { result: record.branchReconcileOutcome, changed: false };
    }
    const outcome = applyLegacyRetirementResolutions(expected, resolutions, new Date().toISOString());
    record.branchReconcileOutcome = outcome;
    return { result: outcome, changed: outcome !== expected };
  });
}

/** Compare the whole observed inventory and its generation inside the schedule
 * writer. A verifier result never authorizes a newer/recreated checkout.
 */
export async function recordRecoveredCheckoutPreservations(appId, expected, observations, stillAbsent, discovery) {
  return updateSchedule(async schedule => {
    const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
    const outcome = record.branchReconcileOutcome;
    if (JSON.stringify(outcome) !== JSON.stringify(expected) || !await stillAbsent()) return { result: outcome, changed: false };
    const now = new Date().toISOString();
    const recoveredPreservations = [...(outcome.recoveredPreservations || [])];
    const diagnosed = unresolvedRetirements(outcome).map(release => {
      const observation = observations.find(row => sameRetirementCheckout(row.release, release) && row.release.createdAt === release.createdAt);
      if (!observation) return release;
      const accepted = observation.proof && recoveredPreservations.length < 1000;
      const { recheck: _recheck, releaseFence: _releaseFence, ...proof } = observation.proof || {};
      if (accepted) recoveredPreservations.push({
        branch: release.branch, path: release.path, head: release.head,
        obligationCreatedAt: release.createdAt, ...proof, verified: true, verifiedAt: now,
      });
      return { ...release, preservationEvidence: { status: 'unresolved',
        reason: observation.proof && !accepted ? 'preservation-receipt-budget-exceeded' : observation.reason,
        checkedAt: now, archives: observation.evidence, ...(observation.coverage && { coverage: observation.coverage }), nextAction: observation.nextAction } };
    });
    const retirementObligations = unresolvedRetirements({ retirementObligations: diagnosed, recoveredPreservations });
    const remaining = (outcome.remaining || []).flatMap(row => {
      const diagnosedRow = diagnosed.find(release => sameRetirementCheckout(row, release) && row.createdAt === release.createdAt);
      return diagnosedRow ? retirementObligations.filter(release => sameRetirementCheckout(release, diagnosedRow)) : [row];
    });
    const historical = retirementObligations.find(row => row.preservationEvidence);
    // Recovery proves preservation, not repository convergence. Retire the old
    // diagnosis and let the next sweep establish the aggregate completion state.
    const diagnosis = historical
      ? { status: 'incomplete', reason: 'historical-preservation-unresolved', nextAction: historical.preservationEvidence.nextAction }
      : ['historical-preservation-unresolved', 'retirement-provenance-unverified'].includes(outcome.reason)
        ? { status: 'incomplete', reason: remaining.length ? 'remaining-holds' : 'preservation-recovered',
          nextAction: remaining.length ? 'Resolve the remaining holds, then run branch reconciliation again.'
            : 'Historical preservation verified; run branch reconciliation again to confirm repository completion.' }
        : {};
    record.branchReconcileOutcome = { ...outcome, retirementObligations, recoveredPreservations, remaining, updatedAt: now,
      ...(discovery && { preservationDiscovery: discovery }),
      ...diagnosis,
    };
    return { result: record.branchReconcileOutcome, changed: true };
  });
}

/** Observations are diagnostic only; journals and fresh service proofs own recovery. */
export async function recordInitializedRetirementRecovery(appId, observation) {
  return updateSchedule(async schedule => {
    const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
    const previous = record.branchReconcileOutcome || {};
    const rows = previous.initializedRetirements || [];
    const index = rows.findIndex(row => row.transactionId === observation.transactionId);
    if (index < 0 && rows.length >= 1000) throw new Error('retirement-observation-budget-exceeded');
    const prior = index < 0 ? null : rows[index];
    if (prior && Object.entries(observation).every(([key, value]) => prior[key] === value)) return { result: prior, changed: false };
    const next = [...rows];
    const row = { ...observation, observedAt: new Date().toISOString() };
    if (index < 0) next.push(row); else next[index] = row;
    record.branchReconcileOutcome = { ...previous, initializedRetirements: next };
    return { result: row, changed: true };
  });
}

export async function getBranchReconcileOutcome(appId) {
  const schedule = await loadSchedule();
  return resolveExecutionRecord(schedule, 'branch-reconcile', appId)?.branchReconcileOutcome ?? null;
}

export async function getBranchReconcileInventory(appId) {
  const outcome = await getBranchReconcileOutcome(appId);
  const { reconcileLegacyRetirementRecords } = await import('./legacyRetirementReconciliation.js');
  const current = await reconcileLegacyRetirementRecords(appId, outcome).catch(() => outcome);
  return reconcileMissingInventory(appId, current);
}

const missingPreservationObligation = row => ({ ...row, reason: 'retirement-provenance-unverified' });
const missingPreservationStatus = {
  status: 'incomplete', reason: 'retirement-provenance-unverified',
  nextAction: 'Trace the missing original checkout/ref. Disappearance and merged commits do not prove the retirement service removed it. A service receipt settles it. Do not copy the checkout into an archive.',
};

async function missingInventoryRows(appId, rows, options) {
  if (!appId || !rows.length) return [];
  const app = await getAppById(appId);
  if (!app?.repoPath) return [];
  return findGoneInventoryRows(app.repoPath, rows, options);
}

/** Missing originals remain evidence until an exact service receipt settles them. */
export async function recordMissingInventoryRows(appId, rows) {
  return updateSchedule(async (schedule) => {
    const outcome = ensureExecutionRecord(schedule, 'branch-reconcile', appId).branchReconcileOutcome;
    if (!Array.isArray(outcome?.remaining)) return { result: outcome ?? null, changed: false };
    const missing = outcome.remaining.filter(entry => rows.some(row => sameRetirementCheckout(row, entry)));
    if (!missing.length) return { result: outcome, changed: false };
    const now = new Date().toISOString();
    const obligations = retainRetirementObligations(outcome, missing.map(missingPreservationObligation), now);
    Object.assign(outcome, missingPreservationStatus, { updatedAt: now, retirementObligations: obligations,
      remaining: outcome.remaining.map(row => obligations.find(entry => sameRetirementCheckout(entry, row)) || row),
    });
    return { result: outcome, changed: true };
  });
}

/** Reconcile display inventory with missing source without claiming archival success. */
async function reconcileMissingInventory(appId, outcome) {
  if (!appId || !outcome?.remaining?.length) return outcome;
  const gone = await missingInventoryRows(appId, outcome.remaining, { includeObligations: true }).catch(() => []);
  if (!gone.length) return outcome;
  const unrecorded = gone.filter(row => !isObligationRow(row));
  const current = unrecorded.length ? await recordMissingInventoryRows(appId, unrecorded).catch(() => null) ?? outcome : outcome;
  // The original checkout is gone; flag it so the UI never offers a retire action on it.
  return { ...current, remaining: current.remaining.map(row => ({
    ...row,
    ...(row.path && gone.some(missing => sameRetirementCheckout(missing, row)) && { checkoutMissing: true }),
    ...(!row.path && row.branch && gone.some(missing => sameRetirementCheckout(missing, row)) && { branchMissing: true }),
  })) };
}

/** A prepared archive does not claim deletion. This exact-generation receipt
 * must exist before superseded cleanup is allowed to remove its originals.
 */
export async function recordHeldCheckoutPreservation(appId, { path, branch, head, createdAt, archiveDir, incarnation }) {
  return updateSchedule(async schedule => {
    const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
    const outcome = record.branchReconcileOutcome;
    const row = outcome?.retirementObligations?.find(entry => sameRetirementCheckout(entry, { path, branch, head }) && entry.createdAt === createdAt);
    if (!row || !incarnation?.pointer || !incarnation?.gitdir
      || JSON.stringify(row.checkoutIncarnation) !== JSON.stringify(incarnation)
      || (archiveDir !== null && (typeof archiveDir !== 'string' || !archiveDir))) throw new Error('retirement-obligation-changed');
    row.preservationReceipt = { archiveDir, incarnation: structuredClone(incarnation), status: archiveDir === null ? 'preparing' : 'preserved', preparedAt: new Date().toISOString() };
    return { result: row.preservationReceipt, changed: true };
  });
}

const RETIRED_CHECKOUTS_KEPT = 20;

/**
 * Drop a retired checkout from the last inventory and keep a short record of
 * where its archive went. Status is untouched: only the next sweep can say the
 * repository converged.
 */
export async function recordHeldCheckoutRetirement(appId, { path, branch, branchDeleted, head, archiveDir, checkoutIdentity }) {
  return updateSchedule(async (schedule) => {
    const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
    const outcome = record.branchReconcileOutcome || {};
    // Display history is bounded; receipt evidence and replay identity are durable. A delayed retry
    // must not become new evidence after its display row has been evicted.
    const identity = receipt => createHash('sha256').update(JSON.stringify([
      // A non-empty archive path stays the historical id. In-place removal has no
      // archive, so the checkout identity distinguishes a recreated tree at the
      // same path, branch and head. An archive path is never replaced by it.
      receipt.archiveDir ?? receipt.checkoutIdentity ?? null,
      receipt.path, receipt.branch ?? null, receipt.head,
      receipt.branchDeleted === true,
    ])).digest('hex');
    const receipts = { ...(outcome.retirementReceiptIdentities || {}) };
    const evidence = { ...(outcome.retirementReceiptEvidence || {}) };
    for (const receipt of outcome.retired || []) {
      const recordedArchive = receipt.archiveDir ?? null;
      const archiveKept = recordedArchive === null || (typeof recordedArchive === 'string' && recordedArchive.length > 0);
      if (receipt.branchDeleted === true && receipt.retiredAt && archiveKept) {
        const normalized = { ...receipt, archiveDir: recordedArchive };
        receipts[identity(normalized)] ??= receipt.retiredAt;
        evidence[identity(normalized)] ??= normalized;
      }
    }
    const recordedArchive = archiveDir ?? null;
    const archiveKept = recordedArchive === null || (typeof recordedArchive === 'string' && recordedArchive.length > 0);
    const receiptId = branchDeleted === true && archiveKept
      ? identity({ path, branch, head, archiveDir: recordedArchive, branchDeleted, checkoutIdentity }) : null;
    if (receiptId && receipts[receiptId]) {
      // Keep the original timestamp. Fill a missing checkout identity so a
      // later inventory row can match the receipt that already settled this tuple.
      const prior = evidence[receiptId];
      if (prior && checkoutIdentity && !prior.checkoutIdentity) evidence[receiptId] = { ...prior, checkoutIdentity };
      const changed = JSON.stringify(receipts) !== JSON.stringify(outcome.retirementReceiptIdentities || {})
        || JSON.stringify(evidence) !== JSON.stringify(outcome.retirementReceiptEvidence || {});
      if (changed) record.branchReconcileOutcome = { ...outcome, retirementReceiptIdentities: receipts, retirementReceiptEvidence: evidence };
      return { result: record.branchReconcileOutcome, changed };
    }
    const retiredAt = new Date().toISOString();
    if (receiptId) receipts[receiptId] = retiredAt;
    const receipt = { path, ...(branch && { branch }), head, branchDeleted, archiveDir: recordedArchive, retiredAt, ...(checkoutIdentity && { checkoutIdentity }) };
    const retired = [receipt, ...(outcome.retired || [])].slice(0, RETIRED_CHECKOUTS_KEPT);
    if (receiptId) evidence[receiptId] = receipt;
    const retirementObligations = unresolvedRetirements({ ...outcome, retired, retirementReceiptEvidence: evidence });
    record.branchReconcileOutcome = {
      ...outcome, retirementObligations,
      retirementReceiptIdentities: receipts, retirementReceiptEvidence: evidence,
      updatedAt: retiredAt,
      remaining: Array.isArray(outcome.remaining)
        ? outcome.remaining.filter(entry => retirementObligations.some(row => sameRetirementObservation(row, entry))
          || !(sameRetirementObservation(entry, receipt)
            || (!entry.checkoutIdentity && sameRetirementCheckout(entry, receipt))))
        : outcome.remaining ?? null,
      retired,
    };
    return { result: record.branchReconcileOutcome, changed: true };
  });
}

/**
 * Record a checkout retirement across apps observing the exact checkout tuple.
 * Settles stale inventory rows left behind when an active run finishes and removes its worktree.
 */
export async function recordWorkspaceCheckoutRetirement(repoPath, receipt) {
  if (!repoPath || (!receipt?.path && !receipt?.branch)) return null;
  const schedule = await loadSchedule();
  const perApp = schedule?.executions?.['task:branch-reconcile']?.perApp;
  if (!perApp || typeof perApp !== 'object') return null;
  let updated = null;
  for (const [appId, record] of Object.entries(perApp)) {
    const outcome = record?.branchReconcileOutcome;
    if (!outcome) continue;
    const rows = [...(outcome.remaining || []), ...(outcome.retirementObligations || [])];
    if (!rows.some(row => sameRetirementCheckout(row, receipt))) continue;
    const app = await getAppById(appId).catch(() => null);
    if (app?.repoPath !== repoPath) continue;
    updated = await recordHeldCheckoutRetirement(appId, receipt);
  }
  return updated;
}

/**
 * A perpetual drain's convergence state, read in ONE pass: the actionable
 * signature its last dispatch was handed, and how many times it has dispatched
 * since it last went idle. Read together because they are decided together — two
 * separate getters also left a read-skew window between the two fields.
 * @returns {Promise<{ signature:string|null, dispatchCount:number }>}
 */
export async function getPerpetualDrainState(taskType, appId = null) {
  const schedule = await loadSchedule();
  const record = resolveExecutionRecord(schedule, taskType, appId);
  return {
    signature: record?.lastActionableSignature ?? null,
    dispatchCount: record?.perpetualDispatchCount || 0,
    ...(record?.branchReconcileAttempts && { branchAttempts: record.branchReconcileAttempts })
  };
}

/**
 * Record that a perpetual drain is dispatching against `signature`: resume the
 * drain (drop any park), remember the signature so a later cycle can recognize
 * "same set ⇒ no progress", and spend one dispatch from the cap's budget — all in
 * a single read-modify-write, so the three facts can never land apart.
 * @returns {Promise<number>} the new consecutive-dispatch count
 */
export async function recordPerpetualDispatch(taskType, appId = null, signature, { branchAttempts } = {}) {
  return updateSchedule(async (schedule) => {
    const record = ensureExecutionRecord(schedule, taskType, appId);
    for (const field of PARK_FIELDS) delete record[field];
    if (branchAttempts !== undefined) record.branchReconcileAttempts = branchAttempts;
    // Mirrors parkPerpetual's signature handling, including the churn detector's
    // `signatureRepeatCount`. A dispatch only happens when the set CHANGED (an
    // unchanged one parks instead), so this is always the "new signature ⇒ first
    // sighting" case — leaving the previous count in place would let the NEXT park
    // increment a stale value, over-reporting "same finding again" to a detector
    // that parks the coordinator and files a tracker issue off that number.
    if (signature == null) {
      delete record.lastActionableSignature;
      delete record.signatureRepeatCount;
    } else {
      record.lastActionableSignature = signature;
      record.signatureRepeatCount = 1;
    }
    const count = (record.perpetualDispatchCount || 0) + 1;
    record.perpetualDispatchCount = count;
    return { result: count, changed: true };
  });
}

/**
 * Reset a perpetual task's cached drain state for an explicit user-initiated
 * re-run. Drops any park AND the convergence `lastActionableSignature` in a
 * single write, so the next detection dispatches on LIVE state alone — never a
 * stale "no-progress" verdict or a cadence park. This is what makes a manual
 * "Run" honor the user's intent to re-check now: without clearing the signature,
 * branch-reconcile/issue-reconcile would re-park `no-progress` against an
 * unchanged-since-last-run set even though the user explicitly asked to re-drive.
 *
 * Branch-reconcile retains its attempted revisions: a manual retry must reach
 * the remaining branches before starting another sweep of the blocked prefix.
 *
 * ONLY a human asking for a re-run may call this. An automated re-issue that
 * borrows the on-demand lane (the perpetual drain's own completion refill) must
 * NOT: clearing the convergence signature and the dispatch counter is precisely
 * what removes every brake the drain has, and the drain then re-dispatches for as
 * long as one actionable item exists. That is the loop that ran ~40 branch-reconcile
 * coordinators overnight on 2026-08-12. See `origin` on the on-demand request.
 *
 * Returns true when it cleared anything.
 */
export async function resetPerpetualForManualRun(taskType, appId = null) {
  return updateSchedule(async (schedule) => {
    const record = resolveExecutionRecord(schedule, taskType, appId);
    if (!record) return { result: false, changed: false };
    let changed = false;
    for (const field of [...PARK_FIELDS, 'lastActionableSignature', 'signatureRepeatCount', 'perpetualDispatchCount']) {
      if (record[field] !== undefined) { delete record[field]; changed = true; }
    }
    return { result: changed, changed };
  });
}

/**
 * Apply the "a human pressed Run" state resets for one on-demand request — and
 * apply NOTHING when the request is an automated drain refill.
 *
 * This is the single home of that policy. It used to be open-coded in each spawn
 * engine that drains the on-demand queue, which is how the loop this guards against
 * got in: the engines could not tell a human "Run Now" from the perpetual drain
 * re-issuing itself through the same queue, so they cleared the drain's park,
 * convergence signature, and dispatch budget on every automated hop. There are
 * THREE consumers of that queue (cos.dequeueNextTask, cosTaskGenerator's
 * spawnPriority0OnDemand, and the idle-review path), so "remember to check origin
 * at each call site" is not a durable invariant — calling this instead is.
 *
 * @param {{taskType:string, origin?:string}} request - the queued on-demand record
 * @param {string|null} [appId] - the app scope, or null for a global task
 * @returns {Promise<boolean>} true when the request was user-initiated (resets
 *   applied) — callers use it to decide whether user-facing feedback is warranted
 */
export async function applyOnDemandRunResets(request, appId = null) {
  // Every AUTOMATED origin inherits the brakes — the drain's own refill and a
  // quota burn alike. Written as "is this a human?" rather than "is this a
  // refill?" so an origin added later fails CLOSED instead of silently
  // acquiring a human's park/convergence resets (a burn that cleared them would
  // re-run a converged drain every time its window opened).
  if (!isUserOriginRequest(request)) return false;
  // A user-initiated "Run" must re-check live state, never honor a stale park or
  // convergence verdict.
  await resetPerpetualForManualRun(request.taskType, appId);
  // It also unparks a failure-parked type (#2616): a human explicitly re-running is
  // an "I've addressed it" signal. A refill carries no such signal from anybody —
  // gating this too keeps a drain that fails every run from clearing its own
  // failure park forever.
  await clearTaskTypeFailurePark(request.taskType, appId);
  return true;
}

/**
 * Check if all runAfter dependencies have completed since this task's last run.
 * Returns { satisfied, pending } where pending lists unfinished dependency task types.
 *
 * Dependencies that are disabled — either globally (missing from the schedule or
 * `enabled: false`) — or use an on-demand interval are skipped, since they will
 * not run automatically and would otherwise block the dependent task indefinitely.
 * A scheduled per-app override keeps its dependency gate active.
 */
async function checkRunAfterDeps(schedule, taskType, appId = null, featureEnabled = createFeatureGate()) {
  const interval = schedule.tasks[taskType];
  const deps = interval?.runAfter;
  if (!deps || deps.length === 0) return { satisfied: true, pending: [] };

  const key = `task:${taskType}`;
  const execution = schedule.executions[key] || { lastRun: null, perApp: {} };
  const ownLastRun = safeDate(appId ? execution.perApp[appId]?.lastRun : execution.lastRun);

  const pending = [];
  for (const dep of deps) {
    const depConfig = schedule.tasks[dep];
    if (!depConfig || !depConfig.enabled) continue;
    if (!(await featureEnabled(depConfig))) continue;
    if (appId && !(await isTaskTypeEnabledForApp(appId, dep))) continue;
    // Same resolver the readiness check uses, so a dependency an app pins to
    // its own cadence is judged on THAT cadence — an app-level cron on a
    // globally on-demand dep is a real gate, not a skippable manual task.
    const depInterval = appId ? await getAppTaskTypeInterval(appId, dep) : null;
    if (resolveAppOverrideCadence({ interval: depInterval }, depConfig).type === INTERVAL_TYPES.ON_DEMAND) continue;

    const depKey = `task:${dep}`;
    const depExec = schedule.executions[depKey] || { lastRun: null, perApp: {} };
    const depLastRun = safeDate(appId ? depExec.perApp[appId]?.lastRun : depExec.lastRun);

    // Dependency must have run after this task's last run (i.e., within the current cycle)
    if (depLastRun <= ownLastRun) {
      pending.push(dep);
    }
  }

  return { satisfied: pending.length === 0, pending };
}

// `now` pins the clock for one scheduler tick so every app is judged against the
// same instant, however long earlier apps took to prepare (#11755).
async function evaluateTaskReadiness(taskType, appId, { featureEnabled, continuingPerpetualDrain, schedule: injected = null, now = Date.now() }) {
  if (appId && requiresInstallWideTarget(taskType)) {
    return { shouldRun: false, reason: TASK_READINESS_REASON.REQUIRES_INSTALL_WIDE_TARGET };
  }
  // `loadSchedule` is an uncached disk read plus a merge over every shipped
  // task default, and a caller building ONE status payload asks this question
  // dozens of times against the snapshot it already holds. Reading it again per
  // question would be both slower and less coherent — a mid-loop write would
  // make the payload describe two different schedules.
  const schedule = injected || await loadSchedule();
  const interval = schedule.tasks[taskType];

  if (!interval || !interval.enabled) {
    return { shouldRun: false, reason: TASK_READINESS_REASON.DISABLED };
  }
  if (!(await featureEnabled(interval))) {
    return { shouldRun: false, reason: TASK_READINESS_REASON.FEATURE_DISABLED, feature: interval.feature };
  }

  // The maintainer role owns recurring cadence; this card is its manual door.
  if (taskType === 'development-watchdog') return { shouldRun: false, reason: TASK_READINESS_REASON.ON_DEMAND_ONLY };

  // Fetch timezone once for reuse across weekday and cron checks
  const timezone = await getUserTimezone();

  // Weekday-only tasks skip weekends (timezone-aware)
  if (interval.weekdaysOnly) {
    const { dayOfWeek } = getLocalParts(new Date(now), timezone);
    if (dayOfWeek === 0 || dayOfWeek === 6) {
      return { shouldRun: false, reason: TASK_READINESS_REASON.WEEKDAY_ONLY };
    }
  }

  if (appId) {
    const enabledForApp = await isTaskTypeEnabledForApp(appId, taskType);
    if (!enabledForApp) {
      return { shouldRun: false, reason: TASK_READINESS_REASON.DISABLED_FOR_APP };
    }
  }

  // Determine the effective cadence: the app's own override outranks the task's
  // global one. `resolveAppOverrideCadence` owns the decode (a raw cron
  // expression, a retired named cadence written by an older install, or the
  // numeric `intervalMs` handler-backed tasks like layered-intelligence use for
  // sub-daily slots), so every surface that has to PREDICT an app's cadence —
  // getScheduleStatus, the Schedule Timeline — resolves it exactly the way this
  // dispatch gate does.
  const [appInterval, appIntervalMs] = appId
    ? await Promise.all([getAppTaskTypeInterval(appId, taskType), getAppTaskTypeIntervalMs(appId, taskType)])
    : [null, null];
  const appCadence = appId
    ? resolveAppOverrideCadence({ interval: appInterval, intervalMs: appIntervalMs }, interval)
    : null;
  const effectiveType = appCadence ? appCadence.type : interval.type;
  const effectiveCron = appCadence ? appCadence.cronExpression : (interval.cronExpression || null);
  // `perpetual` is a task-level global property — per-app rows override the
  // cadence only (see the issue's Out of Scope), so the global flag always wins.
  const isPerpetual = interval.perpetual === true;

  const key = `task:${taskType}`;
  const execution = schedule.executions[key] || { lastRun: null, count: 0, perApp: {} };

  // For per-app tracking, use app-specific execution data
  const appExecution = appId
    ? (execution.perApp[appId] || { lastRun: null, count: 0 })
    : execution;

  // Type-level failure auto-park (#2616): a type whose instances failed
  // FAILURE_PARK_THRESHOLD times in a row is parked for every cadence type
  // until a manual retry or config change clears the ledger. Checked before
  // the cadence switch so it short-circuits every type.
  if (appExecution.failureParkedAt) {
    return {
      shouldRun: false,
      reason: TASK_READINESS_REASON.FAILURE_PARKED,
      failureParkedAt: appExecution.failureParkedAt,
      failureParkReason: appExecution.failureParkReason || null,
      consecutiveFailures: Number(appExecution.consecutiveFailures) || 0
    };
  }

  const lastRun = appExecution.lastRun ? new Date(appExecution.lastRun).getTime() : 0;

  let result;

  // A perpetual task's park record is the drain's brake: the work-detector at
  // DISPATCH time writes `parkedUntil` when nothing is actionable, and this only
  // READS it (so readiness checks never do network I/O). Shared by both cadence
  // variants — an automatic on-demand drain is due whenever it is not parked; a
  // cron+perpetual task additionally needs a cron slot to initiate a drain.
  const perpetualParkResult = () => {
    const parkUntil = parkedUntilMs(appExecution);
    if (parkUntil && now < parkUntil) {
      return {
        shouldRun: false,
        reason: TASK_READINESS_REASON.PERPETUAL_PARKED,
        nextRunAt: new Date(parkUntil).toISOString(),
        parkReason: appExecution.parkReason || null,
        parkActionableCount: appExecution.parkActionableCount ?? null
      };
    }
    return parkUntil ? { shouldRun: true, reason: TASK_READINESS_REASON.PERPETUAL_RECHECK } : null;
  };

  switch (effectiveType) {
    case INTERVAL_TYPES.ON_DEMAND:
      // Drain-until-done when perpetual; otherwise a manual trigger is the only
      // way this ever runs.
      // Missing autoStart preserves existing automatic drains across upgrades.
      // Manual drains only refill after their own successful completion.
      result = isPerpetual && (interval.autoStart !== false || continuingPerpetualDrain)
        ? (perpetualParkResult() || { shouldRun: true, reason: TASK_READINESS_REASON.PERPETUAL_DRAIN })
        : { shouldRun: false, reason: TASK_READINESS_REASON.ON_DEMAND_ONLY };
      break;

    case INTERVAL_TYPES.CRON: {
      // A parked perpetual drain is gated by its park, not by the cron slot —
      // and once the park elapses it is due immediately (computePerpetualRecheckAt
      // already derived that instant from this very expression).
      if (isPerpetual) {
        const parked = perpetualParkResult();
        if (parked) { result = parked; break; }
        if (continuingPerpetualDrain) {
          result = { shouldRun: true, reason: TASK_READINESS_REASON.PERPETUAL_DRAIN };
          break;
        }
        // Unparked: the cron evaluation below decides whether to INITIATE a
        // drain. Once one is running, the completion-refill lane keeps it going
        // back-to-back regardless of subsequent ticks.
      }
      // Cron expression: per-app override (stored as the interval string) or global config
      const cronExpr = effectiveCron;
      if (!isCronExpression(cronExpr)) {
        result = { shouldRun: false, reason: TASK_READINESS_REASON.INVALID_CRON, cronExpression: cronExpr };
        break;
      }

      // Only the current scheduled minute is eligible. Replaying from lastRun
      // makes a schedule edit retroactively create missed work and lets hourly
      // improvement checks launch tasks before their next configured occurrence.
      // Keep lastRun as a lower bound to prevent a second run in the same minute.
      const minuteStart = Math.floor(now / 60_000) * 60_000;
      const fromDate = new Date(Math.max(lastRun || 0, minuteStart - 1));
      const nextRun = parseCronToNextRun(cronExpr, fromDate, timezone);
      if (!nextRun) {
        result = { shouldRun: false, reason: TASK_READINESS_REASON.INVALID_CRON, cronExpression: cronExpr };
        break;
      }
      if (now >= nextRun.getTime()) {
        result = { shouldRun: true, reason: TASK_READINESS_REASON.CRON_DUE, cronExpression: cronExpr, nextRunAt: nextRun.toISOString() };
      } else {
        result = { shouldRun: false, reason: TASK_READINESS_REASON.CRON_COOLDOWN, cronExpression: cronExpr,
          nextRunAt: nextRun.toISOString() };
      }
      break;
    }

    default:
      // Unreachable once normalized — an unreadable cadence must never auto-run.
      result = { shouldRun: false, reason: TASK_READINESS_REASON.ON_DEMAND_ONLY };
  }

  // Escalating failure backoff (#2616): a type with recent consecutive failures
  // (still below the park threshold) slows down — 2^n × base, capped — instead
  // of re-queuing every tick. Applies to every cadence type. Gated on
  // `lastFailureAt` so a never-failed type is unaffected; a success resets the
  // ledger via recordTaskTypeSuccess so the backoff lifts immediately.
  if (result.shouldRun) {
    const consecutiveFailures = Number(appExecution.consecutiveFailures) || 0;
    const lastFailure = appExecution.lastFailureAt ? new Date(appExecution.lastFailureAt).getTime() : 0;
    if (consecutiveFailures > 0 && lastFailure) {
      const backoffMs = computeFailureBackoffMs(consecutiveFailures);
      const sinceFailure = now - lastFailure;
      if (sinceFailure < backoffMs) {
        result = {
          shouldRun: false,
          reason: TASK_READINESS_REASON.FAILURE_COOLDOWN,
          consecutiveFailures,
          failureBackoffMs: backoffMs,
          nextRunIn: backoffMs - sinceFailure,
          nextRunAt: new Date(lastFailure + backoffMs).toISOString(),
          lastErrorCategory: appExecution.lastErrorCategory || null
        };
      }
    }
  }

  // If the task would run, check runAfter dependencies — blocked until all enabled deps have run since our last run.
  // Disabled deps (globally or for this app) are skipped, since they'll never run.
  if (result.shouldRun && interval.runAfter?.length > 0) {
    const depCheck = await checkRunAfterDeps(schedule, taskType, appId, featureEnabled);
    if (!depCheck.satisfied) {
      return { shouldRun: false, reason: TASK_READINESS_REASON.WAITING_ON_DEPENDENCIES, pendingDeps: depCheck.pending };
    }
  }

  if (result.shouldRun && await inputsUnchangedForTask(taskType, appId, schedule)) {
    return { shouldRun: false, reason: TASK_READINESS_REASON.INPUTS_UNCHANGED };
  }

  return result;
}

/**
 * Check whether a task should initiate a scheduled run for an app or globally.
 */
export async function shouldRunTask(taskType, appId = null, { featureEnabled = createFeatureGate(), schedule = null, now = Date.now() } = {}) {
  return evaluateTaskReadiness(taskType, appId, { featureEnabled, continuingPerpetualDrain: false, schedule, now });
}

/**
 * Check whether an already-started perpetual drain should take another hop.
 * If asked to continue a non-perpetual type, its normal cadence remains in force.
 */
export async function shouldContinuePerpetualDrain(taskType, appId = null, { featureEnabled = createFeatureGate(), now = Date.now() } = {}) {
  return evaluateTaskReadiness(taskType, appId, { featureEnabled, continuingPerpetualDrain: true, now });
}

/**
 * Get all enabled task types that are due to run (optionally for a specific app)
 */
export async function getDueTasks(appId = null, { continuingTaskType = null, now = Date.now() } = {}) {
  const schedule = await loadSchedule();
  const due = [];
  const featureEnabled = createFeatureGate();

  for (const [taskType, interval] of Object.entries(schedule.tasks)) {
    if (!interval.enabled) continue;

    const checkTask = taskType === continuingTaskType
      ? shouldContinuePerpetualDrain
      : shouldRunTask;
    const check = await checkTask(taskType, appId, { featureEnabled, now });
    if (check.shouldRun) {
      due.push({ taskType, reason: check.reason, interval });
    }
  }

  return due;
}

/**
 * Get the next task type to run (optionally for a specific app).
 * When `perpetualOnly` is true, return a due perpetual drain or null; never a
 * cron type that would mask it.
 */
export async function getNextTaskType(appId = null, { perpetualOnly = false, continuingTaskType = null, dueTasks = null } = {}) {
  dueTasks ??= await getDueTasks(appId, { continuingTaskType });

  const perpetualDue = dueTasks.filter(t => t.interval.perpetual === true);
  if (perpetualOnly) {
    return perpetualDue.length > 0
      ? { taskType: perpetualDue[0].taskType, reason: 'perpetual-drain' }
      : null;
  }

  // A user-pinned wall-clock schedule outranks a drain: a 9 AM cron must fire at
  // 9 AM even while a perpetual task is mid-backlog. A cron+perpetual task is
  // already gated by its own park, so it can sit in either bucket safely.
  const cronDue = dueTasks.filter(t => t.interval.type === INTERVAL_TYPES.CRON);
  if (cronDue.length > 0) {
    return { taskType: cronDue[0].taskType, reason: 'cron-due' };
  }

  // Perpetual tasks actively draining a backlog keep the app's single
  // improvement slot until their work-detector idles and they park.
  if (perpetualDue.length > 0) {
    return { taskType: perpetualDue[0].taskType, reason: 'perpetual-drain' };
  }

  // Everything else is on-demand: it runs only from an explicit trigger.
  return null;
}

// ============================================================
// On-Demand Requests
// ============================================================

/**
 * Who asked for an on-demand run. `'user'` (the default, and what any request
 * already on disk from before this field existed reads as) means a human pressed
 * Run: the drain engines reset the park, the convergence signature, and the
 * dispatch counter so the check runs against live state. `'refill'` means the
 * perpetual drain re-issued ITSELF through the same lane after a completed run —
 * automated, and therefore NOT allowed to clear its own brakes.
 */
export async function triggerOnDemandTask(taskType, appId = null, {
  emit = true, origin = ON_DEMAND_ORIGINS.USER, targetPullRequest = null, burn = null,
  provider = null, model = null, effort = null,
} = {}) {
  // A targeted run names ONE open PR/MR instead of letting the task pick from
  // the app's whole open set (the PR/MR row's "Review this PR" button). Coerced
  // and validated here so a bad value can't reach the generator's forge filter.
  const requested = Number(targetPullRequest);
  const scopedPullRequest = Number.isInteger(requested) && requested > 0 ? requested : null;
  // Burn provenance rides ON the request because acceptance is asynchronous —
  // an on-demand engine generates the task minutes later and stamps these keys
  // onto it (lib/quotaBurnOrigin.js). Refused BEFORE the schedule write rather
  // than dropped: an unattributable burn would leave a task that reads as
  // cooldown-exempt with no family to credit its refusal to.
  const burnProvenance = origin === ON_DEMAND_ORIGINS.QUOTA_BURN ? normalizeQuotaBurnProvenance(burn) : null;
  if (origin === ON_DEMAND_ORIGINS.QUOTA_BURN && !burnProvenance) {
    return { error: 'A quota-burn request must name the burning family and its burn step' };
  }
  // Optional per-request provider/model/effort pin (the PR/MR row's "Run with"
  // picker) — layered onto the task's metadata by
  // prepareManagedAppImprovementTask as the MOST specific pin, above
  // the schedule interval and the app's own per-app override.
  const providerOverride = (provider || model || effort) ? { provider, model, effort } : null;
  const manual = isManualOnDemandRequest({ origin, burn: burnProvenance });
  // Unattended launches (burn, refill) of an input-gated audit are declined while
  // nothing it reads changed since its last clean run; a human Run always goes.
  if (!manual && await inputsUnchangedForTask(taskType, appId, await loadSchedule())) {
    return { error: `Task type '${taskType}' inputs are unchanged since its last clean run`, reason: TASK_READINESS_REASON.INPUTS_UNCHANGED };
  }
  const request = await updateSchedule(async (schedule) => {
    const tasks = schedule.tasks || {};
    const config = Object.prototype.hasOwnProperty.call(tasks, taskType) ? tasks[taskType] : null;
    const entry = config ? {
      enabled: manual || config.enabled === true,
      featureEnabled: await createFeatureGate()(config),
      feature: config.feature || null,
      // A quota burn faces this gate alongside a human Run: a type owned by
      // another automation is not something an unattended burn may commandeer
      // either. Only the drain's own REFILL is exempt — it is that automation
      // re-issuing itself.
      eligible: origin === ON_DEMAND_ORIGINS.REFILL || getTaskTypeInvocation(taskType).userInvokable !== false,
      // Per-app enablement is a rung for an UNATTENDED origin only. A human
      // pressing Run is deliberately overriding the app's cadence switch — the
      // drain's applyOnDemandRunResets exists for exactly that — while a burn
      // or a notification hand-off picks its own target and must respect the
      // switch the user set. Omitted,
      // the ladder skips the rung.
      appIds: (origin === ON_DEMAND_ORIGINS.QUOTA_BURN || origin === ON_DEMAND_ORIGINS.GITHUB_NOTIFICATION) && !manual
        ? enabledAppIdsByTaskType(await getActiveApps().catch(() => [])).get(taskType) || []
        : undefined,
    } : null;

    // The ladder itself lives in lib/quotaBurnTaskRef.js so the Quota Burn page
    // renders exactly the verdict this dispatch would produce (#6405).
    const gate = evaluateOnDemandEligibility({ taskType, appId, entry });
    if (gate) return { result: { error: gate.reason }, changed: false };

    // The master Improve switch is the one ladder input that pays a state.json
    // read, so it is resolved only once the cheap rungs pass and then fed back
    // through the SAME ladder — the rung is never restated here. Rejecting on it
    // matters: the request would be silently dropped downstream.
    const improvement = evaluateOnDemandEligibility({
      taskType, appId, entry, improvementEnabled: isImprovementEnabled(await loadState()),
    });
    if (improvement) return { result: { error: improvement.reason }, changed: false };

    if (!schedule.onDemandRequests) {
      schedule.onDemandRequests = [];
    }

    const request = {
      id: `demand-${randomUUID()}`,
      taskType,
      appId,
      origin,
      requestedAt: new Date().toISOString(),
      ...(scopedPullRequest ? { targetPullRequest: scopedPullRequest } : {}),
      ...(burnProvenance ? { burn: burnProvenance } : {}),
      ...(providerOverride ? { providerOverride } : {})
    };

    schedule.onDemandRequests.push(request);
    return { result: request, changed: true };
  });

  if (request.error) return request;

  // Operator-action ledger (#5594): ONLY a human pressing Run Now. The perpetual
  // drain re-issues itself through this same lane with `origin: REFILL` — logging
  // that would fill the ledger with events the user never performed and make
  // "what did I trigger?" unanswerable.
  if (isUserOriginRequest(request)) {
    await recordUserAction({
      type: 'cos.schedule.trigger',
      target: taskType,
      targetName: appId,
      summary: `Ran scheduled task '${taskType}' on demand${appId ? ` for ${appId}` : ''}${scopedPullRequest ? ` (#${scopedPullRequest})` : ''}`,
      payload: { taskType, appId: appId ?? null, requestId: request.id, ...(scopedPullRequest ? { targetPullRequest: scopedPullRequest } : {}) },
      source: { service: 'taskSchedule', fn: 'triggerOnDemandTask' },
      happenedAt: request.requestedAt,
      dedupeKey: `cos.schedule.trigger:${request.id}`,
    });
  }

  emitLog('info', `On-demand task requested: ${taskType}`, { appId }, '📅 TaskSchedule');
  // The event's only consumer is a `dequeueNextTask()` trigger (cos.js). Callers
  // that already own their own dequeue (the perpetual drain-on-completion refill,
  // which enqueues a re-issue and then drains it via its OWN
  // dequeueNextTask({ ignoreTaskId })) pass `emit: false` to avoid a redundant
  // SECOND dequeue of the same request — which would re-run recordExecution + the
  // work-detector probe. The manual "Run Now" route keeps the default so its
  // request is picked up promptly.
  if (emit) cosEvents.emit('task:on-demand-requested', request);

  return request;
}

/**
 * Queue the next item in a perpetual drain without treating it as a human
 * pressing Run. The two options are an inseparable policy pair: the refill's
 * completion handler owns dequeue, and the automated origin must preserve the
 * drain's park, convergence signature, and dispatch counter.
 */
export async function queuePerpetualRefill(taskType, appId) {
  return triggerOnDemandTask(taskType, appId, {
    emit: false,
    origin: ON_DEMAND_ORIGINS.REFILL,
  });
}

export async function getOnDemandRequests() {
  const schedule = await loadSchedule();
  const featureEnabled = createFeatureGate();
  return getAvailableOnDemandRequests(schedule, featureEnabled);
}

async function getAvailableOnDemandRequests(schedule, featureEnabled) {
  const requests = schedule.onDemandRequests || [];
  const availability = await Promise.all(requests.map((request) => (
    featureEnabled(schedule.tasks?.[request.taskType])
  )));
  return requests.filter((_request, index) => availability[index]);
}

export async function clearOnDemandRequest(requestId) {
  return updateSchedule(async (schedule) => {
    if (!schedule.onDemandRequests) return { result: null, changed: false };

    const index = schedule.onDemandRequests.findIndex(r => r.id === requestId);
    if (index === -1) return { result: null, changed: false };

    const cleared = schedule.onDemandRequests.splice(index, 1)[0];
    return { result: cleared, changed: true };
  });
}

// ============================================================
// Schedule Status
// ============================================================

/**
 * The apps that run `taskType` on a cron of their OWN — enabled for the task,
 * and stating a cadence rather than inheriting the task's.
 *
 * Both callers that have to reason about an app-level clock start here:
 * `getUpcomingTasks` (which app boundary should wake the daemon) and
 * `resolveHiddenAppSchedules` (which schedules the UI cannot see on the global
 * row). They differ only in what they do with the result, so the override →
 * cadence walk lives here once.
 *
 * `allOverrides[i]` is the override map for `activeApps[i]`, in the caller's
 * own order; entries come back as `{ app, cronExpression }` in that order.
 */
function appsWithOwnCron(taskType, interval, activeApps, allOverrides) {
  const matched = [];
  for (let i = 0; i < activeApps.length; i++) {
    const override = allOverrides[i]?.[taskType];
    if (override?.enabled !== true) continue;
    const cadence = resolveAppOverrideCadence(override, interval);
    // An inheriting app rides the task's own cadence; only an app stating its
    // own cron adds a clock the global row does not already carry.
    if (cadence.inherited || cadence.type !== INTERVAL_TYPES.CRON) continue;
    if (!isCronExpression(cadence.cronExpression)) continue;
    matched.push({ app: activeApps[i], cronExpression: cadence.cronExpression.trim() });
  }
  return matched;
}

/**
 * The per-app cron cadences a task's GLOBAL row cannot express.
 *
 * Returns one entry per enabled app whose own override resolves to a valid cron
 * expression that differs from whatever the task runs on globally — the state
 * where a task left on-demand globally carries an app-level cron and therefore
 * read as "manual only" on every surface. Apps that inherit the global cadence, or that
 * restate the same expression, are omitted: they already sit on the global
 * track, and listing them would make "3 apps scheduled" mean two different
 * things depending on the task.
 *
 * `shouldRunTask` supplies each entry's next slot rather than a local cron
 * parse, so the time shown is the one dispatch would actually honor (per-app
 * last run, failure backoff, dependency gates and all).
 */
async function resolveHiddenAppSchedules(taskType, interval, activeApps, allOverrides, featureEnabled, schedule) {
  const globalCron = interval.type === INTERVAL_TYPES.CRON && isCronExpression(interval.cronExpression)
    ? interval.cronExpression.trim()
    : null;
  // An app restating the task's own expression sits on the global track
  // already; counting it would make "N apps scheduled" mean something
  // different per task.
  const candidates = appsWithOwnCron(taskType, interval, activeApps, allOverrides)
    .filter(candidate => candidate.cronExpression !== globalCron);
  if (candidates.length === 0) return [];

  const checks = await mapWithConcurrency(candidates, 8, ({ app }) =>
    shouldRunTask(taskType, app.id, { featureEnabled, schedule }));
  return candidates.map(({ app, cronExpression }, i) => ({
    appId: app.id,
    appName: app.name || app.id,
    cronExpression,
    nextRunAt: checks[i]?.nextRunAt || null,
    shouldRun: checks[i]?.shouldRun === true,
    reason: checks[i]?.reason || null,
    missedSlot: checks[i]?.missedSlot || null
  }));
}

export async function getScheduleStatus() {
  // Surface the master Improve toggle so the UI can disable Run Now affordances
  const [schedule, state] = await Promise.all([loadSchedule(), loadState()]);
  const featureEnabled = createFeatureGate();
  const onDemandRequests = (await getAvailableOnDemandRequests(schedule, featureEnabled))
    .filter(request => getTaskTypeInvocation(request.taskType).visibility !== 'hidden');

  const status = {
    lastUpdated: schedule.lastUpdated,
    improvementEnabled: isImprovementEnabled(state),
    tasks: {},
    templates: schedule.templates,
    onDemandRequests,
    learningAdjustmentsActive: 0,
    dataInputCatalog: getTaskDataInputCatalog()
  };

  // Fetch active apps once for per-app override aggregation
  const activeApps = await getActiveApps();
  const totalAppCount = activeApps.length;

  for (const [taskType, interval] of Object.entries(schedule.tasks)) {
    if (!(await featureEnabled(interval))) continue;
    const invocation = getTaskTypeInvocation(taskType);
    if (invocation.visibility === 'hidden') continue;
    const execution = schedule.executions[`task:${taskType}`] || { lastRun: null, count: 0, perApp: {} };
    const promptInfo = getTaskTypePromptInfo(taskType);

    // Get learning adjustment info
    const baseInterval = interval.intervalMs || DAY;
    const learningInfo = await getPerformanceAdjustedInterval(taskType, baseInterval);

    // Check global shouldRun status
    const check = await shouldRunTask(taskType, null, { featureEnabled, schedule });

    const isEnabledForApp = (override) => override?.enabled === true;
    const appOverrides = {};
    let enabledAppCount = 0;
    const allOverrides = await mapWithConcurrency(activeApps, 8, (app) => getAppTaskTypeOverrides(app.id));
    for (let i = 0; i < activeApps.length; i++) {
      const override = allOverrides[i][taskType];
      if (override) {
        appOverrides[activeApps[i].id] = {
          enabled: isEnabledForApp(override),
          interval: override.interval || null,
          // Surface the per-app provider/model pin: it OUTRANKS the global pin at
          // spawn for every task type (#4783), so omitting it here made the Schedule
          // page's provider read as authoritative when it wasn't (an app pinned to
          // another provider ran on that one with no hint why).
          ...(override.providerId && { providerId: override.providerId }),
          ...(override.model && { model: override.model }),
          ...(override.taskMetadata && { taskMetadata: override.taskMetadata })
        };
      }
      if (isEnabledForApp(override)) {
        enabledAppCount++;
      }
    }

    // Cadences that are INVISIBLE from the global row: an enabled app pinning a
    // cron expression the task itself does not carry. The reported case is a
    // task left 'on-demand' globally while one app schedules it — the app is
    // genuinely clock-driven, so a Schedule card reading "Manual trigger only"
    // and a Timeline filing it under "no clock time" are both wrong.
    // An app that inherits, or that restates the global expression, adds
    // nothing to show and is left out so the count answers "how many apps run
    // this on a schedule you can't see here".
    const appSchedules = await resolveHiddenAppSchedules(taskType, interval, activeApps, allOverrides, featureEnabled, schedule);

    const auditMeta = getAuditScheduleMetadata(taskType);
    const taskStatus = {
      ...interval,
      ...auditMeta,
      displayName: interval.displayName || (auditMeta.displayName !== taskType ? auditMeta.displayName : (DEFAULT_TASK_INTERVALS[taskType]?.displayName || taskType)),
      labels: interval.labels || [],
      // Advisory ordering: WHICH tasks to run first, named by task type. Never
      // a dispatch gate — that is `runAfter`, spread in from `interval` above.
      //
      // Layered at READ time like every other catalog-derived field here
      // (displayName, defaultLabels, runGuidance): a stored value wins, and an
      // absent one inherits the shipped order — so editing AUDIT_SUGGESTED_AFTER
      // reaches existing installs without a migration. An explicit `[]` is a
      // user's clear and is key-present, so `??` keeps it.
      suggestedAfter: normalizeSuggestedAfter(interval.suggestedAfter ?? AUDIT_SUGGESTED_AFTER[taskType], taskType),
      // WHY this task sits where it does — rationale for the order above, not
      // the order itself.
      runGuidance: AUDIT_RUN_GUIDANCE[taskType] || (isAuditTaskType(taskType) ? 'Run when this area has a concrete need; coordinate overlapping fixes and validate after each merge.' : null),
      lastRun: execution.lastRun,
      runCount: execution.count,
      globalLastRun: execution.lastRun,
      globalRunCount: execution.count,
      // The triage lane's last ranked "Recommended next audits" (#12085).
      recommendedAudits: execution.recommendedAudits || null,
      perAppCount: Object.keys(execution.perApp).length,
      appOverrides,
      enabledAppCount,
      totalAppCount,
      appSchedules,
      status: check,
      learningAdjusted: learningInfo.adjusted,
      learningMultiplier: learningInfo.multiplier,
      successRate: learningInfo.successRate,
      dataPoints: learningInfo.dataPoints,
      adjustedIntervalMs: learningInfo.adjustedIntervalMs,
      recommendation: learningInfo.recommendation,
      description: interval.description || getTaskTypeDescription(taskType),
      promptMode: promptInfo.mode,
      ...(promptInfo.description ? { promptDescription: promptInfo.description } : {}),
      invocation,
      // Whether a "Run Now" with NO app is this type's real run (it sweeps every
      // managed app in one dispatch). Served from the server registry rather than
      // mirrored in client constants, so the UI cannot drift from the set the
      // dispatch engines actually treat as install-wide.
      installWide: INSTALL_WIDE_TASK_TYPES.has(taskType),
      // Whether PortOS executes this type ITSELF (services/scheduledHandlers/)
      // rather than dispatching an agent. Served from the registry rather than
      // mirrored in client constants for the same reason as `installWide`: the
      // UI must not drift from the set the dispatch engines actually treat as
      // programmatic. It drives the Run Now affordance (no app picker — these
      // never target a managed app) and the prompt panel (there is no prompt).
      programmatic: isProgrammaticScheduledTaskType(taskType)
    };

    // Include default stage prompts for pipeline tasks so UI can display them
    if (interval.taskMetadata?.pipeline?.stages?.length > 0) {
      taskStatus.stagePrompts = interval.taskMetadata.pipeline.stages.map(stage =>
        DEFAULT_TASK_PROMPTS[stage.promptKey] || null
      );
    }

    // Surface agent-managed flags so the UI can lock the corresponding toggles
    if (MANAGED_AGENT_OPTIONS[taskType]) {
      taskStatus.managedAgentOptions = MANAGED_AGENT_OPTIONS[taskType];
    }

    if (isAuditTaskType(taskType)) {
      taskStatus.fileIssuesCapable = true;
      taskStatus.defaultFileIssues = defaultFileIssuesFor(taskType);
      if (auditDoWorkRequiresWorktree(taskType)) {
        taskStatus.doWorkRequiresWorktree = true;
      }
    } else if (taskType === 'user-action-review') {
      // Not an audit-catalog type (no mode-contract injection — its
      // alternative to filing issues is queueing CoS tasks, not editing code),
      // but its deliverable posture is the same fileIssues toggle, so the
      // schedule UI surfaces the switch the same way.
      taskStatus.fileIssuesCapable = true;
      taskStatus.defaultFileIssues = true;
    }

    // Perpetual tasks park PER-APP (parkPerpetual is called with the appId), so
    // the global `status` above (shouldRunTask with no appId) always reads
    // 'perpetual-drain' for app-scoped tasks like claim-issue/claim-work even
    // when every app is parked. Aggregate the per-app (and global) park records
    // so the UI can show the true parked/draining state and the soonest recheck.
    // Projects the shared aggregatePerpetualParks rollup (same park semantics as
    // the getUpcomingTasks eligibility derivation below).
    if (interval.perpetual) {
      const parks = aggregatePerpetualParks(execution, Date.now());
      // Named apart from the `perpetual` BOOLEAN this config carries: the flag
      // says the task drains, this says what its drain is doing right now.
      taskStatus.perpetualStatus = {
        globalParked: parks.globalParked,
        parkedAppCount: parks.parkedAppCount,
        trackedAppCount: parks.trackedAppCount,
        nextRecheckAt: parks.soonestParkAt === null ? null : new Date(parks.soonestParkAt).toISOString(),
        parkReason: parks.parkReason,
        ...(parks.parkCounts != null && { parkCounts: parks.parkCounts }),
        ...(parks.parkSkipCauses != null && { parkSkipCauses: parks.parkSkipCauses }),
        // A stall means the probe (e.g. gh/glab) has failed several evaluations
        // in a row WITHOUT parking — the drain keeps ticking, so it can be
        // present at the same time `globalParked`/`parkedAppCount` read "not
        // parked". Null when the probe is healthy.
        stall: aggregatePerpetualStall(execution)
      };
    }

    if (taskType === 'branch-reconcile') {
      const outcomes = [
        ...(execution.branchReconcileOutcome ? [[null, execution.branchReconcileOutcome]] : []),
        ...Object.entries(execution.perApp || {}).filter(([, record]) => record.branchReconcileOutcome)
          .map(([appId, record]) => [appId, record.branchReconcileOutcome]),
      ];
      taskStatus.reconcileOutcomes = Object.fromEntries(
        await mapWithConcurrency(outcomes, 8, async ([appId, outcome]) => [appId, await reconcileMissingInventory(appId, outcome)])
      );
    }
    status.tasks[taskType] = taskStatus;

    if (learningInfo.adjusted) {
      status.learningAdjustmentsActive++;
    }
  }

  return status;
}

/**
 * Reset execution history for a task type
 */
export async function resetExecutionHistory(taskType, appId = null) {
  const result = await updateSchedule(async (schedule) => {
    const key = `task:${taskType}`;

    if (!schedule.executions[key]) {
      return { result: { error: 'No execution history found' }, changed: false };
    }

    if (appId) {
      if (schedule.executions[key].perApp?.[appId]) {
        delete schedule.executions[key].perApp[appId];
      }
    } else {
      delete schedule.executions[key];
    }

    return { result: { success: true, taskType, appId }, changed: true };
  });

  if (result.error) return result;
  emitLog('info', `Reset execution history for ${taskType}`, { appId }, '📅 TaskSchedule');

  return result;
}

// ============================================================
// Upcoming Tasks Preview
// ============================================================

/**
 * Aggregate a perpetual task's park records into a single upcoming-eligibility
 * verdict for getUpcomingTasks.
 *
 * Perpetual parks are recorded PER-APP (parkPerpetual is always called with an
 * appId — see applyPerpetualWorkGate / the reconcile blocks in cosTaskGenerator),
 * so the top-level execution record is only a container and never carries its own
 * `parkedUntil` for the app-scoped drains (claim-issue, claim-work, branch-/
 * issue-reconcile). The GLOBAL `shouldRunTask` therefore always reads
 * 'perpetual-drain' (shouldRun:true) even when every app is parked on its recheck
 * cadence — which made getUpcomingTasks report the task 'ready' forever and hid
 * its real next-recheck boundary (e.g. a `recheckCron: '0 9 * * *'`) from
 * scheduleNextImprovementCheck. The daemon then never woke AT 9am; the parked
 * drain only resumed on the ≤1h fallback poll, so a task configured for 9am ran
 * up to an hour late (or read as "didn't run").
 *
 * Derive eligibility from the shared aggregatePerpetualParks rollup instead (see
 * its GLOBAL-RECORD INCLUSION RULE for which scopes count). Returns:
 *   - null                                    → no tracked scope yet (caller keeps its global 'ready' default)
 *   - { status:'ready', eligibleAt:now }      → some tracked scope is due now (unparked or park elapsed)
 *   - { status:'scheduled', eligibleAt:<ms> } → every tracked scope parked; soonest recheck
 */
function perpetualUpcomingEligibility(execution, now) {
  const parks = aggregatePerpetualParks(execution, now);
  if (parks.trackedCount === 0) return null;
  return parks.anyDueNow
    ? { status: 'ready', eligibleAt: now }
    : { status: 'scheduled', eligibleAt: parks.soonestParkAt };
}

export async function getUpcomingTasks(limit = 10) {
  const schedule = await loadSchedule();
  const now = Date.now();
  const upcoming = [];
  const featureEnabled = createFeatureGate();
  // The improvement daemon queues per-app work, so its wake-up preview must
  // include app-scoped cadence overrides. In particular, an app can opt into a
  // cron expression while the global task remains on-demand; omitting that
  // boundary leaves the hourly fallback as the only chance to notice the slot.
  //
  // Strict on purpose (#7527): a rejected inventory/override read used to be
  // swallowed into [] / {}, which looked like "no apps configured" rather than
  // "the calculation is unavailable" — cosJobScheduler.scheduleNextImprovementCheck
  // would then arm its 1h fallback and could sleep through a cron minute a
  // healthy read would have caught. Let the rejection propagate; the caller
  // owns the retry.
  const activeApps = await getActiveApps();
  const activeAppOverrides = activeApps.length > 0
    ? await mapWithConcurrency(activeApps, 8, (app) => getAppTaskTypeOverrides(app.id))
    : [];

  for (const [taskType, interval] of Object.entries(schedule.tasks)) {
    if (!interval.enabled) continue;
    if (!(await featureEnabled(interval))) continue;
    if (getTaskTypeInvocation(taskType).visibility === 'hidden') continue;

    const check = await shouldRunTask(taskType, null, { featureEnabled, schedule });
    const execution = schedule.executions[`task:${taskType}`] || { lastRun: null, count: 0 };

    // `shouldRunTask(taskType, appId)` resolves the same effective cadence used
    // by the queue path, including an app's raw cron override and its own last
    // run. A due app makes the task ready; otherwise the soonest app boundary
    // is the wake-up deadline. This also handles a globally on-demand task that
    // has no global candidate but is cron-scheduled for one managed app.
    // An inheriting app rides the global `check` above; only an app stating its
    // OWN cron adds a boundary the global cadence cannot see.
    const scheduledApps = appsWithOwnCron(taskType, interval, activeApps, activeAppOverrides)
      .map(candidate => candidate.app);
    const appChecks = scheduledApps.length > 0
      ? await mapWithConcurrency(scheduledApps, 8, (app) =>
        shouldRunTask(taskType, app.id, { featureEnabled, schedule }))
      : [];
    const appReady = appChecks.some(appCheck => appCheck?.shouldRun);
    const futureAppTimes = appChecks.map(appCheck => Date.parse(appCheck?.nextRunAt))
      .filter(time => Number.isFinite(time) && time > now);
    const nextAppAt = futureAppTimes.length ? Math.min(...futureAppTimes) : null;
    const appUpcoming = appReady
      ? { status: 'ready', eligibleAt: now }
      : nextAppAt !== null ? { status: 'scheduled', eligibleAt: nextAppAt } : null;
    const futureTimes = [Date.parse(check.nextRunAt), nextAppAt]
      .filter(time => Number.isFinite(time) && time > now);
    const nextScheduledAt = futureTimes.length ? Math.min(...futureTimes) : null;

    // On-demand tasks have no wall-clock position — unless they are perpetual,
    // whose park/recheck boundary IS the schedule the daemon must wake on, or
    // an enabled managed app supplies a scheduled override.
    if (interval.type === INTERVAL_TYPES.ON_DEMAND && (!interval.perpetual || interval.autoStart === false) && !appUpcoming) continue;

    let eligibleAt = null;
    let taskStatus = null;

    if (check.shouldRun) {
      eligibleAt = now;
      taskStatus = 'ready';
    } else if (check.nextRunAt) {
      eligibleAt = new Date(check.nextRunAt).getTime();
      taskStatus = 'scheduled';
    }

    if (appUpcoming) {
      if (appUpcoming.status === 'ready') {
        taskStatus = 'ready';
        eligibleAt = now;
      } else if (taskStatus !== 'ready' && (eligibleAt === null || appUpcoming.eligibleAt < eligibleAt)) {
        taskStatus = 'scheduled';
        eligibleAt = appUpcoming.eligibleAt;
      }
    }

    // No global or per-app wall-clock candidate (for example a plain
    // on-demand task, or a task blocked by a weekday/dependency gate) has no
    // place in an upcoming schedule preview.
    if (!taskStatus) continue;

    // Perpetual tasks park per-app, so the global `check` above can't see the
    // recheck boundary — re-derive status/eligibility from the park records so
    // scheduleNextImprovementCheck wakes the daemon AT the next recheck (e.g. 9am)
    // instead of only on the ≤1h fallback poll. See perpetualUpcomingEligibility.
    if (interval.perpetual) {
      const perpetual = perpetualUpcomingEligibility(execution, now);
      if (perpetual) {
        taskStatus = perpetual.status;
        eligibleAt = perpetual.eligibleAt;
      }
    }

    upcoming.push({
      taskType,
      intervalType: interval.type,
      nextScheduledAt,
      status: taskStatus,
      eligibleAt,
      eligibleIn: eligibleAt - now,
      eligibleInFormatted: formatTimeRemaining(eligibleAt - now),
      lastRun: execution.lastRun,
      lastRunFormatted: execution.lastRun ? formatRelativeTime(new Date(execution.lastRun).getTime()) : 'never',
      runCount: execution.count,
      successRate: check.successRate ?? null,
      learningAdjusted: check.learningApplied || false,
      adjustmentMultiplier: check.adjustmentMultiplier || 1.0,
      description: interval.description || getTaskTypeDescription(taskType)
    });
  }

  upcoming.sort((a, b) => {
    if (a.status === 'ready' && b.status !== 'ready') return -1;
    if (b.status === 'ready' && a.status !== 'ready') return 1;
    return a.eligibleAt - b.eligibleAt;
  });

  return upcoming.slice(0, limit);
}

function formatTimeRemaining(ms) {
  if (ms <= 0) return 'now';
  const minutes = Math.floor(ms / 60000);
  const hours = Math.floor(minutes / 60);
  const days = Math.floor(hours / 24);
  if (days > 0) return `${days}d ${hours % 24}h`;
  if (hours > 0) return `${hours}h ${minutes % 60}m`;
  if (minutes > 0) return `${minutes}m`;
  return '< 1m';
}

function formatRelativeTime(timestamp) {
  const now = Date.now();
  const diff = now - timestamp;
  const minutes = Math.floor(diff / 60000);
  const hours = Math.floor(minutes / 60);
  const days = Math.floor(hours / 24);
  if (days > 0) return `${days}d ago`;
  if (hours > 0) return `${hours}h ago`;
  if (minutes > 0) return `${minutes}m ago`;
  return 'just now';
}