@stigmer/react 3.5.3 → 3.7.0

package/src/schedule/cadence.ts

@@ -0,0 +1,298 @@
+/**
+ * The cadence model behind {@link CadenceField} — a pure, dependency-free
+ * bridge between human-friendly schedule presets and the 5-field cron
+ * grammar the Schedule spec stores.
+ *
+ * Deliberately NOT a cron parser. The platform owns no cron parsing in
+ * either edition — calendar and DST semantics live in the Temporal server
+ * (see stigmer-server's schedule/controller/cron.go, DD-008 D2). This
+ * module only:
+ *
+ *   1. GENERATES cron strings from presets (`cadenceToCron`) — trivial
+ *      string construction, always valid by construction.
+ *   2. RECOGNIZES the exact shapes the builder emits (`cronToCadence`)
+ *      so a stored cron round-trips back into the preset UI; anything
+ *      else falls back to the `custom` preset showing the raw string.
+ *   3. MIRRORS the server's purely lexical validation (`validateCron`,
+ *      `validateTimeZone`) with the same user-facing wording, so the
+ *      form can reject bad input instantly. The server remains the
+ *      authority — its errors surface verbatim on submit.
+ */
+
+// ---------------------------------------------------------------------------
+// Preset model
+// ---------------------------------------------------------------------------
+
+/** A human-friendly cadence, convertible to/from a cron expression. */
+export type CadencePreset =
+  | { readonly kind: "hourly"; readonly minute: number }
+  | { readonly kind: "daily"; readonly hour: number; readonly minute: number }
+  | {
+      readonly kind: "weekly";
+      /** Days of week, cron numbering: 0 = Sunday … 6 = Saturday. */
+      readonly days: readonly number[];
+      readonly hour: number;
+      readonly minute: number;
+    }
+  | {
+      readonly kind: "monthly";
+      /** Day of month, 1–31. Days 29–31 skip months without that day. */
+      readonly day: number;
+      readonly hour: number;
+      readonly minute: number;
+    }
+  | { readonly kind: "custom"; readonly cron: string };
+
+/** Discriminant of {@link CadencePreset}. */
+export type CadenceKind = CadencePreset["kind"];
+
+/** Day-of-week labels indexed by cron numbering (0 = Sunday). */
+export const WEEKDAY_LABELS = [
+  "Sunday",
+  "Monday",
+  "Tuesday",
+  "Wednesday",
+  "Thursday",
+  "Friday",
+  "Saturday",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Preset → cron
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the 5-field cron expression for a preset.
+ *
+ * Output is always valid by construction: numeric fields only,
+ * day-of-week in cron numbering (0 = Sunday). For `custom`, the raw
+ * string is returned as-is — validate it with {@link validateCron}.
+ */
+export function cadenceToCron(preset: CadencePreset): string {
+  switch (preset.kind) {
+    case "hourly":
+      return `${preset.minute} * * * *`;
+    case "daily":
+      return `${preset.minute} ${preset.hour} * * *`;
+    case "weekly": {
+      // Sorted, deduplicated day list keeps the output canonical so
+      // cronToCadence round-trips regardless of selection order.
+      const days = [...new Set(preset.days)].sort((a, b) => a - b);
+      return `${preset.minute} ${preset.hour} * * ${days.join(",")}`;
+    }
+    case "monthly":
+      return `${preset.minute} ${preset.hour} ${preset.day} * *`;
+    case "custom":
+      return preset.cron;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Cron → preset (recognition, not parsing)
+// ---------------------------------------------------------------------------
+
+const HOURLY_RE = /^(\d{1,2}) \* \* \* \*$/;
+const DAILY_RE = /^(\d{1,2}) (\d{1,2}) \* \* \*$/;
+const WEEKLY_RE = /^(\d{1,2}) (\d{1,2}) \* \* (\d(?:,\d)*)$/;
+const MONTHLY_RE = /^(\d{1,2}) (\d{1,2}) (\d{1,2}) \* \*$/;
+
+/**
+ * Recognize a cron expression as one of the builder's presets.
+ *
+ * Only the exact shapes {@link cadenceToCron} emits (plus the
+ * calendar shorthands `@hourly`/`@daily`/`@weekly`/`@monthly`) map to a
+ * structured preset. Everything else — ranges, steps, names, `@yearly`
+ * — is a perfectly valid schedule that this UI simply cannot decompose,
+ * so it round-trips as `custom` with the raw string intact.
+ */
+export function cronToCadence(cron: string): CadencePreset {
+  const normalized = cron.trim().replace(/\s+/g, " ");
+
+  switch (normalized) {
+    case "@hourly":
+      return { kind: "hourly", minute: 0 };
+    case "@daily":
+      return { kind: "daily", hour: 0, minute: 0 };
+    case "@weekly":
+      return { kind: "weekly", days: [0], hour: 0, minute: 0 };
+    case "@monthly":
+      return { kind: "monthly", day: 1, hour: 0, minute: 0 };
+  }
+
+  let m = HOURLY_RE.exec(normalized);
+  if (m) {
+    const minute = Number(m[1]);
+    if (isMinute(minute)) return { kind: "hourly", minute };
+  }
+
+  m = DAILY_RE.exec(normalized);
+  if (m) {
+    const minute = Number(m[1]);
+    const hour = Number(m[2]);
+    if (isMinute(minute) && isHour(hour)) return { kind: "daily", hour, minute };
+  }
+
+  m = WEEKLY_RE.exec(normalized);
+  if (m) {
+    const minute = Number(m[1]);
+    const hour = Number(m[2]);
+    const days = m[3].split(",").map(Number);
+    if (
+      isMinute(minute) &&
+      isHour(hour) &&
+      days.length > 0 &&
+      days.every((d) => d >= 0 && d <= 6) &&
+      new Set(days).size === days.length
+    ) {
+      return { kind: "weekly", days: [...days].sort((a, b) => a - b), hour, minute };
+    }
+  }
+
+  m = MONTHLY_RE.exec(normalized);
+  if (m) {
+    const minute = Number(m[1]);
+    const hour = Number(m[2]);
+    const day = Number(m[3]);
+    if (isMinute(minute) && isHour(hour) && day >= 1 && day <= 31) {
+      return { kind: "monthly", day, hour, minute };
+    }
+  }
+
+  return { kind: "custom", cron };
+}
+
+function isMinute(n: number): boolean {
+  return Number.isInteger(n) && n >= 0 && n <= 59;
+}
+
+function isHour(n: number): boolean {
+  return Number.isInteger(n) && n >= 0 && n <= 23;
+}
+
+// ---------------------------------------------------------------------------
+// Plain-English summary
+// ---------------------------------------------------------------------------
+
+/**
+ * Human-readable summary of a cadence, e.g.
+ * `"Every day at 09:00 (Asia/Kolkata)"`.
+ *
+ * This is a description of the chosen preset, not a computed fire-time
+ * forecast — the platform's next fire time is published by the server
+ * as `status.next_fire_at` after apply.
+ */
+export function describeCadence(
+  preset: CadencePreset,
+  timeZone?: string,
+): string {
+  const zone = timeZone ? ` (${timeZone})` : "";
+  switch (preset.kind) {
+    case "hourly":
+      return `Every hour at minute ${preset.minute}${zone}`;
+    case "daily":
+      return `Every day at ${formatTime(preset.hour, preset.minute)}${zone}`;
+    case "weekly": {
+      const days = [...new Set(preset.days)].sort((a, b) => a - b);
+      const names =
+        days.length === 7
+          ? "day"
+          : listWithAnd(days.map((d) => WEEKDAY_LABELS[d]));
+      return `Every ${names} at ${formatTime(preset.hour, preset.minute)}${zone}`;
+    }
+    case "monthly":
+      return `On day ${preset.day} of every month at ${formatTime(preset.hour, preset.minute)}${zone}`;
+    case "custom":
+      return `Cron “${preset.cron.trim()}”${zone}`;
+  }
+}
+
+/** `9, 5` → `"09:05"` (24-hour clock, zero-padded). */
+export function formatTime(hour: number, minute: number): string {
+  return `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
+}
+
+function listWithAnd(items: readonly string[]): string {
+  if (items.length === 1) return items[0];
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+
+// ---------------------------------------------------------------------------
+// Lexical validation — mirrors stigmer-server schedule/controller/cron.go
+// ---------------------------------------------------------------------------
+
+// The accepted @-shorthands, the field character set, the rejection
+// cases AND the message wording below mirror the server byte-for-byte
+// (Go: cron.go / cron_test.go; Java: ValidateScheduleSpec). A change on
+// any side must change all three, or the instant client feedback drifts
+// from what the server enforces on submit.
+
+const CRON_SHORTHANDS = new Set([
+  "@hourly",
+  "@daily",
+  "@weekly",
+  "@monthly",
+  "@yearly",
+]);
+
+const CRON_FIELD_PATTERN = /^[0-9A-Za-z*,/-]+$/;
+
+/**
+ * Validate a cron expression against the platform's lexical grammar.
+ *
+ * Returns the user-facing error message (identical wording to the
+ * server's) or `null` when the expression is acceptable. Purely
+ * lexical — it does not evaluate calendar semantics.
+ */
+export function validateCron(cron: string): string | null {
+  if (cron.startsWith("CRON_TZ=") || cron.startsWith("TZ=")) {
+    return "spec.cron must not carry a timezone prefix (CRON_TZ=/TZ=) — spec.time_zone is the single timezone authority";
+  }
+
+  if (cron.includes("#")) {
+    return "spec.cron must not contain a comment (#)";
+  }
+
+  if (cron.startsWith("@")) {
+    if (cron.startsWith("@every")) {
+      return "spec.cron must be a calendar expression — @every intervals are not supported";
+    }
+    if (!CRON_SHORTHANDS.has(cron)) {
+      return `spec.cron shorthand "${cron}" is not supported — use @hourly, @daily, @weekly, @monthly, or @yearly, or a 5-field cron expression`;
+    }
+    return null;
+  }
+
+  // Matches Go's strings.Fields: split on runs of whitespace, so
+  // surrounding/duplicate whitespace never produces empty fields.
+  const fields = cron.split(/\s+/).filter((f) => f.length > 0);
+  if (fields.length !== 5) {
+    return `spec.cron must have exactly 5 fields (minute hour day-of-month month day-of-week); got ${fields.length}`;
+  }
+
+  for (const field of fields) {
+    if (!CRON_FIELD_PATTERN.test(field)) {
+      return `spec.cron field "${field}" contains unsupported characters — allowed: digits, names, '*', ',', '-', '/'`;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate an IANA time zone name using the runtime's own tz database
+ * (`Intl`), mirroring the server's check against the platform tz
+ * database. Returns the user-facing error message or `null`.
+ *
+ * `"Local"` is rejected explicitly for the same reason the server
+ * rejects it: it is host-dependent, not a zone.
+ */
+export function validateTimeZone(timeZone: string): string | null {
+  const invalid = `spec.time_zone "${timeZone}" is not a valid IANA time zone (e.g. "Asia/Kolkata")`;
+  if (timeZone === "Local") return invalid;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone });
+    return null;
+  } catch {
+    return invalid;
+  }
+}

package/src/schedule/index.ts

@@ -0,0 +1,69 @@
+export { deriveScheduleState, formatNextFire } from "./scheduleState.js";
+export type { ScheduleState, ScheduleStateInfo } from "./scheduleState.js";
+
+export { createScheduleListFn, listSchedulesPage } from "./scheduleListFn.js";
+export type { ScheduleListClient, SchedulePage } from "./scheduleListFn.js";
+
+export { useSchedule } from "./useSchedule.js";
+export type { UseScheduleReturn } from "./useSchedule.js";
+
+export { useScheduleRuns } from "./useScheduleRuns.js";
+export type {
+  UseScheduleRunsOptions,
+  UseScheduleRunsReturn,
+} from "./useScheduleRuns.js";
+
+export { useScheduleList } from "./useScheduleList.js";
+export type {
+  UseScheduleListOptions,
+  UseScheduleListReturn,
+} from "./useScheduleList.js";
+
+export { useScheduleCount } from "./useScheduleCount.js";
+export type {
+  UseScheduleCountOptions,
+  UseScheduleCountReturn,
+} from "./useScheduleCount.js";
+
+export { useResumeSchedule } from "./useResumeSchedule.js";
+export type { UseResumeScheduleReturn } from "./useResumeSchedule.js";
+
+export { useTriggerSchedule } from "./useTriggerSchedule.js";
+export type { UseTriggerScheduleReturn } from "./useTriggerSchedule.js";
+
+export { useSetScheduleEnabled } from "./useSetScheduleEnabled.js";
+export type { UseSetScheduleEnabledReturn } from "./useSetScheduleEnabled.js";
+
+export { useUpdateScheduleSpec } from "./useUpdateScheduleSpec.js";
+export type { UseUpdateScheduleSpecReturn } from "./useUpdateScheduleSpec.js";
+
+export { createScheduleColumns } from "./scheduleColumns.js";
+export type { ScheduleColumnsOptions } from "./scheduleColumns.js";
+
+export { ScheduleRowActions } from "./ScheduleRowActions.js";
+export type { ScheduleRowActionsProps } from "./ScheduleRowActions.js";
+
+export { ScheduleDetailView, ScheduleIcon } from "./ScheduleDetailView.js";
+export type { ScheduleDetailViewProps } from "./ScheduleDetailView.js";
+
+export { ScheduleRunsTable } from "./ScheduleRunsTable.js";
+export type { ScheduleRunsTableProps } from "./ScheduleRunsTable.js";
+
+export {
+  cadenceToCron,
+  cronToCadence,
+  describeCadence,
+  validateCron,
+  validateTimeZone,
+  WEEKDAY_LABELS,
+} from "./cadence.js";
+export type { CadencePreset, CadenceKind } from "./cadence.js";
+
+export { useCreateSchedule } from "./useCreateSchedule.js";
+export type { UseCreateScheduleReturn } from "./useCreateSchedule.js";
+
+export { CadenceField } from "./CadenceField.js";
+export type { CadenceFieldProps } from "./CadenceField.js";
+
+export { ScheduleForm } from "./ScheduleForm.js";
+export type { ScheduleFormProps } from "./ScheduleForm.js";

package/src/schedule/scheduleColumns.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { formatRelativeTime } from "../activity/format-relative-time.js";
+import { StatusBadge } from "../resource-workbench/components/StatusBadge.js";
+import type { WorkbenchColumnDef } from "../resource-workbench/types.js";
+import { deriveScheduleState, formatNextFire } from "./scheduleState.js";
+
+/** Options for {@link createScheduleColumns}. */
+export interface ScheduleColumnsOptions {
+  /**
+   * Clock provider for the "next fire" and "last run" columns.
+   * Injectable for deterministic tests and Scenar fixtures.
+   * @default () => new Date()
+   */
+  readonly now?: () => Date;
+}
+
+/**
+ * Column set for a schedule workbench — shared by every console so the
+ * list renders identically everywhere (DD-016).
+ *
+ * The columns exist because schedules are listed via the direct query:
+ * each row is a full `Schedule` proto, so the operational fields the
+ * issue calls for (next fire, last run, enabled/paused state) render
+ * straight from the row — no generic `SearchResult` limitations.
+ *
+ * Columns are not sortable: the direct query has one fixed server-side
+ * order (newest first), and a sort affordance that silently does
+ * nothing would lie.
+ */
+export function createScheduleColumns(
+  options?: ScheduleColumnsOptions,
+): WorkbenchColumnDef<Schedule>[] {
+  const now = options?.now ?? (() => new Date());
+
+  return [
+    {
+      id: "name",
+      header: "Name",
+      cell: (item) => (
+        <span className="font-medium text-foreground">
+          {item.metadata?.name || item.metadata?.slug}
+        </span>
+      ),
+      flex: 2,
+    },
+    {
+      id: "state",
+      header: "State",
+      cell: (item) => {
+        const info = deriveScheduleState(item.spec, item.status);
+        return <StatusBadge phase={info.phase} label={info.label} />;
+      },
+      flex: 1,
+    },
+    {
+      id: "cron",
+      header: "Cadence",
+      cell: (item) => (
+        <span className="inline-flex items-baseline gap-1.5">
+          <code className="font-mono text-xs text-foreground">
+            {item.spec?.cron || "—"}
+          </code>
+          <span className="text-xs text-muted-foreground">
+            {item.spec?.timeZone}
+          </span>
+        </span>
+      ),
+      flex: 1.5,
+    },
+    {
+      id: "next-fire",
+      header: "Next fire",
+      cell: (item) => {
+        const info = deriveScheduleState(item.spec, item.status);
+        const nextFireAt = item.status?.nextFireAt;
+        return (
+          <span className="text-muted-foreground">
+            {info.state === "active" && nextFireAt
+              ? formatNextFire(timestampDate(nextFireAt), now())
+              : "—"}
+          </span>
+        );
+      },
+      flex: 1,
+    },
+    {
+      id: "last-run",
+      header: "Last run",
+      cell: (item) => (
+        <span className="text-muted-foreground">
+          {item.status?.lastFireAt
+            ? formatRelativeTime(timestampDate(item.status.lastFireAt), now())
+            : "Never"}
+        </span>
+      ),
+      flex: 1,
+    },
+    {
+      id: "target",
+      header: "Target agent",
+      cell: (item) => {
+        const target =
+          item.spec?.target?.case === "agent" ? item.spec.target.value : undefined;
+        return (
+          <span className="text-muted-foreground">
+            {target?.agentRef
+              ? `${target.agentRef.org}/${target.agentRef.slug}`
+              : "—"}
+          </span>
+        );
+      },
+      flex: 1.5,
+    },
+  ];
+}

package/src/schedule/scheduleListFn.ts

@@ -0,0 +1,108 @@
+// Schedule list fetching — the direct-query core plus the workbench adapter.
+//
+// Schedules are the one Library kind NOT backed by the search service: the
+// generic `SearchResult` summary cannot carry the operational fields a
+// schedule list exists to show (`next_fire_at`, enabled/paused state, last
+// run), while the direct `listSchedules` query returns full `Schedule`
+// protos and was explicitly shaped for "the org-context view a console tab
+// needs". Both consoles consume this single implementation — inlining it
+// per-app would duplicate correctness-bearing pagination logic (DD-016).
+
+import { create } from "@bufbuild/protobuf";
+import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import {
+  ListSchedulesRequestSchema,
+  type ListSchedulesRequest,
+  type ScheduleList,
+} from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/io_pb";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import type { ListParams, ListResult } from "@stigmer/sdk";
+
+/** The slice of the Stigmer client this module needs (mockable in tests). */
+export interface ScheduleListClient {
+  readonly schedule: {
+    list(input: ListSchedulesRequest): Promise<ScheduleList>;
+  };
+}
+
+/** One page of schedules, with pagination totals. */
+export interface SchedulePage {
+  /** Full `Schedule` protos (spec + status) for the requested page. */
+  readonly items: readonly Schedule[];
+  /** Total schedules in the org (across all pages). */
+  readonly totalCount: number;
+  /** Total pages at the requested page size. */
+  readonly totalPages: number;
+}
+
+const DEFAULT_PAGE_SIZE = 20;
+
+/**
+ * Fetch one page of an organization's schedules via the direct query.
+ *
+ * Handles a verified split between the two server editions: cloud slices
+ * pages server-side, while the OSS server documents that it ignores
+ * `page_info` and returns every matching schedule. A server that
+ * paginated can never return more rows than the requested size, so an
+ * overflowing response is the tell that the server ignored pagination —
+ * only then is the page sliced locally (absolute indices into the full
+ * list). A cloud page passes through untouched.
+ */
+export async function listSchedulesPage(
+  client: ScheduleListClient,
+  org: string,
+  page: { readonly num?: number; readonly size?: number } = {},
+): Promise<SchedulePage> {
+  const size = page.size && page.size > 0 ? page.size : DEFAULT_PAGE_SIZE;
+  const num = page.num && page.num > 0 ? page.num : 1;
+
+  const result = await client.schedule.list(
+    create(ListSchedulesRequestSchema, {
+      org,
+      pageInfo: { num, size },
+    }),
+  );
+
+  const items =
+    result.items.length > size
+      ? result.items.slice((num - 1) * size, num * size)
+      : result.items;
+
+  return {
+    items,
+    totalCount: result.totalCount,
+    totalPages: Math.ceil(result.totalCount / size),
+  };
+}
+
+/**
+ * Build a `ResourceWorkbench`-compatible `listFn` over the direct
+ * schedule query.
+ *
+ * The returned entries are full `Schedule` protos occupying the
+ * `SearchResult` slot of `ListResult` — `ResourceWorkbench` is generic
+ * over its row type (`useResourceCollection` casts entries through to
+ * `TData`), and this is the one documented place where that cast
+ * happens. Consumers type their workbench as
+ * `ResourceWorkbench<Schedule>` and pass `getItemId={(s) => s.metadata?.id}`.
+ *
+ * `params.query` and `params.crossOrgPublic` are ignored: schedules have
+ * no server-side text search (render the workbench with
+ * `searchable={false}`) and are never public/cross-org.
+ */
+export function createScheduleListFn(
+  client: ScheduleListClient,
+): (params: ListParams) => Promise<ListResult> {
+  return async (params: ListParams): Promise<ListResult> => {
+    const { items, totalCount, totalPages } = await listSchedulesPage(
+      client,
+      params.org,
+      params.page ?? {},
+    );
+    return {
+      entries: items as unknown as SearchResult[],
+      totalCount,
+      totalPages,
+    };
+  };
+}

package/src/schedule/scheduleState.ts

@@ -0,0 +1,96 @@
+// Pure schedule-state derivation — the disabled-vs-paused vocabulary,
+// computed on read.
+//
+// A schedule that is not firing is stopped by one of two levers with two
+// different writers and two different remedies (the backend pins this
+// vocabulary in its controller docs):
+//
+//   - "disabled" — the OWNER's switch (`spec.enabled = false`), cleared
+//     by re-applying the manifest or the console's Enable action.
+//   - "paused" — the PLATFORM's failure-streak latch
+//     (`status.paused_reason` non-empty), cleared only by Resume.
+//
+// The console must never collapse these into one badge (stigmer/stigmer#352):
+// each state names its own remedy. When both levers are set, "disabled"
+// wins for display — the owner's intent dominates — but callers should
+// keep the paused reason visible alongside (the banner does).
+
+import type { ScheduleSpec } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/spec_pb";
+import type { ScheduleStatus } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/status_pb";
+import type { StatusPhase } from "../resource-workbench/types.js";
+
+/** The three mutually-exclusive display states of a schedule. */
+export type ScheduleState = "active" | "disabled" | "paused";
+
+/** Derived display state: the tri-state plus its shared-badge rendering. */
+export interface ScheduleStateInfo {
+  /** The display state ("disabled" wins when both levers are set). */
+  readonly state: ScheduleState;
+  /** `StatusPhase` for the shared `StatusBadge` (`--stgm-status-*` tokens). */
+  readonly phase: StatusPhase;
+  /** Human-readable badge label. */
+  readonly label: string;
+  /**
+   * `true` when the platform pause latch is set — independent of the
+   * display state, so a disabled-AND-paused schedule can still surface
+   * its `status.pausedReason`.
+   */
+  readonly isPaused: boolean;
+}
+
+/**
+ * Derive a schedule's display state from its spec and status.
+ *
+ * A missing spec derives as "disabled" — the same fail-closed reading the
+ * server applies to a manifest that omits `enabled`.
+ */
+export function deriveScheduleState(
+  spec: ScheduleSpec | undefined,
+  status: ScheduleStatus | undefined,
+): ScheduleStateInfo {
+  const isPaused = (status?.pausedReason ?? "") !== "";
+
+  if (!spec?.enabled) {
+    return { state: "disabled", phase: "disabled", label: "Disabled", isPaused };
+  }
+  if (isPaused) {
+    return { state: "paused", phase: "degraded", label: "Paused", isPaused };
+  }
+  return { state: "active", phase: "ready", label: "Active", isPaused };
+}
+
+/**
+ * Compact future-instant formatter for a schedule's next fire time:
+ * `now`, `in 5m`, `in 3h`, `in 6d`, then a short date once "days from
+ * now" stops being how people think about it.
+ *
+ * The schedule-local sibling of the activity module's past-only
+ * `formatRelativeTime` (same compact units, same date tail) — kept
+ * separate because that util's contract is deliberately past-only.
+ * A fire time slightly in the past (a tick mid-flight, clock skew)
+ * renders as `now` rather than a nonsense negative countdown.
+ *
+ * `now` is injected, never read from the live clock — required for
+ * deterministic tests and Scenar fixtures.
+ */
+export function formatNextFire(date: Date, now: Date): string {
+  const deltaMs = date.getTime() - now.getTime();
+
+  if (deltaMs < 60_000) return "now";
+
+  const minutes = Math.floor(deltaMs / 60_000);
+  if (minutes < 60) return `in ${minutes}m`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `in ${hours}h`;
+
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `in ${days}d`;
+
+  const sameYear = date.getFullYear() === now.getFullYear();
+  return date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+    ...(sameYear ? {} : { year: "numeric" }),
+  });
+}