@apisurf/ngn-core 0.3.1 → 0.5.0

package/dist/core.js

@@ -325,7 +325,8 @@ var Entry = class {
       shouldRetry: taskExports.shouldRetry,
       onSuccess: taskExports.onSuccess,
       onError: taskExports.onError,
-      onComplete: taskExports.onComplete
+      onComplete: taskExports.onComplete,
+      next: taskExports.next
     };
   }
   get paths() {
@@ -364,7 +365,8 @@ function runDeadline({
   startedAt,
   scheduledAt,
   nextAt,
-  budgetMs
+  budgetMs,
+  periodMs = null
 }) {
   const candidates = [];
   if (nextAt != null) {
@@ -372,23 +374,39 @@ function runDeadline({
     candidates.push(nextAt - Math.min(5e3, Math.max(0, period) * 0.1));
   }
   if (budgetMs != null) candidates.push(startedAt + budgetMs);
+  else if (nextAt == null && periodMs != null) candidates.push(startedAt + periodMs);
   return candidates.length ? Math.floor(Math.min(...candidates)) : null;
 }
-function deadlineSignal(deadline) {
+function deadlineSignal(deadline, outer) {
   const controller = new AbortController();
-  if (deadline == null) return { signal: controller.signal, dispose: () => {
-  } };
+  const onOuter = () => controller.abort(outer?.reason);
+  if (outer?.aborted) onOuter();
+  else outer?.addEventListener("abort", onOuter, { once: true });
+  const detach = () => outer?.removeEventListener("abort", onOuter);
+  if (deadline == null) return { signal: controller.signal, dispose: detach };
   const abort = () => controller.abort(new Error("The run reached its deadline"));
   const delay = deadline - Date.now();
   if (delay <= 0) {
     abort();
-    return { signal: controller.signal, dispose: () => {
-    } };
-  }
-  const timer = setTimeout(abort, delay);
-  timer.unref();
-  return { signal: controller.signal, dispose: () => clearTimeout(timer) };
+    return { signal: controller.signal, dispose: detach };
+  }
+  let timer;
+  const arm = () => {
+    const left = deadline - Date.now();
+    if (left <= 0) return abort();
+    timer = setTimeout(arm, Math.min(left, MAX_TIMER_MS));
+    timer.unref();
+  };
+  arm();
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      clearTimeout(timer);
+      detach();
+    }
+  };
 }
+var MAX_TIMER_MS = 2 ** 31 - 1;
 
 // src/runtime/locks.ts
 var LockBusyError = class extends Error {
@@ -401,10 +419,14 @@ var LockBusyError = class extends Error {
 var DEFAULT_TTL_MS = 6e4;
 var MAX_POLL_MS = 1e3;
 var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var RESERVED_LOCK_PREFIX = "ngn:";
 function assertLockName(name) {
   if (typeof name !== "string" || !name.trim()) {
     throw new Error(`A lock name must be a non-empty string, got ${JSON.stringify(name)}`);
   }
+  if (name.startsWith(RESERVED_LOCK_PREFIX)) {
+    throw new Error(`Lock "${name}": names starting with "${RESERVED_LOCK_PREFIX}" are ngn's own`);
+  }
 }
 function createRunLocks(service, taskRunId) {
   async function tryHold(name, ttlMs) {
@@ -477,6 +499,11 @@ function exclusiveNames(value, taskPath) {
         `Invalid exclusive for ${taskPath}: expected a lock name or a list of them, got ${JSON.stringify(value)}`
       );
     }
+    if (name.startsWith(RESERVED_LOCK_PREFIX)) {
+      throw new Error(
+        `Invalid exclusive for ${taskPath}: "${name}" starts with "${RESERVED_LOCK_PREFIX}", which ngn keeps for itself`
+      );
+    }
   }
   return names;
 }
@@ -1176,8 +1203,157 @@ function breakerSkips(failedInARow, breaker) {
   return Math.min(breaker.maxSkip, 2 ** (failedInARow - breaker.after));
 }
 
+// src/runtime/clock.ts
+var systemClock = {
+  now: () => Date.now(),
+  sleep(ms, signal) {
+    return new Promise((resolve2) => {
+      if (signal?.aborted) return resolve2();
+      const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        resolve2();
+      };
+      const timer = setTimeout(done, Math.max(0, ms));
+      signal?.addEventListener("abort", done, { once: true });
+    });
+  }
+};
+var WAIT_STEP_MS = 1e3;
+
+// src/runtime/cron.ts
+import { Cron } from "croner";
+var CRON_OPTIONS = { mode: "5-or-6-parts", paused: true };
+var parsed = /* @__PURE__ */ new Map();
+function cronOf(pattern) {
+  let cron = parsed.get(pattern);
+  if (!cron) {
+    cron = new Cron(pattern, CRON_OPTIONS);
+    parsed.set(pattern, cron);
+  }
+  return cron;
+}
+function isCronPatternValid(pattern) {
+  try {
+    cronOf(pattern);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function nextCronSlot(pattern, after) {
+  return cronOf(pattern).nextRun(new Date(after))?.getTime() ?? null;
+}
+
+// src/runtime/timing.ts
+var INTERVAL_KEYS = /* @__PURE__ */ new Set(["every", "edge", "min", "max", "backoff"]);
+var BACKOFF_KEYS = /* @__PURE__ */ new Set(["factor", "jitter"]);
+var MIN_EVERY_MS = 1e3;
+var DEFAULT_MAX_FACTOR = 32;
+var DEFAULT_BACKOFF = { factor: 2, jitter: 0.1 };
+function unknownKeys(value, known, what = "") {
+  const unknown = Object.keys(value).filter((key) => !known.has(key));
+  if (!unknown.length) return null;
+  return `unknown ${what}${unknown.length === 1 ? "key" : "keys"} ${unknown.join(", ")}`;
+}
+function resolveTiming(value, taskPath) {
+  if (value == null) throw new Error(`timing pattern is missing for ${taskPath}`);
+  if (typeof value === "string") {
+    if (!isCronPatternValid(value))
+      throw new Error(`Invalid cron pattern: ${value} for ${taskPath}`);
+    return { kind: "cron", pattern: value };
+  }
+  const fail = (what) => {
+    throw new Error(`Invalid timing for ${taskPath}: ${what}`);
+  };
+  if (typeof value !== "object" || Array.isArray(value)) {
+    fail('expected a cron pattern or an object like { every: "5m" }');
+  }
+  const timing = value;
+  const unknown = unknownKeys(timing, INTERVAL_KEYS);
+  if (unknown) fail(unknown);
+  if (timing.every == null) fail("every is required");
+  const everyMs = toMs(timing.every, `timing.every for ${taskPath}`);
+  if (everyMs < MIN_EVERY_MS) fail("every must be at least 1s");
+  const { edge = "leading" } = timing;
+  if (edge !== "leading" && edge !== "trailing") {
+    fail(`edge must be "leading" or "trailing", got ${JSON.stringify(edge)}`);
+  }
+  return {
+    kind: "interval",
+    everyMs,
+    edge,
+    ...resolveLimits(timing, everyMs, taskPath, fail),
+    backoff: resolveBackoff(timing.backoff, fail)
+  };
+}
+function resolveLimits(timing, everyMs, taskPath, fail) {
+  const limit = (key, fallback) => timing[key] == null ? fallback : toMs(timing[key], `timing.${key} for ${taskPath}`);
+  const minMs = limit("min", everyMs);
+  const maxMs = limit("max", everyMs * DEFAULT_MAX_FACTOR);
+  if (minMs < MIN_EVERY_MS) fail("min must be at least 1s");
+  if (minMs > everyMs) fail("min must not be more than every");
+  if (everyMs > maxMs) fail("every must not be more than max");
+  return { minMs, maxMs };
+}
+function resolveBackoff(value, fail) {
+  if (value === false) return null;
+  if (value == null || value === true) return DEFAULT_BACKOFF;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    fail("backoff must be false or an object like { factor: 2, jitter: 0.1 }");
+  }
+  const backoff = value;
+  const unknown = unknownKeys(backoff, BACKOFF_KEYS, "backoff ");
+  if (unknown) fail(unknown);
+  const { factor = DEFAULT_BACKOFF.factor, jitter = DEFAULT_BACKOFF.jitter } = backoff;
+  if (typeof factor !== "number" || !Number.isFinite(factor) || factor < 1) {
+    fail(`backoff.factor must be a number of at least 1, got ${JSON.stringify(factor)}`);
+  }
+  if (typeof jitter !== "number" || !(jitter >= 0 && jitter <= 1)) {
+    fail(`backoff.jitter must be a number from 0 to 1, got ${JSON.stringify(jitter)}`);
+  }
+  return { factor, jitter };
+}
+function timingFromFlag(flag) {
+  try {
+    if (toMs(flag) >= MIN_EVERY_MS) return { every: flag };
+  } catch {
+  }
+  return isCronPatternValid(flag) ? flag : null;
+}
+var NAMED_DELAYS = /* @__PURE__ */ new Set(["every", "min", "max"]);
+function nextDelay(value) {
+  if (typeof value === "string" && NAMED_DELAYS.has(value)) return value;
+  if (typeof value !== "string" && typeof value !== "number") return null;
+  try {
+    return toMs(value);
+  } catch {
+    return null;
+  }
+}
+function parseNextDecision(value) {
+  if (value === void 0) return void 0;
+  const delay = nextDelay(value);
+  if (delay != null) return { delay, reason: null };
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const { in: wanted, reason, ...rest } = value;
+    const inDelay = nextDelay(wanted);
+    if (inDelay != null && Object.keys(rest).length === 0 && (reason == null || typeof reason === "string")) {
+      return { delay: inDelay, reason: reason || null };
+    }
+  }
+  throw new Error(
+    `next returned ${JSON.stringify(value) ?? String(value)}; expected undefined, a duration, "every", "min", "max" or { in, reason }`
+  );
+}
+
 // src/runtime/task.ts
-var sleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var NEXT_HOOK_TIMEOUT_MS = 5e3;
+var FAILURE_STREAK_LOOKBACK = 256;
+function streakOf(outcomes) {
+  const firstOther = outcomes.findIndex((tick) => tick.outcome !== "failure");
+  return firstOther === -1 ? outcomes.length : firstOther;
+}
 var failedRuns = /* @__PURE__ */ new WeakMap();
 function failedRunId(error) {
   return runFailure(error)?.runId ?? null;
@@ -1193,10 +1369,9 @@ var Task = class {
   kv;
   sqlite;
   meta;
+  schedulingServices;
   entry = null;
   entryExports = null;
-  /** Executions started and not yet settled. */
-  inFlight = 0;
   constructor({
     entryParams,
     buildConfigFn
@@ -1205,13 +1380,14 @@ var Task = class {
     this.entry = new Entry(entryParams, {
       onTaskCodeLoaded: this.taskCallbacks?.onTaskCodeLoaded
     });
-    const { taskCallbacks, startRun, history, env, kv, sqlite } = buildConfigFn({
+    const { taskCallbacks, startRun, history, env, kv, sqlite, scheduling } = buildConfigFn({
       sourcePath: this.entry.paths.source,
       compiledPath: this.entry.paths.compiled
     });
     this.taskCallbacks = taskCallbacks;
     this.startRun = startRun;
     this.history = history;
+    this.schedulingServices = scheduling;
     this.sqlite = sqlite;
     this.meta = {
       fileTaskId: -1,
@@ -1241,48 +1417,52 @@ var Task = class {
     invariant5(this.entry, "Entry not initialized.");
     return this.entry.codeHash;
   }
-  get timingPattern() {
+  /** The `timing` export, as the latest run (or `loadEntry`) read it. */
+  get timing() {
     invariant5(this.entryExports, "Entry exports not initialized.");
     return this.entryExports.timing;
   }
-  /**
-   * The task's `overlap` export, `"skip"` when it has none. Throws on anything
-   * else, naming the task, so a typo fails at schedule time.
-   */
-  get overlapPolicy() {
+  /** The `next` export, as loaded: unchecked, for whoever schedules the task to check. */
+  get nextHook() {
     invariant5(this.entryExports, "Entry exports not initialized.");
-    const { overlap = "skip" } = this.entryExports;
-    invariant5(
-      overlap === "skip" || overlap === "allow",
-      `Invalid overlap "${String(overlap)}" for ${this.taskPath}: expected "skip" or "allow"`
-    );
-    return overlap;
+    return this.entryExports.next;
   }
   /**
    * Check the exports that shape how the task is scheduled, so a bad value
-   * fails when the task is scheduled rather than on its first tick.
+   * fails when the task is scheduled rather than on its first tick. ngn runs
+   * one run of a task at a time, so `overlap` may only say so.
    */
   validateExports() {
     invariant5(this.entryExports, "Entry exports not initialized.");
-    void this.overlapPolicy;
-    const { budget, exclusive, retry } = this.entryExports;
+    const { budget, exclusive, retry, overlap = "skip" } = this.entryExports;
+    invariant5(
+      overlap !== "allow",
+      `overlap "allow" for ${this.taskPath}: ngn runs one run of a task at a time, across every process on the database, so a task cannot run beside itself`
+    );
+    invariant5(
+      overlap === "skip",
+      `Invalid overlap "${String(overlap)}" for ${this.taskPath}: expected "skip"`
+    );
     if (budget != null) toMs(budget, `budget for ${this.taskPath}`);
     exclusiveNames(exclusive, this.taskPath);
     resolveRetry(retry, this.taskPath);
   }
-  /** Whether an execution of this task is in progress. */
-  get isRunning() {
-    return this.inFlight > 0;
+  /** The `retry` export, checked. */
+  get retryPolicy() {
+    invariant5(this.entryExports, "Entry exports not initialized.");
+    return resolveRetry(this.entryExports.retry, this.taskPath);
+  }
+  /** The schedule and lease services this task's runs are recorded with. */
+  get scheduling() {
+    return this.schedulingServices;
   }
   /**
-   * Record a run that ngn decided not to start, without loading or calling any
-   * of the task's code. Needs the task to have been registered by an earlier
-   * execution, which is always so for a run skipped because one is in progress.
+   * Load the task file and register it and its version, without running it:
+   * its schedule is kept against the task's id. Returns that id.
    */
-  async skip(reason) {
-    invariant5(this.entry, "Entry not initialized.");
-    const run = await this.startRun();
-    await run.callbacks.onSkip?.({ path: this.entry.paths.relativeEntry, reason });
+  async register() {
+    await this.loadAndRegister();
+    return this.meta.fileTaskId;
   }
   hasTaskExport() {
     return this.entryExports?.task !== void 0;
@@ -1353,31 +1533,106 @@ var Task = class {
     }
   }
   /**
-   * Run the task for one tick, retrying as its `retry` export allows. A
-   * scheduled tick passes when it fired and when the next one is due, which
-   * `ctx.run.deadline` and the retry window are worked out from.
+   * Run the task for one tick, retrying as its `retry` export allows, and say
+   * how it ended. A scheduled tick passes when it fired and when the next one
+   * is due, which `ctx.run.deadline` and the retry window are worked out from.
+   * Never throws: a failure is an outcome, its error recorded on its run.
+   */
+  executeTick(schedule = {}) {
+    return this.executeWithRetries(schedule);
+  }
+  /**
+   * One tick, for a caller that wants the task's value: what it returned, or
+   * undefined for a skip. Throws what the tick failed with.
    */
   async execute(schedule = {}) {
-    this.inFlight++;
-    try {
-      return await this.executeWithRetries(schedule);
-    } finally {
-      this.inFlight--;
-    }
+    const outcome = await this.executeTick(schedule);
+    if (outcome.status === "failure") throw outcome.error;
+    return outcome.result;
   }
   async executeWithRetries(schedule) {
-    const tick2 = {
+    const tick = {
       firstRunId: null,
+      runId: null,
       retry: resolveRetry(void 0, this.taskPath),
-      failedContext: null
+      failedContext: null,
+      final: null
     };
+    const outcome = await this.attempts(schedule, tick);
+    if (schedule.next) outcome.next = await this.askNext(outcome, tick, schedule.next);
+    return outcome;
+  }
+  /**
+   * Ask the `next` hook when to run next. What it throws, returns that it may
+   * not, or a hook that takes too long, is recorded on the tick's final run in
+   * stage `next`, and leaves the decision to the policy, as does a tick that
+   * never got as far as loading the task's exports.
+   */
+  async askNext(outcome, tick, { previousDelayMs, timeoutMs = NEXT_HOOK_TIMEOUT_MS }) {
+    const final = tick.final;
+    const hook = final?.exports.next;
+    if (!final || typeof hook !== "function" || outcome.runId == null) return null;
+    const told = {
+      status: outcome.status,
+      result: outcome.result,
+      error: outcome.error,
+      skipReason: outcome.skipReason,
+      failedInARow: await this.failedInARow(),
+      previousDelayMs,
+      runId: outcome.runId
+    };
+    let timer;
+    try {
+      const value = await Promise.race([
+        (async () => hook(told, final.context))(),
+        new Promise((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`next took longer than ${timeoutMs / 1e3}s`)),
+            timeoutMs
+          );
+        })
+      ]);
+      return parseNextDecision(value) ?? null;
+    } catch (error) {
+      await final.run.callbacks.onHookError?.({ path: final.path, stage: "next", error });
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /** The tick's attempts, retrying as `retry` allows, and how the last one ended. */
+  async attempts(schedule, tick) {
+    const clock = schedule.clock ?? systemClock;
+    const outcome = (attempts, end) => ({
+      result: void 0,
+      error: void 0,
+      skipReason: null,
+      firstRunId: tick.firstRunId,
+      runId: tick.runId,
+      attempts,
+      endedAt: clock.now(),
+      next: null,
+      ...end
+    });
     for (let attempt = 1; ; attempt++) {
-      tick2.failedContext = null;
+      tick.failedContext = null;
+      if (schedule.signal?.aborted) {
+        return outcome(attempt - 1, { status: "failure", error: schedule.signal.reason });
+      }
       try {
-        return await this.executeOnce(schedule, tick2);
+        const end = await this.executeOnce(schedule, tick, clock);
+        return end.status === "success" ? outcome(attempt, { status: "success", result: end.result }) : outcome(attempt, { status: "skipped", skipReason: end.reason });
       } catch (error) {
-        if (!await this.shouldRetry(error, attempt, schedule, tick2)) throw error;
-        await sleep2(tick2.retry.delayMs);
+        let retry;
+        try {
+          retry = await this.shouldRetry(error, attempt, schedule, tick, clock);
+        } catch (thrown) {
+          return outcome(attempt, { status: "failure", error: thrown });
+        }
+        if (!retry || schedule.signal?.aborted)
+          return outcome(attempt, { status: "failure", error });
+        await clock.sleep(tick.retry.delayMs, schedule.signal);
+        if (schedule.signal?.aborted) return outcome(attempt, { status: "failure", error });
       }
     }
   }
@@ -1386,10 +1641,19 @@ var Task = class {
    * fails the same way every time. Then it has to fit before the next tick,
    * and the task's `shouldRetry` gets the last word.
    */
-  async shouldRetry(error, attempt, { nextAt = null }, tick2) {
-    if (!tick2.failedContext || !retryFits({ attempt, retry: tick2.retry, nextAt })) return false;
+  async shouldRetry(error, attempt, { nextAt = null }, tick, clock) {
+    if (!tick.failedContext) return false;
+    if (!retryFits({ attempt, retry: tick.retry, nextAt, now: clock.now() })) return false;
     const { shouldRetry } = this.entryExports ?? {};
-    return shouldRetry ? await shouldRetry(error, tick2.failedContext) !== false : true;
+    return shouldRetry ? await shouldRetry(error, tick.failedContext) !== false : true;
+  }
+  /**
+   * The task's latest ticks that failed in a row, from its run history, so a
+   * restart does not reset the count. Ticks closed as interrupted count, since
+   * their runs were closed as failed; skipped ticks neither break nor extend it.
+   */
+  async failedInARow() {
+    return streakOf(await this.history.recentTickOutcomes(FAILURE_STREAK_LOOKBACK));
   }
   /**
    * Whether the breaker holds this tick back: after `after` failed ticks in a
@@ -1399,11 +1663,7 @@ var Task = class {
   async breakerOpen(retry) {
     if (!retry.breaker) return false;
     const outcomes = await this.history.recentTickOutcomes(retry.breaker.after + 64);
-    const failedInARow = outcomes.findIndex((tick2) => tick2.outcome !== "failure");
-    const wanted = breakerSkips(
-      failedInARow === -1 ? outcomes.length : failedInARow,
-      retry.breaker
-    );
+    const wanted = breakerSkips(streakOf(outcomes), retry.breaker);
     if (wanted === 0) return false;
     return await this.history.countSkipsSince(BREAKER_SKIP_REASON, outcomes[0].id) < wanted;
   }
@@ -1443,14 +1703,17 @@ var Task = class {
    * Load the task file, open the attempt's `task_runs` row, then evaluate the
    * file's code; what that throws is recorded on the row as failed in `load`.
    */
-  async openRun(tick2) {
+  async openRun(tick, onRunStarted) {
     invariant5(this.entry, "Entry not initialized.");
+    tick.final = null;
     await this.loadAndRegister();
     const meta = { ...this.meta };
     const path = this.entry.paths.relativeEntry;
-    const run = await this.startRun({ retryOf: tick2.firstRunId });
-    const firstAttempt = tick2.firstRunId == null;
-    tick2.firstRunId ??= run.id;
+    const run = await this.startRun({ retryOf: tick.firstRunId });
+    const firstAttempt = tick.firstRunId == null;
+    tick.firstRunId ??= run.id;
+    tick.runId = run.id;
+    onRunStarted?.(run.id);
     try {
       return { run, meta, path, firstAttempt, ...await this.readExports(path) };
     } catch (error) {
@@ -1464,12 +1727,20 @@ var Task = class {
    * cannot be loaded at all, or a run row that cannot be written, fails before
    * there is a row to record it on.
    */
-  async executeOnce({ scheduledAt = null, nextAt = null }, tick2) {
-    const { run, meta, path, firstAttempt, exports, task, budgetMs, exclusiveLocks, retry } = await this.openRun(tick2);
-    tick2.retry = retry;
-    const deadline = runDeadline({ startedAt: Date.now(), scheduledAt, nextAt, budgetMs });
-    const { signal, dispose } = deadlineSignal(deadline);
+  async executeOnce({
+    scheduledAt = null,
+    nextAt = null,
+    periodMs = null,
+    signal: outer,
+    onRunStarted
+  }, tick, clock) {
+    const { run, meta, path, firstAttempt, exports, task, budgetMs, exclusiveLocks, retry } = await this.openRun(tick, onRunStarted);
+    tick.retry = retry;
+    const startedAt = clock.now();
+    const deadline = runDeadline({ startedAt, scheduledAt, nextAt, budgetMs, periodMs });
+    const { signal, dispose } = deadlineSignal(deadline, outer);
     const taskContext = this.buildContext(run, meta, { scheduledAt, nextAt, deadline }, signal);
+    tick.final = { run, path, context: taskContext, exports };
     let stage = "start";
     let exclusiveHeld = null;
     try {
@@ -1481,25 +1752,25 @@ var Task = class {
       });
       if ("reason" in gate) {
         await run.callbacks.onSkip?.({ path, reason: gate.reason });
-        return;
+        return { status: "skipped", reason: gate.reason };
       }
       exclusiveHeld = gate.held;
       stage = "shouldSkip";
       if (await exports.shouldSkip?.(taskContext)) {
         await run.callbacks.onSkip?.({ path });
-        return;
+        return { status: "skipped", reason: null };
       }
       stage = "start";
       await run.callbacks.onStart?.({ path });
       stage = "task";
-      tick2.failedContext = taskContext;
+      tick.failedContext = taskContext;
       const value = await task(taskContext);
-      tick2.failedContext = null;
+      tick.failedContext = null;
       stage = "record";
       await run.callbacks.onSuccess?.({ path, result: value });
       await this.runHook(run, "onSuccess", () => exports.onSuccess?.(taskContext));
       await this.runHook(run, "onComplete", () => exports.onComplete?.(taskContext));
-      return value;
+      return { status: "success", result: value };
     } catch (error) {
       await this.failRun(run, stage, error);
       if (stage === "task" || stage === "record") {
@@ -1572,61 +1843,1172 @@ var TaskLibrary = class {
 };
 
 // src/runtime/taskLibraryScheduler.ts
-import invariant8 from "tiny-invariant";
+import invariant7 from "tiny-invariant";
 import { logTaskLibraryScheduler, logTaskLibrarySchedulerError } from "@apisurf/ngn-os";
 
-// src/runtime/schedule.ts
-import { Cron } from "croner";
-import invariant7 from "tiny-invariant";
-var CRON_OPTIONS = { mode: "5-or-6-parts" };
-function isCronPatternValid(pattern) {
-  try {
-    new Cron(pattern, { ...CRON_OPTIONS, paused: true }).stop();
-    return true;
-  } catch {
-    return false;
+// src/runtime/taskSchedule.ts
+import { canTransition as canTransition2, errorSummary } from "@apisurf/ngn-schema/describe";
+
+// src/db/services/schedule.ts
+import {
+  canTransition,
+  failureLine,
+  SCHEDULE_TRANSITIONS
+} from "@apisurf/ngn-schema/describe";
+var FIELDS = ["next_at", "reason", "source", "holder", "anchor", "request"];
+var ScheduleStore = class {
+  constructor(db2) {
+    this.db = db2;
   }
+  async read(taskId) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT * FROM schedules WHERE file_task_id = ?",
+      args: [taskId]
+    });
+    return rows[0] ?? null;
+  }
+  /**
+   * Apply `change` to the task's schedule, as it stands now. The new row, or
+   * why it was refused.
+   */
+  async transition(taskId, change) {
+    const current = await this.read(taskId);
+    const refused = refusal(current, change);
+    if (refused) return { refused };
+    const from = current?.state ?? null;
+    const to = SCHEDULE_TRANSITIONS[change.event].to;
+    const statements = [
+      current ? this.update(taskId, from, to, change) : this.insert(taskId, to, change),
+      this.event(taskId, from, change, current?.next_at ?? null)
+    ];
+    if (change.finalRunId != null)
+      statements.push(this.finalRun(change.finalRunId, change, current));
+    const next = change.followedBy;
+    if (next) {
+      statements.push(
+        this.update(taskId, to, SCHEDULE_TRANSITIONS[next.event].to, next, change.at),
+        this.event(taskId, to, next, change.set?.next_at ?? current?.next_at ?? null)
+      );
+    }
+    const results = await this.db.batch(statements, "write");
+    if (!results[0] || results[0].rowsAffected === 0) {
+      return { refused: `${change.event}: the schedule changed before it could be written` };
+    }
+    return await this.read(taskId);
+  }
+  insert(taskId, to, change) {
+    const set = change.set ?? {};
+    return {
+      sql: `INSERT INTO schedules (file_task_id, state, ${FIELDS.join(", ")}, updated_at)
+            VALUES (:taskId, :to, ${FIELDS.map((f) => `:${f}`).join(", ")}, :at)
+            ON CONFLICT(file_task_id) DO NOTHING`,
+      args: {
+        taskId,
+        to,
+        at: change.at,
+        ...Object.fromEntries(FIELDS.map((f) => [f, set[f] ?? null]))
+      }
+    };
+  }
+  /**
+   * The row update, conditional on the state it comes from (and the holder or
+   * request the change names). `after`: the time of the transition this one
+   * follows in the same write, which it applies only on top of.
+   */
+  update(taskId, from, to, change, after) {
+    const set = change.set ?? {};
+    const fields = FIELDS.filter((f) => f in set);
+    const guards = [
+      change.holder !== void 0 ? "AND holder IS :heldBy" : "",
+      change.requestIs !== void 0 ? "AND request IS :requestIs" : "",
+      after !== void 0 ? "AND updated_at = :after" : ""
+    ];
+    return {
+      sql: `UPDATE schedules SET state = :to, updated_at = :at
+              ${fields.map((f) => `, ${f} = :${f}`).join("")}
+            WHERE file_task_id = :taskId AND state = :from ${guards.join(" ")}`,
+      args: {
+        taskId,
+        from,
+        to,
+        at: change.at,
+        ...change.holder !== void 0 ? { heldBy: change.holder } : {},
+        ...change.requestIs !== void 0 ? { requestIs: change.requestIs } : {},
+        ...after !== void 0 ? { after } : {},
+        ...Object.fromEntries(fields.map((f) => [`${f}`, set[f] ?? null]))
+      }
+    };
+  }
+  /** The next run and its reason, on the tick's final run, written only if the event was. */
+  finalRun(runId, change, current) {
+    return {
+      sql: `UPDATE task_runs SET next_at = :nextAt, next_reason = :reason
+            WHERE id = :id AND changes() = 1`,
+      args: {
+        id: runId,
+        nextAt: change.set?.next_at ?? current?.next_at ?? null,
+        reason: change.set?.reason ?? current?.reason ?? null
+      }
+    };
+  }
+  /** The event, copied from the row the update left, written only if it applied. */
+  event(taskId, from, change, previousNextAt) {
+    return {
+      sql: `INSERT INTO schedule_events (file_task_id, at, event, from_state, to_state,
+              ${FIELDS.join(", ")}, origin, first_run_id, run_id, previous_next_at)
+            SELECT s.file_task_id, :at, :event, :from, s.state, ${FIELDS.map((f) => `s.${f}`).join(", ")},
+              :origin, :firstRunId, :runId, :previousNextAt
+            FROM schedules s WHERE s.file_task_id = :taskId AND changes() = 1`,
+      args: {
+        taskId,
+        at: change.at,
+        event: change.event,
+        from,
+        origin: change.origin ?? null,
+        firstRunId: change.firstRunId ?? null,
+        runId: change.runId ?? null,
+        previousNextAt
+      }
+    };
+  }
+  /**
+   * Close the task's runs that never recorded an end, as failed in
+   * `interrupted` with `why` as the error, in one write. `fromRunId` limits it
+   * to one tick's runs. Returns the ids closed, oldest first.
+   */
+  async closeOpenRuns(taskId, why, { fromRunId = 0, at }) {
+    const open = `file_task_id = :taskId AND id >= :fromRunId AND ended_at IS NULL
+                  AND status IN ('pending', 'running')`;
+    const args = { taskId, fromRunId };
+    const log = (value) => ({
+      sql: `INSERT INTO logs (status, value, file_task_id, task_run_id)
+            SELECT 'error', :value, file_task_id, id FROM task_runs WHERE ${open} ORDER BY id`,
+      args: { ...args, value }
+    });
+    const [, , closed] = await this.db.batch(
+      [
+        log(failureLine("interrupted", new Error(why))),
+        log("Task failed"),
+        {
+          sql: `UPDATE task_runs SET status = 'failure', ended_at = :at WHERE ${open} RETURNING id`,
+          args: { ...args, at }
+        }
+      ],
+      "write"
+    );
+    return closed.rows.map((row) => Number(row.id)).toSorted((a, b) => a - b);
+  }
+};
+function refusal(current, change) {
+  const from = current?.state ?? null;
+  if (!canTransition(from, change.event)) {
+    return `${change.event} is not allowed from ${from ?? "no schedule"}`;
+  }
+  if (change.holder !== void 0 && current?.holder !== change.holder) {
+    return `${change.event}: the task is no longer held by this tick`;
+  }
+  if (change.requestIs !== void 0 && current?.request !== change.requestIs) {
+    return `${change.event}: a request was made since the schedule was read`;
+  }
+  const next = change.followedBy;
+  const to = SCHEDULE_TRANSITIONS[change.event].to;
+  if (next && !canTransition(to, next.event)) return `${next.event} is not allowed from ${to}`;
+  return null;
 }
-async function tick(task, onError, schedule = {}) {
-  try {
-    if (task.isRunning && task.overlapPolicy === "skip") {
-      await task.skip("previous run still in progress");
-      return;
+function isRefusal(value) {
+  return "refused" in value;
+}
+
+// src/runtime/lease.ts
+var TASK_LEASE_TTL_MS = 6e4;
+function taskLeaseName(taskPath) {
+  return `${RESERVED_LOCK_PREFIX}task:${taskPath}`;
+}
+var TaskLease = class _TaskLease {
+  constructor(locks, name, holder, ttlMs, onLost) {
+    this.locks = locks;
+    this.name = name;
+    this.holder = holder;
+    this.ttlMs = ttlMs;
+    this.onLost = onLost;
+    this.renewal = setInterval(() => void this.renew(), Math.max(10, ttlMs / 3));
+    this.renewal.unref();
+  }
+  controller = new AbortController();
+  renewal = null;
+  lastRenewed = Date.now();
+  released = false;
+  /** Take the task's lease, or say who has it. */
+  static async take(locks, taskPath, {
+    ttlMs = TASK_LEASE_TTL_MS,
+    onLost = () => {
+    }
+  } = {}) {
+    const name = taskLeaseName(taskPath);
+    const holder = await locks.tryAcquire(name, ttlMs, null);
+    if (holder) return new _TaskLease(locks, name, holder, ttlMs, onLost);
+    const held = await locks.holderOf(name);
+    return { busy: { holder: held?.holder ?? "", runId: held?.taskRunId ?? null } };
+  }
+  /** Aborts when the lease is lost. */
+  get signal() {
+    return this.controller.signal;
+  }
+  get lost() {
+    return this.controller.signal.aborted;
+  }
+  /** Record the run the lease is working for, so a refusal can name it. */
+  async setRun(runId) {
+    if (this.released || this.lost) return;
+    await this.locks.setRun(this.name, this.holder, runId).catch(() => {
+    });
+  }
+  async renew() {
+    if (this.released || this.lost) return;
+    if (Date.now() - this.lastRenewed > this.ttlMs) return this.lose();
+    try {
+      if (await this.locks.renew(this.name, this.holder, this.ttlMs)) {
+        this.lastRenewed = Date.now();
+      } else {
+        this.lose();
+      }
+    } catch {
+    }
+  }
+  lose() {
+    if (this.lost) return;
+    this.stopRenewing();
+    this.controller.abort(new Error("the run lost its lease"));
+    this.onLost(this);
+  }
+  stopRenewing() {
+    if (this.renewal) clearInterval(this.renewal);
+    this.renewal = null;
+  }
+  async release() {
+    if (this.released) return;
+    this.released = true;
+    this.stopRenewing();
+    await this.locks.release(this.name, this.holder).catch(() => {
+    });
+  }
+  /** Stop renewing without giving the lease back, as a process that died would. */
+  abandon() {
+    this.released = true;
+    this.stopRenewing();
+  }
+};
+
+// src/runtime/scheduleControl.ts
+import {
+  encodeScheduleRequest,
+  formatClock,
+  formatDelay,
+  parseScheduleRequest
+} from "@apisurf/ngn-schema/describe";
+var MIN_DELAY_MS = 1e3;
+async function controlSchedule(target, command) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const row = await target.store.read(target.taskId);
+    if (!row) {
+      return {
+        applied: false,
+        error: true,
+        message: `${target.name} has not been scheduled yet: ngn run schedules it`
+      };
+    }
+    const plan = planCommand(row, command, target);
+    if (!("change" in plan)) return plan;
+    const result = await target.store.transition(target.taskId, plan.change);
+    if (!isRefusal(result)) {
+      return { applied: true, event: plan.change.event, row: result, message: plan.message };
     }
-    await task.execute(schedule);
+  }
+  return {
+    applied: false,
+    error: true,
+    message: `the schedule of ${target.name} kept changing; try again`
+  };
+}
+function planCommand(row, command, target) {
+  if (command.kind === "pause") return planPause(row, target);
+  if (command.kind === "resume") return planResume(row, target);
+  return planNext(row, command.delayMs, target);
+}
+function withRequest(row, more) {
+  return encodeScheduleRequest({ ...parseScheduleRequest(row.request), ...more });
+}
+function planPause(row, { name, now }) {
+  if (row.state === "paused") {
+    return { applied: false, error: false, message: `${name} is already paused` };
+  }
+  if (row.state === "running") {
+    return {
+      change: {
+        event: "pause_requested",
+        at: now,
+        set: { request: withRequest(row, { pause: true }) },
+        requestIs: row.request
+      },
+      message: `${name} has a run in progress; it pauses when the run ends`
+    };
+  }
+  return {
+    change: { event: "paused", at: now, set: { holder: null } },
+    message: `paused ${name}: no runs until ngn resume ${name}`
+  };
+}
+function planResume(row, { name, now, pattern }) {
+  if (row.state !== "paused") {
+    return { applied: false, error: false, message: `${name} isn't paused (${row.state})` };
+  }
+  const missed = row.next_at == null || row.next_at < now;
+  let set = { reason: "resumed", source: "cli" };
+  if (missed) {
+    const nextAt2 = pattern ? nextCronSlot(pattern, now) ?? now : now;
+    set = {
+      next_at: nextAt2,
+      anchor: nextAt2,
+      source: "cli",
+      reason: pattern ? "resumed; missed slots are not run, next on its pattern" : "resumed; it was due while paused, so it runs now"
+    };
+  }
+  const nextAt = set.next_at ?? row.next_at;
+  return {
+    change: { event: "resumed", at: now, set },
+    message: `resumed ${name}: next run ${nextAt <= now ? "now" : formatClock(nextAt)}`
+  };
+}
+function planNext(row, delayMs, { name, now }) {
+  if (row.state === "paused") {
+    return {
+      applied: false,
+      error: true,
+      message: `${name} is paused; run ngn resume ${name} first`
+    };
+  }
+  const delay = delayMs === 0 ? 0 : Math.max(MIN_DELAY_MS, delayMs);
+  const nextAt = now + delay;
+  if (row.state === "running") {
+    return {
+      change: {
+        event: "override_requested",
+        at: now,
+        set: { request: withRequest(row, { nextAt }) },
+        requestIs: row.request
+      },
+      message: `${name} has a run in progress; when it ends, its next run is ${delay === 0 ? "now" : formatClock(nextAt)}`
+    };
+  }
+  return {
+    change: {
+      event: "rescheduled",
+      at: now,
+      set: {
+        next_at: nextAt,
+        reason: `moved with ngn next: ${delay === 0 ? "now" : `in ${formatDelay(delay)}`}`,
+        source: "cli",
+        anchor: nextAt,
+        holder: null
+      }
+    },
+    message: `${name} runs next ${delay === 0 ? "now" : `at ${formatClock(nextAt)}`}`
+  };
+}
+function honourRequest(change, row) {
+  const { pause, nextAt } = parseScheduleRequest(row?.request);
+  const set = { ...change.set, request: null };
+  if (nextAt != null) {
+    Object.assign(set, {
+      next_at: nextAt,
+      reason: `moved with ngn next to ${formatClock(nextAt)}`,
+      source: "cli",
+      anchor: nextAt
+    });
+  }
+  return {
+    ...change,
+    set,
+    requestIs: row?.request ?? null,
+    ...pause ? { followedBy: { event: "paused", at: change.at } } : {}
+  };
+}
+
+// src/runtime/timingRule.ts
+import {
+  describeTiming,
+  formatClock as formatClock2,
+  formatDelay as formatDelay2,
+  formatMs
+} from "@apisurf/ngn-schema/describe";
+function gridSlotAfter(anchor, everyMs) {
+  return (t) => anchor + (Math.floor((t - anchor) / everyMs) + 1) * everyMs;
+}
+function firstFittingSlot(slotAfter, plannedAt, endedAt) {
+  const due = slotAfter(plannedAt);
+  if (endedAt <= due) return { nextAt: due, due, missed: 0 };
+  const nextAt = slotAfter(endedAt - 1);
+  let missed = 0;
+  for (let slot = due; slot < nextAt && missed < 1e3; slot = slotAfter(slot)) missed++;
+  return { nextAt, due, missed };
+}
+function timingRule(timing, exported, random = Math.random) {
+  const words = describeTiming(exported) ?? String(exported);
+  if (timing.kind === "cron") return cronRule(timing.pattern, words);
+  return timing.edge === "trailing" ? trailingRule(timing, words, random) : leadingRule(timing, words, random);
+}
+function failures(n) {
+  return n === 1 ? "a failure" : `${n} failures in a row`;
+}
+function backoffDelay(timing, failedInARow, random) {
+  const { factor, jitter } = timing.backoff;
+  const base = Math.min(timing.maxMs, timing.everyMs * factor ** failedInARow);
+  const jittered = Math.round(base * (1 + (random() * 2 - 1) * jitter));
+  return Math.min(timing.maxMs, Math.max(timing.minMs, jittered));
+}
+function backoffDecision(timing, { status, endedAt, failedInARow }, random) {
+  if (status !== "failure" || !timing.backoff) return null;
+  const n = Math.max(1, failedInARow);
+  const delay = backoffDelay(timing, n, random);
+  const nextAt = endedAt + delay;
+  return {
+    nextAt,
+    reason: `backing off after ${failures(n)}: ${formatDelay2(delay)}`,
+    anchor: timing.edge === "leading" ? nextAt : null,
+    source: "policy"
+  };
+}
+function hookDecision(timing, { choice, endedAt }, onSchedule) {
+  if (!choice) return null;
+  if (choice.delay === "every") {
+    const scheduled = onSchedule();
+    return {
+      ...scheduled,
+      reason: choice.reason ?? `next hook: ${scheduled.reason}`,
+      source: "hook"
+    };
+  }
+  const named = typeof choice.delay === "string" ? choice.delay : null;
+  const wanted = named === "min" ? timing.minMs : named === "max" ? timing.maxMs : choice.delay;
+  const delay = Math.min(timing.maxMs, Math.max(timing.minMs, wanted));
+  const clamped = delay === wanted ? "" : ` (${formatDelay2(wanted)} kept to ${delay === timing.minMs ? "min" : "max"} ${formatDelay2(delay)})`;
+  const nextAt = endedAt + delay;
+  return {
+    nextAt,
+    reason: `${choice.reason ?? `next hook: ${named ? `${named}, ` : ""}${formatDelay2(delay)}`}${clamped}`,
+    anchor: timing.edge === "leading" ? nextAt : null,
+    source: "hook"
+  };
+}
+function intervalLatest(timing, now, slot, input) {
+  if (input.source === "cli") return null;
+  if (input.source != null && input.source !== "policy") return now + timing.maxMs;
+  if (!timing.backoff || input.failedInARow === 0) return slot;
+  const { factor, jitter } = timing.backoff;
+  const longest = timing.everyMs * factor ** input.failedInARow * (1 + jitter);
+  return Math.max(slot, now + Math.min(timing.maxMs, Math.ceil(longest)));
+}
+function trailingRule(timing, words, random) {
+  const { everyMs } = timing;
+  return {
+    words,
+    first: (now) => ({ nextAt: now, anchor: null }),
+    window: (plannedAt) => ({ scheduledAt: plannedAt, nextAt: null, periodMs: everyMs }),
+    decide(input) {
+      const onSchedule = () => ({
+        nextAt: input.endedAt + everyMs,
+        reason: words,
+        anchor: null,
+        source: "policy"
+      });
+      return hookDecision(timing, input, onSchedule) ?? backoffDecision(timing, input, random) ?? onSchedule();
+    },
+    overdue: (now) => ({ nextAt: now, catchUp: true }),
+    latest: (now, input) => intervalLatest(timing, now, now + everyMs, input)
+  };
+}
+function leadingRule(timing, words, random) {
+  const { everyMs } = timing;
+  const slots = (anchor, fallback) => gridSlotAfter(anchor ?? fallback, everyMs);
+  return {
+    words,
+    first: (now) => ({ nextAt: now, anchor: now }),
+    window: (plannedAt, anchor) => ({
+      scheduledAt: plannedAt,
+      nextAt: slots(anchor, plannedAt)(plannedAt),
+      periodMs: null
+    }),
+    decide(input) {
+      const onSchedule = () => {
+        const { plannedAt, endedAt, anchor } = input;
+        const grid = anchor ?? plannedAt;
+        const slot = firstFittingSlot(gridSlotAfter(grid, everyMs), plannedAt, endedAt);
+        const reason = slot.missed ? `ran ${formatMs(endedAt - slot.due)} past its slot; next slot ${formatClock2(slot.nextAt)}` : words;
+        return { nextAt: slot.nextAt, reason, anchor: grid, source: "policy" };
+      };
+      return hookDecision(timing, input, onSchedule) ?? backoffDecision(timing, input, random) ?? onSchedule();
+    },
+    overdue: (now) => ({ nextAt: now, catchUp: true }),
+    latest: (now, input) => intervalLatest(timing, now, slots(input.anchor, now)(now), input)
+  };
+}
+function cronRule(pattern, words) {
+  const slotAfter = (t) => nextCronSlot(pattern, t) ?? Number.MAX_SAFE_INTEGER;
+  return {
+    words,
+    first: (now) => ({ nextAt: slotAfter(now), anchor: null }),
+    window: (plannedAt) => ({
+      scheduledAt: plannedAt,
+      nextAt: slotAfter(plannedAt),
+      periodMs: null
+    }),
+    decide({ plannedAt, endedAt }) {
+      const slot = firstFittingSlot(slotAfter, plannedAt, endedAt);
+      const reason = slot.missed ? `ran past ${slot.missed} ${slot.missed === 1 ? "slot" : "slots"}; next ${formatClock2(slot.nextAt)}` : words;
+      return { nextAt: slot.nextAt, reason, anchor: null, source: "policy" };
+    },
+    overdue: (now) => ({ nextAt: slotAfter(now), catchUp: false }),
+    latest: (now, { source }) => source === "cli" ? null : slotAfter(now)
+  };
+}
+
+// src/runtime/taskSchedule.ts
+var STOP_GRACE_MS = 1e4;
+var CATCH_UP_REASON = "one catch-up run for what was missed while ngn was not running";
+var TickHandle = class {
+  constructor(origin, lease) {
+    this.origin = origin;
+    this.lease = lease;
+    this.whenClosed = new Promise((resolve2) => this.markClosed = () => resolve2(null));
+  }
+  controller = new AbortController();
+  firstRunId = null;
+  runId = null;
+  /** Whether it wrote `started`, so its end has a transition to make. */
+  logged = false;
+  /** Closed by shutdown (or a crash): whatever it decides later is not written. */
+  closed = false;
+  done = Promise.resolve();
+  /** Resolves when the tick is closed, so nothing waits on a run that may never end. */
+  whenClosed;
+  markClosed;
+  close() {
+    this.closed = true;
+    this.markClosed();
+  }
+  get signal() {
+    return AbortSignal.any([this.controller.signal, this.lease.signal]);
+  }
+  noteRun = (runId) => {
+    this.firstRunId ??= runId;
+    this.runId = runId;
+    void this.lease.setRun(runId);
+  };
+};
+function untilAborted(signal) {
+  return new Promise((resolve2) => {
+    if (signal.aborted) resolve2();
+    else signal.addEventListener("abort", () => resolve2(), { once: true });
+  });
+}
+function busyReason(taskPath, busy) {
+  return busy.runId != null ? `run ${busy.runId} of ${taskPath} is in progress` : `a run of ${taskPath} is in progress`;
+}
+async function writeTransition(task, taskId, change, onProblem) {
+  try {
+    const result = await task.scheduling.store.transition(taskId, change);
+    if (!isRefusal(result)) return result;
+    onProblem(`schedule of ${task.taskPath}: refused ${result.refused}`);
   } catch (error) {
-    onError(error);
-  }
-}
-function scheduleTask(task, pattern, onError) {
-  invariant7(isCronPatternValid(pattern), `Invalid cron pattern: ${pattern} for ${task.taskPath}`);
-  task.validateExports();
-  return new Cron(
-    pattern,
-    CRON_OPTIONS,
-    (job) => tick(task, onError, {
-      scheduledAt: job.currentRun()?.getTime() ?? Date.now(),
-      nextAt: job.nextRun()?.getTime() ?? null
-    })
-  );
+    onProblem(
+      `schedule of ${task.taskPath}: could not write ${change.event}: ${errorSummary(error)}`
+    );
+  }
+  return null;
+}
+async function writeTickEnd(task, taskId, change, onProblem) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const row = await task.scheduling.store.read(taskId);
+    const honoured = honourRequest(change, row);
+    let result;
+    try {
+      result = await task.scheduling.store.transition(taskId, honoured);
+    } catch (error) {
+      onProblem(
+        `schedule of ${task.taskPath}: could not write ${change.event}: ${errorSummary(error)}`
+      );
+      return null;
+    }
+    if (!isRefusal(result)) return result;
+    const now = await task.scheduling.store.read(taskId);
+    if (now?.request === honoured.requestIs) {
+      onProblem(`schedule of ${task.taskPath}: refused ${result.refused}`);
+      return null;
+    }
+  }
+  onProblem(`schedule of ${task.taskPath}: requests kept arriving; ${change.event} not written`);
+  return null;
+}
+async function startManual(deps, onLost = () => {
+}) {
+  const { task, taskId, clock, onProblem } = deps;
+  const lease = await TaskLease.take(task.scheduling.locks, task.taskPath, {
+    ttlMs: deps.leaseTtlMs,
+    onLost
+  });
+  if ("busy" in lease) return { busy: busyReason(task.taskPath, lease.busy) };
+  const tick = new TickHandle("manual", lease);
+  const outcome = (async () => {
+    try {
+      const row = await task.scheduling.store.read(taskId);
+      if (row && canTransition2(row.state, "started")) {
+        const request = row.state === "paused" ? { request: withRequest(row, { pause: true }) } : {};
+        const started = await writeTransition(
+          task,
+          taskId,
+          {
+            event: "started",
+            at: clock.now(),
+            origin: "manual",
+            set: { holder: lease.holder, ...request }
+          },
+          onProblem
+        );
+        tick.logged = started != null;
+      }
+      const result = await task.executeTick({
+        scheduledAt: null,
+        nextAt: deps.window?.nextAt ?? null,
+        periodMs: deps.window?.periodMs ?? null,
+        clock,
+        signal: tick.signal,
+        onRunStarted: tick.noteRun
+      });
+      if (tick.logged && !tick.closed && !lease.lost) {
+        await writeTickEnd(
+          task,
+          taskId,
+          {
+            event: "ended",
+            at: clock.now(),
+            holder: lease.holder,
+            set: { holder: null },
+            firstRunId: result.firstRunId,
+            runId: result.runId
+          },
+          onProblem
+        );
+      }
+      return result;
+    } finally {
+      await lease.release();
+    }
+  })();
+  tick.done = outcome.catch(() => {
+  });
+  return { tick, outcome };
+}
+async function runOnce(task, { clock, leaseTtlMs, onProblem }) {
+  const taskId = await task.register();
+  const started = await startManual({ task, taskId, clock, leaseTtlMs, onProblem });
+  return "busy" in started ? started : started.outcome;
 }
+var TaskSchedule = class {
+  constructor(options) {
+    this.options = options;
+    this.exported = options.timing;
+    this.resolved = resolveTiming(options.timing, options.task.taskPath);
+  }
+  taskId = -1;
+  row = null;
+  resolved;
+  exported;
+  stopping = false;
+  halt = new AbortController();
+  ticks = /* @__PURE__ */ new Set();
+  loopDone = Promise.resolve();
+  get task() {
+    return this.options.task;
+  }
+  get path() {
+    return this.options.task.taskPath;
+  }
+  get store() {
+    return this.options.task.scheduling.store;
+  }
+  get clock() {
+    return this.options.clock;
+  }
+  get ttlMs() {
+    return this.options.leaseTtlMs ?? TASK_LEASE_TTL_MS;
+  }
+  rule() {
+    return timingRule(this.resolved, this.exported, this.options.random);
+  }
+  /**
+   * The failure streak `outcome` ends, this tick included. A tick that failed
+   * before it had a run is not in the history, so it is added here.
+   */
+  async failedInARow(outcome) {
+    const streak = await this.task.failedInARow();
+    return outcome?.status === "failure" && outcome.runId == null ? streak + 1 : streak;
+  }
+  nextAt() {
+    return this.row?.next_at ?? null;
+  }
+  /** Register the task, bring its stored schedule up to date, and start the loop. */
+  async start() {
+    this.taskId = await this.task.register();
+    await this.reconcile();
+    this.loopDone = this.loop();
+  }
+  /** Transitions written by this process, so the loop can tell a step that moved things on. */
+  writes = 0;
+  write(change, write = writeTransition) {
+    return write(this.task, this.taskId, change, this.options.onProblem).then((row) => {
+      if (row) {
+        this.row = row;
+        this.writes++;
+      }
+      return row;
+    });
+  }
+  /** Write the transition that ends a tick, honouring a pause or next run asked for during it. */
+  writeEnd(change) {
+    return this.write(change, writeTickEnd);
+  }
+  /**
+   * What a start finds in the database: no schedule yet, a next run still to
+   * come, one missed while ngn was not running, one further off than the
+   * current timing could choose, or a tick a dead process left `running`.
+   */
+  async reconcile() {
+    const now = this.clock.now();
+    const rule = this.rule();
+    const row = await this.store.read(this.taskId);
+    this.row = row;
+    if (!row) {
+      const first = rule.first(now);
+      await this.write({
+        event: "scheduled",
+        at: now,
+        set: { next_at: first.nextAt, anchor: first.anchor, reason: "first run", source: "policy" }
+      });
+      return;
+    }
+    if (row.state === "running") {
+      await this.recoverIfAbandoned();
+      return;
+    }
+    if (row.state !== "waiting" || row.next_at == null) return;
+    if (row.next_at < now - WAIT_STEP_MS) {
+      const overdue = rule.overdue(now, row.anchor);
+      await this.write({
+        event: "overdue",
+        at: now,
+        set: {
+          next_at: overdue.nextAt,
+          reason: overdue.catchUp ? CATCH_UP_REASON : `missed while ngn was not running; ${rule.words}`,
+          source: "policy"
+        }
+      });
+      return;
+    }
+    const latest = rule.latest(now, {
+      anchor: row.anchor,
+      source: row.source,
+      failedInARow: await this.failedInARow()
+    });
+    if (latest != null && row.next_at > latest) {
+      await this.write({
+        event: "reclamped",
+        at: now,
+        set: { next_at: latest, reason: `further off than ${rule.words} allows`, source: "policy" }
+      });
+    }
+  }
+  async loop() {
+    while (!this.stopping) {
+      const before = this.writes;
+      try {
+        if (!await this.step()) await this.pause(WAIT_STEP_MS);
+      } catch (error) {
+        this.options.onProblem(`schedule of ${this.path}: ${errorSummary(error)}`);
+        await this.pause(WAIT_STEP_MS);
+      }
+      if (this.writes === before) await new Promise((resolve2) => setImmediate(resolve2));
+    }
+  }
+  /** Wait up to one step, or less; returns early when stopping. */
+  pause(ms) {
+    return this.clock.sleep(Math.max(0, Math.min(ms, WAIT_STEP_MS)), this.halt.signal);
+  }
+  /**
+   * One look at the schedule: wait while the next run is still to come (the
+   * row is read again every step, so another process's changes are seen), and
+   * run it once it is due. False when it did neither, so the loop waits a step.
+   */
+  async step() {
+    const row = await this.store.read(this.taskId);
+    if (!row) {
+      await this.reconcile();
+      return this.row != null;
+    }
+    this.row = row;
+    if (row.state === "paused") return false;
+    if (row.state === "running") {
+      const own = [...this.ticks][0];
+      if (own) {
+        await Promise.race([own.done, untilAborted(this.halt.signal)]);
+        return true;
+      }
+      return this.recoverIfAbandoned();
+    }
+    const now = this.clock.now();
+    if (row.next_at == null) return false;
+    if (row.next_at > now) {
+      await this.pause(row.next_at - now);
+      return true;
+    }
+    return this.runDue();
+  }
+  takeLease() {
+    return TaskLease.take(this.task.scheduling.locks, this.path, {
+      ttlMs: this.ttlMs,
+      onLost: (lease) => this.leaseLost(lease)
+    });
+  }
+  /**
+   * The lease for a due run, waiting while another run holds it. The first
+   * time it is busy with the run still waiting, the wait is logged as
+   * `blocked`. Null when stopping, or when the row stops asking for a run now:
+   * another process is running the task, which the loop then follows, or a
+   * person paused it or moved its next run.
+   */
+  async acquire() {
+    while (!this.stopping) {
+      const taken = await this.takeLease();
+      if (!("busy" in taken)) return taken;
+      const row = await this.store.read(this.taskId);
+      if (row?.state !== "waiting" && row?.state !== "blocked") return null;
+      if (row.state === "waiting") {
+        if (row.next_at == null || row.next_at > this.clock.now()) return null;
+        await this.write({
+          event: "blocked",
+          at: this.clock.now(),
+          set: { holder: taken.busy.holder },
+          runId: taken.busy.runId
+        });
+      }
+      await this.pause(WAIT_STEP_MS);
+    }
+    return null;
+  }
+  /**
+   * Run the due run, once this process holds the task. The row is read again
+   * under the lease: another process may have run it in the meantime, which is
+   * what stops two of them starting the same run.
+   */
+  async runDue() {
+    const lease = await this.acquire();
+    if (!lease) return false;
+    let handedOver = false;
+    try {
+      const row = await this.store.read(this.taskId);
+      const now = this.clock.now();
+      if (!row || row.state !== "waiting" && row.state !== "blocked") return false;
+      if (row.next_at == null || row.next_at > now) {
+        if (row.state === "blocked") {
+          await this.write({ event: "superseded", at: now, set: { holder: null } });
+        }
+        return true;
+      }
+      handedOver = true;
+      return await this.runTick(lease, row);
+    } finally {
+      if (!handedOver) await lease.release();
+    }
+  }
+  track(tick) {
+    this.ticks.add(tick);
+    void tick.done.finally(() => this.ticks.delete(tick));
+  }
+  /**
+   * A scheduled tick, from `started` to `decided`, holding `lease` throughout.
+   * False when it could not start.
+   */
+  async runTick(lease, row) {
+    const now = this.clock.now();
+    const rule = this.rule();
+    const catchUp = this.resolved.kind === "interval" && row.reason === CATCH_UP_REASON;
+    const tick = new TickHandle(catchUp ? "catch-up" : "scheduled", lease);
+    let plannedAt = catchUp ? now : row.next_at;
+    const late = rule.window(plannedAt, row.anchor).nextAt;
+    if (late != null && late <= now) plannedAt = now;
+    let settle;
+    tick.done = new Promise((resolve2) => settle = resolve2);
+    this.track(tick);
+    try {
+      const started = await this.write({
+        event: "started",
+        at: now,
+        origin: tick.origin,
+        set: { holder: lease.holder }
+      });
+      if (!started) return false;
+      tick.logged = true;
+      const window = rule.window(plannedAt, row.anchor);
+      const previousDelayMs = row.next_at != null ? Math.max(0, row.next_at - row.updated_at) : null;
+      const next = this.resolved.kind === "interval" ? { previousDelayMs, timeoutMs: this.options.nextTimeoutMs } : void 0;
+      const outcome = await Promise.race([this.execute(tick, window, next), tick.whenClosed]);
+      if (!outcome || tick.closed || lease.lost) return true;
+      this.refreshTiming();
+      const decision = this.rule().decide({
+        plannedAt,
+        endedAt: outcome.endedAt,
+        anchor: row.anchor,
+        status: outcome.status,
+        failedInARow: await this.failedInARow(outcome),
+        choice: outcome.next
+      });
+      await this.writeEnd({
+        event: "decided",
+        at: this.clock.now(),
+        holder: lease.holder,
+        set: {
+          next_at: decision.nextAt,
+          reason: decision.reason,
+          source: decision.source,
+          holder: null,
+          anchor: decision.anchor
+        },
+        firstRunId: outcome.firstRunId,
+        runId: outcome.runId,
+        finalRunId: outcome.runId
+      });
+      return true;
+    } finally {
+      await lease.release();
+      settle();
+    }
+  }
+  async execute(tick, window, next) {
+    const outcome = await this.task.executeTick({
+      next,
+      scheduledAt: window.scheduledAt,
+      nextAt: window.nextAt,
+      periodMs: window.periodMs,
+      clock: this.clock,
+      signal: tick.signal,
+      onRunStarted: tick.noteRun
+    });
+    if (outcome.status === "failure") this.options.onRunError(outcome.error);
+    return outcome;
+  }
+  /**
+   * Take up a change to the task's `timing` export, which its latest run read
+   * afresh: it applies from this decision on. A switch between cron and an
+   * interval needs a restart.
+   */
+  refreshTiming() {
+    if (this.options.override) return;
+    const exported = this.task.timing;
+    if (exported === this.exported) return;
+    try {
+      const resolved = resolveTiming(exported, this.path);
+      if (resolved.kind !== this.resolved.kind) {
+        this.options.onProblem(
+          `${this.path} changed its timing between a cron pattern and an interval; restart ngn run to apply it`
+        );
+        return;
+      }
+      this.resolved = resolved;
+      this.exported = exported;
+    } catch (error) {
+      this.options.onProblem(`${errorSummary(error)}; keeping ${this.rule().words}`);
+    }
+  }
+  /** Run now: one run outside the schedule, through the lease. Resolves once it is under way. */
+  async runNow() {
+    if (this.stopping) return { started: false, reason: "ngn is stopping" };
+    const { periodMs } = this.rule().window(this.clock.now(), this.row?.anchor ?? null);
+    const started = await startManual(
+      {
+        task: this.task,
+        taskId: this.taskId,
+        clock: this.clock,
+        leaseTtlMs: this.ttlMs,
+        window: { nextAt: periodMs == null ? this.nextAt() : null, periodMs },
+        onProblem: this.options.onProblem
+      },
+      (lease) => this.leaseLost(lease)
+    );
+    if ("busy" in started) return { started: false, reason: started.busy };
+    this.track(started.tick);
+    void started.outcome.then((outcome) => {
+      if (outcome.status === "failure") this.options.onRunError(outcome.error);
+    });
+    return { started: true };
+  }
+  /**
+   * What `ngn pause`, `resume` and `next` do, asked of this process (ngnui's
+   * buttons): the same transitions, which the loop then picks up as it would
+   * from the CLI.
+   */
+  control(command) {
+    return controlSchedule(
+      {
+        store: this.store,
+        taskId: this.taskId,
+        name: this.path,
+        pattern: this.resolved.kind === "cron" ? this.resolved.pattern : null,
+        now: this.clock.now()
+      },
+      command
+    );
+  }
+  /** The lease of a tick in progress went: say so in the log while the task is still ours. */
+  leaseLost(lease) {
+    const tick = [...this.ticks].find((t) => t.lease === lease);
+    if (!tick?.logged || tick.closed) return;
+    void this.write({
+      event: "lease_lost",
+      at: this.clock.now(),
+      holder: lease.holder,
+      firstRunId: tick.firstRunId,
+      runId: tick.runId
+    });
+  }
+  /**
+   * A task left `running` by a process that is gone, which its expired lease
+   * says: close the tick's open runs as interrupted and decide the next run as
+   * for a failed tick. False when the task is still held by a live process,
+   * or the recovery could not be written, so the loop waits before looking again.
+   */
+  async recoverIfAbandoned() {
+    const held = await this.task.scheduling.locks.holderOf(taskLeaseName(this.path));
+    if (held && held.expiresAt > Date.now()) return false;
+    const lease = await this.takeLease();
+    if ("busy" in lease) return false;
+    try {
+      const row = await this.store.read(this.taskId);
+      if (row?.state !== "running") return row != null;
+      const at = this.clock.now();
+      const closed = await this.store.closeOpenRuns(
+        this.taskId,
+        "the ngn process running it stopped",
+        { at: Date.now() }
+      );
+      const decision = this.rule().decide({
+        plannedAt: at,
+        endedAt: at,
+        anchor: row.anchor,
+        status: "failure",
+        failedInARow: await this.failedInARow()
+      });
+      const recovered = await this.writeEnd({
+        event: "recovered",
+        at,
+        holder: row.holder,
+        set: {
+          next_at: decision.nextAt,
+          reason: `the process running it stopped; ${decision.reason}`,
+          source: "policy",
+          holder: null,
+          anchor: decision.anchor
+        },
+        firstRunId: closed[0] ?? null,
+        runId: closed.at(-1) ?? null
+      });
+      return recovered != null;
+    } finally {
+      await lease.release();
+    }
+  }
+  /**
+   * Stop starting runs, ask the ones in progress to stop (their signal aborts),
+   * and wait up to `graceMs` for them. A tick that ends in time is decided as
+   * usual; the rest have their open runs closed as failed in `interrupted`,
+   * and an `interrupted` event sets the next run to now.
+   */
+  async stop({ graceMs = STOP_GRACE_MS } = {}) {
+    if (this.stopping) return this.loopDone;
+    this.stopping = true;
+    this.halt.abort();
+    const ticks = [...this.ticks];
+    for (const tick of ticks) tick.controller.abort(new Error("ngn is stopping"));
+    if (ticks.length) {
+      const grace = new AbortController();
+      const settled = await Promise.race([
+        Promise.all(ticks.map((tick) => tick.done)).then(() => true),
+        this.clock.sleep(graceMs, grace.signal).then(() => false)
+      ]);
+      grace.abort();
+      if (!settled) {
+        for (const tick of ticks) if (this.ticks.has(tick)) await this.interrupt(tick);
+      }
+    }
+    await this.loopDone;
+  }
+  async interrupt(tick) {
+    tick.close();
+    const at = this.clock.now();
+    if (tick.firstRunId != null) {
+      await this.store.closeOpenRuns(this.taskId, "ngn stopped before the run ended", {
+        fromRunId: tick.firstRunId,
+        at: Date.now()
+      });
+    }
+    if (tick.logged) {
+      const set = tick.origin === "manual" ? { holder: null } : {
+        holder: null,
+        next_at: at,
+        reason: "ngn stopped before the run ended",
+        source: "policy"
+      };
+      await this.writeEnd({
+        event: "interrupted",
+        at,
+        holder: tick.lease.holder,
+        set,
+        firstRunId: tick.firstRunId,
+        runId: tick.runId
+      });
+    }
+    await tick.lease.release();
+    this.ticks.delete(tick);
+  }
+  /**
+   * Stop without cleaning up, the way a process that died would: no more
+   * steps, no lease renewals, nothing written. For tests standing in for a
+   * crash.
+   */
+  abandon() {
+    this.stopping = true;
+    this.halt.abort();
+    for (const tick of this.ticks) {
+      tick.lease.abandon();
+      tick.close();
+    }
+  }
+};
 
 // src/runtime/taskLibraryScheduler.ts
 var TaskLibraryScheduler = class {
   taskLibrary;
-  onRunError;
+  options;
   scheduledTasks = /* @__PURE__ */ new Map();
   constructor(options) {
     this.taskLibrary = options.taskLibrary;
-    this.onRunError = options.onRunError;
+    this.options = options;
   }
   async start() {
     logTaskLibraryScheduler("Starting scheduler");
     const report = { scheduled: [], failed: [] };
     const scheduledTasks = this.taskLibrary.getTasks().map(async (task) => {
       try {
-        await this.scheduleTask(task);
-        report.scheduled.push({ path: task.taskPath, pattern: task.timingPattern ?? "" });
+        const timing = await this.scheduleTask(task);
+        report.scheduled.push({ path: task.taskPath, timing });
       } catch (error) {
         logTaskLibrarySchedulerError(`Error scheduling task: ${task.taskPath}`);
         logTaskLibrarySchedulerError(error);
@@ -1639,58 +3021,106 @@ var TaskLibraryScheduler = class {
     report.failed.sort(byPath);
     return report;
   }
-  async stop() {
+  /**
+   * Stop starting runs, and give the runs in progress up to `graceMs` to end
+   * before closing them as interrupted.
+   */
+  async stop(options = {}) {
     logTaskLibraryScheduler("Stopping scheduler");
-    for (const [path, task] of this.scheduledTasks) {
-      logTaskLibraryScheduler(`Stopping scheduled task: ${path}`);
-      task.stop();
-    }
+    await Promise.all(
+      [...this.scheduledTasks].map(([path, schedule]) => {
+        logTaskLibraryScheduler(`Stopping scheduled task: ${path}`);
+        return schedule.stop(options);
+      })
+    );
   }
+  /** Stop as a process that died would, writing nothing. For tests standing in for a crash. */
+  abandon() {
+    for (const schedule of this.scheduledTasks.values()) schedule.abandon();
+  }
+  /**
+   * Check a loaded task's exports and start its schedule. The timing it is
+   * scheduled on is returned; anything wrong with the exports is thrown,
+   * naming the task, so it fails now rather than on the first tick.
+   */
   async scheduleTask(task) {
     logTaskLibraryScheduler(`Scheduling task: ${task.taskPath}`);
     await task.loadEntry();
-    logTaskLibraryScheduler(`Scheduling: ${task.taskPath} with pattern: ${task.timingPattern}`);
-    invariant8(task.hasTimingExport(), `timing pattern is missing for ${task.taskPath}`);
-    invariant8(task.hasTaskExport(), `task function is missing for ${task.taskPath}`);
-    invariant8(
-      task.timingPattern && this.isCronPatternValid(task.timingPattern),
-      `Invalid cron pattern: ${task.timingPattern} for ${task.taskPath}`
+    const timing = this.options.timing ?? task.timing;
+    const resolved = resolveTiming(timing, task.taskPath);
+    invariant7(task.hasTaskExport(), `task function is missing for ${task.taskPath}`);
+    task.validateExports();
+    invariant7(
+      resolved.kind === "cron" || !task.retryPolicy.breaker,
+      `retry.breaker for ${task.taskPath}: an interval task does not skip ticks; remove the breaker and use timing.backoff, which slows a failing interval task down`
     );
-    const scheduledTask = scheduleTask(task, task.timingPattern, (error) => {
-      logTaskLibrarySchedulerError(`Run failed: ${task.taskPath}`);
-      logTaskLibrarySchedulerError(error);
-      this.onRunError?.(task.taskPath, error, failedRunId(error));
+    const next = task.nextHook;
+    invariant7(
+      next == null || typeof next === "function",
+      `next for ${task.taskPath}: expected a function`
+    );
+    invariant7(
+      next == null || resolved.kind === "interval",
+      `next for ${task.taskPath}: only an interval task can choose its next run; a cron task runs on its pattern`
+    );
+    const schedule = new TaskSchedule({
+      task,
+      timing,
+      override: this.options.timing != null,
+      clock: this.options.clock ?? systemClock,
+      leaseTtlMs: this.options.leaseTtlMs,
+      random: this.options.random,
+      nextTimeoutMs: this.options.nextTimeoutMs,
+      onRunError: (error) => {
+        logTaskLibrarySchedulerError(`Run failed: ${task.taskPath}`);
+        logTaskLibrarySchedulerError(error);
+        this.options.onRunError?.(task.taskPath, error, failedRunId(error));
+      },
+      onProblem: (message) => {
+        logTaskLibrarySchedulerError(message);
+        this.options.onScheduleProblem?.(task.taskPath, message);
+      }
     });
-    this.scheduledTasks.set(task.taskPath, scheduledTask);
+    await schedule.start();
+    this.scheduledTasks.set(task.taskPath, schedule);
     logTaskLibraryScheduler(`Scheduled: ${task.taskPath}`);
+    return timing;
   }
-  unscheduleTask(task) {
-    const existingTask = this.scheduledTasks.get(task.taskPath);
-    if (!existingTask) {
-      return;
+  /**
+   * Start one run of a scheduled task now, outside its schedule: retries,
+   * budget, locks and hooks all apply, and errors go where a tick's go. It is
+   * not a tick, so the breaker does not hold it back, and it leaves the next
+   * run where it was. Resolves once the run is under way, not when it ends.
+   *
+   * A run of the task still going, in this process or another, is reported
+   * rather than recorded as a skip: the person asking can simply wait.
+   */
+  async runNow(taskPath) {
+    const schedule = this.scheduledTasks.get(taskPath);
+    if (!schedule)
+      return { started: false, reason: `${taskPath} is not scheduled by this ngn run` };
+    return schedule.runNow();
+  }
+  /** Pause, resume or move a scheduled task's next run, as `ngn pause`, `resume` and `next` do. */
+  async control(taskPath, command) {
+    const schedule = this.scheduledTasks.get(taskPath);
+    if (!schedule) {
+      return {
+        applied: false,
+        error: true,
+        message: `${taskPath} is not scheduled by this ngn run`
+      };
     }
+    return schedule.control(command);
+  }
+  async unscheduleTask(task) {
+    const existing = this.scheduledTasks.get(task.taskPath);
+    if (!existing) return;
     logTaskLibraryScheduler(`Unscheduling: ${task.taskPath}`);
-    existingTask.stop();
     this.scheduledTasks.delete(task.taskPath);
+    await existing.stop();
     logTaskLibraryScheduler(`Unscheduled: ${task.taskPath}`);
   }
-  isCronPatternValid(cronPattern) {
-    return isCronPatternValid(cronPattern);
-  }
-  // startScheduledTask(path: string) {
-  //   const task = this.scheduledTasks.get(path);
-  //   if (!task) {
-  //     return;
-  //   }
-  //   task.start();
-  // }
-  // stopScheduledTask(path: string) {
-  //   const task = this.scheduledTasks.get(path);
-  //   if (!task) {
-  //     return;
-  //   }
-  //   task.stop();
-  // }
 };
 function byPath(a, b) {
   return a.path.localeCompare(b.path);
@@ -1701,7 +3131,7 @@ function reasonOf(error, path) {
 }
 
 // src/runtime/taskOnceRunner.ts
-import invariant9 from "tiny-invariant";
+import invariant8 from "tiny-invariant";
 import { logTaskOnceRunner, logTaskOnceRunnerError } from "@apisurf/ngn-os";
 var TaskOnceRunner = class {
   task;
@@ -1712,7 +3142,7 @@ var TaskOnceRunner = class {
     logTaskOnceRunner(`Preparing to run task: ${this.task.taskPath}`);
     await this.task.loadEntry();
     logTaskOnceRunner(`Loaded task code: ${this.task.taskPath}`);
-    invariant9(this.task.hasTaskExport(), `task function is missing for ${this.task.taskPath}`);
+    invariant8(this.task.hasTaskExport(), `task function is missing for ${this.task.taskPath}`);
     logTaskOnceRunner(`Running task: ${this.task.taskPath}`);
     try {
       await this.task.execute();
@@ -1731,10 +3161,10 @@ import {
   initDbFileIfNotExists,
   isDbPath
 } from "@apisurf/ngn-persistence";
-import invariant10 from "tiny-invariant";
+import invariant9 from "tiny-invariant";
 var db;
 async function setupDbClient(dbPath) {
-  invariant10(isDbPath(dbPath), "Invalid db path");
+  invariant9(isDbPath(dbPath), "Invalid db path");
   if (db) {
     return db;
   }
@@ -1742,7 +3172,7 @@ async function setupDbClient(dbPath) {
   return db;
 }
 function getDbClient() {
-  invariant10(db, "DB client not initialized");
+  invariant9(db, "DB client not initialized");
   return db;
 }
 
@@ -1753,8 +3183,8 @@ import {
   logTaskConsoleInfo,
   logTaskConsoleWarn
 } from "@apisurf/ngn-os";
-import invariant11 from "tiny-invariant";
-import { errorSummary, failureLine } from "@apisurf/ngn-schema/describe";
+import invariant10 from "tiny-invariant";
+import { errorSummary as errorSummary2, failureLine as failureLine2 } from "@apisurf/ngn-schema/describe";
 
 // src/db/services/fileTask.ts
 import { $fileTaskInsert } from "@apisurf/ngn-schema";
@@ -1943,7 +3373,7 @@ var TaskRunService = class {
   }
   async skipTaskRun(taskRunId, reason = null) {
     await this.db.execute({
-      sql: "UPDATE task_runs SET status = 'skipped', ended_at = :ended_at, skip_reason = :reason WHERE id = :id",
+      sql: "UPDATE task_runs SET status = 'skipped', ended_at = :ended_at, skip_reason = :reason WHERE id = :id AND ended_at IS NULL",
       args: { id: taskRunId, ended_at: Date.now(), reason }
     });
   }
@@ -1978,16 +3408,20 @@ var TaskRunService = class {
   }
   async startTaskRun(taskRunId) {
     await this.db.execute({
-      sql: "UPDATE task_runs SET started_at = :started_at, status = 'running' WHERE id = :id",
+      sql: "UPDATE task_runs SET started_at = :started_at, status = 'running' WHERE id = :id AND ended_at IS NULL",
       args: {
         started_at: Date.now(),
         id: taskRunId
       }
     });
   }
+  /**
+   * Record how a run ended. False when it already had an end: ngn closed it as
+   * interrupted while it was still going, and that record stands.
+   */
   async endTaskRun(taskRunId, status, result = null) {
-    await this.db.execute({
-      sql: "UPDATE task_runs SET ended_at = :ended_at, status = :status, result = :result WHERE id = :id",
+    const { rowsAffected } = await this.db.execute({
+      sql: "UPDATE task_runs SET ended_at = :ended_at, status = :status, result = :result WHERE id = :id AND ended_at IS NULL",
       args: {
         ended_at: Date.now(),
         status,
@@ -1995,6 +3429,7 @@ var TaskRunService = class {
         id: taskRunId
       }
     });
+    return rowsAffected > 0;
   }
   async getById(taskId) {
     const { rows } = await this.db.execute({
@@ -2137,6 +3572,27 @@ var LockService = class {
     });
     return rowsAffected > 0;
   }
+  /** Who holds `name`, and until when; null when nobody has it. Expired leases included. */
+  async holderOf(name) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT holder, task_run_id, expires_at FROM locks WHERE name = ?",
+      args: [name]
+    });
+    const row = rows[0];
+    if (!row) return null;
+    return {
+      holder: row.holder,
+      taskRunId: row.task_run_id ?? null,
+      expiresAt: row.expires_at
+    };
+  }
+  /** Record which run a held lease is working for. */
+  async setRun(name, holder, taskRunId) {
+    await this.db.execute({
+      sql: "UPDATE locks SET task_run_id = :taskRunId WHERE name = :name AND holder = :holder",
+      args: { name, holder, taskRunId }
+    });
+  }
   async release(name, holder) {
     await this.db.execute({
       sql: "DELETE FROM locks WHERE name = :name AND holder = :holder",
@@ -2150,9 +3606,10 @@ async function recordSafely(runId, write) {
   try {
     await write();
   } catch (error) {
-    logTaskCallback(`Could not record what run ${runId} threw: ${errorSummary(error)}`);
+    logTaskCallback(`Could not record what run ${runId} threw: ${errorSummary2(error)}`);
   }
 }
+var lateEnd = (outcome) => `finished after ngn closed it as interrupted: ${outcome}`;
 function createControlsGenerator({
   dbClient,
   env,
@@ -2163,12 +3620,13 @@ function createControlsGenerator({
   const kvService = new KVService(dbClient);
   const timingService = new TimingService(dbClient);
   const lockService = new LockService(dbClient);
+  const scheduling = { store: new ScheduleStore(dbClient), locks: lockService };
   const generateControls = ({ sourcePath, compiledPath }) => {
     let fileTaskId;
     let fileTaskVersionId;
     const assertMandatoryIds = () => {
-      invariant11(!!fileTaskId, "Task ID not found");
-      invariant11(!!fileTaskVersionId, "Task version ID not found");
+      invariant10(!!fileTaskId, "Task ID not found");
+      invariant10(!!fileTaskVersionId, "Task version ID not found");
     };
     const taskCallbacks = {
       async onTaskLoadComplete({ paths, md5Hash, compiledCode }) {
@@ -2212,8 +3670,12 @@ function createControlsGenerator({
         },
         async onFailure({ path, stage, error }) {
           await recordSafely(runId, async () => {
-            await taskRunService.endTaskRun(runId, "failure");
-            await logService.logError(taskId, runId, failureLine(stage, error));
+            if (!await taskRunService.endTaskRun(runId, "failure")) {
+              await logService.logError(taskId, runId, failureLine2(stage, error));
+              await logService.logWarning(taskId, runId, lateEnd("failed"));
+              return;
+            }
+            await logService.logError(taskId, runId, failureLine2(stage, error));
             await logService.logError(taskId, runId, "Task failed");
           });
           logTaskCallback(`Task failed in ${stage}: ${taskId}, run ID: ${runId}`);
@@ -2222,13 +3684,16 @@ function createControlsGenerator({
         async onHookError({ path, stage, error }) {
           await recordSafely(
             runId,
-            () => logService.logError(taskId, runId, failureLine(stage, error))
+            () => logService.logError(taskId, runId, failureLine2(stage, error))
           );
           logTaskCallback(`Hook ${stage} threw: ${taskId}, run ID: ${runId}`);
           report?.({ path, runId, stage, error, fatal: false });
         },
         async onSuccess({ result }) {
-          await taskRunService.endTaskRun(runId, "success", serializeResult(result));
+          if (!await taskRunService.endTaskRun(runId, "success", serializeResult(result))) {
+            await logService.logWarning(taskId, runId, lateEnd("succeeded"));
+            return;
+          }
           await logService.logInfo(taskId, runId, "Task succeeded");
           logTaskCallback(`Task succeeded: ${taskId}, run ID: ${runId}`);
         }
@@ -2273,6 +3738,7 @@ function createControlsGenerator({
           return taskRunService.countSkipsSince(fileTaskId, reason, afterId);
         }
       },
+      scheduling,
       env: env ?? {},
       // Scoped to this task's own folder — see createTaskSqlite
       sqlite: createTaskSqlite(sourcePath),
@@ -2295,11 +3761,14 @@ export {
   Compiler,
   LockBusyError,
   Queue,
+  STOP_GRACE_MS,
+  ScheduleStore,
   Task,
   TaskLibrary,
   TaskLibraryScheduler,
   TaskOnceRunner,
   closeTaskDatabases,
+  controlSchedule,
   createControlsGenerator,
   executeEsm,
   failedRunId,
@@ -2307,7 +3776,10 @@ export {
   initDbFileIfNotExists,
   isCronPatternValid,
   releaseTaskDatabases,
+  resolveTiming,
   runFailure,
-  scheduleTask,
-  setupDbClient
+  runOnce,
+  setupDbClient,
+  systemClock,
+  timingFromFlag
 };