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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* 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';
}